Bug 1778535
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: | Oleg Bulatov <obulatov> |
Status: | CLOSED ERRATA | QA Contact: | XiuJuan Wang <xiuwang> |
Severity: | high | Docs Contact: | |
Priority: | unspecified | ||
Version: | 4.3.0 | CC: | aos-bugs, jokerman, wzheng, xiuwang |
Target Milestone: | --- | ||
Target Release: | 4.3.0 | ||
Hardware: | Unspecified | ||
OS: | Unspecified | ||
Whiteboard: | |||
Fixed In Version: | Doc Type: | If docs needed, set a value | |
Doc Text: | Story Points: | --- | |
Clone Of: | 1778534 | Environment: | |
Last Closed: | 2020-01-23 11:14:58 UTC | Type: | --- |
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: | 1778534 | ||
Bug Blocks: |
Description
Clayton Coleman
2019-12-01 23:43:26 UTC
Latest 4.3.0-0.nightly-2019-12-04-214544 didn't included the fix yet. $oc version Client Version: openshift-clients-4.3.0-201910250623-77-gdf8483a7 Server Version: 4.3.0-0.nightly-2019-12-04-214544 Kubernetes Version: v1.16.2 $oc version --loglevel=8 | grep buildDate "buildDate": "2019-12-03T23:50:46Z", Get oc client from openshift-client-linux-4.3.0-0.nightly-2019-12-08-215349.tar.gz, ./oc version --loglevel=8 | grep buildDate "buildDate": "2019-12-06T13:29:47Z", ./oc version Client Version: openshift-clients-4.3.0-201910250623-85-g3fa38ed2 Server Version: 4.3.0-0.nightly-2019-12-08-190955 Kubernetes Version: v1.16.2 Still could reproduce this bug with latest client and server. $ ./oc explain image KIND: Image VERSION: image.openshift.io/v1 DESCRIPTION: Image is an immutable representation of a container image and metadata at a point in time. FIELDS: apiVersion <string> APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources dockerImageConfig <string> DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. dockerImageLayers <[]Object> -required- DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. dockerImageManifest <string> DockerImageManifest is the raw JSON of the manifest dockerImageManifestMediaType <string> DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. dockerImageMetadata <map[string]> DockerImageMetadata contains metadata about this image dockerImageMetadataVersion <string> DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" dockerImageReference <string> DockerImageReference is the string that can be used to pull this image. dockerImageSignatures <[]string> DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. kind <string> Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds metadata <Object> signatures <[]Object> Signatures holds all signatures of the image. ./oc explain imagestreams KIND: ImageStream VERSION: image.openshift.io/v1 DESCRIPTION: 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. FIELDS: apiVersion <string> APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources kind <string> Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds metadata <Object> spec <Object> -required- Spec describes the desired state of this stream status <Object> Status describes the current state of this stream ./oc explain imagestreamimage KIND: ImageStreamImage VERSION: image.openshift.io/v1 DESCRIPTION: ImageStreamImage represents an Image that is retrieved by image name from an ImageStream. FIELDS: apiVersion <string> APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources image <Object> -required- Image associated with the ImageStream and image name. kind <string> Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds metadata <Object> ./oc explain imagestreammapping KIND: ImageStreamMapping VERSION: image.openshift.io/v1 DESCRIPTION: ImageStreamMapping represents a mapping from a single tag to a container image as well as the reference to the container image stream the image came from. FIELDS: apiVersion <string> APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources image <Object> -required- Image is a container image. kind <string> Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds metadata <Object> tag <string> -required- Tag is a string value this image can be located with inside the stream. ./oc explain imagestreamtag KIND: ImageStreamTag VERSION: image.openshift.io/v1 DESCRIPTION: ImageStreamTag represents an Image that is retrieved by tag name from an ImageStream. FIELDS: apiVersion <string> APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources conditions <[]Object> conditions is an array of conditions that apply to the image stream tag. generation <integer> -required- generation is the current generation of the tagged image - if tag is provided and this value is not equal to the tag generation, a user has requested an import that has not completed, or conditions will be filled out indicating any error. image <Object> -required- image associated with the ImageStream and tag. kind <string> Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds lookupPolicy <Object> -required- lookupPolicy indicates whether this tag will handle image references in this namespace. metadata <Object> tag <Object> -required- tag is the spec tag associated with this image stream tag, and it may be null if only pushes have occurred to this image stream. Tested in env of latest payload 4.3.0-0.nightly-2019-12-11-032710, the issue still exists. Checked above PR openshift/api/pull/531/files , the zz_generated.swagger_doc_generated.go's change is not bumped into origin repo yet: https://github.com/openshift/origin/blob/release-4.3/vendor/github.com/openshift/api/image/v1/zz_generated.swagger_doc_generated.go . Test with payload 4.3.0-0.nightly-2019-12-12-021332, and pass $ oc version Client Version: v4.3.0 Server Version: 4.3.0-0.nightly-2019-12-12-021332 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 imagestream 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 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. ========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. 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:0062 |