Working with Deployments

1. Creating Deployment

Example: Basic Deployment

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

Field	Description	Values
apiVersion	API version to use	`apps/v1`
kind	Resource type	`Deployment`
metadata.name	Name of the deployment	String
spec.replicas	Number of desired pods	Integer
spec.selector.matchLabels	Label selector for pods	Map of labels
spec.template.metadata.labels	Labels for pods created by this deployment	Map of labels
spec.template.spec.containers	List of containers in the pod	Array of container specs

Note: The replicas field determines how many pod instances should be running at all times.

2. Applying Deployment YAML

Example: Basic Deployment YAML

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

Field	Description	Values
apiVersion	API version to use	`apps/v1`
kind	Resource type	`Deployment`
metadata.name	Name of the deployment	String
metadata.labels	Labels to apply to the deployment	Map of key-value pairs
spec.replicas	Number of desired pods	Integer
spec.selector.matchLabels	Label selector for pods	Map of key-value pairs
spec.template.metadata.labels	Labels to apply to pods	Map of key-value pairs
spec.template.spec.containers	List of containers in the pod	Array of container objects

Note: The replicas field determines how many pods should be running at all times.

Warning: Ensure the image field points to a valid container image.

3. Scaling Deployment

Field	Description	Values	Notes
replicas	Number of desired pods	`3`	Default is 1
strategy.type	Update strategy for the deployment	`RollingUpdate`, `Recreate`	Default is `RollingUpdate`
strategy.rollingUpdate.maxUnavailable	Maximum number of pods that can be unavailable during update	`1`	Can be integer or percentage
strategy.rollingUpdate.maxSurge	Maximum number of pods that can be created above desired replicas	`1`	Can be integer or percentage

Example: Scaling Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.19

Example: Update Replicas Count

kubectl scale deployment nginx-deployment --replicas=5

Note: Scaling a deployment creates new pods or deletes existing ones to match the desired replica count.

4. Updating Deployment Image

Field	Description	Example
spec.template.spec.containers[].image	Specifies the Docker image to use for the container	`nginx:1.21`

Example: Update Deployment Image

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.22 # Updated image

Note: When updating the image, Kubernetes will perform a rolling update by default.

Update Process

Update the image field in the deployment manifest
Apply the updated manifest using kubectl apply -f deployment.yaml
Kubernetes starts new pods with the updated image
Old pods are terminated once new ones are ready

5. Viewing Rollout Status

Example: Check rollout status of a deployment

kubectl rollout status deployment/my-deployment

Field	Description	Values
deployment.status.observedGeneration	Generation observed by the deployment controller	`1`
deployment.status.replicas	Total number of replicas managed by the deployment	`3`
deployment.status.readyReplicas	Number of ready replicas	`3`
deployment.status.updatedReplicas	Number of updated replicas	`3`
deployment.status.unavailableReplicas	Number of unavailable replicas	`0`
deployment.status.conditions	Conditions indicating the status of the deployment	`[{type: "Progressing", status: "True", reason: "NewReplicaSetAvailable"}]`

Note: The kubectl rollout status command provides a concise view of the deployment's rollout progress, including whether it is in progress or completed.

6. Viewing Rollout History

Command	Description	Notes
kubectl rollout history	View the rollout history of a deployment	Shows revisions and their configurations

Example: View rollout history

kubectl rollout history deployment/my-deployment

Note: The rollout history includes all revisions of the deployment, showing changes in configuration between versions.

Field	Description	Values
REVISION	Revision number of the deployment	`1`, `2`, etc.
VERSION	Kubernetes version used for the rollout	`v1.28.0`
IMAGE	Container image used in this revision	`nginx:1.25`
FLAGS	Flags used in the deployment	`--replicas=3`

7. Rolling Back Deployment

Field	Description	Values
spec.revisionHistoryLimit	Controls the number of old ReplicaSets to retain	`3`
status.observedGeneration	Generation observed by the deployment controller	`2`
status.replicas	Total number of replicas managed by the deployment	`3`
status.updatedReplicas	Number of replicas updated to the latest version	`3`
status.availableReplicas	Number of available replicas	`3`

Example: Rolling Back Deployment

kubectl rollout undo deployment/my-deployment --to-revision=1

Example: Check Rollout History

kubectl rollout history deployment/my-deployment

Note: The revisionHistoryLimit field controls how many old ReplicaSets are retained to allow for rollbacks. By default, Kubernetes keeps 10 previous revisions.

8. Pausing Rollouts

Pausing a rollout allows you to make changes to a Deployment without triggering a new rollout. This is useful for making configuration updates or applying fixes without disrupting the application.

Command	Description	Example
kubectl rollout pause	Pauses the rollout of a Deployment	`kubectl rollout pause deployment/my-deployment`
kubectl rollout resume	Resumes the rollout of a Deployment	`kubectl rollout resume deployment/my-deployment`

Example: Pausing and Resuming a Rollout

Pause the rollout of a Deployment to make configuration changes:

kubectl rollout pause deployment/my-deployment

After making changes, resume the rollout:

kubectl rollout resume deployment/my-deployment

Note: Pausing a rollout does not stop any running pods. It only prevents new pods from being created with the updated configuration until the rollout is resumed.

9. Resuming Rollouts

Field	Description	Values
spec.paused	Indicates whether the deployment is paused	`false` to resume, `true` to pause

Example: Resuming a Paused Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  paused: false
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21

Note: Setting paused: false resumes the rollout process if it was previously paused.

Warning: If a deployment is paused, any changes to the spec will not trigger a rollout until it's unpaused.

10. Configuring Update Strategy

Field	Description	Values	Notes
strategy.type	Update strategy type	`RollingUpdate`, `Recreate`	Default is `RollingUpdate`
strategy.rollingUpdate	Configuration for rolling updates	`maxUnavailable`, `maxSurge`	Used only when `strategy.type` is `RollingUpdate`
strategy.rollingUpdate.maxUnavailable	Minimum number of pods unavailable during update	`1`, `25%`	Default is `25%`
strategy.rollingUpdate.maxSurge	Maximum number of pods that can be created above desired count	`1`, `25%`	Default is `25%`

Example: Deployment with custom update strategy

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25

Note: maxUnavailable and maxSurge can be specified as integers or percentages. If set as a percentage, the value is rounded down to the nearest integer.

11. Setting Max Unavailable

Field	Description	Default Value	Notes
maxUnavailable	Maximum number of pods that can be unavailable during the update process	1	Can be specified as an integer or percentage (e.g., 20%)

Example: Setting maxUnavailable in Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 5
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21

12. Setting Max Surge

Field	Description	Default Value	Notes
maxSurge	Number of additional pods that can be created while replacing an old pod	`1`	Can be an integer or percentage (e.g., `25%`)
maxUnavailable	Number of pods that can be unavailable while replacing an old pod	`0`	Can be an integer or percentage (e.g., `25%`)

Example: Deployment with maxSurge and maxUnavailable

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21

13. Setting Revision History Limit

Field	Description	Default Value	Notes
revisionHistoryLimit	Controls the number of old ReplicaSets to retain for rollback purposes	`10`	Set to `0` to retain all revisions (not recommended in production)

Example: Setting Revision History Limit in Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21