---
title: "YAML Tutorial"
source: Panaversity Learn Agentic AI
source_url: https://github.com/panaversity/learn-agentic-ai
licence: Apache-2.0
domain: agentic-ai
subdomain: panaversity-agentic
date_added: 2026-04-25
---

# YAML Tutorial

Below is a detailed tutorial on YAML (YAML Ain't Markup Language), a human-readable data serialization format commonly used for configuration files, data exchange, and more. This tutorial will cover the basics, syntax, data structures, and practical examples to help you get started.

---

### **What is YAML?**
YAML is a lightweight, structured format designed to be easy for humans to read and write, while still being machine-parsable. It’s often used in DevOps (e.g., Kubernetes, Docker Compose), configuration files, and data storage. Unlike JSON or XML, YAML emphasizes simplicity and readability.

---

### **Key Features of YAML**
- **Human-readable**: Uses indentation and minimal punctuation.
- **Supports complex data structures**: Scalars (simple values), sequences (lists), and mappings (key-value pairs).
- **No curly braces or brackets**: Relies on indentation (like Python).
- **Extensible**: Supports comments, multi-line strings, and custom data types.

---

### **Basic Syntax Rules**
1. **Indentation**: YAML uses spaces (not tabs) for nesting. Typically, 2 spaces per level.
2. **Comments**: Start with `#` and continue to the end of the line.
3. **Key-Value Pairs**: Written as `key: value` (note the space after the colon).
4. **Case-sensitive**: Keys and values are case-sensitive.
5. **Documents**: Multiple YAML documents in one file are separated by `---`.

---

### **Core Data Structures**
YAML supports three primary data structures:

#### 1. **Scalars (Simple Values)**
Scalars are single values like strings, numbers, booleans, or null.
- Examples:
  ```yaml
  name: John Doe
  age: 30
  is_student: false
  score: 3.14
  nothing: null  # or ~ or nothing at all
  ```
- Strings can be unquoted, single-quoted (`'`), or double-quoted (`"`):
  ```yaml
  unquoted: hello world
  single: 'hello world'
  double: "hello world"
  ```
  - Use quotes when a string contains special characters (e.g., `:`, `#`) or starts with a number.

#### 2. **Sequences (Lists)**
Sequences represent ordered lists, denoted by a hyphen (`-`) followed by a space.
- Example:
  ```yaml
  fruits:
    - apple
    - banana
    - orange
  ```
- Inline format (equivalent to above):
  ```yaml
  fruits: [apple, banana, orange]
  ```

#### 3. **Mappings (Dictionaries/Key-Value Pairs)**
Mappings are unordered key-value pairs, nested with indentation.
- Example:
  ```yaml
  person:
    name: Alice
    age: 25
    city: New York
  ```
- Inline format:
  ```yaml
  person: {name: Alice, age: 25, city: New York}
  ```

---

### **Advanced Features**

#### **Nested Structures**
You can combine sequences and mappings for complex data.
- Example (a list of people):
  ```yaml
  people:
    - name: Alice
      age: 25
    - name: Bob
      age: 30
  ```
- Example (a person with a list of hobbies):
  ```yaml
  person:
    name: Charlie
    hobbies:
      - reading
      - hiking
      - coding
  ```

#### **Multi-line Strings**
Use `|` (literal) or `>` (folded) to handle multi-line text:
- Literal (`|`): Preserves newlines and formatting.
  ```yaml
  poem: |
    Roses are red,
    Violets are blue,
    YAML is great,
    And so are you!
  ```
- Folded (`>`): Collapses newlines into spaces (useful for paragraphs).
  ```yaml
  description: >
    This is a long description
    that spans multiple lines
    but will be folded into one.
  ```

#### **Anchors and Aliases**
Reuse data with anchors (`&`) and aliases (`*`):
- Example:
  ```yaml
  defaults: &defaults
    timeout: 30
    retries: 3

  server1:
    <<: *defaults  # Merges the defaults
    host: server1.example.com

  server2:
    <<: *defaults
    host: server2.example.com
  ```

#### **Multiple Documents**
Separate independent YAML documents with `---`:
```yaml
---
name: Document 1
data: Hello
---
name: Document 2
data: World
```

#### **Explicit Typing**
Force a value’s type with `!!`:
```yaml
number: !!int "123"    # Ensures it's an integer
text: !!str 123        # Ensures it's a string
```

---

### **Practical Examples**

#### 1. **Simple Configuration File**
```yaml
app:
  name: MyApp
  version: 1.0.0
  debug: true
  ports:
    - 8080
    - 443
  database:
    host: localhost
    port: 5432
    user: admin
```

#### 2. **Docker Compose File**
```yaml
version: '3'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
  db:
    image: postgres:13
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
```

#### 3. **Kubernetes Pod Definition**
```yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: my-container
      image: nginx
      ports:
        - containerPort: 80
```

---

### **Common Pitfalls**
1. **Tabs vs. Spaces**: YAML rejects tabs for indentation—use spaces only.
2. **Colons**: Ensure a space follows a colon in key-value pairs (`key: value`, not `key:value`).
3. **Ambiguous Scalars**: Use quotes for strings that might be misinterpreted (e.g., `yes` could be a boolean).
4. **Indentation Errors**: Mismatched indentation breaks the structure.

---

### **How to Validate YAML**
- Use online tools like **YAML Lint** (yamllint.com).
- Many editors (e.g., VS Code) have YAML extensions with syntax highlighting and validation.
- Command-line tool: Install `yamllint` (`pip install yamllint`) and run `yamllint file.yaml`.

---

### **Getting Started**
1. Create a file (e.g., `config.yaml`).
2. Write your YAML content following the syntax above.
3. Test it with a YAML parser in your preferred language (e.g., PyYAML in Python: `pip install pyyaml`):
   ```python
   import yaml
   with open("config.yaml", "r") as file:
       data = yaml.safe_load(file)
       print(data)
   ```

---

### **Conclusion**
YAML’s simplicity and flexibility make it a powerful tool for configuration and data representation. Start with basic scalars, sequences, and mappings, then explore advanced features like anchors and multi-line strings as needed. Practice by writing your own YAML files, and soon you’ll find it intuitive and efficient!

## YAML Usage

YAML is widely used across various modern containerization, orchestration, and cloud technologies, including Docker, Docker Compose, Kubernetes, Helm, Operators, and Azure Container Apps (ACA). Below, I’ll explain how YAML is utilized in each of these tools and provide examples where applicable.

---

### **1. Docker**
- **Direct Usage**: Docker itself primarily uses a `Dockerfile`, which is **not YAML**—it has its own declarative syntax for defining container images. However, Docker does not require YAML for its core functionality (e.g., `docker run` or `docker build`).
- **Indirect Usage**: YAML becomes relevant when you use Docker with orchestration tools like Docker Compose or Kubernetes (see below).
- **Conclusion**: Docker itself doesn’t use YAML directly, but it integrates with tools that do.

---

### **2. Docker Compose**
- **Usage**: Docker Compose relies heavily on YAML to define multi-container applications. The `docker-compose.yml` file specifies services, networks, volumes, and their configurations.
- **Example**:
  ```yaml
  version: '3.8'
  services:
    web:
      image: nginx:latest
      ports:
        - "80:80"
    db:
      image: postgres:13
      environment:
        POSTGRES_USER: user
        POSTGRES_PASSWORD: password
  ```
- **Conclusion**: YAML is the standard format for Docker Compose configuration files.

---

### **3. Kubernetes**
- **Usage**: Kubernetes uses YAML extensively to define resources like Pods, Deployments, Services, ConfigMaps, and more. These YAML files are applied to the cluster using `kubectl apply -f file.yaml`.
- **Example** (Pod definition):
  ```yaml
  apiVersion: v1
  kind: Pod
  metadata:
    name: nginx-pod
  spec:
    containers:
      - name: nginx
        image: nginx:latest
        ports:
          - containerPort: 80
  ```
- **Conclusion**: YAML is a core part of Kubernetes for declarative configuration management.

---

### **4. Helm**
- **Usage**: Helm, a package manager for Kubernetes, uses YAML within its chart structure. Helm charts include `values.yaml` (for customizable parameters) and templates (which generate Kubernetes YAML files). While Helm itself is a templating tool, the output and much of the input are YAML-based.
- **Example** (`values.yaml`):
  ```yaml
  replicaCount: 2
  image:
    repository: nginx
    tag: latest
  service:
    type: LoadBalancer
    port: 80
  ```
- **Conclusion**: YAML is integral to Helm for defining values and rendering Kubernetes manifests.

---

### **5. Operators (Kubernetes Operators)**
- **Usage**: Kubernetes Operators extend Kubernetes functionality using Custom Resource Definitions (CRDs), which are defined and managed via YAML files. Operators often involve YAML for both the CRD itself and the custom resources users apply.
- **Example** (Custom Resource):
  ```yaml
  apiVersion: example.com/v1
  kind: MyApp
  metadata:
    name: my-app-instance
  spec:
    size: 3
    version: "1.0"
  ```
- **Conclusion**: YAML is used to define and interact with Operator-managed resources in Kubernetes.

---

### **6. Azure Container Apps (ACA)**
- **Usage**: Azure Container Apps supports YAML for defining application configurations, though it’s less common than using the Azure CLI, Portal, or ARM templates (JSON). You can export an ACA configuration as YAML or use YAML with tools like the Azure CLI (`az containerapp create --yaml file.yaml`).
- **Example**:
  ```yaml
  name: myapp
  type: Microsoft.App/containerApps
  location: eastus
  properties:
    configuration:
      ingress:
        external: true
        targetPort: 80
    template:
      containers:
        - image: nginx:latest
          name: nginx
          resources:
            cpu: 0.5
            memory: 1Gi
  ```
- **Conclusion**: YAML is supported in ACA, particularly for programmatic configuration, though it’s not the primary method for all workflows.

---

### **Summary Table**

| Tool                | Uses YAML?         | Primary Use Case                                  |
|---------------------|--------------------|--------------------------------------------------|
| **Docker**          | No (Dockerfile)    | Image building (not YAML-based)                  |
| **Docker Compose**  | Yes               | Multi-container app definitions                  |
| **Kubernetes**      | Yes               | Resource definitions (Pods, Deployments, etc.)   |
| **Helm**            | Yes               | Chart values and Kubernetes manifest generation  |
| **Operators**       | Yes               | Custom Resource Definitions and instances        |
| **Azure Container Apps** | Yes (optional) | App configuration (less common than CLI/JSON)    |

---

### **Why YAML?**
YAML’s human-readable format, support for nested structures, and minimal syntax make it ideal for these tools. It allows developers and operators to define complex configurations declaratively, which aligns with the “infrastructure as code” philosophy prevalent in modern DevOps.
