Skip to content

fix: make pre-commit hooks pass for global image prefix overrides and rewrite small parts of the introduction #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erdii merged 2 commits into from
Sep 9, 2025
Merged

fix: make pre-commit hooks pass for global image prefix overrides and rewrite small parts of the introduction #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c6e33ae
fix: make pre-commit hooks pass for global image prefix overrides and…
erdii Sep 9, 2025
a015b2d
fix: bump node version in deploy workflow to make netlify-cli run again
erdii Sep 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
81 changes: 59 additions & 22 deletions content/en/docs/advanced_features/global-prefix-override.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down