// Module included in the following assemblies:
// * openshift_images/tagging-images

:_mod-docs-content-type: PROCEDURE
[id="images-referencing-images-imagestreams_{context}"]
= Using image stream reference syntax

[role="_abstract"]
To ensure that your builds and deployments use the intended image version in {product-title}, you must use the correct reference syntax format.

.Procedure

* To reference an image by a mutable tag (`ImageStreamTag`) from an image stream within your cluster, use the `<image_stream_name>:<tag>` format in your build or deployment. For example:
+
[source,yaml]
----
# ...
spec:
  containers:
    - name: my-app
      image: <image_stream_name>:<tag>
----
+
--
where:

`spec.containers.image`:: Specifies the image to use from the image stream. For example, `ruby:2.0`.
--

* To reference a specific, immutable image ID, or digest, within an image stream, use the `<image_stream_name>@<image_id>` format in your build or deployment. For example:
+
[source,yaml]
----
# ...
spec:
  containers:
    - name: my-app
      image: <image_stream_name>@<image_id>
----
+
--
where:

`spec.containers.image`:: Specifies the image to use from the image stream. For example, `ruby@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e`.
--
+
[NOTE]
====
Using the image ID with the `@id` syntax ensures your configuration always uses the exact same image, even if the tag is later updated to point to a different image.
====

* To reference an image from an external registry by using the DockerImage format, use the standard Docker pull specification: `<registry>/<namespace>/<image_name>:<tag>`. For example:
+
[source,yaml]
----
# ...
spec:
  source:
    type: Dockerfile
  strategy:
    type: Docker
    dockerStrategy:
      from:
        kind: DockerImage
        name: <registry>/<namespace>/<image_name>:<tag>
----
+
--
where:

`spec.strategy.dockerStrategy.from.name`:: Specifies the image to use from the external registry. For example, `registry.redhat.io/rhel7:latest`.
--
+
[NOTE]
====
When no tag is specified in a `DockerImage` reference, the `latest` tag is assumed.
====