Skip to content

YAML

YAML Ain’t Markup Language (YAML) is a human-readable data-serialization language. YAML is not a programming language. It is mostly used for storing configuration information.

Note

Data serialization is the process of converting data objects, or object states present in complex data structures, into a stream of bytes for storage, transfer, and distribution in a form that can allow recovery of its original structure.

As you will see a lot of YAML in our Kubernetes basics course, we want to make sure you can read and write YAML. If you are not yet familiar with YAML, this introduction is waiting for you. Otherwise, feel free to skip it or come back later if you meet some less familiar YAML stuff.

This introduction is based on the YAML Tutorial from cloudbees.com.

For more information about YAML, see the YAML website.

Asimple file

Let’s look at a YAML file for a overview:

---
foo: "foo is not bar"
bar: "bar is not foo"
pi: 3.14159
awesome: true
kubernetes-birth-year: 2015
cloud-native:
  - scalable
  - dynamic
  - cloud
  - container
kubernetes:
  version: "1.22.0"
  deployed: true
  applications:
    - name: "My App"
      location: "public cloud"

The file starts with three dashes. These dashes indicate the start of a new YAML document. YAML supports multiple documents, and compliant parsers will recognize each set of dashes as the beginning of a new one.

Then we see the construct that makes up most of a typical YAML document: a key-value pair. foo is a key that points to a string value: foo is not bar

YAML knows four different data types:

  • foo & bar are strings.
  • pi is a floating-point number
  • awesome is a boolean
  • kubernetes-birth-year is an integer

You can enclose strings in single or double-quotes or no quotes at all. YAML recognizes unquoted numerals as integers or floating point.

The cloud-native item is an array with four elements, each denoted by an opening dash. The elements in cloud-native are indented with two spaces. Indentation is how YAML denotes nesting. The number of spaces can vary from file to file, but tabs are not allowed.

Finally, kubernetes is a dictionary that contains a string version, a boolean deployed and an array applications where the item of the array contains two strings.

YAML supports nesting of key-values, and mixing types.

Indentation and Whitespace

Whitespace is part of YAML’s formatting. Unless otherwise indicated, newlines indicate the end of a field. You structure a YAML document with indentation. The indentation level can be one or more spaces. The specification forbids tabs because tools treat them differently.

Comments

Comments begin with a pound sign. They can appear after a document value or take up an entire line.

---
# This is a full line comment
foo: bar # this is a comment, too

YAML data types

Values in YAML’s key-value pairs are scalar. They act like the scalar types in languages like Perl, Javascript, and Python. It’s usually good enough to enclose strings in quotes, leave numbers unquoted, and let the parser figure it out. But that’s only the tip of the iceberg. YAML is capable of a great deal more.

Key-Value Pairs and Dictionaries

The key-value is YAML’s basic building block. Every item in a YAML document is a member of at least one dictionary. The key is always a string. The value is a scalar so that it can be any datatype. So, as we’ve already seen, the value can be a string, a number, or another dictionary.

Numeric types

YAML recognizes numeric types. We saw floating point and integers above. YAML supports several other numeric types. An integer can be decimal, hexadecimal, or octal.

---
foo: 12345
bar: 0x12d4
plop: 023332

YAML supports both fixed and exponential floating point numbers.

---
foo: 1230.15
bar:  12.3015e+05

Finally, we can represent not-a-number (NAN) or infinity. 

---
foo: .inf
bar: -.Inf
plop: .NAN

Foo is infinity. Bar is negative infinity, and plop is NAN.

Strings

YAML strings are Unicode. In most situations, you don’t have to specify them in quotes.

---
foo: this is a normal string

But if we want escape sequences handled, we need to use double quotes. 

---
foo: "this is not a normal string\n"
bar: this is not a normal string\n

YAML processes the first value as ending with a carriage return and linefeed. Since the second value is not quoted, YAML treats the \n as two characters. 

foo: this is not a normal string
bar : this is not a normal string\n

YAML will not escape strings with single quotes, but the single quotes do avoid having string contents interpreted as document formatting. String values can span more than one line. With the fold (greater than) character, you can specify a string in a block. 

bar: >
  this is not a normal string it
  spans more than
  one line
  see?

But it’s interpreted without the newlines: bar : this is not a normal string it spans more than one line see?

The block (pipe) character has a similar function, but YAML interprets the field exactly as is.

---
bar: |
  this is not a normal string it
  spans more than
  one line
  see?

So, we see the newlines where they are in the document.

bar : this is not a normal string it
spans more than
one line
see?

Nulls

You enter nulls with a tilde or the unquoted null string literal.

---
foo: ~
bar: null

Booleans

YAML indicates boolean values with the keywords True, On and Yes for true. False is indicated with False, Off, or No.

---
foo: True
bar: False
light: On
TV: Off

Arrays

You can specify arrays or lists on a single line.

---
items: [ 1, 2, 3, 4, 5 ]
names: [ "one", "two", "three", "four" ]

Or, you can put them on multiple lines.

---
items:
  - 1
  - 2
  - 3
  - 4
  - 5
names:
  - "one"
  - "two"
  - "three"
  - "four"

The multiple line format is useful for lists that contain complex objects instead of scalars. 

---
items:
  - things:
      thing1: huey
      things2: dewey
      thing3: louie
  - other things:
      key: value

An array can contain any valid YAML value. The values in a list do not have to be the same type.

Dictionaries

We covered dictionaries above, but there’s more to them. Like arrays, you can put dictionaries inline. We saw this format above.

---
foo: { thing1: huey, thing2: louie, thing3: dewey }

We’ve seen them span lines before.

---
foo: bar
bar: foo

And, of course, they can be nested and hold any value.

---
foo:
  bar:
    - bar
    - rab
    - plop