#配置 Registry 推送限制

Alauda Container Platform Registry 包含一个内置代理，可对 OCI registry API 请求强制执行镜像推送限制。

你可以利用此功能来：

• 限制已推送镜像的最大大小
• 限制仓库中允许的标签数量
• 应用全局限制或基于路径的覆盖规则

#开始之前

• 必须已安装 Alauda Container Platform Registry 集群插件。
• 你必须具有更新 Registry 插件配置的权限。
• 你必须能够在 Registry 命名空间中创建 ConfigMap。
• 如果你尚未安装 Registry，请参见 通过 YAML 安装。

#工作原理

要使用此功能，请在 Registry 插件配置中启用 registryLimitConfig，并创建一个用于定义限制的 ConfigMap。

#启用 Registry 推送限制

在安装或更新 Registry 插件时，启用 registryLimitConfig 并将其指向一个 ConfigMap 名称。

示例：

spec:
  config:
    registryLimitConfig:
      enabled: true
      configMapName: image-registry-limit-config

说明：

• enabled: true 会将限制配置挂载到 Registry 代理容器中。
• configMapName 必须引用你手动创建的 ConfigMap。
• 对于新的部署，建议使用的 ConfigMap 名称是 image-registry-limit-config。
• 运行时也支持旧版 ConfigMap 名称 registry-gateway-config，以保持向后兼容。

#创建限制 ConfigMap

在与 Registry 部署相同的命名空间中创建一个 ConfigMap。

示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: image-registry-limit-config
  namespace: cpaas-system
data:
  max_image_size: "1GB"
  tag_count_limit: "1000"
  rules: |
    - path: ^team-a/.+
      limit:
        max_image_size: "100MB"
        tag_count_limit: "3"
    - path: ^team-b/.+
      limit:
        max_image_size: "5GB"
        tag_count_limit: "20"

应用它：

kubectl apply -f image-registry-limit-config.yaml

#配置键

#全局键

#可选规则键

每条规则包含：

• path：用于匹配仓库路径的正则表达式
• limit.max_image_size：规则匹配时应用的大小限制
• limit.tag_count_limit：规则匹配时应用的标签数量限制

规则按顺序进行评估，第一个匹配的规则将生效。

对于每条规则，请同时设置 limit.max_image_size 和 limit.tag_count_limit。

#配置示例

#示例 1：仅全局限制

apiVersion: v1
kind: ConfigMap
metadata:
  name: image-registry-limit-config
  namespace: cpaas-system
data:
  max_image_size: "500MB"
  tag_count_limit: "50"

效果：

• 所有仓库使用相同的默认大小限制和标签数量限制。

#示例 2：按仓库覆盖

apiVersion: v1
kind: ConfigMap
metadata:
  name: image-registry-limit-config
  namespace: cpaas-system
data:
  max_image_size: "1GB"
  tag_count_limit: "100"
  rules: |
    - path: ^project-a/.+
      limit:
        max_image_size: "100MB"
        tag_count_limit: "3"
    - path: ^project-b/release/.+
      limit:
        max_image_size: "5GB"
        tag_count_limit: "20"

效果：

• project-a/* 的限制为 100MB 和 3 个标签。
• project-b/release/* 的限制为 5GB 和 20 个标签。
• 其他仓库使用全局默认值。

#应用更改

在创建或更新 ConfigMap 后，Registry 代理会自动加载新规则。

请留出一小段传播延迟时间，然后新限制才会生效。

#验证配置

1. 检查 ConfigMap 是否存在：

   kubectl get configmap image-registry-limit-config -n cpaas-system

2. 检查 Registry 部署是否正在运行：

   kubectl get pods -n cpaas-system -l app=image-registry

3. 向受该规则覆盖的仓库推送镜像，并验证结果。

示例：

nerdctl login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/team-a/demo:v1

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

预期行为：

• 当镜像大小超过配置的限制时，推送会被拒绝。
• 当仓库已经达到允许的最大标签数量时，推送会被拒绝。

#推荐做法

• 先从全局默认值开始，然后仅在需要时添加基于路径的规则。
• 使用能够让规则匹配更可预测的仓库路径约定。
• 在更新过程中保持 ConfigMap 名称稳定。
• 在应用到生产环境之前，先在非生产环境中验证更改。

#故障排除

#限制没有生效

请检查以下内容：

• spec.config.registryLimitConfig.enabled 已设置为 true
• ConfigMap 名称与 spec.config.registryLimitConfig.configMapName 匹配
• ConfigMap 存在于 Registry 命名空间中
• rules 中的仓库路径与实际推送目标匹配

#某条规则未匹配到预期的仓库

检查 path 中的正则表达式。

规则按顺序匹配，因此前面的某条规则可能已经生效。

#现有环境仍在使用 registry-gateway-config

运行时仍支持旧版 ConfigMap 名称。

对于新环境，请使用 image-registry-limit-config。