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

Merge pull request #986 from jbw976/v2-follow-ups 

fix: post v2 follow up fixes and clean up
This commit is contained in:
Jared Watts 2025-09-03 17:51:54 -07:00 committed by GitHub
parent 3555176893 f142a967c3
commit 8bae31a12a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
21 changed files with 1281 additions and 327 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
content/master/get-started/install.md
View File

@ -87,7 +87,7 @@ crossplane-rbac-manager-86d9b5cf9f-2vc4s 1/1 Running 0 26m
Crossplane supports customizations at install time by configuring the Helm Crossplane supports customizations at install time by configuring the Helm
chart. chart.
Read [the Helm chart README](https://github.com/crossplane/crossplane/blob/v2/cluster/charts/crossplane/README.md#configuration) Read [the Helm chart README](https://github.com/crossplane/crossplane/blob/v2/cluster/charts/crossplane/README.md#configuration)
to learn what customizations are available. to learn what customizations are available.
Read [the Helm documentation](https://helm.sh/docs/) to learn how to run Helm Read [the Helm documentation](https://helm.sh/docs/) to learn how to run Helm
@ -103,25 +103,17 @@ at the table below.
{{< expand "Feature flags" >}} {{< expand "Feature flags" >}}
{{< table caption="Feature flags" >}} {{< table caption="Feature flags" >}}
| Status | Flag | Description | | Status | Flag | Description |
| --- | --- | --- | |--------|-----------------------------------------|---------------------------------------------------------------------------|
| Beta | `--enable-deployment-runtime-configs` | Enable support for DeploymentRuntimeConfigs. | | Beta | `--enable-deployment-runtime-configs` | Enable support for DeploymentRuntimeConfigs. |
| Beta | `--enable-usages` | Enable support for Usages. | | Beta | `--enable-usages` | Enable support for Usages. |
| Beta | `--enable-realtime-compositions` | Enable support for real time compositions. | | 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-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-function-response-cache` | Enable caching of composition function responses to improve performance. |
| Alpha | `--enable-signature-verification` | Enable support for package signature verification via ImageConfig API. | | Alpha | `--enable-signature-verification` | Enable support for package signature verification via ImageConfig API. |
{{< /table >}} {{< /table >}}
{{< /expand >}} {{< /expand >}}
Set these flags either in the `values.yaml` file or at install time using the Set these flags either in the `values.yaml` file or at install time using the
`--set` flag, for example: `--set `--set` flag, for example: `--set
args='{"--enable-composition-functions","--enable-composition-webhook-schema-validation"}'`. args='{"--enable-composition-functions","--enable-composition-webhook-schema-validation"}'`.
#### Change the default package registry
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages.
Change the default registry location during the Crossplane install with
`--set args='{"--registry=index.docker.io"}'`.

266
content/master/guides/change-logs.md Normal file
View File

@ -0,0 +1,266 @@
---
title: Change Logs
weight: 210
description: "Change logs help you audit all changes made to your resources"
state: alpha
alphaVersion: "1.17"
---
The change logs feature helps users of Crossplane Providers understand what
changes a provider makes to the resources it manages. Whenever a provider
creates, updates, or deletes a managed resource, the provider records an entry
explaining the details of the change in its change log.
Change logs are important for awareness of the changes that a provider is
making to its managed resources. Due to the nature of Crossplane's active
reconciliation, it's possible for a provider to make changes to managed
resources without any user interaction. Consider the scenario when someone
updates a resource outside of Crossplane, for example via the AWS console or
`gcloud` CLI. When Crossplane detects this configuration drift, it
enforces the declared state and corrects the unexpected change
without any user interaction.
With Crossplane acting continuously and autonomously to update critical
infrastructure, it's vital for users to have insight into the operations the provider performs,
so they can build and maintain a strong sense of confidence and trust
in their control planes. Change logs provide details about all changes the
provider makes, so users can remain aware of any changes, even when they aren't
explicitly expecting any.
{{<hint "tip">}} Change logs help you understand all the changes a provider is
making to your resources, even when changes weren't explicitly requested, for
example because of Crossplane's automatic correction of configuration drift.
{{</hint>}}
## Enabling change logs
{{<hint "important" >}} Change logs are an alpha feature and must be explicitly
enabled for each provider through the use of a `DeploymentRuntimeConfig`.
{{</hint >}}
To enable change logs for a provider, use a `DeploymentRuntimeConfig` to
configure each provider pod that should start producing change logs. The
`DeploymentRuntimeConfig` has several important configuration details:
1. A command line argument to the provider container that enables the change
logs feature, for example `--enable-changelogs`.
1. A [side car container](https://github.com/crossplane/changelogs-sidecar) that
collects change events and produces change log entries to the provider's pod
logs.
1. A shared volume mounted to both the provider and sidecar containers that
enables communication of change events between the two containers.
### Prerequisites
This guide assumes you have a control plane with [Crossplane installed]({{<ref "../get-started/install">}}).
It also assumes you have the [`jq` tool installed](https://jqlang.org/download/),
to perform lightweight querying and filtering of the content in the change logs.
The only other prerequisite for enabling change logs is provider support for the
change logs feature. Support for change logs is optional, and not all providers
in the Crossplane ecosystem have added it yet.
{{<hint "tip">}} Not all providers support the change logs feature. Check with
your provider of choice to confirm it has added support for change logs.
{{</hint>}}
This guide walks through a full example of generating change logs with
[`provider-kubernetes`](https://github.com/crossplane-contrib/provider-kubernetes).
### Create a `DeploymentRuntimeConfig`
Create a `DeploymentRuntimeConfig` that enables change logs for
the provider when it's installed by performing the following configuration
steps:
1. Set the {{<hover label="drc" line="15">}}--enable-changelogs{{</hover>}} flag on the provider.
1. Add the {{<hover label="drc" line="19">}}sidecar container{{</hover>}} to the provider pod.
1. Declare a {{<hover label="drc" line="24">}}shared volume{{</hover>}} and mount it in the {{<hover label="drc" line="16">}}provider
container{{</hover>}} and the {{<hover label="drc" line="21">}}sidecar
container{{</hover>}}.
```yaml {label="drc",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: enable-changelogs
spec:
deploymentTemplate:
spec:
selector: {}
template:
spec:
containers:
- name: package-runtime
args:
- --enable-changelogs
volumeMounts:
- name: changelogs-vol
mountPath: /var/run/changelogs
- name: changelogs-sidecar
image: xpkg.crossplane.io/crossplane/changelogs-sidecar:v0.0.1
volumeMounts:
- name: changelogs-vol
mountPath: /var/run/changelogs
volumes:
- name: changelogs-vol
emptyDir: {}
serviceAccountTemplate:
metadata:
name: provider-kubernetes
EOF
```
### Install the provider
Install the {{<hover label="provider" line="7">}}provider{{</hover>}} and
instruct it to use the {{<hover label="provider" line="8">}}DeploymentRuntimeConfig{{</hover>}}
that was just created.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-kubernetes
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-kubernetes:v0.18.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
name: enable-changelogs
EOF
```
### Configure permissions
To allow the provider to create Kubernetes resources in the control
plane, grant the appropriate permissions. This guide only creates a
`ConfigMap`, so it only requires permissions for that resource type.
{{<hint "important">}} This guide grants specific permissions to the provider
for example purposes. This approach isn't intended to be representative of a
production environment. See more examples for configuring `provider-kubernetes` in its
[examples directory](https://github.com/crossplane-contrib/provider-kubernetes/tree/main/examples/namespaced/provider).
{{</hint>}}
```yaml {label="rbac",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: configmap-edit
rules:
- apiGroups:
- ""
resources:
- configmaps
verbs:
- "*"
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: provider-kubernetes-configmap-edit
subjects:
- kind: ServiceAccount
name: provider-kubernetes
namespace: crossplane-system
roleRef:
kind: ClusterRole
name: configmap-edit
apiGroup: rbac.authorization.k8s.io
---
apiVersion: kubernetes.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: InjectedIdentity
EOF
```
### Create a resource
After installing and configuring the provider with change logs enabled,
create a resource that generates change log entries that reflect the actions
the control plane takes.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: kubernetes.crossplane.io/v1alpha2
kind: Object
metadata:
name: configmap-for-changelogs
spec:
forProvider:
manifest:
apiVersion: v1
kind: ConfigMap
metadata:
namespace: default
name: configmap-for-changelogs
data:
key-1: cool-value-1
EOF
```
### Examine the change logs
Confirm that the change logs include the resource creation operation.
Examine the pod logs for `provider-kubernetes`, specifically the
`changelogs-sidecar` container:
```shell {label="changelogs-output-full",copy-lines="1"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar | jq
{
"timestamp": "2025-04-25T08:23:34Z",
"provider": "provider-kubernetes:v0.18.0",
"apiVersion": "kubernetes.crossplane.io/v1alpha2",
"kind": "Object",
"name": "configmap-for-changelogs",
"externalName": "configmap-for-changelogs",
"operation": "OPERATION_TYPE_CREATE",
"snapshot": {
...(omitted for brevity)...
```
Each change log entry contains rich information about the state of the resource
when the change operation occurred. Because each entry is a structured `JSON`
object, you can filter and query them to find any subset of information that
interests you:
```shell {label="changelogs-output-scoped",copy-lines="1-2"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
```
### Full lifecycle operations
Update and delete operations also generate corresponding change log entries.
Update the resource by patching its data field `key-1` with a new value
`cooler-value-2`:
```shell {label="object-patch",copy-lines="1-2"}
kubectl patch object configmap-for-changelogs --type=json \
-p='[{"op": "replace", "path": "/spec/forProvider/manifest/data/key-1", "value": "cooler-value-2"}]'
object.kubernetes.crossplane.io/configmap-for-changelogs patched
```
Then, delete the object entirely:
```shell {label="object-delete",copy-lines="1"}
kubectl delete object configmap-for-changelogs
object.kubernetes.crossplane.io "configmap-for-changelogs" deleted
```
Check the change logs again to verify that they include both the update and delete operations and capture the
object's full lifecycle:
```shell {label="changelogs-output-final",copy-lines="1-2"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
"2025-04-25T08:24:21Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_UPDATE"
"2025-04-25T08:24:25Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_DELETE"
```

16
content/master/guides/crossplane-with-argo-cd.md
View File

@ -1,25 +1,21 @@
<!-- vale Google.Headings = NO --> ---
<!-- vale Microsoft.HeadingAcronyms = NO -->
---
title: Configuring Crossplane with Argo CD title: Configuring Crossplane with Argo CD
weight: 270 weight: 270
description: "Deploy Crossplane resources with GitOps" description: "Deploy Crossplane resources with GitOps"
--- ---
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
[Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io) [Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io)
are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes
cluster into a Universal Control Plane for all your resources. Configuration details are cluster into a Universal Control Plane for all your resources. Configuration details are
required in order for the two to work together properly. required in order for the two to work together properly.
This doc will help you understand these requirements. It is recommended to use This doc will help you understand these requirements. It is recommended to use
Argo CD version 2.4.8 or later with Crossplane. Argo CD version 2.4.8 or later with Crossplane.
Argo CD synchronizes Kubernetes resource manifests stored in a Git repository Argo CD synchronizes Kubernetes resource manifests stored in a Git repository
with those running in a Kubernetes cluster (GitOps). Argo CD has different ways to configure with those running in a Kubernetes cluster (GitOps). Argo CD has different ways to configure
how it tracks resources. With Crossplane, you need to configure Argo CD how it tracks resources. With Crossplane, you need to configure Argo CD
to use Annotation based resource tracking. See the [Argo CD docs](https://argo-cd.readthedocs.io/en/latest/user-guide/resource_tracking/) for additional detail. to use Annotation based resource tracking. See the [Argo CD docs](https://argo-cd.readthedocs.io/en/latest/user-guide/resource_tracking/) for additional detail.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO --> <!-- vale Microsoft.HeadingAcronyms = NO -->
### Configuring Argo CD with Crossplane ### Configuring Argo CD with Crossplane

212
content/master/guides/import-existing-resources.md Normal file
View File

@ -0,0 +1,212 @@
---
title: Import Existing Resources
weight: 200
description: "Import existing resources into your control plane for Crossplane to manage"
---
If you have resources that are already provisioned in a Provider,
you can import them as managed resources and let Crossplane manage them.
A managed resource's [`managementPolicies`]({{<ref "../managed-resources/managed-resources#managementpolicies">}})
field enables importing external resources into Crossplane.
## Import resources in observe only mode
Start by importing external resources with an `Observe` [management policy]({{<ref "../managed-resources/managed-resources#managementpolicies">}}).
Crossplane imports observe only resources but never changes or deletes the
resources.
{{<hint "important" >}}
The managed resource `managementPolicies` option is a beta feature.
The Provider determines support for management policies.
Refer to the Provider's documentation to see if the Provider supports
management policies.
{{< /hint >}}
<!-- vale off -->
### Apply the Observe management policy
<!-- vale on -->
Create a new managed resource matching the
{{<hover label="oo-policy" line="1">}}apiVersion{{</hover>}} and
{{<hover label="oo-policy" line="2">}}kind{{</hover>}} of the resource
to import and add
{{<hover label="oo-policy" line="4">}}managementPolicies: ["Observe"]{{</hover>}} to the
{{<hover label="oo-policy" line="3">}}spec{{</hover>}}
For example, to import a GCP SQL DatabaseInstance, create a new resource with
the {{<hover label="oo-policy" line="4">}}managementPolicies: ["Observe"]{{</hover>}}
set.
```yaml {label="oo-policy",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
spec:
managementPolicies: ["Observe"]
```
### Add the external-name annotation
Add the {{<hover label="oo-ex-name" line="5">}}crossplane.io/external-name{{</hover>}}
annotation for the resource. This name must match the name inside the Provider.
For example, for a GCP database named
{{<hover label="oo-ex-name" line="5">}}my-external-database{{</hover>}}, apply
the
{{<hover label="oo-ex-name" line="5">}}crossplane.io/external-name{{</hover>}}
annotation with the value
{{<hover label="oo-ex-name" line="5">}}my-external-database{{</hover>}}.
```yaml {label="oo-ex-name",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
```
### Create a Kubernetes object name
Create a {{<hover label="oo-name" line="4">}}name{{</hover>}} to use for the
Kubernetes object.
For example, name the Kubernetes object
{{<hover label="oo-name" line="4">}}my-imported-database{{</hover>}}.
```yaml {label="oo-name",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
```
### Identify a specific external resource
If more than one resource inside the Provider shares the same name, identify the
specific resource with a unique
{{<hover line="9" label="oo-region">}}spec.forProvider{{</hover>}} field.
For example, only import the GCP SQL database in the
{{<hover line="10" label="oo-region">}}us-central1{{</hover>}} region.
```yaml {label="oo-region"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
forProvider:
region: "us-central1"
```
### Apply the managed resource
Apply the new managed resource. Crossplane syncs the status of the external
resource in the cloud with the newly created managed resource.
### View the discovered resource
Crossplane discovers the managed resource and populates the
{{<hover label="ooPopulated" line="12">}}status.atProvider{{</hover>}}
fields with the values from the external resource.
```yaml {label="ooPopulated",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
forProvider:
region: us-central1
status:
atProvider:
connectionName: crossplane-playground:us-central1:my-external-database
databaseVersion: POSTGRES_14
deletionProtection: true
firstIpAddress: 35.184.74.79
id: my-external-database
publicIpAddress: 35.184.74.79
region: us-central1
# Removed for brevity
settings:
- activationPolicy: ALWAYS
availabilityType: REGIONAL
diskSize: 100
# Removed for brevity
pricingPlan: PER_USE
tier: db-custom-4-26624
version: 4
conditions:
- lastTransitionTime: "2023-02-22T07:16:51Z"
reason: Available
status: "True"
type: Ready
- lastTransitionTime: "2023-02-22T07:16:51Z"
reason: ReconcileSuccess
status: "True"
type: Synced
```
<!-- vale off -->
## Control imported observe only resources
<!-- vale on -->
Crossplane can take active control of observe only imported resources by
changing the `managementPolicies` after import.
Change the {{<hover label="fc" line="8">}}managementPolicies{{</hover>}} field
of the managed resource to
{{<hover label="fc" line="8">}}["*"]{{</hover>}}.
Copy any required parameter values from
{{<hover label="fc" line="16">}}status.atProvider{{</hover>}} and provide them
in {{<hover label="fc" line="9">}}spec.forProvider{{</hover>}}.
{{< hint "tip" >}}
Manually copy the important `spec.atProvider` values to `spec.forProvider`.
{{< /hint >}}
```yaml {label="fc"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["*"]
forProvider:
databaseVersion: POSTGRES_14
region: us-central1
settings:
- diskSize: 100
tier: db-custom-4-26624
status:
atProvider:
databaseVersion: POSTGRES_14
region: us-central1
# Removed for brevity
settings:
- diskSize: 100
tier: db-custom-4-26624
# Removed for brevity
conditions:
- lastTransitionTime: "2023-02-22T07:16:51Z"
reason: Available
status: "True"
type: Ready
- lastTransitionTime: "2023-02-22T11:16:45Z"
reason: ReconcileSuccess
status: "True"
type: Synced
```
Crossplane now fully manages the imported resource. Crossplane applies any
changes to the managed resource in the Provider's external resource.

54
content/master/guides/self-signed-ca-certs.md
View File

@ -1,54 +0,0 @@
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
---
title: Self-signed CA certs
weight: 270
description: "Configure Crossplane with self-signed certificates"
---
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
> Using self-signed certificates isn't advised in production, it's
recommended to only use self-signed certificates for testing.
When Crossplane loads Configuration and Provider Packages from private
registries, you must configure it to trust the CA and Intermediate certs.
You need to install Crossplane via the Helm chart with the
`registryCaBundleConfig.name` and `registryCaBundleConfig.key` parameters
defined. See [Install Crossplane]({{<ref "../get-started/install" >}}).
## Configure
1. Create a CA Bundle (A file containing your Root and Intermediate
certificates in a specific order). You can do this with any text editor or
from the command line, so long as the resulting file contains all required crt
files in the proper order. Often, this is either a single
self-signed Root CA crt file, or an Intermediate crt and Root crt file. The
order of the crt files should be from lowest to highest in signing order.
For example, if you have a chain of two certificates below your Root
certificate, you place the bottom level Intermediate cert at the beginning of
the file, then the Intermediate cert that singed that cert, then the Root cert
that signed that cert.
2. Save the files as `[yourdomain].ca-bundle`.
3. Create a Kubernetes ConfigMap in your Crossplane system namespace:
```
kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
--from-file=ca-bundle=./[yourdomain].ca-bundle
```
4. Set the `registryCaBundleConfig.name` Helm chart parameter to
`ca-bundle-config` and the `registryCaBundleConfig.key` parameter to
`ca-bundle`.
> The Helm docs cover providing Helm with parameter values,
[Helm install](https://helm.sh/docs/helm/helm_install/). An example block
in an `override.yaml` file would look like this:
```
registryCaBundleConfig:
name: ca-bundle-config
key: ca-bundle
```

35
content/master/guides/upgrade-crossplane.md
View File

@ -7,9 +7,19 @@ description: "Upgrade Crossplane to newer versions"
The recommended upgrade method for an existing Crossplane install is to use The recommended upgrade method for an existing Crossplane install is to use
[Helm](http://helm.io). [Helm](http://helm.io).
<!-- vale write-good.Weasel = NO -->
{{<hint "important" >}}
Always upgrade Crossplane **one minor version at a time**, using the most recent
patch version available for each.
For example, if you are on `v1.18` and want to upgrade to `v2.0`, you should
first upgrade to `v1.19`, then `v1.20`, before finally upgrading to `v2.0`. The
upgrade path in this example looks like `v1.18` → `v1.19` → `v1.20` → `v2.0`.
{{</hint>}}
<!-- vale write-good.Weasel = YES -->
## Prerequisites ## Prerequisites
* [Helm](https://helm.sh/docs/intro/install/) version `v3.2.0` or later * [Helm](https://helm.sh/docs/intro/install/) version `v3.2.0` or later
## Add the Crossplane Helm repository ## Add the Crossplane Helm repository
Verify Helm has the Crossplane repository. Verify Helm has the Crossplane repository.
@ -27,35 +37,26 @@ helm repo update
``` ```
{{<hint "important" >}} {{<hint "important" >}}
Upgrading Crossplane without updating the Helm chart installs the last version Upgrading Crossplane without updating the Helm chart installs the last version
available in the locally cached Helm chart. available in the locally cached Helm chart.
{{< /hint >}} {{</hint>}}
## Upgrade Crossplane ## Upgrade Crossplane
Upgrade Crossplane with `helm upgrade`, providing the Crossplane namespace. Upgrade Crossplane with `helm upgrade`, providing the Crossplane namespace.
By default, Crossplane installs into the `crossplane-system` By default, Crossplane installs into the `crossplane-system`
namespace. namespace.
```shell ```shell
helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane
``` ```
Helm preserves any arguments or flags originally used when installing Helm preserves any arguments or flags originally used when installing
Crossplane. Crossplane.
Crossplane uses any new default behaviors unless they're changed in the `helm Crossplane uses any new default behaviors unless they're changed in the `helm
upgrade` command. upgrade` command.
For example, in v1.20.0 Crossplane changed the default image registry from Override new defaults by
`index.docker.io` to `xpkg.crossplane.io`. Upgrading Crossplane from a version [customizing the Helm chart]({{<ref "../get-started/install#customize-the-crossplane-helm-chart" >}})
before v1.20.0 updates the default package registry.
Override new defaults by
[customizing the Helm chart]({{<ref "../get-started/install#customize-the-crossplane-helm-chart" >}})
with the upgrade command. with the upgrade command.
For example, to maintain the original image registry use
```shell
helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane --set 'args={"--registry=index.docker.io"}'
```

59
content/master/guides/upgrade-to-crossplane-v2.md
View File

@ -4,12 +4,12 @@ weight: 410
description: "Upgrade from Crossplane v1 to v2" description: "Upgrade from Crossplane v1 to v2"
--- ---
Crossplane v2 introduces significant improvements while maintaining backward Crossplane v2 introduces significant improvements while maintaining backward
compatibility with most v1 configurations. This guide helps you upgrade from compatibility with most v1 configurations. This guide helps you upgrade from
Crossplane v1.x to v2. Crossplane v1.x to v2.
Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including
namespaced resources, the ability to compose any Kubernetes resource, and new namespaced resources, the ability to compose any Kubernetes resource, and new
operational workflows. operational workflows.
{{<hint "important">}} {{<hint "important">}}
@ -18,11 +18,11 @@ If you're running an earlier version, upgrade to v1.20 first.
{{</hint>}} {{</hint>}}
{{<hint "note">}} {{<hint "note">}}
There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and
MRs to v2 namespaced style. You can upgrade to Crossplane v2 and MRs to v2 namespaced style. You can upgrade to Crossplane v2 and
start using the new namespaced features right away - your existing v1 start using the new namespaced features right away - your existing v1
resources continue working unchanged. See resources continue working unchanged. See
[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) [crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726)
for migration tooling progress. for migration tooling progress.
{{</hint>}} {{</hint>}}
@ -45,7 +45,7 @@ Crossplane v2 removes these deprecated features:
* [Default registry flag](#default-registry-flag) * [Default registry flag](#default-registry-flag)
### Native patch and transform composition ### Native patch and transform composition
**Deprecated in**: v1.17 **Deprecated in**: v1.17
**Replaced by**: [Composition functions]({{<ref "../composition/compositions">}}) **Replaced by**: [Composition functions]({{<ref "../composition/compositions">}})
If you're using `spec.mode: Resources` in your Compositions, migrate to If you're using `spec.mode: Resources` in your Compositions, migrate to
@ -55,14 +55,14 @@ composition functions before upgrading.
Compositions: Compositions:
```shell ```shell
# Convert patch and transform to function pipelines # Convert patch and transform to function pipelines
crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml
``` ```
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
### ControllerConfig type ### ControllerConfig type
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
**Deprecated in**: v1.11 **Deprecated in**: v1.11
**Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}}) **Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}})
Update any ControllerConfig resources to use DeploymentRuntimeConfig instead. Update any ControllerConfig resources to use DeploymentRuntimeConfig instead.
@ -78,13 +78,13 @@ crossplane beta convert deployment-runtime controller-config.yaml -o deployment-
### External secret stores ### External secret stores
**Status**: alpha feature, unmaintained **Status**: alpha feature, unmaintained
If you're using external secret stores, migrate to native Kubernetes secrets If you're using external secret stores, migrate to native Kubernetes secrets
or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading. or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading.
### Default registry flag ### Default registry flag
**Removed**: `--registry` flag for default package registry **Removed**: `--registry` flag for default package registry
All packages must now use fully qualified names including the registry All packages must now use fully qualified names including the registry
host name. Check your packages with: host name. Check your packages with:
```shell ```shell
@ -92,7 +92,7 @@ kubectl get pkg -o wide
``` ```
Update any packages without registry host names before upgrading. For example: Update any packages without registry host names before upgrading. For example:
- ❌ `crossplane-contrib/provider-aws-s3:v1.23.0` - ❌ `crossplane-contrib/provider-aws-s3:v1.23.0`
- ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0` - ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0`
## Who can upgrade ## Who can upgrade
@ -112,7 +112,7 @@ If you're using any removed features, migrate away from them first.
The recommended upgrade approach: The recommended upgrade approach:
1. [Prepare for upgrade](#1-prepare-for-upgrade) 1. [Prepare for upgrade](#1-prepare-for-upgrade)
2. [Upgrade Crossplane core](#2-upgrade-crossplane-core) 2. [Upgrade Crossplane core](#2-upgrade-crossplane-core)
3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies) 3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies)
4. [Upgrade providers](#4-upgrade-providers) 4. [Upgrade providers](#4-upgrade-providers)
5. [Start using v2 features](#5-start-using-v2-features) 5. [Start using v2 features](#5-start-using-v2-features)
@ -148,7 +148,7 @@ kubectl get pods -n crossplane-system
### 3. Configure managed resource activation policies ### 3. Configure managed resource activation policies
Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed
resources (`*`). Before installing v2 providers, you can optionally customize resources (`*`). Before installing v2 providers, you can optionally customize
this for better cluster resource efficiency. this for better cluster resource efficiency.
@ -159,7 +159,7 @@ Check what managed resources you use:
kubectl get managed kubectl get managed
``` ```
Optionally, replace the default MRAP with a targeted one that activates only Optionally, replace the default MRAP with a targeted one that activates only
the resources you need: the resources you need:
```shell ```shell
@ -179,21 +179,21 @@ spec:
# Legacy cluster-scoped resources (existing v1 resources) # Legacy cluster-scoped resources (existing v1 resources)
- buckets.s3.aws.upbound.io - buckets.s3.aws.upbound.io
- instances.ec2.aws.upbound.io - instances.ec2.aws.upbound.io
# Modern namespaced resources (new v2 resources) # Modern namespaced resources (new v2 resources)
- buckets.s3.aws.m.upbound.io - buckets.s3.aws.m.upbound.io
- instances.ec2.aws.m.upbound.io - instances.ec2.aws.m.upbound.io
``` ```
{{<hint "tip">}} {{<hint "tip">}}
Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs
`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern `s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern
namespaced managed resources. namespaced managed resources.
{{</hint>}} {{</hint>}}
### 4. Upgrade providers ### 4. Upgrade providers
Upgrade your providers to versions that support both namespaced and Upgrade your providers to versions that support both namespaced and
cluster-scoped managed resources: cluster-scoped managed resources:
```shell ```shell
@ -232,6 +232,15 @@ Existing Compositions work with Crossplane v2 with minimal changes. v2 managed
resources are schematically identical to v1 managed resources - they're just resources are schematically identical to v1 managed resources - they're just
namespaced. namespaced.
{{<hint "important">}}
**Don't update existing compositions that are actively used by composite
resources in your control plane.**
Updating a live composition that's in use by existing XRs could disrupt or
replace your resources. Use the below migration approach only when creating new
compositions for new resources.
{{</hint>}}
To use v2 namespaced managed resources in compositions: To use v2 namespaced managed resources in compositions:
1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io` 1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io`
@ -337,7 +346,7 @@ Your existing v1 resources continue working in Crossplane v2:
* **Legacy cluster-scoped MRs**: Continue working unchanged * **Legacy cluster-scoped MRs**: Continue working unchanged
* **Existing Compositions**: Continue working with legacy XRs * **Existing Compositions**: Continue working with legacy XRs
These resources use `LegacyCluster` scope internally and maintain full These resources use `LegacyCluster` scope internally and maintain full
backward compatibility. backward compatibility.
For example, existing v1-style XRDs continue working with claims: For example, existing v1-style XRDs continue working with claims:
@ -383,5 +392,5 @@ After upgrading:
3. **Try Operations**: Experiment with operational workflows 3. **Try Operations**: Experiment with operational workflows
4. **Plan migration**: Consider which existing resources to migrate to v2 patterns 4. **Plan migration**: Consider which existing resources to migrate to v2 patterns
Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the
updated [composition documentation]({{<ref "../composition/compositions">}}). updated [composition documentation]({{<ref "../composition/compositions">}}).

22
content/master/managed-resources/managed-resource-activation-policies.md
View File

@ -83,6 +83,13 @@ spec:
- clusters.eks.aws.m.crossplane.io - clusters.eks.aws.m.crossplane.io
``` ```
{{<hint "important">}}
Use the **plural** name when using a complete MRD name, aligning with how
Kubernetes expresses the complete names of CRDs.
For example, use `buckets`, as opposed to `bucket`, in `buckets.s3.aws.m.crossplane.io`.
{{</hint>}}
### Wildcard patterns ### Wildcard patterns
Use `*` wildcards to match multiple resources: Use `*` wildcards to match multiple resources:
@ -91,7 +98,7 @@ Use `*` wildcards to match multiple resources:
spec: spec:
activate: activate:
- "*.s3.aws.m.crossplane.io" # All S3 resources - "*.s3.aws.m.crossplane.io" # All S3 resources
- "*.ec2.aws.m.crossplane.io" # All EC2 resources - "*.ec2.aws.m.crossplane.io" # All EC2 resources
- "*.rds.aws.m.crossplane.io" # All RDS databases - "*.rds.aws.m.crossplane.io" # All RDS databases
``` ```
@ -255,7 +262,7 @@ spec:
- "*.s3.aws.m.crossplane.io" - "*.s3.aws.m.crossplane.io"
- "*.storage.gcp.m.crossplane.io" - "*.storage.gcp.m.crossplane.io"
--- ---
# Database team MRAP # Database team MRAP
apiVersion: apiextensions.crossplane.io/v1alpha1 apiVersion: apiextensions.crossplane.io/v1alpha1
kind: ManagedResourceActivationPolicy kind: ManagedResourceActivationPolicy
metadata: metadata:
@ -332,7 +339,7 @@ status:
reason: Running reason: Running
activated: activated:
- buckets.s3.aws.m.crossplane.io - buckets.s3.aws.m.crossplane.io
- instances.ec2.aws.m.crossplane.io - instances.ec2.aws.m.crossplane.io
- instances.rds.aws.m.crossplane.io - instances.rds.aws.m.crossplane.io
- securitygroups.ec2.aws.m.crossplane.io - securitygroups.ec2.aws.m.crossplane.io
- subnets.ec2.aws.m.crossplane.io - subnets.ec2.aws.m.crossplane.io
@ -373,7 +380,7 @@ status:
```shell ```shell
# List available MRDs # List available MRDs
kubectl get mrds kubectl get mrds
# Check your pattern matches # Check your pattern matches
kubectl get mrds -o name | grep "your-pattern" kubectl get mrds -o name | grep "your-pattern"
``` ```
@ -405,7 +412,7 @@ status:
```yaml ```yaml
conditions: conditions:
- type: Healthy - type: Healthy
status: "Unknown" status: "Unknown"
reason: EncounteredErrors reason: EncounteredErrors
message: "failed to activate 2 of 5 ManagedResourceDefinitions" message: "failed to activate 2 of 5 ManagedResourceDefinitions"
``` ```
@ -443,8 +450,9 @@ conflicts. This enables team-based activation strategies and Configuration
package dependencies. package dependencies.
<!-- vale alex.ProfanityUnlikely = NO --> <!-- vale alex.ProfanityUnlikely = NO -->
1. **Start specific, broaden as needed** - Begin with exact resource names, 1. **Start specific, broaden as needed** - Begin with exact resource names
add wildcards only when beneficial for maintainability (using the plural name for each resource), add wildcards only when beneficial for
maintainability
2. **Plan for provider evolution** - Design wildcard patterns that 2. **Plan for provider evolution** - Design wildcard patterns that
accommodate new resources as providers add them (for example, accommodate new resources as providers add them (for example,
`*.s3.aws.m.crossplane.io` works for future S3 resources) `*.s3.aws.m.crossplane.io` works for future S3 resources)

181
content/master/packages/image-configs.md
View File

@ -10,6 +10,21 @@ description: "Centralized control of package image configuration"
Crossplane package images. It allows you to configure package manager behavior Crossplane package images. It allows you to configure package manager behavior
for images globally, without needing to be referenced by other objects. for images globally, without needing to be referenced by other objects.
## Matching image references
`spec.matchImages` is a list of image references that the `ImageConfig` applies
to. Each item in the list specifies the type and configuration of the image
reference to match. The only supported type is `Prefix`, which matches the
prefix of the image reference. No wildcards are supported. The `type` defaults
to `Prefix` and can be omitted.
When there are multiple `ImageConfigs` matching an image reference, the one with
the longest matching prefix is selected. If there are multiple `ImageConfigs`
with the same longest matching prefix, one of them is selected
arbitrarily. Please note that this situation occurs only if there are
overlapping prefixes in the `matchImages` lists of different `ImageConfig`
resources, which should be avoided.
## Configuring a pull secret ## Configuring a pull secret
You can use `ImageConfig` to inject a pull secret into the Crossplane package You can use `ImageConfig` to inject a pull secret into the Crossplane package
@ -46,43 +61,6 @@ following command:
kubectl -n crossplane-system create secret docker-registry acme-registry-credentials --docker-server=registry1.com --docker-username=<user> --docker-password=<password> kubectl -n crossplane-system create secret docker-registry acme-registry-credentials --docker-server=registry1.com --docker-username=<user> --docker-password=<password>
``` ```
### Matching image references
`spec.matchImages` is a list of image references that the `ImageConfig` applies
to. Each item in the list specifies the type and configuration of the image
reference to match. The only supported type is `Prefix`, which matches the
prefix of the image reference. No wildcards are supported. The `type` defaults
to `Prefix` and can be omitted.
When there are multiple `ImageConfigs` matching an image reference, the one
with the longest matching prefix is selected. If there are multiple
`ImageConfigs` with the same longest matching prefix, one of them is selected
arbitrarily. Please note that this situation occurs only if there are
overlapping prefixes in the `matchImages` lists of different `ImageConfig`
resources, which should be avoided.
### Debugging
When the package manager selects an `ImageConfig` for a package, it throws an
event with the reason `ImageConfigSelection` and the name of the selected
`ImageConfig` and injected pull secret. You can find these events both on the
package and package revision resources.
For example, the following event indicates that the `ImageConfig` named
`acme-packages` was selected for the configuration named `acme-configuration-foo`:
```shell
$ kubectl describe configuration acme-configuration-foo
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal ImageConfigSelection 45s packages/configuration.pkg.crossplane.io Selected pullSecret "acme-registry-credentials" from ImageConfig "acme-packages" for registry authentication
```
If you can't find the expected event, ensure the prefix of the image reference
matches the `matchImages` list of any `ImageConfig` resources in the cluster.
## Configuring signature verification ## Configuring signature verification
{{<hint "important" >}} {{<hint "important" >}}
@ -98,7 +76,7 @@ rejects the package deployment.
In the following example, the `ImageConfig` resource named `verify-acme-packages` In the following example, the `ImageConfig` resource named `verify-acme-packages`
configures verification of the signature of images with the prefixes configures verification of the signature of images with the prefixes
`registry1.com/acme-co/configuration-foo` and `registry1.com/acme-co/configuration-foo` and
`registry1.com/acme-co/configuration-bar`. `registry1.com/acme-co/configuration-bar`.
In the example below, the `ImageConfig` resource named `verify-acme-packages` is In the example below, the `ImageConfig` resource named `verify-acme-packages` is
set up to verify the signatures of images with the prefixes set up to verify the signatures of images with the prefixes
@ -211,4 +189,129 @@ If you can't see this condition on the package revision resource, namely
`ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that `ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that
you enable the feature. you enable the feature.
<!-- vale write-good.Passive = YES --> ## Rewriting image paths
You can use an `ImageConfig` to pull package images from an alternative location
such as a private registry. `spec.rewriteImages` specifies how to rewrite the
paths of matched images.
Only prefix replacement is supported. The prefix specified in
`spec.rewriteImage.prefix` replaces the matched prefix from `matchImages`. For
example, the following `ImageConfig` replaces `xpkg.crossplane.io` with
`registry1.com` for any image with the prefix `xpkg.crossplane.io`.
```yaml
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: private-registry-rewrite
spec:
matchImages:
- prefix: xpkg.crossplane.io
rewriteImage:
prefix: registry1.com
```
In this example, installing the provider package
`xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.4.0` will result in the
package manager pulling the provider from
`registry1.com/crossplane-contrib/provider-nop:v0.4.0`.
Rewriting image paths via `ImageConfig` is useful when mirroring packages to a
private registry, because it allows a package and all its dependencies to be
pulled from the same registry. For example, the provider
`xpkg.crossplane.io/crossplane-contrib/provider-aws-s3` has a dependency on
`xpkg.crossplane.io/crossplane-contrib/provider-family-aws`. If you mirror the
packages to your own registry at `registry1.com` and install them without an
`ImageConfig`, the package manager still attempts to pull the dependency from
`xpkg.crossplane.io`. With the preceding `ImageConfig`, the dependency is pulled
from `registry1.com`.
Rewriting an image path with `ImageConfig` doesn't change the `spec.package`
field of the package resource. The rewritten path is recorded in the
`status.resolvedPackage` field. The preceding example results in the following:
```shell
kubectl describe provider crossplane-contrib-provider-family-aws
...
Spec:
...
Package: xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.22.0
Status:
...
Resolved Package: registry1.com/crossplane-contrib/provider-family-aws:v1.22.0
```
### Interaction with other operations
{{<hint "tip" >}}
Image rewriting is always done before other `ImageConfig` operations. If you
wish to also configure pull secrets or signature verification as well as
rewriting, those `ImageConfig` resources must match the rewritten image path.
{{< /hint >}}
For example, if you are mirroring packages from `xpkg.crossplane.io` to
`registry1.com` and need to configure pull secrets for `registry1.com`, two
`ImageConfig` resources are necessary:
```yaml
# Rewrite xpkg.crossplane.io -> registry1.com
---
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: private-registry-rewrite
spec:
matchImages:
- prefix: xpkg.crossplane.io
rewriteImage:
prefix: registry1.com
# Configure pull secrets for registry1.com
---
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: private-registry-auth
spec:
matchImages:
- type: Prefix
prefix: registry1.com
registry:
authentication:
pullSecretRef:
name: private-registry-credentials
```
## Debugging
When the package manager selects an `ImageConfig` for a package, it throws an
event with the reason `ImageConfigSelection` and the name of the selected
`ImageConfig` and injected pull secret. You can find these events both on the
package and package revision resources. The package manager also updates the
`appliedImageConfigRefs` field in the package status to show the purpose for
which each `ImageConfig` was selected.
For example, the following event and status show that the `ImageConfig` named
`acme-packages` was used to provide a pull secret for the configuration named
`acme-configuration-foo`:
```shell
kubectl describe configuration acme-configuration-foo
...
Status:
Applied Image Config Refs:
Name: acme-packages
Reason: SetImagePullSecret
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal ImageConfigSelection 45s packages/configuration.pkg.crossplane.io Selected pullSecret "acme-registry-credentials" from ImageConfig "acme-packages" for registry authentication
```
If you can't find the expected event and `appliedImageConfigRefs` entry, ensure
the prefix of the image reference matches the `matchImages` list of any
`ImageConfig` resources in the cluster.
<!-- vale write-good.Passive = YES -->

1
content/v2.0-preview/_index.md
View File

@ -3,6 +3,7 @@ title: "Welcome"
weight: -1 weight: -1
cascade: cascade:
version: "2.0-preview" version: "2.0-preview"
hidden: true
--- ---
Welcome to the Crossplane documentation. Crossplane is a control plane framework Welcome to the Crossplane documentation. Crossplane is a control plane framework

26
content/v2.0/get-started/install.md
View File

@ -87,7 +87,7 @@ crossplane-rbac-manager-86d9b5cf9f-2vc4s 1/1 Running 0 26m
Crossplane supports customizations at install time by configuring the Helm Crossplane supports customizations at install time by configuring the Helm
chart. chart.
Read [the Helm chart README](https://github.com/crossplane/crossplane/blob/v2/cluster/charts/crossplane/README.md#configuration) Read [the Helm chart README](https://github.com/crossplane/crossplane/blob/v2/cluster/charts/crossplane/README.md#configuration)
to learn what customizations are available. to learn what customizations are available.
Read [the Helm documentation](https://helm.sh/docs/) to learn how to run Helm Read [the Helm documentation](https://helm.sh/docs/) to learn how to run Helm
@ -103,25 +103,17 @@ at the table below.
{{< expand "Feature flags" >}} {{< expand "Feature flags" >}}
{{< table caption="Feature flags" >}} {{< table caption="Feature flags" >}}
| Status | Flag | Description | | Status | Flag | Description |
| --- | --- | --- | |--------|-----------------------------------------|---------------------------------------------------------------------------|
| Beta | `--enable-deployment-runtime-configs` | Enable support for DeploymentRuntimeConfigs. | | Beta | `--enable-deployment-runtime-configs` | Enable support for DeploymentRuntimeConfigs. |
| Beta | `--enable-usages` | Enable support for Usages. | | Beta | `--enable-usages` | Enable support for Usages. |
| Beta | `--enable-realtime-compositions` | Enable support for real time compositions. | | 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-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-function-response-cache` | Enable caching of composition function responses to improve performance. |
| Alpha | `--enable-signature-verification` | Enable support for package signature verification via ImageConfig API. | | Alpha | `--enable-signature-verification` | Enable support for package signature verification via ImageConfig API. |
{{< /table >}} {{< /table >}}
{{< /expand >}} {{< /expand >}}
Set these flags either in the `values.yaml` file or at install time using the Set these flags either in the `values.yaml` file or at install time using the
`--set` flag, for example: `--set `--set` flag, for example: `--set
args='{"--enable-composition-functions","--enable-composition-webhook-schema-validation"}'`. args='{"--enable-composition-functions","--enable-composition-webhook-schema-validation"}'`.
#### Change the default package registry
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages.
Change the default registry location during the Crossplane install with
`--set args='{"--registry=index.docker.io"}'`.

266
content/v2.0/guides/change-logs.md Normal file
View File

@ -0,0 +1,266 @@
---
title: Change Logs
weight: 210
description: "Change logs help you audit all changes made to your resources"
state: alpha
alphaVersion: "1.17"
---
The change logs feature helps users of Crossplane Providers understand what
changes a provider makes to the resources it manages. Whenever a provider
creates, updates, or deletes a managed resource, the provider records an entry
explaining the details of the change in its change log.
Change logs are important for awareness of the changes that a provider is
making to its managed resources. Due to the nature of Crossplane's active
reconciliation, it's possible for a provider to make changes to managed
resources without any user interaction. Consider the scenario when someone
updates a resource outside of Crossplane, for example via the AWS console or
`gcloud` CLI. When Crossplane detects this configuration drift, it
enforces the declared state and corrects the unexpected change
without any user interaction.
With Crossplane acting continuously and autonomously to update critical
infrastructure, it's vital for users to have insight into the operations the provider performs,
so they can build and maintain a strong sense of confidence and trust
in their control planes. Change logs provide details about all changes the
provider makes, so users can remain aware of any changes, even when they aren't
explicitly expecting any.
{{<hint "tip">}} Change logs help you understand all the changes a provider is
making to your resources, even when changes weren't explicitly requested, for
example because of Crossplane's automatic correction of configuration drift.
{{</hint>}}
## Enabling change logs
{{<hint "important" >}} Change logs are an alpha feature and must be explicitly
enabled for each provider through the use of a `DeploymentRuntimeConfig`.
{{</hint >}}
To enable change logs for a provider, use a `DeploymentRuntimeConfig` to
configure each provider pod that should start producing change logs. The
`DeploymentRuntimeConfig` has several important configuration details:
1. A command line argument to the provider container that enables the change
logs feature, for example `--enable-changelogs`.
1. A [side car container](https://github.com/crossplane/changelogs-sidecar) that
collects change events and produces change log entries to the provider's pod
logs.
1. A shared volume mounted to both the provider and sidecar containers that
enables communication of change events between the two containers.
### Prerequisites
This guide assumes you have a control plane with [Crossplane installed]({{<ref "../get-started/install">}}).
It also assumes you have the [`jq` tool installed](https://jqlang.org/download/),
to perform lightweight querying and filtering of the content in the change logs.
The only other prerequisite for enabling change logs is provider support for the
change logs feature. Support for change logs is optional, and not all providers
in the Crossplane ecosystem have added it yet.
{{<hint "tip">}} Not all providers support the change logs feature. Check with
your provider of choice to confirm it has added support for change logs.
{{</hint>}}
This guide walks through a full example of generating change logs with
[`provider-kubernetes`](https://github.com/crossplane-contrib/provider-kubernetes).
### Create a `DeploymentRuntimeConfig`
Create a `DeploymentRuntimeConfig` that enables change logs for
the provider when it's installed by performing the following configuration
steps:
1. Set the {{<hover label="drc" line="15">}}--enable-changelogs{{</hover>}} flag on the provider.
1. Add the {{<hover label="drc" line="19">}}sidecar container{{</hover>}} to the provider pod.
1. Declare a {{<hover label="drc" line="24">}}shared volume{{</hover>}} and mount it in the {{<hover label="drc" line="16">}}provider
container{{</hover>}} and the {{<hover label="drc" line="21">}}sidecar
container{{</hover>}}.
```yaml {label="drc",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: enable-changelogs
spec:
deploymentTemplate:
spec:
selector: {}
template:
spec:
containers:
- name: package-runtime
args:
- --enable-changelogs
volumeMounts:
- name: changelogs-vol
mountPath: /var/run/changelogs
- name: changelogs-sidecar
image: xpkg.crossplane.io/crossplane/changelogs-sidecar:v0.0.1
volumeMounts:
- name: changelogs-vol
mountPath: /var/run/changelogs
volumes:
- name: changelogs-vol
emptyDir: {}
serviceAccountTemplate:
metadata:
name: provider-kubernetes
EOF
```
### Install the provider
Install the {{<hover label="provider" line="7">}}provider{{</hover>}} and
instruct it to use the {{<hover label="provider" line="8">}}DeploymentRuntimeConfig{{</hover>}}
that was just created.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-kubernetes
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-kubernetes:v0.18.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
name: enable-changelogs
EOF
```
### Configure permissions
To allow the provider to create Kubernetes resources in the control
plane, grant the appropriate permissions. This guide only creates a
`ConfigMap`, so it only requires permissions for that resource type.
{{<hint "important">}} This guide grants specific permissions to the provider
for example purposes. This approach isn't intended to be representative of a
production environment. See more examples for configuring `provider-kubernetes` in its
[examples directory](https://github.com/crossplane-contrib/provider-kubernetes/tree/main/examples/namespaced/provider).
{{</hint>}}
```yaml {label="rbac",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: configmap-edit
rules:
- apiGroups:
- ""
resources:
- configmaps
verbs:
- "*"
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: provider-kubernetes-configmap-edit
subjects:
- kind: ServiceAccount
name: provider-kubernetes
namespace: crossplane-system
roleRef:
kind: ClusterRole
name: configmap-edit
apiGroup: rbac.authorization.k8s.io
---
apiVersion: kubernetes.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: InjectedIdentity
EOF
```
### Create a resource
After installing and configuring the provider with change logs enabled,
create a resource that generates change log entries that reflect the actions
the control plane takes.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: kubernetes.crossplane.io/v1alpha2
kind: Object
metadata:
name: configmap-for-changelogs
spec:
forProvider:
manifest:
apiVersion: v1
kind: ConfigMap
metadata:
namespace: default
name: configmap-for-changelogs
data:
key-1: cool-value-1
EOF
```
### Examine the change logs
Confirm that the change logs include the resource creation operation.
Examine the pod logs for `provider-kubernetes`, specifically the
`changelogs-sidecar` container:
```shell {label="changelogs-output-full",copy-lines="1"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar | jq
{
"timestamp": "2025-04-25T08:23:34Z",
"provider": "provider-kubernetes:v0.18.0",
"apiVersion": "kubernetes.crossplane.io/v1alpha2",
"kind": "Object",
"name": "configmap-for-changelogs",
"externalName": "configmap-for-changelogs",
"operation": "OPERATION_TYPE_CREATE",
"snapshot": {
...(omitted for brevity)...
```
Each change log entry contains rich information about the state of the resource
when the change operation occurred. Because each entry is a structured `JSON`
object, you can filter and query them to find any subset of information that
interests you:
```shell {label="changelogs-output-scoped",copy-lines="1-2"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
```
### Full lifecycle operations
Update and delete operations also generate corresponding change log entries.
Update the resource by patching its data field `key-1` with a new value
`cooler-value-2`:
```shell {label="object-patch",copy-lines="1-2"}
kubectl patch object configmap-for-changelogs --type=json \
-p='[{"op": "replace", "path": "/spec/forProvider/manifest/data/key-1", "value": "cooler-value-2"}]'
object.kubernetes.crossplane.io/configmap-for-changelogs patched
```
Then, delete the object entirely:
```shell {label="object-delete",copy-lines="1"}
kubectl delete object configmap-for-changelogs
object.kubernetes.crossplane.io "configmap-for-changelogs" deleted
```
Check the change logs again to verify that they include both the update and delete operations and capture the
object's full lifecycle:
```shell {label="changelogs-output-final",copy-lines="1-2"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
"2025-04-25T08:24:21Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_UPDATE"
"2025-04-25T08:24:25Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_DELETE"
```

16
content/v2.0/guides/crossplane-with-argo-cd.md
View File

@ -1,25 +1,21 @@
<!-- vale Google.Headings = NO --> ---
<!-- vale Microsoft.HeadingAcronyms = NO -->
---
title: Configuring Crossplane with Argo CD title: Configuring Crossplane with Argo CD
weight: 270 weight: 270
description: "Deploy Crossplane resources with GitOps" description: "Deploy Crossplane resources with GitOps"
--- ---
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
[Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io) [Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io)
are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes
cluster into a Universal Control Plane for all your resources. Configuration details are cluster into a Universal Control Plane for all your resources. Configuration details are
required in order for the two to work together properly. required in order for the two to work together properly.
This doc will help you understand these requirements. It is recommended to use This doc will help you understand these requirements. It is recommended to use
Argo CD version 2.4.8 or later with Crossplane. Argo CD version 2.4.8 or later with Crossplane.
Argo CD synchronizes Kubernetes resource manifests stored in a Git repository Argo CD synchronizes Kubernetes resource manifests stored in a Git repository
with those running in a Kubernetes cluster (GitOps). Argo CD has different ways to configure with those running in a Kubernetes cluster (GitOps). Argo CD has different ways to configure
how it tracks resources. With Crossplane, you need to configure Argo CD how it tracks resources. With Crossplane, you need to configure Argo CD
to use Annotation based resource tracking. See the [Argo CD docs](https://argo-cd.readthedocs.io/en/latest/user-guide/resource_tracking/) for additional detail. to use Annotation based resource tracking. See the [Argo CD docs](https://argo-cd.readthedocs.io/en/latest/user-guide/resource_tracking/) for additional detail.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO --> <!-- vale Microsoft.HeadingAcronyms = NO -->
### Configuring Argo CD with Crossplane ### Configuring Argo CD with Crossplane

212
content/v2.0/guides/import-existing-resources.md Normal file
View File

@ -0,0 +1,212 @@
---
title: Import Existing Resources
weight: 200
description: "Import existing resources into your control plane for Crossplane to manage"
---
If you have resources that are already provisioned in a Provider,
you can import them as managed resources and let Crossplane manage them.
A managed resource's [`managementPolicies`]({{<ref "../managed-resources/managed-resources#managementpolicies">}})
field enables importing external resources into Crossplane.
## Import resources in observe only mode
Start by importing external resources with an `Observe` [management policy]({{<ref "../managed-resources/managed-resources#managementpolicies">}}).
Crossplane imports observe only resources but never changes or deletes the
resources.
{{<hint "important" >}}
The managed resource `managementPolicies` option is a beta feature.
The Provider determines support for management policies.
Refer to the Provider's documentation to see if the Provider supports
management policies.
{{< /hint >}}
<!-- vale off -->
### Apply the Observe management policy
<!-- vale on -->
Create a new managed resource matching the
{{<hover label="oo-policy" line="1">}}apiVersion{{</hover>}} and
{{<hover label="oo-policy" line="2">}}kind{{</hover>}} of the resource
to import and add
{{<hover label="oo-policy" line="4">}}managementPolicies: ["Observe"]{{</hover>}} to the
{{<hover label="oo-policy" line="3">}}spec{{</hover>}}
For example, to import a GCP SQL DatabaseInstance, create a new resource with
the {{<hover label="oo-policy" line="4">}}managementPolicies: ["Observe"]{{</hover>}}
set.
```yaml {label="oo-policy",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
spec:
managementPolicies: ["Observe"]
```
### Add the external-name annotation
Add the {{<hover label="oo-ex-name" line="5">}}crossplane.io/external-name{{</hover>}}
annotation for the resource. This name must match the name inside the Provider.
For example, for a GCP database named
{{<hover label="oo-ex-name" line="5">}}my-external-database{{</hover>}}, apply
the
{{<hover label="oo-ex-name" line="5">}}crossplane.io/external-name{{</hover>}}
annotation with the value
{{<hover label="oo-ex-name" line="5">}}my-external-database{{</hover>}}.
```yaml {label="oo-ex-name",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
```
### Create a Kubernetes object name
Create a {{<hover label="oo-name" line="4">}}name{{</hover>}} to use for the
Kubernetes object.
For example, name the Kubernetes object
{{<hover label="oo-name" line="4">}}my-imported-database{{</hover>}}.
```yaml {label="oo-name",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
```
### Identify a specific external resource
If more than one resource inside the Provider shares the same name, identify the
specific resource with a unique
{{<hover line="9" label="oo-region">}}spec.forProvider{{</hover>}} field.
For example, only import the GCP SQL database in the
{{<hover line="10" label="oo-region">}}us-central1{{</hover>}} region.
```yaml {label="oo-region"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
forProvider:
region: "us-central1"
```
### Apply the managed resource
Apply the new managed resource. Crossplane syncs the status of the external
resource in the cloud with the newly created managed resource.
### View the discovered resource
Crossplane discovers the managed resource and populates the
{{<hover label="ooPopulated" line="12">}}status.atProvider{{</hover>}}
fields with the values from the external resource.
```yaml {label="ooPopulated",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["Observe"]
forProvider:
region: us-central1
status:
atProvider:
connectionName: crossplane-playground:us-central1:my-external-database
databaseVersion: POSTGRES_14
deletionProtection: true
firstIpAddress: 35.184.74.79
id: my-external-database
publicIpAddress: 35.184.74.79
region: us-central1
# Removed for brevity
settings:
- activationPolicy: ALWAYS
availabilityType: REGIONAL
diskSize: 100
# Removed for brevity
pricingPlan: PER_USE
tier: db-custom-4-26624
version: 4
conditions:
- lastTransitionTime: "2023-02-22T07:16:51Z"
reason: Available
status: "True"
type: Ready
- lastTransitionTime: "2023-02-22T07:16:51Z"
reason: ReconcileSuccess
status: "True"
type: Synced
```
<!-- vale off -->
## Control imported observe only resources
<!-- vale on -->
Crossplane can take active control of observe only imported resources by
changing the `managementPolicies` after import.
Change the {{<hover label="fc" line="8">}}managementPolicies{{</hover>}} field
of the managed resource to
{{<hover label="fc" line="8">}}["*"]{{</hover>}}.
Copy any required parameter values from
{{<hover label="fc" line="16">}}status.atProvider{{</hover>}} and provide them
in {{<hover label="fc" line="9">}}spec.forProvider{{</hover>}}.
{{< hint "tip" >}}
Manually copy the important `spec.atProvider` values to `spec.forProvider`.
{{< /hint >}}
```yaml {label="fc"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
name: my-imported-database
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicies: ["*"]
forProvider:
databaseVersion: POSTGRES_14
region: us-central1
settings:
- diskSize: 100
tier: db-custom-4-26624
status:
atProvider:
databaseVersion: POSTGRES_14
region: us-central1
# Removed for brevity
settings:
- diskSize: 100
tier: db-custom-4-26624
# Removed for brevity
conditions:
- lastTransitionTime: "2023-02-22T07:16:51Z"
reason: Available
status: "True"
type: Ready
- lastTransitionTime: "2023-02-22T11:16:45Z"
reason: ReconcileSuccess
status: "True"
type: Synced
```
Crossplane now fully manages the imported resource. Crossplane applies any
changes to the managed resource in the Provider's external resource.

54
content/v2.0/guides/self-signed-ca-certs.md
View File

@ -1,54 +0,0 @@
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
---
title: Self-signed CA certs
weight: 270
description: "Configure Crossplane with self-signed certificates"
---
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
> Using self-signed certificates isn't advised in production, it's
recommended to only use self-signed certificates for testing.
When Crossplane loads Configuration and Provider Packages from private
registries, you must configure it to trust the CA and Intermediate certs.
You need to install Crossplane via the Helm chart with the
`registryCaBundleConfig.name` and `registryCaBundleConfig.key` parameters
defined. See [Install Crossplane]({{<ref "../get-started/install" >}}).
## Configure
1. Create a CA Bundle (A file containing your Root and Intermediate
certificates in a specific order). You can do this with any text editor or
from the command line, so long as the resulting file contains all required crt
files in the proper order. Often, this is either a single
self-signed Root CA crt file, or an Intermediate crt and Root crt file. The
order of the crt files should be from lowest to highest in signing order.
For example, if you have a chain of two certificates below your Root
certificate, you place the bottom level Intermediate cert at the beginning of
the file, then the Intermediate cert that singed that cert, then the Root cert
that signed that cert.
2. Save the files as `[yourdomain].ca-bundle`.
3. Create a Kubernetes ConfigMap in your Crossplane system namespace:
```
kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
--from-file=ca-bundle=./[yourdomain].ca-bundle
```
4. Set the `registryCaBundleConfig.name` Helm chart parameter to
`ca-bundle-config` and the `registryCaBundleConfig.key` parameter to
`ca-bundle`.
> The Helm docs cover providing Helm with parameter values,
[Helm install](https://helm.sh/docs/helm/helm_install/). An example block
in an `override.yaml` file would look like this:
```
registryCaBundleConfig:
name: ca-bundle-config
key: ca-bundle
```

35
content/v2.0/guides/upgrade-crossplane.md
View File

@ -7,9 +7,19 @@ description: "Upgrade Crossplane to newer versions"
The recommended upgrade method for an existing Crossplane install is to use The recommended upgrade method for an existing Crossplane install is to use
[Helm](http://helm.io). [Helm](http://helm.io).
<!-- vale write-good.Weasel = NO -->
{{<hint "important" >}}
Always upgrade Crossplane **one minor version at a time**, using the most recent
patch version available for each.
For example, if you are on `v1.18` and want to upgrade to `v2.0`, you should
first upgrade to `v1.19`, then `v1.20`, before finally upgrading to `v2.0`. The
upgrade path in this example looks like `v1.18` → `v1.19` → `v1.20` → `v2.0`.
{{</hint>}}
<!-- vale write-good.Weasel = YES -->
## Prerequisites ## Prerequisites
* [Helm](https://helm.sh/docs/intro/install/) version `v3.2.0` or later * [Helm](https://helm.sh/docs/intro/install/) version `v3.2.0` or later
## Add the Crossplane Helm repository ## Add the Crossplane Helm repository
Verify Helm has the Crossplane repository. Verify Helm has the Crossplane repository.
@ -27,35 +37,26 @@ helm repo update
``` ```
{{<hint "important" >}} {{<hint "important" >}}
Upgrading Crossplane without updating the Helm chart installs the last version Upgrading Crossplane without updating the Helm chart installs the last version
available in the locally cached Helm chart. available in the locally cached Helm chart.
{{< /hint >}} {{</hint>}}
## Upgrade Crossplane ## Upgrade Crossplane
Upgrade Crossplane with `helm upgrade`, providing the Crossplane namespace. Upgrade Crossplane with `helm upgrade`, providing the Crossplane namespace.
By default, Crossplane installs into the `crossplane-system` By default, Crossplane installs into the `crossplane-system`
namespace. namespace.
```shell ```shell
helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane
``` ```
Helm preserves any arguments or flags originally used when installing Helm preserves any arguments or flags originally used when installing
Crossplane. Crossplane.
Crossplane uses any new default behaviors unless they're changed in the `helm Crossplane uses any new default behaviors unless they're changed in the `helm
upgrade` command. upgrade` command.
For example, in v1.20.0 Crossplane changed the default image registry from Override new defaults by
`index.docker.io` to `xpkg.crossplane.io`. Upgrading Crossplane from a version [customizing the Helm chart]({{<ref "../get-started/install#customize-the-crossplane-helm-chart" >}})
before v1.20.0 updates the default package registry.
Override new defaults by
[customizing the Helm chart]({{<ref "../get-started/install#customize-the-crossplane-helm-chart" >}})
with the upgrade command. with the upgrade command.
For example, to maintain the original image registry use
```shell
helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane --set 'args={"--registry=index.docker.io"}'
```

59
content/v2.0/guides/upgrade-to-crossplane-v2.md
View File

@ -4,12 +4,12 @@ weight: 410
description: "Upgrade from Crossplane v1 to v2" description: "Upgrade from Crossplane v1 to v2"
--- ---
Crossplane v2 introduces significant improvements while maintaining backward Crossplane v2 introduces significant improvements while maintaining backward
compatibility with most v1 configurations. This guide helps you upgrade from compatibility with most v1 configurations. This guide helps you upgrade from
Crossplane v1.x to v2. Crossplane v1.x to v2.
Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including
namespaced resources, the ability to compose any Kubernetes resource, and new namespaced resources, the ability to compose any Kubernetes resource, and new
operational workflows. operational workflows.
{{<hint "important">}} {{<hint "important">}}
@ -18,11 +18,11 @@ If you're running an earlier version, upgrade to v1.20 first.
{{</hint>}} {{</hint>}}
{{<hint "note">}} {{<hint "note">}}
There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and
MRs to v2 namespaced style. You can upgrade to Crossplane v2 and MRs to v2 namespaced style. You can upgrade to Crossplane v2 and
start using the new namespaced features right away - your existing v1 start using the new namespaced features right away - your existing v1
resources continue working unchanged. See resources continue working unchanged. See
[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) [crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726)
for migration tooling progress. for migration tooling progress.
{{</hint>}} {{</hint>}}
@ -45,7 +45,7 @@ Crossplane v2 removes these deprecated features:
* [Default registry flag](#default-registry-flag) * [Default registry flag](#default-registry-flag)
### Native patch and transform composition ### Native patch and transform composition
**Deprecated in**: v1.17 **Deprecated in**: v1.17
**Replaced by**: [Composition functions]({{<ref "../composition/compositions">}}) **Replaced by**: [Composition functions]({{<ref "../composition/compositions">}})
If you're using `spec.mode: Resources` in your Compositions, migrate to If you're using `spec.mode: Resources` in your Compositions, migrate to
@ -55,14 +55,14 @@ composition functions before upgrading.
Compositions: Compositions:
```shell ```shell
# Convert patch and transform to function pipelines # Convert patch and transform to function pipelines
crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml
``` ```
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
### ControllerConfig type ### ControllerConfig type
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
**Deprecated in**: v1.11 **Deprecated in**: v1.11
**Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}}) **Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}})
Update any ControllerConfig resources to use DeploymentRuntimeConfig instead. Update any ControllerConfig resources to use DeploymentRuntimeConfig instead.
@ -78,13 +78,13 @@ crossplane beta convert deployment-runtime controller-config.yaml -o deployment-
### External secret stores ### External secret stores
**Status**: alpha feature, unmaintained **Status**: alpha feature, unmaintained
If you're using external secret stores, migrate to native Kubernetes secrets If you're using external secret stores, migrate to native Kubernetes secrets
or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading. or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading.
### Default registry flag ### Default registry flag
**Removed**: `--registry` flag for default package registry **Removed**: `--registry` flag for default package registry
All packages must now use fully qualified names including the registry All packages must now use fully qualified names including the registry
host name. Check your packages with: host name. Check your packages with:
```shell ```shell
@ -92,7 +92,7 @@ kubectl get pkg -o wide
``` ```
Update any packages without registry host names before upgrading. For example: Update any packages without registry host names before upgrading. For example:
- ❌ `crossplane-contrib/provider-aws-s3:v1.23.0` - ❌ `crossplane-contrib/provider-aws-s3:v1.23.0`
- ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0` - ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0`
## Who can upgrade ## Who can upgrade
@ -112,7 +112,7 @@ If you're using any removed features, migrate away from them first.
The recommended upgrade approach: The recommended upgrade approach:
1. [Prepare for upgrade](#1-prepare-for-upgrade) 1. [Prepare for upgrade](#1-prepare-for-upgrade)
2. [Upgrade Crossplane core](#2-upgrade-crossplane-core) 2. [Upgrade Crossplane core](#2-upgrade-crossplane-core)
3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies) 3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies)
4. [Upgrade providers](#4-upgrade-providers) 4. [Upgrade providers](#4-upgrade-providers)
5. [Start using v2 features](#5-start-using-v2-features) 5. [Start using v2 features](#5-start-using-v2-features)
@ -148,7 +148,7 @@ kubectl get pods -n crossplane-system
### 3. Configure managed resource activation policies ### 3. Configure managed resource activation policies
Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed
resources (`*`). Before installing v2 providers, you can optionally customize resources (`*`). Before installing v2 providers, you can optionally customize
this for better cluster resource efficiency. this for better cluster resource efficiency.
@ -159,7 +159,7 @@ Check what managed resources you use:
kubectl get managed kubectl get managed
``` ```
Optionally, replace the default MRAP with a targeted one that activates only Optionally, replace the default MRAP with a targeted one that activates only
the resources you need: the resources you need:
```shell ```shell
@ -179,21 +179,21 @@ spec:
# Legacy cluster-scoped resources (existing v1 resources) # Legacy cluster-scoped resources (existing v1 resources)
- buckets.s3.aws.upbound.io - buckets.s3.aws.upbound.io
- instances.ec2.aws.upbound.io - instances.ec2.aws.upbound.io
# Modern namespaced resources (new v2 resources) # Modern namespaced resources (new v2 resources)
- buckets.s3.aws.m.upbound.io - buckets.s3.aws.m.upbound.io
- instances.ec2.aws.m.upbound.io - instances.ec2.aws.m.upbound.io
``` ```
{{<hint "tip">}} {{<hint "tip">}}
Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs
`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern `s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern
namespaced managed resources. namespaced managed resources.
{{</hint>}} {{</hint>}}
### 4. Upgrade providers ### 4. Upgrade providers
Upgrade your providers to versions that support both namespaced and Upgrade your providers to versions that support both namespaced and
cluster-scoped managed resources: cluster-scoped managed resources:
```shell ```shell
@ -232,6 +232,15 @@ Existing Compositions work with Crossplane v2 with minimal changes. v2 managed
resources are schematically identical to v1 managed resources - they're just resources are schematically identical to v1 managed resources - they're just
namespaced. namespaced.
{{<hint "important">}}
**Don't update existing compositions that are actively used by composite
resources in your control plane.**
Updating a live composition that's in use by existing XRs could disrupt or
replace your resources. Use the below migration approach only when creating new
compositions for new resources.
{{</hint>}}
To use v2 namespaced managed resources in compositions: To use v2 namespaced managed resources in compositions:
1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io` 1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io`
@ -337,7 +346,7 @@ Your existing v1 resources continue working in Crossplane v2:
* **Legacy cluster-scoped MRs**: Continue working unchanged * **Legacy cluster-scoped MRs**: Continue working unchanged
* **Existing Compositions**: Continue working with legacy XRs * **Existing Compositions**: Continue working with legacy XRs
These resources use `LegacyCluster` scope internally and maintain full These resources use `LegacyCluster` scope internally and maintain full
backward compatibility. backward compatibility.
For example, existing v1-style XRDs continue working with claims: For example, existing v1-style XRDs continue working with claims:
@ -383,5 +392,5 @@ After upgrading:
3. **Try Operations**: Experiment with operational workflows 3. **Try Operations**: Experiment with operational workflows
4. **Plan migration**: Consider which existing resources to migrate to v2 patterns 4. **Plan migration**: Consider which existing resources to migrate to v2 patterns
Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the
updated [composition documentation]({{<ref "../composition/compositions">}}). updated [composition documentation]({{<ref "../composition/compositions">}}).

22
content/v2.0/managed-resources/managed-resource-activation-policies.md
View File

@ -83,6 +83,13 @@ spec:
- clusters.eks.aws.m.crossplane.io - clusters.eks.aws.m.crossplane.io
``` ```
{{<hint "important">}}
Use the **plural** name when using a complete MRD name, aligning with how
Kubernetes expresses the complete names of CRDs.
For example, use `buckets`, as opposed to `bucket`, in `buckets.s3.aws.m.crossplane.io`.
{{</hint>}}
### Wildcard patterns ### Wildcard patterns
Use `*` wildcards to match multiple resources: Use `*` wildcards to match multiple resources:
@ -91,7 +98,7 @@ Use `*` wildcards to match multiple resources:
spec: spec:
activate: activate:
- "*.s3.aws.m.crossplane.io" # All S3 resources - "*.s3.aws.m.crossplane.io" # All S3 resources
- "*.ec2.aws.m.crossplane.io" # All EC2 resources - "*.ec2.aws.m.crossplane.io" # All EC2 resources
- "*.rds.aws.m.crossplane.io" # All RDS databases - "*.rds.aws.m.crossplane.io" # All RDS databases
``` ```
@ -255,7 +262,7 @@ spec:
- "*.s3.aws.m.crossplane.io" - "*.s3.aws.m.crossplane.io"
- "*.storage.gcp.m.crossplane.io" - "*.storage.gcp.m.crossplane.io"
--- ---
# Database team MRAP # Database team MRAP
apiVersion: apiextensions.crossplane.io/v1alpha1 apiVersion: apiextensions.crossplane.io/v1alpha1
kind: ManagedResourceActivationPolicy kind: ManagedResourceActivationPolicy
metadata: metadata:
@ -332,7 +339,7 @@ status:
reason: Running reason: Running
activated: activated:
- buckets.s3.aws.m.crossplane.io - buckets.s3.aws.m.crossplane.io
- instances.ec2.aws.m.crossplane.io - instances.ec2.aws.m.crossplane.io
- instances.rds.aws.m.crossplane.io - instances.rds.aws.m.crossplane.io
- securitygroups.ec2.aws.m.crossplane.io - securitygroups.ec2.aws.m.crossplane.io
- subnets.ec2.aws.m.crossplane.io - subnets.ec2.aws.m.crossplane.io
@ -373,7 +380,7 @@ status:
```shell ```shell
# List available MRDs # List available MRDs
kubectl get mrds kubectl get mrds
# Check your pattern matches # Check your pattern matches
kubectl get mrds -o name | grep "your-pattern" kubectl get mrds -o name | grep "your-pattern"
``` ```
@ -405,7 +412,7 @@ status:
```yaml ```yaml
conditions: conditions:
- type: Healthy - type: Healthy
status: "Unknown" status: "Unknown"
reason: EncounteredErrors reason: EncounteredErrors
message: "failed to activate 2 of 5 ManagedResourceDefinitions" message: "failed to activate 2 of 5 ManagedResourceDefinitions"
``` ```
@ -443,8 +450,9 @@ conflicts. This enables team-based activation strategies and Configuration
package dependencies. package dependencies.
<!-- vale alex.ProfanityUnlikely = NO --> <!-- vale alex.ProfanityUnlikely = NO -->
1. **Start specific, broaden as needed** - Begin with exact resource names, 1. **Start specific, broaden as needed** - Begin with exact resource names
add wildcards only when beneficial for maintainability (using the plural name for each resource), add wildcards only when beneficial for
maintainability
2. **Plan for provider evolution** - Design wildcard patterns that 2. **Plan for provider evolution** - Design wildcard patterns that
accommodate new resources as providers add them (for example, accommodate new resources as providers add them (for example,
`*.s3.aws.m.crossplane.io` works for future S3 resources) `*.s3.aws.m.crossplane.io` works for future S3 resources)

16
content/v2.0/packages/image-configs.md
View File

@ -25,20 +25,6 @@ arbitrarily. Please note that this situation occurs only if there are
overlapping prefixes in the `matchImages` lists of different `ImageConfig` overlapping prefixes in the `matchImages` lists of different `ImageConfig`
resources, which should be avoided. resources, which should be avoided.
The default registry isn't taken into account for `ImageConfig` matching. That
is, an `ImageConfig` matching the prefix `xpkg.crossplane.io/crossplane-contrib`
doesn't match the following provider, even if the default registry is
`xpkg.crossplane.io`:
```yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-nop
spec:
package: crossplane-contrib/provider-nop:v0.4.0
```
## Configuring a pull secret ## Configuring a pull secret
You can use `ImageConfig` to inject a pull secret into the Crossplane package You can use `ImageConfig` to inject a pull secret into the Crossplane package
@ -90,7 +76,7 @@ rejects the package deployment.
In the following example, the `ImageConfig` resource named `verify-acme-packages` In the following example, the `ImageConfig` resource named `verify-acme-packages`
configures verification of the signature of images with the prefixes configures verification of the signature of images with the prefixes
`registry1.com/acme-co/configuration-foo` and `registry1.com/acme-co/configuration-foo` and
`registry1.com/acme-co/configuration-bar`. `registry1.com/acme-co/configuration-bar`.
In the example below, the `ImageConfig` resource named `verify-acme-packages` is In the example below, the `ImageConfig` resource named `verify-acme-packages` is
set up to verify the signatures of images with the prefixes set up to verify the signatures of images with the prefixes

9
themes/geekboot/layouts/partials/feature-state-alert.html
View File

@ -26,11 +26,12 @@
<p> <p>
This feature was introduced in v{{.Page.Params.alphaVersion}}. This feature was introduced in v{{.Page.Params.alphaVersion}}.
{{ if eq .Page.Params.state "beta" }} {{ if eq .Page.Params.state "beta" }}
<br /> <br />
This feature graduated to beta status in v{{.Page.Params.betaVersion}}. This feature graduated to beta status in v{{.Page.Params.betaVersion}}.
{{ end }} {{ end }}
{{ $ver := (printf "v%s" .Page.Params.version) }} {{ $verParam := .Page.Params.version | default .Site.Params.latest }}
{{ if eq .Page.Params.version "master" }} {{ $ver := (printf "v%s" $verParam) }}
{{ if eq $verParam "master" }}
{{ $ver = "master" }} {{ $ver = "master" }}
{{ end }} {{ end }}
<br /><br /> <br /><br />

21
themes/geekboot/layouts/partials/version-dropdown-menu.html
View File

@ -6,15 +6,18 @@
<!-- get all the versions and break out semver order --> <!-- get all the versions and break out semver order -->
{{ range .Site.Sections }} {{ range .Site.Sections }}
{{ if eq .Page.Params.version "master" }} {{/* Skip versions marked as hidden */}}
{{$sorted_list = $sorted_list | append "master" }} {{ if not .Page.Params.hidden }}
{{ else if ne .Page.Params.version nil }} {{ if eq .Page.Params.version "master" }}
{{ $splitver := split .Page.Params.version "." }} {{$sorted_list = $sorted_list | append "master" }}
{{ if eq (len $splitver) 2 }} {{ else if ne .Page.Params.version nil }}
{{ $verlist := (index $majordict (index $splitver 0)) }} {{ $splitver := split .Page.Params.version "." }}
{{ $verlist = $verlist | append (index $splitver 1) }} {{ if eq (len $splitver) 2 }}
{{ $majordict = merge $majordict (dict (index $splitver 0) $verlist) }} {{ $verlist := (index $majordict (index $splitver 0)) }}
{{ $majorlist = $majorlist | append (index $splitver 0) }} {{ $verlist = $verlist | append (index $splitver 1) }}
{{ $majordict = merge $majordict (dict (index $splitver 0) $verlist) }}
{{ $majorlist = $majorlist | append (index $splitver 0) }}
{{ end }}
{{ end }} {{ end }}
{{ end }} {{ end }}
{{ end }} {{ end }}