anchor.diff:  }
   ----
   ====
  +
  +[[referencing-images-in-image-streams]]
  +
  +=== Referencing Images in Image Streams
  +
  +An `*ImageStreamTag*` is used to reference or retrieve an image for a given
  +image stream and tag. It uses the following convention for its name: `<image
  +stream name>:<tag>`.
  +
  +An `*ImageStreamImage*` is used to reference or retrieve an image for a given
  +image stream and image name. It uses the following convention for its name:
  +`<image stream name>@<name>`.
  +
  +The sample image below is from the *ruby* image stream and was
  +retrieved by asking for the `*ImageStreamImage*` with the name
  +*ruby@371829c*:
  +
  +.Definition of an Image Object retrieved via ImageStreamImage
  +====
  +
  +[source,json]
  +----
  +{
  +    "kind": "ImageStreamImage",
  +    "apiVersion": "v1",
  +    "metadata": {
  +        "name": "ruby@371829c",
  +        "uid": "a48b40d7-18e2-11e5-9ba2-001c422dcd49",
  +        "resourceVersion": "1888",
  +        "creationTimestamp": "2015-06-22T13:29:00Z"
  +    },
  +    "image": {
  +        "metadata": {
  +            "name": "371829c6d5cf05924db2ab21ed79dd0937986a817c7940b00cec40616e9b12eb",
  +            "uid": "a48b40d7-18e2-11e5-9ba2-001c422dcd49",
  +            "resourceVersion": "1888",
  +            "creationTimestamp": "2015-06-22T13:29:00Z"
  +        },
  +        "dockerImageReference": "openshift/ruby-20-centos7:latest",
  +        "dockerImageMetadata": {
  +            "kind": "DockerImage",
  +            "apiVersion": "1.0",
  +            "Id": "371829c6d5cf05924db2ab21ed79dd0937986a817c7940b00cec40616e9b12eb",
  +            "Parent": "8c7059377eaf86bc913e915f064c073ff45552e8921ceeb1a3b7cbf9215ecb66",
  +            "Created": "2015-06-20T23:02:23Z",
  +            "ContainerConfig": {},
  +            "DockerVersion": "1.6.0",
  +            "Author": "Jakub Hadvig \u003cjhadvig@redhat.com\u003e",
  +            "Config": {
  +                "User": "1001",
  +                "ExposedPorts": {
  +                    "8080/tcp": {}
  +                },
  +                "Env": [
  +                    "PATH=/opt/openshift/src/bin:/opt/openshift/bin:/usr/local/sti:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
  +                    "STI_SCRIPTS_URL=image:///usr/local/sti",
  +                    "HOME=/opt/openshift/src",
  +                    "BASH_ENV=/opt/openshift/etc/scl_enable",
  +                    "ENV=/opt/openshift/etc/scl_enable",
  +                    "PROMPT_COMMAND=. /opt/openshift/etc/scl_enable",
  +                    "RUBY_VERSION=2.0"
  +                ],
  +                "Cmd": [
  +                    "usage"
  +                ],
  +                "Image": "8c7059377eaf86bc913e915f064c073ff45552e8921ceeb1a3b7cbf9215ecb66",
  +                "WorkingDir": "/opt/openshift/src",
  +                "Labels": {
  +                    "io.openshift.s2i.scripts-url": "image:///usr/local/sti",
  +                    "k8s.io/description": "Platform for building and running Ruby 2.0 applications",
  +                    "k8s.io/display-name": "Ruby 2.0",
  +                    "openshift.io/expose-services": "8080:http",
  +                    "openshift.io/tags": "builder,ruby,ruby20"
  +                }
  +            },
  +            "Architecture": "amd64",
  +            "Size": 53950504
  +        },
  +        "dockerImageMetadataVersion": "1.0"
  +    }
  +}
  +----
  +====
  +
  +[[image-pull-policy]]
  +
  +=== Image Pull Policy
  +
  +Each container in a pod has a Docker image. Once you have created an image and
  +pushed it to a registry, you can then refer to it in the pod.
  +
  +When OpenShift creates containers, it uses the container's `*imagePullPolicy*`
  +to determine if the image should be pulled prior to starting the container.
  +There are three possible values for `*imagePullPolicy*`:
  +
  +- `*Always*` - always pull the image.
  +- `*IfNotPresent*` - only pull the image if it does not already exist on the node.
  +- `*Never*` - never pull the image.
  +
  +If a container's `*imagePullPolicy*`
  +parameter is not specified, OpenShift sets it based on the image's tag:
  +
  +. If the tag is *latest*, OpenShift defaults `*imagePullPolicy*` to `*Always*`.
  +. Otherwise, OpenShift defaults `*imagePullPolicy*` to `*IfNotPresent*`.
  +
  +[[importing-tag-and-image-metadata]]
  +
  +=== Importing Tag and Image Metadata
  +An image stream can be configured to import tag and image metadata from an image
  +repository in an external Docker image registry. See
  +link:../infrastructure_components/image_registry.html[Image Registry] for more
  +details.
  +
  +[[tag-tracking]]
  +
  +=== Tag Tracking
  +An image stream can also be configured so that a tag "tracks" another one. For
  +example, you can configure the *latest* tag to always refer to the current image
  +for the tag "2.0":
  +
  +====
  +
  +[source,json]
  +----
  +{
  +  "kind": "ImageStream",
  +  "apiVersion": "v1",
  +  "metadata": {
  +    "name": "ruby"
  +  },
  +  "spec": {
  +    "tags": [
  +      {
  +        "name": "latest",
  +        "from": {
  +          "kind": "ImageStreamTag",
  +          "name": "2.0"
  +        }
  +      }
  +    ]
  +  }
  +}
  +----
  +====
  +
  +You can also do the same using the `oc tag` command:
  +
  +`oc tag ruby:latest ruby:2.0`
  
positive.code: operations without creating a new layer at each step, resulting in a fast
  process. In addition, S2I scripts can be written to re-use artifacts stored in a
  previous version of the application image, rather than having to download or
  build them, each time the build is run.
  
  Patchability:: S2I allows you to rebuild the application consistently if an
  underlying image needs a patch due to a security issue.
  
  Operational efficiency:: By restricting build operations instead of allowing
  arbitrary actions, such as in a *_Dockerfile_*, the PaaS operator can avoid
  accidental or intentional abuses of the build system.
  
  Operational security:: Building an arbitrary *_Dockerfile_* exposes the host
  system to root privilege escalation. This can be exploited by a malicious user
  because the entire Docker build process is run as a user with Docker privileges.
  S2I restricts the operations performed as a root user, and can run the scripts
  as a non-root user.
  
  User efficiency:: S2I prevents developers from performing arbitrary `yum
  install` type operations during their application build, which results in slow
  development iteration.
  
  Ecosystem:: S2I encourages a shared ecosystem of images where you can leverage
  best practices for your applications.
  
  [#custom-build]
  === Custom Build
  The Custom build strategy allows developers to define a specific builder image,
  responsible for the entire build process. Using your own builder image allows
  you to customize your build process.
  
  
negative.code: === Docker Build
  The Docker build strategy invokes the plain
  https://docs.docker.com/reference/commandline/cli/#build[docker build] command,
  and it therefore expects a repository with a *_Dockerfile_* and all required
  artifacts in it to produce a runnable image.
  
  [#source-build]
  === Source-to-Image (S2I) Build
  link:../../creating_images/s2i.html[Source-to-Image (S2I)] is a tool for
  building reproducible Docker images. It produces ready-to-run images by
  injecting application source into a Docker image and assembling a new Docker
  image.  The new image incorporates the base image (the builder) and built source
  and is ready to use with the `docker run` command. S2I supports incremental
  builds, which re-use previously downloaded dependencies, previously built
  artifacts, etc.
  
  The advantages of S2I include the following:
  
  [horizontal]
  Image flexibility:: S2I scripts can be written to inject application code into
  almost any existing Docker image, taking advantage of the existing ecosystem.
  Note that, currently, S2I relies on `tar` to inject application
  source, so the image needs to be able to process tarred content.
  