Bug 1778534
| Summary: | Improve API descriptions of important user facing objects for API explorer and oc explain | |||
|---|---|---|---|---|
| Product: | OpenShift Container Platform | Reporter: | Clayton Coleman <ccoleman> | |
| Component: | ImageStreams | Assignee: | Clayton Coleman <ccoleman> | |
| Status: | CLOSED ERRATA | QA Contact: | XiuJuan Wang <xiuwang> | |
| Severity: | high | Docs Contact: | ||
| Priority: | unspecified | |||
| Version: | 4.3.0 | CC: | aos-bugs, jokerman, wzheng | |
| Target Milestone: | --- | |||
| Target Release: | 4.4.0 | |||
| Hardware: | Unspecified | |||
| OS: | Unspecified | |||
| Whiteboard: | ||||
| Fixed In Version: | Doc Type: | If docs needed, set a value | ||
| Doc Text: | Story Points: | --- | ||
| Clone Of: | ||||
| : | 1778535 (view as bug list) | Environment: | ||
| Last Closed: | 2020-05-13 21:53:23 UTC | Type: | Bug | |
| Regression: | --- | Mount Type: | --- | |
| Documentation: | --- | CRM: | ||
| Verified Versions: | Category: | --- | ||
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | ||
| Cloudforms Team: | --- | Target Upstream Version: | ||
| Embargoed: | ||||
| Bug Depends On: | ||||
| Bug Blocks: | 1778535 | |||
|
Description
Clayton Coleman
2019-12-01 23:42:41 UTC
Test with 4.4.0-0.nightly-2019-12-14-103510, and the result passed
$ ./oc version
Client Version: 4.4.0-0.nightly-2019-12-14-103510
Server Version: 4.4.0-0.nightly-2019-12-14-103510
Kubernetes Version: v1.16.2
$ ./oc explain images
KIND: Image
VERSION: image.openshift.io/v1
DESCRIPTION:
Image is an immutable representation of a container image and metadata at a
point in time. Images are named by taking a hash of their contents
(metadata and content) and any change in format, content, or metadata
results in a new name. The images resource is primarily for use by cluster
administrators and integrations like the cluster image registry - end users
instead access images via the imagestreamtags or imagestreamimages
resources. While image metadata is stored in the API, any integration that
implements the container image registry API must provide its own storage
for the raw manifest data, image config, and layer contents.
=====snip==========
$ ./oc explain imagestreams
KIND: ImageStream
VERSION: image.openshift.io/v1
DESCRIPTION:
An ImageStream stores a mapping of tags to images, metadata overrides that
are applied when images are tagged in a stream, and an optional reference
to a container image repository on a registry. Users typically update the
spec.tags field to point to external images which are imported from
container registries using credentials in your namespace with the pull
secret type, or to existing image stream tags and images which are
immediately accessible for tagging or pulling. The history of images
applied to a tag is visible in the status.tags field and any user who can
view an image stream is allowed to tag that image into their own image
streams. Access to pull images from the integrated registry is granted by
having the "get imagestreams/layers" permission on a given image stream.
Users may remove a tag by deleting the imagestreamtag resource, which
causes both spec and status for that tag to be removed. Image stream
history is retained until an administrator runs the prune operation, which
removes references that are no longer in use. To preserve a historical
image, ensure there is a tag in spec pointing to that image by its digest.
=====snip==========
./oc explain imagestreamimage
KIND: ImageStreamImage
VERSION: image.openshift.io/v1
DESCRIPTION:
ImageStreamImage represents an Image that is retrieved by image name from
an ImageStream. User interfaces and regular users can use this resource to
access the metadata details of a tagged image in the image stream history
for viewing, since Image resources are not directly accessible to end
users. A not found error will be returned if no such image is referenced by
a tag within the ImageStream. Images are created when spec tags are set on
an image stream that represent an image in an external registry, when
pushing to the integrated registry, or when tagging an existing image from
one image stream to another. The name of an image stream image is in the
form "<STREAM>@<DIGEST>", where the digest is the content addressible
identifier for the image (sha256:xxxxx...). You can use ImageStreamImages
as the from.kind of an image stream spec tag to reference an image exactly.
The only operations supported on the imagestreamimage endpoint are
retrieving the image.
=====snip==========
$ ./oc explain imagestreamtags
KIND: ImageStreamTag
VERSION: image.openshift.io/v1
DESCRIPTION:
ImageStreamTag represents an Image that is retrieved by tag name from an
ImageStream. Use this resource to interact with the tags and images in an
image stream by tag, or to see the image details for a particular tag. The
image associated with this resource is the most recently successfully
tagged, imported, or pushed image (as described in the image stream
status.tags.items list for this tag). If an import is in progress or has
failed the previous image will be shown. Deleting an image stream tag
clears both the status and spec fields of an image stream. If no image can
be retrieved for a given tag, a not found error will be returned.
=====snip==========
./oc explain imagestreammapping
KIND: ImageStreamMapping
VERSION: image.openshift.io/v1
DESCRIPTION:
ImageStreamMapping represents a mapping from a single image stream tag to a
container image as well as the reference to the container image stream the
image came from. This resource is used by privileged integrators to create
an image resource and to associate it with an image stream in the status
tags field. Creating an ImageStreamMapping will allow any user who can view
the image stream to tag or pull that image, so only create mappings where
the user has proven they have access to the image contents directly. The
only operation supported for this resource is create and the metadata name
and namespace should be set to the image stream containing the tag that
should be updated.
Since the problem described in this bug report should be resolved in a recent advisory, it has been closed with a resolution of ERRATA. For information on the advisory, and where to find the updated files, follow the link below. If the solution does not work for you, open a new bug report. https://access.redhat.com/errata/RHBA-2020:0581 |