Alauda Container Platform
  • 简体中文

    • 使用 ac 管理镜像

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

    目录

    先决条件Registry 模式命令组发现并登录 Registry管理 ImageStream查询 Image 和 ImageStream删除 Image 引用直接处理 OCI Image

    先决条件

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

    Registry 模式

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

    模式后端用途
    modernimage.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_FILEac registry login 写入的本地身份验证文件路径；将其与 --registry-config 一起传递给直接镜像命令。

    命令组

    工作流命令Registry 模式行为
    发现并登录集成 Registryac registry info、ac registry login使用当前 Registry 模式解析 Registry 主机。
    列出并删除集成 Registry 镜像ac get images、ac delete images使用选定的 Registry 模式。
    管理 ImageStreamac 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 认证文件：

    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 选择输出认证文件。

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

    管理 ImageStream

    创建空的 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 资源解析出的拉取规范，并且 rollout 成功完成。

    查询 Image 和 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 命令列出 Image：

    ac get images

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

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

    删除 Image 引用

    首选的 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

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

    直接处理 OCI Image

    显示 Registry 中的 Image 元数据：

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

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

    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"

    将一个 Image 复制到另一个标签：

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

    根据映射文件复制多个 Image：

    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"

    如果找不到输入 Image，--skip-missing 会继续执行。--filter-by-os 选择请求的平台；当目标必须保持为包含所选平台条目的多架构 manifest 列表时，将其与 --keep-manifest-list 结合使用。

    验证复制的 Image：

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

    向 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 \
  --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 对象合并到运行时 Image 配置中。--meta 选项会将 JSON 对象合并到顶层 Image 元数据中。也可以使用 --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 会推送生成的 Image，或者使用 --dry-run 打印计划执行的操作。
    • --keep-manifest-list 会保留多架构索引，同时将追加操作应用于匹配的平台 Image。

    从 Image 中提取文件，无需本地容器运行时：

    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 会列出将要提取的文件，并且不会写入 Image 内容。

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