#Managing Images with ac

Use the ac image commands to work with Alauda Container Platform Registry and the Image API. Alauda Container Platform Registry in ACP 4.4 uses the modern registry mode and provides Image and ImageStream workflows for clusters.

#Prerequisites

• The ac CLI is installed and authenticated to the target cluster.
• The Registry and the image.alauda.io/v1 Image API are available.
• You have the required permissions for the ImageStream, Image, and workload resources used by the command.

#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 Image API graph.

#Command Groups

Administrative usage reporting, cleanup, and trust verification are documented in Managing 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

Print the public host discovered from the configured external route:

ac registry info --public

Check that the Registry /v2/ endpoint is reachable:

ac registry info --check

Write Registry credentials to the default local credential file:

ac registry login

Write credentials to a temporary or CI auth file:

mkdir -p /tmp/registry-auth

ac registry login \
  --registry registry.example.com \
  --to /tmp/registry-auth/config.json

export REGISTRY_AUTH_FILE=/tmp/registry-auth/config.json

Expected result:

• The Registry credentials are written to /tmp/registry-auth/config.json and are available to subsequent direct image commands through REGISTRY_AUTH_FILE.

--to and --registry-config (or -a) select the output auth file for ac registry login.

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=source.example.com/source-team/source-app: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=source.example.com/source-team/source-app:1.0 \
  --confirm

Verify the persisted ImageStreamTag:

ac get imagestreamtags demo:latest -o yaml

Expected result:

• The ImageStreamTag contains the imported image reference and digest.

Common import options:

Tag an external image into an ImageStreamTag:

ac tag source.example.com/source-team/source-app: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

Use tag options to control tracking and import behavior:

ac tag --source=imagestreamtag --alias team-a/demo:stable team-a/demo:latest
ac tag --source=imagestreamtag --reference team-a/demo:stable team-a/demo:latest
ac tag source.example.com/source-team/source-app:latest demo:latest \
  --scheduled \
  --insecure \
  --reference-policy=local \
  --import-mode=PreserveOriginal

--alias requires the source and destination to be in the same ImageStream. The --scheduled and --insecure options apply to external image sources.

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

Set a workload image from the current ImageStreamTag pull specification:

ac set image deployment/my-app app=team-a/demo:latest --source=imagestreamtag -n team-a

Set a workload image from an ImageStreamImage digest:

ac set image deployment/my-app app=team-a/demo@sha256:<digest> \
  --source=imagestreamimage -n team-a

Verify the workload update:

kubectl -n team-a rollout status deployment/my-app --timeout=300s
kubectl -n team-a get deployment my-app -o jsonpath='{.spec.template.spec.containers[?(@.name=="app")].image}{"\n"}'

Expected result:

• The Deployment uses the pull specification resolved from the ImageStream resource, and the rollout completes successfully.

#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 command:

ac get images

In modern mode, ac get images lists cluster-scoped Image resources with NAME and IMAGE REFERENCE columns. Use structured output:

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

#Delete Image References

The preferred Registry workflow is to delete ImageStream tags:

ac tag -d demo:old

The ac delete images command 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 \
  --registry-config="$REGISTRY_AUTH_FILE"

Select one platform from a multi-architecture image:

ac image info external-registry.example.com/base/base-app:latest \
  --filter-by-os=linux/arm64 \
  --registry-config="$REGISTRY_AUTH_FILE"

Show manifest list entries:

ac image info registry.example.com/team-a/demo:latest \
  --show-multiarch \
  --registry-config="$REGISTRY_AUTH_FILE"

Copy one image to another tag:

ac image mirror \
  registry.example.com/team-a/demo:latest \
  registry.example.com/team-a/demo:stable \
  --registry-config="$REGISTRY_AUTH_FILE"

Copy multiple images from a mapping file:

cat > mirror-map.txt <<EOF
source-registry.example.com/team-a/demo:latest=registry.example.com/team-a/demo:latest
source-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 \
  --skip-missing \
  --filter-by-os=linux/amd64 \
  --registry-config="$REGISTRY_AUTH_FILE"

--skip-missing continues when an input image is not found. --filter-by-os selects the requested platform; combine it with --keep-manifest-list when the destination must remain a multi-architecture manifest list containing the selected platform entries.

Verify a copied image:

ac image info registry.example.com/team-a/demo:stable \
  --registry-config="$REGISTRY_AUTH_FILE"

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

ac image append \
  --from external-registry.example.com/base/base-app:latest \
  --to registry.example.com/team-a/base-app:patched \
  layer.tar.gz \
  --registry-config="$REGISTRY_AUTH_FILE"

Preview the append operation:

ac image append \
  --from external-registry.example.com/base/base-app:latest \
  --to registry.example.com/team-a/base-app:patched \
  layer.tar.gz \
  --dry-run \
  --registry-config="$REGISTRY_AUTH_FILE"

The --image option merges a JSON object into the runtime image configuration. The --meta option merges a JSON object into the top-level image metadata. You can also use --drop-history or --created-at without adding a layer:

ac image append \
  --from external-registry.example.com/base/base-app:latest \
  --to registry.example.com/team-a/base-app:annotated \
  --image='{"Entrypoint":["/app/start"]}' \
  --meta='{"author":"team-a"}' \
  --created-at=2024-01-01T00:00:00Z \
  --registry-config="$REGISTRY_AUTH_FILE"

ac image append \
  --from external-registry.example.com/base/base-app:latest \
  --to registry.example.com/team-a/base-app:no-history \
  --drop-history \
  --keep-manifest-list \
  --registry-config="$REGISTRY_AUTH_FILE"

Expected result:

• ac image append pushes the resulting image, or prints the planned action with --dry-run.
• --keep-manifest-list preserves the multi-architecture index while applying the append operation to matching platform images.

Extract files from an image without a local container runtime:

ac image extract external-registry.example.com/base/base-app:latest \
  --path /:/tmp/base-app \
  --confirm \
  --registry-config="$REGISTRY_AUTH_FILE"

Extract selected files to the current directory:

ac image extract external-registry.example.com/base/base-app:latest \
  --file /etc/app/config.yaml \
  --registry-config="$REGISTRY_AUTH_FILE"

Preview an extraction without writing files:

ac image extract external-registry.example.com/base/base-app:latest \
  --path /:/tmp/base-app \
  --dry-run \
  --registry-config="$REGISTRY_AUTH_FILE"

Expected result:

• --file writes the requested file to the current directory.
• --dry-run lists files that would be extracted and does not write image contents.

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