Understanding Kubernetes Manifests: A Beginner’s Guide to Deployments and Services

When working with Kubernetes, you will have to use manifests to configure your workloads. I wrote this guide to help break down the two most basic k8s YAML files that you'll need. Kubernetes manifests serve as instruction manuals that define resources like Pods, Services, and Deployments, written in YAML format.

Tip: YAML is strict with indentation—use an online validator to avoid syntax errors.

Github with full examples here.

Key Kubernetes Manifests

Two common manifests in a Kubernetes cluster are:

1. Deployment: Manages Pods and ensures high availability.
2. Service: Exposes applications and manages networking.

Parts of a Kubernetes Configuration

There are 3 parts to a Kubernetes configuration:

1. Metadata: Where you define the name and labels for your resource
2. Spec (Specification): The actual configuration of what you want, specific to each resource type
3. Status: Automatically generated by Kubernetes to reflect the current state of the resource.

Metadata

Metadata includes essential information about the resource, such as its name and labels. Labels are key-value pairs that help categorize and select Kubernetes resources. They enable flexible organization, such as grouping resources by environment (e.g., env: production), tier (e.g., tier: backend), or other custom criteria.

metadata:
  name: nginx-deployment  # Name of the Deployment
  labels:
    app: nginx           # Labels to identify the application

Spec (Specification)

The spec section defines the desired state of the resource. For example, in a Deployment, the spec includes the number of replicas, the selector for matching Pods, and the template for Pod configuration.

spec:
  replicas: 2              # Number of pod replicas for high availability
  selector:
    matchLabels:
      app: nginx           # Must match the labels in the template
  template:
    metadata:
      labels:
        app: nginx         # Labels applied to the pods
    spec:
      containers:
      - name: nginx         # Name of the container
        image: nginx:1.14.2 # Replace with the URL of your container image
        ports:
        - containerPort: 80 # Port the container listens on

Status

The status section is automatically generated by Kubernetes. It reflects the current state of the resource, such as the number of available replicas in a Deployment. Kubernetes continuously monitors the actual state against the desired state and takes action to reconcile any differences, leveraging its self-healing capabilities.

For example, in our deployment manifest we specified we wanted 2 replicas:

spec:
  replicas: 2

When the deployment is created, Kubernetes will continuously check the status to make sure we have 2 replicas running at all times. If only 1 replica(actual state) is running, it's not at the desired state.

Full YAML Example

Deployment:

A Deployment manages a set of identical Pods, ensuring that the specified number of replicas are running at all times. This ensures high availability and load distribution across your application.

apiVersion: apps/v1
kind: Deployment # Create a deployment resource
metadata:
  name: nginx-deployment # Name of the Deployment
  labels:
    app: nginx # Labels to identify the application
spec:
  replicas: 2 # Number of pod replicas for high availability
  selector:
    matchLabels:
      app: nginx # Must match the labels in the template
  template:
    metadata:
      labels:
        app: nginx # Labels applied to the pods
    spec:
      containers:
      - name: nginx # Name of the container
        image: nginx:1.14.2 # Replace with the URL of your container image
        ports:
        - containerPort: 80 # Port the container listens on

Service:

A Service exposes your application to the network, managing how traffic is directed to the Pods. By setting the Service type to LoadBalancer, Kubernetes provisions an external load balancer (if supported by your cloud provider) to route traffic to your Service, allowing users to access your application via a public IP address.

apiVersion: v1
kind: Service # Create a service resource
metadata:
  name: nginx-service # Name of the service
spec:
  type: LoadBalancer # Exposes the service via a cloud provider's load balancer
  selector:
    app: nginx # Links this service to Pods with the label app: fastapi
  ports:
    - port: 80 # Exposed port for external traffic
      targetPort: 80 # Port on the container to route traffic to
      protocol: TCP # Communication protocol

Resource Declaration (First Two Lines)

The first two line in a Kubernetes yaml manifest is where you declare to Kubernetes the resource type you want to create:

Service

apiVersion: v1
kind: Service # Create a service resource

Deployment

apiVersion: apps/v1
kind: Deployment # Create a deployment resource

Connecting Services to deployments

Service and deployments are connected through selectors and labels. This connection ensures that traffic directed to the Service is properly routed to the appropriate Pods managed by the Deployment.

In the deployment file:

metadata:
  name: nginx-deployment 
  labels:
    app: nginx # Labels to identify the application

spec:
  replicas: 2 
  selector:
    matchLabels:
      app: nginx # Must match the labels in the template

  template:
    metadata:
      labels:
        app: nginx # Labels applied to the pods

Service File

labels:
    app: nginx # Labels to identify the application

How It Works

1. Labels: In the Deployment file, the metadata.labels and template.metadata.labels sections assign the label app: nginx to the Deployment and its Pods. Labels are key-value pairs that help categorize and select Kubernetes resources.
2. Selectors: In the Deployment's spec.selector.matchLabels and the Service's spec.selector, the label app: nginx is used to match and connect the Service to the appropriate Pods.
3. Traffic Routing: The Service uses the selector to identify which Pods to send traffic to. When external traffic arrives at the Service's port, it is forwarded to the targetPort on the matched Pods.

Port Definitions

  ports:
    - port: 80 # Exposed port for external traffic
      targetPort: 80 # Port on the container to route traffic to
      protocol: TCP # Communication protocol

Think of it this way:

1. External traffic comes to the Service on 'port'
2. The Service forwards that traffic to 'targetPort' on your pods
3. Your container needs to be listening on 'targetPort'

These ports must align properly:

• The Service's "targetPort" must match the "containerPort" in your Deployment
• The Service's "port" can be different, but is commonly set to the same number for simplicity

Enhancing Clarity with Detailed Explanations

Metadata

Metadata provides essential information about your Kubernetes resources. Proper labeling is crucial for organizing and managing resources efficiently. Labels allow you to group resources based on various criteria, such as environment (env: production), application tier (tier: backend), or custom categories (app: nginx).

Spec (Specification)

The spec section is the core of your manifest, defining the desired state of the resource. For Deployments, key spec fields include:

• Replicas: Specifies the number of Pod instances to run. For example, replicas: 2 ensures that two Pods are always running, providing high availability.

replicas: 2

• Selector: Determines how the Deployment identifies which Pods to manage. It must match the labels defined in the Pod template.

selector:
  matchLabels:
    app: nginx

• Template: Defines the Pod's metadata and specifications, including labels, containers, and ports.

template:
  metadata:
    labels:
      app: nginx
  spec:
    containers:
    - name: nginx
      image: nginx:1.14.2
      ports:
      - containerPort: 80

Status

The status section is managed by Kubernetes and provides real-time information about the resource's current state. It helps Kubernetes track whether the actual state matches the desired state defined in the spec. If discrepancies are detected, Kubernetes takes corrective actions, such as restarting Pods to maintain the desired number of replicas.

Example of Self-Healing:

If a Pod crashes or becomes unhealthy, Kubernetes will detect that the actual number of running Pods does not match the desired replicas specified in the Deployment. It will then automatically create a new Pod to replace the failed one, ensuring that the application remains available.

Understanding the Big Picture

Now that we've broken down each component of Kubernetes manifests, you can see how they work together to create a robust and self-healing application infrastructure. The combination of proper metadata, well-defined specs, and Kubernetes' built-in status monitoring ensures your applications run reliably and efficiently.

Final Thoughts

After reading this guide, you should have a solid foundation for working with Kubernetes manifests. You now understand how to read, structure, and use both Deployment and Service configurations to manage and deploy applications within your Kubernetes cluster. The examples and explanations provided here will serve as a practical reference as you begin your Kubernetes journey.

Ready to dive deeper? Check out Kubernetes Official Documentation for more in-depth information and advanced configurations.