#Registry v2: Managing Images with ac

Use the latest ac image commands to work with Registry v2 and the ACP Image API. Registry v2 is the Operator-deployed ACP Registry selected by modern registry mode. These commands provide OCP-style Image and ImageStream workflows while keeping compatibility entry points for clusters that are still switching from the legacy Registry.

#Registry Mode

ac selects the image backend from the current cluster's registry mode:

Check and set the mode:

ac config get-registry-mode
ac config set-registry-mode modern

Use the modern mode before running commands that manage ImageStreams, import images, tag images, show Image API usage, verify signatures, or prune through the Registry v2 Image API graph.

#Command Groups

#Discover and Log In to the Registry

Print the Registry host selected by the current registry mode:

ac registry info

Print the internal host:

ac registry info --internal

Check that the Registry /v2/ endpoint is reachable:

ac registry info --check

Write Registry credentials to the default Docker config file:

ac registry login

Write credentials to a migration or CI auth file:

export DOCKER_CONFIG=/tmp/registry-auth

ac registry login \
  --registry registry.example.com \
  --to "$DOCKER_CONFIG/config.json"

Use --skip-check when the Registry endpoint is not reachable from the current machine but the credential file still needs to be written. Use --insecure only when the endpoint is HTTP or uses a certificate that the client does not trust.

#Manage ImageStreams

Create an empty ImageStream:

ac create imagestream demo

Create an ImageStream with local image lookup enabled:

ac create imagestream demo --lookup-local

Create an ImageStreamTag from an external image:

ac create imagestreamtag demo:latest \
  --from-image=quay.io/example/demo:1.0

Import an external image into an ImageStreamTag. Without --confirm, the command previews the import. Add --confirm to persist the tag:

ac import-image demo:latest \
  --from=quay.io/example/demo:1.0 \
  --confirm

Common import options:

Tag an external container image into an ImageStreamTag:

ac tag --source=docker quay.io/example/demo:1.0 demo:latest

Copy the current image behind one ImageStreamTag to another:

ac tag --source=imagestreamtag team-a/demo:stable team-b/demo:latest

Delete a tag:

ac tag -d demo:old

Enable local image lookup for one ImageStream:

ac set image-lookup demo

Disable local image lookup:

ac set image-lookup demo --enabled=false

List local lookup state:

ac set image-lookup --list

#Query Images and ImageStreams

List ImageStreams:

ac get imagestreams -A

Show an ImageStream:

ac get imagestreams demo -n team-a -o yaml

Show the current digest and tag history for a tag:

ac get imagestreamtags demo:latest -n team-a -o wide

Show ImageStreamImage metadata by digest:

ac get imagestreamimages demo@sha256:<digest> -n team-a -o yaml

List images through the integrated Registry compatibility entry point:

ac get images

In modern mode, ac get images aligns with oc get images and lists cluster-scoped Image resources with NAME and IMAGE REFERENCE columns. In legacy mode, it keeps the old ACP Registry catalog output and lists repository tags.

Use structured output:

ac get images -o yaml
ac get images -o json

Legacy-only options remain available for migration and compatibility:

ac get images -n team-a --registry-url=http://old-registry.example.com:5000
ac get images --fast --registry-url=http://old-registry.example.com:5000

#Delete Image References

The preferred Registry v2 workflow is to delete ImageStream tags:

ac tag -d demo:old

The compatibility command ac delete images also works from registry mode. It is a dry run unless --confirm is set:

ac delete images --repo team-a/demo:old
ac delete images --repo team-a/demo:old --confirm

Use repeated --repo flags to delete multiple tag references:

ac delete images \
  --repo team-a/demo:old \
  --repo team-a/api:canary \
  --confirm

Deleting image references does not necessarily release blob storage immediately. Run image pruning and Registry garbage collection separately when storage reclamation is required.

#Work with OCI Images Directly

Show image metadata from a registry:

ac image info registry.example.com/team-a/demo:latest

Select one platform from a multi-architecture image:

ac image info docker.io/library/busybox:latest \
  --filter-by-os=linux/arm64

Show manifest list entries:

ac image info registry.example.com/team-a/demo:latest \
  --show-multiarch

Copy one image to another tag:

ac image mirror \
  registry.example.com/team-a/demo:latest \
  registry.example.com/team-a/demo:stable

Copy multiple images from a mapping file:

cat > mirror-map.txt <<EOF
old-registry.example.com/team-a/demo:latest=registry.example.com/team-a/demo:latest
old-registry.example.com/team-a/api:v1=registry.example.com/team-a/api:v1
EOF

ac image mirror \
  -f mirror-map.txt \
  --dry-run \
  --keep-manifest-list

ac image mirror \
  -f mirror-map.txt \
  --continue-on-error \
  --keep-manifest-list \
  --max-per-registry=4

Add layers or metadata to an image and push the result:

ac image append \
  --from docker.io/library/busybox:latest \
  --to registry.example.com/team-a/busybox:patched \
  layer.tar.gz

Preview the append operation:

ac image append \
  --from docker.io/library/busybox:latest \
  --to registry.example.com/team-a/busybox:patched \
  layer.tar.gz \
  --dry-run

Extract files from an image without a local container runtime:

ac image extract docker.io/library/busybox:latest \
  --path /:/tmp/busybox \
  --confirm

Use --insecure on ac image commands only for test registries, HTTP endpoints, or private certificates that are not trusted by the client.

#View Usage and Clean Up

Show storage and usage statistics for Images:

ac adm top images

Show storage and usage statistics for ImageStreams:

ac adm top imagestreams

Verify image signature identity recorded on an Image object:

ac adm verify-image-signature sha256:<digest> \
  --expected-identity=registry.example.com/team-a/demo:latest

Save trusted conditions back to the Image object:

ac adm verify-image-signature sha256:<digest> \
  --expected-identity=registry.example.com/team-a/demo:latest \
  --save

Preview image pruning:

ac adm prune images

Run pruning after reviewing the dry-run output:

ac adm prune images \
  --keep-tag-revisions=5 \
  --keep-younger-than=72h \
  --confirm

Exclude repositories with a whitelist:

ac adm prune images \
  --whitelist='^cpaas-system/.*' \
  --confirm

Run Registry garbage collection after metadata cleanup:

ac adm registry gc
ac adm registry gc --confirm

You can also trigger Registry GC as part of pruning:

ac adm prune images --confirm --prune-registry

Both ac adm prune images and ac adm registry gc are dry-run by default. Always review the preview before adding --confirm.