From de2e8180960c27b16dd0066509d622225c605ddb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Schmitz=20von=20H=C3=BClst?= Date: Mon, 20 Jul 2026 01:31:20 +0200 Subject: [PATCH] fix(docs): clarify Configuration packages cannot include MRAPs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The xpkg spec restricts Configuration packages to Configuration, CompositeResourceDefinition, and Composition objects only. MRAPs cannot be bundled in Configuration packages. Update docs to: - Explain that MRAPs are applied separately by cluster operators - Show correct approach using dependsOn in crossplane.yaml - Recommend documenting MRD requirements in package README - Align best practices section with this constraint Closes #1126 Signed-off-by: Moritz Schmitz von Hülst --- .../managed-resource-activation-policies.md | 48 +++++++++++++++---- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/content/v2.1/managed-resources/managed-resource-activation-policies.md b/content/v2.1/managed-resources/managed-resource-activation-policies.md index 80c586852..db673b36a 100644 --- a/content/v2.1/managed-resources/managed-resource-activation-policies.md +++ b/content/v2.1/managed-resources/managed-resource-activation-policies.md @@ -275,22 +275,49 @@ spec: ### Configuration package activation -Configuration packages can include MRAPs to declare their resource dependencies: +Configuration packages cannot include MRAPs directly — the +[Crossplane package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md) +restricts Configuration packages to `Configuration`, +`CompositeResourceDefinition`, and `Composition` objects only. + +To declare resource dependencies for a Configuration package, use the +`dependsOn` field in `crossplane.yaml` to specify required Providers: + +```yaml +# crossplane.yaml +apiVersion: meta.pkg.crossplane.io/v1 +kind: Configuration +metadata: + name: my-configuration +spec: + dependsOn: + - apiVersion: pkg.crossplane.io/v1 + kind: Provider + package: xpkg.crossplane.io/crossplane-contrib/provider-aws + version: ">=v0.50.0" +``` + +MRAPs are applied separately by cluster operators or platform teams. A +Configuration author should document which MRDs their Configuration requires +so the operator can create matching MRAPs: ```yaml -# In your Configuration package +# Applied separately by the cluster operator apiVersion: apiextensions.crossplane.io/v1alpha1 kind: ManagedResourceActivationPolicy metadata: - name: web-platform-dependencies + name: my-configuration-dependencies spec: activate: - - buckets.s3.aws.m.crossplane.io # For static assets - - instances.ec2.aws.m.crossplane.io # For web servers - - databases.rds.aws.m.crossplane.io # For application data - - certificates.acm.aws.m.crossplane.io # For HTTPS + - buckets.s3.aws.m.crossplane.io # Required by my-configuration + - instances.ec2.aws.m.crossplane.io # Required by my-configuration ``` +{{}} +Document MRD requirements in your Configuration's README so users know which +MRAPs to create before installing. +{{}} + ## Working with MRAPs @@ -458,9 +485,10 @@ package dependencies. `*.s3.aws.m.crossplane.io` works for future S3 resources) 3. **Group related resources logically** - Create MRAPs that activate resources teams actually use together -4. **Include activation dependencies in Configuration packages** - - Configuration packages should declare what MRDs they need rather than - assuming resources are available +4. **Document MRD requirements in Configuration packages** - + Configuration packages cannot include MRAPs, so document required MRDs + in the package README so operators can create matching MRAPs before + installation 5. **Use conservative patterns in shared environments** - Avoid overly broad wildcards that activate unnecessary resources when multiple teams share providers