Getting started with Kubernetes, part 1: Introduction to YAML [webinar]

Last week, we were pleased to present the first in a new series of webinars, Getting Started with Kubernetes, Part 1: Introduction to YAML.  During that webinar we received dozens of questions -- way more than we could answer in the short time that we had, so we're going to be putting out a separate blog that answers all of those questions in the next few days. In the meantime, though, we wanted to bring you the webinar itself, as well as the transcript (for those people, like me, who like to skim down to the parts they're looking for.)

If you have any questions, or if there are particular topics you'd like us to do training webinars on, please put them in the comments!
 

Webinar Transcript:

Alright, so there are different uses for YAML. You can see YAML in things like configurations, such as Kubernetes, or Swarm or lots of things like OpenStack templates, Ansible Maven, you see it all over the place. And we are going to cover that as we go through, so we'll talk about the different uses. We'll talk about the overall structure. There are actually data types, even though this is all you know, text, and then we will look at some of the tools that are available for you.

Uses cases for YAML

Alright, so let's look at the different uses for YAML. As I said before, configurations, templates and so on. So for example, in Kubernetes, we use YAML for defining things like pods. So a pod is a unit of workload that Kubernetes orchestrates. 

apiVersion: v1
kind: Pod
metadata:
  name: rss-site
  labels:
    app: web
spec:
  containers:
    - name: front-end
      image: nginx
      ports:
        - containerPort: 80
    - name: rss-reader
      image: nickchase/rss-php-nginx:v1
      ports:
            - containerPort: 88

Swarm, as you can see here, is totally different, even though they are both talking about orchestrating containers. 

version: "3.9"

services:
  web:
    image: 127.0.0.1:5000/stackdemo
    build: .
    ports:
      - "8000:8000"
  redis:
           image: redis:alpine

So this is OpenStack. You'll notice they're all doing different things. But what you're seeing is a format, okay, and that format basically takes care of what makes it YAML.

heat_template_version: 2015-04-30

parameters:
  key_name:
    type: string
    description: Name of a KeyPair

resources:
  server:
    type: OS::Nova::Server
    properties:
      key_name: {get_param: key_name}
      flavor: m1.small
             image: ubuntu-trusty-x86_64

So, you've got your text, you've got indentations, such as in this Ansible snippet...

tasks:

  - action: uri url=http://www.example.com return_content=yes
    register: webpage

  - fail:
      msg: 'service is not happy'
             when: "'AWESOME' not in webpage.content"

... or no indentations depending on the situation, such as this Maven snippet.

modelVersion: 4.0.0
groupId: io.takari.polyglot
artifactId: yaml-project
version: 0.0.1-SNAPSHOT
name: 'YAML Maven Love'

properties: {sisuInjectVersion: 0.0.0.M2a}

What makes a YAML document a YAML document?

 

But you'll notice there's no common vocabulary. And that's important to understand because YAML is not a "language" in that you have to learn all the keywords and everything like that. It's a type of markup language.
(Although, technically speaking, YAML stands for YAML Ain't Markup Language -- or Yet Another Markup Language. Iit depends who you ask.)
So there's no specific vocabulary. It's based on the formatting and it's made to be predictable.

Overall YAML structure

Alright, so let's look at overall YAML structure to start out with. 

Associative arrays in YAML

A very simple YAML document would be something like these associative arrays. 

name: nginx
image: nginx:1.10

Okay, now you've dealt with this in all kinds of other languages. You've got a key and a value, or a name and the data that goes with it. So this is kind of the simplest YAML document that you can have. So these associative arrays, we can put all over other documents. 
Now, here's the interesting thing that we have to make note of: this is our traditional YAML format. But YAML is actually a superset of JSON. So if it's valid JSON, it's valid YAML. For example, if I wanted to write this YAML document as JSON, I could do that. 

{
"name": "nginx",
"image": "nginx:1.10"
}

And this format you're familiar with, okay, you've seen this a thousand times. It's the same thing.
Now, a couple things to note here. See how there's a colon here, and we have not put this in quotes. That's why you must put a space after the colon in your associative arrays. If it was JSON, it wouldn't matter because you got your quotes setting everything off, but that's the price you pay for simplicity. 

Nested values in YAML

Okay, now, another thing that we can do is nested values. So for example, the value of the metadata in this document is another associative array, and in that case, that would be name: pod-example. So the way that we associate this array with this name is to indent it. 

apiVersion: v1
kind: Pod
metadata:
  name: pod-example
spec:
  name: ubuntu
  image: ubuntu:trusty
  command: ["myscript"]
  args: ["arg1", "arg2"]

Now, like with other, other indent-dependent languages, you need to make sure that you are consistent. So if you're going to use two spaces, that's fine. If you're going to use four spaces, that's fine. But you must be consistent. 
The other thing is make sure that you never ever, ever use tabs instead of spaces; you must use spaces to indent your YAML.
So in this case, you can see that we are indenting using two spaces, and we've got two objects that have nested values. Also, notice that there are multiple items here that are all part of spec and since they're all indented, we know what they all are. 

Sequences in YAML

In this case, we have five items, each of which is an item of seo_metadata. But as you saw earlier, we had one spec with four parameters. These hyphens are the important part here; they're what indicate that we have a single list of items, and that list is the value of seo_metadata.

seo_metadata:
- One weird trick to reduce belly fat
- You'll never believe these texts!
- Adorable dogs cavorting in the snow
- Which celebrities hate other celebrities
- Kubernetes, Kubernetes, Why Kubernetes, Kubernetes Why

Multiple documents in a single YAML file

You can put multiple objects in a single YAML document, and the way that you do that is by separating them with these three dashes. Okay, so here, I have two different objects (they happen to be the same) but there are two objects in this document.

---
apiVersion: v1
metadata:
  name: pod-example
spec:
  name: ubuntu
  image: ubuntu:trusty
  command: ["myscript"]
---
apiVersion: v1
metadata:
  name: pod-example
spec:
  name: ubuntu
  image: ubuntu:trusty
  command: ["myscript"]

[[ NOTE:  Although for clarity's sake the webinar talked about multiple objects in a single document, the actual terms used in YAML are that there are multiple documents in a single YAML file. ]]

YAML comments

Another thing for the basic format that we need to know is how you put in comments. 

apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
  # Unique key of the DaemonSet instance
  name: daemonset-example
spec:
  template:
    spec:
      containers:
      # This container is run once on each Node in the cluster
      - name: daemonset-example
        image: ubuntu:trusty
        command:
        - /bin/sh
        args:
        - -c
        # This script is run through 

        # `sh -c