diff --git a/content/master/guides/change-logs.md b/content/master/guides/change-logs.md
new file mode 100644
index 00000000..c19bcd72
--- /dev/null
+++ b/content/master/guides/change-logs.md
@@ -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.
+
+{{}} 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.
+{{}}
+
+## Enabling change logs
+
+{{}} Change logs are an alpha feature and must be explicitly
+enabled for each provider through the use of a `DeploymentRuntimeConfig`.
+{{}}
+
+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]({{[}}).
+
+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.
+
+{{}} Not all providers support the change logs feature. Check with
+your provider of choice to confirm it has added support for change logs.
+{{}}
+
+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 {{}}--enable-changelogs{{}} flag on the provider.
+1. Add the {{}}sidecar container{{}} to the provider pod.
+1. Declare a {{}}shared volume{{}} and mount it in the {{}}provider
+ container{{}} and the {{}}sidecar
+ container{{}}.
+
+```yaml {label="drc",copy-lines="all"}
+cat <}}provider{{}} and
+instruct it to use the {{}}DeploymentRuntimeConfig{{}}
+that was just created.
+
+```yaml {label="provider",copy-lines="all"}
+cat <}} 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).
+{{}}
+
+```yaml {label="rbac",copy-lines="all"}
+cat <
-
----
+---
title: Configuring Crossplane with Argo CD
weight: 270
description: "Deploy Crossplane resources with GitOps"
---
-
-
[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
-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.
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 synchronizes Kubernetes resource manifests stored in a Git repository
-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
+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
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.
-
+
### Configuring Argo CD with Crossplane
diff --git a/content/master/guides/import-existing-resources.md b/content/master/guides/import-existing-resources.md
new file mode 100644
index 00000000..d19b3e1c
--- /dev/null
+++ b/content/master/guides/import-existing-resources.md
@@ -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`]({{][}})
+field enables importing external resources into Crossplane.
+
+## Import resources in observe only mode
+
+Start by importing external resources with an `Observe` [management policy]({{][}}).
+
+Crossplane imports observe only resources but never changes or deletes the
+resources.
+
+{{}}
+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 >}}
+
+
+### Apply the Observe management policy
+
+
+Create a new managed resource matching the
+{{}}apiVersion{{}} and
+{{}}kind{{}} of the resource
+to import and add
+{{}}managementPolicies: ["Observe"]{{}} to the
+{{}}spec{{}}
+
+For example, to import a GCP SQL DatabaseInstance, create a new resource with
+the {{}}managementPolicies: ["Observe"]{{}}
+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 {{}}crossplane.io/external-name{{}}
+annotation for the resource. This name must match the name inside the Provider.
+
+For example, for a GCP database named
+{{}}my-external-database{{}}, apply
+the
+{{}}crossplane.io/external-name{{}}
+annotation with the value
+{{}}my-external-database{{}}.
+
+```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 {{}}name{{}} to use for the
+Kubernetes object.
+
+For example, name the Kubernetes object
+{{}}my-imported-database{{}}.
+
+```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
+{{}}spec.forProvider{{}} field.
+
+For example, only import the GCP SQL database in the
+{{}}us-central1{{}} 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
+{{}}status.atProvider{{}}
+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
+```
+
+## Control imported observe only resources
+
+
+Crossplane can take active control of observe only imported resources by
+changing the `managementPolicies` after import.
+
+Change the {{}}managementPolicies{{}} field
+of the managed resource to
+{{}}["*"]{{}}.
+
+Copy any required parameter values from
+{{}}status.atProvider{{}} and provide them
+in {{}}spec.forProvider{{}}.
+
+{{< 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.
diff --git a/content/master/guides/self-signed-ca-certs.md b/content/master/guides/self-signed-ca-certs.md
index c79de817..d8386a57 100644
--- a/content/master/guides/self-signed-ca-certs.md
+++ b/content/master/guides/self-signed-ca-certs.md
@@ -1,54 +1,54 @@
-
-
----
+---
title: Self-signed CA certs
weight: 270
description: "Configure Crossplane with self-signed certificates"
---
-
-
-> Using self-signed certificates isn't advised in production, it's
+{{}}
+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.
+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
+You need to install Crossplane via the Helm chart with the
+`registryCaBundleConfig.name` and `registryCaBundleConfig.key` parameters
defined. See [Install Crossplane]({{][}}).
## 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
+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:
-```
+```shell
kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
---from-file=ca-bundle=./[yourdomain].ca-bundle
+ --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
+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
+{{}}
+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
```
+{{}}
\ No newline at end of file
diff --git a/content/master/packages/image-configs.md b/content/master/packages/image-configs.md
index 6ed9bc7a..701580a0 100644
--- a/content/master/packages/image-configs.md
+++ b/content/master/packages/image-configs.md
@@ -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= --docker-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
{{}}
@@ -98,7 +76,7 @@ rejects the package deployment.
In the following example, the `ImageConfig` resource named `verify-acme-packages`
configures verification of the signature of images with the prefixes
`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
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
you enable the feature.
-
\ No newline at end of file
+## 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
+
+{{}}
+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.
+
+
diff --git a/content/v2.0/guides/change-logs.md b/content/v2.0/guides/change-logs.md
new file mode 100644
index 00000000..c19bcd72
--- /dev/null
+++ b/content/v2.0/guides/change-logs.md
@@ -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.
+
+{{}} 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.
+{{}}
+
+## Enabling change logs
+
+{{}} Change logs are an alpha feature and must be explicitly
+enabled for each provider through the use of a `DeploymentRuntimeConfig`.
+{{}}
+
+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]({{][}}).
+
+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.
+
+{{}} Not all providers support the change logs feature. Check with
+your provider of choice to confirm it has added support for change logs.
+{{}}
+
+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 {{}}--enable-changelogs{{}} flag on the provider.
+1. Add the {{}}sidecar container{{}} to the provider pod.
+1. Declare a {{}}shared volume{{}} and mount it in the {{}}provider
+ container{{}} and the {{}}sidecar
+ container{{}}.
+
+```yaml {label="drc",copy-lines="all"}
+cat <}}provider{{}} and
+instruct it to use the {{}}DeploymentRuntimeConfig{{}}
+that was just created.
+
+```yaml {label="provider",copy-lines="all"}
+cat <}} 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).
+{{]}}
+
+```yaml {label="rbac",copy-lines="all"}
+cat <
-
----
+---
title: Configuring Crossplane with Argo CD
weight: 270
description: "Deploy Crossplane resources with GitOps"
---
-
-
[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
-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.
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 synchronizes Kubernetes resource manifests stored in a Git repository
-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
+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
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.
-
+
### Configuring Argo CD with Crossplane
diff --git a/content/v2.0/guides/import-existing-resources.md b/content/v2.0/guides/import-existing-resources.md
new file mode 100644
index 00000000..d19b3e1c
--- /dev/null
+++ b/content/v2.0/guides/import-existing-resources.md
@@ -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`]({{[}})
+field enables importing external resources into Crossplane.
+
+## Import resources in observe only mode
+
+Start by importing external resources with an `Observe` [management policy]({{][}}).
+
+Crossplane imports observe only resources but never changes or deletes the
+resources.
+
+{{}}
+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 >}}
+
+
+### Apply the Observe management policy
+
+
+Create a new managed resource matching the
+{{}}apiVersion{{}} and
+{{}}kind{{}} of the resource
+to import and add
+{{}}managementPolicies: ["Observe"]{{}} to the
+{{}}spec{{}}
+
+For example, to import a GCP SQL DatabaseInstance, create a new resource with
+the {{}}managementPolicies: ["Observe"]{{}}
+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 {{}}crossplane.io/external-name{{}}
+annotation for the resource. This name must match the name inside the Provider.
+
+For example, for a GCP database named
+{{}}my-external-database{{}}, apply
+the
+{{}}crossplane.io/external-name{{}}
+annotation with the value
+{{}}my-external-database{{}}.
+
+```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 {{}}name{{}} to use for the
+Kubernetes object.
+
+For example, name the Kubernetes object
+{{}}my-imported-database{{}}.
+
+```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
+{{}}spec.forProvider{{}} field.
+
+For example, only import the GCP SQL database in the
+{{}}us-central1{{}} 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
+{{}}status.atProvider{{}}
+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
+```
+
+## Control imported observe only resources
+
+
+Crossplane can take active control of observe only imported resources by
+changing the `managementPolicies` after import.
+
+Change the {{}}managementPolicies{{}} field
+of the managed resource to
+{{}}["*"]{{}}.
+
+Copy any required parameter values from
+{{}}status.atProvider{{}} and provide them
+in {{}}spec.forProvider{{}}.
+
+{{< 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.
diff --git a/content/v2.0/guides/self-signed-ca-certs.md b/content/v2.0/guides/self-signed-ca-certs.md
index c79de817..d8386a57 100644
--- a/content/v2.0/guides/self-signed-ca-certs.md
+++ b/content/v2.0/guides/self-signed-ca-certs.md
@@ -1,54 +1,54 @@
-
-
----
+---
title: Self-signed CA certs
weight: 270
description: "Configure Crossplane with self-signed certificates"
---
-
-
-> Using self-signed certificates isn't advised in production, it's
+{{}}
+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.
+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
+You need to install Crossplane via the Helm chart with the
+`registryCaBundleConfig.name` and `registryCaBundleConfig.key` parameters
defined. See [Install Crossplane]({{][}}).
## 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
+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:
-```
+```shell
kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
---from-file=ca-bundle=./[yourdomain].ca-bundle
+ --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
+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
+{{}}
+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
```
+{{}}
\ No newline at end of file
diff --git a/content/v2.0/packages/image-configs.md b/content/v2.0/packages/image-configs.md
index de0f2af7..701580a0 100644
--- a/content/v2.0/packages/image-configs.md
+++ b/content/v2.0/packages/image-configs.md
@@ -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
@@ -90,7 +76,7 @@ rejects the package deployment.
In the following example, the `ImageConfig` resource named `verify-acme-packages`
configures verification of the signature of images with the prefixes
`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
set up to verify the signatures of images with the prefixes
]