This repo is dedicated to mirroring the OCI artifacts that K3s ships to the places K3s needs them to be. Currently that is the set of images in the K3s airgap image list that are not built by K3s itself: CoreDNS, Traefik, metrics-server, local-path-provisioner, busybox and pause.
regsync is used for mirroring OCI artifacts from one repository to another. regsync
is configured via regsync.yaml. regsync.yaml is generated by running the
generate-regsync subcommand of the Go code in tools/, using config.yaml as
input. You can build the latest version of this code to bin/image-mirror-tools
using scripts/build-tools.sh. Thus, your workflow might look like this:
scripts/build-tools.sh
bin/image-mirror-tools generate-regsync
Once regsync.yaml has been updated, you may run regsync via the command
regsync once --verbosity error --config regsync.yaml --missing
autoupdate.yaml is used to configure automatic updates for artifacts. When
an update is found, the automation creates a pull request that a human user
can then review and merge. See autoupdate.yaml for
more information.
When adding new OCI artifacts to the repo, please indicate so in the pull request.
Nothing needs to be created ahead of time: ghcr.io creates the package on the
first push. Note, however, that a newly created package is private by default -
after the first mirror run, set its visibility to public.
Mirroring only ever happens in CI. config.yaml deliberately carries no
credentials: the Mirror Artifacts
workflow logs into ghcr.io with docker/login-action, using
github.repository_owner and the workflow's GITHUB_TOKEN (which needs the
packages: write permission), and regsync picks that up from
~/.docker/config.json.
As a consequence, running regsync once locally can pull but cannot push
unless you have run docker login ghcr.io yourself. Everything else -
listing source tags for autoupdate, and the pulls that validate does -
works anonymously and needs no credentials at all.
Every artifact mirrored by this repository is prefixed with mirrored-, which
says that it was copied from somewhere else rather than built here. There are
no exceptions - this namespace has no history predating the convention.
regsync.yaml is mostly for use by regsync. It is generated from config.yaml,
and is not very easy to read. It should never be modified directly. It can,
however, be useful for checking that config.yaml changes will have the expected
effect on mirroring.
Repositories describes the repositories that image-mirror interfaces with.
This section roughly correlates to the creds section of regsync.yaml.
| Field | Required | Description |
|---|---|---|
BaseUrl |
yes | The base URL for the repository. Appending / plus an artifact name should be a valid artifact reference. |
Password |
no | The password to use when authenticating against the registry. Leave unset to let regsync use ~/.docker/config.json, which is how CI authenticates. See the regsync documentation for more details. |
Registry |
yes | The registry URL. See the regsync documentation for more details. |
ReqConcurrent |
no | The number of concurrent requests that are made to this registry. See the regsync documentation for more details. |
DefaultTarget |
no | Whether the Repository is used as a target repository for a given artifact when the TargetRepositories field of the Artifact is not set. |
Username |
no | The username to use when authenticating against the registry. Leave unset to let regsync use ~/.docker/config.json, which is how CI authenticates. See the regsync documentation for more details. |
Artifacts describes the artifacts that we want to mirror to each target
repository.
| Field | Required | Description |
|---|---|---|
DoNotMirror |
no | Set to true to exclude the entire Artifact from regsync.yaml. Alternatively, set to an array of strings to specify tags to exclude from regsync.yaml. |
SourceArtifact |
yes | The source artifact. If there is no host, the artifact is assumed to be from Docker Hub. |
Tags |
yes | The tags to mirror. |
TargetArtifactName |
no | By default, the target artifact name is derived from the source artifact, and is of the format mirrored-<org>-<name>. For example, coredns/coredns becomes mirrored-coredns-coredns. However, there are some artifacts that do not follow this convention - this field exists for these cases. New artifacts should not set this field. |
TargetRepositories |
no | Repositories to mirror the artifact to. Repositories are specified via their BaseUrl field. If not specified, the Artifact is mirrored to all Repositories that have DefaultTarget set to true. |
autoupdate.yaml defines configuration for automatically updating artifact tags
based on various update strategies that monitor sources for new tags. Each
entry specifies a strategy for finding tags of artifacts to potentially add to
config.yaml, which are then submitted as pull requests.
| Field | Required | Description |
|---|---|---|
Name |
yes | A unique identifier for this autoupdate entry. Used for logging and generating branch names for pull requests. |
GithubRelease |
no | See GithubRelease. |
HelmLatest |
no | See HelmLatest. |
Registry |
no | See Registry. |
Reviewers |
yes | A list of GitHub users or teams that own the autoupdate entry. Teams should be in the format org/team-slug. |
The GithubRelease strategy fetches all release tags that matches the VersionConstraint from a GitHub
repository and applies it to the specified artifacts.
If LatestOnly is true, it only fetches from the latest release and does not consider the VersionConstraint.
| Field | Required | Description |
|---|---|---|
Owner |
yes | The GitHub repository owner/organization. |
Repository |
yes | The GitHub repository name. |
Artifacts |
yes | See Artifacts. |
LatestOnly |
no | If true, get only the tag from the latest github release. |
VersionConstraint |
no | A SemVer constraint used to filter the github releases. |
VersionRegex |
no | If specified, only matching release tags will be considered. If a capture group is present, only its contents will be passed on. |
A list of artifacts to be updated with the latest release tag. Each artifact will get the same tag as the GitHub release.
| Field | Required | Description |
|---|---|---|
SourceArtifact |
yes | The GitHub repository name. |
TargetArtifactName |
no | The TargetArtifactName of the artifact in config.yaml that you want to update. |
The HelmLatest strategy templates out the latest version of configured
Helm charts and extracts artifact references from the rendered manifests. It
recursively searches for fields with an "image" key in the templated YAML
output.
| Field | Required | Description |
|---|---|---|
HelmRepo |
yes | The URL of the Helm chart repository. |
Charts |
yes | A map where keys are the charts to template, and values are another map from environment name to lists of helm values to --set in that environment. helm template is run once for each environment. |
Artifacts |
no | Used to map a given update artifact to an entry in config.yaml. There may be multiple entries that have the same SourceArtifact, but different TargetArtifactNames, so we need to choose which one receives the update artifact. |
ImageDenylist |
no | A list of images to exclude from the results. |
The Registry strategy fetches all artifact tags that matches the VersionFilter from a registry defined in the Artifacts provided.
Supported registries are:
- Suse Container Registry (registry.suse.com)
- Docker Hub
- Quay.io
- K8s registry (registry.k8s.io)
- GitHub Container Registry (ghcr.io)
- Google Container Registry (gcr.io)
| Field | Required | Description |
|---|---|---|
Artifacts |
yes | Used to map a given update artifact to an entry in config.yaml. There may be multiple entries that have the same SourceArtifact, but different TargetArtifactNames, so we need to choose which one receives the update artifact. |
Latest |
no | A flag to only use the latest tag. This only works if all tags are in semver format. |
VersionFilter |
no | A regex to match against the artifact tags fetched from the registry. |