Kubernetes YAML Template

May 26, 2023

Exploring Kubernetes YAML Template to better understand and work with YAML manifests

YAML ( YAML Ain’t Markup Language) is a human readable data serialisation language used to create configuration files with any programming language. Kubernetes is an open source container orchestration system that uses YAML configuration files also known as manifests used to deploy different resources in Kubernetes . In this hands-on-lab we are going to explore YAML templates with examples.

What is a YAML File?

YAML stands for yet another markup language, or YAML ain’t markup language. YAML is one of the most popular languages for writing configuration files, and developers use it to define and deploy resources such as pods, services, and deployment in Kubernetes.

YAML files either have the extension with .yaml or .yml .

YAML File Structure

YAML file is composed of a collection of data structures. It has the following components.

Key-Value Pairs
YAML Maps and YAML Lists
YAML Indentation
Comments
Merging YAML files

Example Configuration file in YAML structure

#Pod.yaml
—--------
apiVersion: v1
kind: Pod
metadata:
  name: mypod_demo
  labels:
     app: nginx
spec:
  containers:
  - name: container_demo
    image: nginx:alpine
    ports:
    - containerPort: 80

Kind: kind represents the type of Kubernetes object. From the above example, kind represents the Kubernetes Pod object.

Metadata: The field metadata used to organise and define the detailed information about one or more aspects of the specific object. We can also summarise the object and can easily track and work with specific objects.

Spec: The state we desire for the object. This field contains the details about the object. Kubernetes always try to make sure that at any point of time, the cluster current state is matching with the desired state. If we create any object in Kubernetes , we specify the desired state in the spec field in the YAML file.

Key-Value pairs

The basic structure of a YAML file consists of key/value pairs. Each key-value pair is written as key: value and is separated by colon(:), where whitespace after the : is optional.

YAML Maps

Maps are associated with a group of key-value pairs. Basically, whatever structure you want to put together, you can do it with those two structures. We might have maps of lists and lists of maps and so on.,

maps of maps
maps of lists
lists of lists
lists of maps

For example, you might have a config file that starts like this,

--------

apiVersion: v1

kind: Pod

From the above example, we can see, we have two values, v1 and Pod, mapped to two keys, apiVersion and kind.

Let’s look at the following structures by creating a key that maps to another map:

we have a key(metadata) with two other keys as its value name and labels. The labels key itself has a map as its value app. You can nest these as far as you want to.

# sample.yaml

—-------

apiVersion: v1

kind: Pod

metadata:

  name: mypod_demo

  labels:

     app: nginx

YAML Lists

YAML lists are literally a sequence of objects. YAML Lists used to represent a list of items. Each item in the list is a list of key/value pairs.

You can have any number of items in a list, which is defined as items that start with a dash (-) indented from the parent, this indicates the start of a document.

Let’s look at the pod.yaml file. Here, Members of the list can also be maps as:

# pod.yaml
—----------

apiVersion: v1

kind: Pod

metadata:

  name: mypod_demo

  labels:

    app: nginx

spec:

  containers:

    - name: container_demo1

      image: alpine

      ports:

        - containerPort: 80

    - name: container_demo2

      image: latest

      ports:

        - containerPort: 88

Each container inside the spec which consists of a name, an image, and a list of ports. Each list item under ports itself is a map and also lists the containerPort and its values 80 and 88.

YAML Indentation

We structure the YAML document with indentation. The indentation level can be one or more spaces. Indentation is nothing but a blank space between a margin and the beginning of a line of text.

The number of spaces doesn’t matter, but make sure that the indented lines mentioned in the YAML file should be CONSISTENT. So that the YAML processor knows how all of these lines relate to each other because we’ve indented the lines.

From the above pod.yaml file example , the name and labels are at the same indentation level inside metadata field, so the processor knows they’re both part of the same map, it knows that app is a value for labels because it’s indented further.

Quick note:NEVER use tabs in a YAML file . Instead we can use spaces.

Because tabs are treated differently by different editors and tools.

Comments

Lines starts with ‘#’ are considered as comments. YAML file supports single line comments. These comments are ignored by YAML parsers.

# This is a sample YAML file 
--------

apiVersion: v1 #version of kubernetes API

kind: Pod #Type of Kubernetes object

YAML doesn’t support multi-line comments. Suppose we would like to comment on multiple lines in the YAML file, we have to start each commented line with a ‘#’ hashtag.

For Example:

# This is 
# a sample 
# YAML file 
—------

apiVersion: v1 #version of kubernetes API

kind: Pod #Type of Kubernetes object

Merging YAML files

A YAML file can contain one or more YAML documents. We can write multiple YAML files into a single YAML file. Each file is separated by three dashes - - -and treated as a stand-alone unit.

Suppose I want to deploy any application , I need to write a deployment or service object for that , instead of having all of those in different files , we can have them in a single file.

Example: Create deployment.yaml with the following content:

#deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deploy
spec:
  replicas: 3
  selector:
    matchLabels: &labelsToMatch
  template:
    metadata:
      labels: *labelsToMatch
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: nginx-lb
  labels:
    app: nginx
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  selector:
    app: nginx

Labels and Selectors in Kubernetes

Labels: Labels are nothing but Tagging our Pod. Labels are key-value pairs which you can assign to any objects like Deployments, Services and Pods in Kubernetes. They do not provide uniqueness. It is mostly built for the users to identify the objects very easily.

We can attach these labels at the creation time or at the runtime as well.

Selectors: Label Selectors are used to identify a set of objects easily. Selectors work like a filter, and we can get any details of Kubernetes objects.

From the above example of a deployment.yaml file, we have created the Deployment with labels (app: nginx) assigned to the object. The replica set can acquire a selected Pod mentioned in the matchLabels. And that label selector must match the labels we defined in the template, i.e., spec.selector needs to match with at least one of the labels defined in the template.

Kubernetes API Objects

In Kubernetes we are going to communicate with API servers via CLI/API to work with different endpoints or objects like Pods, Nodes, Devices, Deployment etc., in the Kubernetes cluster. In the api server, we have core api groups and other api groups.

In Kubernetes everything is an object. If we look at any endpoints, they can be under the following versions, and these are the predefined endpoints to connect with.

The following output shows the different endpoints

Stable(V1)
Beta(V1 beta 1)
Alpha

Run the following command and the output shows the different endpoints:

kubectl api-versions

For example, we would create a Deployment object , we would go and connect with apps/v1.

YAML Reference

In the Deployment object, we can define the labels to our pod configuration.

As we know that, we have a spec.selector and it is going to match with one of the labels defined in the labels section of the template. Instead of writing the labels again, we are going to refer to them by using the &symbol.

We are going to use the & symbol in the deployment.yaml file as looks like the following:

#deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deploy
spec:
  replicas: 3
  selector:
    matchLabels: &labelsToMatch
      app: nginx
  template:
    metadata:
      labels: *labelsToMatch
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80

From the above Deployment object, we have given a reference name as labelsTo Match with & symbol and instead of writing the labels again to our Pod’s configuration, we can write a reference of those labels with a labelsToMatch with * symbol.

So that we don’t need to mention the labels again and this is basically used to avoid duplication.

YAML Quotes

In YAML, the string which doesn’t have a special meaning, we can write with quotes.

There are many types of strings used in YAML files for different purposes. For each use case, we can use quoting like single (‘string’)and double quoting(“string”).

For example: In the below yaml file,in the env field of nginx-demo container, NORWAY value NO will be treated as a boolean false value. To avoid that, use quotes "NO"

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  labels:
     app: nginx
spec:
  containers:
  - name: nginx-demo
    image: nginx:alpine
    env:
      -  name: INDIA
         value: IN
      -  name: NORWAY
         value: NO
    ports:
    - containerPort: 80

   env:
      -  name: INDIA
         value: IN
      -  name: NORWAY
         value: "NO"

Why YAML Over JSON?

YAML is a superset of JSON. YAML is the most human-readable format, and JSON doesn’t allow comments, but YAML allows comments. Also, YAML uses indentation to define structure in the file, which is very helpful for one familiar with indentation style language like Python.

Configuration in YAML:

# configuration in YAML
apiVersion: v1
kind: Pod #Name of the pod
metadata:
  name: mypod
  labels:
    app=nginx

We will translate to this into JSON, it would look like this,

{
"apiVersion": "v1",
"kind": "Pod", 
"metadata": {
  "name": "mypod",
  "labels": {
    "app": "nginx"
}
}
}

YAML Linters

Linters are programs,used to check the quality of the code in a YAML file by displaying warnings and errors. It helps you to create a YAML configuration file for our Kubernetes cluster easily.

For Online: https://www.yamllint.com/
For offline: https://github.com/mikefarah/yq
VS Code IDE Plugin: https://code.marketplace.visualstudio.com/iems?itemname=redhat.vscode.yaml

Conclusion

This article we have looked at gives an understanding about YAML templates with examples and also knows the configuration type information by using a combination of lists and maps in YAML file and how the YAML configuration file works in Kubernetes. I hope this article helped in better understanding of YAML Templates. Have a Happy Learning!.

Join Our Newsletter

Share this article:

madhu mitha

All Posts