Skip to content

Commit

Permalink
🌱 Align ClusterCatalog API godoc with OpenShift API conventions (#390)
Browse files Browse the repository at this point in the history 
* Update godoc strings for ClusterCatalog API

Signed-off-by: Per Goncalves da Silva <[email protected]>

* Regenerate manifests

Signed-off-by: Per Goncalves da Silva <[email protected]>

* Apply suggestions from code review

Text fixes

Co-authored-by: Bryce Palmer <[email protected]>

* Address reviewer comments

Signed-off-by: Per Goncalves da Silva <[email protected]>

* Update api/core/v1alpha1/clustercatalog_types.go

Co-authored-by: Bryce Palmer <[email protected]>

* Apply suggestions from code review

Co-authored-by: Joe Lanford <[email protected]>
Signed-off-by: Per Goncalves da Silva <[email protected]>

---------

Signed-off-by: Per Goncalves da Silva <[email protected]>
Co-authored-by: Per Goncalves da Silva <[email protected]>
Co-authored-by: Bryce Palmer <[email protected]>
Co-authored-by: Joe Lanford <[email protected]>
  • Loading branch information
@perdasilva @everettraven @joelanford
4 people authored Sep 16, 2024
1 parent ffdb9c3 commit 542fc80
Show file tree
Hide file tree
Showing 2 changed files with 183 additions and 60 deletions.
118 changes: 89 additions & 29 deletions api/core/v1alpha1/clustercatalog_types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// SourceType defines the type of source used for catalogs.
// +enum
type SourceType string

Expand All @@ -45,13 +46,13 @@ const (
//+kubebuilder:printcolumn:name=LastUnpacked,type=date,JSONPath=`.status.lastUnpacked`
//+kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp`

// ClusterCatalog is the Schema for the ClusterCatalogs API
// ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster.
// For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
type ClusterCatalog struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata"`

Spec ClusterCatalogSpec `json:"spec"`
// +optional
Spec ClusterCatalogSpec `json:"spec"`
Status ClusterCatalogStatus `json:"status,omitempty"`
}

Expand All @@ -68,82 +69,141 @@ type ClusterCatalogList struct {
// ClusterCatalogSpec defines the desired state of ClusterCatalog
// +kubebuilder:validation:XValidation:rule="!has(self.source.image.pollInterval) || (self.source.image.ref.find('@sha256:') == \"\")",message="cannot specify PollInterval while using digest-based image"
type ClusterCatalogSpec struct {
// source is the source of a Catalog that contains catalog metadata in the FBC format
// https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
// source is a required field that allows the user to define the source of a Catalog that contains catalog metadata in the File-Based Catalog (FBC) format.
//
// Below is a minimal example of a ClusterCatalogSpec that sources a catalog from an image:
//
// source:
// type: image
// image:
// ref: quay.io/operatorhubio/catalog:latest
//
// For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
Source CatalogSource `json:"source"`

// priority is used as the tie-breaker between bundles selected from different catalogs; a higher number means higher priority.
// priority is an optional field that allows the user to define a priority for a ClusterCatalog.
// A ClusterCatalog's priority is used by clients as a tie-breaker between ClusterCatalogs that meet the client's requirements.
// For example, in the case where multiple ClusterCatalogs provide the same bundle.
// A higher number means higher priority. Negative number as also accepted.
// When omitted, the default priority is 0.
// +kubebuilder:default:=0
// +optional
Priority int32 `json:"priority,omitempty"`
}

// ClusterCatalogStatus defines the observed state of ClusterCatalog
type ClusterCatalogStatus struct {
// conditions store the status conditions of the ClusterCatalog instances
// conditions is a representation of the current state for this ClusterCatalog.
// The status is represented by a set of "conditions".
//
// Each condition is generally structured in the following format:
// - Type: a string representation of the condition type. More or less the condition "name".
// - Status: a string representation of the state of the condition. Can be one of ["True", "False", "Unknown"].
// - Reason: a string representation of the reason for the current state of the condition. Typically useful for building automation around particular Type+Reason combinations.
// - Message: a human-readable message that further elaborates on the state of the condition.
//
// The current set of condition types are:
// - "Unpacked", epresents whether, or not, the catalog contents have been successfully unpacked.
// - "Deleted", represents whether, or not, the catalog contents have been successfully deleted.
//
// The current set of reasons are:
// - "UnpackPending", this reason is set on the "Unpack" condition when unpacking the catalog has not started.
// - "Unpacking", this reason is set on the "Unpack" condition when the catalog is being unpacked.
// - "UnpackSuccessful", this reason is set on the "Unpack" condition when unpacking the catalog is successful and the catalog metadata is available to the cluster.
// - "FailedToStore", this reason is set on the "Unpack" condition when an error has been encountered while storing the contents of the catalog.
// - "FailedToDelete", this reason is set on the "Delete" condition when an error has been encountered while deleting the contents of the catalog.
//
// +optional
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

// resolvedSource contains information about the resolved source
// resolvedSource contains information about the resolved source based on the source type.
//
// Below is an example of a resolved source for an image source:
// resolvedSource:
//
// image:
// lastPollAttempt: "2024-09-10T12:22:13Z"
// lastUnpacked: "2024-09-10T12:22:13Z"
// ref: quay.io/operatorhubio/catalog:latest
// resolvedRef: quay.io/operatorhubio/catalog@sha256:c7392b4be033da629f9d665fec30f6901de51ce3adebeff0af579f311ee5cf1b
// type: image
// +optional
ResolvedSource *ResolvedCatalogSource `json:"resolvedSource,omitempty"`
// contentURL is a cluster-internal address that on-cluster components
// can read the content of a catalog from
// contentURL is a cluster-internal URL from which on-cluster components
// can read the content of a catalog
// +optional
ContentURL string `json:"contentURL,omitempty"`
// observedGeneration is the most recent generation observed for this ClusterCatalog. It corresponds to the
// ClusterCatalog's generation, which is updated on mutation by the API Server.
// +optional
ObservedGeneration int64 `json:"observedGeneration,omitempty"`

// LastUnpacked represents the time when the
// lastUnpacked represents the time when the
// ClusterCatalog object was last unpacked.
// +optional
LastUnpacked metav1.Time `json:"lastUnpacked,omitempty"`
}

// CatalogSource contains the sourcing information for a Catalog
// CatalogSource is a discriminated union of possible sources for a Catalog.
type CatalogSource struct {
// type defines the kind of Catalog content being sourced.
// type is a required reference to the type of source the catalog is sourced from.
//
// Allowed values are ["image"]
//
// When this field is set to "image", the ClusterCatalog content will be sourced from an OCI image.
// When using an image source, the image field must be set and must be the only field defined for this type.
//
// +unionDiscriminator
// +kubebuilder:validation:Enum:="image"
// +kubebuilder:validation:Required
Type SourceType `json:"type"`
// image is the catalog image that backs the content of this catalog.
// image is used to configure how catalog contents are sourced from an OCI image. This field must be set when type is set to "image" and must be the only field defined for this type.
// +optional
Image *ImageSource `json:"image,omitempty"`
}

// ResolvedCatalogSource contains the information about a sourced Catalog
// ResolvedCatalogSource is a discriminated union of resolution information for a Catalog.
type ResolvedCatalogSource struct {
// type defines the kind of Catalog content that was sourced.
// type is a reference to the type of source the catalog is sourced from.
//
// It will be set to one of the following values: ["image"].
//
// When this field is set to "image", information about the resolved image source will be set in the 'image' field.
//
// +unionDiscriminator
// +kubebuilder:validation:Enum:="image"
// +kubebuilder:validation:Required
Type SourceType `json:"type"`
// image is the catalog image that backs the content of this catalog.
// image is a field containing resolution information for a catalog sourced from an image.
Image *ResolvedImageSource `json:"image"`
}

// ResolvedImageSource contains information about the sourced Catalog
// ResolvedImageSource provides information about the resolved source of a Catalog sourced from an image.
type ResolvedImageSource struct {
// ref contains the reference to a container image containing Catalog contents.
// ref is the reference to a container image containing Catalog contents.
Ref string `json:"ref"`
// resolvedRef contains the resolved sha256 image ref containing Catalog contents.
// resolvedRef is the resolved sha256 image ref containing Catalog contents.
ResolvedRef string `json:"resolvedRef"`
// lastPollAtempt is the time when the source resolved was last polled for new content.
// lastPollAttempt is the time when the source image was last polled for new content.
LastPollAttempt metav1.Time `json:"lastPollAttempt"`
// LastUnpacked is the time when the catalog contents were successfully unpacked.
// lastUnpacked is the last time when the Catalog contents were successfully unpacked.
LastUnpacked metav1.Time `json:"lastUnpacked"`
}

// ImageSource contains information required for sourcing a Catalog from an OCI image
// ImageSource enables users to define the information required for sourcing a Catalog from an OCI image
type ImageSource struct {
// ref contains the reference to a container image containing Catalog contents.
// ref is a required field that allows the user to define the reference to a container image containing Catalog contents.
// Examples:
// ref: quay.io/operatorhubio/catalog:latest # image reference
// ref: quay.io/operatorhubio/catalog@sha256:c7392b4be033da629f9d665fec30f6901de51ce3adebeff0af579f311ee5cf1b # image reference with sha256 digest
Ref string `json:"ref"`
// pollInterval indicates the interval at which the image source should be polled for new content,
// specified as a duration (e.g., "5m", "1h", "24h", "etc".). Note that PollInterval may not be
// specified for a catalog image referenced by a sha256 digest.
// pollInterval is an optional field that allows the user to set the interval at which the image source should be polled for new content.
// It must be specified as a duration.
// It must not be specified for a catalog image referenced by a sha256 digest.
// Examples:
// pollInterval: 1h # poll the image source every hour
// pollInterval: 30m # poll the image source every 30 minutes
// pollInterval: 1h30m # poll the image source every 1 hour and 30 minutes
//
// When omitted, the image will not be polled for new content.
// +kubebuilder:validation:Format:=duration
// +optional
PollInterval *metav1.Duration `json:"pollInterval,omitempty"`
Expand Down
Loading

0 comments on commit 542fc80

Please sign in to comment.