Managing Images with ac

Use the ac image commands to work with Alauda Container Platform Registry and the Image API. In ACP 4.5, the Registry uses the modern registry mode and supports ImageDigest 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.
  • The example image namespace team-a exists. The cross-namespace copy also requires team-b.
  • A namespace administrator has granted the required image permissions. Image API operations also require permission to read or change the resources used by each command.
  • Registry hosts used by direct ac image commands are reachable from your machine, and the client trusts their TLS certificates.

Replace the example values before running commands on your developer machine or in a CI environment. Each task is independent unless it explicitly continues a preceding task.

ValueDescription
team-aNamespace that owns the example images and the my-app Deployment.
team-bDestination namespace for the cross-namespace copy.
registry.example.comVerified Registry hostname, including a port when required, without a scheme or path.
source.example.com/source-team/source-app:1.0Existing source image that you can read. Replace other source image references in the examples with images you can access.
source-registry.example.com, external-registry.example.comSource hosts for the mirror, append, and extract examples. Replace them and their repository paths with accessible source images.
<digest>The 64-character hexadecimal suffix of a SHA-256 image digest. Omit sha256: when replacing this placeholder; the commands already include it.
REGISTRY_AUTH_FILEAbsolute path to the local auth file written by ac registry login.
layer.tar.gzExisting local tar archive of the filesystem changes to append. Archive paths must be relative to the image filesystem root.

Before setting a workload image, the my-app Deployment must exist in team-a with a container named app. Before querying, copying, or deleting a tag, that source tag must exist in the stated namespace.

Registry Mode

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

ModeBackendUse it for
modernimage.alauda.io/v1 ImageDigest and ImageStream API plus the Registry service.Registry management in ACP 4.5.
autoAutomatic detection.Discovery. If detection is ambiguous, set modern explicitly before ImageStream or Image API operations.

Check and set the mode:

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

Use modern mode before managing ImageStreams, importing images, or tagging images. The mode is stored in the kubeconfig cluster entry used by the current context. Every context that points to the same cluster shares this setting. The AC_IMAGE_REGISTRY_MODE environment variable can override it for a command invocation.

The Operator normally binds Registry operand resources to cpaas-system and records that binding on Config/cluster. If the binding cannot be read, the CLI falls back to image-registry-system for modern discovery. Use the recorded Config/cluster annotation or an explicit --registry-url as the authoritative source, especially for confirmed storage cleanup and custom installations.

For administrative usage reporting and cleanup, see Managing access and cleanup. For stored signature claims, see Check recorded signature identity.

Discover and Log In to the Registry

For direct ac image commands, ask your Registry administrator for a verified internal or external endpoint. See Exposing the Registry for endpoint verification. Use an endpoint reachable from your machine and complete Authenticate an external OCI client. That procedure selects a verified host, writes REGISTRY_AUTH_FILE, and verifies image access.

Optionally, print the Registry host selected by the current registry mode:

ac registry info

Add --internal or --public to select the internal or public host. --public requires a configured public hostname.

When the discovered host matches the endpoint supplied by your administrator, check its /v2/ endpoint:

ac registry info --check

The check uses HTTPS and prefers the public host, falling back to the internal host. It does not accept an endpoint override or an insecure-connection flag. A successful check confirms that the endpoint is reachable. Image permissions need separate verification. If discovery is unavailable or reports a different host, use the administrator-provided endpoint explicitly for login. An internal Service address requires network and DNS access to the cluster.

For an HTTP endpoint used only in controlled testing, check it separately with curl installed:

curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
  http://<test-registry-host>/v2/

Replace <test-registry-host> with the HTTP test hostname and port. A 200 response or a 401 authentication challenge confirms that the endpoint is reachable. For normal use, have a Registry administrator configure a secure external host.

Manage ImageStreams

Create an empty ImageStream in team-a:

ac create imagestream demo -n team-a

Verify the stream:

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

Expected result: ImageStream/demo exists in team-a.

Add --lookup-local when creating the stream to enable local image lookup. To change an existing stream, use ac set image-lookup as shown below.

For imports from a private source registry, ask a namespace administrator to prepare private image imports with source registry credentials in the destination namespace (team-a here). The Image API server reads those namespace credentials and must be able to reach the source registry. Direct image commands use local credentials written by ac registry login or selected with REGISTRY_AUTH_FILE. Server-side imports do not receive those local credentials.

Create a new ImageStreamTag from an external image:

ac create imagestreamtag demo:latest \
  --from-image=source.example.com/source-team/source-app:1.0 \
  -n team-a

Preview the resource locally with --dry-run=client. Server dry-run is rejected for this compound tag operation before metadata changes are made.

Preview an import before creating or refreshing a tag. The preview contacts the source registry without persisting the ImageStream changes:

ac import-image demo:latest \
  --from=source.example.com/source-team/source-app:1.0 \
  -n team-a

Persist the import with the same source and namespace:

ac import-image demo:latest \
  --from=source.example.com/source-team/source-app:1.0 \
  -n team-a \
  --confirm

Verify the persisted ImageStreamTag:

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

Expected result: the ImageStreamTag contains the imported image reference and digest.

Common import options:

OptionPurpose
--insecureImport from a registry that is not fully secured by trusted HTTPS.
--reference-policy=source|localSelect the source or local Registry pull reference returned when resolving an imported tag.
--import-mode=PreserveOriginalPreserve the source multi-architecture manifest list or image index and import its child manifests.
-o json|yamlPrint import results in a structured format.

Import failures return a nonzero exit status in every output format, including JSON and YAML. The command renders the result before exiting. Automation can inspect the returned status fields for details and use the process exit status to detect failure.

Importing records metadata without copying image layers immediately. With source reference policy, clients pull from the source registry and need access to it. With local policy, clients use the integrated Registry. It can fetch uncached content from the source and needs upstream connectivity and source credentials in the ImageStream namespace. To publish a local copy, use image mirroring.

The default import mode, Legacy, selects one platform from a multi-architecture source, preferring the API server's platform. Use PreserveOriginal when consumers need the original image index.

ACP 4.5 performs a one-time import. Periodic imports are not supported; ac import-image, ac tag, and ac create imagestreamtag reject --scheduled=true. To refresh an existing tag from its external source, run a confirmed import and verify the persisted image reference and digest:

ac import-image demo:latest \
  --from=source.example.com/source-team/source-app:1.0 \
  -n team-a \
  --confirm
ac get imagestreamtags demo:latest -n team-a -o yaml

Tag an external image into an ImageStreamTag:

ac tag source.example.com/source-team/source-app:1.0 demo:latest -n team-a

To pin an external manifest or image index by digest, replace <digest> with its hash from the source registry. Use an import to create the destination tag and preserve the original index when the source contains multiple platforms:

ac import-image demo:fixed \
  --from='source.example.com/source-team/source-app@sha256:<digest>' \
  --import-mode=PreserveOriginal \
  -n team-a \
  --confirm
ac get imagestreamtags demo:fixed -n team-a -o yaml

Expected result: the destination tag resolves to the specified source digest.

Copy the image currently referenced by one ImageStreamTag to another. The source team-a/demo:stable must already resolve to an image. You need source ImageStream read and image pull permissions in team-a, and tag write permissions in team-b:

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

Use --alias to link tags inside the same ImageStream:

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

Verify the alias relationship:

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

Expected result: the destination tag records the source tag relationship and resolves to the source image.

--alias initially copies the source image and retains a reference to the source tag. A Registry push, import, or retag that changes the source also updates its direct aliases in the same ImageStream. Alias chains and cycles are not supported. Use a tag copy without --alias or an image digest when you need a fixed image.

Use --reference with an external registry image to record its pull specification without importing the image:

ac tag --reference source.example.com/source-team/source-app:1.0 demo:latest -n team-a

For an ImageStreamTag source without --alias, ac tag resolves the tag to its current digest. Adding --reference preserves the source pull specification, so pulling the destination tag may require access to the source repository:

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

With --alias, the current source pull specification is copied regardless of --reference.

To preserve a multi-architecture external source and use the local Registry pull reference:

ac tag source.example.com/source-team/source-app:latest demo:latest \
  --reference-policy=local \
  --import-mode=PreserveOriginal \
  -n team-a

The --insecure option applies to external image sources and is only needed for controlled insecure-source tests.

Enable local image lookup for one ImageStream:

ac set image-lookup demo -n team-a

Disable local image lookup:

ac set image-lookup demo --enabled=false -n team-a

List local lookup state:

ac set image-lookup --list -n team-a

These commands change or display ImageStream.spec.lookupPolicy.local. This setting does not rewrite workload manifests or continuously update running workloads. Resolve an ImageStream reference and update the workload explicitly with the following commands. Repeat the update to deploy a newer tag revision.

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

ac get imagestreams, ac get imagestreamtags, and ac get imagestreamimages read the Image API. ac get images is a compatibility command: in modern mode it normally reads the Registry catalog over HTTPS. Its endpoint is selected from the host recorded in Config/cluster status, a configured spec.routes[] hostname, or the internal Service address. The client must be able to reach that endpoint, so from outside the cluster pass the external Ingress host explicitly:

ac get images -n team-a --registry-url=https://registry.example.com

--registry-url replaces the Registry endpoint. Namespace lookup and authorization still use the Kubernetes API. Use the ImageStream queries below when you need Image API access without Registry connectivity.

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. Your account needs get permission on imagestreams and imagestreamimages in team-a; this query does not require cluster-scoped ImageDigest access:

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

List repository and tag references through the compatibility command:

ac get images -n team-a

In modern mode, ac get images keeps the repository and tag output used by existing scripts. Without -n, it uses the current namespace; -A requests authorized namespaces. Structured output uses the same repository and tag view:

ac get images -n team-a -o yaml
ac get images -n team-a -o json

To include digest and creation time from Registry manifest metadata, use -o wide. It requires the same reachable endpoint, which must also be trusted. When discovery cannot read Config/cluster and verifies only the internal Service, the command fails with modern registry endpoint is not trusted; pass --registry-url for wide metadata.

ac get images -n team-a -o wide

To request native Image API text output, set AC_REGISTRY_COMPAT_OUTPUT=native and omit -o:

AC_REGISTRY_COMPAT_OUTPUT=native ac get images -n team-a

The native output uses NAME and IMAGE REFERENCE columns for namespace-scoped tag records. Without a trusted endpoint, the native request retains compatibility output. Use the explicit ImageStream queries above for Image API access in that case. To inspect cluster-scoped image metadata, query ImageDigest objects with the required cluster-scoped read permission:

ac get imagedigests.image.alauda.io -o yaml

Delete Image References

Prefer deleting ImageStream tags:

ac tag -d demo:old -n team-a

The ac delete images command follows the selected registry mode. In modern mode it removes the specified ImageStreamTag references with a server-side consistency check. Without --confirm, it runs as a preview.

In each target namespace, the command requires list and get on imagestreams, and get and delete on imagestreamtags in the image.alauda.io API group. The system:image-deleter role supplies only the delete permission. Ask a namespace administrator to grant the additional reads before using this command.

Use one --repo flag per existing tag reference. Preview the deletion:

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

Delete those same references:

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

Verify that both ImageStreamTag references are absent:

for tag in demo:old api:canary; do
  result="$(kubectl get imagestreamtags.image.alauda.io "$tag" -n team-a \
    --ignore-not-found -o name)" || {
    echo "Could not verify ImageStreamTag team-a/$tag because the API request failed." >&2
    exit 1
  }
  if [ -n "$result" ]; then
    echo "ImageStreamTag team-a/$tag still exists" >&2
    exit 1
  fi
done
echo 'Deleted ImageStreamTags are no longer returned.'

Expected result: the loop completes successfully and prints the confirmation message. A missing ImageStreamTag is expected after deletion.

Storage reclamation is a separate Registry cleanup task and may not happen immediately after deleting image references. Ask a Registry administrator to prune images and reclaim storage when needed.

Use these tag commands when removing one tag. An OCI client's manifest deletion by digest can remove multiple tags that share the digest in the same repository; see Namespace image permissions.

Work with OCI Images Directly

These commands read and write registries directly. Credential lookup uses the explicit --registry-config/-a path first, then REGISTRY_AUTH_FILE, then the client's default auth file. For private source images, the selected file must also contain credentials for the source host; logging in to the destination does not authenticate another registry.

Set REGISTRY_AUTH_FILE to the auth file created during login, or pass --registry-config=/absolute/path/to/config.json on every command. Keep that variable in the same shell for the examples that follow.

export REGISTRY_AUTH_FILE='/absolute/path/to/config.json'
test -r "$REGISTRY_AUTH_FILE" || {
  echo "Registry auth file is not readable." >&2
  exit 1
}

Inspect an Image

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"

Add --show-multiarch without --filter-by-os to list manifest list or image index entries.

Mirror Images

Preview copying an existing image to another tag while preserving all platforms:

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

Copy the image with the same options:

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

Without --keep-manifest-list or an explicit --filter-by-os, mirror selects the CLI machine's OS and architecture. This can discard other platforms or fail when the source has no matching platform, such as a Linux-only image copied from a macOS machine.

Verify the new tag:

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

Prepare a mapping file to copy multiple existing source images:

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

Preview the mappings and options:

ac image mirror \
  -f mirror-map.txt \
  --continue-on-error \
  --keep-manifest-list \
  --max-per-registry=4 \
  --skip-missing \
  --filter-by-os=linux/amd64 \
  --dry-run \
  --registry-config="$REGISTRY_AUTH_FILE"

Copy using the same mappings and options:

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"

The preview lists planned mappings without checking remote images or permissions. --skip-missing skips missing sources, so a successful copy command can leave some destinations absent. With --continue-on-error, other failures are reported after the remaining mappings are attempted.

--filter-by-os selects the requested platform. Combine it with --keep-manifest-list to retain an image index containing only the selected platform entries.

Verify both mapped destinations:

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

Append Layers or Metadata

Prepare layer.tar.gz from the files to add or replace. For example, create it from a directory:

tar -czf layer.tar.gz -C '<layer-directory>' .

Replace <layer-directory> with the local directory containing those filesystem changes. Keep the output archive outside that directory.

Preview appending the layer to the linux/amd64 image:

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

Push the result with the same source, layer, and platform:

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

Select a platform supported by your base image and target workloads. Without an explicit platform or --keep-manifest-list, append uses the CLI machine's OS and architecture. Use --keep-manifest-list without a platform filter to apply the change to every platform in an index.

The CLI accepts --force as a compatibility flag, but the ACP 4.5 implementation rejects it. Do not use it to force layer uploads.

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. To change metadata 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='{"Labels":{"team":"team-a"}}' \
  --meta='{"author":"team-a"}' \
  --created-at=2024-01-01T00:00:00Z \
  --filter-by-os=linux/amd64 \
  --registry-config="$REGISTRY_AUTH_FILE"

To remove history from every platform while preserving the image index:

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.

Verify an appended image with ac image info <result-image> --show-multiarch --registry-config="$REGISTRY_AUTH_FILE". Replace <result-image> with the full destination reference from the append command.

Extract Files

Extract files without a local container runtime. Prepare an empty output directory:

EXTRACT_DIR="$(mktemp -d)"

Preview extraction of one platform into that directory:

ac image extract external-registry.example.com/base/base-app:latest \
  --path /:"$EXTRACT_DIR" \
  --filter-by-os=linux/amd64 \
  --dry-run \
  --registry-config="$REGISTRY_AUTH_FILE"

Extract with the same source, destination, and platform:

ac image extract external-registry.example.com/base/base-app:latest \
  --path /:"$EXTRACT_DIR" \
  --filter-by-os=linux/amd64 \
  --registry-config="$REGISTRY_AUTH_FILE"

The destination must be empty unless --confirm is set. Adding --confirm permits overwriting matching files in an existing destination. The preview lists paths without writing image contents.

For --file, the destination is the current directory. Prepare a separate empty directory:

FILE_EXTRACT_DIR="$(mktemp -d)"

Run this example only when /etc/app/config.yaml exists in the selected source image:

(
  cd "$FILE_EXTRACT_DIR" || exit 1
  ac image extract external-registry.example.com/base/base-app:latest \
    --file /etc/app/config.yaml \
    --filter-by-os=linux/amd64 \
    --registry-config="$REGISTRY_AUTH_FILE"
)

Verify the extraction:

test -f "$FILE_EXTRACT_DIR/config.yaml"

Expected result:

  • The full filesystem is written under EXTRACT_DIR for the --path example.
  • The selected file is written as config.yaml under FILE_EXTRACT_DIR for the --file example.

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