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

@@ -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 }}

helm/experimental.yaml

@@ -225,6 +225,93 @@ spec:
                     catalog:
                       packageName: example-package
                 properties:
+                  bundle:
+                    description: |-
+                      bundle is used to configure how information is sourced from a bundle.
+                      This field is required when sourceType is "Bundle", and forbidden otherwise.
+                    properties:
+                      ref:
+                        description: |-
+                          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"
+                        maxLength: 1000
+                        type: string
+                        x-kubernetes-validations:
+                        - message: must start with a valid domain. valid domains must
+                            be alphanumeric characters (lowercase and uppercase) separated
+                            by the "." character.
+                          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: a valid name is required. valid names must contain
+                            lowercase alphanumeric characters separated only by the
+                            ".", "_", "__", "-" characters.
+                          rule: self.find('(\\/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?((\\/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?)+)?)')
+                            != ""
+                        - message: must end with a digest or a tag
+                          rule: self.find('(@.*:)') != "" || self.find(':.*$') !=
+                            ""
+                        - message: tag is invalid. the tag must not be more than 127
+                            characters
+                          rule: 'self.find(''(@.*:)'') == "" ? (self.find('':.*$'')
+                            != "" ? self.find('':.*$'').substring(1).size() <= 127
+                            : true) : true'
+                        - message: tag is invalid. valid tags must begin with a word
+                            character (alphanumeric + "_") followed by word characters
+                            or ".", and "-" characters
+                          rule: 'self.find(''(@.*:)'') == "" ? (self.find('':.*$'')
+                            != "" ? self.find('':.*$'').matches('':[\\w][\\w.-]*$'')
+                            : true) : 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.
+                          rule: 'self.find(''(@.*:)'') != "" ? self.find(''(@.*:)'').matches(''(@[A-Za-z][A-Za-z0-9]*([-_+.][A-Za-z][A-Za-z0-9]*)*[:])'')
+                            : true'
+                        - message: digest is not valid. the encoded string must be
+                            at least 32 characters
+                          rule: 'self.find(''(@.*:)'') != "" ? self.find('':.*$'').substring(1).size()
+                            >= 32 : true'
+                        - message: digest is not valid. the encoded string must only
+                            contain hex characters (A-F, a-f, 0-9)
+                          rule: 'self.find(''(@.*:)'') != "" ? self.find('':.*$'').matches('':[0-9A-Fa-f]*$'')
+                            : true'
+                    required:
+                    - ref
+                    type: object
                   catalog:
                     description: |-
                       catalog is used to configure how information is sourced from a catalog.
@@ -474,13 +561,19 @@ spec:
                     description: |-
                       sourceType is a required reference to the type of install source.
 
-                      Allowed values are "Catalog"
+                      Allowed values are "Bundle" or "Catalog"
+
+                      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.
 
                       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:
+                    - Bundle
                     - Catalog
                     type: string
                 required: