Skip to main contentIBM Cloud-Native

Pod Design

Labels, Selectors, and Annotations

Labels are key/value pairs that are attached to objects, such as pods. Labels are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system. Labels can be used to organize and to select subsets of objects. Labels can be attached to objects at creation time and subsequently added and modified at any time. Each object can have a set of key/value labels defined. Each Key must be unique for a given object.

You can use Kubernetes annotations to attach arbitrary non-identifying metadata to objects. Clients such as tools and libraries can retrieve this metadata.

You can use either labels or annotations to attach metadata to Kubernetes objects. Labels can be used to select objects and to find collections of objects that satisfy certain conditions. In contrast, annotations are not used to identify and select objects. The metadata in an annotation can be small or large, structured or unstructured, and can include characters not permitted by labels.

Resources

OpenShift

IKS

References

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  labels:
    app: foo
    tier: frontend
    env: dev
  annotations:
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  restartPolicy: Never
  containers:
    - name: app
      image: busybox

Change Labels on Objects 

oc label <objectname>

Getting Pods based on their labels.

  oc get pods --show-labels
  oc get pods -L tier,env
  oc get pods -l app
  oc get pods -l tier=frontend
  oc get pods -l 'env=dev,tier=frontend'
  oc get pods -l 'env in (dev, test)'
  oc get pods -l 'tier!=backend'
  oc get pods -l 'env,env notin (prod)'

Deployments

A Deployment provides declarative updates for Pods and ReplicaSets.

You describe a desired state in a Deployment, and the Deployment Controller changes the actual state to the desired state at a controlled rate. You can define Deployments to create new ReplicaSets, or to remove existing Deployments and adopt all their resources with new Deployments.

The following are typical use cases for Deployments:

  • Create a Deployment to rollout a ReplicaSet. The ReplicaSet creates Pods in the background. Check the status of the rollout to see if it succeeds or not.
  • Declare the new state of the Pods by updating the PodTemplateSpec of the Deployment. A new ReplicaSet is created and the Deployment manages moving the Pods from the old ReplicaSet to the new one at a controlled rate. Each new ReplicaSet updates the revision of the Deployment.
  • Rollback to an earlier Deployment revision if the current state of the Deployment is not stable. Each rollback updates the revision of the Deployment.
  • Scale up the Deployment to facilitate more load.
  • Pause the Deployment to apply multiple fixes to its PodTemplateSpec and then resume it to start a new rollout.
  • Use the status of the Deployment as an indicator that a rollout has stuck.
  • Clean up older ReplicaSets that you don’t need anymore.

Resources

OpenShift

IKS

References

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:

Creates a Deployment 

oc apply -f <deploymentYAML>

Gets Deployments 

oc get deploy my-deployment

Gets the deployments description 

oc describe deployment my-deployment

Edit the deployment 

oc edit deployment my-deployment

Scale the deployment 

oc scale deployment/my-deployment --replicas=4

Delete the deployment 

oc delete my-deployment

Deployments rolling updates and rollback

Updating a Deployment A Deployment’s rollout is triggered if and only if the Deployment’s Pod template (that is, .spec.template) is changed, for example if the labels or container images of the template are updated. Other updates, such as scaling the Deployment, do not trigger a rollout.

Each time a new Deployment is observed by the Deployment controller, a ReplicaSet is created to bring up the desired Pods. If the Deployment is updated, the existing ReplicaSet that controls Pods whose labels match .spec.selector but whose template does not match .spec.template are scaled down. Eventually, the new ReplicaSet is scaled to .spec.replicas and all old ReplicaSets is scaled to 0.

Label selector updates It is generally discouraged to make label selector updates and it is suggested to plan your selectors up front. In any case, if you need to perform a label selector update, exercise great caution and make sure you have grasped all of the implications.

Rolling Back a Deployment Sometimes, you may want to rollback a Deployment; for example, when the Deployment is not stable, such as crash looping. By default, all of the Deployment’s rollout history is kept in the system so that you can rollback anytime you want (you can change that by modifying revision history limit).

A Deployment’s revision is created when a Deployment’s rollout is triggered. This means that the new revision is created if and only if the Deployment’s Pod template (.spec.template) is changed, for example if you update the labels or container images of the template. Other updates, such as scaling the Deployment, do not create a Deployment revision, so that you can facilitate simultaneous manual- or auto-scaling. This means that when you roll back to an earlier revision, only the Deployment’s Pod template part is rolled back.

Resources

OpenShift

IKS

References

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:

Get Deployments 

oc get deployments

Sets new image for Deployment 

oc set image deployment/my-deployment nginx=nginx:1.16.1 --record

Get ReplicaSets 

oc get rs

Get Deployment Description 

oc describe deployment my-deployment

Check the status of the rollout 

oc rollout status my-deployment

Get Rollout History 

oc rollout history deployment my-deployment

Undo Rollout 

oc rollback my-deployment

Jobs and CronJobs

Jobs A Job creates one or more Pods and ensures that a specified number of them successfully terminate. As pods successfully complete, the Job tracks the successful completions. When a specified number of successful completions is reached, the task (ie, Job) is complete. Deleting a Job will clean up the Pods it created.

CronJobs One CronJob object is like one line of a crontab (cron table) file. It runs a job periodically on a given schedule, written in Cron format.

All CronJob schedule: times are based on the timezone of the master where the job is initiated.

Resources

OpenShift

IKS

References

It computes π to 2000 places and prints it out

apiVersion: batch/v1
kind: Job
metadata:
  name: pi
spec:
  template:
    spec:
      containers:
      - name: pi

Running in parallel

apiVersion: batch/v1
kind: Job
metadata:
  name: pi
spec:
  parallelism: 2
  completions: 3
  template:
    spec:
apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
      template:

Gets Jobs 

oc get jobs

Gets Job Description 

oc describe job pi

Gets Pods from the Job 

oc get pods

Deletes Job 

oc delete job pi

Gets CronJob 

oc get cronjobs

Describes CronJob 

oc describe cronjobs pi

Gets Pods from CronJob 

oc get pods

Deletes CronJob 

oc delete cronjobs pi

Activities

TaskDescriptionLink
Try It Yourself
Rolling Updates LabCreate a Rolling Update for your application.Rolling Updates
Cron Jobs LabUsing Tekton to test new versions of applications.Crons Jobs
Edit this page on GitHub
Previous
Cloud-Native Foundation: Observability
Next
Cloud-Native Foundation: Services & Networking