From ee80908097e9d9d123b69ed8de48331094ecbf3b Mon Sep 17 00:00:00 2001 From: huizhang Date: Mon, 20 Jul 2026 15:01:55 +0800 Subject: [PATCH 1/4] docs: document Registry v2 repository path limit --- .../configure/registry/registry_v2/registry_overview.mdx | 2 +- .../registry/registry_v2/accessing_the_registry.mdx | 8 ++++++++ .../registry/registry_v2/managing_images_with_ac.mdx | 2 ++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/en/configure/registry/registry_v2/registry_overview.mdx b/docs/en/configure/registry/registry_v2/registry_overview.mdx index 27b459c2..906f016f 100644 --- a/docs/en/configure/registry/registry_v2/registry_overview.mdx +++ b/docs/en/configure/registry/registry_v2/registry_overview.mdx @@ -40,7 +40,7 @@ The registry integrates with authentication and Kub | Term | Meaning | | --- | --- | -| Image repository | A namespace-scoped collection of image tags and digests, addressed as `/:`. | +| Image repository | A namespace-scoped collection of image tags and digests, addressed as `/:`. The repository name is a single path segment; nested paths such as `//:` are not supported. | | ImageStream | Image API resource that records tag specifications and tag history for a repository. | | Image | Cluster-scoped image metadata for a digest. | | ImagePruner | Singleton custom resource that configures scheduled prune jobs. | diff --git a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx index ad3d3139..68e6bd2c 100644 --- a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx +++ b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx @@ -145,6 +145,14 @@ If the registry uses a private CA, configure client trust before push and pull o ## Push and Pull Images +Registry v2 image repositories use exactly two path segments after the registry host: + +```text +//: +``` + +Repository paths with a third segment after the registry host are not supported. For example, use `registry.example.com/team-a/my-app:v1`, not `registry.example.com/team-a/platform/my-app:v1`. To group related images, use a single image name such as `platform-my-app`, or use a separate namespace. + Tag and push an image: ```bash diff --git a/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx b/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx index 3f3e7a7a..aeb281b8 100644 --- a/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx +++ b/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx @@ -80,6 +80,8 @@ Use `--skip-check` when the registry endpoint is not reachable from the current ## Manage ImageStreams +Registry v2 maps each image repository to one namespace and one ImageStream name. Use `/:` when referencing an image in the integrated Registry. Repository paths with an additional path segment, such as `//:`, are not supported. Use a single ImageStream name such as `group-imagestream`, or use a separate namespace for grouping. + Create an empty ImageStream: ```bash From 7e728ca77d2223486a4ab3f102caa4a65b5c3d45 Mon Sep 17 00:00:00 2001 From: huizhang Date: Mon, 20 Jul 2026 16:01:36 +0800 Subject: [PATCH 2/4] docs: refine Registry v2 path guidance --- .../registry/registry_v2/accessing_the_registry.mdx | 6 +++--- .../registry/registry_v2/managing_images_with_ac.mdx | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx index 68e6bd2c..8126ac79 100644 --- a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx +++ b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx @@ -131,7 +131,7 @@ ac registry login \ --registry registry.example.com ``` -To write credentials to a specific Docker-compatible auth file, set `DOCKER_CONFIG` or use `--to`: +To write credentials to a specific OCI registry auth file, set `DOCKER_CONFIG` or use `--to`: ```bash export DOCKER_CONFIG=/tmp/registry-auth @@ -148,10 +148,10 @@ If the registry uses a private CA, configure client trust before push and pull o Registry v2 image repositories use exactly two path segments after the registry host: ```text -//: +//: ``` -Repository paths with a third segment after the registry host are not supported. For example, use `registry.example.com/team-a/my-app:v1`, not `registry.example.com/team-a/platform/my-app:v1`. To group related images, use a single image name such as `platform-my-app`, or use a separate namespace. +Repository paths with a third segment after the registry host are not supported. For example, use `registry.example.com/team-a/my-app:v1`, not `registry.example.com/team-a/platform/my-app:v1`. To group related images, use a single repository name such as `platform-my-app`, or use a separate namespace when your namespace model allows it. Tag and push an image: diff --git a/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx b/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx index aeb281b8..55a8b704 100644 --- a/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx +++ b/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx @@ -80,7 +80,7 @@ Use `--skip-check` when the registry endpoint is not reachable from the current ## Manage ImageStreams -Registry v2 maps each image repository to one namespace and one ImageStream name. Use `/:` when referencing an image in the integrated Registry. Repository paths with an additional path segment, such as `//:`, are not supported. Use a single ImageStream name such as `group-imagestream`, or use a separate namespace for grouping. +Registry v2 maps each image repository to one namespace and one ImageStream name. For `ac` ImageStream references, use `/:`. For OCI image references, use `//:`. Repository paths with an additional path segment, such as `//:`, are not supported. Use a single repository name such as `group-repository`, or use a separate namespace when your namespace model allows it. Create an empty ImageStream: @@ -98,14 +98,14 @@ Create an ImageStreamTag from an external image: ```bash ac create imagestreamtag demo:latest \ - --from-image=quay.io/example/demo:1.0 + --from-image=external-registry.example.com/example/demo:1.0 ``` Import an external image into an ImageStreamTag. Without `--confirm`, the command previews the import. Add `--confirm` to persist the tag: ```bash ac import-image demo:latest \ - --from=quay.io/example/demo:1.0 \ + --from=external-registry.example.com/example/demo:1.0 \ --confirm ``` @@ -122,7 +122,7 @@ Common import options: Tag an external container image into an ImageStreamTag: ```bash -ac tag --source=docker quay.io/example/demo:1.0 demo:latest +ac tag --source=docker external-registry.example.com/example/demo:1.0 demo:latest ``` Copy the current image behind one ImageStreamTag to another: From b0cb2fbd88d96f70277e1a0b6bd7f134fb9df6e8 Mon Sep 17 00:00:00 2001 From: huizhang Date: Mon, 20 Jul 2026 16:39:16 +0800 Subject: [PATCH 3/4] docs: remove banned registry terminology --- .../registry_v2/accessing_the_registry.mdx | 6 +++--- .../registry_v2/managing_images_with_ac.mdx | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx index 8126ac79..d1e21432 100644 --- a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx +++ b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx @@ -131,14 +131,14 @@ ac registry login \ --registry registry.example.com ``` -To write credentials to a specific OCI registry auth file, set `DOCKER_CONFIG` or use `--to`: +To write credentials to a specific OCI registry auth file, use `--to`: ```bash -export DOCKER_CONFIG=/tmp/registry-auth +mkdir -p /tmp/registry-auth ac registry login \ --registry registry.example.com \ - --to "$DOCKER_CONFIG/config.json" + --to /tmp/registry-auth/config.json ``` If the registry uses a private CA, configure client trust before push and pull operations. Use `--insecure` only for an HTTP endpoint or a non-production test certificate that the client does not trust. diff --git a/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx b/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx index 55a8b704..cdff898a 100644 --- a/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx +++ b/docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx @@ -60,7 +60,7 @@ Check that the Registry `/v2/` endpoint is reachable: ac registry info --check ``` -Write Registry credentials to the default Docker config file: +Write Registry credentials to the default local credential file: ```bash ac registry login @@ -69,11 +69,11 @@ ac registry login Write credentials to a temporary or CI auth file: ```bash -export DOCKER_CONFIG=/tmp/registry-auth +mkdir -p /tmp/registry-auth ac registry login \ --registry registry.example.com \ - --to "$DOCKER_CONFIG/config.json" + --to /tmp/registry-auth/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. @@ -122,7 +122,7 @@ Common import options: Tag an external container image into an ImageStreamTag: ```bash -ac tag --source=docker external-registry.example.com/example/demo:1.0 demo:latest +ac tag external-registry.example.com/example/demo:1.0 demo:latest ``` Copy the current image behind one ImageStreamTag to another: @@ -240,7 +240,7 @@ ac image info registry.example.com/team-a/demo:latest Select one platform from a multi-architecture image: ```bash -ac image info docker.io/library/busybox:latest \ +ac image info external-registry.example.com/library/busybox:latest \ --filter-by-os=linux/arm64 ``` @@ -283,7 +283,7 @@ Add layers or metadata to an image and push the result: ```bash ac image append \ - --from docker.io/library/busybox:latest \ + --from external-registry.example.com/library/busybox:latest \ --to registry.example.com/team-a/busybox:patched \ layer.tar.gz ``` @@ -292,7 +292,7 @@ Preview the append operation: ```bash ac image append \ - --from docker.io/library/busybox:latest \ + --from external-registry.example.com/library/busybox:latest \ --to registry.example.com/team-a/busybox:patched \ layer.tar.gz \ --dry-run @@ -301,7 +301,7 @@ ac image append \ Extract files from an image without a local container runtime: ```bash -ac image extract docker.io/library/busybox:latest \ +ac image extract external-registry.example.com/library/busybox:latest \ --path /:/tmp/busybox \ --confirm ``` From 29d15a200c57af0e4eb4c3fca0f51f40b8d205af Mon Sep 17 00:00:00 2001 From: huizhang Date: Mon, 20 Jul 2026 17:06:36 +0800 Subject: [PATCH 4/4] docs: clarify registry v2 image commands --- .../registry/how_to/common_cli_command.mdx | 13 ++++++++----- .../registry_v2/accessing_the_registry.mdx | 14 +++++++++++--- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/en/developer/registry/how_to/common_cli_command.mdx b/docs/en/developer/registry/how_to/common_cli_command.mdx index 01297dc3..852b3cf4 100644 --- a/docs/en/developer/registry/how_to/common_cli_command.mdx +++ b/docs/en/developer/registry/how_to/common_cli_command.mdx @@ -10,6 +10,9 @@ i18n: Use the `ac` CLI for platform login, namespace permission management, and Registry metadata operations. Use a standard OCI client such as `nerdctl` for image transfer operations such as push and pull. +This page documents legacy Registry CLI operations. For Registry v2, use the mode-aware Image and +ImageStream commands in [Registry v2: Managing Images with ac](../registry_v2/managing_images_with_ac.mdx). + The examples below assume: - Registry client address: `` @@ -50,8 +53,8 @@ If you run `ac` inside a Pod, Job, or CronJob: Address usage in this document: - `` is the Registry address used by OCI clients such as `nerdctl`. -- `` is the Registry API endpoint used by `ac get images` and `ac delete images`. -- In external access scenarios, `ac` should typically use an explicitly specified `--registry-url` instead of relying on the default in-cluster Registry address. +- `` is the legacy Registry API endpoint used by `ac get images` and `ac delete images` in legacy mode. +- In legacy external access scenarios, `ac` should typically use an explicitly specified `--registry-url` instead of relying on the default in-cluster Registry address. ## Authenticate to ACP @@ -111,7 +114,7 @@ nerdctl --insecure-registry login -u - ## List Images -List images from namespaces that the current user is allowed to access: +List legacy Registry images from namespaces that the current user is allowed to access: ```bash ac get images --registry-url= @@ -123,7 +126,7 @@ ac get images -n my-ns --registry-url= ac get images -o yaml --registry-url= ``` -When `ac` runs outside the cluster, explicitly specifying `--registry-url` is recommended. Otherwise, the CLI may fall back to the default in-cluster Registry address, which is often unreachable from a local workstation. +When `ac` runs outside the cluster in legacy mode, explicitly specifying `--registry-url` is recommended. Otherwise, the CLI may fall back to the default in-cluster Registry address, which is often unreachable from a local workstation. Example: @@ -170,7 +173,7 @@ nerdctl push /my-ns/my-app:latest ## Delete Images -Use `ac delete images` to remove image tags from the Registry: +Use `ac delete images` to remove image tags from the legacy Registry: ```bash # Preview the deletion result without removing anything diff --git a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx index d1e21432..a2715380 100644 --- a/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx +++ b/docs/en/developer/registry/registry_v2/accessing_the_registry.mdx @@ -199,9 +199,17 @@ Show the Image metadata for a digest: ac get imagestreamimages my-app@sha256: -n team-a -o yaml ``` -List Registry HTTP image repositories visible to the current user: +List cluster-scoped Image resources through the current `modern` registry mode: ```bash -ac get images --registry-url=https://registry.example.com -ac get images -n team-a --registry-url=https://registry.example.com +ac config set-registry-mode modern +ac get images +ac get images -o yaml +``` + +For namespace-scoped repository views, query ImageStream resources instead of passing a Registry URL override: + +```bash +ac get imagestreams -n team-a +ac get imagestreamtags my-app:v1 -n team-a -o wide ```