mirror of https://github.com/crossplane/docs.git
Add documentation for alpha Usages
Signed-off-by: Hasan Turken <turkenh@gmail.com>
This commit is contained in:
Hasan Turken
parent
a1478bb2ae
commit
a06f55dd57
|
|
@ -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]({{<ref "./pods#change-pod-settings">}})
|
||||
and enabling
|
||||
{{<hover label="deployment" line="12">}}--enable-usages{{</hover>}}
|
||||
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
|
||||
```
|
||||
|
||||
{{<hint "tip" >}}
|
||||
|
||||
The [Crossplane install guide]({{<ref "../software/install#feature-flags">}})
|
||||
describes enabling feature flags like
|
||||
{{<hover label="deployment" line="12">}}\-\-enable-usages{{</hover>}}
|
||||
with Helm.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
## Create a Usage
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
A {{<hover label="protect" line="2">}}Usage{{</hover>}}
|
||||
{{<hover label="protect" line="5">}}spec{{</hover>}} has a mandatory
|
||||
{{<hover label="protect" line="6">}}of{{</hover>}} field for defining the resource
|
||||
being used or protected. The
|
||||
{{<hover label="protect" line="11">}}reason{{</hover>}} field defines the reason
|
||||
for protection and the {{<hover label="order" line="11">}}by{{</hover>}} 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
|
||||
{{<hover label="protect" line="10">}}my-database{{</hover>}} resource by rejecting
|
||||
any deletion request with the
|
||||
{{<hover label="protect" line="11">}}reason{{</hover>}} 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
|
||||
{{<hover label="order" line="10">}}my-cluster{{</hover>}} resource by rejecting
|
||||
any deletion request before
|
||||
{{<hover label="order" line="15">}}my-prometheus-chart{{</hover>}} 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 {{<hover label="selectors" line="9">}}selectors{{</hover>}}
|
||||
to define the resource being used or the using one.
|
||||
This enables using {{<hover label="selectors" line="12">}}labels{{</hover>}} or
|
||||
{{<hover label="selectors" line="11">}}matching controller references{{</hover>}}
|
||||
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
|
||||
{{<hover label="selectors-resolved" line="10">}}resourceRef.name{{</hover>}}
|
||||
field. The following example shows the `Usage` resource after the selectors are
|
||||
resolved.
|
||||
|
||||
{{<hint "important" >}}
|
||||
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]({{<ref "./compositions#matching-a-controller-reference" >}})
|
||||
in selectors to ensures that the matching resource is in the same composite
|
||||
resource in the same way as [cross-resource referencing]({{<ref "./compositions#cross-resource-references" >}}).
|
||||
|
||||
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
|
||||
```
|
||||
|
|
@ -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 >}}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue