> ## 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.
# Pods with YAML
> Guide to creating Kubernetes Pods with YAML manifests, explaining apiVersion kind metadata spec structure, example pod manifest, kubectl commands and best practices.
Hello and welcome to this lesson.
In this lesson we'll learn how to create a Pod using a YAML manifest and how to apply it to a cluster with kubectl.
Kubernetes resources are typically defined with YAML manifest files. Each manifest follows a consistent structure: the four common top-level fields are `apiVersion`, `kind`, `metadata`, and `spec`. These are the root-level properties required by most Kubernetes objects.
| Top-level field | Purpose | Example |
| - | - | - |
| `apiVersion` | API group and version for the resource | `v1` (for Pod) |
| `kind` | The resource type to create | `Pod`, `Deployment`, `Service` |
| `metadata` | Identifying information and metadata (name, labels, annotations, namespace) | `name: myapp-pod` |
| `spec` | Resource-specific configuration (containers, ports, replicas, etc.) | `containers: - name: nginx-container` |
Details for each field:
* `apiVersion`: Specifies which API version to use. Pods use `v1` in the core API group. Other resources may use `apps/v1`, `networking.k8s.io/v1`, etc.
* `kind`: The resource type you want to create (for example, `Pod`, `Deployment`, `Service`).
* `metadata`: A map with identifying fields such as `name`, `namespace`, `labels`, and `annotations`.
* `spec`: The specification for the resource. For Pods, `spec` must include a `containers` list where each container has at least a `name` and an `image`.
YAML is indentation-sensitive. Keys at the same logical level must have the same indentation. Under `metadata`, keys like `name` and `labels` should be siblings with the same indent; keys under `labels` must be further indented. Do not add arbitrary fields under `metadata`—only keys that Kubernetes expects (like `name`, `namespace`, `labels`, `annotations`, etc.).
For a Pod with a single container, `spec.containers` is a list. Each item in that list is a map describing a container (minimum: `name` and `image`). Below is a minimal, correct Pod manifest. Save it as `pod-definition.yml`.
```yaml theme={null}
# pod-definition.yml
apiVersion: v1
kind: Pod
metadata:
name: myapp-pod
labels:
app: myapp
type: front-end
spec:
containers:
- name: nginx-container
image: nginx
```
Why this manifest works:
* `apiVersion: v1` and `kind: Pod` tell Kubernetes you're creating a Pod using the core `v1` API.
* Under `metadata`, `name` is the Pod's identifier and `labels` is a map used for selection and grouping.
* `spec.containers` is a list allowing multiple containers in a single Pod; this example describes one container named `nginx-container` using the `nginx` image.
To create the Pod from this file, run:
```bash theme={null}
kubectl create -f pod-definition.yml
```
You can also use `kubectl apply -f pod-definition.yml` to create or update a resource declaratively.
To list Pods in the current namespace:
```bash theme={null}
kubectl get pods
```
Example output:
```console theme={null}
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
myapp-pod 1/1 Running 0 20s
```
To inspect the Pod in detail (labels, container images, events, start time, and troubleshooting info):
```bash theme={null}
kubectl describe pod myapp-pod
```
This prints a detailed description including assigned labels, container status, and recent events.
Pods are ephemeral. If a Pod is deleted or fails, it won’t be automatically recreated unless it is managed by a controller (for example, a Deployment or ReplicaSet). For production workloads, prefer using Deployments to manage Pod lifecycle and scaling.
Summary
* Kubernetes manifests typically include `apiVersion`, `kind`, `metadata`, and `spec`.
* Under `metadata`, use only supported fields such as `name`, `namespace`, `labels`, and `annotations`.
* `spec` is resource-specific; for Pods it contains a `containers` list where each container has at least `name` and `image`.
* Use `kubectl create -f ` or `kubectl apply -f ` to create resources, `kubectl get pods` to list Pods, and `kubectl describe pod ` for detailed information.
References
* [Kubernetes API Concepts](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)
* [kubectl documentation](https://kubernetes.io/docs/reference/kubectl/)
* [Pods — Kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/)
A demo follows.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.