Add experimental, feature-gated support for resolving bundles directly from their image reference

Signed-off-by: Joe Lanford <joe.lanford@gmail.com>

Author: joelanford

api/v1/clusterextension_types.go

@@ -108,27 +108,47 @@ type ClusterExtensionSpec struct {
 	Config *ClusterExtensionConfig `json:"config,omitempty"`
 }
 
-const SourceTypeCatalog = "Catalog"
+const (
+	SourceTypeBundle  = "Bundle"
+	SourceTypeCatalog = "Catalog"
+)
 
 // SourceConfig is a discriminated union which selects the installation source.
 //
 // +union
+// <opcon:experimental:validation:XValidation:rule="has(self.sourceType) && self.sourceType == 'Bundle' ? has(self.bundle) : !has(self.bundle)",message="bundle is required when sourceType is Bundle, and forbidden otherwise">
 // +kubebuilder:validation:XValidation:rule="has(self.sourceType) && self.sourceType == 'Catalog' ? has(self.catalog) : !has(self.catalog)",message="catalog is required when sourceType is Catalog, and forbidden otherwise"
 type SourceConfig struct {
 	// sourceType is a required reference to the type of install source.
 	//
-	// Allowed values are "Catalog"
+	//
+	// Allowed values are <opcon:experimental:description>"Bundle" or </opcon:experimental:description>"Catalog"
+	//
+	// <opcon:experimental:description>
+	// When this field is set to "Bundle", the bundle of content to install
+	// is specified directly. In this case, no interaction with ClusterCatalog
+	// resources is necessary. When using the Bundle sourceType, the bundle
+	// field must also be set.
+	// </opcon:experimental:description>
 	//
 	// 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"
+	// <opcon:experimental:validation:Enum=Bundle;Catalog>
+	// <opcon:standard:validation:Enum=Catalog>
 	// +kubebuilder:validation:Required
 	SourceType string `json:"sourceType"`
 
+	// bundle is used to configure how information is sourced from a bundle.
+	// This field is required when sourceType is "Bundle", and forbidden otherwise.
+	//
+	// +optional.
+	// <opcon:experimental>
+	Bundle *BundleSource `json:"bundle,omitempty"`
+
 	// catalog is used to configure how information is sourced from a catalog.
 	// This field is required when sourceType is "Catalog", and forbidden otherwise.
 	//
@@ -180,6 +200,60 @@ type ClusterExtensionConfig struct {
 	Inline *apiextensionsv1.JSON `json:"inline,omitempty"`
 }
 
+// BundleSource defines the configuration used to retrieve a bundle directly from
+// its OCI-based image reference.
+type BundleSource struct {
+	// ref allows users to define the reference to a container image containing bundle contents.
+	// ref is required.
+	// ref can not be more than 1000 characters.
+	//
+	// A reference can be broken down into 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/bundle", "bundle", "my-bundle.prod".
+	// An example of the domain and name parts of a reference being combined is "quay.io/operatorhubio/bundle".
+	//
+	// 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"
+	//
+	// +kubebuilder:validation: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."
+	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != \"\" || self.find(':.*$') != \"\"",message="must end with a digest or a tag"
+	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') == \"\" ? (self.find(':.*$') != \"\" ? self.find(':.*$').substring(1).size() <= 127 : true) : true",message="tag is invalid. the tag must not be more than 127 characters"
+	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') == \"\" ? (self.find(':.*$') != \"\" ? self.find(':.*$').matches(':[\\\\w][\\\\w.-]*$') : true) : true",message="tag is invalid. valid tags must begin with a word character (alphanumeric + \"_\") followed by word characters or \".\", and \"-\" characters"
+	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != \"\" ? self.find('(@.*:)').matches('(@[A-Za-z][A-Za-z0-9]*([-_+.][A-Za-z][A-Za-z0-9]*)*[:])') : true",message="digest algorithm is not valid. valid algorithms must start with an uppercase or lowercase alpha character followed by alphanumeric characters and may contain the \"-\", \"_\", \"+\", and \".\" characters."
+	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != \"\" ? self.find(':.*$').substring(1).size() >= 32 : true",message="digest is not valid. the encoded string must be at least 32 characters"
+	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != \"\" ? self.find(':.*$').matches(':[0-9A-Fa-f]*$') : true",message="digest is not valid. the encoded string must only contain hex characters (A-F, a-f, 0-9)"
+	Ref string `json:"ref"`
+}
+
 // CatalogFilter defines the attributes used to identify and filter content from a catalog.
 type CatalogFilter struct {
 	// packageName is a reference to the name of the package to be installed

api/v1/zz_generated.deepcopy.go

@@ -404,7 +404,8 @@ func run() error {
 		return httputil.BuildHTTPClient(cpwCatalogd)
 	})
 
-	resolver := &resolve.CatalogResolver{
+	resolver := &resolve.MultiResolver{}
+	resolver.RegisterType(ocv1.SourceTypeCatalog, &resolve.CatalogResolver{
 		WalkCatalogsFunc: resolve.CatalogWalker(
 			func(ctx context.Context, option ...client.ListOption) ([]ocv1.ClusterCatalog, error) {
 				var catalogs ocv1.ClusterCatalogList
@@ -418,6 +419,12 @@ func run() error {
 		Validations: []resolve.ValidationFunc{
 			resolve.NoDependencyValidation,
 		},
+	})
+	if features.OperatorControllerFeatureGate.Enabled(features.DirectBundleInstall) {
+		resolver.RegisterType(ocv1.SourceTypeBundle, &resolve.BundleResolver{
+			ImagePuller: imagePuller,
+			ImageCache:  imageCache,
+		})
 	}
 
 	aeClient, err := apiextensionsv1client.NewForConfig(mgr.GetConfig())

cmd/operator-controller/main.go

@@ -50,6 +50,23 @@ _Appears in:_
 | `version` _string_ | version is a required field and is a reference to the version that this bundle represents<br />version follows the semantic versioning standard as defined in https://semver.org/. |  | Required: \{\} <br /> |
 
 
+#### BundleSource
+
+
+
+BundleSource defines the configuration used to retrieve a bundle directly from
+its OCI-based image reference.
+
+
+
+_Appears in:_
+- [SourceConfig](#sourceconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `ref` _string_ | ref allows users to define the reference to a container image containing bundle contents.<br />ref is required.<br />ref can not be more than 1000 characters.<br /><br />A reference can be broken down into 3 parts - the domain, name, and identifier.<br /><br />The domain is typically the registry where an image is located.<br />It must be alphanumeric characters (lowercase and uppercase) separated by the "." character.<br />Hyphenation is allowed, but the domain must start and end with alphanumeric characters.<br />Specifying a port to use is also allowed by adding the ":" character followed by numeric values.<br />The port must be the last value in the domain.<br />Some examples of valid domain values are "registry.mydomain.io", "quay.io", "my-registry.io:8080".<br /><br />The name is typically the repository in the registry where an image is located.<br />It must contain lowercase alphanumeric characters separated only by the ".", "_", "__", "-" characters.<br />Multiple names can be concatenated with the "/" character.<br />The domain and name are combined using the "/" character.<br />Some examples of valid name values are "operatorhubio/bundle", "bundle", "my-bundle.prod".<br />An example of the domain and name parts of a reference being combined is "quay.io/operatorhubio/bundle".<br /><br />The identifier is typically the tag or digest for an image reference and is present at the end of the reference.<br />It starts with a separator character used to distinguish the end of the name and beginning of the identifier.<br />For a digest-based reference, the "@" character is the separator.<br />For a tag-based reference, the ":" character is the separator.<br />An identifier is required in the reference.<br /><br />Digest-based references must contain an algorithm reference immediately after the "@" separator.<br />The algorithm reference must be followed by the ":" character and an encoded string.<br />The algorithm must start with an uppercase or lowercase alpha character followed by alphanumeric characters and may contain the "-", "_", "+", and "." characters.<br />Some examples of valid algorithm values are "sha256", "sha256+b64u", "multihash+base58".<br />The encoded string following the algorithm must be hex digits (a-f, A-F, 0-9) and must be a minimum of 32 characters.<br /><br />Tag-based references must begin with a word character (alphanumeric + "_") followed by word characters or ".", and "-" characters.<br />The tag must not be longer than 127 characters.<br /><br />An example of a valid digest-based image reference is "quay.io/operatorhubio/catalog@sha256:200d4ddb2a73594b91358fe6397424e975205bfbe44614f5846033cad64b3f05"<br />An example of a valid tag-based image reference is "quay.io/operatorhubio/catalog:latest" |  | MaxLength: 1000 <br />Required: \{\} <br /> |
+
+
 #### CRDUpgradeSafetyEnforcement
 
 _Underlying type:_ _string_
@@ -459,13 +476,17 @@ _Appears in:_
 SourceConfig is a discriminated union which selects the installation source.
 
 
+<opcon:experimental:validation:XValidation:rule="has(self.sourceType) && self.sourceType == 'Bundle' ? has(self.bundle) : !has(self.bundle)",message="bundle is required when sourceType is Bundle, and forbidden otherwise">
+
+
 
 _Appears in:_
 - [ClusterExtensionSpec](#clusterextensionspec)
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `sourceType` _string_ | sourceType is a required reference to the type of install source.<br /><br />Allowed values are "Catalog"<br /><br />When this field is set to "Catalog", information for determining the<br />appropriate bundle of content to install will be fetched from<br />ClusterCatalog resources existing on the cluster.<br />When using the Catalog sourceType, the catalog field must also be set. |  | Enum: [Catalog] <br />Required: \{\} <br /> |
+| `sourceType` _string_ | sourceType is a required reference to the type of install source.<br /><br />Allowed values are <opcon:experimental:description>"Bundle" or </opcon:experimental:description>"Catalog"<br /><br /><opcon:experimental:description><br />When this field is set to "Bundle", the bundle of content to install<br />is specified directly. In this case, no interaction with ClusterCatalog<br />resources is necessary. When using the Bundle sourceType, the bundle<br />field must also be set.<br /></opcon:experimental:description><br /><br />When this field is set to "Catalog", information for determining the<br />appropriate bundle of content to install will be fetched from<br />ClusterCatalog resources existing on the cluster.<br />When using the Catalog sourceType, the catalog field must also be set.<br /><br /><opcon:experimental:validation:Enum=Bundle;Catalog><br /><opcon:standard:validation:Enum=Catalog> |  | Required: \{\} <br /> |
+| `bundle` _[BundleSource](#bundlesource)_ | bundle is used to configure how information is sourced from a bundle.<br />This field is required when sourceType is "Bundle", and forbidden otherwise.<br /><br /><opcon:experimental> |  |  |
 | `catalog` _[CatalogFilter](#catalogfilter)_ | catalog is used to configure how information is sourced from a catalog.<br />This field is required when sourceType is "Catalog", and forbidden otherwise. |  |  |
 
 

docs/api-reference/olmv1-api-reference.md

@@ -126,6 +126,7 @@ require (
 	github.com/gobuffalo/flect v1.0.3 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang-migrate/migrate/v4 v4.19.0 // indirect
 	github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/btree v1.1.3 // indirect

go.mod

@@ -258,13 +258,13 @@ func formatDescription(description string, channel string, name string) string {
 	startTag := "<opcon:experimental:description>"
 	endTag := "</opcon:experimental:description>"
 	if channel == StandardChannel && strings.Contains(description, startTag) {
-		regexPattern := `\n*` + regexp.QuoteMeta(startTag) + `(?s:(.*?))` + regexp.QuoteMeta(endTag) + `\n*`
+		regexPattern := regexp.QuoteMeta(startTag) + `(?s:(.*?))` + regexp.QuoteMeta(endTag)
 		re := regexp.MustCompile(regexPattern)
 		match := re.FindStringSubmatch(description)
 		if len(match) != 2 {
 			log.Fatalf("Invalid <opcon:experimental:description> tag for %s", name)
 		}
-		description = re.ReplaceAllString(description, "\n\n")
+		description = re.ReplaceAllString(description, "")
 	} else {
 		description = strings.ReplaceAll(description, startTag, "")
 		description = strings.ReplaceAll(description, endTag, "")

hack/tools/crd-generator/main.go

@@ -11,6 +11,7 @@ operatorControllerFeatures:
   - PreflightPermissions
   - HelmChartSupport
   - BoxcutterRuntime
+  - DirectBundleInstall
 
 # List of enabled experimental features for catalogd
 # Use with {{- if has "FeatureGate" .Values.catalogdFeatures }}