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 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:
create, scale, expose, or delete.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 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.
nginx-web Deployment doesn't exist, Kubernetes creates it with three replicas.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.
For any serious use of Kubernetes, the declarative model is the recommended approach. Its advantages are fundamental to building reliable systems:
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.
Was this section helpful?
© 2026 ApX Machine LearningEngineered with