> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Pods with YAML

> Creating and applying a Kubernetes Pod YAML manifest, inspecting pods with kubectl, and tips for manifests, debugging, and evolving to Deployments

In this lesson you'll create a Kubernetes Pod by writing a YAML manifest and submitting it to the API server with `kubectl apply`. Using a manifest gives you versionable, declarative control over the Pod's desired state (recommended for reproducible deployments) versus the ephemeral `kubectl run` imperative command.

This page covers:

* the minimal Pod manifest structure
* a working example that runs the `nginx` image
* how to apply the file and inspect the Pod with `kubectl`
* a trimmed `kubectl describe` example and common fields

## Pod manifest basics

Create a file called `pod.yaml` (for example, `vim pod.yaml`). A minimal Pod manifest has four top-level fields:

| Field | Purpose | Example |
| - | - | - |
| `apiVersion` | API group and version used for the resource | `v1` |
| `kind` | Resource type (case-sensitive) | `Pod` |
| `metadata` | Metadata such as `name`, `labels`, `annotations` | `name: nginx` |
| `spec` | Desired state specification, including `containers` | see example below |

Notes:

* `labels` is a mapping inside `metadata` and is useful for selectors and organization (e.g., `app: nginx`).
* `containers` is a YAML sequence. Each list item is a container object; the hyphen denotes a sequence item.
* Container `name` is the container identifier inside the Pod and can differ from the image name.
* For images from non-Docker Hub registries, specify the full path: `registry.example.com/myrepo/myimage:tag`.

<Callout icon="lightbulb" color="#1CB2FE">
  Use consistent indentation (two spaces recommended). Avoid tabs — inconsistent indentation breaks YAML parsing.
</Callout>

## Minimal Pod manifest example

Create `pod.yaml` with the contents below to run an `nginx` container:

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend
spec:
  containers:
  - name: nginx
    image: nginx
```

Save the file and apply it to your cluster:

```bash theme={null}
kubectl apply -f pod.yaml
```

## Example terminal session

A typical session creating the Pod and checking status looks like this:

```bash theme={null}
admin@ubuntu-server:~/kubernetes-for-beginners# kubectl apply -f pod.yaml
pod/nginx created

admin@ubuntu-server:~/kubernetes-for-beginners# kubectl get pods
NAME     READY   STATUS              RESTARTS   AGE
nginx    0/1     ContainerCreating   0          7s

# A few seconds later
admin@ubuntu-server:~/kubernetes-for-beginners# kubectl get pods
NAME     READY   STATUS    RESTARTS   AGE
nginx    1/1     Running   0          20s
```

## Inspecting the Pod

To view detailed runtime information, use:

```bash theme={null}
kubectl describe pod nginx
```

Below is a trimmed example of `kubectl describe` output (some fields omitted for brevity). This output helps you debug scheduling, image pulls, container state, events, and mounted volumes.

```text theme={null}
Name:         nginx
Namespace:    default
Priority:     0
Node:         minikube/192.168.99.100
Start Time:   Thu, 01 Jan 1970 00:00:00 +0000
Labels:       app=nginx
              tier=frontend
Annotations:  <none>
Status:       Running
IP:           172.17.0.4
IPs:
  IP:  172.17.0.4
Controlled By:  <none>
Containers:
  nginx:
    Container ID:   docker://abcdef123456
    Image:          nginx
    Image ID:       docker-pullable://nginx@sha256:...
    Port:           <none>
    Host Port:      <none>
    State:          Running
      Started:      Thu, 01 Jan 1970 00:00:10 +0000
    Ready:          True
    Restart Count:  0
Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True
Volumes:
  default-token-f5ntk:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  default-token-f5ntk
    Optional:    false
QoS Class:       BestEffort
Node-Selectors:  <none>
Tolerations:     node.kubernetes.io/not-ready:NoExecute for 300s
                 node.kubernetes.io/unreachable:NoExecute for 300s

Events:
  Type     Reason     Age    From               Message
  ----     ------     ----   ----               -------
  Normal   Scheduled  21s    default-scheduler  Successfully assigned default/nginx to minikube
  Normal   Pulling    20s    kubelet, minikube   Pulling image "nginx"
  Normal   Pulled     14s    kubelet, minikube   Successfully pulled image "nginx"
  Normal   Created    14s    kubelet, minikube   Created container nginx
  Normal   Started    14s    kubelet, minikube   Started container nginx
```

## Tips and next steps

* Use manifests to store desired state in source control and to recreate environments consistently.
* When you need multiple replicas and rolling updates, transition from a Pod manifest to a Deployment manifest.
* Add probes (`livenessProbe`, `readinessProbe`), resource requests/limits, and environment variables to the container spec as your application requirements grow.

Useful links and references:

* [Kubernetes Pods documentation](https://kubernetes.io/docs/concepts/workloads/pods/)
* [kubectl reference](https://kubernetes.io/docs/reference/kubectl/)
* [YAML basics (indentation rules)](https://yaml.org/spec/1.2/spec.html)

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/docker-certified-associate-exam-course/module/d9358627-4fc7-4acc-ab96-fa25232555c6/lesson/8c84a314-515e-431e-9dbe-62c434da9772" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.