Tag 9: Spiegeln und Artefakte – regsync und oras
Ziel: Du spiegelst öffentliche Images automatisch in deine Registry und legst beliebige Dateien – Konfiguration, Helm-Chart, SBOM – als OCI-Artefakte daneben. · Dauer: ca. 75 min · Voraussetzung: Tag 8
Briefing
- regsync spiegelt nach einer YAML-Datei: Quelle,
Ziel, Tag-Filter.
checkzeigt, was zu tun wäre,oncekopiert einmal,serverläuft dauerhaft nach Zeitplan. - Eine Registry speichert nicht nur Images. Jedes Manifest mit eigenem artifactType ist ein OCI-Artefakt – eine Datei, ein Chart, eine SBOM.
- oras schiebt solche Artefakte hin und her und hängt
sie per
subjectan ein Image (Referrer). Wer hängt was an mein 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 mit subject ──► notes-api@sha256:9a22…
+ Tag sha256-9a22… (Referrers-Fallback)
Drill 1: regsync – installieren und konfigurieren
| Steckbrief | regsync |
|---|---|
| Aufgabe | Images und Repositories nach Konfiguration zwischen Registries spiegeln |
| Besonderheit | Tag-Filter per Regex, Rate-Limit-Schutz, Intervall/Cron im Server-Modus |
| Projekt | github.com/regclient/regclient, regclient.org (Apache-2.0) |
| Version im Buch | v0.11.7 |
regsync gehört zu regclient wie regctl und ist ebenfalls ein einzelnes 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'Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):
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
Die Konfiguration: Logins (creds), Vorgaben
(defaults) und die Liste der Spiegelaufträge
(sync). Werte wie das Passwort holt regsync per Template
aus der Umgebung, sie stehen nicht in der Datei:
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):'Erwartet:
user: lab
pass: lab-registry-pw-123
min: 20
platform: ""
min: 20
platform: linux/arm64
min: 20
type: repositoryspiegelt alle Tags, dietags.allow(reguläre Ausdrücke) passieren lassen;denyschließt aus.type: imagespiegelt genau einen Tag.platformkopiert nur eine Plattform statt des ganzen Index – bei postgres spart das gut 90 % des Downloads.ratelimit.min: 20: Sinkt das Docker-Hub-Kontingent unter 20, wartet regsync 15 Minuten (retry), statt dich auszusperren.
Sicherheit:
regsync configzeigt die aufgelösten Templates – inklusive Passwort im Klartext. Nicht in CI-Logs ausgeben.
Fortschritt speichern? Kostenlos registrieren
Drill 2: check und once
regsync check -c regsync.yml 2>&1 | grep -o 'msg=.*' | cut -c1-88Erwartet:
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
Drei Aufträge, obwohl mirror/nginx:1.30.6-alpine seit
Tag 8 existiert: Dort liegt nur das arm64-Manifest, auf Docker Hub ein
Index – andere Digests, also neu spiegeln.
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}}'
echoErwartet:
9
real 0m12.578s
1.30.6-alpine
stable-alpine
18.6-alpine
sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
application/vnd.oci.image.manifest.v1+json
arm64
nginx ging schnell: Alle Blobs lagen schon in deiner Registry (Tag 7), regsync musste sie nur verknüpfen. Kopiert wurden die neun postgres-Layer. Der Digest ist der Original-Index – regsync kopiert grundsätzlich digest-erhaltend. Ein zweiter Lauf:
regsync once -c regsync.yml; echo "Exit: $?"
regsync once --missing -c regsync.yml; echo "Exit: $?"Erwartet:
Exit: 0
Exit: 0
Keine Meldung, nichts zu tun. --missing prüft bestehende
Tags gar nicht erst, sondern kopiert nur fehlende – gut für Tags, die
sich nie ändern. Jetzt der Rate-Limit-Schutz: Eine Kopie der
Konfiguration verlangt mindestens 99 freie 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.ymlErwartet:
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 wartet 15 Minuten, timeout bricht vorher ab. Der
normale Lauf danach holt den Tag zurück. Ungekürzt steht in der zweiten
Zeile
source-remain=44 source-limit=100 step-min=99 sleep=15m0s.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Dauerbetrieb – server oder Timer
regsync server läuft dauerhaft und prüft jeden Auftrag
nach seinem interval (oder schedule mit
Cron-Syntax):
timeout 15 regsync server -c regsync.yml; echo "Exit: $?"Erwartet:
time=2026-10-30T20:55:59.036Z level=INFO msg="Stopping server"
Exit: 124
Als Dienst ist ein systemd-Timer mit once oft einfacher:
Er läuft, beendet sich und hinterlässt ein Journal. Eine Skizze als
User-Units:
mkdir -p systemd ~/.config/systemd/user
cat > systemd/regsync.service <<'EOF'
# systemd/regsync.service – Stand Ende Tag 9 (Skizze)
[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 – Stand Ende Tag 9 (Skizze)
[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 catErwartet:
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 meldet nichts – die Units sind
gültig. systemctl --user enable --now regsync.timer würde
den Spiegel scharf schalten; im Labor bleibt es bei der Skizze.
Alternativ läuft regsync als Container
(ghcr.io/regclient/regsync) per Quadlet-Unit (Tag 3) im
Server-Modus.
Fortschritt speichern? Kostenlos registrieren
Drill 4: oras – installieren und eine Datei pushen
| Steckbrief | oras |
|---|---|
| Aufgabe | beliebige Dateien als OCI-Artefakte ablegen, holen, kopieren, anhängen |
| Besonderheit | Referrers (attach/discover) mit Fallback auf das Tag-Schema; OCI-Layout |
| Projekt | oras.land, github.com/oras-project/oras (Apache-2.0) |
| Version im Buch | 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"Erwartet:
/tmp/oras.tgz: OK
Version: 1.3.6
Login Succeeded
backup/notes-web
lab/notes-api
library/nginx
0.1.0
oras schreibt das Login in ~/.docker/config.json –
dieselbe Datei wie crane. Jetzt eine beliebige Datei als Artefakt, hier
deine regsync-Konfiguration:
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}}'Erwartet:
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"
}
}
}
Ein Artefakt ist ein normales OCI-Manifest: artifactType
sagt, was es ist, die Config ist leer ({}, 2 Byte), jede
Datei ein Layer mit eigenem Medientyp und dem Dateinamen als
title. Zurückholen – und was Podman davon hält:
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-88Erwartet:
regsync.yml
Error: unable to copy from source docker://registry.ct.lab:5000/lab/regsync-config:tag
Podman lehnt ab
(unsupported image-specific operation on artifact): Das ist
kein Image. Genau das macht Artefakte sicher nebeneinander lagerbar.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Ein Helm-Chart als OCI-Artefakt
Helm speichert Charts seit Version 3.8 in OCI-Registries – mit festen Medientypen für Config und Chart-Archiv. Ein Mini-Chart von Hand, ganz ohne helm:
mkdir -p chart/notes/templates
cat > chart/notes/Chart.yaml <<'EOF'
# chart/notes/Chart.yaml – Stand Ende Tag 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 – Stand Ende Tag 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"; echoErwartet:
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"}
Genau so legt
helm push notes-0.1.0.tgz oci://registry.ct.lab:5000/charts
das Chart ab (helm schreibt zusätzlich Annotationen);
helm install … oci://…/charts/notes --version 0.1.0 holt
es. Ohne --artifact-type leitet oras den Typ aus dem
Medientyp der Config ab.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Eine SBOM an notes-api hängen
syft (Tag 14) erzeugt die Stückliste direkt aus der Registry, oras hängt sie an:
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"Erwartet:
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"
Das Image selbst bleibt unverändert (gleicher Digest). Das neue
Manifest zeigt mit subject auf notes-api – aber wie findet
discover es wieder?
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]}]'Erwartet:
404
0.1.0
sha256-9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
"application/vnd.oci.image.index.v1+json"
[{"artifactType":"application/spdx+json","digest":"sha256:bb38807d70b2"}]
OCI 1.1 sieht eine Referrers-API vor
(/v2/<repo>/referrers/<digest>). Registry 3.1.2
kennt sie nicht (404). Dann greift das Ausweichschema der Spezifikation:
ein Index unter dem Tag sha256-<digest>, der alle
Referrer auflistet. oras pflegt ihn beim Anhängen, cosign (Tag 14) macht
es genauso. Die SBOM wieder holen:
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"Erwartet:
identisch
Fortschritt speichern? Kostenlos registrieren
Drill 7: Kopieren mit Referrern und Aufräumen
oras cp -r kopiert ein Image samt allem, was daran hängt
– etwa beim Freigeben in ein 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}}'; echoErwartet:
Digest: sha256:9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
Tagged stabil
0.1.0
sha256-9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
stabil
└── application/spdx+json
application/spdx+json
Ohne -r bliebe die SBOM zurück – genauso bei
crane copy oder skopeo copy. regctl kennt
Referrer auch (regctl artifact list,
regctl image copy --referrers).
Im Original-Repository räumst du auf: An Tag 14 hängt cosign die SBOM signiert an notes-api, eine unsignierte daneben würde nur verwirren. Erst den Referrer, dann den Fallback-Tag löschen:
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 sbomErwartet:
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 entfernt den Referrer aus dem Fallback-Index, lässt den leeren Index aber stehen – den Tag löschst du selbst.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Der Spiegel ist aktuell:
cd ~/ct-lab/tag09
source ~/ct-lab/setup/env.sh
regsync check -c regsync.yml 2>&1 | grep -c 'sync needed'Erwartet:
0
nginx als Original-Index, postgres nur für arm64:
regctl image digest "$REG/mirror/nginx:1.30.6-alpine"
regctl image inspect "$REG/mirror/postgres:18.6-alpine" \
--format '{{.Architecture}}'; echoErwartet:
sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
arm64
Das Helm-Chart ist ein Artefakt, an release/notes-api hängt die SBOM:
oras manifest fetch "$REG/charts/notes:0.1.0" | jq -r .config.mediaType
oras discover "$REG/release/notes-api:0.1.0"Erwartet (gekürzt):
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 hat nur den Tag 0.1.0, die Units sind
gültig:
oras repo tags "$REG/notes/notes-api"
systemd-analyze verify --user systemd/regsync.service systemd/regsync.timer
echo "Exit: $?"Erwartet:
0.1.0
Exit: 0
Challenge
Hänge die README.md der notes-Anwendung als
Markdown-Artefakt an notes/notes-web:0.1.0 und finde sie
mit oras discover wieder – gefiltert auf genau diesen
Artefakttyp.
Hinweis: oras discover hat einen Filter
für den Artefakttyp; der Medientyp für Markdown ist
text/markdown.
Lösung
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"Erwartet:
Digest: sha256:18b349b152cb097dafecf5b4fe84f4dd18f39572267197c83d5bdd1d2e15a9b8
└── text/markdown
└── sha256:18b349b152cb097dafecf5b4fe84f4dd18f39572267197c83d5bdd1d2e15a9b8
registry.ct.lab:5000/notes/notes-web@sha256:…
Mit dem Filter application/spdx+json bleibt nur das
Image selbst stehen – es hängt keine SBOM an notes-web.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Spiegel statt direkter Pulls: Builds und Cluster ziehen nur aus der
internen Registry; regsync (oder die Proxy-Cache-Funktion von Harbor,
Zot, Artifactory) holt von außen – mit
tags.allowals bewusster Freigabeliste. - Docker-Hub-Login in regsync (
credsfürdocker.io, Token per{{ file … }}) hebt das Limit; Token gehören in einen Secret-Store, nicht ins Git. - Registries mit Referrers-API (OCI 1.1: Harbor, Zot, ACR, ECR, GHCR)
brauchen keine
sha256-…-Tags. Beim Umzug zwischen Registries Referrer immer mitkopieren (oras cp -r,regctl image copy --referrers, regsyncreferrers: true). - OCI-Artefakte ersetzen getrennte Ablagen: Charts, SBOMs, Policies, Konfigurationen und Binaries liegen versioniert und per Digest adressierbar neben den Images.
- Unsignierte Anhänge sind nur Hinweise. Was in der Lieferkette zählt, wird signiert (cosign attest, Tag 14) und bei der Abnahme geprüft.