Kubernetes definition files, commonly referred to as YAML manifests, are the core mechanism for declaring the desired state of your application and its supporting infrastructure within a Kubernetes cluster. They are not scripts or executable code, but rather data files specifying the configuration of Kubernetes objects.

Core Concepts:

• Declarative Configuration: Kubernetes operates on a declarative model. You define what you want, not how to achieve it. The Kubernetes control plane continuously works to reconcile the actual state with the desired state defined in these files.
• Kubernetes Objects: These files define Kubernetes objects. Common object types include Pods, Deployments, Services, ConfigMaps, Secrets, and more. Each object has a defined schema dictating the permissible fields and their data types.
• YAML Syntax: Manifests are written in YAML (YAML Ain’t Markup Language). YAML prioritizes readability through indentation and key-value pairs. Incorrect indentation will cause parsing errors.

Key Components of a YAML Manifest:

• apiVersion: apiVersion is the mandatory field that selects which version of the Kubernetes API schema to use for the object. It tells the API server which fields are allowed, what defaults to apply, and which controller should handle the resource. For a Deployment you write apiVersion: apps/v1; without that exact line the server cannot validate or create the Deployment . Check out API Groups from k8s documentation for full list.
• kind – a string that names the resource type (e.g., “Deployment”, “Service”, “ConfigMap”). It must match a type known to the API server at the given apiVersion. The server uses kind to route the request to the correct handler and validation schema; changing kind changes the entire semantics of the manifest.
• metadata – an object that identifies and organizes the resource. The only required subfield is name, which must be unique within a namespace. Optional subfields include namespace (defaults to “default”), labels (key‑value pairs for selection and grouping), annotations (key‑value pairs for tool‑specific metadata), and generateName for automatic naming. System‑populated read‑only fields such as uid, resourceVersion, and creationTimestamp also reside here. Metadata is used by controllers, selectors, and CLI filters.
• spec – an object that declares the desired state of the resource. Its structure is defined by the schema associated with the apiVersion and kind. For a Deployment, spec contains replicas (desired pod count), selector (label query to match pods), template (a PodTemplateSpec describing the pod to create), and optional fields like strategy (rolling‑update behavior) or minReadySeconds. The spec is declarative; controllers continuously reconcile the actual state (reported in the separate status field) to match the spec.

Example: A Simple Pod Definition

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  labels:
    app: my-app
spec:
  containers:
    - name: my-container
      image: nginx:latest
      ports:
      - containerPort: 80

Explanation:

• apiVersion: v1: Uses the core v1 API for Pods.

• kind: Pod: Creates a Pod object.

• metadata.name: my-pod: Names the Pod “my-pod”.

• metadata.labels.app: my-app: Assigns the label app: my-app to the Pod.

• spec.containers: Defines the containers within the Pod.

• spec.containers[0].name: my-container: Names the container “my-container”.

• spec.containers[0].image: nginx:latest: Specifies the Docker image to use (latest Nginx image).

• spec.containers[0].ports[0].containerPort: 80: Exposes port 80 inside the container.

  metadata has dictionary values. spec has list values. That is why a hyphen is added in spec and not in metadata.

More Complex Objects: Deployments

Deployments manage Pods, ensuring the desired number of replicas are running and handling updates.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-container
          image: nginx:latest
          ports:
          - containerPort: 80

Explanation:

• replicas: 3: Ensures three replicas of the Pod are running.
• selector.matchLabels.app: my-app: The Deployment selects Pods with the label app: my-app.
• template: Defines the Pod template used to create new Pods. Essentially, it’s a Pod definition embedded within the Deployment.

Services

Services expose applications running within the cluster.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
      type: LoadBalancer

Explanation:

• selector.app: my-app: Selects Pods with the label app: my-app. Traffic is routed to these Pods.
• ports[0].port: 80: Exposes port 80 on the Service.
• ports[0].targetPort: 80: Routes traffic to port 80 on the selected Pods.
• type: LoadBalancer: Provisions a cloud provider load balancer to expose the service externally (if supported by the cluster). Other types include ClusterIP and NodePort.

Managing Manifests:

• kubectl apply -f <filename.yaml>: Creates or updates resources based on the manifest file.
• kubectl get <object_type>: Lists objects of a specific type.
• kubectl describe <object_name>: Provides detailed information about an object.
• kubectl delete -f <filename.yaml>: Deletes resources defined in the manifest file.

Validation:

• kubectl apply –validate=true -f <filename.yaml>: Validates the manifest against the Kubernetes schema before applying. This helps catch errors early. Generally recommended.