使用 ac 管理镜像

使用 ac 镜像命令处理 Alauda Container Platform Registry 以及 Image API。ACP 4.4 中的 Alauda Container Platform Registry 使用 modern Registry 模式，并为集群提供 Image 和 ImageStream 工作流。

前提条件

已安装 ac CLI，并已通过身份验证连接到目标集群。
Registry 和 image.alauda.io/v1 Image API 可用。
你拥有命令所使用的 ImageStream、Image 和工作负载资源所需的权限。

Registry 模式

ac 根据当前集群的 Registry 模式选择镜像后端：

模式	后端	用途
`modern`	`image.alauda.io/v1` Image 和 ImageStream API 以及 Registry 服务。	ACP 4.4 中的 Registry 管理。
`auto`	自动检测。	发现。在执行 ImageStream 或 Image API 操作前设置 `modern`，前提是命令需要显式模式。

检查并设置模式：

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

在管理 ImageStream、导入镜像、为镜像添加标签，或通过 Image API 图查看 Image API 使用情况之前，使用 modern 模式。

占位符	描述
`<digest>`	`ac get images` 返回的镜像摘要或 ImageStream 标签查询结果。包含 `sha256:` 前缀。
`REGISTRY_AUTH_FILE`	`ac registry login` 写入的本地身份验证文件路径；使用 `--registry-config` 将其传递给直接镜像命令。

命令组

工作流	命令	Registry 模式行为
发现并登录集成 Registry	`ac registry info`、`ac registry login`	使用当前 Registry 模式解析 Registry 主机。
列出并删除集成 Registry 镜像	`ac get images`、`ac delete images`	使用选定的 Registry 模式。
管理 ImageStream	`ac create imagestream`、`ac create imagestreamtag`、`ac import-image`、`ac tag`、`ac set image-lookup`	需要 `modern` 模式。
查询 Image API 资源	`ac get imagestreams`、`ac get imagestreamtags`、`ac get imagestreamimages`	需要 Image API。
直接使用 OCI 镜像	`ac image info`、`ac image mirror`、`ac image append`、`ac image extract`	直接与 Registry 通信。仅在限定范围的测试或私有 CA 场景中使用 `--insecure`。

管理使用情况报告、清理和信任验证，请参阅管理访问权限和清理。

发现并登录 Registry

打印当前 Registry 模式选定的 Registry 主机：

ac registry info

打印内部主机：

ac registry info --internal

打印从配置的外部路由发现的公共主机：

ac registry info --public

检查 Registry /v2/ 端点是否可访问：

ac registry info --check

将 Registry 凭证写入默认本地凭证文件：

ac registry login

将凭证写入临时或 CI auth 文件：

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

预期结果：

Registry 凭证将写入 /tmp/registry-auth/config.json，并可通过 REGISTRY_AUTH_FILE 供后续直接镜像命令使用。

--to 和 --registry-config（或 -a）选择 ac registry login 的输出 auth 文件。

当 Registry 端点无法从当前计算机访问，但仍需要写入凭证文件时，使用 --skip-check。仅当端点使用 HTTP 或使用客户端不信任的证书时，才使用 --insecure。

管理 ImageStreams

创建空的 ImageStream：

ac create imagestream demo

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

ac create imagestream demo --lookup-local

从外部镜像创建 ImageStreamTag：

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

将外部镜像导入 ImageStreamTag。如果不使用 --confirm，该命令会预览导入结果。添加 --confirm 以持久化该标签：

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

验证已持久化的 ImageStreamTag：

ac get imagestreamtags demo:latest -o yaml

预期结果：

ImageStreamTag 包含已导入的镜像引用和摘要。

常用导入选项：

选项	用途
`--scheduled`	定期导入外部镜像或仓库。
`--insecure`	从未完全由受信任 HTTPS 保护的 Registry 导入。
`--reference-policy=source\|local`	控制工作负载使用源引用还是本地 Registry 引用。
`--import-mode=PreserveOriginal`	当服务器支持此导入模式时，保留原始源引用。
`-o json\|yaml`	以结构化格式打印导入结果。

将外部镜像标记到 ImageStreamTag：

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

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

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

使用标签选项控制跟踪和导入行为：

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 要求源和目标位于同一个 ImageStream 中。--scheduled 和 --insecure 选项适用于外部镜像源。

删除标签：

ac tag -d demo:old

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

ac set image-lookup demo

禁用本地镜像查找：

ac set image-lookup demo --enabled=false

列出本地查找状态：

ac set image-lookup --list

根据当前 ImageStreamTag 的拉取规范设置工作负载镜像：

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

根据 ImageStreamImage 摘要设置工作负载镜像：

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

验证工作负载更新：

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"}'

预期结果：

Deployment 使用从 ImageStream 资源解析出的拉取规范，并且滚动部署成功完成。

查询镜像和 ImageStream

列出 ImageStream：

ac get imagestreams -A

显示 ImageStream：

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

显示某个标签的当前摘要和标签历史记录：

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

按摘要显示 ImageStreamImage 元数据：

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

通过集成的 Registry 命令列出镜像：

ac get images

在 modern 模式下，ac get images 会列出集群范围的 Image 资源，并显示 NAME 和 IMAGE REFERENCE 列。使用结构化输出：

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

删除镜像引用

首选的 Registry 工作流是删除 ImageStream 标签：

ac tag -d demo:old

ac delete images 命令遵循所选的 Registry 模式。除非设置了 --confirm，否则该命令以试运行方式执行：

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

使用多个 --repo 标志删除多个标签引用：

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

删除镜像引用不一定会立即释放 blob 存储空间。需要回收存储空间时，请分别运行镜像清理和 Registry 垃圾回收。

直接处理 OCI 镜像

显示 Registry 中的镜像元数据：

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

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

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

显示 manifest 列表条目：

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

将一个镜像复制到另一个标签：

ac image mirror \
  registry.example.com/team-a/demo:latest \
  registry.example.com/team-a/demo:stable \
  --registry-config="$REGISTRY_AUTH_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 会继续执行。--filter-by-os 选择请求的平台；当目标必须保持为包含所选平台条目的多架构 manifest 列表时，将其与 --keep-manifest-list 结合使用。

验证复制的镜像：

ac image info registry.example.com/team-a/demo:stable \
  --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:patched \
  layer.tar.gz \
  --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:patched \
  layer.tar.gz \
  --dry-run \
  --registry-config="$REGISTRY_AUTH_FILE"

--image 选项会将 JSON 对象合并到运行时镜像配置中。--meta 选项会将 JSON 对象合并到顶层镜像元数据中。也可以使用 --drop-history 或 --created-at，而不添加层：

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"

预期结果：

ac image append 会推送生成的镜像，或者使用 --dry-run 输出计划执行的操作。
--keep-manifest-list 会保留多架构索引，同时将追加操作应用于匹配的平台镜像。

在没有本地容器运行时的情况下从镜像中提取文件：

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

将选定的文件提取到当前目录：

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

预览提取操作而不写入文件：

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

预期结果：

--file 会将请求的文件写入当前目录。
--dry-run 会列出将要提取的文件，但不会写入镜像内容。

仅在测试 Registry、HTTP 端点或客户端不信任的私有证书中，对 ac image 命令使用 --insecure。

#使用 ac 管理镜像

#目录

#前提条件

#Registry 模式

#命令组

#发现并登录 Registry

#管理 ImageStreams

#查询镜像和 ImageStream

#删除镜像引用

#直接处理 OCI 镜像

使用 ac 管理镜像

目录

前提条件

Registry 模式

命令组

发现并登录 Registry

管理 ImageStreams

查询镜像和 ImageStream

删除镜像引用

直接处理 OCI 镜像