Skip to content
Hands-on IT IT Drills

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 HEALTHCHECK along 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-only copies 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.tar

Expected:

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. Rootless containers-storage: therefore only works via podman 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/null

Expected:

["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 .Tags

Expected:

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

Expected:

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 p2

Expected:

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

Expected:

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

Expected:

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 head is a HEAD request: the digest without a download – does not count as a pull on Docker Hub.
  • --format takes Go templates over regclient’s fields; raw-body returns the manifest unchanged for jq.
  • image inspect and image config automatically resolve the index to your platform, --platform selects 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.User

Expected:

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

Expected:

{"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.json

Expected:

["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 .mediaType

Expected:

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

Expected: 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.json

Expected:

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

Expected:

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

Expected (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 dir or regctl image export onto a medium, and on the other side back into the internal registry – always with --preserve-digests, otherwise signatures and pins break.
  • A policy.json with reject as the default and sigstoreSigned for 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.json on build runners.