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

+++ This bug was initially created as a clone of Bug #1778534 +++

The descriptions of the objects in the image.openshift.io API group are very terse and don't convey:

1. Who the intended user of the object is
2. What are the expected scenarios the object will be used in
3. What operations are available for the object
4. What other objects are relevant for a given resource

Update the godoc.

Comment 2 XiuJuan Wang 2019-12-05 03:34:52 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",

Comment 3 XiuJuan Wang 2019-12-09 02:33:30 UTC

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.

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.

image <Object> -required-
Image associated with the ImageStream and image name.

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.

image <Object> -required-
Image is a container image.

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.

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.

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.

Comment 5 XiuJuan Wang 2019-12-11 07:38:44 UTC

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 .

Comment 7 XiuJuan Wang 2019-12-12 08:13:53 UTC

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.

Comment 9 errata-xmlrpc 2020-01-23 11:14:58 UTC

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