Day 8: Moving images – skopeo and regctl
Goal: You inspect images without pulling, migrate them between registries and formats, and know the two tools that do this most thoroughly. · Duration: approx. 90 min · Prerequisite: Day 7
Briefing
- skopeo comes from the Podman project and uses the
same library (
containers/image): same logins, same policy, same transports (docker://,oci:,dir:,docker-archive:,containers-storage:). - regctl (regclient) is a pure registry tool: manifests, blobs, tags, artifacts, rate limits, modifying images – all directly via the API.
- Both copy without a daemon. The difference is in the details: who
converts, who keeps digests, who loses the
HEALTHCHECKalong the way?
docker://docker.io/… ──skopeo copy──► docker://registry.ct.lab:5000/mirror/…
│ │ ▲
│ skopeo copy ─────┤ │ regctl image import
▼ ▼ │
oci:dir:tag dir:ordner docker-archive:x.tar regctl image export x.tar
containers-storage:localhost/… (Podman storage)
Drill 1: skopeo – inspect without pulling
| Profile | skopeo |
|---|---|
| Purpose | Inspect, copy, synchronize and delete images – without a daemon |
| Special feature | transports for registry, directory, archives and Podman storage; policy |
| Project | github.com/containers/skopeo (Apache-2.0) |
| Version in the book | 1.21.0 (Ubuntu package skopeo) |
source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag08 && cd ~/ct-lab/tag08
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag07/notes/." .
sudo apt-get install -y skopeo >/dev/null
apt-cache policy skopeo | sed -n 2p; skopeo --version
N="docker://$REG/library/nginx:1.30.6-alpine"
skopeo inspect "$N" | jq '{Name, Digest, Architecture, Created, RepoTags}'Expected (abridged, IDs and times will differ on your machine):
Installed: 1.21.0~pre1-2build1
skopeo version 1.21.0-dev
{
"Name": "registry.ct.lab:5000/library/nginx",
"Digest": "sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949",
"Architecture": "arm64",
"Created": "2026-10-22T00:16:56.267286194Z",
"RepoTags": [
"1.30.6-alpine"
]
}
inspect fetches the index, the matching manifest and the
config – no layers. Digest is the index digest,
Architecture is your machine’s
(--override-arch amd64 asks for a different one). The raw
data is available too:
skopeo inspect --raw "$N" | jq -r '.mediaType, (.manifests | length)'
skopeo inspect --config "$N" | jq -c '{architecture, variant, cmd: .config.Cmd}'
skopeo inspect --format '{{.Digest}} {{.Architecture}}' \
"docker://$REG/notes/notes-api:0.1.0"
skopeo inspect --no-tags "docker://$REG/notes/notes-api:0.1.0" \
| jq -r '.Labels["org.opencontainers.image.version"]'Expected:
application/vnd.oci.image.index.v1+json
16
{"architecture":"arm64","variant":"v8","cmd":["nginx","-g","daemon off;"]}
sha256:9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23 arm64
0.1.0
--raw shows the manifest unchanged,
--config the config, --format takes a Go
template. --no-tags skips listing all tags – noticeably
faster for repositories with a thousand tags.
Save your progress? Sign up for free
Drill 2: Registry migration with
skopeo copy
The classic: bring a public image into your own registry.
skopeo copy docker://docker.io/library/nginx:1.30.6-alpine \
"docker://$REG/mirror/nginx:1.30.6-alpine"
skopeo inspect --raw "docker://$REG/mirror/nginx:1.30.6-alpine" | jq -r .mediaType
skopeo inspect --format '{{.Digest}}' "docker://$REG/mirror/nginx:1.30.6-alpine"Expected:
Getting image source signatures
Copying blob sha256:872998b8576e5aa2dd875c0a156f30bb6bc2573fddce2652fce6884a9893952d
Copying blob sha256:d3531b7a4f217bdc3426c57bcff84c170f086f456a39689d4a615c6d026c4be0
…
Copying config sha256:71f44768e348d88b5e3ea14a77e0e082792bc46d283de47ef08249bd7ae2e223
Writing manifest to image destination
application/vnd.oci.image.manifest.v1+json
sha256:4f7cab9e1cd018f80e67f31e02dc0c6d18560b19504461c4f3dd37e5c63a74c5
Without further options, skopeo copies only your
platform: the destination holds no index, but the arm64
manifest (you know 4f7c… from Day 7). For a real mirror you
need --all – this time from your registry, so Docker Hub is
spared:
skopeo copy -q --all --preserve-digests "$N" \
"docker://$REG/mirror/nginx:1.30.6-alpine-all"
skopeo inspect --format '{{.Digest}}' "docker://$REG/mirror/nginx:1.30.6-alpine-all"Expected:
sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
Why --preserve-digests? skopeo remembers in
~/.local/share/containers/cache/blob-info-cache-v1.sqlite
which compressed blobs have the same content, and may substitute a
known, differently compressed blob while copying. In a test run without
the switch, skopeo replaced the Alpine base layer of amd64 with the one
from notes-web this way – the index got a new digest
(05ff… instead of 0e52…). With
--preserve-digests this never happens; signatures and pins
stay valid.
Tip:
--multi-arch index-onlycopies only the index without the images – almost never useful, often dangerous. For mirrors:--all --preserve-digests.
Save your progress? Sign up for free
Drill 3: Transports – directories, archives, Podman storage
skopeo copy -q "docker://$REG/notes/notes-api:0.1.0" dir:api-dir
skopeo copy -q "docker://$REG/notes/notes-api:0.1.0" oci:api-oci:0.1.0
skopeo copy -q "docker://$REG/notes/notes-api:0.1.0" \
docker-archive:api.tar:localhost/notes-api:archiv
ls api-dir api-oci
jq -c '.manifests[] | {mediaType,
ref: .annotations["org.opencontainers.image.ref.name"]}' api-oci/index.json
skopeo inspect --format '{{.Digest}}' oci:api-oci:0.1.0
du -sh api-dir api-oci api.tarExpected:
api-dir:
0765d1019f4676ebd06a9055cfa442cd6d000689f5e2ba31be8fc998b89faf7b
2f8852384d1b2d65d511677cf4bbe13190ec6619d81d7935942c229f5c19cacb
34a23a5bdaf142798f754d18fa12765aaaf79f520ee3968f1714a79cfcc2aaf0
manifest.json
version
api-oci:
blobs
index.json
oci-layout
{"mediaType":"application/vnd.oci.image.manifest.v1+json","ref":"0.1.0"}
sha256:1389c10cc4811b7ad4f77c740ffae5be4f6d43239f596aebceffc6c409f16df0
4.5M api-dir
4.5M api-oci
12M api.tar
| Transport | Content | Typical for |
|---|---|---|
dir: |
blobs and manifest as individual files | debugging, air gap |
oci:pfad:tag |
OCI layout (like crane pull --format oci) |
tool chains |
docker-archive: |
docker save format, layers uncompressed |
podman load, old tools |
containers-storage: |
Podman/Buildah storage | build locally, then copy |
Watch the digest: oci: rewrote the Docker manifest into
an OCI manifest – new digest 1389…. Now the local Podman
storage:
skopeo copy -q dir:api-dir containers-storage:localhost/notes-api:von-dir
podman unshare skopeo copy -q dir:api-dir \
containers-storage:localhost/notes-api:von-dir; echo "Exit: $?"
podman images --format '{{.Repository}}:{{.Tag}} {{.ID}}' localhost/notes-api \
| grep -E ':(0\.1\.0|von-dir) 'Expected:
Error during unshare(...): Operation not permitted
Exit: 0
localhost/notes-api:von-dir 0765d1019f46
localhost/notes-api:0.1.0 0765d1019f46
Warning: Ubuntu 26.04 allows user namespaces only for programs with an AppArmor profile (
kernel.apparmor_restrict_unprivileged_userns = 1). Podman and Buildah have one, skopeo does not. Rootlesscontainers-storage:therefore only works viapodman unshare skopeo …– then skopeo runs in Podman’s namespace.
The same image ID 0765… as 0.1.0: it is the same image.
And what happens to the HEALTHCHECK from the Docker format when
converting to OCI?
skopeo copy -q --format oci "docker://$REG/notes/notes-api:0.1.0" \
"docker://$REG/lab/notes-api:0.1.0-oci"
skopeo inspect --config --raw "docker://$REG/notes/notes-api:0.1.0" \
| jq -c .config.Healthcheck.Test
skopeo inspect --config --raw "docker://$REG/lab/notes-api:0.1.0-oci" \
| jq -c .config.Healthcheck.Test
podman rmi localhost/notes-api:von-dir >/dev/nullExpected:
["CMD","/notes-api","healthcheck"]
null
skopeo rebuilds the config when converting – and the OCI
specification has no Healthcheck. By the way, without
--raw, inspect --config always shows the
config translated to OCI, so the HEALTHCHECK is missing there even for
the original. --preserve-digests together with
--format oci does not convert at all: a new digest would be
the exact opposite.
Save your progress? Sign up for free
Drill 4: sync, list-tags, delete, login and policy
skopeo sync copies entire repositories – here as a
backup into a directory and into another repository:
skopeo sync --src docker --dest dir --scoped "$REG/notes/notes-api" backup/ \
2>&1 | tail -1
find backup -maxdepth 4 -type d | tail -1
skopeo sync --src docker --dest docker "$REG/notes/notes-web" "$REG/backup" \
2>&1 | tail -1
skopeo list-tags "docker://$REG/backup/notes-web" | jq -c .TagsExpected:
time="2026-10-30T20:51:27Z" level=info msg="Synced 1 images from 1 sources"
backup/registry.ct.lab:5000/notes/notes-api:0.1.0
time="2026-10-30T20:51:28Z" level=info msg="Synced 1 images from 1 sources"
["0.1.0"]
--scoped creates the full source path in the
destination. For several sources with filters, sync takes a YAML file
(--src yaml); --dry-run only shows what would
happen:
cat > sync.yaml <<'EOF'
# sync.yaml – Stand Ende Tag 8: Quellen für skopeo sync --src yaml
registry.ct.lab:5000:
images-by-tag-regex:
notes/notes-api: ^0\.1\.
notes/notes-worker: ^0\.
EOF
skopeo sync --src yaml --dest docker --dry-run sync.yaml "$REG/backup" 2>&1 \
| grep -o 'Would have.*' | cut -c1-88Expected:
Would have copied image ref 1/1" from="docker://registry.ct.lab:5000/notes/notes-work
Would have copied image ref 1/1" from="docker://registry.ct.lab:5000/notes/notes-api:
Would have synced 2 images from 2 sources
Deleting and logins:
skopeo delete "docker://$REG/backup/notes-web:0.1.0"
skopeo list-tags "docker://$REG/backup/notes-web" | jq -c .Tags
skopeo logout "$REG" && cat "$XDG_RUNTIME_DIR/containers/auth.json"; echo
skopeo list-tags "docker://$REG/notes/notes-api" | jq -c .Tags
echo "$REG_PASS" | skopeo login -u "$REG_USER" --password-stdin "$REG"Expected:
[]
Removed login credentials for registry.ct.lab:5000
{
"auths": {}
}
["0.1.0"]
Login Succeeded!
After the logout, list-tags still works: skopeo falls
back to ~/.docker/config.json (the crane login from Day 7).
skopeo login writes the same file as
podman login.
Finally, the policy:
/etc/containers/policy.json decides which images skopeo and
Podman accept at all. Ubuntu ships “everything allowed”:
jq -c . /etc/containers/policy.json
cat > policy-lab.json <<'EOF'
{
"default": [{"type": "reject"}],
"transports": {
"docker": {"registry.ct.lab:5000": [{"type": "insecureAcceptAnything"}]},
"dir": {"": [{"type": "insecureAcceptAnything"}]}
}
}
EOF
skopeo --policy policy-lab.json copy -q "docker://$REG/notes/notes-api:0.1.0" dir:p1
echo "Exit: $?"
skopeo --policy policy-lab.json copy -q oci:api-oci:0.1.0 dir:p2; echo "Exit: $?"
rm -rf p1 p2Expected:
{"default":[{"type":"insecureAcceptAnything"}]}
Exit: 0
time="2026-10-30T20:51:52Z" level=fatal msg="Source image rejected: Running image oci:
api-oci:0.1.0 is rejected by policy."
Exit: 1
Only your registry and dir: are allowed, everything else
is rejected. Instead of insecureAcceptAnything, there can
be sigstoreSigned with a key – then Podman only accepts
signed images (Day 14). System-wide, the file in
/etc/containers/ applies; per user,
~/.config/containers/policy.json.
Save your progress? Sign up for free
Drill 5: regctl – install, log in, tags
| Profile | regctl |
|---|---|
| Purpose | Registry tool for manifests, blobs, tags, artifacts and images |
| Special feature | rate limit display, mirrors, Go templates, modifying images
(image mod) |
| Project | github.com/regclient/regclient, regclient.org (Apache-2.0) |
| Version in the book | v0.11.7 |
regctl is a single binary:
arch=$(dpkg --print-architecture)
read -r _ _ url sum < <(grep "^regctl $arch " "$LAB/setup/tools.lock")
curl -fsSLo /tmp/regctl "$url"
echo "$sum /tmp/regctl" | sha256sum -c -
sudo install -m 0755 /tmp/regctl /usr/local/bin/regctl && rm /tmp/regctl
regctl version --format '{{.VCSTag}}'; echo
regctl tag ls "$REG/notes/notes-api"
regctl registry whoami "$REG"Expected:
/tmp/regctl: OK
v0.11.7
0.1.0
no login found for registry.ct.lab:5000
regctl already reads the tags – with the login from
~/.docker/config.json. whoami, however, only
knows regctl’s own configuration. A login of its own:
echo "$REG_PASS" | regctl registry login "$REG" -u "$REG_USER" --pass-stdin
ls -l ~/.regctl/config.json
jq '.hosts | map_values(keys)' ~/.regctl/config.json
regctl registry whoami "$REG"Expected:
-rw------- 1 ubuntu ubuntu 113 Oct 30 20:52 /home/ubuntu/.regctl/config.json
{
"registry.ct.lab:5000": [
"pass",
"user"
]
}
lab
Now the example from the briefing: all tags of nginx – with a filter.
regctl tag ls docker.io/library/nginx | wc -l
regctl tag ls --include '1\.30\.6-alpine.*' docker.io/library/nginx
regctl image ratelimit docker.io/library/nginx:1.30.6-alpine
regctl image ratelimit "$REG/notes/notes-api:0.1.0" --format '{{.Set}}'; echoExpected:
1381
1.30.6-alpine
1.30.6-alpine-otel
1.30.6-alpine-perl
1.30.6-alpine-slim
1.30.6-alpine3.24
1.30.6-alpine3.24-otel
1.30.6-alpine3.24-perl
1.30.6-alpine3.24-slim
{
"Remain": 53,
"Limit": 100,
"Reset": 0,
"Set": true,
"Policies": [
"100;w=3600"
]
}
false
--include and --exclude are regular
expressions over the whole tag. ratelimit sends a HEAD
request and reads the headers ratelimit-remaining and
ratelimit-limit: 53 of 100 pulls left in this one-hour
window (w=3600). HEAD itself does not count. Your registry
has no limit (Set: false).
Save your progress? Sign up for free
Drill 6: Manifests and templates
N="$REG/library/nginx:1.30.6-alpine"
regctl manifest head "$N"
regctl manifest get "$N" | sed -n 2p | tr -s ' '
regctl manifest get "$N" --format '{{range .Manifests}}{{if ne .Platform.OS "unknown"}}
{{- .Platform.Architecture}}{{with .Platform.Variant}}/{{.}}{{end}} {{end}}{{end}}'
echo
regctl image digest --platform linux/arm64 "$N"
regctl image inspect "$N" --format '{{.Architecture}}/{{.Variant}} {{.Created}}'; echo
regctl image config "$N" --format '{{len .RootFS.DiffIDs}} Layer'; echo
regctl manifest get "$REG/notes/notes-api:0.1.0" --format raw-body | jq -r .mediaTypeExpected:
sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
MediaType: application/vnd.oci.image.index.v1+json
amd64 arm/v6 arm/v7 arm64/v8 386 ppc64le riscv64 s390x
sha256:4f7cab9e1cd018f80e67f31e02dc0c6d18560b19504461c4f3dd37e5c63a74c5
arm64/v8 2026-10-22 00:16:56.267286194 +0000 UTC
8 Layer
application/vnd.docker.distribution.manifest.v2+json
manifest headis a HEAD request: the digest without a download – does not count as a pull on Docker Hub.--formattakes Go templates over regclient’s fields;raw-bodyreturns the manifest unchanged for jq.image inspectandimage configautomatically resolve the index to your platform,--platformselects a different one.
Save your progress? Sign up for free
Drill 7: Copy, modify, export
regctl image copy "$REG/notes/notes-api:0.1.0" "$REG/lab/notes-api:rc"
regctl image mod "$REG/lab/notes-api:rc" --to-oci --label lab.tag=08 \
--create 0.1.0-oci08
regctl manifest get "$REG/lab/notes-api:0.1.0-oci08" --format raw-body \
| jq -r .mediaType
regctl image inspect "$REG/lab/notes-api:0.1.0-oci08" \
--format '{{index .Config.Labels "lab.tag"}} {{json .Config.Healthcheck.Test}}'Expected:
registry.ct.lab:5000/lab/notes-api:rc
registry.ct.lab:5000/lab/notes-api:0.1.0-oci08
application/vnd.oci.image.manifest.v1+json
08 ["CMD","/notes-api","healthcheck"]
image mod writes a new image under the tag from
--create (or, with --replace, replaces the old
one). Unlike skopeo, --to-oci only changes the media types
and leaves the config alone – the HEALTHCHECK stays. More switches of
image mod: --env, --annotation,
--layer-strip-file, --time and
--reproducible.
Files, archives, blobs:
regctl image get-file "$REG/notes/notes-api:0.1.0" /etc/ssl/certs/ca-certificates.crt \
| head -1
regctl image export "$REG/notes/notes-api:0.1.0" api-regctl.tar
tar -tf api-regctl.tar | head -4
regctl image import "$REG/lab/notes-api:import" api-regctl.tar
regctl image digest "$REG/lab/notes-api:import"
C=$(regctl manifest get "$REG/notes/notes-api:0.1.0" --format '{{.Config.Digest}}')
regctl blob head "$REG/notes/notes-api" "$C" \
| grep -E '^(Content-Length|Docker-Content)'
regctl blob get "$REG/notes/notes-api" "$C" | jq -r .config.UserExpected:
-----BEGIN CERTIFICATE-----
oci-layout
index.json
manifest.json
blobs/
sha256:9a22b91aff08798c7a7531ca483b799d2cde2492dbdf911f291c161d4ffc7f23
Content-Length: 3848
Docker-Content-Digest: sha256:0765d1019f4676ebd06a9055cfa442cd6d000689f5e2ba31be8fc998…
65532:65532
get-file fetches a single file from the layers without
unpacking the image. The export format is both an OCI layout and a
docker save archive (manifest.json) – import
into Podman or into a registry without a digest change. Tags and
repositories:
regctl tag ls "$REG/lab/notes-api"
regctl tag rm "$REG/lab/notes-api:rc"
regctl tag ls "$REG/lab/notes-api"
regctl repo ls "$REG"Expected:
0.1.0-oci
0.1.0-oci08
import
rc
0.1.0-oci
0.1.0-oci08
import
backup/notes-web
lab/notes-api
library/nginx
mirror/nginx
notes/notes-api
notes/notes-web
notes/notes-worker
tag rm deletes only the tag – unlike
crane delete by digest, other tags on the same manifest
(import) stay in place. backup/notes-web stays
in the list even though it no longer has a tag: the registry does not
forget empty repositories.
Save your progress? Sign up for free
Drill 8: Registry options and mirror
regctl remembers options per registry. A mirror routes requests for Docker Hub to your registry first, plus a brake of two requests per second:
regctl registry set docker.io --mirror "$REG" --req-per-sec 2
regctl registry config docker.io | jq -c '{hostname, mirrors, reqPerSec}'
regctl -v trace image digest docker.io/library/nginx:1.30.6-alpine 2>&1 \
| grep -o 'req-method=HEAD req-url="https://[^/]*' | head -1Expected:
{"hostname":"registry-1.docker.io","mirrors":["registry.ct.lab:5000"],"reqPerSec":2}
req-method=HEAD req-url="https://registry.ct.lab:5000
The first request goes to your registry:
docker.io/library/nginx is looked up there as
library/nginx – exactly the path you copied nginx to on Day
7. If the image is missing from the mirror, regctl asks Docker Hub. To
remove it again: --mirror "" leaves an empty entry behind,
jq is cleaner:
jq 'del(.hosts["docker.io"])' ~/.regctl/config.json > /tmp/rc.json
install -m 0600 /tmp/rc.json ~/.regctl/config.json && rm /tmp/rc.json
jq -c '.hosts | keys' ~/.regctl/config.jsonExpected:
["registry.ct.lab:5000"]
Clean up the playground:
for t in 0.1.0-oci 0.1.0-oci08 import; do regctl tag rm "$REG/lab/notes-api:$t"; done
regctl tag rm "$REG/mirror/nginx:1.30.6-alpine-all"
rm -rf api-dir api-oci api.tar api-regctl.tar backup
regctl tag ls "$REG/mirror/nginx"Expected:
1.30.6-alpine
Save your progress? Sign up for free
Checkpoint
mirror/nginx is a single manifest:
cd ~/ct-lab/tag08
source ~/ct-lab/setup/env.sh
skopeo inspect --raw "docker://$REG/mirror/nginx:1.30.6-alpine" | jq -r .mediaTypeExpected:
application/vnd.oci.image.manifest.v1+json
It contains only your machine’s architecture:
regctl image inspect "$REG/mirror/nginx:1.30.6-alpine" \
--format '{{.Architecture}}'; echoExpected: arm64 on a Mac with an Apple chip,
amd64 on an Intel machine like here.
amd64
regctl is logged in, a mirror for docker.io is no longer configured:
jq -r '.hosts | keys[]' ~/.regctl/config.jsonExpected:
registry.ct.lab:5000
The policy rejects foreign sources, lab/notes-api is
empty:
jq -r '.default[0].type' policy-lab.json
regctl tag ls "$REG/lab/notes-api" | wc -lExpected:
reject
0
Challenge
Are postgres:18.6-alpine and
postgres:18-alpine on Docker Hub currently the same image?
Also prove that your check did not use up a single pull.
Hint: Digests via HEAD request do not count – compare the rate limit before and after.
Solution
regctl image ratelimit docker.io/library/postgres:18-alpine --format '{{.Remain}}'; echo
for t in 18.6-alpine 18-alpine 18.6-alpine3.24; do
echo "$t $(regctl image digest "docker.io/library/postgres:$t")"
done
regctl image ratelimit docker.io/library/postgres:18-alpine --format '{{.Remain}}'; echoExpected (the number depends on your pulls in the last hour):
100
18.6-alpine sha256:10a5c69a83035ab5239f5620d708520e8b28f5aa1f2b20143e6024532edadfb5
18-alpine sha256:10a5c69a83035ab5239f5620d708520e8b28f5aa1f2b20143e6024532edadfb5
18.6-alpine3.24 sha256:10a5c69a83035ab5239f5620d708520e8b28f5aa1f2b20143e6024532edadfb5
100
Three tags, one digest – and the limit is unchanged. In the Compose
file, the digest belongs after the tag
(postgres:18.6-alpine@sha256:10a5…), then it is
binding.
Save your progress? Sign up for free
Enterprise Note
- Air-gap transfer:
skopeo sync --dest dirorregctl image exportonto a medium, and on the other side back into the internal registry – always with--preserve-digests, otherwise signatures and pins break. - A
policy.jsonwithrejectas the default andsigstoreSignedfor your own registry turns Podman hosts into consumers of verified images only. - Docker Hub limits hit entire NAT networks: a central pull-through cache or mirror (regsync, Day 9) instead of hundreds of clients with anonymous pulls.
- Format conversions (
skopeo --format oci) change digests and can lose fields such as HEALTHCHECK. In pipelines, convert deliberately once, then only copy in a digest-preserving way. - regctl in CI: logins via
--host reg=…,user=…,pass=…or the environment, never the personal~/.regctl/config.jsonon build runners.