From a06f55dd57547362710d7e6fa27e2a1c4f081e03 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Thu, 17 Aug 2023 15:56:27 +0300 Subject: [PATCH 1/3] 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 000000000..3a17a0019 --- /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 50498661d..a6f9afab6 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 >}} From 196e10bd8e289dfbbb33bc93cbcc378b0c297f22 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Thu, 17 Aug 2023 17:55:51 +0300 Subject: [PATCH 2/3] Fix vale errors in usages.md Signed-off-by: Hasan Turken --- content/master/concepts/usages.md | 67 ++++++++++++++++--------------- 1 file changed, 35 insertions(+), 32 deletions(-) diff --git a/content/master/concepts/usages.md b/content/master/concepts/usages.md index 3a17a0019..6518d3c51 100644 --- a/content/master/concepts/usages.md +++ b/content/master/concepts/usages.md @@ -1,24 +1,24 @@ --- title: Usages -weight: 90 +weight: 95 state: alpha alphaVersion: "1.14" -description: "Usage defines deletion protection for Managed Resources or Composites" +description: "Usage defines a usage relationship 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: +A `Usage` is a Crossplane resource that defines a usage relationship for a +Managed Resource or a Composite Resource. Two main use cases for the Usages are +as follows: 1. Protecting a resource from accidental deletion. -2. Deletion ordering, that is, preventing a resource from being deleted before - the dependent resource deleted. +2. Deletion ordering by ensuring that a resource isn't deleted before the + deletion of its dependent resources. 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 +## Enable usages Usages are an alpha feature. Alpha features aren't enabled by default. Enable `Usage` support by @@ -51,21 +51,23 @@ with Helm. {{< /hint >}} -## Create a Usage +## Create a usage A {{}}Usage{{}} {{}}spec{{}} has a mandatory {{}}of{{}} field for defining the resource -being used or protected. The +in use 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. + +defines the using resource. Both fields are optional, but at least one of them +must be provided. + -### Usage for Deletion Protection +### Usage for deletion protection -The following example will prevent the deletion of the +The following example prevents the deletion of the {{}}my-database{{}} resource by rejecting any deletion request with the {{}}reason{{}} defined. @@ -84,13 +86,12 @@ spec: reason: "Production Database - should never be deleted!" ``` -### Usage for Deletion Ordering +### Usage for deletion ordering -The following example will prevent the deletion of +The following example prevents the deletion of {{}}my-cluster{{}} resource by rejecting -any deletion request before -{{}}my-prometheus-chart{{}} resource is -deleted. +any deletion request before the deletion of +{{}}my-prometheus-chart{{}} resource. ```yaml {label="order"} apiVersion: apiextensions.crossplane.io/v1alpha1 @@ -110,12 +111,12 @@ spec: name: my-prometheus-chart ``` -### Using Selectors with Usages +### Using selectors with usages Usages can use {{}}selectors{{}} -to define the resource being used or the using one. +to define the resource in use or the using one. This enables using {{}}labels{{}} or -{{}}matching controller references{{}} +{{}}matching controller references{{}} to define resource instead of providing the resource name. ```yaml {label="selectors"} @@ -139,15 +140,17 @@ spec: baz: qux ``` -Once the selectors are resolved, the `Usage` controller will persist the -resource name in the +Once the `Usage` controller resolves the selectors, it persists the resource +name in the {{}}resourceRef.name{{}} -field. The following example shows the `Usage` resource after the selectors are -resolved. +field. The following example shows the `Usage` resource after the resolution of +selectors. {{}} -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. + +The selectors are resolved only once. If there are more than one matches, a +random resource is selected from the list of matched resources. + {{< /hint >}} ```yaml {label="selectors-resolved"} @@ -174,17 +177,17 @@ spec: baz: qux ``` -## Usage in a Composition +## 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]({{}}) +[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. +between a `Cluster` and a `Release` resource. The `Usage` blocks deletion of +the `Cluster` resource until the `Release` resource is successfully deleted. ```yaml {label="composition"} apiVersion: apiextensions.crossplane.io/v1 From abf3dc480049f1f5bc8f61c6bdf593fbf2f8dc84 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Mon, 11 Sep 2023 15:37:14 +0300 Subject: [PATCH 3/3] Add notes and tips to Usage Signed-off-by: Hasan Turken --- content/master/concepts/usages.md | 32 ++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/content/master/concepts/usages.md b/content/master/concepts/usages.md index 6518d3c51..f8858c50d 100644 --- a/content/master/concepts/usages.md +++ b/content/master/concepts/usages.md @@ -14,8 +14,8 @@ as follows: 2. Deletion ordering by ensuring that a resource isn't deleted before the deletion of its dependent resources. -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) +See the section [Usage for Deletion Protection](#usage-for-deletion-protection) for the +first use case and the section [Usage for Deletion Ordering](#usage-for-deletion-ordering) for the second one. ## Enable usages @@ -65,6 +65,18 @@ defines the using resource. Both fields are optional, but at least one of them must be provided. +{{}} + +Usage relationships can be defined between `Managed Resources` and `Composites`. + +However, a `Composite` as the using resource (`spec.by`) would be ineffective +unless the `compositeDeletePolicy` `Foreground` is used because it wouldn't block +deletion of its child resources before its own deletion with the default deletion +policy `Background`. + + +{{< /hint >}} + ### Usage for deletion protection The following example prevents the deletion of the @@ -140,7 +152,7 @@ spec: baz: qux ``` -Once the `Usage` controller resolves the selectors, it persists the resource +After the `Usage` controller resolves the selectors, it persists the resource name in the {{}}resourceRef.name{{}} field. The following example shows the `Usage` resource after the resolution of @@ -220,3 +232,17 @@ spec: resourceSelector: matchControllerRef: true ``` + +{{}} + + +When there are multiple resources of same type in a Composition, the +{{}}Usage{{}} resource must +uniquely identify the resource in use or the using one. This could be +accomplished by using extra labels and combining +{{}}matchControllerRef{{}} +with a `matchLabels` selector. Another alternative is patching `resourceRef.name` +directly with the help of `ToCompositeFieldPath` and `FromCompositeFieldPath` +or `ToEnvironmentFieldPath` and `FromEnvironmentFieldPath` type patches. + +{{< /hint >}} \ No newline at end of file