crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document Usages for v2 

Signed-off-by: Nic Cope <nicc@rk0n.org>
This commit is contained in:
Nic Cope 2025-03-28 22:03:51 -07:00
parent dc39ca3f50
commit 89dbb4427a
1 changed files with 72 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
content/v2.0-preview/managed-resources/usages.md
View File

@ -4,11 +4,10 @@ weight: 30
state: beta state: beta
alphaVersion: "1.14" alphaVersion: "1.14"
betaVersion: "1.19" betaVersion: "1.19"
description: "Usage defines a usage relationship for Managed Resources or Composites" description: "Usage indicates a resource is in use"
--- ---
A `Usage` is a Crossplane resource that defines a usage relationship for a A `Usage` indicates a resource is in use. Two main use cases for Usages are
Managed Resource or a Composite Resource. Two main use cases for the Usages are
as follows: as follows:
1. Protecting a resource from accidental deletion. 1. Protecting a resource from accidental deletion.
@ -68,18 +67,6 @@ defines the using resource. Both fields are optional, but at least one of them
must be provided. must be provided.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
{{<hint "important" >}}
<!-- vale write-good.Passive = NO -->
Usage relationships can be defined between `Managed Resources` and `Composites`.
<!-- vale write-good.TooWordy = NO -->
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`.
<!-- vale write-good.TooWordy = YES -->
<!-- vale write-good.Passive = YES -->
{{< /hint >}}
### Usage for deletion protection ### Usage for deletion protection
The following example prevents the deletion of the The following example prevents the deletion of the
@ -88,13 +75,14 @@ any deletion request with the
{{<hover label="protect" line="11">}}reason{{</hover>}} defined. {{<hover label="protect" line="11">}}reason{{</hover>}} defined.
```yaml {label="protect"} ```yaml {label="protect"}
apiVersion: apiextensions.crossplane.io/v1beta1 apiVersion: protection.crossplane.io/v1beta1
kind: Usage kind: Usage
metadata: metadata:
namespace: default
name: protect-production-database name: protect-production-database
spec: spec:
of: of:
apiVersion: rds.aws.upbound.io/v1beta1 apiVersion: rds.m.aws.upbound.io/v1beta1
kind: Instance kind: Instance
resourceRef: resourceRef:
name: my-database name: my-database
@ -109,18 +97,19 @@ any deletion request before the deletion of
{{<hover label="order" line="15">}}my-prometheus-chart{{</hover>}} resource. {{<hover label="order" line="15">}}my-prometheus-chart{{</hover>}} resource.
```yaml {label="order"} ```yaml {label="order"}
apiVersion: apiextensions.crossplane.io/v1beta1 apiVersion: protection.crossplane.io/v1beta1
kind: Usage kind: Usage
metadata: metadata:
namespace: default
name: release-uses-cluster name: release-uses-cluster
spec: spec:
of: of:
apiVersion: eks.upbound.io/v1beta1 apiVersion: eks.m.upbound.io/v1beta1
kind: Cluster kind: Cluster
resourceRef: resourceRef:
name: my-cluster name: my-cluster
by: by:
apiVersion: helm.crossplane.io/v1beta1 apiVersion: helm.m.crossplane.io/v1beta1
kind: Release kind: Release
resourceRef: resourceRef:
name: my-prometheus-chart name: my-prometheus-chart
@ -135,20 +124,21 @@ This enables using {{<hover label="selectors" line="12">}}labels{{</hover>}} or
to define resource instead of providing the resource name. to define resource instead of providing the resource name.
```yaml {label="selectors"} ```yaml {label="selectors"}
apiVersion: apiextensions.crossplane.io/v1beta1 apiVersion: protection.crossplane.io/v1beta1
kind: Usage kind: Usage
metadata: metadata:
namespace: default
name: release-uses-cluster name: release-uses-cluster
spec: spec:
of: of:
apiVersion: eks.upbound.io/v1beta1 apiVersion: eks.m.upbound.io/v1beta1
kind: Cluster kind: Cluster
resourceSelector: resourceSelector:
matchControllerRef: false # default, and could be omitted matchControllerRef: false # default, and could be omitted
matchLabels: matchLabels:
foo: bar foo: bar
by: by:
apiVersion: helm.crossplane.io/v1beta1 apiVersion: helm.m.crossplane.io/v1beta1
kind: Release kind: Release
resourceSelector: resourceSelector:
matchLabels: matchLabels:
@ -169,13 +159,14 @@ random resource is selected from the list of matched resources.
{{< /hint >}} {{< /hint >}}
```yaml {label="selectors-resolved"} ```yaml {label="selectors-resolved"}
apiVersion: apiextensions.crossplane.io/v1beta1 apiVersion: protection.crossplane.io/v1beta1
kind: Usage kind: Usage
metadata: metadata:
namespace: default
name: release-uses-cluster name: release-uses-cluster
spec: spec:
of: of:
apiVersion: eks.upbound.io/v1beta1 apiVersion: eks.m.upbound.io/v1beta1
kind: Cluster kind: Cluster
resourceRef: resourceRef:
name: my-cluster name: my-cluster
@ -183,7 +174,7 @@ spec:
matchLabels: matchLabels:
foo: bar foo: bar
by: by:
apiVersion: helm.crossplane.io/v1beta1 apiVersion: helm.m.crossplane.io/v1beta1
kind: Release kind: Release
resourceRef: resourceRef:
name: my-cluster name: my-cluster
@ -200,19 +191,20 @@ Replaying the blocked deletion is possible by setting the
{{<hover label="replay" line="6">}}replayDeletion{{</hover>}} field to `true`. {{<hover label="replay" line="6">}}replayDeletion{{</hover>}} field to `true`.
```yaml {label="replay"} ```yaml {label="replay"}
apiVersion: apiextensions.crossplane.io/v1beta1 apiVersion: protection.crossplane.io/v1beta1
kind: Usage kind: Usage
metadata: metadata:
namespace: default
name: release-uses-cluster name: release-uses-cluster
spec: spec:
replayDeletion: true replayDeletion: true
of: of:
apiVersion: eks.upbound.io/v1beta1 apiVersion: eks.m.upbound.io/v1beta1
kind: Cluster kind: Cluster
resourceRef: resourceRef:
name: my-cluster name: my-cluster
by: by:
apiVersion: helm.crossplane.io/v1beta1 apiVersion: helm.m.crossplane.io/v1beta1
kind: Release kind: Release
resourceRef: resourceRef:
name: my-prometheus-chart name: my-prometheus-chart
@ -235,51 +227,6 @@ resources in a Composition. The Usages support
in selectors to ensures that the matching resource is in the same composite in selectors to ensures that the matching resource is in the same composite
resource in the same way as [cross-resource referencing]({{<ref "./managed-resources#referencing-other-resources" >}}). resource in the same way as [cross-resource referencing]({{<ref "./managed-resources#referencing-other-resources" >}}).
The following example shows a Composition that defines a deletion ordering
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
kind: Composition
spec:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
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/v1beta1
kind: Usage
spec:
replayDeletion: true
of:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
resourceSelector:
matchControllerRef: true
by:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
resourceSelector:
matchControllerRef: true
```
{{<hint "tip" >}} {{<hint "tip" >}}
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
@ -288,8 +235,55 @@ When there are multiple resources of same type in a Composition, the
uniquely identify the resource in use or the using one. This could be uniquely identify the resource in use or the using one. This could be
accomplished by using extra labels and combining accomplished by using extra labels and combining
{{<hover label="composition" line="24">}}matchControllerRef{{</hover>}} {{<hover label="composition" line="24">}}matchControllerRef{{</hover>}}
with a `matchLabels` selector. Another alternative is patching `resourceRef.name` with a `matchLabels` selector.
directly with the help of `ToCompositeFieldPath` and `FromCompositeFieldPath`
or `ToEnvironmentFieldPath` and `FromEnvironmentFieldPath` type patches.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
{{< /hint >}} {{< /hint >}}
## Usage across namespaces
A `Usage` with `of` and `by` represents a usage relationship between two
resources in the same namespace as the `Usage` by default.
A `Usage` can represent a usage relationship between a `by` resource in the same
namespace as the `Usage` and an `of` resource in a different namespace.
To use a resource in a different namespace, specify the `namespace` in the `of`
`resourceRef` or `resourceSelector`.
```yaml {label="order"}
apiVersion: protection.crossplane.io/v1beta1
kind: Usage
metadata:
namespace: default
name: release-uses-cluster
spec:
of:
apiVersion: eks.m.upbound.io/v1beta1
kind: Cluster
resourceRef:
namespace: cluster-infra
name: my-cluster
by:
apiVersion: helm.m.crossplane.io/v1beta1
kind: Release
resourceRef:
name: my-prometheus-chart
```
## ClusterUsages
Use a `ClusterUsage` to protect cluster scoped resources.
```yaml {label="protect"}
apiVersion: protection.crossplane.io/v1beta1
kind: ClusterUsage
metadata:
name: protect-important-crd
spec:
of:
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
resourceRef:
name: importantresources.example.crossplane.io
reason: "Very important CRD - should never be deleted!"
```