Skip to content
Hands-on IT IT Drills

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. check shows what would need doing, once copies once, server runs 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: repository mirrors all tags that pass tags.allow (regular expressions); deny excludes. type: image mirrors exactly one tag.
  • platform copies 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 config shows 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-88

Expected:

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}}'
echo

Expected:

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.yml

Expected:

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 cat

Expected:

    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-88

Expected:

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"; echo

Expected:

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}}'; echo

Expected:

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 sbom

Expected:

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}}'; echo

Expected:

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.allow as a deliberate allowlist.
  • A Docker Hub login in regsync (creds for docker.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, regsync referrers: 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.