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.
TOC
PrerequisitesRegistry ModeDiscover and Log In to the RegistryManage ImageStreamsQuery Images and ImageStreamsDelete Image ReferencesWork with OCI Images DirectlyInspect an ImageMirror ImagesAppend Layers or MetadataExtract FilesPrerequisites
- The
acCLI is installed and authenticated to the target cluster. - The Registry and the
image.alauda.io/v1Image API are available. - The example image namespace
team-aexists. The cross-namespace copy also requiresteam-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 imagecommands 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.
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:
Check and set the mode:
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:
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:
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:
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:
Verify the stream:
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:
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:
Persist the import with the same source and namespace:
Verify the persisted ImageStreamTag:
Expected result: the ImageStreamTag contains the imported image reference and digest.
Common import options:
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:
Tag an external image into an ImageStreamTag:
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:
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:
Use --alias to link tags inside the same ImageStream:
Verify the alias relationship:
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:
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:
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:
The --insecure option applies to external image sources and is only needed for controlled
insecure-source tests.
Enable local image lookup for one ImageStream:
Disable local image lookup:
List local lookup state:
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:
Set a workload image from an ImageStreamImage digest:
Verify the workload update:
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:
--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:
Show an ImageStream:
Show the current digest and tag history for a tag:
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:
List repository and tag references through the compatibility command:
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:
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.
To request native Image API text output, set AC_REGISTRY_COMPAT_OUTPUT=native and omit -o:
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:
Delete Image References
Prefer deleting ImageStream tags:
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:
Delete those same references:
Verify that both ImageStreamTag references are absent:
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.
Inspect an Image
Show image metadata from a registry:
Select one platform from a multi-architecture image:
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:
Copy the image with the same options:
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:
Prepare a mapping file to copy multiple existing source images:
Preview the mappings and options:
Copy using the same mappings and options:
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:
Append Layers or Metadata
Prepare layer.tar.gz from the files to add or replace. For example, create it from a 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:
Push the result with the same source, layer, and platform:
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:
To remove history from every platform while preserving the image index:
Expected result:
ac image appendpushes the resulting image, or prints the planned action with--dry-run.--keep-manifest-listpreserves 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:
Preview extraction of one platform into that directory:
Extract with the same source, destination, and platform:
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:
Run this example only when /etc/app/config.yaml exists in the selected source image:
Verify the extraction:
Expected result:
- The full filesystem is written under
EXTRACT_DIRfor the--pathexample. - The selected file is written as
config.yamlunderFILE_EXTRACT_DIRfor the--fileexample.
Use --insecure on ac image commands only for test registries, HTTP endpoints, or private
certificates that are not trusted by the client.