diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index f35eab9..417aee3 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -18,7 +18,7 @@ jobs: - name: Setup Node uses: actions/setup-node@v2 with: - node-version: '16' + node-version: '20' - name: Cache dependencies uses: actions/cache@v4 diff --git a/content/en/docs/advanced_features/global-prefix-override.md b/content/en/docs/advanced_features/global-prefix-override.md index 1bf193b..e4cb69b 100644 --- a/content/en/docs/advanced_features/global-prefix-override.md +++ b/content/en/docs/advanced_features/global-prefix-override.md @@ -3,23 +3,42 @@ title: Global Image Prefix Override weight: 2001 --- -The Global Image Prefix Override feature allows using mirrored package and workload images from a private registry without needing to rebuild the images with new image references. +The Global Image Prefix Override feature allows using mirrored package and +workload images from a private registry without needing to rebuild the images +with new image references. -This feature solves the problem of mirroring upstream images while preserving their original deployment manifests, all without relying on the Package Operator's internal image digest feature. +This feature solves the problem of mirroring package images that reference +other images with the [image-digest feature](/docs/guides/image-digests/) +without having to rebuild the images. -For example, this enables deployment of upstream package-operator artifacts from private registries without rebuilding them in downstream pipelines. This solves the previously impossible scenario where organizations needed to mirror upstream images, because PKO's internal image digest feature insist on referencing images by their original address. +For example, this enables deployment of upstream package-operator artifacts +from private registries without rebuilding them in downstream pipelines. +This solves the previously impossible scenario where organizations needed +to mirror upstream images, because PKO's internal image digest feature insist +on referencing images by their original address. ## Implementation -Prefix overrides can be configured through either of these options supplied to the `package-operator-manager` binary: +Prefix overrides can be configured through either of these options supplied +to the `package-operator-manager` binary: + - Environment variable: `PKO_IMAGE_PREFIX_OVERRIDES` - Command-line flag: `image-prefix-overrides` -Both accept mappings in `from=to` format (e.g., `quay.io/my-org/=mirror.example.com/mirror-org/`). A comma separataed list in the same format can also be provided for multiple overrides. When Package Operator encounters an image reference starting with the `from` prefix, it automatically substitutes it with the `to` prefix while preserving the remainder of the image path. +Both accept mappings in `from=to` format +(e.g., `quay.io/my-org/=mirror.example.com/mirror-org/`). +A comma separataed list in the same format can also be provided +for multiple overrides. When Package Operator encounters an image reference +starting with the `from` prefix, it automatically substitutes it with the +`to` prefix while preserving the remainder of the image path. ## Usage Example -The following `mirror.sh` script demonstrates the mirroring of the images and the modification of the bootstrap job manifests. (Images for version v1.82.2 are mirrored from the registry namespace `quay.io/package-operator` into the registry namespace `quay.io/erdii-test/pko-mirror`). +The following `mirror.sh` script demonstrates the mirroring of the images +and the modification of the bootstrap job manifests. +(Images for version v1.82.2 are mirrored from the registry namespace +`quay.io/package-operator` into the registry namespace +`quay.io/erdii-test/pko-mirror`). ```bash #!/bin/bash @@ -57,38 +76,56 @@ yq -i 'with( .image |= sub("quay.io/package-operator", "quay.io/erdii-test/pko-mirror"), .args[0] |= sub("quay.io/package-operator", "quay.io/erdii-test/pko-mirror") ) - )' self-bootstrap-job.yaml + )' self-bootstrap-job.yaml ``` ## Key Components Explained -### Image Mirroring: -The `skopeo copy` commands create identical copies of all upstream PKO package images in your private registry, maintaining the original tags and manifests. +### Image Mirroring + +The `skopeo copy` commands create identical copies of all upstream +PKO package images in your private registry, +maintaining the original tags and manifests. -### Prefix Override Injection: -The first `yq` command modifies the PKO_IMAGE_PREFIX_OVERRIDES environment variable to redirect all PKO package image pulls from quay.io/package-operator/ to quay.io/erdii-test/pko-mirror/ -while additionally rewriting the prefixes of the templated image address outputs of the [image digest feature](https://github.com/package-operator/website/blob/904d2c0a90d53e01ed59b602181d47b314925b8b/content/en/docs/guides/image-digests.md). Example template directive: {{.images.someNamedImage}} +### Prefix Override Injection -The pattern `original-prefix/=new-prefix/` ensures complete prefix substitution while preserving image names and tags +The first `yq` command modifies the PKO_IMAGE_PREFIX_OVERRIDES environment +variable to redirect all PKO package image pulls from quay.io/package-operator/ +to quay.io/erdii-test/pko-mirror/ while additionally rewriting the prefixes +of the templated image address outputs of the +[image digest feature](https://github.com/package-operator/website/blob/904d2c0a90d53e01ed59b602181d47b314925b8b/content/en/docs/guides/image-digests.md). +Example template directive: {{.images.someNamedImage}} -### Direct Reference Updates: -The second `yq` command handles hardcoded image references that bypass the prefix override mechanism by: +The pattern `original-prefix/=new-prefix/` ensures complete prefix substitution +while preserving image names and tags. + +### Direct Reference Updates + +The second `yq` command handles hardcoded image references that +bypass the prefix override mechanism by: Modifying the container's `.image` field Updating the first command-line argument in .args[0] -To ensure that all artifacts required for PKO's bootstrap procedure are pulled correctly , it is required to reference the bootstrap job workload image directly from the mirrored location. +To ensure that all artifacts required for PKO's bootstrap procedure are +pulled correctly, it is required to reference the bootstrap job workload image +directly from the mirrored location. The package image location also gets replaced for readability reasons. - -# Deployment Process -## 1. Apply the prepared manifest on the target cluster: -```kubectl apply -f self-bootstrap-job.yaml``` +## Deployment Process + +### 1. Apply the prepared manifest on the target cluster -## 2. Monitor progress until the ClusterPackage CRD becomes available -## 3. Verification: +```bash +kubectl apply -f self-bootstrap-job.yaml ``` + +### 2. Monitor progress until the ClusterPackage CRD becomes available + +### 3. Verification + +```bash # Verify package image source kubectl get clusterpackage package-operator -o yaml | yq .spec.image