Skip to content

Latest commit

 

History

History
360 lines (242 loc) · 5.56 KB

yaml.md

File metadata and controls

360 lines (242 loc) · 5.56 KB
Raw

Gentle introduction to YAML

  • YAML Ain't Markup Language (according to yaml.org)

  • Almost required when working with containers:

    • Docker Compose files

    • Kubernetes manifests

    • Many CI pipelines (GitHub, GitLab...)

  • If you don't know much about YAML, this is for you!

What is it?

  • Data representation language
- country: France
  capital: Paris
  code: fr
  population: 68042591
- country: Germany
  capital: Berlin
  code: de
  population: 84270625
- country: Norway
  capital: Oslo
  code: no # It's a trap!
  population: 5425270
  • Even without knowing YAML, we probably can add a country to that file :)

Trying YAML

Basic stuff

  • Strings, numbers, boolean values, null

  • Sequences (=arrays, lists)

  • Mappings (=objects)

  • Superset of JSON

    (if you know JSON, you can just write JSON)

  • Comments start with #

  • A single file can have multiple documents

    (separated by --- on a single line)

Sequences

  • Example: sequence of strings

    [ "france", "germany", "norway" ]

  • Example: the same sequence, without the double-quotes

    [ france, germany, norway ]

  • Example: the same sequence, in "block collection style" (=multi-line)

    - france
- germany
- norway

Mappings

  • Example: mapping strings to numbers

    { "france": 68042591, "germany": 84270625, "norway": 5425270 }

  • Example: the same mapping, without the double-quotes

    { france: 68042591, germany: 84270625, norway: 5425270 }

  • Example: the same mapping, in "block collection style"

    france: 68042591
germany: 84270625
norway: 5425270

Combining types

  • In a sequence (or mapping) we can have different types

    (including other sequences or mappings)

  • Example:

    questions: [ name, quest, favorite color ]
answers: [ "Arthur, King of the Britons", Holy Grail, purple, 42 ]

  • Note that we need to quote "Arthur" because of the comma

  • Note that we don't have the same number of elements in questions and answers

More combinations

  • Example:

      - service: nginx
    ports: [ 80, 443 ]
  - service: bind
    ports: [ 53/tcp, 53/udp ]
  - service: ssh
    ports: 22

  • Note that ports doesn't always have the same type

    (the code handling that data will probably have to be smart!)

⚠️ Automatic booleans

codes:
  france: fr
  germany: de
  norway: no

--

{
  "codes": {
    "france": "fr",
    "germany": "de",
    "norway": false
  }
}

⚠️ Automatic booleans

  • no can become false

    (it depends on the YAML parser used)

  • It should be quoted instead:

      codes:
    france: fr
    germany: de
    norway: "no"

⚠️ Automatic floats

version:
  libfoo: 1.10
  fooctl: 1.0

--

{
  "version": {
    "libfoo": 1.1,
    "fooctl": 1
  }
}

⚠️ Automatic floats

  • Trailing zeros disappear

  • These should also be quoted:

      version:
    libfoo: "1.10"
    fooctl: "1.0"

⚠️ Automatic times

portmap:
- 80:80
- 22:22

--

{
  "portmap": [
    "80:80",
    1342
  ]
}

⚠️ Automatic times

  • 22:22 becomes 1342

  • Thats 22 minutes and 22 seconds = 1342 seconds

  • Again, it should be quoted

Document separator

  • A single YAML file can have multiple documents separated by ---:

      This is a document consisting of a single string.
  --- 💡
  name: The second document
  type: This one is a mapping (key→value)
  --- 💡
  - Third document
  - This one is a sequence

  • Some folks like to add an extra --- at the beginning and/or at the end

    (it's not mandatory but can help e.g. to cat multiple files together)

.footnote[💡 Ignore this; it's here to work around this issue.]

Multi-line strings

Try the following block in a YAML parser:

add line breaks: "in double quoted strings\n(like this)"
preserve line break: |
  by using
  a pipe (|)
  (this is great for embedding shell scripts, configuration files...)
do not preserve line breaks: >
  by using
  a greater-than (>)
  (this is great for embedding very long lines)

See https://yaml-multiline.info/ for advanced multi-line tips!

(E.g. to strip or keep extra \n characters at the end of the block.)

class: extra-details

Advanced features

Anchors let you "memorize" and re-use content:

debian: &debian
  packages: deb
  latest-stable: bullseye

also-debian: *debian

ubuntu:
  <<: *debian
  latest-stable: jammy

class: extra-details

YAML, good or evil?

  • Natural progression from XML to JSON to YAML

  • There are other data languages out there

    (e.g. HCL, domain-specific things crafted with Ruby, CUE...)

  • Compromises are made, for instance:

    • more user-friendly → more "magic" with side effects

    • more powerful → steeper learning curve

  • Love it or loathe it but it's a good idea to understand it!

  • Interesting tool if you appreciate YAML: https://carvel.dev/ytt/

???

:EN:- Understanding YAML and its gotchas :FR:- Comprendre le YAML et ses subtilités