Make ServiceAccount optional in experimental channel

joelanford · claude · joelanford · commit 1094bc94bd41 · 2025-11-21T15:36:26.000-05:00
This commit updates the ClusterExtension API to make the serviceAccount field optional in the experimental channel while keeping it required in the standard channel. Changes to ClusterExtension API: - Added <opcon:standard:validation:Required> and <opcon:experimental:validation:Optional> tags to ServiceAccount field - Added channel-specific descriptions for serviceAccount behavior: - Standard: Service account is required - Experimental: If omitted, authenticates as synthetic user "olmv1:clusterextensions:<clusterExtensionName>" with group "olmv1:clusterextensions" - Added channel-specific descriptions for namespace field explaining the relationship with serviceAccount - Updated ServiceAccountReference documentation to remove namespace requirement text - Changed JSON tags to use omitzero for optional behavior Generated artifacts updated: - CRDs (standard and experimental channels) - API reference documentation - All manifest files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/api/v1/clusterextension_types.go b/api/v1/clusterextension_types.go
@@ -49,12 +49,19 @@ const (
 // ClusterExtensionSpec defines the desired state of ClusterExtension
 type ClusterExtensionSpec struct {
 	// namespace is a reference to a Kubernetes namespace.
-	// This is the namespace in which the provided ServiceAccount must exist.
-	// It also designates the default namespace where namespace-scoped resources
+	//
+	// This 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.
 	//
+	// <opcon:standard:description>
+	// This is also the namespace of the referenced service account.
+	// </opcon:standard:description>
+	// <opcon:experimental:description>
+	// This is also the namespace of the referenced service account, if specified.
+	// </opcon:experimental:description>
+	//
 	// namespace 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
@@ -69,12 +76,24 @@ type ClusterExtensionSpec struct {
 
 	// serviceAccount is a reference to a ServiceAccount used to perform all interactions
 	// with the cluster that are required to manage the extension.
+	// <opcon:standard:description>
 	// The ServiceAccount must be configured with the necessary permissions to perform these interactions.
-	// The ServiceAccount must exist in the namespace referenced in the spec.
+	//
 	// serviceAccount is required.
+	// </opcon:standard:description>
 	//
-	// +kubebuilder:validation:Required
-	ServiceAccount ServiceAccountReference `json:"serviceAccount"`
+	// <opcon:experimental:description>
+	// If serviceAccount is specified, OLM will authenticate as that service account.
+	// Otherwise, operator-controller will authenticate as:
+	//   - User:  "olm:clusterextension:<clusterExtensionName>"
+	//   - Group: "olm:clusterextensions"
+	//
+	// The authenticated user must be configured with the necessary permissions to perform these interactions.
+	// </opcon:experimental:description>
+	//
+	// <opcon:standard:validation:Required>
+	// <opcon:experimental:validation:Optional>
+	ServiceAccount ServiceAccountReference `json:"serviceAccount,omitzero"`
 
 	// source is a required field which selects the installation source of content
 	// for this ClusterExtension. Selection is performed by setting the sourceType.
@@ -374,14 +393,12 @@ type CatalogFilter struct {
 	UpgradeConstraintPolicy UpgradeConstraintPolicy `json:"upgradeConstraintPolicy,omitempty"`
 }
 
-// ServiceAccountReference identifies the serviceAccount used fo install a ClusterExtension.
+// ServiceAccountReference identifies the serviceAccount name used to manage a ClusterExtension.
 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 must exist in the installNamespace.
-	//
 	// name 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,
@@ -404,7 +421,7 @@ type ServiceAccountReference struct {
 	// +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
-	Name string `json:"name"`
+	Name string `json:"name,omitempty"`
 }
 
 // PreflightConfig holds the configuration for the preflight checks.  If used, at least one preflight check must be non-nil.
diff --git a/docs/api-reference/olmv1-api-reference.md b/docs/api-reference/olmv1-api-reference.md
@@ -339,8 +339,8 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `namespace` _string_ | namespace is a reference to a Kubernetes namespace.<br />This is the namespace in which the provided ServiceAccount must exist.<br />It also designates the default namespace where namespace-scoped resources<br />for the extension are applied to the cluster.<br />Some extensions may contain namespace-scoped resources to be applied in other namespaces.<br />This namespace must exist.<br />namespace is required, immutable, and follows the DNS label standard<br />as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters or hyphens (-),<br />start and end with an alphanumeric character, and be no longer than 63 characters<br />[RFC 1123]: https://tools.ietf.org/html/rfc1123 |  | MaxLength: 63 <br />Required: \{\} <br /> |
-| `serviceAccount` _[ServiceAccountReference](#serviceaccountreference)_ | serviceAccount is a reference to a ServiceAccount used to perform all interactions<br />with the cluster that are required to manage the extension.<br />The ServiceAccount must be configured with the necessary permissions to perform these interactions.<br />The ServiceAccount must exist in the namespace referenced in the spec.<br />serviceAccount is required. |  | Required: \{\} <br /> |
+| `namespace` _string_ | namespace is a reference to a Kubernetes namespace.<br />This designates the default namespace where namespace-scoped resources<br />for the extension are applied to the cluster.<br />Some extensions may contain namespace-scoped resources to be applied in other namespaces.<br />This namespace must exist.<br /><opcon:standard:description><br />This is also the namespace of the referenced service account.<br /></opcon:standard:description><br /><opcon:experimental:description><br />This is also the namespace of the referenced service account, if specified.<br /></opcon:experimental:description><br />namespace is required, immutable, and follows the DNS label standard<br />as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters or hyphens (-),<br />start and end with an alphanumeric character, and be no longer than 63 characters<br />[RFC 1123]: https://tools.ietf.org/html/rfc1123 |  | MaxLength: 63 <br />Required: \{\} <br /> |
+| `serviceAccount` _[ServiceAccountReference](#serviceaccountreference)_ | serviceAccount is a reference to a ServiceAccount used to perform all interactions<br />with the cluster that are required to manage the extension.<br /><opcon:standard:description><br />The ServiceAccount must be configured with the necessary permissions to perform these interactions.<br />serviceAccount is required.<br /></opcon:standard:description><br /><opcon:experimental:description><br />If serviceAccount is specified, OLM will authenticate as that service account.<br />Otherwise, operator-controller will authenticate as:<br />  - User:  "olm:clusterextension:<clusterExtensionName>"<br />  - Group: "olm:clusterextensions"<br />The authenticated user must be configured with the necessary permissions to perform these interactions.<br /></opcon:experimental:description><br /><opcon:standard:validation:Required><br /><opcon:experimental:validation:Optional> |  |  |
 | `source` _[SourceConfig](#sourceconfig)_ | source is a required field which selects the installation source of content<br />for this ClusterExtension. Selection is performed by setting the sourceType.<br />Catalog is currently the only implemented sourceType, and setting the<br />sourcetype to "Catalog" requires the catalog field to also be defined.<br />Below is a minimal example of a source definition (in yaml):<br />source:<br />  sourceType: Catalog<br />  catalog:<br />    packageName: example-package |  | Required: \{\} <br /> |
 | `install` _[ClusterExtensionInstallConfig](#clusterextensioninstallconfig)_ | install is an optional field used to configure the installation options<br />for the ClusterExtension such as the pre-flight check configuration. |  |  |
 | `config` _[ClusterExtensionConfig](#clusterextensionconfig)_ | config is an optional field used to specify bundle specific configuration<br />used to configure the bundle. Configuration is bundle specific and a bundle may provide<br />a configuration schema. When not specified, the default configuration of the resolved bundle will be used.<br />config is validated against a configuration schema provided by the resolved bundle. If the bundle does not provide<br />a configuration schema the final manifests will be derived on a best-effort basis. More information on how<br />to configure the bundle should be found in its end-user documentation.<br /><opcon:experimental> |  |  |
@@ -439,7 +439,7 @@ _Appears in:_
 
 
 
-ServiceAccountReference identifies the serviceAccount used fo install a ClusterExtension.
+ServiceAccountReference identifies the serviceAccount name used to manage a ClusterExtension.
 
 
 
@@ -448,7 +448,7 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `name` _string_ | name is a required, immutable reference to the name of the ServiceAccount<br />to be used for installation and management of the content for the package<br />specified in the packageName field.<br />This ServiceAccount must exist in the installNamespace.<br />name follows the DNS subdomain standard as defined in [RFC 1123].<br />It must contain only lowercase alphanumeric characters,<br />hyphens (-) or periods (.), start and end with an alphanumeric character,<br />and be no longer than 253 characters.<br />Some examples of valid values are:<br />  - some-serviceaccount<br />  - 123-serviceaccount<br />  - 1-serviceaccount-2<br />  - someserviceaccount<br />  - some.serviceaccount<br />Some examples of invalid values are:<br />  - -some-serviceaccount<br />  - some-serviceaccount-<br />[RFC 1123]: https://tools.ietf.org/html/rfc1123 |  | MaxLength: 253 <br />Required: \{\} <br /> |
+| `name` _string_ | name is a required, immutable reference to the name of the ServiceAccount<br />to be used for installation and management of the content for the package<br />specified in the packageName field.<br />name follows the DNS subdomain standard as defined in [RFC 1123].<br />It must contain only lowercase alphanumeric characters,<br />hyphens (-) or periods (.), start and end with an alphanumeric character,<br />and be no longer than 253 characters.<br />Some examples of valid values are:<br />  - some-serviceaccount<br />  - 123-serviceaccount<br />  - 1-serviceaccount-2<br />  - someserviceaccount<br />  - some.serviceaccount<br />Some examples of invalid values are:<br />  - -some-serviceaccount<br />  - some-serviceaccount-<br />[RFC 1123]: https://tools.ietf.org/html/rfc1123 |  | MaxLength: 253 <br />Required: \{\} <br /> |
 
 
 #### SourceConfig
diff --git a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml
@@ -151,12 +151,14 @@ spec:
               namespace:
                 description: |-
                   namespace is a reference to a Kubernetes namespace.
-                  This is the namespace in which the provided ServiceAccount must exist.
-                  It also designates the default namespace where namespace-scoped resources
+
+                  This 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.
 
+                  This is also the namespace of the referenced service account, if specified.
+
                   namespace 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
@@ -173,18 +175,20 @@ spec:
                 description: |-
                   serviceAccount is a reference to 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.
-                  serviceAccount is required.
+
+                  If serviceAccount is specified, OLM will authenticate as that service account.
+                  Otherwise, operator-controller will authenticate as:
+                    - User:  "olm:clusterextension:<clusterExtensionName>"
+                    - Group: "olm:clusterextensions"
+
+                  The authenticated user must be configured with the necessary permissions to perform these interactions.
                 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 must exist in the installNamespace.
-
                       name 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,
@@ -498,7 +502,6 @@ spec:
                     has(self.catalog) : !has(self.catalog)'
             required:
             - namespace
-            - serviceAccount
             - source
             type: object
           status:
diff --git a/helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml b/helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml
@@ -112,12 +112,14 @@ spec:
               namespace:
                 description: |-
                   namespace is a reference to a Kubernetes namespace.
-                  This is the namespace in which the provided ServiceAccount must exist.
-                  It also designates the default namespace where namespace-scoped resources
+
+                  This 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.
 
+                  This is also the namespace of the referenced service account.
+
                   namespace 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
@@ -134,8 +136,9 @@ spec:
                 description: |-
                   serviceAccount is a reference to 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.
+
                   serviceAccount is required.
                 properties:
                   name:
@@ -144,8 +147,6 @@ spec:
                       to be used for installation and management of the content for the package
                       specified in the packageName field.
 
-                      This ServiceAccount must exist in the installNamespace.
-
                       name 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,
diff --git a/internal/operator-controller/controllers/clusterextension_admission_test.go b/internal/operator-controller/controllers/clusterextension_admission_test.go
@@ -349,7 +349,7 @@ func TestClusterExtensionAdmissionServiceAccount(t *testing.T) {
 		{"dot-separated", "dotted.name", ""},
 		{"longest valid service account name", strings.Repeat("x", 253), ""},
 		{"too long service account name", strings.Repeat("x", 254), tooLongError},
-		{"no service account name", "", regexMismatchError},
+		{"no service account name", "", ""},
 		{"spaces", "spaces spaces", regexMismatchError},
 		{"capitalized", "Capitalized", regexMismatchError},
 		{"camel case", "camelCase", regexMismatchError},
diff --git a/manifests/experimental-e2e.yaml b/manifests/experimental-e2e.yaml
@@ -939,12 +939,14 @@ spec:
               namespace:
                 description: |-
                   namespace is a reference to a Kubernetes namespace.
-                  This is the namespace in which the provided ServiceAccount must exist.
-                  It also designates the default namespace where namespace-scoped resources
+
+                  This 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.
 
+                  This is also the namespace of the referenced service account, if specified.
+
                   namespace 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
@@ -961,18 +963,20 @@ spec:
                 description: |-
                   serviceAccount is a reference to 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.
-                  serviceAccount is required.
+
+                  If serviceAccount is specified, OLM will authenticate as that service account.
+                  Otherwise, operator-controller will authenticate as:
+                    - User:  "olm:clusterextension:<clusterExtensionName>"
+                    - Group: "olm:clusterextensions"
+
+                  The authenticated user must be configured with the necessary permissions to perform these interactions.
                 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 must exist in the installNamespace.
-
                       name 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,
@@ -1286,7 +1290,6 @@ spec:
                     has(self.catalog) : !has(self.catalog)'
             required:
             - namespace
-            - serviceAccount
             - source
             type: object
           status:
diff --git a/manifests/experimental.yaml b/manifests/experimental.yaml
diff --git a/manifests/standard-e2e.yaml b/manifests/standard-e2e.yaml
diff --git a/manifests/standard.yaml b/manifests/standard.yaml
