Automate Your Configs: A Practical Guide to Manipulating YAML with yq

In the landscape of modern DevOps, YAML is everywhere. It’s the language you use to define your applications in Kubernetes, orchestrate your deployments in Ansible, and build your CI/CD pipelines. It's clean and human readable.

But what happens when you need to change these files as part of an automated process? Editing YAML with traditional text tools like sed is a fragile nightmare, one extra space away from breaking everything.

If you’ve ever wished for a magical spellbook that could read, understand, and rewrite your YAML files with perfect precision, then you need to meet yq. It’s the essential command line utility that brings the power of jq to the world of YAML, transforming your configuration management from a manual chore into a seamless automated flow.

Introducing yq: The jq Equivalent for YAML

yq is a lightweight and powerful command line processor for YAML. It allows you to parse, filter, and update YAML files using the exact same query syntax that made jq so famous for JSON. This means if you already know jq, you already know the basics of yq.

The critical advantage of yq is that it doesn’t just see text; it understands the YAML structure. It knows about indentation, lists, objects, and even comments. This structural awareness means you can target the exact piece of data you want to read or change with complete confidence, something that is simply not possible with regular text tools.

Installation is typically a breeze on any operating system using a package manager like Homebrew on macOS (brew install yq) or Snap on Linux (sudo snap install yq).

Reading Data: Extracting Values from Kubernetes Manifests and Ansible Playbooks

The most common task in automation is reading a value from a configuration file. With yq, you use a dot . to navigate through the nested structure of a YAML file, just like walking down the branches of a tree.

Example: A Kubernetes Manifest

Let's take a simplified Kubernetes deployment.yaml file.

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx-app
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: nginx
          image: nginx:1.24.0

Output: nginx:1.24.0

Example: An Ansible Playbook

The same logic applies beautifully to other YAML based tools like Ansible. Consider this simple playbook.

# playbook.yml
- name: Configure Web Server
  hosts: webservers
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present

To get the name of the first task:

Bash

yq '.[0].tasks[0].name' playbook.yml

Output: Install nginx

Writing Data: How to Update Image Tags or Replica Counts In Place

Reading data is useful, but writing data is where yq becomes a CI/CD superstar. Imagine your pipeline just built a new Docker image. You now need to update your Kubernetes deployment to use this new image tag. Doing this manually is slow and risky. With yq, it's a single, reliable command.

The syntax for updating a value is yq '.path.to.key = "new value"'. To make the change directly to the file, you use the in place flag, -i.

Use Case 1: Updating an Image Tag

Using our deployment.yaml from before, let’s update the Nginx image to a new version.

yq -i '.spec.template.spec.containers[0].image = "nginx:1.25.0"' deployment.yaml

If you inspect the file now, you'll see the image tag has been perfectly updated without disturbing anything else.

Use Case 2: Scaling Replicas

Need to scale up your application for a high traffic event?

yq -i '.spec.replicas = 5' deployment.yaml

This command finds the replicas key and changes its value to 5, saving the file instantly. This is the kind of task you can easily add to any automation script.

The Ultimate Time Saver: Converting Between YAML and JSON

Often you'll find yourself working in a mixed environment. Your configurations might be in YAML, but you need to send some data to an API endpoint that only accepts JSON. yq acts as a seamless universal translator between the two formats.

YAML to JSON

By default, yq outputs in a JSON compatible format. To get clean, compact JSON, you can use the -o json flag.

yq -o json '.' deployment.yaml

JSON to YAML

Going the other way is just as easy. If you have a JSON file, you can convert it to beautiful, readable YAML using the pretty print -P flag or -o yaml.

# Assuming you have a file named config.json
yq -P '.' config.json

This ability to effortlessly bridge the two most important data formats in modern computing makes yq an incredibly versatile tool to have in your arsenal.

yq is more than just a convenience; it's a fundamental tool for a reliable DevOps automation. It allows you to treat your configuration files as structured data, not just plain text.

By mastering its ability to read, write, and convert YAML, you can eliminate manual errors, speed up your deployment pipelines, and manage your infrastructure with a level of precision and confidence you never thought possible from the command line ! 🎉