Bug 1778535 - Improve API descriptions of important user facing objects for API explorer and oc explain
Summary: Improve API descriptions of important user facing objects for API explorer an...
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: ImageStreams
Version: 4.3.0
Hardware: Unspecified
OS: Unspecified
unspecified
high
Target Milestone: ---
: 4.3.0
Assignee: Oleg Bulatov
QA Contact: XiuJuan Wang
URL:
Whiteboard:
Depends On: 1778534
Blocks:
TreeView+ depends on / blocked
 
Reported: 2019-12-01 23:43 UTC by Clayton Coleman
Modified: 2020-01-23 11:14 UTC (History)
4 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of: 1778534
Environment:
Last Closed: 2020-01-23 11:14:58 UTC
Target Upstream Version:


Attachments (Terms of Use)


Links
System ID Private Priority Status Summary Last Updated
Github openshift api pull 531 0 'None' 'closed' 'Bug 1778535: Improve API documentation for image types' 2019-12-06 06:12:49 UTC
Github openshift cluster-config-operator pull 109 0 'None' 'open' '[release-4.3] Bug 1778535: use api branch release-4.3' 2019-12-09 14:57:44 UTC
Github openshift origin pull 24283 0 None None None 2019-12-11 10:08:48 UTC

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.

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.

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


Note You need to log in before you can comment on or make changes to this bug.