When an image stream tag is updated to point to a new image, OpenShift Container Platform can automatically take action to roll the new image out to resources that were using the old image. You configure this behavior in different ways depending on the type of resource that references the image stream tag.

OpenShift Container Platform resources

OpenShift Container Platform Deployment configurations and Build configurations can be automatically triggered by changes to image stream tags. The triggered action can be run using the new value of the image referenced by the updated image stream tag.

Triggering Kubernetes resources

Kubernetes resources do not have fields for triggering, unlike deployment and build configurations, which include as part of their API definition a set of fields for controlling triggers. Instead, you can use annotations in OpenShift Container Platform to request triggering.

The annotation is defined as follows:

Key: image.openshift.io/triggers
Value:
[
 {
   "from": {
     "kind": "ImageStreamTag", (1)
     "name": "example:latest", (2)
     "namespace": "myapp", (3)
   },
   "fieldPath": "spec.template.spec.containers[?(@.name='web')].image", (4)
   "paused": "false" (5)
 },
 ...
]
1 Required: kind is the resource to trigger from must be ImageStreamTag.
2 Required: name must be the name of an image stream tag.
3 Optional: namespace defaults to the namespace of the object.
4 Required: fieldPath is the JSON path to change. This field is limited and accepts only a JSON path expression that precisely matches a container by ID or index. For pods, the JSON path is "spec.containers[?(@.name='web')].image".
5 Optional: paused is whether or not the trigger is paused, and the default value is false. Set paused to true to temporarily disable this trigger.

When one of the core Kubernetes resources contains both a pod template and this annotation, OpenShift Container Platform attempts to update the object by using the image currently associated with the image stream tag that is referenced by trigger. The update is performed against the fieldPath specified.

Examples of core Kubernetes resources that can contain both a pod template and annotation include:

  • CronJobs

  • Deployments

  • StatefulSets

  • DaemonSets

  • Jobs

  • ReplicationControllers

  • Pods

Triggering Kubernetes resources automatically

You can automatically trigger Kubernetes resources by updating the image stream tag.

In the following example, the trigger fires when the example:latest image stream tag is updated. Upon firing, the pod template image reference for the web container is updated with a new image value for the object. If the pod template is part of a deployment definition, the change to the pod template automatically triggers a deployment, which rolls out the new image.

Procedure
  • Trigger Kubernetes resources by updating the image stream tag similar to the one in this example:

    image.openshift.io/triggers=[{"from":{"kind":"ImageStreamTag","name":"example:latest"},"fieldPath":"spec.template.spec.containers[?(@.name='web')].image"}]

Unless the deployment is paused, this pod template update automatically causes a deployment to occur with the new image value.

Triggering Kubernetes resources manually

You can manually trigger Kubernetes resources by entering the oc set triggers command.

When adding an image trigger to deployments, you can use the oc set triggers command. For example, the example command in this procedure adds an image change trigger to the deployment named example so that when the example:latest image stream tag is updated, the web container inside the deployment updates with the new image value.

Procedure
  • Trigger Kubernetes resources by entering the oc set triggers command:

    $ oc set triggers deploy/example --from-image=example:latest -c web

Unless the deployment is paused, this pod template update automatically causes a deployment to occur with the new image value.