Alauda Container Platform
  • 简体中文

    • 常用 CLI 命令操作

    使用 ac CLI 进行平台登录、命名空间权限管理以及 Registry 元数据操作。使用标准 OCI client（例如 nerdctl）执行镜像传输操作，例如 push 和 pull。

    以下示例假定：

    • Registry client 地址：<REGISTRY_CLIENT_HOSTPORT>
    • Registry API URL：<REGISTRY_API_URL>
    • 当前命名空间：my-ns

    目录

    开始之前认证机制认证到 ACP为用户授予命名空间权限为 ServiceAccount 授予命名空间权限认证 OCI Client列出镜像拉取镜像推送镜像删除镜像

    开始之前

    在运行本文档中的命令之前，请确保：

    • 已安装 ac。
    • 如果需要 push 或 pull 镜像，已安装 nerdctl。
    • 当前环境可以访问 ACP API 端点和 Registry 地址。
    • 已登录 ACP 并选择了目标集群。
    • 当前 ACP 账户，或 Pod 或 Job 中使用的 ServiceAccount，具有所需的命名空间权限。

    典型权限要求：

    • 拉取镜像：system:image-puller
    • 推送镜像：system:image-pusher
    • 使用 ac get images 列出镜像：可访问目标命名空间
    • 使用 ac delete images 删除镜像：有权限删除目标命名空间中的镜像

    如果在 Pod、Job 或 CronJob 中运行 ac：

    • Pod 必须使用有效的 serviceAccountName。
    • 已挂载的 ServiceAccount token 必须可用。
    • 该 ServiceAccount 必须具有访问目标集群以及 Registry 相关 API 的权限。

    认证机制

    ac 和 nerdctl 使用不同的认证路径：

    • ac 使用当前 ACP 登录会话访问 Registry 相关 API。
    • 如果 ac 在 Pod 内运行且没有可用的 ACP 会话，则可以回退使用已挂载的 ServiceAccount token。
    • nerdctl 直接对 Registry 进行认证，通常使用已拥有目标命名空间访问权限的同一 ACP 账户凭据。

    本文档中的地址使用方式：

    • <REGISTRY_CLIENT_HOSTPORT> 是 OCI client（例如 nerdctl）使用的 Registry 地址。
    • <REGISTRY_API_URL> 是 ac get images 和 ac delete images 使用的 Registry API 端点。
    • 在外部访问场景中，ac 通常应显式指定 --registry-url，而不是依赖默认的集群内 Registry 地址。

    认证到 ACP

    在使用 ac 中与 Registry 相关的命令之前，请先登录并选择目标集群：

    ac login <acp-url>
ac config get-clusters
ac config use-cluster <cluster-name>

    登录后，ac 可以使用当前会话访问 Registry 相关 API，例如 ac get images 和 ac delete images。

    为用户授予命名空间权限

    为用户添加命名空间拉取权限。

    ac create rolebinding <binding-name> --clusterrole=system:image-puller --user=<username> -n <namespace>

    为用户添加命名空间推送权限。

    ac create rolebinding <binding-name> --clusterrole=system:image-pusher --user=<username> -n <namespace>

    为 ServiceAccount 授予命名空间权限

    为 ServiceAccount 添加命名空间拉取权限。

    ac create rolebinding <binding-name> --clusterrole=system:image-puller --serviceaccount=<namespace>:<serviceaccount-name> -n <namespace>

    为 ServiceAccount 添加命名空间推送权限。

    ac create rolebinding <binding-name> --clusterrole=system:image-pusher --serviceaccount=<namespace>:<serviceaccount-name> -n <namespace>

    认证 OCI Client

    对于镜像 push 和 pull，请使用拥有目标命名空间访问权限的同一 ACP 账户凭据：

    nerdctl login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>

    如果 Registry 使用自签名证书或纯 HTTP，请添加全局标志 --insecure-registry。

    示例：

    nerdctl --insecure-registry login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>

    列出镜像

    列出当前用户有权访问的命名空间中的镜像：

    ac get images --registry-url=<REGISTRY_API_URL>

# List images from a specific namespace
ac get images -n my-ns --registry-url=<REGISTRY_API_URL>

# Use structured output
ac get images -o yaml --registry-url=<REGISTRY_API_URL>

    当 ac 在集群外运行时，建议显式指定 --registry-url。否则，CLI 可能会回退到默认的集群内 Registry 地址，而该地址通常无法从本地工作站访问。

    示例：

    ac get images --registry-url=<REGISTRY_API_URL>

    拉取镜像

    使用 nerdctl 从 Registry 拉取镜像：

    # Pull an image from the current namespace
nerdctl pull <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

# Pull an image from another namespace when you already have permission
nerdctl pull <REGISTRY_CLIENT_HOSTPORT>/shared-ns/base-image:latest

    推送镜像

    将本地镜像推送到当前命名空间：

    # Tag the local image with the target repository
nerdctl tag my-app:latest <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:v1

# Push it to the Registry
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:v1

    将其他 Registry 中的镜像复制到 ACP Registry：

    # Pull the source image
nerdctl pull remote.registry.io/demo/my-app:latest

# Retag it for ACP Registry
nerdctl tag remote.registry.io/demo/my-app:latest <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

# Push it to ACP Registry
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

    删除镜像

    使用 ac delete images 从 Registry 中移除镜像标签：

    # Preview the deletion result without removing anything
ac delete images --repo=my-ns/my-app:v1 --registry-url=<REGISTRY_API_URL>

# Confirm the deletion
ac delete images --repo=my-ns/my-app:v1 --registry-url=<REGISTRY_API_URL> --confirm

    注意：

    • 此操作会从 Registry 中移除镜像 manifest 引用，但不能保证底层镜像数据会立即回收。
    • 在当前实现中，如果多个标签指向同一个 manifest digest，删除其中一个标签也可能会移除引用同一 manifest 的其他关联标签。

    示例：

    ac delete images \
  --repo=my-ns/my-app:v1 \
  --registry-url=<REGISTRY_API_URL> \
  --confirm