From 9308c5e5d758ea4901432aeea0bd6c83329a5252 Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Thu, 28 Aug 2025 09:35:39 -0600 Subject: [PATCH 1/2] Restore v1.20 ImageConfig docs that were lost in v2.0 The rewrite feature of `ImageConfig` was merged around the time v2 work started, and as a result the docs for it were lost in v2. Re-introduce the missing docs from 1.20. Signed-off-by: Adam Wolfe Gordon --- content/v2.0/packages/image-configs.md | 193 ++++++++++++++++++++----- 1 file changed, 155 insertions(+), 38 deletions(-) diff --git a/content/v2.0/packages/image-configs.md b/content/v2.0/packages/image-configs.md index 6ed9bc7a..43d025d1 100644 --- a/content/v2.0/packages/image-configs.md +++ b/content/v2.0/packages/image-configs.md @@ -10,6 +10,35 @@ 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. + +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 @@ -46,43 +75,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 {{}} @@ -211,4 +203,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 configure pull secrets or signature verification as well as rewriting, +additional `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. + + From 098895d3fa81f3071f98417a350cb9237a2edd31 Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Thu, 28 Aug 2025 11:08:46 -0600 Subject: [PATCH 2/2] Appease vale by using additional words in place of "additional" Signed-off-by: Adam Wolfe Gordon --- content/v2.0/packages/image-configs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v2.0/packages/image-configs.md b/content/v2.0/packages/image-configs.md index 43d025d1..de0f2af7 100644 --- a/content/v2.0/packages/image-configs.md +++ b/content/v2.0/packages/image-configs.md @@ -260,8 +260,8 @@ Status: {{}} Image rewriting is always done before other `ImageConfig` operations. If you -wish to configure pull secrets or signature verification as well as rewriting, -additional `ImageConfig` resources must match the rewritten image path. +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