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.

✍️ 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:

- A value: text (a string), a number,
true/false, ornull(nothing). - A map (also called an object or dictionary): names with values, like
name: webor"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:
| JSON | YAML | |
|---|---|---|
| Map | {"name": "web", "cpu": 2} | name: web and cpu: 2 on their own lines |
| List | ["web", "prod"] | lines starting with - |
| Nesting | brackets { } and [ ] | indentation with spaces |
| Text | always in double quotes | quotes usually optional (that is a trap) |
| Comments | not allowed | # like this |
| Used by | APIs, gcloud --format=json, package.json | Kubernetes, 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
- A Google Cloud account (the free trial works) and a project.
- 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.comPart 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 worksFrom 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-bOn 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.36servers.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.0Step 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
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.jsonparse 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
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 errormetadata:$
^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'}]}
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 boolEvery line is a real bug waiting to happen:
country: NO(Norway) became the booleanFalse.yes,no,on,offare booleans too.version: 1.10became the number1.1: the zero is lost.mode: 0755became493: 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
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: validPOC: 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.10and0755into the wrong types; quotes fixed all three.
Quiz task: check what you learned
- With jq, print the zone of every server with
"cpu": 8. (Answer:jq -r '.servers[] | select(.cpu == 8) | .zone' servers.json.) - Write
["web", "prod"]as a YAML list. (Answer: two lines,- weband- prod.) - Why does
enabled: offbecomeFalse? (Answer: YAML 1.1 reads on/off/yes/no as booleans; quote it if you mean text.) - 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.)
- 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
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 see | Why | Fix |
|---|---|---|
parse error: Expected separator between values | A missing comma in JSON | Add the comma at the end of the line before |
Expected another key-value pair | A trailing comma before } or ] | Remove the last comma |
found character '\t' that cannot start any token | A tab in YAML | Use spaces; cat -A shows ^I tabs |
mapping values are not allowed here | A missing space after : or a wrong indent | Write key: value with a space; align the level |
| A setting is ignored with no error | Wrong indentation put it elsewhere | Load and print the file; align it under its parent |
A value changed (NO to false, 1.10 to 1.1) | YAML guessed the type | Quote it: "NO", "1.10" |
What next
- Use jq with real cloud data: BigQuery for Beginners: Query Billions of Rows for Free.
- YAML in a real pipeline: Cloud Build Hands-On: Pipelines Without Managing Servers.
- Automate with scripts: Bash Scripting for DevOps: Automate Boring Tasks.
- More hands-on posts: ByteBlog. Practice in ByteLabs and see the courses.
Prepared by the CareerByteCode Team from our tested lab, with AI help for the write-up.
⭐ Keep learning with CareerByteCode
Hand-picked to go deeper on this topicGet 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.
Related blogs
CareerByteCode TeamLinux for Cloud Beginners: 50 Commands on a Free VM
What you build: a free e2-micro Linux VM where you practise 50 everyday commands for files, text, permissions, processes, network and packages, in your own Google Cloud account. Every step tested.
#beginners
CareerByteCode TeamGoogle Cloud Free Tier Explained: What Is Really Free
What you build: a tour of the Always Free products (VM, bucket, BigQuery, Cloud Run, Pub/Sub, Secret Manager) with a real price-list cost check, the bigger-VM trap and a budget alert.
#beginners
CareerByteCode TeamLinux File Permissions Explained with Real Mistakes
What you build: a script, a team folder, an SSH key and a config file that break with Permission denied, then work with the right chmod, chown and group, on a free VM.
#beginners
CareerByteCode TeamLinux Networking Commands Every Cloud Engineer Needs
What you build: ip, ss, dig, curl, tcpdump and nc on real traffic on a free VM, plus three real breaks: a wrong listen address, a VPC firewall and a bad /etc/hosts line.
💬 Comments (0)
Top · NewestSign in to comment