Day 9: Mirrors and artifacts – regsync and oras
Goal: You mirror public images into your registry automatically and store arbitrary files – configuration, Helm chart, SBOM – next to them as OCI artifacts. · Duration: approx. 75 min · Prerequisite: Day 8
Briefing
- regsync mirrors according to a YAML file: source,
target, tag filter.
checkshows what would need doing,oncecopies once,serverruns permanently on a schedule. - A registry stores more than images. Every manifest with its own artifactType is an OCI artifact – a file, a chart, an SBOM.
- oras moves such artifacts back and forth and
attaches them to an image via
subject(referrer). Who attached what to my image? –oras discover.
docker.io/library/nginx ─┐ registry.ct.lab:5000
docker.io/library/postgres┴─regsync once──► mirror/nginx, mirror/postgres
regsync.yml, notes-0.1.0.tgz ──oras push──► lab/regsync-config, charts/notes
notes-api.spdx.json ──oras attach──► manifest with subject ──► notes-api@sha256:9a22…
+ tag sha256-9a22… (referrers fallback)
Drill 1: regsync – install and configure
| Profile | regsync |
|---|---|
| Task | Mirror images and repositories between registries according to a configuration |
| Special feature | Tag filters via regex, rate-limit protection, interval/cron in server mode |
| Project | github.com/regclient/regclient, regclient.org (Apache-2.0) |
| Version in this book | v0.11.7 |
regsync belongs to regclient, like regctl, and is also a single binary:
source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag09 && cd ~/ct-lab/tag09
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag08/notes/." .
regsync version --format '{{.VCSTag}}'; echo
regsync --help | sed -n '/Available Commands/,/^$/p'Expected (shortened; IDs and times will differ for you):
v0.11.7
Available Commands:
check processes each sync command once but skip actual copy
completion Generate the autocompletion script for the specified shell
config Show the config
help Help about any command
once processes each sync command once, ignoring cron schedule
server run the regsync server
version Show the version
The configuration: logins (creds), defaults
(defaults) and the list of mirror jobs (sync).
regsync pulls values such as the password from the environment via
templates; they are not in the file:
cat > regsync.yml <<'EOF'
# regsync.yml – Stand Ende Tag 9: Docker Hub in die eigene Registry spiegeln
version: 1
creds:
- registry: '{{ env "REG" }}'
user: '{{ env "REG_USER" }}'
pass: '{{ env "REG_PASS" }}'
defaults:
parallel: 1
interval: 6h
ratelimit:
min: 20
retry: 15m
sync:
- source: docker.io/library/nginx
target: '{{ env "REG" }}/mirror/nginx'
type: repository
tags:
allow:
- '1\.30\.6-alpine'
- 'stable-alpine'
- source: docker.io/library/postgres
target: '{{ env "REG" }}/mirror/postgres'
type: repository
platform: linux/arm64
tags:
allow:
- '18\.6-alpine'
EOF
regsync config -c regsync.yml | grep -E '^ *(user|pass|platform|min):'Expected:
user: lab
pass: lab-registry-pw-123
min: 20
platform: ""
min: 20
platform: linux/arm64
min: 20
type: repositorymirrors all tags that passtags.allow(regular expressions);denyexcludes.type: imagemirrors exactly one tag.platformcopies just one platform instead of the whole index – for postgres that saves a good 90% of the download.ratelimit.min: 20: if the Docker Hub quota drops below 20, regsync waits 15 minutes (retry) instead of getting you locked out.
Security:
regsync configshows the resolved templates – including the password in plain text. Don’t print it in CI logs.
Save your progress? Sign up for free
Drill 2: check and once
regsync check -c regsync.yml 2>&1 | grep -o 'msg=.*' | cut -c1-88Expected:
msg="Image sync needed" source=docker.io/library/nginx:1.30.6-alpine target=registry.c
msg="Image sync needed" source=docker.io/library/nginx:stable-alpine target=registry.c
msg="Image sync needed" source=docker.io/library/postgres:18.6-alpine@sha256:b1c1673a8
Three jobs, even though mirror/nginx:1.30.6-alpine has
existed since Day 8: there you only have the arm64 manifest, Docker Hub
has an index – different digests, so mirror again.
time regsync once -c regsync.yml 2>&1 | grep -c 'Copy layer'
regctl tag ls "$REG/mirror/nginx"; regctl tag ls "$REG/mirror/postgres"
regctl image digest "$REG/mirror/nginx:1.30.6-alpine"
regctl manifest get "$REG/mirror/postgres:18.6-alpine" --format raw-body \
| jq -r .mediaType
regctl image inspect "$REG/mirror/postgres:18.6-alpine" --format '{{.Architecture}}'
echoExpected:
9
real 0m12.578s
1.30.6-alpine
stable-alpine
18.6-alpine
sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
application/vnd.oci.image.manifest.v1+json
arm64
nginx was fast: all blobs were already in your registry (Day 7), regsync only had to link them. What got copied were the nine postgres layers. The digest is the original index – regsync always copies digest-preserving. A second run:
regsync once -c regsync.yml; echo "Exit: $?"
regsync once --missing -c regsync.yml; echo "Exit: $?"Expected:
Exit: 0
Exit: 0
No message, nothing to do. --missing doesn’t check
existing tags at all, it only copies missing ones – good for tags that
never change. Now the rate-limit protection: a copy of the configuration
demands at least 99 free pulls:
regctl tag rm "$REG/mirror/nginx:stable-alpine"
sed 's/min: 20/min: 99/' regsync.yml > /tmp/rs99.yml
timeout 20 regsync once -c /tmp/rs99.yml 2>&1 | grep -o 'msg=.*' | cut -c1-88
regsync once -c regsync.yml 2>&1 | grep -c 'sync needed'; rm /tmp/rs99.ymlExpected:
msg="Image sync needed" source=docker.io/library/nginx:stable-alpine target=registry.c
msg="Delaying for rate limit" source=docker.io/library/nginx:stable-alpine source-rema
msg="Failed to sync" target=registry.ct.lab:5000/mirror/nginx:stable-alpine source=doc
1
regsync waits 15 minutes, timeout aborts before that.
The normal run afterwards brings the tag back. Unshortened, the second
line reads
source-remain=44 source-limit=100 step-min=99 sleep=15m0s.
Save your progress? Sign up for free
Drill 3: Continuous operation – server or timer
regsync server runs permanently and checks each job
according to its interval (or schedule with
cron syntax):
timeout 15 regsync server -c regsync.yml; echo "Exit: $?"Expected:
time=2026-10-30T20:55:59.036Z level=INFO msg="Stopping server"
Exit: 124
As a service, a systemd timer with once is often
simpler: it runs, exits and leaves a journal behind. A sketch as user
units:
mkdir -p systemd ~/.config/systemd/user
cat > systemd/regsync.service <<'EOF'
# systemd/regsync.service – state at end of Day 9 (sketch)
[Unit]
Description=regsync: Docker Hub in die eigene Registry spiegeln
[Service]
Type=oneshot
EnvironmentFile=%h/ct-lab/tag09/regsync.env
ExecStart=/usr/local/bin/regsync once -c %h/ct-lab/tag09/regsync.yml
EOF
cat > systemd/regsync.timer <<'EOF'
# systemd/regsync.timer – state at end of Day 9 (sketch)
[Unit]
Description=regsync alle 6 Stunden
[Timer]
OnCalendar=00/6:00
RandomizedDelaySec=15m
Persistent=true
[Install]
WantedBy=timers.target
EOF
printf 'REG=%s\nREG_USER=%s\nREG_PASS=%s\n' "$REG" "$REG_USER" "$REG_PASS" \
> regsync.env && chmod 600 regsync.env
systemd-analyze verify --user systemd/regsync.service systemd/regsync.timer
systemd-analyze calendar '00/6:00' | grep 'Next elapse'
cp systemd/regsync.* ~/.config/systemd/user/ && systemctl --user daemon-reload
systemctl --user start regsync.service
journalctl --user -u regsync.service -n 2 --no-pager -o catExpected:
Next elapse: Sat 2026-10-31 00:00:00 UTC
Starting regsync.service - regsync: Docker Hub in die eigene Registry spiegeln...
Finished regsync.service - regsync: Docker Hub in die eigene Registry spiegeln.
systemd-analyze verify reports nothing – the units are
valid. systemctl --user enable --now regsync.timer would
arm the mirror; in the lab we stick with the sketch. Alternatively,
regsync runs as a container (ghcr.io/regclient/regsync) via
a Quadlet unit (Day 3) in server mode.
Save your progress? Sign up for free
Drill 4: oras – install and push a file
| Profile | oras |
|---|---|
| Task | Store, fetch, copy and attach arbitrary files as OCI artifacts |
| Special feature | Referrers (attach/discover) with fallback to the tag schema; OCI layout |
| Project | oras.land, github.com/oras-project/oras (Apache-2.0) |
| Version in this book | 1.3.6 |
arch=$(dpkg --print-architecture)
read -r _ _ url sum < <(grep "^oras $arch " "$LAB/setup/tools.lock")
curl -fsSLo /tmp/oras.tgz "$url"
echo "$sum /tmp/oras.tgz" | sha256sum -c -
sudo tar -C /usr/local/bin -xzf /tmp/oras.tgz oras && rm /tmp/oras.tgz
oras version | head -1
echo "$REG_PASS" | oras login -u "$REG_USER" --password-stdin "$REG"
oras repo ls "$REG" | head -3
oras repo tags "$REG/notes/notes-api"Expected:
/tmp/oras.tgz: OK
Version: 1.3.6
Login Succeeded
backup/notes-web
lab/notes-api
library/nginx
0.1.0
oras writes the login to ~/.docker/config.json – the
same file as crane. Now an arbitrary file as an artifact, here your
regsync configuration:
oras push "$REG/lab/regsync-config:tag09" \
--artifact-type application/vnd.ct-lab.config regsync.yml:application/yaml \
-a "org.opencontainers.image.description=regsync-Konfiguration Tag 9"
oras manifest fetch "$REG/lab/regsync-config:tag09" | jq '{artifactType,
config: .config.mediaType, layer: .layers[0] | {mediaType, annotations}}'Expected:
Preparing regsync.yml
Uploading 44136fa355b3 application/vnd.oci.empty.v1+json
Uploading 97c5debe9cc5 regsync.yml
Uploaded 44136fa355b3 application/vnd.oci.empty.v1+json
Uploaded 97c5debe9cc5 regsync.yml
Uploading 53ac840e6911 application/vnd.oci.image.manifest.v1+json
Uploaded 53ac840e6911 application/vnd.oci.image.manifest.v1+json
Pushed [registry] registry.ct.lab:5000/lab/regsync-config:tag09
ArtifactType: application/vnd.ct-lab.config
Digest: sha256:53ac840e69118a1401d013383fd1d3608ca67a435b0f4bc46ca31d0bb9f996ee
{
"artifactType": "application/vnd.ct-lab.config",
"config": "application/vnd.oci.empty.v1+json",
"layer": {
"mediaType": "application/yaml",
"annotations": {
"org.opencontainers.image.title": "regsync.yml"
}
}
}
An artifact is a normal OCI manifest: artifactType says
what it is, the config is empty ({}, 2 bytes), each file is
a layer with its own media type and the file name as title.
Fetch it back – and see what Podman thinks of it:
oras pull -o /tmp/zurueck "$REG/lab/regsync-config:tag09" >/dev/null
ls /tmp/zurueck && rm -rf /tmp/zurueck
podman pull "$REG/lab/regsync-config:tag09" 2>&1 | tail -1 | cut -c1-88Expected:
regsync.yml
Error: unable to copy from source docker://registry.ct.lab:5000/lab/regsync-config:tag
Podman refuses
(unsupported image-specific operation on artifact): this is
not an image. That is exactly what makes it safe to store artifacts side
by side.
Save your progress? Sign up for free
Drill 5: A Helm chart as an OCI artifact
Since version 3.8, Helm stores charts in OCI registries – with fixed media types for the config and the chart archive. A mini chart by hand, without helm at all:
mkdir -p chart/notes/templates
cat > chart/notes/Chart.yaml <<'EOF'
# chart/notes/Chart.yaml – state at end of Day 9
apiVersion: v2
name: notes
version: 0.1.0
appVersion: "0.1.0"
EOF
cat > chart/notes/templates/cm.yaml <<'EOF'
# chart/notes/templates/cm.yaml – state at end of Day 9
apiVersion: v1
kind: ConfigMap
metadata:
name: notes
data:
version: "{{ .Chart.AppVersion }}"
EOF
tar -C chart -czf notes-0.1.0.tgz notes
echo '{"apiVersion":"v2","name":"notes","version":"0.1.0","appVersion":"0.1.0"}' \
> chart-config.json
oras push "$REG/charts/notes:0.1.0" \
--config chart-config.json:application/vnd.cncf.helm.config.v1+json \
notes-0.1.0.tgz:application/vnd.cncf.helm.chart.content.v1.tar+gzip | tail -2
oras manifest fetch "$REG/charts/notes:0.1.0" \
| jq -c '{config: .config.mediaType, layer: .layers[0].mediaType}'
C=$(oras manifest fetch "$REG/charts/notes:0.1.0" | jq -r .config.digest)
oras blob fetch --output - "$REG/charts/notes@$C"; echoExpected:
ArtifactType: application/vnd.cncf.helm.config.v1+json
Digest: sha256:87559126a99b28be786a946d1224a6ac03c688fb31ceec7fc6ae852fb259d550
{"config":"application/vnd.cncf.helm.config.v1+json","layer":"application/vnd.cncf.he
lm.chart.content.v1.tar+gzip"}
{"apiVersion":"v2","name":"notes","version":"0.1.0","appVersion":"0.1.0"}
This is exactly how
helm push notes-0.1.0.tgz oci://registry.ct.lab:5000/charts
stores the chart (helm additionally writes annotations);
helm install … oci://…/charts/notes --version 0.1.0 fetches
it. Without --artifact-type, oras derives the type from the
config’s media type.
Save your progress? Sign up for free
Drill 6: Attach an SBOM to notes-api
syft (Day 14) generates the bill of materials directly from the registry, oras attaches it:
syft -q "registry:$REG/notes/notes-api:0.1.0" -o spdx-json=notes-api.spdx.json
jq -r '"\(.spdxVersion): \(.packages | length) Pakete"' notes-api.spdx.json
oras attach --artifact-type application/spdx+json "$REG/notes/notes-api:0.1.0" \
notes-api.spdx.json:application/spdx+json | tail -2
oras discover "$REG/notes/notes-api:0.1.0"Expected:
SPDX-2.3: 10 Pakete
Attached to [registry] registry.ct.lab:5000/notes/notes-api@sha256:9a22b91aff08798c7a75…
Digest: sha256:bb38807d70b256afceaa2fe5cbd958895472cdcce5926bb8b2826f9bf9864928
registry.ct.lab:5000/notes/notes-api@sha256:9a22b91aff08798c7a7531ca483b799d2cde2492dbd…
└── application/spdx+json
└── sha256:bb38807d70b256afceaa2fe5cbd958895472cdcce5926bb8b2826f9bf9864928
└── [annotations]
└── org.opencontainers.image.created: "2026-10-30T21:27:43Z"
The image itself stays unchanged (same digest). The new manifest
points to notes-api via subject – but how does
discover find it again?
D=$(crane digest "$REG/notes/notes-api:0.1.0")
curl -s -o /dev/null -w '%{http_code}\n' -u "$REG_USER:$REG_PASS" \
"https://$REG/v2/notes/notes-api/referrers/$D"
oras repo tags "$REG/notes/notes-api"
oras manifest fetch "$REG/notes/notes-api:sha256-${D#sha256:}" \
| jq -c '.mediaType, [.manifests[] | {artifactType, digest: .digest[0:19]}]'Expected:
404
0.1.0
sha256-9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
"application/vnd.oci.image.index.v1+json"
[{"artifactType":"application/spdx+json","digest":"sha256:bb38807d70b2"}]
OCI 1.1 provides a Referrers API
(/v2/<repo>/referrers/<digest>). Registry 3.1.2
doesn’t support it (404). Then the specification’s fallback scheme kicks
in: an index under the tag sha256-<digest> that lists
all referrers. oras maintains it when attaching, cosign (Day 14) does
the same. Fetch the SBOM again:
S=$(oras discover --format json "$REG/notes/notes-api:0.1.0" \
| jq -r '.referrers[0].digest')
oras pull -o sbom "$REG/notes/notes-api@$S" >/dev/null
cmp sbom/notes-api.spdx.json notes-api.spdx.json && echo "identisch"Expected (identisch = identical):
identisch
Save your progress? Sign up for free
Drill 7: Copying with referrers and cleaning up
oras cp -r copies an image together with everything
attached to it – for example when promoting it to a release
repository:
oras cp -r "$REG/notes/notes-api:0.1.0" "$REG/release/notes-api:0.1.0" | tail -1
oras tag "$REG/release/notes-api:0.1.0" stabil | tail -1
oras repo tags "$REG/release/notes-api"
oras discover "$REG/release/notes-api:0.1.0" | sed -n 2p
regctl artifact list "$REG/release/notes-api:0.1.0" \
--format '{{range .Descriptors}}{{.ArtifactType}}{{end}}'; echoExpected:
Digest: sha256:9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
Tagged stabil
0.1.0
sha256-9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
stabil
└── application/spdx+json
application/spdx+json
Without -r, the SBOM would be left behind – the same
goes for crane copy or skopeo copy. regctl
knows about referrers too (regctl artifact list,
regctl image copy --referrers).
In the original repository, you clean up: on Day 14, cosign attaches the SBOM signed to notes-api, and an unsigned one next to it would only confuse. Delete the referrer first, then the fallback tag:
oras manifest delete --force "$REG/notes/notes-api@$S" | tail -1
oras manifest fetch "$REG/notes/notes-api:sha256-${D#sha256:}"; echo
oras manifest delete --force "$REG/notes/notes-api:sha256-${D#sha256:}" | cut -c1-60
oras repo tags "$REG/notes/notes-api"
rm -rf sbomExpected:
Deleted [registry] registry.ct.lab:5000/notes/notes-api@sha256:bb38807d70b256afceaa2fe5…
{"schemaVersion":2,"mediaType":"application/vnd.oci.image.index.v1+json","manifests":[]}
Deleted [registry] registry.ct.lab:5000/notes/notes-api:sha2
0.1.0
oras removes the referrer from the fallback index but leaves the empty index in place – you delete the tag yourself.
Save your progress? Sign up for free
Checkpoint
The mirror is up to date:
cd ~/ct-lab/tag09
source ~/ct-lab/setup/env.sh
regsync check -c regsync.yml 2>&1 | grep -c 'sync needed'Expected:
0
nginx as the original index, postgres for arm64 only:
regctl image digest "$REG/mirror/nginx:1.30.6-alpine"
regctl image inspect "$REG/mirror/postgres:18.6-alpine" \
--format '{{.Architecture}}'; echoExpected:
sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
arm64
The Helm chart is an artifact, and the SBOM is attached to release/notes-api:
oras manifest fetch "$REG/charts/notes:0.1.0" | jq -r .config.mediaType
oras discover "$REG/release/notes-api:0.1.0"Expected (shortened):
application/vnd.cncf.helm.config.v1+json
registry.ct.lab:5000/release/notes-api@sha256:322f88bdda87…
└── application/spdx+json
└── sha256:74a7545087426ea8fe43661fbd99d3de459ecc9fb83ca6279e7dd37aa41f9100
└── [annotations]
└── org.opencontainers.image.created: "…"
notes/notes-api has only the tag 0.1.0, and the units
are valid:
oras repo tags "$REG/notes/notes-api"
systemd-analyze verify --user systemd/regsync.service systemd/regsync.timer
echo "Exit: $?"Expected:
0.1.0
Exit: 0
Challenge
Attach the README.md of the notes application as a
Markdown artifact to notes/notes-web:0.1.0 and find it
again with oras discover – filtered to exactly this
artifact type.
Hint: oras discover has a filter for
the artifact type; the media type for Markdown is
text/markdown.
Solution
oras attach --artifact-type text/markdown "$REG/notes/notes-web:0.1.0" \
README.md:text/markdown | tail -1
oras discover --artifact-type text/markdown "$REG/notes/notes-web:0.1.0" | sed -n 2,3p
oras discover --artifact-type application/spdx+json "$REG/notes/notes-web:0.1.0"Expected:
Digest: sha256:18b349b152cb097dafecf5b4fe84f4dd18f39572267197c83d5bdd1d2e15a9b8
└── text/markdown
└── sha256:18b349b152cb097dafecf5b4fe84f4dd18f39572267197c83d5bdd1d2e15a9b8
registry.ct.lab:5000/notes/notes-web@sha256:…
With the filter application/spdx+json, only the image
itself remains – there is no SBOM attached to notes-web.
Save your progress? Sign up for free
Enterprise Note
- Mirrors instead of direct pulls: builds and clusters pull only from
the internal registry; regsync (or the proxy-cache feature of Harbor,
Zot, Artifactory) fetches from outside – with
tags.allowas a deliberate allowlist. - A Docker Hub login in regsync (
credsfordocker.io, token via{{ file … }}) raises the limit; tokens belong in a secret store, not in Git. - Registries with a Referrers API (OCI 1.1: Harbor, Zot, ACR, ECR,
GHCR) don’t need
sha256-…tags. When moving between registries, always copy the referrers along (oras cp -r,regctl image copy --referrers, regsyncreferrers: true). - OCI artifacts replace separate storage: charts, SBOMs, policies, configurations and binaries sit next to the images, versioned and addressable by digest.
- Unsigned attachments are only hints. Whatever counts in the supply chain gets signed (cosign attest, Day 14) and verified at acceptance.