From a06f55dd57547362710d7e6fa27e2a1c4f081e03 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Thu, 17 Aug 2023 15:56:27 +0300 Subject: [PATCH] Add documentation for alpha Usages Signed-off-by: Hasan Turken --- content/master/concepts/usages.md | 219 +++++++++++++++++++++++++++++ content/master/software/install.md | 1 + 2 files changed, 220 insertions(+) create mode 100644 content/master/concepts/usages.md diff --git a/content/master/concepts/usages.md b/content/master/concepts/usages.md new file mode 100644 index 00000000..3a17a001 --- /dev/null +++ b/content/master/concepts/usages.md @@ -0,0 +1,219 @@ +--- +title: Usages +weight: 90 +state: alpha +alphaVersion: "1.14" +description: "Usage defines deletion protection for Managed Resources or Composites" +--- + +A `Usage` is a Crossplane resource that defines deletion protection for a +Managed Resource or a Composite Resource. There are two main use cases for the +Usages: + +1. Protecting a resource from accidental deletion. +2. Deletion ordering, that is, preventing a resource from being deleted before + the dependent resource deleted. + +See the [Usage for Deletion Protection](#usage-for-deletion-protection) for the +first use case and the [Usage for Deletion Ordering](#usage-for-deletion-ordering) +for the second one. + +## Enable Usages +Usages are an alpha feature. Alpha features aren't enabled by default. + +Enable `Usage` support by +[changing the Crossplane pod setting]({{}}) +and enabling +{{}}--enable-usages{{}} +argument. + +```yaml {label="deployment",copy-lines="12"} +$ kubectl edit deployment crossplane --namespace crossplane-system +apiVersion: apps/v1 +kind: Deployment +spec: +# Removed for brevity + template: + spec: + containers: + - args: + - core + - start + - --enable-usages +``` + +{{}} + +The [Crossplane install guide]({{}}) +describes enabling feature flags like +{{}}\-\-enable-usages{{}} +with Helm. +{{< /hint >}} + + +## Create a Usage + + +A {{}}Usage{{}} +{{}}spec{{}} has a mandatory +{{}}of{{}} field for defining the resource +being used or protected. The +{{}}reason{{}} field defines the reason +for protection and the {{}}by{{}} field +defines the using resource. Both are optional fields, however, at least one of +them must be defined. + +### Usage for Deletion Protection + +The following example will prevent the deletion of the +{{}}my-database{{}} resource by rejecting +any deletion request with the +{{}}reason{{}} defined. + +```yaml {label="protect"} +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: Usage +metadata: + name: protect-production-database +spec: + of: + apiVersion: rds.aws.upbound.io/v1beta1 + kind: Instance + resourceRef: + name: my-database + reason: "Production Database - should never be deleted!" +``` + +### Usage for Deletion Ordering + +The following example will prevent the deletion of +{{}}my-cluster{{}} resource by rejecting +any deletion request before +{{}}my-prometheus-chart{{}} resource is +deleted. + +```yaml {label="order"} +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: Usage +metadata: + name: release-uses-cluster +spec: + of: + apiVersion: eks.upbound.io/v1beta1 + kind: Cluster + resourceRef: + name: my-cluster + by: + apiVersion: helm.crossplane.io/v1beta1 + kind: Release + resourceRef: + name: my-prometheus-chart +``` + +### Using Selectors with Usages + +Usages can use {{}}selectors{{}} +to define the resource being used or the using one. +This enables using {{}}labels{{}} or +{{}}matching controller references{{}} +to define resource instead of providing the resource name. + +```yaml {label="selectors"} +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: Usage +metadata: + name: release-uses-cluster +spec: + of: + apiVersion: eks.upbound.io/v1beta1 + kind: Cluster + resourceSelector: + matchControllerRef: false # default, and could be omitted + matchLabels: + foo: bar + by: + apiVersion: helm.crossplane.io/v1beta1 + kind: Release + resourceSelector: + matchLabels: + baz: qux +``` + +Once the selectors are resolved, the `Usage` controller will persist the +resource name in the +{{}}resourceRef.name{{}} +field. The following example shows the `Usage` resource after the selectors are +resolved. + +{{}} +The selectors are resolved only once and a random resource will be selected from +the list of matched resources if there are more than one matches. +{{< /hint >}} + +```yaml {label="selectors-resolved"} +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: Usage +metadata: + name: release-uses-cluster +spec: + of: + apiVersion: eks.upbound.io/v1beta1 + kind: Cluster + resourceRef: + name: my-cluster + resourceSelector: + matchLabels: + foo: bar + by: + apiVersion: helm.crossplane.io/v1beta1 + kind: Release + resourceRef: + name: my-cluster + resourceSelector: + matchLabels: + baz: qux +``` + +## Usage in a Composition + +A typical use case for Usages is to define a deletion ordering between the +resources in a Composition. The Usages support +[matching controller reference]({{}}) +in selectors to ensures that the matching resource is in the same composite +resource in the same way as [cross-resource referencing]({{}}). + +The following example shows a Composition that defines a deletion ordering +between a `Cluster` and a `Release` resource which will block deletion of the +`Cluster` resource until the `Release` resource is successfully deleted. + +```yaml {label="composition"} +apiVersion: apiextensions.crossplane.io/v1 +kind: Composition +spec: + resources: + - name: cluster + base: + apiVersion: container.gcp.upbound.io/v1beta1 + kind: Cluster + # Removed for brevity + - name: release + base: + apiVersion: helm.crossplane.io/v1beta1 + kind: Release + # Removed for brevity + - name: release-uses-cluster + base: + apiVersion: apiextensions.crossplane.io/v1alpha1 + kind: Usage + spec: + of: + apiVersion: container.gcp.upbound.io/v1beta1 + kind: Cluster + resourceSelector: + matchControllerRef: true + by: + apiVersion: helm.crossplane.io/v1beta1 + kind: Release + resourceSelector: + matchControllerRef: true +``` diff --git a/content/master/software/install.md b/content/master/software/install.md index 50498661..a6f9afab 100644 --- a/content/master/software/install.md +++ b/content/master/software/install.md @@ -269,6 +269,7 @@ at the table below. | Alpha | `--enable-composition-webhook-schema-validation` | Enable Composition validation using schemas. | | Alpha | `--enable-environment-configs` | Enable support for EnvironmentConfigs. | | Alpha | `--enable-external-secret-stores` | Enable support for External Secret Stores. | +| Alpha | `--enable-usages` | Enable support for Usages. | {{< /table >}} {{< /expand >}}