Document the ImageConfig path rewriting feature in Crossplane 1.20

While we're here, move the common content on matching and debugging to their own
top-level headings, since they apply to all the different ImageConfig features.

Signed-off-by: Adam Wolfe Gordon <[email protected]>

Author: adamwg

content/v1.20/concepts/image-configs.md

@@ -10,6 +10,35 @@ description: "Image Configs is an API for centralized control of the configurati
 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.
+
+The default registry is not taken into account for `ImageConfig` matching. That
+is, an `ImageConfig` matching the prefix `xpkg.crossplane.io/crossplane-contrib`
+will not be applied to the following provider, even when 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
@@ -46,43 +75,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 +203,128 @@ If you can't see this condition on the package revision resource, namely
 `ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that
 the feature is enabled.
 
-<!-- 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.
+
+Currently, only prefix replacement is supported. The prefix specified in
+`spec.rewriteImage.prefix` replaces the matched prefix from `matchImages`. For
+example, the following `ImageConfig` will replace `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 particularly useful when mirroring
+packages to a private registry, since 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 will still pull the dependency from
+`xpkg.crossplane.io`. With the `ImageConfig` shown above, the dependency will be
+pulled from `registry1.com`.
+
+Rewriting an image path with `ImageConfig` does not change the `spec.package`
+field of the package resource. The rewritten path is recorded in the
+`status.resolvedPackage` field. The example above 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 image configs
+
+Image rewriting is always done before other `ImageConfig` operations. If you
+wish to configure pull secrets or signature verification for images being
+rewritten by an `ImageConfig`, the other configs must match the rewritten image
+path.
+
+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 indicate the purpose for
+which each `ImageConfig` was selected.
+
+For example, the following event and status indicate 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 -->