Alauda Container Platform
  • 简体中文

    • Registry v2：使用 ac 管理镜像

    使用最新的 ac 镜像命令来操作 Registry v2 和 Image API。Registry v2 由 modern registry mode 选中，并为 集群提供 Image 和 ImageStream 工作流。对于仍在使用旧版 Registry 的环境，兼容性入口仍然可用。

    目录

    Registry ModeCommand Groups发现并登录到 Registry管理 ImageStreams查询 Images 和 ImageStreams删除 Image References直接处理 OCI Images

    Registry Mode

    ac 会根据当前集群的 registry mode 选择镜像后端：

    模式后端适用场景
    modernRegistry v2 image.alauda.io/v1 Image 和 ImageStream API，以及 registry service。Registry v2 管理。
    legacy旧版 Registry 的 catalog、tag 和 manifest metadata。仍在使用旧版 Registry 的环境。
    auto自动检测。发现。若同时检测到两个代际版本，请在进行镜像管理前显式设置该模式。

    检查并设置模式：

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

    在管理 ImageStreams、导入镜像、给镜像打标签，或通过 Registry v2 Image API graph 查看 Image API 用法之前，请先使用 modern mode。

    Command Groups

    工作流命令Registry mode 行为
    发现并登录到集成的 Registryac registry info, ac registry login使用当前 registry mode 解析 Registry host。
    列出并删除集成的 Registry 镜像ac get images, ac delete images与模式感知兼容的命令。
    管理 ImageStreamsac create imagestream, ac create imagestreamtag, ac import-image, ac tag, ac set image-lookup需要 modern mode。
    查询 Image API 资源ac get imagestreams, ac get imagestreamtags, ac get imagestreamimages需要 Registry v2 Image API。
    直接处理 OCI 镜像ac image info, ac image mirror, ac image append, ac image extract直接与 registry 通信。仅在受限测试或 private-CA 场景中使用 --insecure。

    管理用途报告、清理和信任验证记录在 管理 Registry v2 访问和清理 中。

    发现并登录到 Registry

    打印当前 registry mode 选择的 Registry host：

    ac registry info

    打印内部 host：

    ac registry info --internal

    检查 Registry /v2/ endpoint 是否可达：

    ac registry info --check

    将 Registry 凭证写入默认的 Docker 配置文件：

    ac registry login

    将凭证写入临时或 CI auth file：

    export DOCKER_CONFIG=/tmp/registry-auth

ac registry login \
  --registry registry.example.com \
  --to "$DOCKER_CONFIG/config.json"

    当 registry endpoint 无法从当前机器访问，但仍需要写入 credential file 时，请使用 --skip-check。仅当 endpoint 使用 HTTP 或使用客户端不信任的证书时，才使用 --insecure。

    管理 ImageStreams

    创建一个空的 ImageStream：

    ac create imagestream demo

    创建一个启用了本地镜像查找的 ImageStream：

    ac create imagestream demo --lookup-local

    从外部镜像创建一个 ImageStreamTag：

    ac create imagestreamtag demo:latest \
  --from-image=quay.io/example/demo:1.0

    将外部镜像导入到 ImageStreamTag 中。若不使用 --confirm，命令只会预览导入。添加 --confirm 以持久化该 tag：

    ac import-image demo:latest \
  --from=quay.io/example/demo:1.0 \
  --confirm

    常见导入选项：

    选项作用
    --scheduled周期性导入外部镜像或 repository。
    --insecure从未完全通过受信任 HTTPS 保护的 registry 导入。
    --reference-policy=source|local控制 workload 使用源引用还是本地 Registry 引用。
    --import-mode=Legacy|PreserveOriginal选择导入 manifest lists 和相关镜像 metadata 的方式。
    -o json|yaml以结构化格式打印导入结果。

    将外部 container image 打入一个 ImageStreamTag：

    ac tag --source=docker quay.io/example/demo:1.0 demo:latest

    将一个 ImageStreamTag 下的当前镜像复制到另一个 ImageStreamTag：

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

    删除一个 tag：

    ac tag -d demo:old

    为某个 ImageStream 启用本地镜像查找：

    ac set image-lookup demo

    禁用本地镜像查找：

    ac set image-lookup demo --enabled=false

    列出本地查找状态：

    ac set image-lookup --list

    查询 Images 和 ImageStreams

    列出 ImageStreams：

    ac get imagestreams -A

    显示一个 ImageStream：

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

    显示某个 tag 的当前 digest 和 tag 历史：

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

    按 digest 显示 ImageStreamImage metadata：

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

    通过集成的 Registry 兼容性入口列出 images：

    ac get images

    在 modern mode 下，ac get images 会列出集群范围的 Image resources，并显示 NAME 和 IMAGE REFERENCE 列。在 legacy mode 下，它会保留旧版 Registry catalog 输出，并列出 repository tags。

    使用结构化输出：

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

    为兼容性保留了仅适用于旧版的选项：

    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

    删除 Image References

    Registry v2 的首选工作流是删除 ImageStream tags：

    ac tag -d demo:old

    兼容性命令 ac delete images 也会遵循所选的 registry mode。除非设置了 --confirm，否则它只是一次 dry run：

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

    使用重复的 --repo 标志删除多个 tag references：

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

    删除 image references 并不一定会立即释放 blob storage。若需要回收存储，请单独运行 image pruning 和 registry garbage collection。

    直接处理 OCI Images

    显示某个 registry 中的 image metadata：

    ac image info registry.example.com/team-a/demo:latest

    从多架构镜像中选择一个 platform：

    ac image info docker.io/library/busybox:latest \
  --filter-by-os=linux/arm64

    显示 manifest list 条目：

    ac image info registry.example.com/team-a/demo:latest \
  --show-multiarch

    将一个镜像复制到另一个 tag：

    ac image mirror \
  registry.example.com/team-a/demo:latest \
  registry.example.com/team-a/demo:stable

    从映射文件复制多个镜像：

    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

    向镜像添加 layer 或 metadata 并推送结果：

    ac image append \
  --from docker.io/library/busybox:latest \
  --to registry.example.com/team-a/busybox:patched \
  layer.tar.gz

    预览 append 操作：

    ac image append \
  --from docker.io/library/busybox:latest \
  --to registry.example.com/team-a/busybox:patched \
  layer.tar.gz \
  --dry-run

    在没有本地 container runtime 的情况下从镜像中提取文件：

    ac image extract docker.io/library/busybox:latest \
  --path /:/tmp/busybox \
  --confirm

    仅在测试 registry、HTTP endpoint 或客户端不信任的私有证书场景中，才在 ac image 命令上使用 --insecure。