Skip to content

feat(protection): document new provider deletion protection with clusterusages #1090

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
haarchri wants to merge 1 commit into
base: master
Choose a base branch
from
+112 −10
Open

feat(protection): document new provider deletion protection with clusterusages #1090

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/master/get-started/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ at the table below.
| Beta | `--enable-realtime-compositions` | Enable support for real time compositions. |
| Alpha | `--enable-dependency-version-upgrades ` | Enable automatic version upgrades of dependencies when updating packages. |
| Alpha | `--enable-function-response-cache` | Enable caching of composition function responses to improve performance. |
| Alpha | `--enable-provider-deletion-protection` | Enable automatic protection of Providers from deletion when they have active managed resources. Requires `--enable-usages`. |
| Alpha | `--enable-signature-verification` | Enable support for package signature verification via ImageConfig API. |
{{< /table >}}
{{< /expand >}}
Expand Down
28 changes: 18 additions & 10 deletions content/master/managed-resources/usages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ A `Usage` indicates a resource is in use. Two main use cases for Usages are
as follows:

1. Protecting a resource from accidental deletion.
2. Deletion ordering by ensuring that a resource isn't deleted before the
2. Deletion ordering by ensuring that a resource isn't deleted before the
deletion of its dependent resources.

See the section [Usage for Deletion Protection](#usage-for-deletion-protection) for the
Expand All @@ -23,9 +23,9 @@ for the second one.
Usages are a beta feature. Crossplane enables beta features by default.
<!-- vale write-good.Passive = YES -->

Disable `Usage` support by
Disable `Usage` support by
[changing the Crossplane pod setting]({{<ref "../guides/pods#change-pod-settings">}})
and setting
and setting
{{<hover label="deployment" line="12">}}--enable-usages=false{{</hover>}}
argument.

Expand All @@ -46,8 +46,8 @@ spec:

{{<hint "tip" >}}

The [Crossplane install guide]({{<ref "../get-started/install#feature-flags">}})
describes enabling feature flags like
The [Crossplane install guide]({{<ref "../get-started/install#feature-flags">}})
describes enabling feature flags like
{{<hover label="deployment" line="12">}}\-\-enable-usages{{</hover>}}
with Helm.
{{< /hint >}}
Expand All @@ -60,7 +60,7 @@ with Helm.
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
in use or protected. The
in use 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 fields are optional, but at least one of them
Expand All @@ -69,7 +69,7 @@ must be provided.

### Usage for deletion protection

The following example prevents the deletion of the
The following example prevents 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.
Expand All @@ -93,7 +93,7 @@ spec:

The following example prevents the deletion of
{{<hover label="order" line="10">}}my-cluster{{</hover>}} resource by rejecting
any deletion request before the deletion of
any deletion request before the deletion of
{{<hover label="order" line="15">}}my-prometheus-chart{{</hover>}} resource.

```yaml {label="order"}
Expand Down Expand Up @@ -146,7 +146,7 @@ spec:
```

After the `Usage` controller resolves the selectors, it persists the resource
name in the
name in the
{{<hover label="selectors-resolved" line="10">}}resourceRef.name{{</hover>}}
field. The following example shows the `Usage` resource after the resolution of
selectors.
Expand Down Expand Up @@ -235,7 +235,7 @@ 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
accomplished by using extra labels and combining
{{<hover label="composition" line="24">}}matchControllerRef{{</hover>}}
with a `matchLabels` selector.
with a `matchLabels` selector.
<!-- vale write-good.Passive = YES -->
{{< /hint >}}

Expand Down Expand Up @@ -289,3 +289,11 @@ spec:
name: importantresources.example.crossplane.io
reason: "Very important CRD - should never be deleted!"
```

{{<hint "tip" >}}
Crossplane can automatically create `ClusterUsage` resources to protect
Providers from accidental deletion when they have active managed resources.
Enable this with the `--enable-provider-deletion-protection` alpha feature flag.
See [Provider deletion protection]({{<ref "../packages/providers#provider-deletion-protection">}})
for details.
{{< /hint >}}
93 changes: 93 additions & 0 deletions content/master/packages/providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -457,6 +457,99 @@ removing their finalizers.
For more information on deleting abandoned resources read the [Crossplane troubleshooting guide]({{<ref "../guides/troubleshoot-crossplane#deleting-when-a-resource-hangs" >}}).
{{< /hint >}}

### Provider deletion protection

{{<hint "important" >}}
Provider deletion protection is an alpha feature. Crossplane disables alpha
features by default.

Enable Provider deletion protection with the
`--enable-provider-deletion-protection`
[feature flag]({{<ref "../get-started/install#feature-flags">}}).
This feature also requires
[Usages]({{<ref "../managed-resources/usages">}}) to be enabled (on by default).

```shell {label="protection-helm"}
helm upgrade --install crossplane crossplane-stable/crossplane \
--namespace crossplane-system \
--set args='{"--enable-provider-deletion-protection"}'
```
{{</hint >}}

When Provider deletion protection is enabled, Crossplane automatically prevents
the deletion of Providers that still have active managed resources. This
protects against accidentally removing a Provider and orphaning its managed
resources.

Crossplane watches for managed resources associated with each Provider. When
managed resources exist, Crossplane creates a
[ClusterUsage]({{<ref "../managed-resources/usages#clusterusages">}}) that
blocks deletion of the owning Provider. The `ClusterUsage` includes a
descriptive reason indicating which managed resource type is still active,
for example `"Provider has active managed resources of type
VPC.ec2.aws.upbound.io"`.

When all managed resources of a given type are deleted, Crossplane automatically
removes the corresponding `ClusterUsage`, allowing the Provider to be deleted.

List all provider protection `ClusterUsages` using the
`crossplane.io/provider-protection=true` label:

```shell {copy-lines="1"}
kubectl get clusterusages -l crossplane.io/provider-protection=true
Copy link
Copy Markdown
Member

@jbw976 jbw976 May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when i ran this command, i got more useful printer columns like DETAILS - do you not see the same? i think it looks better to have the more details by default in the docs

NAME                                                                       DETAILS                                                                            READY   AGE
provider-protection-0d9403ef4e758ec5ee89d2773d0b356af7635adc37548b0eaabb   Provider has active managed resources of type VPC.ec2.aws.m.upbound.io             True    22s
provider-protection-3da1709122b36532e8cbdedbcabde45947f99dd33d931eb682ee   Provider has active managed resources of type Subnet.ec2.aws.m.upbound.io          True    7s
provider-protection-774712aa693d57a5e7ce09a7754d53f3ca5cc59f417083756b2a   Provider has active managed resources of type SecurityGroup.ec2.aws.m.upbound.io   True    7s

NAME AGE
provider-protection-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6 5m
```

{{<hint "note" >}}
Crossplane generates `ClusterUsage` names using a hash of the
`ManagedResourceDefinition` name. Use the
`crossplane.io/provider-protection=true` label to find them.

Each `ClusterUsage` also has labels for the Provider name
(`pkg.crossplane.io/package`) and the MRD name
(`apiextensions.crossplane.io/mrd`).
{{< /hint >}}

Inspect a specific `ClusterUsage` to see which Provider it protects and why:

```yaml
apiVersion: protection.crossplane.io/v1beta1
kind: ClusterUsage
metadata:
name: provider-protection-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
labels:
crossplane.io/provider-protection: "true"
pkg.crossplane.io/package: crossplane-contrib-provider-aws-s3
apiextensions.crossplane.io/mrd: buckets.s3.aws.upbound.io
spec:
of:
apiVersion: pkg.crossplane.io/v1
kind: Provider
resourceRef:
name: crossplane-contrib-provider-aws-s3
reason: "Provider has active managed resources of type Bucket.s3.aws.upbound.io"
```

Attempting to delete a Provider with active managed resources returns an error
from the Usage admission webhook:

```shell
$ kubectl delete provider.pkg.crossplane.io/provider-aws-ec2
Copy link
Copy Markdown
Member

@jbw976 jbw976 May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the terminal prompt char should not be included here, the docs add that automatically

currently, the copy to clipboard button is displayed and clicking it copies the entire command along with error message. If we don't mean for folks to copy it, then we should disable it with {copy-lines="none"} or if we do want folks to copy it then set it to just line 1 with {copy-lines="1"}

Error from server (This resource is in-use by 3 usage(s), including the
*v1beta1.ClusterUsage "provider-protection-774712aa693d57a5e7ce09a7754d53f3
ca5cc59f417083756b2a" with reason: "Provider has active managed resources of
type SecurityGroup.ec2.aws.m.upbound.io".): admission webhook
"nousages.protection.crossplane.io" denied the request: This resource is
in-use by 3 usage(s), including the *v1beta1.ClusterUsage
"provider-protection-774712aa693d57a5e7ce09a7754d53f3ca5cc59f417083756b2a"
with reason: "Provider has active managed resources of type
SecurityGroup.ec2.aws.m.upbound.io".
```

To delete a protected Provider, first remove all its managed resources, or
manually delete the `ClusterUsage` resource protecting it.

## Verify a Provider

Providers install their own APIs representing the managed resources they support.
Expand Down
Loading