permissions preflight: add clusterextension.status.missingRules

Signed-off-by: Joe Lanford <[email protected]>

Author: joelanford

api/v1/clusterextension_types.go

@@ -17,6 +17,7 @@ limitations under the License.
 package v1
 
 import (
+	rbacv1 "k8s.io/api/rbac/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
@@ -454,6 +455,47 @@ type ClusterExtensionStatus struct {
 	//
 	// +optional
 	Install *ClusterExtensionInstallStatus `json:"install,omitempty"`
+
+	// missing rules is a list of rules (by namespace) that the cluster extension's service account is likely lacking,
+	// but which are needed to be able to fully manage all resources in the resolved cluster extension manifest.
+	//
+	// +listType=atomic
+	// +optional
+	// +kubebuilder:validation:MaxItems:=64
+	MissingRules []ClusterExtensionMissingRulesItem `json:"missingRules,omitempty"`
+}
+
+// ClusterExtensionMissingRulesItem represents the set of rules that are missing in a given scope.
+type ClusterExtensionMissingRulesItem struct {
+	// namespace is a reference to a Kubernetes namespace.
+	// This is the namespace where the ClusterExtension's service account is lacking
+	// the rules provided in missingRules.
+	//
+	// When namespace is non-empty, one or more RoleBindings should be created to reference
+	// Roles and/or ClusterRoles that provided the missingRules in the namespace.
+	//
+	// When namespace is the empty string, one or more ClusterRoleBindings should be created
+	// to reference ClusterRoles that provide the missingRules cluster-wide.
+	//
+	// namespace is required 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
+	//
+	// +kubebuilder:validation:MaxLength:=63
+	// +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
+	Namespace string `json:"namespace"`
+
+	// missingRules is a list of RBAC policy rules that the ClusterExtension's service account lacks in the
+	// namespace defined in the namespace field.
+	//
+	// missingRules is required.
+	//
+	// +listType=atomic
+	// +kubebuilder:validation:MaxItems:=1024
+	MissingRules []rbacv1.PolicyRule `json:"missingRules"`
 }
 
 // ClusterExtensionInstallStatus is a representation of the status of the identified bundle.

api/v1/zz_generated.deepcopy.go

@@ -581,6 +581,100 @@ spec:
                 required:
                 - bundle
                 type: object
+              missingRules:
+                description: |-
+                  missing rules is a list of rules (by namespace) that the cluster extension's service account is likely lacking,
+                  but which are needed to be able to fully manage all resources in the resolved cluster extension manifest.
+                items:
+                  description: ClusterExtensionMissingRulesItem represents the set
+                    of rules that are missing in a given scope.
+                  properties:
+                    missingRules:
+                      description: |-
+                        missingRules is a list of RBAC policy rules that the ClusterExtension's service account lacks in the
+                        namespace defined in the namespace field.
+
+                        missingRules is required.
+                      items:
+                        description: |-
+                          PolicyRule holds information that describes a policy rule, but does not contain information
+                          about who the rule applies to or which namespace the rule applies to.
+                        properties:
+                          apiGroups:
+                            description: |-
+                              APIGroups is the name of the APIGroup that contains the resources.  If multiple API groups are specified, any action requested against one of
+                              the enumerated resources in any API group will be allowed. "" represents the core API group and "*" represents all API groups.
+                            items:
+                              type: string
+                            type: array
+                            x-kubernetes-list-type: atomic
+                          nonResourceURLs:
+                            description: |-
+                              NonResourceURLs is a set of partial urls that a user should have access to.  *s are allowed, but only as the full, final step in the path
+                              Since non-resource URLs are not namespaced, this field is only applicable for ClusterRoles referenced from a ClusterRoleBinding.
+                              Rules can either apply to API resources (such as "pods" or "secrets") or non-resource URL paths (such as "/api"),  but not both.
+                            items:
+                              type: string
+                            type: array
+                            x-kubernetes-list-type: atomic
+                          resourceNames:
+                            description: ResourceNames is an optional white list of
+                              names that the rule applies to.  An empty set means
+                              that everything is allowed.
+                            items:
+                              type: string
+                            type: array
+                            x-kubernetes-list-type: atomic
+                          resources:
+                            description: Resources is a list of resources this rule
+                              applies to. '*' represents all resources.
+                            items:
+                              type: string
+                            type: array
+                            x-kubernetes-list-type: atomic
+                          verbs:
+                            description: Verbs is a list of Verbs that apply to ALL
+                              the ResourceKinds contained in this rule. '*' represents
+                              all verbs.
+                            items:
+                              type: string
+                            type: array
+                            x-kubernetes-list-type: atomic
+                        required:
+                        - verbs
+                        type: object
+                      maxItems: 1024
+                      type: array
+                      x-kubernetes-list-type: atomic
+                    namespace:
+                      description: |-
+                        namespace is a reference to a Kubernetes namespace.
+                        This is the namespace where the ClusterExtension's service account is lacking
+                        the rules provided in missingRules.
+
+                        When namespace is non-empty, one or more RoleBindings should be created to reference
+                        Roles and/or ClusterRoles that provided the missingRules in the namespace.
+
+                        When namespace is the empty string, one or more ClusterRoleBindings should be created
+                        to reference ClusterRoles that provide the missingRules cluster-wide.
+
+                        namespace is required 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
+                      type: string
+                      x-kubernetes-validations:
+                      - message: namespace must be a valid DNS1123 label
+                        rule: self.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+                  required:
+                  - missingRules
+                  - namespace
+                  type: object
+                maxItems: 64
+                type: array
+                x-kubernetes-list-type: atomic
             type: object
         type: object
     served: true

config/base/operator-controller/crd/bases/olm.operatorframework.io_clusterextensions.yaml

@@ -292,6 +292,23 @@ ClusterExtensionList contains a list of ClusterExtension
 | `items` _[ClusterExtension](#clusterextension) array_ | items is a required list of ClusterExtension objects. |  | Required: \{\} <br /> |
 
 
+#### ClusterExtensionMissingRulesItem
+
+
+
+ClusterExtensionMissingRulesItem represents the set of rules that are missing in a given scope.
+
+
+
+_Appears in:_
+- [ClusterExtensionStatus](#clusterextensionstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `namespace` _string_ | namespace is a reference to a Kubernetes namespace.<br />This is the namespace where the ClusterExtension's service account is lacking<br />the rules provided in missingRules.<br /><br />When namespace is non-empty, one or more RoleBindings should be created to reference<br />Roles and/or ClusterRoles that provided the missingRules in the namespace.<br /><br />When namespace is the empty string, one or more ClusterRoleBindings should be created<br />to reference ClusterRoles that provide the missingRules cluster-wide.<br /><br />namespace is required 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 /><br />[RFC 1123]: https://tools.ietf.org/html/rfc1123 |  | MaxLength: 63 <br />Required: \{\} <br /> |
+| `missingRules` _[PolicyRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#policyrule-v1-rbac) array_ | missingRules is a list of RBAC policy rules that the ClusterExtension's service account lacks in the<br />namespace defined in the namespace field.<br /><br />missingRules is required. |  | MaxItems: 1024 <br /> |
+
+
 #### ClusterExtensionSpec
 
 
@@ -326,6 +343,7 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | The set of condition types which apply to all spec.source variations are Installed and Progressing.<br /><br />The Installed condition represents whether or not the bundle has been installed for this ClusterExtension.<br />When Installed is True and the Reason is Succeeded, the bundle has been successfully installed.<br />When Installed is False and the Reason is Failed, the bundle has failed to install.<br /><br />The Progressing condition represents whether or not the ClusterExtension is advancing towards a new state.<br />When Progressing is True and the Reason is Succeeded, the ClusterExtension is making progress towards a new state.<br />When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts.<br />When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery.<br /><br />When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition.<br />These are indications from a package owner to guide users away from a particular package, channel, or bundle.<br />BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog.<br />ChannelDeprecated is set if the requested channel is marked deprecated in the catalog.<br />PackageDeprecated is set if the requested package is marked deprecated in the catalog.<br />Deprecated is a rollup condition that is present when any of the deprecated conditions are present. |  |  |
 | `install` _[ClusterExtensionInstallStatus](#clusterextensioninstallstatus)_ | install is a representation of the current installation status for this ClusterExtension. |  |  |
+| `missingRules` _[ClusterExtensionMissingRulesItem](#clusterextensionmissingrulesitem) array_ | missing rules is a list of rules (by namespace) that the cluster extension's service account is likely lacking,<br />but which are needed to be able to fully manage all resources in the resolved cluster extension manifest. |  | MaxItems: 64 <br /> |
 
 
 #### ImageSource

docs/api-reference/operator-controller-api-reference.md

@@ -2,6 +2,7 @@ package applier
 
 import (
 	"bytes"
+	"cmp"
 	"context"
 	"errors"
 	"fmt"
@@ -105,14 +106,18 @@ func (h *Helm) Apply(ctx context.Context, contentFS fs.FS, ext *ocv1.ClusterExte
 
 		var preAuthErrors []error
 		if len(missingRules) > 0 {
-			var missingRuleDescriptions []string
+			var missingRulesItems []ocv1.ClusterExtensionMissingRulesItem
 			for ns, policyRules := range missingRules {
-				for _, rule := range policyRules {
-					missingRuleDescriptions = append(missingRuleDescriptions, ruleDescription(ns, rule))
-				}
+				missingRulesItems = append(missingRulesItems, ocv1.ClusterExtensionMissingRulesItem{
+					Namespace:    ns,
+					MissingRules: policyRules,
+				})
 			}
-			slices.Sort(missingRuleDescriptions)
-			preAuthErrors = append(preAuthErrors, fmt.Errorf("service account lacks permission to manage cluster extension:\n  %s", strings.Join(missingRuleDescriptions, "\n  ")))
+			slices.SortFunc(missingRulesItems, func(a, b ocv1.ClusterExtensionMissingRulesItem) int {
+				return cmp.Compare(a.Namespace, b.Namespace)
+			})
+			ext.Status.MissingRules = missingRulesItems
+			preAuthErrors = append(preAuthErrors, fmt.Errorf("service account lacks permission to manage cluster extension"))
 		}
 		if err != nil {
 			preAuthErrors = append(preAuthErrors, fmt.Errorf("authorization evaluation error: %w", err))