1. Documentation
×

Triggering updates on image stream changes

When an image stream tag is updated to point to a new image, OKD 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.

OKD resources

OKD 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

To enable Kubernetes resources, such as Deployments and StatefulSets, to seamlessly consume new image versions, configure image stream change triggers in OKD. This ensures your application deployments are automatically updated when the associated image stream detects a change.

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 OKD to request triggering.

The annotation is defined as follows:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    image.openshift.io/triggers:
      [
       {
         "from": {
           "kind": "ImageStreamTag",
           "name": "example:latest",
           "namespace": "myapp"
         },
         "fieldPath": "spec.template.spec.containers[?(@.name==\"web\")].image",
         "paused": false
       },
      # ...
      ]
# ...

where:

kind

Specifies the resource to trigger from, and must have the value ImageStreamTag.

name

Specifies the name of an image stream tag.

namespace

Specifies the namespace of the object. This field is optional.

fieldPath

Specifies 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.

paused

Specifies whether or not the trigger is paused. This field is optional, and defaults to the value false. Set the value to true to temporarily disable this trigger.

When one of the core Kubernetes resources contains both a pod template and this annotation, OKD 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

Setting the image trigger on Kubernetes resources

To enable automatic updates for your deployed applications managed by Kubernetes, use the command-line interface (CLI) to set an image stream change trigger on Kubernetes resources. This ensures that resources, like Deployments and StatefulSets, are automatically invoked when a new version of an upstream image is available.

When adding an image trigger to deployments, you can use the oc set triggers command. For example, the sample 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. This command sets the correct image.openshift.io/triggers annotation on the deployment resource.

Procedure

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

    $ oc set triggers deploy/example --from-image=example:latest -c web
    Example deployment with trigger annotation
    apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    image.openshift.io/triggers: '[{"from":{"kind":"ImageStreamTag","name":"example:latest"},"fieldPath":"spec.template.spec.containers[?(@.name==\"container\")].image"}]'
# ...

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