diff --git a/olm/catalogd/v1alpha1/clustercatalog_crd.yaml b/olm/catalogd/v1alpha1/clustercatalog_crd.yaml new file mode 100644 index 00000000000..a3a10dc991c --- /dev/null +++ b/olm/catalogd/v1alpha1/clustercatalog_crd.yaml @@ -0,0 +1,297 @@ +--- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + annotations: + controller-gen.kubebuilder.io/version: v0.16.1 + name: clustercatalogs.olm.operatorframework.io +spec: + group: olm.operatorframework.io + names: + kind: ClusterCatalog + listKind: ClusterCatalogList + plural: clustercatalogs + singular: clustercatalog + scope: Cluster + versions: + - additionalPrinterColumns: + - jsonPath: .status.lastUnpacked + name: LastUnpacked + type: date + - jsonPath: .status.conditions[?(@.type=="Serving")].status + name: Serving + type: string + - jsonPath: .metadata.creationTimestamp + name: Age + type: date + name: v1alpha1 + schema: + openAPIV3Schema: + description: |- + 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 + properties: + apiVersion: + description: |- + 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 + type: string + kind: + description: |- + 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 + type: string + metadata: + type: object + spec: + description: ClusterCatalogSpec defines the desired state of ClusterCatalog + properties: + availability: + default: Enabled + description: |- + Availability is an optional field that allows users to define whether the ClusterCatalog is utilized by the operator-controller. + + Allowed values are : ["Enabled", "Disabled"]. + If set to "Enabled", the catalog will be used for updates, serving contents, and package installations. + + If set to "Disabled", catalogd will stop serving the catalog and the cached data will be removed. + + If unspecified, the default value is "Enabled" + enum: + - Disabled + - Enabled + type: string + priority: + default: 0 + description: |- + 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 numbers are also accepted. + When omitted, the default priority is 0. + format: int32 + type: integer + source: + description: |- + 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 + properties: + image: + description: 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. + properties: + pollInterval: + description: |- + 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. + format: duration + type: string + ref: + description: |- + 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 + type: string + required: + - ref + type: object + type: + description: |- + 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. + enum: + - Image + type: string + required: + - type + type: object + x-kubernetes-validations: + - message: source type 'Image' requires image field + rule: self.type == 'Image' && has(self.image) + required: + - source + type: object + x-kubernetes-validations: + - message: cannot specify PollInterval while using digest-based image + rule: '!has(self.source.image.pollInterval) || (self.source.image.ref.find(''@sha256:'') + == "")' + status: + description: ClusterCatalogStatus defines the observed state of ClusterCatalog + properties: + conditions: + description: |- + 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: + - "Serving", which represents whether or not the contents of the catalog are being served via the HTTP(S) web server. + - "Progressing", which represents whether or not the ClusterCatalog is progressing towards a new state. + + The current set of reasons are: + - "Succeeded", this reason is set on the "Progressing" condition when progressing to a new state is successful. + - "Blocked", this reason is set on the "Progressing" condition when the ClusterCatalog controller has encountered an error that requires manual intervention for recovery. + - "Retrying", this reason is set on the "Progressing" condition when the ClusterCatalog controller has encountered an error that might be resolvable on subsequent reconciliation attempts. + - "Available", this reason is set on the "Serving" condition when the contents of the ClusterCatalog are being served via an endpoint on the HTTP(S) web server. + - "Unavailable", this reason is set on the "Serving" condition when there is not an endpoint on the HTTP(S) web server that is serving the contents of the ClusterCatalog. + items: + description: Condition contains details for one aspect of the current + state of this API Resource. + properties: + lastTransitionTime: + description: |- + lastTransitionTime is the last time the condition transitioned from one status to another. + This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + format: date-time + type: string + message: + description: |- + message is a human readable message indicating details about the transition. + This may be an empty string. + maxLength: 32768 + type: string + observedGeneration: + description: |- + observedGeneration represents the .metadata.generation that the condition was set based upon. + For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date + with respect to the current state of the instance. + format: int64 + minimum: 0 + type: integer + reason: + description: |- + reason contains a programmatic identifier indicating the reason for the condition's last transition. + Producers of specific condition types may define expected values and meanings for this field, + and whether the values are considered a guaranteed API. + The value should be a CamelCase string. + This field may not be empty. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: type of condition in CamelCase or in foo.example.com/CamelCase. + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + lastUnpacked: + description: |- + lastUnpacked represents the time when the + ClusterCatalog object was last unpacked successfully. + format: date-time + type: string + resolvedSource: + description: |- + 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: + lastSuccessfulPollAttempt: "2024-09-10T12:22:13Z" + ref: quay.io/operatorhubio/catalog@sha256:c7392b4be033da629f9d665fec30f6901de51ce3adebeff0af579f311ee5cf1b + type: Image + properties: + image: + description: image is a field containing resolution information + for a catalog sourced from an image. + properties: + lastSuccessfulPollAttempt: + description: lastSuccessfulPollAttempt is the time when the + resolved source was last successfully polled for new content. + format: date-time + type: string + ref: + description: ref contains the resolved sha256 image ref containing + Catalog contents. + type: string + required: + - lastSuccessfulPollAttempt + - ref + type: object + type: + description: |- + 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. + enum: + - Image + type: string + required: + - image + - type + type: object + x-kubernetes-validations: + - message: source type 'Image' requires image field + rule: self.type == 'Image' && has(self.image) + urls: + description: urls contains the URLs that can be used to access the + catalog. + properties: + base: + description: |- + base is a required cluster-internal URL which provides API access for this ClusterCatalog. + A suffix API access path can be added to retrieve catalog data for the ClusterCatalog. + Currently, a 'v1' API access provides complete FBC retrival via the path "/api/v1/all", with the general form `{base}/api/v1/all`. + type: string + required: + - base + type: object + type: object + required: + - metadata + - spec + type: object + served: true + storage: true + subresources: + status: {} diff --git a/olm/catalogd/v1alpha1/clustercatalog_types.go b/olm/catalogd/v1alpha1/clustercatalog_types.go new file mode 100644 index 00000000000..830c9218d08 --- /dev/null +++ b/olm/catalogd/v1alpha1/clustercatalog_types.go @@ -0,0 +1,223 @@ +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +) + +// SourceType defines the type of source used for catalogs. +// +enum +type SourceType string + +const ( + SourceTypeImage SourceType = "Image" + + TypeProgressing = "Progressing" + TypeServing = "Serving" + + // Serving reasons + ReasonAvailable = "Available" + ReasonUnavailable = "Unavailable" + ReasonDisabled = "Disabled" + + // Progressing reasons + ReasonSucceeded = "Succeeded" + ReasonRetrying = "Retrying" + ReasonBlocked = "Blocked" + + MetadataNameLabel = "olm.operatorframework.io/metadata.name" + + AvailabilityEnabled = "Enabled" + AvailabilityDisabled = "Disabled" +) + +//+kubebuilder:object:root=true +//+kubebuilder:resource:scope=Cluster +//+kubebuilder:subresource:status +//+kubebuilder:printcolumn:name=LastUnpacked,type=date,JSONPath=`.status.lastUnpacked` +//+kubebuilder:printcolumn:name="Serving",type=string,JSONPath=`.status.conditions[?(@.type=="Serving")].status` +//+kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp` + +// 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"` + Status ClusterCatalogStatus `json:"status,omitempty"` +} + +//+kubebuilder:object:root=true + +// ClusterCatalogList contains a list of ClusterCatalog +type ClusterCatalogList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata"` + + Items []ClusterCatalog `json:"items"` +} + +// 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 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 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 numbers are also accepted. + // When omitted, the default priority is 0. + // +kubebuilder:default:=0 + // +optional + Priority int32 `json:"priority"` + + // Availability is an optional field that allows users to define whether the ClusterCatalog is utilized by the operator-controller. + // + // Allowed values are : ["Enabled", "Disabled"]. + // If set to "Enabled", the catalog will be used for updates, serving contents, and package installations. + // + // If set to "Disabled", catalogd will stop serving the catalog and the cached data will be removed. + // + // If unspecified, the default value is "Enabled" + // + // +kubebuilder:validation:Enum="Disabled";"Enabled" + // +kubebuilder:default="Enabled" + // +optional + Availability string `json:"availability,omitempty"` +} + +// ClusterCatalogStatus defines the observed state of ClusterCatalog +type ClusterCatalogStatus struct { + // 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: + // - "Serving", which represents whether or not the contents of the catalog are being served via the HTTP(S) web server. + // - "Progressing", which represents whether or not the ClusterCatalog is progressing towards a new state. + // + // The current set of reasons are: + // - "Succeeded", this reason is set on the "Progressing" condition when progressing to a new state is successful. + // - "Blocked", this reason is set on the "Progressing" condition when the ClusterCatalog controller has encountered an error that requires manual intervention for recovery. + // - "Retrying", this reason is set on the "Progressing" condition when the ClusterCatalog controller has encountered an error that might be resolvable on subsequent reconciliation attempts. + // - "Available", this reason is set on the "Serving" condition when the contents of the ClusterCatalog are being served via an endpoint on the HTTP(S) web server. + // - "Unavailable", this reason is set on the "Serving" condition when there is not an endpoint on the HTTP(S) web server that is serving the contents of the ClusterCatalog. + // + // +optional + Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` + // 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: + // lastSuccessfulPollAttempt: "2024-09-10T12:22:13Z" + // ref: quay.io/operatorhubio/catalog@sha256:c7392b4be033da629f9d665fec30f6901de51ce3adebeff0af579f311ee5cf1b + // type: Image + // +optional + ResolvedSource *ResolvedCatalogSource `json:"resolvedSource,omitempty"` + // urls contains the URLs that can be used to access the catalog. + // +optional + URLs *ClusterCatalogURLs `json:"urls,omitempty"` + // lastUnpacked represents the time when the + // ClusterCatalog object was last unpacked successfully. + // +optional + LastUnpacked metav1.Time `json:"lastUnpacked,omitempty"` +} + +// ClusterCatalogURLs contains the URLs that can be used to access the catalog. +type ClusterCatalogURLs struct { + // base is a required cluster-internal URL which provides API access for this ClusterCatalog. + // A suffix API access path can be added to retrieve catalog data for the ClusterCatalog. + // Currently, a 'v1' API access provides complete FBC retrival via the path "/api/v1/all", with the general form `{base}/api/v1/all`. + // +kubebuilder:validation:Required + Base string `json:"base"` +} + +// CatalogSource is a discriminated union of possible sources for a Catalog. +// CatalogSource contains the sourcing information for a Catalog +// +union +// +kubebuilder:validation:XValidation:rule="self.type == 'Image' && has(self.image)",message="source type 'Image' requires image field" +type CatalogSource struct { + // 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 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 is a discriminated union of resolution information for a Catalog. +// ResolvedCatalogSource contains the information about a sourced Catalog +// +union +// +kubebuilder:validation:XValidation:rule="self.type == 'Image' && has(self.image)",message="source type 'Image' requires image field" +type ResolvedCatalogSource struct { + // 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 a field containing resolution information for a catalog sourced from an image. + Image *ResolvedImageSource `json:"image"` +} + +// ResolvedImageSource provides information about the resolved source of a Catalog sourced from an image. +type ResolvedImageSource struct { + // ref contains the resolved sha256 image ref containing Catalog contents. + Ref string `json:"ref"` + // lastSuccessfulPollAttempt is the time when the resolved source was last successfully polled for new content. + LastSuccessfulPollAttempt metav1.Time `json:"lastSuccessfulPollAttempt"` +} + +// ImageSource enables users to define the information required for sourcing a Catalog from an OCI image +type ImageSource struct { + // 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 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"` +} + +func init() { + SchemeBuilder.Register(&ClusterCatalog{}, &ClusterCatalogList{}) +} diff --git a/olm/catalogd/v1alpha1/groupversion_info.go b/olm/catalogd/v1alpha1/groupversion_info.go new file mode 100644 index 00000000000..0135abc67d7 --- /dev/null +++ b/olm/catalogd/v1alpha1/groupversion_info.go @@ -0,0 +1,20 @@ +// Package v1alpha1 contains API Schema definitions for the olm v1alpha1 API group +// +kubebuilder:object:generate=true +// +groupName=olm.operatorframework.io +package v1alpha1 + +import ( + "k8s.io/apimachinery/pkg/runtime/schema" + "sigs.k8s.io/controller-runtime/pkg/scheme" +) + +var ( + // GroupVersion is group version used to register these objects + GroupVersion = schema.GroupVersion{Group: "olm.operatorframework.io", Version: "v1alpha1"} + + // SchemeBuilder is used to add go types to the GroupVersionKind scheme + SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion} + + // AddToScheme adds the types in this group-version to the given scheme. + AddToScheme = SchemeBuilder.AddToScheme +) diff --git a/olm/operator-controller/v1alpha1/clusterextension_crd.yaml b/olm/operator-controller/v1alpha1/clusterextension_crd.yaml new file mode 100644 index 00000000000..61b81606bf7 --- /dev/null +++ b/olm/operator-controller/v1alpha1/clusterextension_crd.yaml @@ -0,0 +1,582 @@ +--- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + annotations: + controller-gen.kubebuilder.io/version: v0.16.1 + name: clusterextensions.olm.operatorframework.io +spec: + group: olm.operatorframework.io + names: + kind: ClusterExtension + listKind: ClusterExtensionList + plural: clusterextensions + singular: clusterextension + scope: Cluster + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + description: ClusterExtension is the Schema for the clusterextensions API + properties: + apiVersion: + description: |- + 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 + type: string + kind: + description: |- + 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 + type: string + metadata: + type: object + spec: + description: ClusterExtensionSpec defines the desired state of ClusterExtension + properties: + install: + description: |- + install is a required field used to configure the installation options + for the ClusterExtension such as the installation namespace, + the service account and the pre-flight check configuration. + + Below is a minimal example of an installation definition (in yaml): + install: + namespace: example-namespace + serviceAccount: + name: example-sa + properties: + namespace: + description: |- + namespace is a reference to the Namespace in which the bundle of + content for the package referenced in the packageName field will be applied. + The bundle may contain cluster-scoped resources or resources that are + applied to other Namespaces. This Namespace is expected to exist. + + namespace is required, immutable, and follows the DNS label standard + as defined in [RFC 1123]. This means that valid values: + - Contain no more than 63 characters + - Contain only lowercase alphanumeric characters or '-' + - Start with an alphanumeric character + - End with an alphanumeric character + + Some examples of valid values are: + - some-namespace + - 123-namespace + - 1-namespace-2 + - somenamespace + + Some examples of invalid values are: + - -some-namespace + - some-namespace- + - thisisareallylongnamespacenamethatisgreaterthanthemaximumlength + - some.namespace + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 + maxLength: 63 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ + type: string + x-kubernetes-validations: + - message: namespace is immutable + rule: self == oldSelf + preflight: + description: |- + preflight is an optional field that can be used to configure the preflight checks run before installation or upgrade of the content for the package specified in the packageName field. + + When specified, it overrides the default configuration of the preflight checks that are required to execute successfully during an install/upgrade operation. + + When not specified, the default configuration for each preflight check will be used. + properties: + crdUpgradeSafety: + description: |- + crdUpgradeSafety is used to configure the CRD Upgrade Safety pre-flight + checks that run prior to upgrades of installed content. + + The CRD Upgrade Safety pre-flight check safeguards from unintended + consequences of upgrading a CRD, such as data loss. + + This field is required if the spec.install.preflight field is specified. + properties: + policy: + default: Enabled + description: |- + policy is used to configure the state of the CRD Upgrade Safety pre-flight check. + + This field is required when the spec.install.preflight.crdUpgradeSafety field is + specified. + + Allowed values are ["Enabled", "Disabled"]. The default value is "Enabled". + + When set to "Disabled", the CRD Upgrade Safety pre-flight check will be skipped + when performing an upgrade operation. This should be used with caution as + unintended consequences such as data loss can occur. + + When set to "Enabled", the CRD Upgrade Safety pre-flight check will be run when + performing an upgrade operation. + enum: + - Enabled + - Disabled + type: string + required: + - policy + type: object + required: + - crdUpgradeSafety + type: object + x-kubernetes-validations: + - message: at least one of [crdUpgradeSafety] are required when + preflight is specified + rule: has(self.crdUpgradeSafety) + serviceAccount: + description: |- + serviceAccount is a required reference to a ServiceAccount that exists + in the installNamespace. The provided ServiceAccount is used to install and + manage the content for the package specified in the packageName field. + + In order to successfully install and manage the content for the package, + the ServiceAccount provided via this field should be configured with the + appropriate permissions to perform the necessary operations on all the + resources that are included in the bundle of content being applied. + properties: + name: + description: |- + name is a required, immutable reference to the name of the ServiceAccount + to be used for installation and management of the content for the package + specified in the packageName field. + + This ServiceAccount is expected to exist in the installNamespace. + + This field follows the DNS subdomain name standard as defined in [RFC + 1123]. This means that valid values: + - Contain no more than 253 characters + - Contain only lowercase alphanumeric characters, '-', or '.' + - Start with an alphanumeric character + - End with an alphanumeric character + + Some examples of valid values are: + - some-serviceaccount + - 123-serviceaccount + - 1-serviceaccount-2 + - someserviceaccount + - some.serviceaccount + + Some examples of invalid values are: + - -some-serviceaccount + - some-serviceaccount- + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 + maxLength: 253 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + x-kubernetes-validations: + - message: name is immutable + rule: self == oldSelf + required: + - name + type: object + required: + - namespace + - serviceAccount + type: object + source: + description: |- + source is a required field which selects the installation source of content + for this ClusterExtension. Selection is performed by setting the sourceType. + + Catalog is currently the only implemented sourceType, and setting the + sourcetype to "Catalog" requires the catalog field to also be defined. + + Below is a minimal example of a source definition (in yaml): + + source: + sourceType: Catalog + catalog: + packageName: example-package + properties: + catalog: + description: |- + catalog is used to configure how information is sourced from a catalog. This field must be defined when sourceType is set to "Catalog", + and must be the only field defined for this sourceType. + properties: + channels: + description: |- + channels is an optional reference to a set of channels belonging to + the package specified in the packageName field. + + A "channel" is a package author defined stream of updates for an extension. + + When specified, it is used to constrain the set of installable bundles and + the automated upgrade path. This constraint is an AND operation with the + version field. For example: + - Given channel is set to "foo" + - Given version is set to ">=1.0.0, <1.5.0" + - Only bundles that exist in channel "foo" AND satisfy the version range comparison will be considered installable + - Automatic upgrades will be constrained to upgrade edges defined by the selected channel + + When unspecified, upgrade edges across all channels will be used to identify valid automatic upgrade paths. + + This field follows the DNS subdomain name standard as defined in [RFC + 1123]. This means that valid entries: + - Contain no more than 253 characters + - Contain only lowercase alphanumeric characters, '-', or '.' + - Start with an alphanumeric character + - End with an alphanumeric character + + Some examples of valid values are: + - 1.1.x + - alpha + - stable + - stable-v1 + - v1-stable + - dev-preview + - preview + - community + + Some examples of invalid values are: + - -some-channel + - some-channel- + - thisisareallylongchannelnamethatisgreaterthanthemaximumlength + - original_40 + - --default-channel + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 + items: + maxLength: 253 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + type: array + packageName: + description: |- + packageName is a reference to the name of the package to be installed + and is used to filter the content from catalogs. + + This field is required, immutable and follows the DNS subdomain name + standard as defined in [RFC 1123]. This means that valid entries: + - Contain no more than 253 characters + - Contain only lowercase alphanumeric characters, '-', or '.' + - Start with an alphanumeric character + - End with an alphanumeric character + + Some examples of valid values are: + - some-package + - 123-package + - 1-package-2 + - somepackage + + Some examples of invalid values are: + - -some-package + - some-package- + - thisisareallylongpackagenamethatisgreaterthanthemaximumlength + - some.package + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 + maxLength: 253 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + x-kubernetes-validations: + - message: packageName is immutable + rule: self == oldSelf + selector: + description: |- + selector is an optional field that can be used + to filter the set of ClusterCatalogs used in the bundle + selection process. + + When unspecified, all ClusterCatalogs will be used in + the bundle selection process. + properties: + matchExpressions: + description: matchExpressions is a list of label selector + requirements. The requirements are ANDed. + items: + description: |- + A label selector requirement is a selector that contains values, a key, and an operator that + relates the key and values. + properties: + key: + description: key is the label key that the selector + applies to. + type: string + operator: + description: |- + operator represents a key's relationship to a set of values. + Valid operators are In, NotIn, Exists and DoesNotExist. + type: string + values: + description: |- + values is an array of string values. If the operator is In or NotIn, + the values array must be non-empty. If the operator is Exists or DoesNotExist, + the values array must be empty. This array is replaced during a strategic + merge patch. + items: + type: string + type: array + x-kubernetes-list-type: atomic + required: + - key + - operator + type: object + type: array + x-kubernetes-list-type: atomic + matchLabels: + additionalProperties: + type: string + description: |- + matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels + map is equivalent to an element of matchExpressions, whose key field is "key", the + operator is "In", and the values array contains only "value". The requirements are ANDed. + type: object + type: object + x-kubernetes-map-type: atomic + upgradeConstraintPolicy: + default: CatalogProvided + description: |- + upgradeConstraintPolicy is an optional field that controls whether + the upgrade path(s) defined in the catalog are enforced for the package + referenced in the packageName field. + + Allowed values are: ["CatalogProvided", "SelfCertified"]. + + When this field is set to "CatalogProvided", automatic upgrades will only occur + when upgrade constraints specified by the package author are met. + + When this field is set to "SelfCertified", the upgrade constraints specified by + the package author are ignored. This allows for upgrades and downgrades to + any version of the package. This is considered a dangerous operation as it + can lead to unknown and potentially disastrous outcomes, such as data + loss. It is assumed that users have independently verified changes when + using this option. + + If unspecified, the default value is "CatalogProvided". + enum: + - CatalogProvided + - SelfCertified + type: string + version: + description: |- + version is an optional semver constraint (a specific version or range of versions). When unspecified, the latest version available will be installed. + + Acceptable version ranges are no longer than 64 characters. + Version ranges are composed of comma- or space-delimited values and one or + more comparison operators, known as comparison strings. Additional + comparison strings can be added using the OR operator (||). + + # Range Comparisons + + To specify a version range, you can use a comparison string like ">=3.0, + <3.6". When specifying a range, automatic updates will occur within that + range. The example comparison string means "install any version greater than + or equal to 3.0.0 but less than 3.6.0.". It also states intent that if any + upgrades are available within the version range after initial installation, + those upgrades should be automatically performed. + + # Pinned Versions + + To specify an exact version to install you can use a version range that + "pins" to a specific version. When pinning to a specific version, no + automatic updates will occur. An example of a pinned version range is + "0.6.0", which means "only install version 0.6.0 and never + upgrade from this version". + + # Basic Comparison Operators + + The basic comparison operators and their meanings are: + - "=", equal (not aliased to an operator) + - "!=", not equal + - "<", less than + - ">", greater than + - ">=", greater than OR equal to + - "<=", less than OR equal to + + # Wildcard Comparisons + + You can use the "x", "X", and "*" characters as wildcard characters in all + comparison operations. Some examples of using the wildcard characters: + - "1.2.x", "1.2.X", and "1.2.*" is equivalent to ">=1.2.0, < 1.3.0" + - ">= 1.2.x", ">= 1.2.X", and ">= 1.2.*" is equivalent to ">= 1.2.0" + - "<= 2.x", "<= 2.X", and "<= 2.*" is equivalent to "< 3" + - "x", "X", and "*" is equivalent to ">= 0.0.0" + + # Patch Release Comparisons + + When you want to specify a minor version up to the next major version you + can use the "~" character to perform patch comparisons. Some examples: + - "~1.2.3" is equivalent to ">=1.2.3, <1.3.0" + - "~1" and "~1.x" is equivalent to ">=1, <2" + - "~2.3" is equivalent to ">=2.3, <2.4" + - "~1.2.x" is equivalent to ">=1.2.0, <1.3.0" + + # Major Release Comparisons + + You can use the "^" character to make major release comparisons after a + stable 1.0.0 version is published. If there is no stable version published, // minor versions define the stability level. Some examples: + - "^1.2.3" is equivalent to ">=1.2.3, <2.0.0" + - "^1.2.x" is equivalent to ">=1.2.0, <2.0.0" + - "^2.3" is equivalent to ">=2.3, <3" + - "^2.x" is equivalent to ">=2.0.0, <3" + - "^0.2.3" is equivalent to ">=0.2.3, <0.3.0" + - "^0.2" is equivalent to ">=0.2.0, <0.3.0" + - "^0.0.3" is equvalent to ">=0.0.3, <0.0.4" + - "^0.0" is equivalent to ">=0.0.0, <0.1.0" + - "^0" is equivalent to ">=0.0.0, <1.0.0" + + # OR Comparisons + You can use the "||" character to represent an OR operation in the version + range. Some examples: + - ">=1.2.3, <2.0.0 || >3.0.0" + - "^0 || ^3 || ^5" + + For more information on semver, please see https://semver.org/ + maxLength: 64 + pattern: ^(\s*(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|[x|X|\*])(\.(0|[1-9]\d*|x|X|\*]))?(\.(0|[1-9]\d*|x|X|\*))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)((?:\s+|,\s*|\s*\|\|\s*)(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|x|X|\*])(\.(0|[1-9]\d*|x|X|\*))?(\.(0|[1-9]\d*|x|X|\*]))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)*$ + type: string + required: + - packageName + type: object + sourceType: + description: |- + sourceType is a required reference to the type of install source. + + Allowed values are ["Catalog"] + + When this field is set to "Catalog", information for determining the appropriate + bundle of content to install will be fetched from ClusterCatalog resources existing + on the cluster. When using the Catalog sourceType, the catalog field must also be set. + enum: + - Catalog + type: string + required: + - sourceType + type: object + x-kubernetes-validations: + - message: sourceType Catalog requires catalog field + rule: self.sourceType == 'Catalog' && has(self.catalog) + required: + - install + - source + type: object + status: + description: ClusterExtensionStatus defines the observed state of ClusterExtension. + properties: + conditions: + description: |- + conditions is a representation of the current state for this ClusterExtension. + 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 global set of condition types are: + - "Installed", represents whether or not the a bundle has been installed for this ClusterExtension + - "Progressing", represents whether or not the ClusterExtension is progressing towards a new state + + When the ClusterExtension is sourced from a catalog, the following conditions are also possible: + - "Deprecated", represents an aggregation of the PackageDeprecated, ChannelDeprecated, and BundleDeprecated condition types + - "PackageDeprecated", represents whether or not the package specified in the spec.source.catalog.packageName field has been deprecated + - "ChannelDeprecated", represents whether or not any channel specified in spec.source.catalog.channels has been deprecated + - "BundleDeprecated", represents whether or not the installed bundle is deprecated + + The current set of reasons are: + - "Succeeded", this reason is set on the "Installed" and "Progressing" conditions when initial installation and progressing to a new state is successful + - "Failed", this reason is set on the "Installed" condition when an error has occurred while performing the initial installation. + - "Blocked", this reason is set on the "Progressing" condition when the ClusterExtension controller has encountered an error that requires manual intervention for recovery + - "Retrying", this reason is set on the "Progressing" condition when the ClusterExtension controller has encountered an error that could be resolved on subsequent reconciliation attempts + - "Deprecated", this reason is set on the "Deprecated", "PackageDeprecated", "ChannelDeprecated", and "BundleDeprecated" conditions to signal that the installed package has been deprecated at the particular scope + items: + description: Condition contains details for one aspect of the current + state of this API Resource. + properties: + lastTransitionTime: + description: |- + lastTransitionTime is the last time the condition transitioned from one status to another. + This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + format: date-time + type: string + message: + description: |- + message is a human readable message indicating details about the transition. + This may be an empty string. + maxLength: 32768 + type: string + observedGeneration: + description: |- + observedGeneration represents the .metadata.generation that the condition was set based upon. + For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date + with respect to the current state of the instance. + format: int64 + minimum: 0 + type: integer + reason: + description: |- + reason contains a programmatic identifier indicating the reason for the condition's last transition. + Producers of specific condition types may define expected values and meanings for this field, + and whether the values are considered a guaranteed API. + The value should be a CamelCase string. + This field may not be empty. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: type of condition in CamelCase or in foo.example.com/CamelCase. + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map + install: + properties: + bundle: + description: |- + bundle is a representation of the currently installed bundle. + + A "bundle" is a versioned set of content that represents the resources that + need to be applied to a cluster to install a package. + properties: + name: + description: |- + name is a required field and is a reference + to the name of a bundle + type: string + version: + description: |- + version is a required field and is a reference + to the version that this bundle represents + type: string + required: + - name + - version + type: object + required: + - bundle + type: object + type: object + type: object + served: true + storage: true + subresources: + status: {} diff --git a/olm/operator-controller/v1alpha1/clusterextension_types.go b/olm/operator-controller/v1alpha1/clusterextension_types.go new file mode 100644 index 00000000000..9292242b336 --- /dev/null +++ b/olm/operator-controller/v1alpha1/clusterextension_types.go @@ -0,0 +1,518 @@ +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + + "github.com/operator-framework/operator-controller/internal/conditionsets" +) + +var ClusterExtensionKind = "ClusterExtension" + +type ( + UpgradeConstraintPolicy string + CRDUpgradeSafetyPolicy string +) + +const ( + // The extension will only upgrade if the new version satisfies + // the upgrade constraints set by the package author. + UpgradeConstraintPolicyCatalogProvided UpgradeConstraintPolicy = "CatalogProvided" + + // Unsafe option which allows an extension to be + // upgraded or downgraded to any available version of the package and + // ignore the upgrade path designed by package authors. + // This assumes that users independently verify the outcome of the changes. + // Use with caution as this can lead to unknown and potentially + // disastrous results such as data loss. + UpgradeConstraintPolicySelfCertified UpgradeConstraintPolicy = "SelfCertified" +) + +// ClusterExtensionSpec defines the desired state of ClusterExtension +type ClusterExtensionSpec struct { + // source is a required field which selects the installation source of content + // for this ClusterExtension. Selection is performed by setting the sourceType. + // + // Catalog is currently the only implemented sourceType, and setting the + // sourcetype to "Catalog" requires the catalog field to also be defined. + // + // Below is a minimal example of a source definition (in yaml): + // + // source: + // sourceType: Catalog + // catalog: + // packageName: example-package + // + Source SourceConfig `json:"source"` + + // install is a required field used to configure the installation options + // for the ClusterExtension such as the installation namespace, + // the service account and the pre-flight check configuration. + // + // Below is a minimal example of an installation definition (in yaml): + // install: + // namespace: example-namespace + // serviceAccount: + // name: example-sa + Install ClusterExtensionInstallConfig `json:"install"` +} + +const SourceTypeCatalog = "Catalog" + +// SourceConfig is a discriminated union which selects the installation source. +// +union +// +kubebuilder:validation:XValidation:rule="self.sourceType == 'Catalog' && has(self.catalog)",message="sourceType Catalog requires catalog field" +type SourceConfig struct { + // sourceType is a required reference to the type of install source. + // + // Allowed values are ["Catalog"] + // + // When this field is set to "Catalog", information for determining the appropriate + // bundle of content to install will be fetched from ClusterCatalog resources existing + // on the cluster. When using the Catalog sourceType, the catalog field must also be set. + // + // +unionDiscriminator + // +kubebuilder:validation:Enum:="Catalog" + SourceType string `json:"sourceType"` + + // catalog is used to configure how information is sourced from a catalog. This field must be defined when sourceType is set to "Catalog", + // and must be the only field defined for this sourceType. + // + // +optional. + Catalog *CatalogSource `json:"catalog,omitempty"` +} + +// ClusterExtensionInstallConfig is a union which selects the clusterExtension installation config. +// ClusterExtensionInstallConfig requires the namespace and serviceAccount which should be used for the installation of packages. +// +union +type ClusterExtensionInstallConfig struct { + // namespace is a reference to the Namespace in which the bundle of + // content for the package referenced in the packageName field will be applied. + // The bundle may contain cluster-scoped resources or resources that are + // applied to other Namespaces. This Namespace is expected to exist. + // + // namespace is required, immutable, and follows the DNS label standard + // as defined in [RFC 1123]. This means that valid values: + // - Contain no more than 63 characters + // - Contain only lowercase alphanumeric characters or '-' + // - Start with an alphanumeric character + // - End with an alphanumeric character + // + // Some examples of valid values are: + // - some-namespace + // - 123-namespace + // - 1-namespace-2 + // - somenamespace + // + // Some examples of invalid values are: + // - -some-namespace + // - some-namespace- + // - thisisareallylongnamespacenamethatisgreaterthanthemaximumlength + // - some.namespace + // + // [RFC 1123]: https://tools.ietf.org/html/rfc1123 + // + //+kubebuilder:validation:Pattern:=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ + //+kubebuilder:validation:MaxLength:=63 + //+kubebuilder:validation:XValidation:rule="self == oldSelf",message="namespace is immutable" + Namespace string `json:"namespace"` + + // serviceAccount is a required reference to a ServiceAccount that exists + // in the installNamespace. The provided ServiceAccount is used to install and + // manage the content for the package specified in the packageName field. + // + // In order to successfully install and manage the content for the package, + // the ServiceAccount provided via this field should be configured with the + // appropriate permissions to perform the necessary operations on all the + // resources that are included in the bundle of content being applied. + ServiceAccount ServiceAccountReference `json:"serviceAccount"` + + // preflight is an optional field that can be used to configure the preflight checks run before installation or upgrade of the content for the package specified in the packageName field. + // + // When specified, it overrides the default configuration of the preflight checks that are required to execute successfully during an install/upgrade operation. + // + // When not specified, the default configuration for each preflight check will be used. + // + //+optional + Preflight *PreflightConfig `json:"preflight,omitempty"` +} + +// CatalogSource defines the required fields for catalog source. +type CatalogSource struct { + // packageName is a reference to the name of the package to be installed + // and is used to filter the content from catalogs. + // + // This field is required, immutable and follows the DNS subdomain name + // standard as defined in [RFC 1123]. This means that valid entries: + // - Contain no more than 253 characters + // - Contain only lowercase alphanumeric characters, '-', or '.' + // - Start with an alphanumeric character + // - End with an alphanumeric character + // + // Some examples of valid values are: + // - some-package + // - 123-package + // - 1-package-2 + // - somepackage + // + // Some examples of invalid values are: + // - -some-package + // - some-package- + // - thisisareallylongpackagenamethatisgreaterthanthemaximumlength + // - some.package + // + // [RFC 1123]: https://tools.ietf.org/html/rfc1123 + // + //+kubebuilder:validation:MaxLength:=253 + //+kubebuilder:validation:Pattern:=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + //+kubebuilder:validation:XValidation:rule="self == oldSelf",message="packageName is immutable" + PackageName string `json:"packageName"` + + // version is an optional semver constraint (a specific version or range of versions). When unspecified, the latest version available will be installed. + // + // Acceptable version ranges are no longer than 64 characters. + // Version ranges are composed of comma- or space-delimited values and one or + // more comparison operators, known as comparison strings. Additional + // comparison strings can be added using the OR operator (||). + // + // # Range Comparisons + // + // To specify a version range, you can use a comparison string like ">=3.0, + // <3.6". When specifying a range, automatic updates will occur within that + // range. The example comparison string means "install any version greater than + // or equal to 3.0.0 but less than 3.6.0.". It also states intent that if any + // upgrades are available within the version range after initial installation, + // those upgrades should be automatically performed. + // + // # Pinned Versions + // + // To specify an exact version to install you can use a version range that + // "pins" to a specific version. When pinning to a specific version, no + // automatic updates will occur. An example of a pinned version range is + // "0.6.0", which means "only install version 0.6.0 and never + // upgrade from this version". + // + // # Basic Comparison Operators + // + // The basic comparison operators and their meanings are: + // - "=", equal (not aliased to an operator) + // - "!=", not equal + // - "<", less than + // - ">", greater than + // - ">=", greater than OR equal to + // - "<=", less than OR equal to + // + // # Wildcard Comparisons + // + // You can use the "x", "X", and "*" characters as wildcard characters in all + // comparison operations. Some examples of using the wildcard characters: + // - "1.2.x", "1.2.X", and "1.2.*" is equivalent to ">=1.2.0, < 1.3.0" + // - ">= 1.2.x", ">= 1.2.X", and ">= 1.2.*" is equivalent to ">= 1.2.0" + // - "<= 2.x", "<= 2.X", and "<= 2.*" is equivalent to "< 3" + // - "x", "X", and "*" is equivalent to ">= 0.0.0" + // + // # Patch Release Comparisons + // + // When you want to specify a minor version up to the next major version you + // can use the "~" character to perform patch comparisons. Some examples: + // - "~1.2.3" is equivalent to ">=1.2.3, <1.3.0" + // - "~1" and "~1.x" is equivalent to ">=1, <2" + // - "~2.3" is equivalent to ">=2.3, <2.4" + // - "~1.2.x" is equivalent to ">=1.2.0, <1.3.0" + // + // # Major Release Comparisons + // + // You can use the "^" character to make major release comparisons after a + // stable 1.0.0 version is published. If there is no stable version published, // minor versions define the stability level. Some examples: + // - "^1.2.3" is equivalent to ">=1.2.3, <2.0.0" + // - "^1.2.x" is equivalent to ">=1.2.0, <2.0.0" + // - "^2.3" is equivalent to ">=2.3, <3" + // - "^2.x" is equivalent to ">=2.0.0, <3" + // - "^0.2.3" is equivalent to ">=0.2.3, <0.3.0" + // - "^0.2" is equivalent to ">=0.2.0, <0.3.0" + // - "^0.0.3" is equvalent to ">=0.0.3, <0.0.4" + // - "^0.0" is equivalent to ">=0.0.0, <0.1.0" + // - "^0" is equivalent to ">=0.0.0, <1.0.0" + // + // # OR Comparisons + // You can use the "||" character to represent an OR operation in the version + // range. Some examples: + // - ">=1.2.3, <2.0.0 || >3.0.0" + // - "^0 || ^3 || ^5" + // + // For more information on semver, please see https://semver.org/ + // + //+kubebuilder:validation:MaxLength:=64 + //+kubebuilder:validation:Pattern=`^(\s*(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|[x|X|\*])(\.(0|[1-9]\d*|x|X|\*]))?(\.(0|[1-9]\d*|x|X|\*))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)((?:\s+|,\s*|\s*\|\|\s*)(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|x|X|\*])(\.(0|[1-9]\d*|x|X|\*))?(\.(0|[1-9]\d*|x|X|\*]))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)*$` + //+optional + Version string `json:"version,omitempty"` + + // channels is an optional reference to a set of channels belonging to + // the package specified in the packageName field. + // + // A "channel" is a package author defined stream of updates for an extension. + // + // When specified, it is used to constrain the set of installable bundles and + // the automated upgrade path. This constraint is an AND operation with the + // version field. For example: + // - Given channel is set to "foo" + // - Given version is set to ">=1.0.0, <1.5.0" + // - Only bundles that exist in channel "foo" AND satisfy the version range comparison will be considered installable + // - Automatic upgrades will be constrained to upgrade edges defined by the selected channel + // + // When unspecified, upgrade edges across all channels will be used to identify valid automatic upgrade paths. + // + // This field follows the DNS subdomain name standard as defined in [RFC + // 1123]. This means that valid entries: + // - Contain no more than 253 characters + // - Contain only lowercase alphanumeric characters, '-', or '.' + // - Start with an alphanumeric character + // - End with an alphanumeric character + // + // Some examples of valid values are: + // - 1.1.x + // - alpha + // - stable + // - stable-v1 + // - v1-stable + // - dev-preview + // - preview + // - community + // + // Some examples of invalid values are: + // - -some-channel + // - some-channel- + // - thisisareallylongchannelnamethatisgreaterthanthemaximumlength + // - original_40 + // - --default-channel + // + // [RFC 1123]: https://tools.ietf.org/html/rfc1123 + // + //+kubebuilder:validation:items:MaxLength:=253 + //+kubebuilder:validation:items:Pattern:=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + //+optional + Channels []string `json:"channels,omitempty"` + + // selector is an optional field that can be used + // to filter the set of ClusterCatalogs used in the bundle + // selection process. + // + // When unspecified, all ClusterCatalogs will be used in + // the bundle selection process. + // + //+optional + Selector metav1.LabelSelector `json:"selector,omitempty"` + + // upgradeConstraintPolicy is an optional field that controls whether + // the upgrade path(s) defined in the catalog are enforced for the package + // referenced in the packageName field. + // + // Allowed values are: ["CatalogProvided", "SelfCertified"]. + // + // When this field is set to "CatalogProvided", automatic upgrades will only occur + // when upgrade constraints specified by the package author are met. + // + // When this field is set to "SelfCertified", the upgrade constraints specified by + // the package author are ignored. This allows for upgrades and downgrades to + // any version of the package. This is considered a dangerous operation as it + // can lead to unknown and potentially disastrous outcomes, such as data + // loss. It is assumed that users have independently verified changes when + // using this option. + // + // If unspecified, the default value is "CatalogProvided". + // + //+kubebuilder:validation:Enum:=CatalogProvided;SelfCertified + //+kubebuilder:default:=CatalogProvided + //+optional + UpgradeConstraintPolicy UpgradeConstraintPolicy `json:"upgradeConstraintPolicy,omitempty"` +} + +// ServiceAccountReference references a serviceAccount. +type ServiceAccountReference struct { + // name is a required, immutable reference to the name of the ServiceAccount + // to be used for installation and management of the content for the package + // specified in the packageName field. + // + // This ServiceAccount is expected to exist in the installNamespace. + // + // This field follows the DNS subdomain name standard as defined in [RFC + // 1123]. This means that valid values: + // - Contain no more than 253 characters + // - Contain only lowercase alphanumeric characters, '-', or '.' + // - Start with an alphanumeric character + // - End with an alphanumeric character + // + // Some examples of valid values are: + // - some-serviceaccount + // - 123-serviceaccount + // - 1-serviceaccount-2 + // - someserviceaccount + // - some.serviceaccount + // + // Some examples of invalid values are: + // - -some-serviceaccount + // - some-serviceaccount- + // + // [RFC 1123]: https://tools.ietf.org/html/rfc1123 + // + //+kubebuilder:validation:MaxLength:=253 + //+kubebuilder:validation:Pattern:=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + //+kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable" + Name string `json:"name"` +} + +// PreflightConfig holds the configuration for the preflight checks. If used, at least one preflight check must be non-nil. +// +kubebuilder:validation:XValidation:rule="has(self.crdUpgradeSafety)",message="at least one of [crdUpgradeSafety] are required when preflight is specified" +type PreflightConfig struct { + // crdUpgradeSafety is used to configure the CRD Upgrade Safety pre-flight + // checks that run prior to upgrades of installed content. + // + // The CRD Upgrade Safety pre-flight check safeguards from unintended + // consequences of upgrading a CRD, such as data loss. + // + // This field is required if the spec.install.preflight field is specified. + CRDUpgradeSafety *CRDUpgradeSafetyPreflightConfig `json:"crdUpgradeSafety"` +} + +// CRDUpgradeSafetyPreflightConfig is the configuration for CRD upgrade safety preflight check. +type CRDUpgradeSafetyPreflightConfig struct { + // policy is used to configure the state of the CRD Upgrade Safety pre-flight check. + // + // This field is required when the spec.install.preflight.crdUpgradeSafety field is + // specified. + // + // Allowed values are ["Enabled", "Disabled"]. The default value is "Enabled". + // + // When set to "Disabled", the CRD Upgrade Safety pre-flight check will be skipped + // when performing an upgrade operation. This should be used with caution as + // unintended consequences such as data loss can occur. + // + // When set to "Enabled", the CRD Upgrade Safety pre-flight check will be run when + // performing an upgrade operation. + // + //+kubebuilder:validation:Enum:="Enabled";"Disabled" + //+kubebuilder:default:=Enabled + Policy CRDUpgradeSafetyPolicy `json:"policy"` +} + +const ( + // TODO(user): add more Types, here and into init() + TypeInstalled = "Installed" + TypeProgressing = "Progressing" + + // TypeDeprecated is a rollup condition that is present when + // any of the deprecated conditions are present. + TypeDeprecated = "Deprecated" + TypePackageDeprecated = "PackageDeprecated" + TypeChannelDeprecated = "ChannelDeprecated" + TypeBundleDeprecated = "BundleDeprecated" + + ReasonSucceeded = "Succeeded" + ReasonDeprecated = "Deprecated" + ReasonFailed = "Failed" + ReasonBlocked = "Blocked" + ReasonRetrying = "Retrying" + + CRDUpgradeSafetyPolicyEnabled CRDUpgradeSafetyPolicy = "Enabled" + CRDUpgradeSafetyPolicyDisabled CRDUpgradeSafetyPolicy = "Disabled" +) + +func init() { + // TODO(user): add Types from above + conditionsets.ConditionTypes = append(conditionsets.ConditionTypes, + TypeInstalled, + TypeDeprecated, + TypePackageDeprecated, + TypeChannelDeprecated, + TypeBundleDeprecated, + TypeProgressing, + ) + // TODO(user): add Reasons from above + conditionsets.ConditionReasons = append(conditionsets.ConditionReasons, + ReasonSucceeded, + ReasonDeprecated, + ReasonFailed, + ReasonBlocked, + ReasonRetrying, + ) +} + +type BundleMetadata struct { + // name is a required field and is a reference + // to the name of a bundle + Name string `json:"name"` + // version is a required field and is a reference + // to the version that this bundle represents + Version string `json:"version"` +} + +// ClusterExtensionStatus defines the observed state of ClusterExtension. +type ClusterExtensionStatus struct { + Install *ClusterExtensionInstallStatus `json:"install,omitempty"` + + // conditions is a representation of the current state for this ClusterExtension. + // 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 global set of condition types are: + // - "Installed", represents whether or not the a bundle has been installed for this ClusterExtension + // - "Progressing", represents whether or not the ClusterExtension is progressing towards a new state + // + // When the ClusterExtension is sourced from a catalog, the following conditions are also possible: + // - "Deprecated", represents an aggregation of the PackageDeprecated, ChannelDeprecated, and BundleDeprecated condition types + // - "PackageDeprecated", represents whether or not the package specified in the spec.source.catalog.packageName field has been deprecated + // - "ChannelDeprecated", represents whether or not any channel specified in spec.source.catalog.channels has been deprecated + // - "BundleDeprecated", represents whether or not the installed bundle is deprecated + // + // The current set of reasons are: + // - "Succeeded", this reason is set on the "Installed" and "Progressing" conditions when initial installation and progressing to a new state is successful + // - "Failed", this reason is set on the "Installed" condition when an error has occurred while performing the initial installation. + // - "Blocked", this reason is set on the "Progressing" condition when the ClusterExtension controller has encountered an error that requires manual intervention for recovery + // - "Retrying", this reason is set on the "Progressing" condition when the ClusterExtension controller has encountered an error that could be resolved on subsequent reconciliation attempts + // - "Deprecated", this reason is set on the "Deprecated", "PackageDeprecated", "ChannelDeprecated", and "BundleDeprecated" conditions to signal that the installed package has been deprecated at the particular scope + // + // + // +patchMergeKey=type + // +patchStrategy=merge + // +listType=map + // +listMapKey=type + Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` +} + +type ClusterExtensionInstallStatus struct { + // bundle is a representation of the currently installed bundle. + // + // A "bundle" is a versioned set of content that represents the resources that + // need to be applied to a cluster to install a package. + Bundle BundleMetadata `json:"bundle"` +} + +//+kubebuilder:object:root=true +//+kubebuilder:resource:scope=Cluster +//+kubebuilder:subresource:status + +// ClusterExtension is the Schema for the clusterextensions API +type ClusterExtension struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec ClusterExtensionSpec `json:"spec,omitempty"` + Status ClusterExtensionStatus `json:"status,omitempty"` +} + +//+kubebuilder:object:root=true + +// ClusterExtensionList contains a list of ClusterExtension +type ClusterExtensionList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []ClusterExtension `json:"items"` +} + +func init() { + SchemeBuilder.Register(&ClusterExtension{}, &ClusterExtensionList{}) +} diff --git a/olm/operator-controller/v1alpha1/groupversion_info.go b/olm/operator-controller/v1alpha1/groupversion_info.go new file mode 100644 index 00000000000..0135abc67d7 --- /dev/null +++ b/olm/operator-controller/v1alpha1/groupversion_info.go @@ -0,0 +1,20 @@ +// Package v1alpha1 contains API Schema definitions for the olm v1alpha1 API group +// +kubebuilder:object:generate=true +// +groupName=olm.operatorframework.io +package v1alpha1 + +import ( + "k8s.io/apimachinery/pkg/runtime/schema" + "sigs.k8s.io/controller-runtime/pkg/scheme" +) + +var ( + // GroupVersion is group version used to register these objects + GroupVersion = schema.GroupVersion{Group: "olm.operatorframework.io", Version: "v1alpha1"} + + // SchemeBuilder is used to add go types to the GroupVersionKind scheme + SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion} + + // AddToScheme adds the types in this group-version to the given scheme. + AddToScheme = SchemeBuilder.AddToScheme +)