Skip to content

Update documentation for image stream limits to clarify definitions a… #109556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stevsmit wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update documentation for image stream limits to clarify definitions a… #109556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions modules/admin-quota-limits.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,17 +117,17 @@ where:

`limits.max.storage`:: Specifies the maximum size of an image that can be pushed to an internal registry.

`limits.max.openshift.io/image-tags`:: Specifies the maximum number of unique image tags as defined in the specification for the image stream.
`limits.max.openshift.io/image-tags`:: Specifies the maximum number of unique references counted from tag definitions in the `imagestream.spec.tags` resource.

`limits.max.openshift.io/images`:: Specifies the maximum number of unique image references as defined in the specification for the image stream status.
`limits.max.openshift.io/images`:: Specifies the maximum number of unique image identities, or digests, recorded in the `imagestream.status.tags` resource.

`type.max.cpu`:: Specifies the maximum amount of CPU that a pod can request on a node across all containers.

`type.max.memory`:: Specifies the maximum amount of memory that a pod can request on a node across all containers.

`type.max.ephemeral-storage`:: Specifies the maximum amount of ephemeral storage that a pod can request on a node across all containers.

`min.cpu`:: Speciifes the minimum amount of CPU that a pod can request on a node across all containers. See the Supported Constraints table for important information.
`min.cpu`:: Specifies the minimum amount of CPU that a pod can request on a node across all containers. See the Supported Constraints table for important information.

`min.memory`:: Specifies the minimum amount of memory that a pod can request on a node across all containers. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more than the `max` memory value.

Expand Down
9 changes: 7 additions & 2 deletions modules/image-stream-limits.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,14 @@ An image stream can consume the following resources:
* `openshift.io/images`
* `openshift.io/ImageStream`

The `openshift.io/image-tags` resource represents unique stream limits. Possible references are an `ImageStreamTag`, an `ImageStreamImage`, or a `DockerImage`. You can use the `oc tag` and `oc import-image` commands or use image stream to create tags. No distinction exists between internal and external references. However, each unique reference that is tagged in an image stream specification is counted only once. The reference does not restrict pushes to an internal container image registry in any way, but the reference is useful for tag restriction.
The `openshift.io/image-tags` limit bounds unique references derived from tag definitions in the `imagestream.spec.tags` resource. A reference can be an `ImageStreamTag`, an `ImageStreamImage`, or a `DockerImage`. You can use the `oc tag` and `oc import-image` commands to create tags. Internal and external references are not distinguished, and each unique reference in the spec is counted once. Updates that would exceed the limit are rejected, including updates from pushes to the internal registry that add or change tag definitions.

The `openshift.io/images` resource represents unique image names that are recorded in image stream status. The resource helps restrict the number of images that can be pushed to the internal registry. Internal and external references are not distinguished.
The `openshift.io/images` limit bounds unique image identities recorded in `imagestream.status.tags`. The name is equivalent to the digest for the image. It limits how many distinct images the stream can reference in status, including from registry pushes. Internal and external references are not distinguished.

[IMPORTANT]
====
Do not read `openshift.io/image-tags` and `openshift.io/images` as "tag names versus images per tag." The first limit is computed from the `ImageStream` `spec.tags` resource. The second is computed from the `imagestream.status.tags` resource. Both limits can cause image stream updates to fail when a push or other operation would exceed them.
====

The following table shows the supported constraints for an image stream. If specified, the constraints must hold true for each image stream.

Expand Down
2 changes: 1 addition & 1 deletion modules/nodes-cluster-limit-ranges-creating.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ where:
`spec.limit.type.defaultRequest`:: For a container, specifies the default amount of CPU or memory that a container can request, if not specified in the `Pod` spec. This parameter is optional.
`spec.limit.type.maxLimitRequestRatio`:: For a container, specifies the maximum limit-to-request ratio that can be specified in the `Pod` spec. This parameter is optional.
`spec.limit.type.openshift.io/Image`:: Specifies limits for an image object. Set the maximum size of an image that can be pushed to an {product-registry}.
`spec.limit.type.openshift.io/ImageStream`:: Specifies limits for an image stream. Set the maximum number of image tags and references that can be in the `ImageStream` object file, as needed.
`spec.limit.type.openshift.io/ImageStream`:: Specifies limits for an image stream: `openshift.io/image-tags` caps unique references from `spec.tags`, and `openshift.io/images` caps unique images recorded in `status.tags`.
`spec.limit.type.openshift.io/PersistentVolueClaim`:: Specifies limits for a persistent volume claim. Set the minimum and maximum amount of storage that can be requested.
--

Expand Down
17 changes: 11 additions & 6 deletions modules/nodes-cluster-limit-ranges-limits.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,11 +167,16 @@ A limit range allows you to specify limits for image streams.
For each image stream, the following requirements must hold true:
+
--
* The number of image tags in an `ImageStream` specification must be less than or equal to the `openshift.io/image-tags` constraint in the `LimitRange` object.
* The count of unique references derived from `imagestream.spec.tags` must be less than or equal to the `openshift.io/image-tags` constraint in the `LimitRange` object.

* The number of unique references to images in an `ImageStream` specification must be less than or equal to the `openshift.io/images` constraint in the limit range object.
* The count of unique image identities recorded in `imagestream.status.tags` must be less than or equal to the `openshift.io/images` constraint in the `LimitRange` object.
--
+
[IMPORTANT]
====
The names `openshift.io/image-tags` and `openshift.io/images` do not mean a maximum number of tag names versus a maximum number of images per tag. The first limit applies to tag definitions and their references in the `ImageStream` `spec.tags` resource. The second applies to distinct resolved images (typically by digest) recorded in the `ImageStream` `status.tags` resource. Creating or updating tags, including by pushing to the {product-registry}, can be rejected if it would exceed either limit.
====
+
.Imagestream `LimitRange` object definition
[source,yaml]
----
Expand All @@ -190,13 +195,13 @@ where
+
--
`metadata.name`:: Specifies the name of the `LimitRange` object.
`spec.limit.max.openshift.io/image-tags`:: Specifies the maximum number of unique image tags in the `imagestream.spec.tags` parameter in imagestream spec.
`spec.limit.max.openshift.io/images`:: Specifies the maximum number of unique image references in the `imagestream.status.tags` parameter in the `imagestream` spec.
`spec.limit.max.openshift.io/image-tags`:: Specifies the maximum number of unique references counted from tag definitions in `imagestream.spec.tags`.
`spec.limit.max.openshift.io/images`:: Specifies the maximum number of unique image identities (image names equal to the digest) recorded in `imagestream.status.tags`.
--
+
The `openshift.io/image-tags` resource represents unique image references. Possible references are an `*ImageStreamTag*`, an `*ImageStreamImage*` and a `*DockerImage*`. Tags can be created using the `oc tag` and `oc import-image` commands. No distinction is made between internal and external references. However, each unique reference tagged in an `ImageStream` specification is counted just once. It does not restrict pushes to an internal container image registry in any way, but is useful for tag restriction.
The `openshift.io/image-tags` limit counts unique references from entries in `imagestream.spec.tags`. A reference can be an `*ImageStreamTag*`, `*ImageStreamImage*`, or `*DockerImage*`. You can add tag definitions with `oc tag` or `oc import-image`. Internal and external references are treated the same, and each unique reference in the spec is counted once. If an update would raise the count above the limit, the request is rejected, including when the update is caused by a push to the {product-registry}.
+
The `openshift.io/images` resource represents unique image names recorded in image stream status. It allows for restriction of a specific number of images that can be pushed to the {product-registry}. Internal and external references are not distinguished.
The `openshift.io/images` limit counts unique image identities in `imagestream.status.tags`. It bounds how many distinct images the stream can hold in status. Internal and external references are not distinguished.

Persistent volume claim limits::
A limit range allows you to restrict the storage requested in a persistent volume claim (PVC).
Expand Down