#Registry v2: Managing Images with ac

Use the latest ac image commands to work with Registry v2 and the Image API. Registry v2 is selected by modern registry mode and provides Image and ImageStream workflows for clusters. Compatibility entry points remain available for environments that still use 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 modern mode before managing ImageStreams, importing images, tagging images, or viewing Image API usage through the Registry v2 Image API graph.

#Command Groups

Administrative usage reporting, cleanup, and trust verification are documented in Managing Registry v2 access and cleanup.

#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 temporary 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 lists cluster-scoped Image resources with NAME and IMAGE REFERENCE columns. In legacy mode, it keeps the old 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 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 follows the selected 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.