Skip to content

Commit

Permalink
config/v1: New Release type for ClusterVersionStatus
Browse files Browse the repository at this point in the history 
This commit adds the ability to store release metadata, for example
the list of channels that a release is in:

  $ curl -sH 'Accept:application/json' 'https://api.openshift.com/api/upgrades_info/v1/graph?channel=stable-4.2' | jq -r '.nodes[] | select(.version == "4.2.4").metadata["io.openshift.upgrades.graph.release.channels"] | split(",")[]'
  candidate-4.2
  fast-4.2
  stable-4.2

That will allow the console and other downstream tooling to expose a
list of channels available to a given cluster right now, instead of
hard-coding an expected list [1].  This will account for things like
phased releases, where we may not recommend an upgrade for your
particular stable-4.2 cluster even though we are recommending the
upgrade for other stable-4.2 clusters.

Pivoting around this retyping in Go will require consumer bumps, but I
don't think it's a breaking change because the only YAML removal is
'force', which is meaningless in AvailableUpdates.  So I don't think
this needs to count as a backwards-compat-breaking schema bump.

Autogenerated bumps via:

  $ unset GOBIN  # vendor/k8s.io/code-generator/generate-groups.sh and such require "${GOPATH}/bin/deepcopy-gen"
  $ go get k8s.io/gengo/examples/deepcopy-gen
  $ hack/update-deepcopy.sh
  $ hack/update-swagger-docs.sh
  $ make update-codegen-crds

[1]: openshift/console#2935
  • Loading branch information
@wking
wking committed Jun 4, 2020
1 parent 768b700 commit ae27521
Show file tree
Hide file tree
Showing 4 changed files with 164 additions and 34 deletions.
90 changes: 64 additions & 26 deletions config/v1/0000_00_cluster-version-operator_01_clusterversion.crd.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,28 +162,47 @@ spec:
channel has been specified.
type: array
items:
description: Update represents a release of the ClusterVersionOperator,
referenced by the Image member.
description: Release represents an OpenShift release in the release
graph.
type: object
properties:
force:
description: "force allows an administrator to update to an image
that has failed verification, does not appear in the availableUpdates
list, or otherwise would be blocked by normal protections on
update. This option should only be used when the authenticity
of the provided image has been verified out of band because
the provided image will run with full administrative access
to the cluster. Do not use this flag with images that comes
from unknown or potentially malicious sources. \n This flag
does not override other forms of consistency checking that are
required before a new update is deployed."
type: boolean
additionalMetadata:
description: "additionalMetadata is additional metadata associated
with the release. Unlike the metadata property, the additionalMetadata
property contains metadata that is not covered by the release
image signatures. For example, it may contain associated channels
declared by the upstream update recommendation service. This
information is as reliable as the upstream and connection used
to retrieve it. \n Consumers who require static verification
or non-repudiation should avoid additionalMetadata and prefer
metadata. \n Consumers who prefer that security but would accept
the transitory verification provided by their upstream connection
should prefer values in metadata and fall back to additionalMetadata
if they do not find a key in metadata. \n Consumers who are
confident in their upstream connection and who do not desire
static verification or non-repudiation may wish to prefer values
in additionalMetadata and fall back to metadata if they do not
find a key in additionalMetadata. In return for the reduced
security, they can benefit from things like upstream fixes for
release images that contain an erroneous landing page."
type: object
additionalProperties:
type: string
image:
description: image is a container image location that contains
the update. When this field is part of spec, image is optional
if version is specified and the availableUpdates field contains
a matching version.
type: string
metadata:
description: Metadata is metadata associated with the release,
such as associated channels (under io.openshift.upgrades.graph.release.channels)
or a landing page (under url). This information is extracted
from within the release image, so it is covered by the same
release image signatures used to verify the image.
type: object
additionalProperties:
type: string
version:
description: version is a semantic versioning identifying the
update version. When this field is part of spec, version is
Expand Down Expand Up @@ -234,24 +253,43 @@ spec:
tag.
type: object
properties:
force:
description: "force allows an administrator to update to an image
that has failed verification, does not appear in the availableUpdates
list, or otherwise would be blocked by normal protections on update.
This option should only be used when the authenticity of the provided
image has been verified out of band because the provided image
will run with full administrative access to the cluster. Do not
use this flag with images that comes from unknown or potentially
malicious sources. \n This flag does not override other forms
of consistency checking that are required before a new update
is deployed."
type: boolean
additionalMetadata:
description: "additionalMetadata is additional metadata associated
with the release. Unlike the metadata property, the additionalMetadata
property contains metadata that is not covered by the release
image signatures. For example, it may contain associated channels
declared by the upstream update recommendation service. This information
is as reliable as the upstream and connection used to retrieve
it. \n Consumers who require static verification or non-repudiation
should avoid additionalMetadata and prefer metadata. \n Consumers
who prefer that security but would accept the transitory verification
provided by their upstream connection should prefer values in
metadata and fall back to additionalMetadata if they do not find
a key in metadata. \n Consumers who are confident in their upstream
connection and who do not desire static verification or non-repudiation
may wish to prefer values in additionalMetadata and fall back
to metadata if they do not find a key in additionalMetadata. In
return for the reduced security, they can benefit from things
like upstream fixes for release images that contain an erroneous
landing page."
type: object
additionalProperties:
type: string
image:
description: image is a container image location that contains the
update. When this field is part of spec, image is optional if
version is specified and the availableUpdates field contains a
matching version.
type: string
metadata:
description: Metadata is metadata associated with the release, such
as associated channels (under io.openshift.upgrades.graph.release.channels)
or a landing page (under url). This information is extracted
from within the release image, so it is covered by the same release
image signatures used to verify the image.
type: object
additionalProperties:
type: string
version:
description: version is a semantic versioning identifying the update
version. When this field is part of spec, version is optional
Expand Down
56 changes: 52 additions & 4 deletions config/v1/types_cluster_version.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ type ClusterVersionStatus struct {
// with the information available, which may be an image or a tag.
// +kubebuilder:validation:Required
// +required
Desired Update `json:"desired"`
Desired Release `json:"desired"`

// history contains a list of the most recent versions applied to the cluster.
// This value may be empty during cluster startup, and then will be updated
Expand Down Expand Up @@ -127,7 +127,7 @@ type ClusterVersionStatus struct {
// +nullable
// +kubebuilder:validation:Required
// +required
AvailableUpdates []Update `json:"availableUpdates"`
AvailableUpdates []Release `json:"availableUpdates"`
}

// UpdateState is a constant representing whether an update was successfully
Expand Down Expand Up @@ -221,8 +221,7 @@ type ComponentOverride struct {
// URL is a thin wrapper around string that ensures the string is a valid URL.
type URL string

// Update represents a release of the ClusterVersionOperator, referenced by the
// Image member.
// Update represents an administrator update request.
// +k8s:deepcopy-gen=true
type Update struct {
// version is a semantic versioning identifying the update version. When this
Expand Down Expand Up @@ -251,6 +250,55 @@ type Update struct {
Force bool `json:"force"`
}

// Release represents an OpenShift release in the release graph.
// +k8s:deepcopy-gen=true
type Release struct {
// version is a semantic versioning identifying the update version. When this
// field is part of spec, version is optional if image is specified.
Version string `json:"version"`

// image is a container image location that contains the update. When this
// field is part of spec, image is optional if version is specified and the
// availableUpdates field contains a matching version.
Image string `json:"image"`

// Metadata is metadata associated with the release, such
// as associated channels (under
// io.openshift.upgrades.graph.release.channels) or a landing page
// (under url). This information is extracted from within the
// release image, so it is covered by the same release image
// signatures used to verify the image.
//
// +optional
Metadata map[string]string `json:"metadata,omitempty"`

// additionalMetadata is additional metadata associated with the
// release. Unlike the metadata property, the additionalMetadata
// property contains metadata that is not covered by the release
// image signatures. For example, it may contain associated
// channels declared by the upstream update recommendation service.
// This information is as reliable as the upstream and connection used
// to retrieve it.
//
// Consumers who require static verification or
// non-repudiation should avoid additionalMetadata and prefer metadata.
//
// Consumers who prefer that security but would accept the transitory
// verification provided by their upstream connection should prefer
// values in metadata and fall back to additionalMetadata if they do
// not find a key in metadata.
//
// Consumers who are confident in their upstream connection and who do
// not desire static verification or non-repudiation may wish to prefer
// values in additionalMetadata and fall back to metadata if they do
// not find a key in additionalMetadata. In return for the reduced
// security, they can benefit from things like upstream fixes for
// release images that contain an erroneous landing page.
//
// +optional
AdditionalMetadata map[string]string `json:"additionalMetadata,omitempty"`
}

// RetrievedUpdates reports whether available updates have been retrieved from
// the upstream update server. The condition is Unknown before retrieval, False
// if the updates could not be retrieved or recently failed, or True if the
Expand Down
38 changes: 35 additions & 3 deletions config/v1/zz_generated.deepcopy.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

14 changes: 13 additions & 1 deletion config/v1/zz_generated.swagger_doc_generated.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit ae27521

Please sign in to comment.