Zum Inhalt springen
Trainingslager IT-Trainingslager

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. check zeigt, was zu tun wäre, once kopiert einmal, server lä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 subject an 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: repository spiegelt alle Tags, die tags.allow (reguläre Ausdrücke) passieren lassen; deny schließt aus. type: image spiegelt genau einen Tag.
  • platform kopiert 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 config zeigt 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-88

Erwartet:

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

Erwartet:

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

Erwartet:

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 cat

Erwartet:

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

Erwartet:

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

Erwartet:

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

Erwartet:

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 sbom

Erwartet:

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

Erwartet:

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.allow als bewusster Freigabeliste.
  • Docker-Hub-Login in regsync (creds für docker.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, regsync referrers: 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.