Declarative vs. Imperative Management

When managing Kubernetes, you communicate your intentions to the Kubernetes API server using kubectl. The formulation of these intentions follows two distinct management models: imperative and declarative. While both models are available, understanding their differences is significant for managing applications effectively and reliably.

The Imperative Approach: A Sequence of Commands

The imperative model is like giving direct, step-by-step instructions. You tell Kubernetes exactly what to do and when to do it. If you want to create a resource, you run a command to create it. If you want to scale it, you run a command to scale it.

For example, to launch an Nginx container, you might run:

# Create a Deployment named 'nginx-web' with the nginx image
kubectl create deployment nginx-web --image=nginx

This command instructs the API server to create a Deployment object. Later, if you decide you need three instances of this application for redundancy, you would issue another command:

# Scale the 'nginx-web' Deployment to 3 replicas
kubectl scale deployment nginx-web --replicas=3

Characteristics of the Imperative Model:

• Action-oriented: Commands correspond to specific actions like create, scale, expose, or delete.
• Simple for one-off tasks: It's fast and straightforward for quick operations, testing, or debugging inside a cluster.
• Lacks a source of truth: The state of your application exists only within the live cluster. There is no file you can look at to see the complete, intended configuration. This makes it difficult to recreate the same setup consistently or to review changes.

The imperative approach is useful for learning and exploration, but it quickly becomes unmanageable for production systems. It leads to "configuration drift," where the running state of the cluster slowly diverges from what you originally intended, with no auditable history of how it got there.

The Declarative Approach: Defining the Desired State

The declarative model shifts the focus from how to what. Instead of telling Kubernetes the sequence of steps to perform, you provide a manifest file, typically written in YAML, that describes the final state you want to achieve.

You define all the characteristics of your application in a .yaml file: the container image to use, the number of replicas, the ports to expose, and any other configuration. Then, you instruct Kubernetes to make the cluster's state match the state described in your file.

Here is a simple Deployment manifest for the same Nginx application:

# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80

To apply this desired state, you use a single command:

kubectl apply -f nginx-deployment.yaml

When Kubernetes receives this manifest, its control plane components work to reconcile the current state with your desired state.

• If the nginx-web Deployment doesn't exist, Kubernetes creates it with three replicas.
• If it already exists but only has one replica, Kubernetes scales it up to three.
• If it already exists with three replicas, Kubernetes does nothing, because the desired state already matches the actual state.

If you later need to change the container image to a new version, you simply update the image field in the YAML file and run kubectl apply -f nginx-deployment.yaml again. Kubernetes will intelligently perform a rolling update to achieve the new desired state.

The imperative workflow involves a sequence of direct commands, while the declarative workflow focuses on defining a desired state in a manifest file and letting the Kubernetes controller reconcile the cluster to match it.

Why Declarative is the Standard

For any serious use of Kubernetes, the declarative model is the recommended approach. Its advantages are fundamental to building reliable systems:

• Version Control for Infrastructure: You can store your YAML manifests in a Git repository. This practice, often called GitOps, gives you a full, auditable history of every change made to your application's configuration. You can see who changed what, when, and why.
• Reproducibility: You can reliably recreate your entire application stack in any cluster by simply applying the same set of manifests. This is invaluable for disaster recovery, testing, and creating new environments.
• Predictability: The kubectl apply command is idempotent, meaning you can run it repeatedly with the same file and the outcome will be the same. Kubernetes calculates the difference between the desired state and the current state and only performs the necessary actions. This makes automation through CI/CD pipelines safe and predictable.

Throughout this course, we will focus almost exclusively on the declarative model. While we may use imperative commands for inspection and debugging, all application definitions will be done through YAML manifests. This practice provides the foundation for managing complex, production-grade applications on Kubernetes.