diff --git a/api/v1/clustercatalog_types.go b/api/v1/clustercatalog_types.go
index 8df90a806..2583c1128 100644
--- a/api/v1/clustercatalog_types.go
+++ b/api/v1/clustercatalog_types.go
@@ -62,7 +62,7 @@ type ClusterCatalog struct {
// spec is a required field that defines the desired state of the ClusterCatalog.
// The controller ensures that the catalog is unpacked and served over the catalog content HTTP server.
- // +kubebuilder:validation:Required
+ // +required
Spec ClusterCatalogSpec `json:"spec"`
// status contains the following information about the state of the ClusterCatalog:
@@ -85,7 +85,7 @@ type ClusterCatalogList struct {
// items is a list of ClusterCatalogs.
// items is required.
- // +kubebuilder:validation:Required
+ // +required
Items []ClusterCatalog `json:"items"`
}
@@ -105,7 +105,7 @@ type ClusterCatalogSpec struct {
// image:
// ref: quay.io/operatorhubio/catalog:latest
//
- // +kubebuilder:validation:Required
+ // +required
Source CatalogSource `json:"source"`
// priority is an optional field that defines a priority for this ClusterCatalog.
@@ -199,7 +199,7 @@ type ClusterCatalogURLs struct {
//
// New endpoints may be added as needs evolve.
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:MaxLength:=525
// +kubebuilder:validation:XValidation:rule="isURL(self)",message="must be a valid URL"
// +kubebuilder:validation:XValidation:rule="isURL(self) ? (url(self).getScheme() == \"http\" || url(self).getScheme() == \"https\") : true",message="scheme must be either http or https"
@@ -220,7 +220,7 @@ type CatalogSource struct {
//
// +unionDiscriminator
// +kubebuilder:validation:Enum:="Image"
- // +kubebuilder:validation:Required
+ // +required
Type SourceType `json:"type"`
// image configures how catalog contents are sourced from an OCI image.
// It is required when type is Image, and forbidden otherwise.
@@ -241,7 +241,7 @@ type ResolvedCatalogSource struct {
//
// +unionDiscriminator
// +kubebuilder:validation:Enum:="Image"
- // +kubebuilder:validation:Required
+ // +required
Type SourceType `json:"type"`
// image contains resolution information for a catalog sourced from an image.
// It must be set when type is Image, and forbidden otherwise.
@@ -253,7 +253,7 @@ type ResolvedImageSource struct {
// ref contains the resolved image digest-based reference.
// The digest format allows you to use other tooling to fetch the exact OCI manifests
// that were used to extract the catalog contents.
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:MaxLength:=1000
// +kubebuilder:validation:XValidation:rule="self.matches('^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])((\\\\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))+)?(:[0-9]+)?\\\\b')",message="must start with a valid domain. valid domains must be alphanumeric characters (lowercase and uppercase) separated by the \".\" character."
// +kubebuilder:validation:XValidation:rule="self.find('(\\\\/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?((\\\\/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?)+)?)') != \"\"",message="a valid name is required. valid names must contain lowercase alphanumeric characters separated only by the \".\", \"_\", \"__\", \"-\" characters."
@@ -307,7 +307,7 @@ type ImageSource struct {
// An example of a valid digest-based image reference is "quay.io/operatorhubio/catalog@sha256:200d4ddb2a73594b91358fe6397424e975205bfbe44614f5846033cad64b3f05"
// An example of a valid tag-based image reference is "quay.io/operatorhubio/catalog:latest"
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:MaxLength:=1000
// +kubebuilder:validation:XValidation:rule="self.matches('^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])((\\\\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))+)?(:[0-9]+)?\\\\b')",message="must start with a valid domain. valid domains must be alphanumeric characters (lowercase and uppercase) separated by the \".\" character."
// +kubebuilder:validation:XValidation:rule="self.find('(\\\\/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?((\\\\/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?)+)?)') != \"\"",message="a valid name is required. valid names must contain lowercase alphanumeric characters separated only by the \".\", \"_\", \"__\", \"-\" characters."
diff --git a/api/v1/clusterextension_types.go b/api/v1/clusterextension_types.go
index f098d2220..a196bd0b0 100644
--- a/api/v1/clusterextension_types.go
+++ b/api/v1/clusterextension_types.go
@@ -63,7 +63,7 @@ type ClusterExtensionSpec struct {
// +kubebuilder:validation:MaxLength:=63
// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="namespace is immutable"
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\")",message="namespace must be a valid DNS1123 label"
- // +kubebuilder:validation:Required
+ // +required
Namespace string `json:"namespace"`
// serviceAccount specifies a ServiceAccount used to perform all interactions with the cluster
@@ -72,7 +72,7 @@ type ClusterExtensionSpec struct {
// The ServiceAccount must exist in the namespace referenced in the spec.
// The serviceAccount field is required.
//
- // +kubebuilder:validation:Required
+ // +required
ServiceAccount ServiceAccountReference `json:"serviceAccount"`
// source is required and selects the installation source of content for this ClusterExtension.
@@ -88,7 +88,7 @@ type ClusterExtensionSpec struct {
// catalog:
// packageName: example-package
//
- // +kubebuilder:validation:Required
+ // +required
Source SourceConfig `json:"source"`
// install is optional and configures installation options for the ClusterExtension,
@@ -127,7 +127,7 @@ type SourceConfig struct {
//
// +unionDiscriminator
// +kubebuilder:validation:Enum:="Catalog"
- // +kubebuilder:validation:Required
+ // +required
SourceType string `json:"sourceType"`
// catalog configures how information is sourced from a catalog.
@@ -167,7 +167,7 @@ type ClusterExtensionConfig struct {
//
// +unionDiscriminator
// +kubebuilder:validation:Enum:="Inline"
- // +kubebuilder:validation:Required
+ // +required
ConfigType ClusterExtensionConfigType `json:"configType"`
// inline contains JSON or YAML values specified directly in the ClusterExtension.
@@ -210,7 +210,7 @@ type CatalogFilter struct {
// +kubebuilder:validation:MaxLength:=253
// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="packageName is immutable"
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$\")",message="packageName must be a valid DNS1123 subdomain. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters"
- // +kubebuilder:validation:Required
+ // +required
PackageName string `json:"packageName"`
// version is an optional semver constraint (a specific version or range of versions).
@@ -393,7 +393,7 @@ type ServiceAccountReference struct {
// +kubebuilder:validation:MaxLength:=253
// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable"
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$\")",message="name must be a valid DNS1123 subdomain. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters"
- // +kubebuilder:validation:Required
+ // +required
Name string `json:"name"`
}
@@ -421,7 +421,7 @@ type CRDUpgradeSafetyPreflightConfig struct {
// When set to "Strict", the CRD Upgrade Safety pre-flight check runs during an upgrade operation.
//
// +kubebuilder:validation:Enum:="None";"Strict"
- // +kubebuilder:validation:Required
+ // +required
Enforcement CRDUpgradeSafetyEnforcement `json:"enforcement"`
}
@@ -445,14 +445,14 @@ type BundleMetadata struct {
// It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
// start and end with an alphanumeric character, and be no longer than 253 characters.
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$\")",message="packageName must be a valid DNS1123 subdomain. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters"
Name string `json:"name"`
// version is required and references the version that this bundle represents.
// It follows the semantic versioning standard as defined in https://semver.org/.
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:XValidation:rule="self.matches(\"^([0-9]+)(\\\\.[0-9]+)?(\\\\.[0-9]+)?(-([-0-9A-Za-z]+(\\\\.[-0-9A-Za-z]+)*))?(\\\\+([-0-9A-Za-z]+(-\\\\.[-0-9A-Za-z]+)*))?\")",message="version must be well-formed semver"
Version string `json:"version"`
}
@@ -521,7 +521,7 @@ type ClusterExtensionInstallStatus struct {
// A "bundle" is a versioned set of content that represents the resources that need to be applied
// to a cluster to install a package.
//
- // +kubebuilder:validation:Required
+ // +required
Bundle BundleMetadata `json:"bundle"`
}
@@ -559,7 +559,7 @@ type ClusterExtensionList struct {
// items is a required list of ClusterExtension objects.
//
- // +kubebuilder:validation:Required
+ // +required
Items []ClusterExtension `json:"items"`
}
diff --git a/api/v1/clusterextensionrevision_types.go b/api/v1/clusterextensionrevision_types.go
index 368a8fca8..ad24c910b 100644
--- a/api/v1/clusterextensionrevision_types.go
+++ b/api/v1/clusterextensionrevision_types.go
@@ -61,7 +61,7 @@ type ClusterExtensionRevisionSpec struct {
// Each ClusterExtensionRevision belonging to the same parent ClusterExtension must have a unique revision number.
// The revision number must always be the previous revision number plus one, or 1 for the first revision.
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:Minimum:=1
// +kubebuilder:validation:XValidation:rule="self == oldSelf", message="revision is immutable"
Revision int64 `json:"revision"`
@@ -238,7 +238,7 @@ type ClusterExtensionRevisionList struct {
// items is a required list of ClusterExtensionRevision objects.
//
- // +kubebuilder:validation:Required
+ // +required
Items []ClusterExtensionRevision `json:"items"`
}
diff --git a/docs/api-reference/olmv1-api-reference.md b/docs/api-reference/olmv1-api-reference.md
index 6aeb4c8f4..02393c08a 100644
--- a/docs/api-reference/olmv1-api-reference.md
+++ b/docs/api-reference/olmv1-api-reference.md
@@ -46,8 +46,8 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `name` _string_ | name is required and follows the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters. | | Required: \{\}
|
-| `version` _string_ | version is required and references the version that this bundle represents.
It follows the semantic versioning standard as defined in https://semver.org/. | | Required: \{\}
|
+| `name` _string_ | name is required and follows the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters. | | |
+| `version` _string_ | version is required and references the version that this bundle represents.
It follows the semantic versioning standard as defined in https://semver.org/. | | |
#### CRDUpgradeSafetyEnforcement
@@ -80,7 +80,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `enforcement` _[CRDUpgradeSafetyEnforcement](#crdupgradesafetyenforcement)_ | enforcement is required and configures the state of the CRD Upgrade Safety pre-flight check.
Allowed values are "None" or "Strict". The default value is "Strict".
When set to "None", the CRD Upgrade Safety pre-flight check is skipped during an upgrade operation.
Use this option with caution as unintended consequences such as data loss can occur.
When set to "Strict", the CRD Upgrade Safety pre-flight check runs during an upgrade operation. | | Enum: [None Strict]
Required: \{\}
|
+| `enforcement` _[CRDUpgradeSafetyEnforcement](#crdupgradesafetyenforcement)_ | enforcement is required and configures the state of the CRD Upgrade Safety pre-flight check.
Allowed values are "None" or "Strict". The default value is "Strict".
When set to "None", the CRD Upgrade Safety pre-flight check is skipped during an upgrade operation.
Use this option with caution as unintended consequences such as data loss can occur.
When set to "Strict", the CRD Upgrade Safety pre-flight check runs during an upgrade operation. | | Enum: [None Strict]
|
#### CatalogFilter
@@ -96,7 +96,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `packageName` _string_ | packageName specifies the name of the package to be installed and is used to filter
the content from catalogs.
It is required, immutable, and follows the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters.
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
Required: \{\}
|
+| `packageName` _string_ | packageName specifies the name of the package to be installed and is used to filter
the content from catalogs.
It is required, immutable, and follows the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters.
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
|
| `version` _string_ | version is an optional semver constraint (a specific version or range of versions).
When unspecified, the latest version available is 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.
You can add additional comparison strings 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
|
| `channels` _string array_ | channels is optional and specifies 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.
Each channel in the list must follow the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters.
You can specify no more than 256 channels.
When specified, it constrains 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 are considered installable
- Automatic upgrades are constrained to upgrade edges defined by the selected channel
When unspecified, upgrade edges across all channels are used to identify valid automatic upgrade paths.
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 | | MaxItems: 256
items:MaxLength: 253
items:XValidation: \{self.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$") channels entries must be valid DNS1123 subdomains \}
|
| `selector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta)_ | selector is optional and filters the set of ClusterCatalogs used in the bundle selection process.
When unspecified, all ClusterCatalogs are used in the bundle selection process. | | |
@@ -117,7 +117,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `type` _[SourceType](#sourcetype)_ | type is a required field that specifies the type of source for the catalog.
The only allowed value is "Image".
When set to "Image", the ClusterCatalog content is 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]
Required: \{\}
|
+| `type` _[SourceType](#sourcetype)_ | type is a required field that specifies the type of source for the catalog.
The only allowed value is "Image".
When set to "Image", the ClusterCatalog content is 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]
|
| `image` _[ImageSource](#imagesource)_ | image configures how catalog contents are sourced from an OCI image.
It is required when type is Image, and forbidden otherwise. | | |
@@ -140,7 +140,7 @@ _Appears in:_
| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
-| `spec` _[ClusterCatalogSpec](#clustercatalogspec)_ | spec is a required field that defines the desired state of the ClusterCatalog.
The controller ensures that the catalog is unpacked and served over the catalog content HTTP server. | | Required: \{\}
|
+| `spec` _[ClusterCatalogSpec](#clustercatalogspec)_ | spec is a required field that defines the desired state of the ClusterCatalog.
The controller ensures that the catalog is unpacked and served over the catalog content HTTP server. | | |
| `status` _[ClusterCatalogStatus](#clustercatalogstatus)_ | status contains the following information about the state of the ClusterCatalog:
- Whether the catalog contents are being served via the catalog content HTTP server
- Whether the ClusterCatalog is progressing to a new state
- A reference to the source from which the catalog contents were retrieved | | |
@@ -161,7 +161,7 @@ ClusterCatalogList contains a list of ClusterCatalog
| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | |
| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
-| `items` _[ClusterCatalog](#clustercatalog) array_ | items is a list of ClusterCatalogs.
items is required. | | Required: \{\}
|
+| `items` _[ClusterCatalog](#clustercatalog) array_ | items is a list of ClusterCatalogs.
items is required. | | |
#### ClusterCatalogSpec
@@ -177,7 +177,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `source` _[CatalogSource](#catalogsource)_ | source is a required field that defines the source of a catalog.
A catalog contains information on content that can be installed on a cluster.
The catalog source makes catalog contents discoverable and usable by other on-cluster components.
These components can present the content in a GUI dashboard or install content from the catalog on the cluster.
The catalog source must contain catalog metadata in the File-Based Catalog (FBC) format.
For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs.
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 | | Required: \{\}
|
+| `source` _[CatalogSource](#catalogsource)_ | source is a required field that defines the source of a catalog.
A catalog contains information on content that can be installed on a cluster.
The catalog source makes catalog contents discoverable and usable by other on-cluster components.
These components can present the content in a GUI dashboard or install content from the catalog on the cluster.
The catalog source must contain catalog metadata in the File-Based Catalog (FBC) format.
For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs.
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 | | |
| `priority` _integer_ | priority is an optional field that defines a priority for this ClusterCatalog.
Clients use the ClusterCatalog priority as a tie-breaker between ClusterCatalogs that meet their requirements.
Higher numbers mean higher priority.
Clients decide how to handle scenarios where multiple ClusterCatalogs with the same priority meet their requirements.
Clients should prompt users for additional input to break the tie.
When omitted, the default priority is 0.
Use negative numbers to specify a priority lower than the default.
Use positive numbers to specify a priority higher than the default.
The lowest possible value is -2147483648.
The highest possible value is 2147483647. | 0 | |
| `availabilityMode` _[AvailabilityMode](#availabilitymode)_ | availabilityMode is an optional field that defines how the ClusterCatalog is made available to clients on the cluster.
Allowed values are "Available", "Unavailable", or omitted.
When omitted, the default value is "Available".
When set to "Available", the catalog contents are unpacked and served over the catalog content HTTP server.
Clients should consider this ClusterCatalog and its contents as usable.
When set to "Unavailable", the catalog contents are no longer served over the catalog content HTTP server.
Treat this the same as if the ClusterCatalog does not exist.
Use "Unavailable" when you want to keep the ClusterCatalog but treat it as if it doesn't exist. | Available | Enum: [Unavailable Available]
|
@@ -214,7 +214,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `base` _string_ | base is a cluster-internal URL that provides endpoints for accessing the catalog content.
Clients should append the path for the endpoint they want to access.
Currently, only a single endpoint is served and is accessible at the path /api/v1.
The endpoints served for the v1 API are:
- /all - this endpoint returns the entire catalog contents in the FBC format
New endpoints may be added as needs evolve. | | MaxLength: 525
Required: \{\}
|
+| `base` _string_ | base is a cluster-internal URL that provides endpoints for accessing the catalog content.
Clients should append the path for the endpoint they want to access.
Currently, only a single endpoint is served and is accessible at the path /api/v1.
The endpoints served for the v1 API are:
- /all - this endpoint returns the entire catalog contents in the FBC format
New endpoints may be added as needs evolve. | | MaxLength: 525
|
#### ClusterExtension
@@ -253,7 +253,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `configType` _[ClusterExtensionConfigType](#clusterextensionconfigtype)_ | configType is required and specifies the type of configuration source.
The only allowed value is "Inline".
When set to "Inline", the cluster extension configuration is defined inline within the ClusterExtension resource. | | Enum: [Inline]
Required: \{\}
|
+| `configType` _[ClusterExtensionConfigType](#clusterextensionconfigtype)_ | configType is required and specifies the type of configuration source.
The only allowed value is "Inline".
When set to "Inline", the cluster extension configuration is defined inline within the ClusterExtension resource. | | Enum: [Inline]
|
| `inline` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#json-v1-apiextensions-k8s-io)_ | inline contains JSON or YAML values specified directly in the ClusterExtension.
It is used to specify arbitrary configuration values for the ClusterExtension.
It must be set if configType is 'Inline' and must be a valid JSON/YAML object containing at least one property.
The configuration values are validated at runtime against a JSON schema provided by the bundle. | | MinProperties: 1
Type: object
|
@@ -303,7 +303,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `bundle` _[BundleMetadata](#bundlemetadata)_ | bundle is required and represents the identifying attributes of a 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. | | Required: \{\}
|
+| `bundle` _[BundleMetadata](#bundlemetadata)_ | bundle is required and represents the identifying attributes of a 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. | | |
#### ClusterExtensionList
@@ -323,7 +323,7 @@ ClusterExtensionList contains a list of ClusterExtension
| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | |
| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
-| `items` _[ClusterExtension](#clusterextension) array_ | items is a required list of ClusterExtension objects. | | Required: \{\}
|
+| `items` _[ClusterExtension](#clusterextension) array_ | items is a required list of ClusterExtension objects. | | |
#### ClusterExtensionSpec
@@ -339,9 +339,9 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `namespace` _string_ | namespace specifies a Kubernetes namespace.
This is the namespace where the provided ServiceAccount must exist.
It also designates the default namespace where namespace-scoped resources for the extension are applied to the cluster.
Some extensions may contain namespace-scoped resources to be applied in other namespaces.
This namespace must exist.
The namespace field is required, immutable, and follows the DNS label standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters or hyphens (-), start and end with an alphanumeric character,
and be no longer than 63 characters.
[RFC 1123]: https://tools.ietf.org/html/rfc1123 | | MaxLength: 63
Required: \{\}
|
-| `serviceAccount` _[ServiceAccountReference](#serviceaccountreference)_ | serviceAccount specifies a ServiceAccount used to perform all interactions with the cluster
that are required to manage the extension.
The ServiceAccount must be configured with the necessary permissions to perform these interactions.
The ServiceAccount must exist in the namespace referenced in the spec.
The serviceAccount field is required. | | Required: \{\}
|
-| `source` _[SourceConfig](#sourceconfig)_ | source is required and selects the installation source of content for this ClusterExtension.
Set the sourceType field to perform the selection.
Catalog is currently the only implemented sourceType.
Setting 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 | | Required: \{\}
|
+| `namespace` _string_ | namespace specifies a Kubernetes namespace.
This is the namespace where the provided ServiceAccount must exist.
It also designates the default namespace where namespace-scoped resources for the extension are applied to the cluster.
Some extensions may contain namespace-scoped resources to be applied in other namespaces.
This namespace must exist.
The namespace field is required, immutable, and follows the DNS label standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters or hyphens (-), start and end with an alphanumeric character,
and be no longer than 63 characters.
[RFC 1123]: https://tools.ietf.org/html/rfc1123 | | MaxLength: 63
|
+| `serviceAccount` _[ServiceAccountReference](#serviceaccountreference)_ | serviceAccount specifies a ServiceAccount used to perform all interactions with the cluster
that are required to manage the extension.
The ServiceAccount must be configured with the necessary permissions to perform these interactions.
The ServiceAccount must exist in the namespace referenced in the spec.
The serviceAccount field is required. | | |
+| `source` _[SourceConfig](#sourceconfig)_ | source is required and selects the installation source of content for this ClusterExtension.
Set the sourceType field to perform the selection.
Catalog is currently the only implemented sourceType.
Setting 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 | | |
| `install` _[ClusterExtensionInstallConfig](#clusterextensioninstallconfig)_ | install is optional and configures installation options for the ClusterExtension,
such as the pre-flight check configuration. | | |
| `config` _[ClusterExtensionConfig](#clusterextensionconfig)_ | config is optional and specifies bundle-specific configuration.
Configuration is bundle-specific and a bundle may provide a configuration schema.
When not specified, the default configuration of the resolved bundle is used.
config is validated against a configuration schema provided by the resolved bundle. If the bundle does not provide
a configuration schema the bundle is deemed to not be configurable. More information on how
to configure bundles can be found in the OLM documentation associated with your current OLM version.
| | |
@@ -382,7 +382,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `ref` _string_ | ref is a required field that defines the reference to a container image containing catalog contents.
It cannot be more than 1000 characters.
A reference has 3 parts: the domain, name, and identifier.
The domain is typically the registry where an image is located.
It must be alphanumeric characters (lowercase and uppercase) separated by the "." character.
Hyphenation is allowed, but the domain must start and end with alphanumeric characters.
Specifying a port to use is also allowed by adding the ":" character followed by numeric values.
The port must be the last value in the domain.
Some examples of valid domain values are "registry.mydomain.io", "quay.io", "my-registry.io:8080".
The name is typically the repository in the registry where an image is located.
It must contain lowercase alphanumeric characters separated only by the ".", "_", "__", "-" characters.
Multiple names can be concatenated with the "/" character.
The domain and name are combined using the "/" character.
Some examples of valid name values are "operatorhubio/catalog", "catalog", "my-catalog.prod".
An example of the domain and name parts of a reference being combined is "quay.io/operatorhubio/catalog".
The identifier is typically the tag or digest for an image reference and is present at the end of the reference.
It starts with a separator character used to distinguish the end of the name and beginning of the identifier.
For a digest-based reference, the "@" character is the separator.
For a tag-based reference, the ":" character is the separator.
An identifier is required in the reference.
Digest-based references must contain an algorithm reference immediately after the "@" separator.
The algorithm reference must be followed by the ":" character and an encoded string.
The algorithm must start with an uppercase or lowercase alpha character followed by alphanumeric characters and may contain the "-", "_", "+", and "." characters.
Some examples of valid algorithm values are "sha256", "sha256+b64u", "multihash+base58".
The encoded string following the algorithm must be hex digits (a-f, A-F, 0-9) and must be a minimum of 32 characters.
Tag-based references must begin with a word character (alphanumeric + "_") followed by word characters or ".", and "-" characters.
The tag must not be longer than 127 characters.
An example of a valid digest-based image reference is "quay.io/operatorhubio/catalog@sha256:200d4ddb2a73594b91358fe6397424e975205bfbe44614f5846033cad64b3f05"
An example of a valid tag-based image reference is "quay.io/operatorhubio/catalog:latest" | | MaxLength: 1000
Required: \{\}
|
+| `ref` _string_ | ref is a required field that defines the reference to a container image containing catalog contents.
It cannot be more than 1000 characters.
A reference has 3 parts: the domain, name, and identifier.
The domain is typically the registry where an image is located.
It must be alphanumeric characters (lowercase and uppercase) separated by the "." character.
Hyphenation is allowed, but the domain must start and end with alphanumeric characters.
Specifying a port to use is also allowed by adding the ":" character followed by numeric values.
The port must be the last value in the domain.
Some examples of valid domain values are "registry.mydomain.io", "quay.io", "my-registry.io:8080".
The name is typically the repository in the registry where an image is located.
It must contain lowercase alphanumeric characters separated only by the ".", "_", "__", "-" characters.
Multiple names can be concatenated with the "/" character.
The domain and name are combined using the "/" character.
Some examples of valid name values are "operatorhubio/catalog", "catalog", "my-catalog.prod".
An example of the domain and name parts of a reference being combined is "quay.io/operatorhubio/catalog".
The identifier is typically the tag or digest for an image reference and is present at the end of the reference.
It starts with a separator character used to distinguish the end of the name and beginning of the identifier.
For a digest-based reference, the "@" character is the separator.
For a tag-based reference, the ":" character is the separator.
An identifier is required in the reference.
Digest-based references must contain an algorithm reference immediately after the "@" separator.
The algorithm reference must be followed by the ":" character and an encoded string.
The algorithm must start with an uppercase or lowercase alpha character followed by alphanumeric characters and may contain the "-", "_", "+", and "." characters.
Some examples of valid algorithm values are "sha256", "sha256+b64u", "multihash+base58".
The encoded string following the algorithm must be hex digits (a-f, A-F, 0-9) and must be a minimum of 32 characters.
Tag-based references must begin with a word character (alphanumeric + "_") followed by word characters or ".", and "-" characters.
The tag must not be longer than 127 characters.
An example of a valid digest-based image reference is "quay.io/operatorhubio/catalog@sha256:200d4ddb2a73594b91358fe6397424e975205bfbe44614f5846033cad64b3f05"
An example of a valid tag-based image reference is "quay.io/operatorhubio/catalog:latest" | | MaxLength: 1000
|
| `pollIntervalMinutes` _integer_ | pollIntervalMinutes is an optional field that sets the interval, in minutes, at which the image source is polled for new content.
You cannot specify pollIntervalMinutes when ref is a digest-based reference.
When omitted, the image is not polled for new content. | | Minimum: 1
|
@@ -416,7 +416,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `type` _[SourceType](#sourcetype)_ | type is a required field that specifies the type of source for the catalog.
The only allowed value is "Image".
When set to "Image", information about the resolved image source is set in the image field. | | Enum: [Image]
Required: \{\}
|
+| `type` _[SourceType](#sourcetype)_ | type is a required field that specifies the type of source for the catalog.
The only allowed value is "Image".
When set to "Image", information about the resolved image source is set in the image field. | | Enum: [Image]
|
| `image` _[ResolvedImageSource](#resolvedimagesource)_ | image contains resolution information for a catalog sourced from an image.
It must be set when type is Image, and forbidden otherwise. | | |
@@ -433,7 +433,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `ref` _string_ | ref contains the resolved image digest-based reference.
The digest format allows you to use other tooling to fetch the exact OCI manifests
that were used to extract the catalog contents. | | MaxLength: 1000
Required: \{\}
|
+| `ref` _string_ | ref contains the resolved image digest-based reference.
The digest format allows you to use other tooling to fetch the exact OCI manifests
that were used to extract the catalog contents. | | MaxLength: 1000
|
#### RevisionStatus
@@ -466,7 +466,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `name` _string_ | name is a required, immutable reference to the name of the ServiceAccount used for installation
and management of the content for the package specified in the packageName field.
This ServiceAccount must exist in the installNamespace.
The name field follows the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters.
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
Required: \{\}
|
+| `name` _string_ | name is a required, immutable reference to the name of the ServiceAccount used for installation
and management of the content for the package specified in the packageName field.
This ServiceAccount must exist in the installNamespace.
The name field follows the DNS subdomain standard as defined in [RFC 1123].
It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),
start and end with an alphanumeric character, and be no longer than 253 characters.
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
|
#### SourceConfig
@@ -482,7 +482,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
-| `sourceType` _string_ | sourceType is required and specifies the type of install source.
The only allowed value is "Catalog".
When set to "Catalog", information for determining the appropriate bundle of content to install
is fetched from ClusterCatalog resources on the cluster.
When using the Catalog sourceType, the catalog field must also be set. | | Enum: [Catalog]
Required: \{\}
|
+| `sourceType` _string_ | sourceType is required and specifies the type of install source.
The only allowed value is "Catalog".
When set to "Catalog", information for determining the appropriate bundle of content to install
is fetched from ClusterCatalog resources on the cluster.
When using the Catalog sourceType, the catalog field must also be set. | | Enum: [Catalog]
|
| `catalog` _[CatalogFilter](#catalogfilter)_ | catalog configures how information is sourced from a catalog.
It is required when sourceType is "Catalog", and forbidden otherwise. | | |
diff --git a/hack/tools/crd-generator/testdata/api/v1/clusterextension_types.go b/hack/tools/crd-generator/testdata/api/v1/clusterextension_types.go
index 8e134a342..bd0de61d7 100644
--- a/hack/tools/crd-generator/testdata/api/v1/clusterextension_types.go
+++ b/hack/tools/crd-generator/testdata/api/v1/clusterextension_types.go
@@ -60,7 +60,7 @@ type ClusterExtensionSpec struct {
//
//
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\")",message="namespace must be a valid DNS1123 label"
- // +kubebuilder:validation:Required
+ // +required
Namespace string `json:"namespace"`
// serviceAccount is a reference to a ServiceAccount used to perform all interactions
@@ -69,7 +69,7 @@ type ClusterExtensionSpec struct {
// The ServiceAccount must exist in the namespace referenced in the spec.
// serviceAccount is required.
//
- // +kubebuilder:validation:Required
+ // +required
ServiceAccount ServiceAccountReference `json:"serviceAccount"`
// source is a required field which selects the installation source of content
@@ -85,7 +85,7 @@ type ClusterExtensionSpec struct {
// catalog:
// packageName: example-package
//
- // +kubebuilder:validation:Required
+ // +required
Source SourceConfig `json:"source"`
// install is an optional field used to configure the installation options
@@ -114,7 +114,7 @@ type SourceConfig struct {
// +unionDiscriminator
//
//
- // +kubebuilder:validation:Required
+ // +required
SourceType string `json:"sourceType"`
// catalog is used to configure how information is sourced from a catalog.
@@ -180,7 +180,7 @@ type CatalogFilter struct {
// +kubebuilder:validation:MaxLength:=253
// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="packageName is immutable"
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$\")",message="packageName must be a valid DNS1123 subdomain. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters"
- // +kubebuilder:validation:Required
+ // +required
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.
@@ -370,7 +370,7 @@ type ServiceAccountReference struct {
// +kubebuilder:validation:MaxLength:=253
// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable"
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$\")",message="name must be a valid DNS1123 subdomain. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters"
- // +kubebuilder:validation:Required
+ // +required
Name string `json:"name"`
}
@@ -400,7 +400,7 @@ type CRDUpgradeSafetyPreflightConfig struct {
// performing an upgrade operation.
//
// +kubebuilder:validation:Enum:="None";"Strict"
- // +kubebuilder:validation:Required
+ // +required
Enforcement CRDUpgradeSafetyEnforcement `json:"enforcement"`
}
@@ -425,14 +425,14 @@ type BundleMetadata struct {
// hyphens (-) or periods (.), start and end with an alphanumeric character,
// and be no longer than 253 characters.
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$\")",message="packageName must be a valid DNS1123 subdomain. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters"
Name string `json:"name"`
// version is a required field and is a reference to the version that this bundle represents
// version follows the semantic versioning standard as defined in https://semver.org/.
//
- // +kubebuilder:validation:Required
+ // +required
// +kubebuilder:validation:XValidation:rule="self.matches(\"^([0-9]+)(\\\\.[0-9]+)?(\\\\.[0-9]+)?(-([-0-9A-Za-z]+(\\\\.[-0-9A-Za-z]+)*))?(\\\\+([-0-9A-Za-z]+(-\\\\.[-0-9A-Za-z]+)*))?\")",message="version must be well-formed semver"
Version string `json:"version"`
}
@@ -475,7 +475,7 @@ type ClusterExtensionInstallStatus struct {
// A "bundle" is a versioned set of content that represents the resources that
// need to be applied to a cluster to install a package.
//
- // +kubebuilder:validation:Required
+ // +required
Bundle BundleMetadata `json:"bundle"`
}
@@ -513,7 +513,7 @@ type ClusterExtensionList struct {
// items is a required list of ClusterExtension objects.
//
- // +kubebuilder:validation:Required
+ // +required
Items []ClusterExtension `json:"items"`
}