BZ 1446644 Adding more detail on image streams #5322
Conversation
|
@sferich888 |
|
@bmcelvee this looks similar to the item i suggested to you. |
There was a problem hiding this comment.
I think we should start this with a glossary of terms that explains:
-
docker repository (docker.io/openshift/jenkins-2-centos7)
-
docker repository tag (docker.io/openshift/jenkins-2-centos7:latest)
-
docker image sha (docker.io/openshift/jenkins-2-centos7@sha256:ab312bda324)
-
imagestream
-
imagestream tag
-
imagestream image
| . Its own image repository in {product-title}'s | ||
| xref:../../architecture/infrastructure_components/image_registry.adoc#integrated-openshift-registry[integrated | ||
| //from image-streams-faq/ | ||
| An Image Stream contains all of the metadata information about any given image that is specified in the Image Stream specification. |
There was a problem hiding this comment.
this sentence seems redundant, all it says is "an imagestream contains the information that is specified in the imagestream"
I think it would be more useful to combine this w/ the next sentence and say "An imagestream does not contain actual image data, it is simply a mapping between tags and the actual images. It can contain additional metadata that describes the tags provided by the imagestream."
| ---- | ||
|
|
||
| <1> The name of the image stream. | ||
| <2> The image source (repository or other image stream). |
There was a problem hiding this comment.
that field can only take on a repository value, it can't be an imagestream. i'm not really sure what purpose status.dockerImageRepository even serves, since each status.tag indicates where the tag comes from. @soltysh ?
There was a problem hiding this comment.
It's again connected with already depreacated .spec.dockerImageRepository, but you're right this is just repo, you can pull image from. Usually cluster internal link, but recently with addition of public pull spec (openshift/origin#15853) this can give you pullable docker image (from outside the cluster)
|
|
||
| <1> The name of the image stream. | ||
| <2> The image source (repository or other image stream). | ||
| <3> The name of the external image to use. |
There was a problem hiding this comment.
"the sha identifier that this imagestream tag currently references and which will be used by resources that reference this imagestream tag"
| <1> The name of the image stream. | ||
| <2> The image source (repository or other image stream). | ||
| <3> The name of the external image to use. | ||
| <4> The image tag. |
| * If the source image changes, the Image Stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| However, if an image author pushes a newer version of an image without properly tagging the image, it can accidentally create a new distinct image (with newer version information). | ||
| This condition can impact applications in unexpected ways. |
There was a problem hiding this comment.
this needs to elaborate on what it means to "push an image without properly tagging it" (and how/why that is problem since just above we claimed the imagestream insulates you from this)
| However, if an image author pushes a newer version of an image without properly tagging the image, it can accidentally create a new distinct image (with newer version information). | ||
| This condition can impact applications in unexpected ways. | ||
|
|
||
| Also, use caution when using the `latest` taq in an image stream (as opposed to the version-specific tags). The `latest` tag will use the latest available version of the specified Image. |
There was a problem hiding this comment.
this a convention. our "latest" imagestreamtags specifically, are reference tags which follow another imagestreamtag and could be updated in the future to change what they follow (much like a symlink. our latest tag is a symlink to v2.4, in the future we might change it to be a symlink to v2.5).
However users can create their own imagestreamtags named anything they want. And those imagestreamtags might or might not be reference-style tags.
In short, we need a deep discussion of reference-style tags, and this isn't the place to talk about the behavior of our specific imagestreams that happen to define latest in this way.
There was a problem hiding this comment.
Also in general throughout this document it's critical to be extremely clear as to whether you are talking about a "docker image tag" or a "imagestream tag" because they are two different things with different implications.
| Users, without permission to read or list images on the cluster level, can still | ||
| retrieve the images tagged in a project they have access to using this resource. | ||
| Users that lack permission to read or list images on the cluster level can still | ||
| retrieve the images tagged in a project using this image streams. |
| //from FAQ | ||
| For example, xref:../dev_guide/builds/triggering_builds.adoc#image-change-triggers[Builds] and | ||
| xref:../dev_guide/deployments/basic_deployment_operations.adoc#image-change-trigger[Deployments] can be automatically started when an Image Stream is modified. | ||
| This is achieved by monitoring that particular Image Stream and notifying the controller (the Build or Deployment) when a change was detected. |
There was a problem hiding this comment.
"monitoring that particular Image Stream Tag"
|
|
||
| //from FAQ | ||
| For example, xref:../dev_guide/builds/triggering_builds.adoc#image-change-triggers[Builds] and | ||
| xref:../dev_guide/deployments/basic_deployment_operations.adoc#image-change-trigger[Deployments] can be automatically started when an Image Stream is modified. |
| @@ -175,17 +175,51 @@ endif::[] | |||
| [[image-streams]] | |||
| == Image Streams | |||
|
|
|||
| //from https://blog.openshift.com/image-streams-faq/ | |||
| An Image Stream is a pointer to an image using various identifying qualities. This means that even if the source image changes, | |||
| the Image Stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | |||
There was a problem hiding this comment.
Unless you, either:
- have scheduled import set
- manually re-import the image.
I think it's worth mentioning that.
| A SHA code that can be used to pull an image. For example: | ||
| *docker.io/openshift/jenkins-2-centos7@sha256:ab312bda324*. | ||
|
|
||
| Imagestream:: |
| An {product-title} object that comprises any number of Docker-formatted container images identified by tags. | ||
| See xref:image-streams[Image Streams] below. | ||
|
|
||
| Imagestream tag:: |
| Imagestream tag:: | ||
| A named pointer to an image in an image stream. See xref:image-stream-tag[Image Stream Tag] below. | ||
|
|
||
| Imagestream image:: |
| A named pointer to an image in an image stream. See xref:image-stream-tag[Image Stream Tag] below. | ||
|
|
||
| Imagestream image:: | ||
| An image that allows you to retrieve an image from a particular image stream where it is tagged. |
There was a problem hiding this comment.
An object that allows you to retrieve a particular docker image from a particular image stream.
| *docker.io/openshift/jenkins-2-centos7@sha256:ab312bda324*. | ||
|
|
||
| Imagestream:: | ||
| An {product-title} object that comprises any number of Docker-formatted container images identified by tags. |
There was a problem hiding this comment.
An object that comprises any number of Image Stream Tags. IS per se does not have any docker images, only pointers to them.
| ---- | ||
|
|
||
| <1> The name of the image stream. | ||
| <2> The image source (repository or other image stream). |
There was a problem hiding this comment.
It's again connected with already depreacated .spec.dockerImageRepository, but you're right this is just repo, you can pull image from. Usually cluster internal link, but recently with addition of public pull spec (openshift/origin#15853) this can give you pullable docker image (from outside the cluster)
| An Image Stream is a pointer to an image using various identifying qualities. This means that even if the source image changes, | ||
| the Image Stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| An imagestream does not contain actual image data, it is simply a mapping between tags and the actual images. |
There was a problem hiding this comment.
mapping between tags and actual images
| the Image Stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| An imagestream does not contain actual image data, it is simply a mapping between tags and the actual images. | ||
| It can contain additional metadata that describes the tags provided by the imagestream. |
| ==== | ||
| //Ben: i'm not really sure what purpose status.dockerImageRepository even serves, since each status.tag indicates where the tag comes from. @soltysh ? |
There was a problem hiding this comment.
Like I've mentioned elsewhere, we deprecated .spec.dockerImageRepository, @bparees did you deprecate the .status.dockerImageRepository along with the other?
Currently it should provide with a pull spec, usually cluster internal, unless there's a public url for the registry configured.
There was a problem hiding this comment.
no, I didn't deprecate .status.dockerImageRepository but i'm glad you suggested it too because i proposed it to @smarterclayton and he explained to me all the reasons we can never do that (that it presents the target for pushes to the imagestream, ie the internal registry service ip)
There was a problem hiding this comment.
the user doesn't set it, it gets set by the system. it will point to the internal registry service ip.
There was a problem hiding this comment.
@bparees hmmm... I'm not sure if that is still true with our current abilities where each tag can point to a totally different backing repo. In which case we still should read that information per tag, imho. It's worth a second thought, I guess.
There was a problem hiding this comment.
@soltysh yes I raised similar questions to @smarterclayton but the answer I got is that status.DockerImageRepository is the location where users can push to in the internal registry. I guess they already know where to push to if they want to update the external image (on dockerhub for example) but if they want to push to the imagestream directly to create new tags, status.DockerImageRepository is the registry host they'd push to to accomplish that.
I'm glad I'm not the only one confused by this, though :)
| 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 new image is pushed to the registry, or schedule the import to do it later. |
There was a problem hiding this comment.
Triggering and scheduling should not be mixed in this way. The above sentence suggests you can specify a point in time when an image will be re-imported, but that's not true. Scheduled import is about having the image stream tag checked every X minutes (configured by cluster admin) and if the source image has changed that change will be picked up and reflected in image stream. That in turn can trigger Build and/or Deployment flow.
There was a problem hiding this comment.
+1
import - refresh what this imagestreamtag points to
trigger - do something when an imagestreamtag changes
import can lead to a trigger, but so can other things. and import might not cause a trigger if nothing cares about that particular imagestreamtag.
|
|
||
| * 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 new image is pushed to the registry, or schedule the import to do it later. | ||
| * You can share images using fine-grained access and quickly distribute images across your teams. |
| An _image stream image_ allows you to retrieve an image from a particular image stream | ||
| where it is tagged. | ||
|
|
||
| The image stream image consists of two parts delimited by an `@` sign: | ||
| `<image stream name>@<image name>`. To refer to the image in the |
There was a problem hiding this comment.
<image stream name>@<image name> - maybe write image name/id. Although we use the name for the image object, it's actually docker image id, and people might get confused seeing name here, and seeing something like sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d
| [[image-stream-triggers]] | ||
| === Image Stream Triggers | ||
|
|
||
| Image change triggers allow your build or deployment (via replication controller) to be automatically invoked when a new version of an upstream image is available. |
There was a problem hiding this comment.
your build or deployment (via replication controller)
That RC is not important in this context.
| An _image stream is a pointer to an image using various identifying qualities. This means that even if the source image changes, | ||
| the image stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| Note that an image stream can be configured to periodically chack for updates (using the `--scheduled` tag) or you can start a |
| the image stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| Note that an image stream can be configured to periodically chack for updates (using the `--scheduled` tag) or you can start a | ||
| new build manually by re-importing an image (using the `oc import-image` command). |
There was a problem hiding this comment.
or you can manually re-import an image
It has nothing to do with builds, here.
| new build manually by re-importing an image (using the `oc import-image` command). | ||
|
|
||
| An image stream does not contain actual image data, it is simply a mapping between tags and actual images. | ||
| It can contain additional metadata that describes the tags provided by the imagestream. |
| * If the source image changes, the Image Stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| // https://access.redhat.com/solutions/3016781 Caveats around referencing latest tags | ||
| However, a general caveat is to understand what your ImageStreamTag is pointing to, and be careful if it changes what it points to". |
There was a problem hiding this comment.
It's not a caveat of using image streams, but docker images in general. IS are only affected with this rule the same way everything else using latest tag.
There was a problem hiding this comment.
Acutally, IS bypass the problem of using latest by providing you a stable pointer, until the next import.
There was a problem hiding this comment.
Yeah, this is another place where we really need a glossary to setup the concept of docker tags vs imagestream tags, because they have different characteristics that need to be understood.
(and imagestreamtags that "reference" another imagestreamtag are yet another level of complexity that needs to be explained, and that's where you get into the whole issue of "not using latest because latest could suddenly point to something new" (where it may or may not actually be called latest))
There was a problem hiding this comment.
@soltysh FYI. The wording "caveat" came from here, which was added as an External Tracker in the original BZ:
https://access.redhat.com/solutions/3016781
|
|
||
| * 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 new image is pushed to the registry. | ||
| * You can periodically reimport images on a defined schedule. If the source image has changed, that change is picked up and reflected in image stream and |
There was a problem hiding this comment.
You can mark a tag for a periodical re-import (link to https://docs.openshift.org/latest/dev_guide/managing_images.html#importing-tag-and-image-metadata)
| * 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 new image is pushed to the registry. | ||
| * You can periodically reimport images on a defined schedule. If the source image has changed, that change is picked up and reflected in image stream and | ||
| trigger the Build and/or Deployment flow. |
There was a problem hiding this comment.
and can trigger a Build and/or Deployment
There was a problem hiding this comment.
If it triggers is dependent on Build/Deployment configuration.
There was a problem hiding this comment.
yeah again the concept of triggering builds/deployments should really be called out as its own section. It is only tangentially related to managing/maintaining/updating imagestreams+imagestreamtags.
|
@bmcelvee @sferich888 @mburke5678 if you guys are interested, i'd be happy to have a 15-30 minute BJ session w/ you guys to walk through docker images vs imagestreams vs imagestreamtags, reference tags, etc, if you think it would help you revise this doc. I might want @soltysh to keep me honest though. |
|
Added Working with Image Streams using the Practice section from the Image Stream FAQ docs. Also, I created the Image Streams section as its own topic to see how folks thought that might work. |
If you need me as well, just ping me :) |
| @@ -175,17 +175,58 @@ endif::[] | |||
| [[image-streams]] | |||
| == Image Streams | |||
|
|
|||
| //from https://blog.openshift.com/image-streams-faq/ | |||
| An _image stream is a pointer to an image using various identifying qualities. This means that even if the source image changes, | |||
There was a problem hiding this comment.
_image stream_ <- I think you're missing closing underscore
| the image stream will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| Note that an image stream can be configured to periodically chack for updates (using the `--scheduled` flag on a tag) | ||
| or you can re-importing an image (using the `oc import-image` command). |
| A label applied to a Docker image in a repository that distinguish specific images. For example, here *latest* is a tag: | ||
| *docker.io/openshift/jenkins-2-centos7:latest* | ||
|
|
||
| Docker image sha:: |
There was a problem hiding this comment.
s/Docker image sha/Docker image id
SHA is a shorthand for secure hashing algorithm, but the name most frequently use is ID here.
| See xref:image-stream-image[Image Stream Images] below. | ||
|
|
||
| Image stream trigger:: | ||
| A trigger causes a specific action when an image stream tag changes. Importing an image can be a trigger, along with other things. An import only causes a trigger if an image stream is following the associated image stream tag. See xref:image-stream-triggers[Image Stream Triggers] below. |
There was a problem hiding this comment.
Import causes a trigger to fire only when there are deployments, builds or other resources listening for those.
|
|
||
| <1> The name of the image stream. | ||
| <2> The image source repository. | ||
| <3> The the internal registry service IP address, which is the target for pushes to the image stream. This valueis set automatically. |
| [[image-stream-triggers]] | ||
| === Image Stream Triggers | ||
|
|
||
| Image change triggers allow your build or deployment to be automatically invoked when a new version of an upstream image is available. |
| Tag python:3.6 set to import docker.io/python:3.6.0 periodically. | ||
| ---- | ||
|
|
||
| This command causes {product-title} to periodiallly update this particular image stream tag should. This period is a cluster-wide setting is set to 15 minutes by default. |
There was a problem hiding this comment.
Maybe link to master-config describing this?
|
|
||
| [[image-streams]] | ||
| //from https://blog.openshift.com/image-streams-faq/ | ||
| An _image stream is a pointer to an image using various identifying qualities. This means that even if the source image changes, |
There was a problem hiding this comment.
Rewrote that paragraph
| include::dev_guide/deployments/basic_deployment_operations.adoc[tag=image-change-trig] | ||
|
|
||
| [[image-stream-mappings]] | ||
| == Image Stream Mappings |
There was a problem hiding this comment.
Can this be marked as an advanced topic? Regular users don't need to bother with those implementation details.
There was a problem hiding this comment.
Added a note below.
"Configuring image stream mappings is an advanced feature."
@soltysh
Do we want to define when a user would need to create an image stream mapping?
| To remove the periodical check, re-run above command but omit the --scheduled flag. This will reset its behavior to default. | ||
|
|
||
| ---- | ||
| oc tag <repositiory/image> <image-name:tag> |
There was a problem hiding this comment.
Can we have this describe in only one document and all others will be only pointing to it? I'm confused now.
There was a problem hiding this comment.
@soltysh Not sure what you are asking. Do we want to move the "working with" concepts into the introductory sections? For ex. this command would go into the "Image Stream Tag" section?
|
@zhouying7780 Please take a look at |
| xref:../../architecture/infrastructure_components/image_registry.adoc#integrated-openshift-registry[integrated | ||
| // http://redhatgov.io/workshops/security_openshift/exercise1.3/ | ||
| An _image stream_ can automatically perform an action when new images are created. Builds and deployments can watch an image stream | ||
| to receive notifications when new images are added and react by performing a build or deployment, respectively. |
There was a problem hiding this comment.
the image stream isn't performing an action. deploymentconfigs+buildconfigs are choosing to watch the imagestream for changes and then take some action if it does change.
| <1> The name of the image stream. | ||
| <2> The image source repository. | ||
| <3> The internal registry service IP address, which is the target for pushes to the image stream. This value is set automatically. | ||
| <3> The SHA identifier that this image stream tag currently references. Resources that reference this image stream tag use this identifier. |
There was a problem hiding this comment.
Couldn't find the 'The SHA identifier that this image stream tag currently references' ?
There was a problem hiding this comment.
@zhouying7780 Thank you. I fixed the call-out numbering. The SHA identifier is <4>:
image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 <4>
| is often abbreviated as _istag_. An image stream tag is used to reference or retrieve | ||
| an image for a given image stream and tag. | ||
|
|
||
| Image stream taga can reference any local or externally |
| @@ -175,29 +175,143 @@ endif::[] | |||
| [[image-streams]] | |||
| == Image Streams | |||
|
|
|||
| An _image stream_ comprises any number of | |||
There was a problem hiding this comment.
this whole file needs to be renamed, right?
There was a problem hiding this comment.
@bparees Yeah, I think that the Image Stream section should be its own page. I will see what the others think. You have any thoughts?
There was a problem hiding this comment.
yes they should be split out (also you seem to have updated the table of contents to imply there would only be an images page? but i guess you'll want to add a builds entry to the table of contents).
Maybe do that in a follow up PR though, so we can keep this one to getting the content right? There's been a lot of good discussion/review and i don't want to muddy the waters further.
| You can think of an image stream as a wrapper or abstraction | ||
| for Docker images to see what images are available and to 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 presenta single virtual view of related images, similar to an image repository. |
| related images, similar to an image repository, and may contain images from any | ||
| of the following: | ||
| An _image stream_ is a mapping between tags in {product-title} objects and | ||
| xref:../../architecture/core_concepts/containers_and_images.adoc#docker-images[Docker image] images. |
There was a problem hiding this comment.
"An image stream and its associated tags provide an abstraction for referencing Docker images from within OpenShift."
| xref:../../architecture/core_concepts/containers_and_images.adoc#docker-images[Docker image] images. | ||
| You can think of an image stream as a wrapper or abstraction | ||
| for Docker images to see what images are available and to ensure that you are using the specific image you need even if the image in | ||
| the repository changes. |
There was a problem hiding this comment.
"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."
|
|
||
| . Its own image repository in {product-title}'s | ||
| xref:../../architecture/infrastructure_components/image_registry.adoc#integrated-openshift-registry[integrated | ||
| Yoyu can configure xref:../dev_guide/builds/triggering_builds.adoc#image-change-triggers[Builds] and |
|
|
||
| Image stream trigger:: | ||
| A trigger that causes a specific action when an image stream tag changes. For example, importing an image can be a trigger. | ||
| Importing causes a trigger to fire when there are Deployments, Buildss or other resources listening for those. See xref:image-stream-triggers[Image Stream Triggers] below. |
There was a problem hiding this comment.
importing is not the trigger.
the trigger is "the value of the tag changed". importing can cause the value of the tag to change, but so can pushing a new image to the tag.
There was a problem hiding this comment.
above comment still valid (importing is not a trigger, importing can cause the value of the tag to change, which is a trigger if it happens).
also s/Buildss/Builds/
| + | ||
| [NOTE] | ||
| ==== | ||
| Tracking tags are limited to a single image stream and cannot reference other image streams. |
There was a problem hiding this comment.
i'm not sure what this means, hopefully @soltysh can clarify.
| generation: 1 | ||
| image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d | ||
| tag: latest | ||
| ---- | ||
| ==== | ||
|
|
||
| [[image-stream-triggers]] | ||
| === Image Stream Triggers |
There was a problem hiding this comment.
image stream change triggers
| ---- | ||
|
|
||
| [[image-stream-mappings-working-adding-tags]] | ||
| ==== Adding Tags to an External Image |
|
|
||
| Docker repository:: | ||
| A central location for uploading and downloading images. | ||
| For example, the OpenShift Jenkins images are in a Docker registry: *docker.io/openshift/jenkins-2-centos7:latest*. |
There was a problem hiding this comment.
since this glossary appears twice i'm not sure what i'm reviewing anymore. i'm stopping here.
There was a problem hiding this comment.
@bparees Sorry. This comment must have gotten lost. I was thinking of breaking the Builds and Image Stream topic into two topics. This file is a test and I have not updated it for some time.
There was a problem hiding this comment.
can you create a PR where I can actually see the proposed changes, then? this is really frustrating to try to review in its current state.
There was a problem hiding this comment.
@bparees All proposed changes are in architecture/core_concepts/builds_and_image_streams.adoc. I removed the extraneous document.
| notifications when new images are added and react by performing a build or | ||
| deployment, respectively. For a | ||
| curated set of image streams, see the | ||
| The following image stream contains two tags: `34` which points to a Python v3.4 image and `35` which points to a Python v3.5 image: |
There was a problem hiding this comment.
this seems out of place since the example imagestream is two paragraphs down.
| The following image stream contains two tags: `34` which points to a Python v3.4 image and `35` which points to a Python v3.5 image: | ||
|
|
||
| When you define an object that references an image stream tag, you point to an image stream tag, not the Docker repository. When you build or deploy | ||
| your application, {product-title} queries the Docker repository using the image stream tag to locate the specific ID of the image and use that |
|
|
||
| Docker repository:: | ||
| A central location for uploading and downloading images. | ||
| For example, the OpenShift Jenkins images are in a Docker registry: |
There was a problem hiding this comment.
s/registry/repository/
And should add another entry for "docker registry": a content server that can store and service images from docker repositories. example being registry.access.redhat.com
| ---- | ||
|
|
||
| Docker image:: | ||
| A reference to an image for a given external registry. It uses the standard Docker pull specification for its name. |
There was a problem hiding this comment.
Docker image: A specific set of content that can be run as a container. Usually associated with a particular tag within a docker repository.
| === Important terms | ||
|
|
||
| Docker repository:: | ||
| A central location for uploading and downloading images. |
There was a problem hiding this comment.
Replace with: "A collection of related docker images and tags identifying them"
| === Image Stream Images | ||
|
|
||
| An _image stream image_ points from within an image stream | ||
| to a particular external image ID. It is often abbreviated as _isimage_. |
| An _image stream image_ points from within an image stream | ||
| to a particular external image ID. It is often abbreviated as _isimage_. | ||
|
|
||
| Image stream images allows you to retrieve an image from a particular image stream |
There was a problem hiding this comment.
allows you to retrieve metadata about an image from a particular image stream.
|
|
||
| * _Tracking tags_ are reference tags that follow another image stream tag and could be updated in the future to change which image they follow, much like a symlink. Note that these new levels are not guaranteed to be backwards-compatible. | ||
| + | ||
| For example, the `latest` image stream tags that ship with {product-title} are tracking tags. This means consumers of the `latest` image stream tag will be 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.6 could be changed to v3.7 at any time. It is important to be aware that the `latest` image stream tag behaves differently than the Docker `latest` tag. The `latest` image stream tag does not point to the latest image in the Docker repository. It points to another image stream tag that might not be the latest version of an image. For example, if the `latest` image stream tag points to v3.2 of an image, when the 3.3 version is released, the `latest` tag is not automatically updated to v3.3, and remains at v3.2 until it is manually updated. |
There was a problem hiding this comment.
The
latestimage stream tag does not point to the latest image in the Docker repository.
The latest image stream tag does not, in this case, point to the latest image in the Docker repository.
There was a problem hiding this comment.
It is important to be aware that the
latestimage stream tag behaves differently than the Dockerlatesttag.
It is important to be aware that these latest image stream tags behaves differently than the Docker latest tag.
There was a problem hiding this comment.
For example, if the
latestimage stream tag points to v3.2 of an image, when the 3.3 version is released, thelatesttag is not automatically updated to v3.3, and remains at v3.2 until it is manually updated.
For example, if the latest image stream tag points to an image stream tag for v3.2 of an image, when the 3.3 version is released, the latest tag is not automatically updated to v3.3, and remains at v3.2 until it is manually updated to point to a v3.3 image stream tag.
| + | ||
| [NOTE] | ||
| ==== | ||
| Tracking tags are limited to a single image stream and cannot reference other image streams. |
| Tag python:latest set to python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25. | ||
| ---- | ||
|
|
||
| Use the `oc describe` command to confirm the the image stream has two tags, one (`3.5`) pointing at the external Docker image and another tag (`latest`) pointing to a different tag in the same image stream. |
There was a problem hiding this comment.
and another tag (
latest) pointing to a different tag in the same image stream.
and another tag (latest) pointing to the same image because it was created based on the first tag.
|
@bparees Do you have a sample build config and/or deployment config that points to an image stream? Might like to add a sample of how the build/deploy references the image stream. |
|
|
||
| * If the source image changes, the image stream tag will still point to a known-good version of the image, ensuring that your application will not break unexpectedly. | ||
|
|
||
| * You can configure security around who can view and use the images through permissions on the image stream objects. |
There was a problem hiding this comment.
@bparees Do you know if we cover this in the docs? Not sure what I am looking for in how to set image permissions.
There was a problem hiding this comment.
probably not explicitly for imagestreams, they are controlled in the same way access is controlled to any resource: https://docs.openshift.org/latest/admin_guide/manage_authorization_policy.html
|
|
||
| Image stream image:: | ||
| An image that allows you to retrieve a specific Docker image from a particular image stream where it is tagged. | ||
| See xref:image-stream-image[Image Stream Images] below. |
There was a problem hiding this comment.
@bparees Is an image stream image simply an image that is referenced in an image stream?
There was a problem hiding this comment.
an "imagestreamimage" is an api resource object which pulls together some metadata about a particular image sha.
and yes it mostly exists because there is an imagestream that contains a tag that is currently pointing to that particular image sha.
|
@bparees Is there a general workflow that we can include:
|
|
@mburke5678 we already have examples of buildconfigs referencing imagestreamtags here: and deploymentconfigs referencing ISTs here: |
I really don't want to get sidetracked into this discussion. We are fixing the documentation of what imagestreams/tags are, not how to use them in a DC or a BC. |
| xref:../../architecture/infrastructure_components/image_registry.adoc#integrated-openshift-registry[integrated | ||
| 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 xref:../dev_guide/builds/triggering_builds.adoc#image-change-triggers[Builds] and |
There was a problem hiding this comment.
The Builds and Deployment links are broken.
| 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, |
There was a problem hiding this comment.
s/deployment/Deployment (for consistency)
| 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 docker image in the docker registry is updated, the build/deployment will continue using the previous (presumably known good) image. |
| notifications when new images are added and react by performing a build or | ||
| deployment, respectively. For a | ||
| curated set of image streams, see the | ||
| When you define an object that references an image stream tag (such as a or build configuration or deployment configuration), you point to an image stream tag, not the Docker repository. When you build or deploy your application, {product-title} queries the Docker repository using the image stream tag to locate the associated ID of the image and uses that |
There was a problem hiding this comment.
s/such as a or build configuration or deployment/such as a Build configuration or Deployment...
There was a problem hiding this comment.
s/build/Build; s/deploy/Deploy
| ==== | ||
|
|
||
| Docker image ID:: | ||
| A SHA code that can be used to pull an image. For example: |
There was a problem hiding this comment.
Since this is the first reference to SHA in this doc, do you think it needs to be defined? If it's common knowledge, it could slide.
| in the `Strategy` stanza of the configuration. | ||
|
|
||
| For a sample deployment configuration that references an image stream, | ||
| see xref:../../dev_guide/deployments/how_deployments_work.html#creating-a-deployment-configuration[Creating a Deployment Configuration] |
There was a problem hiding this comment.
The Creating a Deployment Configuration link is broken
|
LGTM |
|
Email exchange: Maciej Szulik | 4:00 PM (17 hours ago) |
(cherry picked from commit f53a22e) xref:openshift#5322
(cherry picked from commit f53a22e) xref:openshift#5322
(cherry picked from commit f53a22e) xref:openshift#5322
(cherry picked from commit f53a22e) xref:openshift#5322
(cherry picked from commit f53a22e) xref:openshift#5322
|
[rev_history] |
| [[image-stream-configure]] | ||
| === Configuring Image Streams | ||
|
|
||
| ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[] |
There was a problem hiding this comment.
@mburke5678 - something is not right here. This ifdef doesn't have a closing endif. Also, this seems to cover almost all distros that we have. Does it, and the next ifdef, need to be here if it applies to origin, enterprise, dedicated and online?
There was a problem hiding this comment.
@vikram-redhat That ifdef was in the file when I started on this issue. I thought the same thing; but, assumed that someone knew better than I. Same with the following one.
Looks like it was added here: Update for atomic registry use case
Thank you for adding the endif back.
| ---- | ||
|
|
||
| This command causes {product-title} to periodically update this particular image stream tag. This period is a | ||
| xref:../../install_config/master_node_configuration.adoc#master-config-image-config[cluster-wide setting] set to 15 minutes by default. |
There was a problem hiding this comment.
@mburke5678 because this goes into the dedicated and online branches, it should have been conditionalized for enterprise and origin branches only. I have fixed it for dedicated and online.
https://bugzilla.redhat.com/show_bug.cgi?id=1446644