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

replace missing content from v2 

For this commit, we looked at all guides/content from v1.20 and
copied over any content that is still relevant for v2.0 but was
not included in the huge refactor of the v2 docs.

* change logs guide
* Argo CD guide
* import existing resources guide
* self-signed certificates guide
* image configs (missing details in master)

Signed-off-by: Jared Watts <jbw976@gmail.com>
This commit is contained in:
Jared Watts 2025-09-02 18:14:18 -07:00
parent 3555176893
commit 452c634363
No known key found for this signature in database
GPG Key ID: 0467EEAE3B6EC0D2
10 changed files with 1163 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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"
```

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

@ -1,12 +1,8 @@
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
---
title: Configuring Crossplane with Argo CD
weight: 270
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)
are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes

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.

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

@ -1,15 +1,13 @@
<!-- 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
{{<hint "important">}}
Using self-signed certificates isn't advised in production, it's
recommended to only use self-signed certificates for testing.
{{</hint>}}
When Crossplane loads Configuration and Provider Packages from private
registries, you must configure it to trust the CA and Intermediate certs.
@ -20,7 +18,7 @@ defined. See [Install Crossplane]({{<ref "../get-started/install" >}}).
## Configure
1. Create a CA Bundle (A file containing your Root and Intermediate
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
@ -35,7 +33,7 @@ that signed that cert.
3. Create a Kubernetes ConfigMap in your Crossplane system namespace:
```
```shell
kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
--from-file=ca-bundle=./[yourdomain].ca-bundle
```
@ -44,11 +42,13 @@ kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
`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
{{<hint "note">}}
The Helm docs cover providing Helm with parameter values during
[`helm install`](https://helm.sh/docs/helm/helm_install/). An example block
in an `override.yaml` file would look like this:
```
```yaml
registryCaBundleConfig:
name: ca-bundle-config
key: ca-bundle
```
{{</hint>}}

177
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
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
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>
```
### 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
{{<hint "important" >}}
@ -211,4 +189,129 @@ If you can't see this condition on the package revision resource, namely
`ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that
you enable the feature.
## 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 -->

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"
```

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

@ -1,12 +1,8 @@
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
---
title: Configuring Crossplane with Argo CD
weight: 270
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)
are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes

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.

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

@ -1,15 +1,13 @@
<!-- 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
{{<hint "important">}}
Using self-signed certificates isn't advised in production, it's
recommended to only use self-signed certificates for testing.
{{</hint>}}
When Crossplane loads Configuration and Provider Packages from private
registries, you must configure it to trust the CA and Intermediate certs.
@ -20,7 +18,7 @@ defined. See [Install Crossplane]({{<ref "../get-started/install" >}}).
## Configure
1. Create a CA Bundle (A file containing your Root and Intermediate
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
@ -35,7 +33,7 @@ that signed that cert.
3. Create a Kubernetes ConfigMap in your Crossplane system namespace:
```
```shell
kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
--from-file=ca-bundle=./[yourdomain].ca-bundle
```
@ -44,11 +42,13 @@ kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
`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
{{<hint "note">}}
The Helm docs cover providing Helm with parameter values during
[`helm install`](https://helm.sh/docs/helm/helm_install/). An example block
in an `override.yaml` file would look like this:
```
```yaml
registryCaBundleConfig:
name: ca-bundle-config
key: ca-bundle
```
{{</hint>}}

14
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`
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
You can use `ImageConfig` to inject a pull secret into the Crossplane package