Managing image streams

    An image stream and its associated tags provide an abstraction for referencing container images from within OKD. The image stream and its tags allow you to see what images are available and ensure that you are using the specific image you need even if the image in the repository changes.

    Image streams do not contain actual image data, but present a single virtual view of related images, similar to an image repository.

    You can configure builds and deployments to watch an image stream for notifications when new images are added and react by performing a build or deployment, respectively.

    For example, if a deployment is using a certain image and a new version of that image is created, a deployment could be automatically performed to pick up the new version of the image.

    However, if the image stream tag used by the deployment or build is not updated, then even if the container image in the container image registry is updated, the build or deployment continues using the previous, presumably known good image.

    The source images can be stored in any of the following:

    • OKD’s integrated registry.

    • An external registry, for example registry.redhat.io or Quay.io.

    • Other image streams in the OKD cluster.

    When you define an object that references an image stream tag, such as a build or deployment configuration, you point to an image stream tag and not the repository. When you build or deploy your application, OKD queries the repository using the image stream tag to locate the associated ID of the image and uses that exact image.

    The image stream metadata is stored in the etcd instance along with other cluster information.

    Using image streams has several significant benefits:

    • You can tag, rollback a tag, and quickly deal with images, without having to re-push using the command line.

    • You can trigger builds and deployments when a new image is pushed to the registry. Also, OKD has generic triggers for other resources, such as Kubernetes objects.

    • You can mark a tag for periodic re-import. If the source image has changed, that change is picked up and reflected in the image stream, which triggers the build or deployment flow, depending upon the build or deployment configuration.

    • You can share images using fine-grained access control and quickly distribute images across your teams.

    • If the source image changes, the image stream tag still points to a known-good version of the image, ensuring that your application do not break unexpectedly.

    • You can configure security around who can view and use the images through permissions on the image stream objects.

    • Users that lack permission to read or list images on the cluster level can still retrieve the images tagged in a project using image streams.

    Configuring image streams

    An object file contains the following elements.

    Imagestream object definition

    An image stream image points from within an image stream to a particular image ID.

    Image stream images allow you to retrieve metadata about an image from a particular image stream where it is tagged.

    Image stream image objects are automatically created in OKD whenever you import or tag an image into the image stream. You should never have to explicitly define an image stream image object in any image stream definition that you use to create image streams.

    The image stream image consists of the image stream name and image ID from the repository, delimited by an @ sign:

    1. <image-stream-name>@<image-id>

    To refer to the image in the ImageStream object example, the image stream image looks like:

    1. origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d

    Image stream tags

    An image stream tag is a named pointer to an image in an image stream. It is abbreviated as istag. An image stream tag is used to reference or retrieve an image for a given image stream and tag.

    Image stream tags can reference any local or externally managed image. It contains a history of images represented as a stack of all images the tag ever pointed to. Whenever a new or existing image is tagged under particular image stream tag, it is placed at the first position in the history stack. The image previously occupying the top position is available at the second position. This allows for easy rollbacks to make tags point to historical images again.

    The following image stream tag is from an ImageStream object:

    Image stream tag with two images in its history

    1.   tags:
    2.   - items:
    3.     - created: 2017-09-02T10:15:09Z
    4.       dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d
    5.       generation: 2
    6.       image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5
    7.     - created: 2017-09-29T13:40:11Z
    8.       dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5
    9.       generation: 1
    10.       image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d
    11.     tag: latest

    Image stream tags can be permanent tags or tracking tags.

    • Permanent tags are version-specific tags that point to a particular version of an image, such as Python 3.5.

    • For example, the latest image stream tags that ship with OKD are tracking tags. This means consumers of the latest image stream tag are updated to the newest level of the framework provided by the image when a new level becomes available. A latest image stream tag to v3.10 can be changed to v3.11 at any time. It is important to be aware that these latest image stream tags behave differently than the Docker latest tag. The latest image stream tag, in this case, does not point to the latest image in the Docker repository. It points to another image stream tag, which might not be the latest version of an image. For example, if the latest image stream tag points to v3.10 of an image, when the 3.11 version is released, the latest tag is not automatically updated to v3.11, and remains at v3.10 until it is manually updated to point to a v3.11 image stream tag.

    You can create your own image stream tags for your own needs.

    The image stream tag is composed of the name of the image stream and a tag, separated by a colon:

    1. <imagestream name>:<tag>

    For example, to refer to the sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d image in the ImageStream object example earlier, the image stream tag would be:

    1. origin-ruby-sample:latest

    Image stream triggers allow your builds and deployments to be automatically invoked when a new version of an upstream image is available.

    For example, builds and deployments can be automatically started when an image stream tag is modified. This is achieved by monitoring that particular image stream tag and notifying the build or deployment when a change is detected.

    Image stream mapping

    When the integrated registry receives a new image, it creates and sends an image stream mapping to OKD, providing the image’s project, name, tag, and image metadata.

    This information is used to create a new image, if it does not already exist, and to tag the image into the image stream. OKD stores complete metadata about each image, such as commands, entry point, and environment variables. Images in OKD are immutable and the maximum name length is 63 characters.

    The following image stream mapping example results in an image being tagged as test/origin-ruby-sample:latest:

    Image stream mapping object definition

    1. apiVersion: v1
    2. kind: ImageStreamMapping
    3. metadata:
    4.   creationTimestamp: null
    5.   name: origin-ruby-sample
    6.   namespace: test
    7. tag: latest
    8. image:
    9.   dockerImageLayers:
    10.   - name: sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef
    11.     size: 0
    12.   - name: sha256:ee1dd2cb6df21971f4af6de0f1d7782b81fb63156801cfde2bb47b4247c23c29
    13.     size: 196634330
    14.   - name: sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef
    15.     size: 0
    16.   - name: sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef
    17.     size: 0
    18.   - name: sha256:ca062656bff07f18bff46be00f40cfbb069687ec124ac0aa038fd676cfaea092
    19.     size: 177723024
    20.   - name: sha256:63d529c59c92843c395befd065de516ee9ed4995549f8218eac6ff088bfa6b6e
    21.     size: 55679776
    22.   - name: sha256:92114219a04977b5563d7dff71ec4caa3a37a15b266ce42ee8f43dba9798c966
    23.     size: 11939149
    24.   dockerImageMetadata:
    25.     Architecture: amd64
    26.     Config:
    27.       Cmd:
    28.       - /usr/libexec/s2i/run
    29.       Entrypoint:
    30.       - container-entrypoint
    31.       Env:
    32.       - RACK_ENV=production
    33.       - OPENSHIFT_BUILD_NAMESPACE=test
    34.       - OPENSHIFT_BUILD_SOURCE=https://github.com/openshift/ruby-hello-world.git
    35.       - EXAMPLE=sample-app
    36.       - PATH=/opt/app-root/src/bin:/opt/app-root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    37.       - STI_SCRIPTS_URL=image:///usr/libexec/s2i
    38.       - STI_SCRIPTS_PATH=/usr/libexec/s2i
    40.       - BASH_ENV=/opt/app-root/etc/scl_enable
    41.       - ENV=/opt/app-root/etc/scl_enable
    42.       - PROMPT_COMMAND=. /opt/app-root/etc/scl_enable
    43.       - RUBY_VERSION=2.2
    44.       ExposedPorts:
    45.         8080/tcp: {}
    46.       Labels:
    47.         build-date: 2015-12-23
    48.         io.k8s.description: Platform for building and running Ruby 2.2 applications
    49.         io.k8s.display-name: 172.30.56.218:5000/test/origin-ruby-sample:latest
    50.         io.openshift.build.commit.author: Ben Parees <bparees@users.noreply.github.com>
    51.         io.openshift.build.commit.date: Wed Jan 20 10:14:27 2016 -0500
    52.         io.openshift.build.commit.id: 00cadc392d39d5ef9117cbc8a31db0889eedd442
    53.         io.openshift.build.commit.message: 'Merge pull request #51 from php-coder/fix_url_and_sti'
    54.         io.openshift.build.commit.ref: master
    55.         io.openshift.build.image: centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e
    56.         io.openshift.build.source-location: https://github.com/openshift/ruby-hello-world.git
    57.         io.openshift.builder-base-version: 8d95148
    58.         io.openshift.builder-version: 8847438ba06307f86ac877465eadc835201241df
    59.         io.openshift.s2i.scripts-url: image:///usr/libexec/s2i
    60.         io.openshift.tags: builder,ruby,ruby22
    61.         io.s2i.scripts-url: image:///usr/libexec/s2i
    62.         license: GPLv2
    63.         name: CentOS Base Image
    64.         vendor: CentOS
    65.       User: "1001"
    66.       WorkingDir: /opt/app-root/src
    67.     Container: 86e9a4a3c760271671ab913616c51c9f3cea846ca524bf07c04a6f6c9e103a76
    68.     ContainerConfig:
    69.       AttachStdout: true
    70.       Cmd:
    71.       - /bin/sh
    72.       - -c
    73.       - tar -C /tmp -xf - && /usr/libexec/s2i/assemble
    74.       Entrypoint:
    75.       - container-entrypoint
    76.       Env:
    77.       - RACK_ENV=production
    78.       - OPENSHIFT_BUILD_NAME=ruby-sample-build-1
    79.       - OPENSHIFT_BUILD_NAMESPACE=test
    80.       - OPENSHIFT_BUILD_SOURCE=https://github.com/openshift/ruby-hello-world.git
    81.       - EXAMPLE=sample-app
    82.       - PATH=/opt/app-root/src/bin:/opt/app-root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    83.       - STI_SCRIPTS_URL=image:///usr/libexec/s2i
    84.       - STI_SCRIPTS_PATH=/usr/libexec/s2i
    85.       - HOME=/opt/app-root/src
    86.       - BASH_ENV=/opt/app-root/etc/scl_enable
    87.       - ENV=/opt/app-root/etc/scl_enable
    88.       - PROMPT_COMMAND=. /opt/app-root/etc/scl_enable
    89.       - RUBY_VERSION=2.2
    90.       ExposedPorts:
    91.         8080/tcp: {}
    92.       Hostname: ruby-sample-build-1-build
    93.       Image: centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e
    94.       OpenStdin: true
    95.       StdinOnce: true
    96.       User: "1001"
    97.       WorkingDir: /opt/app-root/src
    98.     Created: 2016-01-29T13:40:00Z
    99.     DockerVersion: 1.8.2.fc21
    100.     Id: 9d7fd5e2d15495802028c569d544329f4286dcd1c9c085ff5699218dbaa69b43
    101.     Parent: 57b08d979c86f4500dc8cad639c9518744c8dd39447c055a3517dc9c18d6fccd
    102.     Size: 441976279
    103.     apiVersion: "1.0"
    104.     kind: DockerImage
    105.   dockerImageMetadataVersion: "1.0"
    106.   dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d

    The following sections describe how to use image streams and image stream tags.

    You can get general information about the image stream and detailed information about all the tags it is pointing to.

    Procedure

    • Get general information about the image stream and detailed information about all the tags it is pointing to:

      1. $ oc describe is/<image-name>

      For example:

      1. $ oc describe is/python

      Example output

      1. Name:            python
      2. Namespace:        default
      3. Created:        About a minute ago
      4. Annotations:        openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z
      5. Docker Pull Spec:    docker-registry.default.svc:5000/default/python
      6. Image Lookup:        local=false
      8. Tags:            1
      10. 3.5
      11.   tagged from centos/python-35-centos7
      13.   * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25
      14.       About a minute ago

    • Get all the information available about particular image stream tag:

      1. $ oc describe istag/<image-stream>:<tag-name>

      For example:

      1. $ oc describe istag/python:latest

      Example output

    Adding tags to an image stream

    You can add additional tags to image streams.

    Procedure

    • Add a tag that points to one of the existing tags by using the `oc tag`command:

      1. $ oc tag <image-name:tag1> <image-name:tag2>

      For example:

      1. $ oc tag python:3.5 python:latest

      Example output

      1. Tag python:latest set to python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25.

    • Confirm the image stream has two tags, one, 3.5, pointing at the external container image and another tag, latest, pointing to the same image because it was created based on the first tag.

      1. $ oc describe is/python

      Example output

      1. Name:            python
      2. Namespace:        default
      3. Created:        5 minutes ago
      4. Labels:            <none>
      5. Annotations:        openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z
      6. Docker Pull Spec:    docker-registry.default.svc:5000/default/python
      7. Image Lookup:        local=false
      8. Unique Images:        1
      9. Tags:            2
      11. latest
      12.   tagged from python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25
      14.   * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25
      15.       About a minute ago
      17. 3.5
      18.   tagged from centos/python-35-centos7
      20.   * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25
      21.       5 minutes ago

    You can add tags for external images.

    Procedure

    • Add tags pointing to internal or external images, by using the oc tag command for all tag-related operations:

      1. $ oc tag <repository/image> <image-name:tag>
      1. $ oc tag docker.io/python:3.6.0 python:3.6

      Example output

      1. Tag python:3.6 set to docker.io/python:3.6.0.

      If the external image is secured, you must create a secret with credentials for accessing that registry.

    Updating image stream tags

    You can update a tag to reflect another tag in an image stream.

    Procedure

    • Update a tag:

      1. $ oc tag <image-name:tag> <image-name:latest>

      For example, the following updates the latest tag to reflect the 3.6 tag in an image stream:

      1. $ oc tag python:3.6 python:latest

      Example output

      1. Tag python:latest set to python@sha256:438208801c4806548460b27bd1fbcb7bb188273d13871ab43f.

    You can remove old tags from an image stream.

    Procedure

    • Remove old tags from an image stream:

      For example:

      1. $ oc tag -d python:3.5

      Example output

      1. Deleted tag default/python:3.5.

    See for more information on how the Cluster Samples Operator handles deprecated image stream tags.

    Configuring periodic importing of image stream tags

    When working with an external container image registry, to periodically re-import an image, for example to get latest security updates, you can use the --scheduled flag.

    Procedure

    1. Schedule importing images:

      1. $ oc tag <repository/image> <image-name:tag> --scheduled

      For example:

      1. $ oc tag docker.io/python:3.6.0 python:3.6 --scheduled

      Example output

      1. Tag python:3.6 set to import docker.io/python:3.6.0 periodically.

      This command causes OKD to periodically update this particular image stream tag. This period is a cluster-wide setting set to 15 minutes by default.

    2. Remove the periodic check, re-run above command but omit the --scheduled flag. This release_notes its behavior to default.

      1. $ oc tag <repositiory/image> <image-name:tag>

    Importing images and image streams from private registries

    An image stream can be configured to import tag and image metadata from private image registries requiring authentication. This procedures applies if you change the registry that the Cluster Samples Operator uses to pull content from to something other than registry.redhat.io.

    Procedure

    1. You must create a secret object that is used to store your credentials by entering the following command:

      1. $ oc create secret generic <secret_name> --from-file=.dockerconfigjson=<file_absolute_path> --type=kubernetes.io/dockerconfigjson

    2. After the secret is configured, create the new image stream or enter the oc import-image command:

      1. $ oc import-image <imagestreamtag> --from=<image> --confirm

      During the import process, OKD picks up the secrets and provides them to the remote party.

    The .dockercfg $HOME/.docker/config.json file for Docker clients is a Docker credentials file that stores your authentication information if you have previously logged into a secured or insecure registry.

    To pull a secured container image that is not from OKD’s internal registry, you must create a pull secret from your Docker credentials and add it to your service account.

    Procedure

    • If you already have a .dockercfg file for the secured registry, you can create a secret from that file by running:

      1. $ oc create secret generic <pull_secret_name> \
      2.     --from-file=.dockercfg=<path/to/.dockercfg> \
      3.     --type=kubernetes.io/dockercfg

    • Or if you have a $HOME/.docker/config.json file:

      1. $ oc create secret generic <pull_secret_name> \
      2.     --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
      3.     --type=kubernetes.io/dockerconfigjson

    • If you do not already have a Docker credentials file for the secured registry, you can create a secret by running:

      1. $ oc create secret docker-registry <pull_secret_name> \
      2.     --docker-server=<registry_server> \
      3.     --docker-username=<user_name> \
      4.     --docker-password=<password> \
      5.     --docker-email=<email>