From 80f9dbd72ccb270acb1ff57d24f530fa57c33ac0 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Thu, 10 Apr 2025 18:27:14 -0700 Subject: [PATCH] Move manual RBAC documentation to compositions page Add refs from other pages where it might come up. I also added a bit of detail and rephrased to address some Vale linter warnings. Signed-off-by: Nic Cope --- .../v2.0-preview/composition/compositions.md | 62 ++++++++++++++++++- .../get-started-with-composition.md | 7 +++ content/v2.0-preview/whats-new/_index.md | 34 +++------- 3 files changed, 74 insertions(+), 29 deletions(-) diff --git a/content/v2.0-preview/composition/compositions.md b/content/v2.0-preview/composition/compositions.md index 0deb452f..6cb95959 100644 --- a/content/v2.0-preview/composition/compositions.md +++ b/content/v2.0-preview/composition/compositions.md @@ -269,6 +269,64 @@ spec: # Removed for brevity ``` +### Grant access to composed resources + +Crossplane uses its [service account](https://kubernetes.io/docs/concepts/security/service-accounts/) +to create the composed resources that a function pipeline returns. + +Crossplane's service account has access to create, update, and delete any +resource installed by a [provider]({{}}), or +defined by an XRD. This includes all +[MRs]({{}}) and +[XRs]({{}}). It also has access to some types of +Kubernetes resources that it needs to function - for example it can create +deployments. + +You must grant Crossplane access to compose any other kind of resource. You do +this by creating an [RBAC ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). + + + +The ClusterRole must aggregate to Crossplane's primary ClusterRole using +[ClusterRole aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles). + + +Here's a ClusterRole that grants Crossplane access to manage +[CloudNativePG](https://cloudnative-pg.io) PostgreSQL clusters. + +``` yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cnpg:aggregate-to-crossplane + labels: + rbac.crossplane.io/aggregate-to-crossplane: "true" +rules: +- apiGroups: + - postgresql.cnpg.io + resources: + - clusters + verbs: + - "*" +``` + + + +The `rbac.crossplane.io/aggregate-to-crossplane: "true"` label is critical. It +configures the role to aggregate to Crossplane's primary cluster role. + + +{{}} +The [RBAC manager]({{}}) automatically +grants Crossplane access to MRs and XRs. The RBAC manager uses +[escalate access](https://kubernetes.io/docs/concepts/security/rbac-good-practices/#escalate-verb) +to grant Crossplane access that the RBAC manager doesn't have. + +The RBAC manager is an optional Crossplane component that's enabled by default. +**If you disable the RBAC manager, you must manually grant Crossplane access to +_any_ kind of resource you wish to compose - including XRs and MRs.** +{{< /hint >}} + ## Test a composition You can preview the output of any composition using the Crossplane CLI. You @@ -545,8 +603,8 @@ which composed resources it should create or update. If the function needs __extra resources__ to determine the desired state it can request any cluster-scoped resource Crossplane already has access to, either by -by name or labels through the returned RunFunctionResponse. Crossplane then -calls the function again including the requested __extra resources__ and the +name or labels through the returned RunFunctionResponse. Crossplane then calls +the function again including the requested __extra resources__ and the __context__ returned by the Function itself alongside the same __input__, __observed__ and __desired state__ of the previous RunFunctionRequest. Functions can iteratively request __extra resources__ if needed, but to avoid endlessly diff --git a/content/v2.0-preview/get-started/get-started-with-composition.md b/content/v2.0-preview/get-started/get-started-with-composition.md index a585b9aa..d7eb5ece 100644 --- a/content/v2.0-preview/get-started/get-started-with-composition.md +++ b/content/v2.0-preview/get-started/get-started-with-composition.md @@ -660,6 +660,13 @@ Functions can change the results of earlier functions in the pipeline. Crossplane uses the result returned by the last function. {{}} +{{}} +If you edit this composition to include a different kind of resource you might +need to grant Crossplane access to compose it. Read +[the composition documentation]({{}}) +to learn how to grant Crossplane access. +{{}} + ## Use the custom resource Crossplane now understands `App` custom resources. diff --git a/content/v2.0-preview/whats-new/_index.md b/content/v2.0-preview/whats-new/_index.md index dd8c2a08..1bd1903d 100644 --- a/content/v2.0-preview/whats-new/_index.md +++ b/content/v2.0-preview/whats-new/_index.md @@ -207,32 +207,12 @@ compose-pg@{animate: true} This opens composition to exciting new use cases - for example building custom app models with Crossplane. -### Beware Crossplane's default access - -Crossplane by default can only access a limited set of kubernetes resources beyond what gets configured by any providers. - -To grant access to additional resource resource types, create additional `ClusterRoles` and include them in the default Crossplane `ClusterRole` through [aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles). Crossplane's default ClusterRole aggregates using a selector for the label `rbac.crossplane.io/aggregate-to-crossplane: "true"` - -If you don't include this you may experience RBAC issues composing third party custom resources. - -Here is an example of allowing Crossplane handle the lifecycle of CloudNativePG PostgreSQL `Cluster`. - -``` yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: cnpg:aggregate-to-crossplane - labels: - app: crossplane - rbac.crossplane.io/aggregate-to-crossplane: "true" -rules: -- apiGroups: - - postgresql.cnpg.io - resources: - - clusters - verbs: - - "*" -``` +{{}} +You must grant Crossplane access to compose resources that aren't Crossplane +resources like MRs or XRs. Read +[the composition documentation]({{}}) +to learn how to grant Crossplane access. +{{}} ## Backward compatibility @@ -263,4 +243,4 @@ upgrade from v1.x to Crossplane v2 without breaking changes. Existing Compositions will require minor updates to work with Crossplane v2 style XRs. A migration guide will be available closer to the final release of Crossplane v2. - \ No newline at end of file +