CareerByteCode
ByteBlogby CareerByteCode

YAML and JSON for Cloud Engineers: Read Any Config File

What you build: real JSON read with jq, YAML read, validated and converted, and the 4 classic config bugs (commas, tabs, silent indentation, type guessing) broken and fixed on a free VM.

YAML and JSON for Cloud Engineers: Read Any Config File

✍️ Translate this blog into Hindi, Tamil or Telugu

Kubernetes manifests, Docker Compose files, GitHub Actions, Cloud Build pipelines, Ansible playbooks, Terraform outputs, every cloud API answer: they are all YAML or JSON. If you can read these two formats with confidence, you can read almost any config file in cloud and DevOps. In this lab you read JSON with jq, read and validate YAML, convert one into the other, and break both in the ways that cost engineers hours: a missing comma, a tab, an indentation that silently changes the meaning, and YAML quietly turning NO into false.

Who it is for: beginners who copy config files from tutorials and want to understand and fix them. Time: about 1 hour. Cost: free. An e2-micro VM in us-east1 is in Google Cloud's Always Free tier (one per account), and we delete it at the end. (Cloud Shell has the same tools, so you can also do everything from Step 2 there.)

Every command below was run for real by the CareerByteCode Team on a fresh Google Cloud project, and every output and screenshot is the real result we got.

🧪⭐ Recommended by CareerByteCode · ByteLabs project bundleCloud and DevOps Realtime Starterโ‚น499Build the projects →

Part A: YAML and JSON in plain English

Both formats describe the same three things:

YAML and JSON in one picture
The same data written two ways: JSON with brackets and quotes, YAML with indentation
  • A value: text (a string), a number, true/false, or null (nothing).
  • A map (also called an object or dictionary): names with values, like name: web or "name": "web". Real-life example: a form with labelled boxes.
  • A list (array): values in order, like the items on a shopping list.

Maps and lists can sit inside each other as deep as needed. The difference is only how you write them:

JSONYAML
Map{"name": "web", "cpu": 2}name: web and cpu: 2 on their own lines
List["web", "prod"]lines starting with -
Nestingbrackets { } and [ ]indentation with spaces
Textalways in double quotesquotes usually optional (that is a trap)
Commentsnot allowed# like this
Used byAPIs, gcloud --format=json, package.jsonKubernetes, Compose, Actions, Ansible, Cloud Build

YAML is a superset of JSON: any JSON file is also valid YAML.

The tools: jq (read and filter JSON on the command line), yamllint (check YAML for errors and style), and Python's PyYAML (read YAML exactly as programs do).

Before you start

  1. A Google Cloud account (the free trial works) and a project.
  2. Open Cloud Shell (the >_ icon at the top right of the Google Cloud console) and set your project:
export PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID
gcloud services enable compute.googleapis.com

Part B: the lab

Step 1: a free e2-micro VM

Why: a clean Linux server (Debian 12) to practise on. --no-service-account --no-scopes gives it no Google Cloud permissions; this lab needs none.

gcloud compute instances create yaml-lab --zone=us-east1-b --machine-type=e2-micro \
  --image-family=debian-12 --image-project=debian-cloud --boot-disk-size=10GB --boot-disk-type=pd-standard \
  --no-service-account --no-scopes 2>&1 | tail -2
until gcloud compute ssh yaml-lab --zone=us-east1-b --tunnel-through-iap --command="echo ssh ok" 2>/dev/null | grep -q ok; do sleep 10; done; echo "SSH works"
NAME      ZONE        MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUS
yaml-lab  us-east1-b  e2-micro                   10.142.0.25  EXTERNAL_IP  RUNNING
SSH works

From here on: open an interactive SSH session with the VM using the command below (run it in Cloud Shell; or click Compute Engine > VM instances > SSH next to yaml-lab). Once you see the VM terminal prompt (you@yaml-lab:~$), run the next boxes there.

gcloud compute ssh yaml-lab --zone=us-east1-b

On the VM: everything from here to the clean up runs inside the VM in ~/lab274 (mkdir -p ~/lab274 && cd ~/lab274). Create the two sample files there (nano servers.json, nano app.yaml):

mkdir -p ~/lab274 && cd ~/lab274
{
  "project": "demo-shop",
  "servers": [
    {"name": "web-1", "zone": "us-east1-b", "cpu": 2, "tags": ["web", "prod"], "healthy": true},
    {"name": "web-2", "zone": "us-east1-c", "cpu": 2, "tags": ["web", "prod"], "healthy": false},
    {"name": "batch-1", "zone": "us-central1-a", "cpu": 8, "tags": ["batch"], "healthy": true}
  ]
}
# app.yaml: a small config in the same shape as a Kubernetes Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-web
  labels:
    app: shop
    team: payments
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80
          env:
            - name: MODE
              value: "production"
            - name: LOG_LEVEL
              value: info
        - name: sidecar
          image: busybox:1.36

servers.json is like what a cloud API returns about your servers. app.yaml has the same shape as a Kubernetes Deployment.

Step 2: install the tools

Why: jq for JSON, yamllint to check YAML, python3-yaml (PyYAML) to read YAML exactly as many tools do.

# Tools: jq (JSON), yamllint (checks YAML), python3-yaml (reads YAML in Python)
sudo apt-get update -qq && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq jq yamllint python3-yaml > /dev/null
jq --version; yamllint --version; python3 -c "import yaml; print('PyYAML', yaml.__version__)"
jq-1.6
yamllint 1.29.0
PyYAML 6.0

Step 3: read JSON with jq

Why: jq takes a path to the data you want. . is the whole document (pretty-printed), .project one value, .servers[] each item of the list, .servers[].name the name of each, select() filters, and -r prints raw text without quotes.

# Read JSON with jq: the whole file, one value, a list, a filter
cd ~/lab274
jq . servers.json | head -6
jq -r '.project' servers.json
jq -r '.servers[].name' servers.json
jq -r '.servers[] | select(.healthy == false) | "\(.name) in \(.zone) is DOWN"' servers.json
jq '[.servers[].cpu] | add' servers.json
{
  "project": "demo-shop",
  "servers": [
    {
      "name": "web-1",
      "zone": "us-east1-b",
demo-shop
web-1
web-2
batch-1
web-2 in us-east1-c is DOWN
12
Reading JSON with jq
The whole file, one value, every name, only the server that is down, and the total CPUs

Read the paths like an address: .servers[1].zone = "in servers, item number 1 (counting from 0), the zone". [... ] | add collects values into a list and adds them up: 2 + 2 + 8 = 12 CPUs.

Break it: commas in JSON

JSON is strict. Two common mistakes: a missing comma between two items, and an extra comma after the last one (which JavaScript and Python allow, but JSON does not).

# Break it: one missing comma and one trailing comma. JSON allows neither.
cd ~/lab274
printf '{\n  "name": "web-1"\n  "cpu": 2\n}\n' > bad1.json
printf '{\n  "name": "web-1",\n  "cpu": 2,\n}\n' > bad2.json
jq . bad1.json; echo "jq exit $?"
jq . bad2.json; echo "jq exit $?"
python3 -m json.tool bad2.json
parse error: Expected separator between values at line 3, column 7
jq exit 4
parse error: Expected another key-value pair at line 4, column 1
jq exit 4
Expecting property name enclosed in double quotes: line 4 column 1 (char 33)

The error points at the line after the mistake: jq expected a separator at line 3 (where "cpu" starts) because line 2 had no comma. For the trailing comma it expected another key at line 4 (the closing }). Python's json.tool gives the same answer in other words. Tip: when a JSON error points at a line that looks fine, look at the end of the line before it.

Step 4: read YAML

Why: yamllint -d relaxed checks the file. Then Python loads it exactly as Kubernetes or Ansible would, and we read values by name: d['spec']['replicas'] means "in spec, the replicas value".

# Read YAML: the same ideas (maps, lists, values) written with indentation instead of brackets
cd ~/lab274
yamllint -d relaxed app.yaml && echo "app.yaml: valid"
python3 -c "
import yaml; d = yaml.safe_load(open('app.yaml'))
print('kind:', d['kind'], '| replicas:', d['spec']['replicas'])
for c in d['spec']['template']['spec']['containers']: print('container', c['name'], 'image', c['image'])
print('labels:', d['metadata']['labels'])"
app.yaml: valid
kind: Deployment | replicas: 3
container web image nginx:1.27
container sidecar image busybox:1.36
labels: {'app': 'shop', 'team': 'payments'}

In YAML, - name: web starts a list item that is a map. Both containers are in the containers list because both - lines have the same indentation.

Step 5: YAML to JSON

Why: the two formats hold the same data, so you can convert one into the other. Here Python loads the YAML and writes JSON, and jq reads it. This is also how you query any YAML file with jq.

# YAML and JSON are two ways to write the same data: convert YAML to JSON, then query it with jq
cd ~/lab274
python3 -c "import yaml, json; print(json.dumps(yaml.safe_load(open('app.yaml'))))" > app.json
jq -c '.metadata' app.json
jq -r '.spec.template.spec.containers[0].env[] | "\(.name)=\(.value)"' app.json
{"name":"shop-web","labels":{"app":"shop","team":"payments"}}
MODE=production
LOG_LEVEL=info
YAML read and converted
app.yaml is valid, Python reads its values, and the same data as JSON answers jq queries

Break it: a tab in YAML

YAML allows spaces only for indentation. Many editors insert a tab when you press the Tab key.

# Break it: a TAB used for indentation. YAML allows spaces only.
cd ~/lab274
printf 'metadata:\n\tname: shop-web\n' > tab.yaml
cat -A tab.yaml
python3 -c "import yaml; yaml.safe_load(open('tab.yaml'))" 2>&1 | tail -3
yamllint tab.yaml | grep error
metadata:$
^Iname: shop-web$
yaml.scanner.ScannerError: while scanning for the next token
found character '\t' that cannot start any token
  in "tab.yaml", line 2, column 1
  2:1       error    syntax error: found character '\t' that cannot start any token (syntax)

cat -A shows hidden characters: ^I is a tab and $ is the end of a line. PyYAML stops with found character '\t' that cannot start any token, and yamllint says syntax error with the line and column. Fix: set your editor to insert spaces (2 per level is the usual style for YAML) or replace tabs with sed -i 's/\t/ /g' file.yaml.

Break it: the silent one, wrong indentation

The worst YAML mistakes give no error at all. Here env: is meant to belong to the container, but it starts at the left edge, so YAML puts it at the top level of the file.

# Break it (the silent one): env is meant to belong to the container, but its indentation puts it at the top level
cd ~/lab274
cat > indent.yaml <<'Y'
containers:
  - name: web
    image: nginx:1.27
env:
  - name: MODE
    value: production
Y
python3 -c "import yaml; d = yaml.safe_load(open('indent.yaml')); print('top-level keys:', list(d)); print('container web:', d['containers'][0])"
sed -i 's/^env:/    env:/; s/^  - name: MODE/      - name: MODE/; s/^    value: production/        value: production/' indent.yaml
cat indent.yaml
python3 -c "import yaml; d = yaml.safe_load(open('indent.yaml')); print('top-level keys:', list(d)); print('container web:', d['containers'][0])"
🎓⭐ Recommended by CareerByteCode · Live trainingCloud & DevOps Live Cohort Internshipโ‚น2,360See the training →
top-level keys: ['containers', 'env']
container web: {'name': 'web', 'image': 'nginx:1.27'}
containers:
  - name: web
    image: nginx:1.27
    env:
      - name: MODE
        value: production
top-level keys: ['containers']
container web: {'name': 'web', 'image': 'nginx:1.27', 'env': [{'name': 'MODE', 'value': 'production'}]}
Silent indentation bug
A tab stops YAML with an error; wrong indentation loads fine but puts env in the wrong place

The first file loads without a single error, but the top-level keys are containers and env, and the container web has no env. A tool reading it would start the container with no settings, or reject env as unknown. After indenting env under the container (4 spaces, and its items 6), the container has its env. This is why you check with a linter, a schema tool (for Kubernetes: kubectl apply --dry-run=server), or by loading and printing the data, and do not just trust "no error".

Break it: YAML guesses types

When a value has no quotes, YAML guesses its type. Sometimes it guesses wrong. (This is the "YAML 1.1" behaviour that PyYAML and many tools still use.)

# Break it: YAML guesses types. NO becomes false, 1.10 becomes 1.1, 0755 becomes a number
cd ~/lab274
cat > types.yaml <<'Y'
country: NO
version: 1.10
mode: 0755
port: "8080"
enabled: yes
Y
python3 -c "import yaml; [print(k, '=', repr(v), type(v).__name__) for k, v in yaml.safe_load(open('types.yaml')).items()]"
country = False bool
version = 1.1 float
mode = 493 int
port = '8080' str
enabled = True bool

Every line is a real bug waiting to happen:

  • country: NO (Norway) became the boolean False. yes, no, on, off are booleans too.
  • version: 1.10 became the number 1.1: the zero is lost.
  • mode: 0755 became 493: a leading zero means octal (base 8).
  • port: "8080" stayed text because it is quoted.

Fix it: quote anything that must stay text

# Fix it: quote anything that must stay text
cd ~/lab274
sed -i -E 's/^(country|version|mode): (.*)$/\1: "\2"/' types.yaml && cat types.yaml
python3 -c "import yaml; [print(k, '=', repr(v), type(v).__name__) for k, v in yaml.safe_load(open('types.yaml')).items()]"
country: "NO"
version: "1.10"
mode: "0755"
port: "8080"
enabled: yes
country = 'NO' str
version = '1.10' str
mode = '0755' str
port = '8080' str
enabled = True bool
YAML types
NO, 1.10 and 0755 are misread without quotes; with quotes they stay exactly as written

Rule of thumb: quote version numbers, codes like country or zip codes, values with leading zeros, and anything that looks like yes/no/on/off but is meant as text.

Step 6: many documents in one file

Why: a single YAML file can hold several documents separated by ---. Kubernetes files often put a Service and a Deployment together this way.

# Several documents in one YAML file (--- between them), like many Kubernetes files
cd ~/lab274
printf 'kind: Service\nname: shop-svc\n---\nkind: Deployment\nname: shop-web\n' > multi.yaml
python3 -c "import yaml; [print(d['kind'], d['name']) for d in yaml.safe_load_all(open('multi.yaml'))]"
yamllint -d relaxed multi.yaml && echo "multi.yaml: valid"
Service shop-svc
Deployment shop-web
multi.yaml: valid

POC: prove it works

  • jq read values, filtered the server that is down and added up the CPUs from real JSON.
  • A missing and a trailing comma were both refused by jq and Python, with the line shown.
  • YAML was validated, read by path and converted to JSON.
  • A tab stopped YAML with an error; a wrong indentation loaded silently into the wrong place and was fixed.
  • YAML turned NO, 1.10 and 0755 into the wrong types; quotes fixed all three.

Quiz task: check what you learned

  1. With jq, print the zone of every server with "cpu": 8. (Answer: jq -r '.servers[] | select(.cpu == 8) | .zone' servers.json.)
  2. Write ["web", "prod"] as a YAML list. (Answer: two lines, - web and - prod.)
  3. Why does enabled: off become False? (Answer: YAML 1.1 reads on/off/yes/no as booleans; quote it if you mean text.)
  4. A YAML file loads with no error but a setting is ignored. What do you check first? (Answer: the indentation of that setting, by loading the file and printing where it ended up.)
  5. Which character starts a comment in YAML, and can JSON have comments? (Answer: #; JSON has no comments.)

Clean up (delete everything)

Type exit to leave the VM and come back to Cloud Shell, then run this in Cloud Shell:

gcloud compute instances delete yaml-lab --zone=us-east1-b --quiet 2>&1 | tail -1
echo "yaml-lab VMs left: $(gcloud compute instances list --filter="name=yaml-lab" --format="value(name)" | wc -l)"
echo "yaml-lab disks left: $(gcloud compute disks list --filter="name~^yaml-lab" --format="value(name)" | wc -l)"
Deleted [https://www.googleapis.com/compute/v1/projects/your-project-id/zones/us-east1-b/instances/yaml-lab].
yaml-lab VMs left: 0
yaml-lab disks left: 0
Clean up
The yaml-lab VM and its disk are deleted: 0 left

FAQ

Which one should I use for my own configs? Follow the tool: Kubernetes and most CI files use YAML (easier to read and comment). For data that programs exchange, JSON is safer because it has no guessing.

What is yq? A jq-like tool for YAML. There are two different programs with that name (a Go one and a Python one) with different syntax, so check which one you have. Converting to JSON and using jq, as in Step 5, always works.

How do I see a gcloud result as JSON? Add --format=json to almost any gcloud command, then pipe it into jq. kubectl get pod x -o json and -o yaml work the same way.

How many spaces per level? YAML only needs the same number of spaces for items at the same level. Two spaces is the common style; Kubernetes examples use two.

What are &, * and << in some YAML files? Anchors and aliases: &name labels a block and *name reuses it, so you do not repeat yourself. They are common in Docker Compose and CI files.

How do I check a Kubernetes YAML file properly? kubectl apply --dry-run=server -f file.yaml asks the cluster to validate it against the real schema without creating anything.

Troubleshooting

You seeWhyFix
parse error: Expected separator between valuesA missing comma in JSONAdd the comma at the end of the line before
Expected another key-value pairA trailing comma before } or ]Remove the last comma
found character '\t' that cannot start any tokenA tab in YAMLUse spaces; cat -A shows ^I tabs
mapping values are not allowed hereA missing space after : or a wrong indentWrite key: value with a space; align the level
A setting is ignored with no errorWrong indentation put it elsewhereLoad and print the file; align it under its parent
A value changed (NO to false, 1.10 to 1.1)YAML guessed the typeQuote it: "NO", "1.10"

What next

Prepared by the CareerByteCode Team from our tested lab, with AI help for the write-up.

Read next →Linux for Cloud Beginners: 50 Commands on a Free VM⏱ 17 min

⭐ Keep learning with CareerByteCode

Hand-picked to go deeper on this topic
News, guides and updates from the CareerByteCode team
🏅 Expert writer

The CareerByteCode team writes about what is new on careerbytecode.in: courses, labs, exams, events and the community, which is free to join for influencers and content creators in tech.

Get CareerByteCode Team's next blog by email

One email a week when they publish. Add the weekly Best of ByteBlog too. No spam, unsubscribe with one click.

We email you once to confirm. By subscribing you agree to the privacy policy.

💬 Comments (0)

Top · Newest

Sign in to comment

Related blogs

🧪⭐ Recommended by CareerByteCode · ByteLabs project bundleCloud and DevOps Realtime Starterโ‚น499Build the projects →