#Configure Registry Push Limits

The Alauda Container Platform Registry includes a built-in proxy that can enforce image push limits for OCI registry API requests.

You can use this capability to:

• Limit the maximum size of pushed images
• Limit the number of tags allowed in a repository
• Apply global limits or path-based override rules

#Before You Begin

• The Alauda Container Platform Registry cluster plugin must already be installed.
• You must have permission to update the Registry plugin configuration.
• You must be able to create a ConfigMap in the Registry namespace.
• If you have not installed the Registry yet, see Install Via YAML.

#How It Works

To use this feature, enable registryLimitConfig in the Registry plugin configuration and create a ConfigMap that defines the limits.

#Enable Registry Push Limits

When installing or updating the Registry plugin, enable registryLimitConfig and point it to a ConfigMap name.

Example:

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

Notes:

• enabled: true mounts the limit configuration into the Registry proxy container.
• configMapName must reference a ConfigMap that you create manually.
• For new deployments, the recommended ConfigMap name is image-registry-limit-config.
• The runtime also accepts the legacy ConfigMap name registry-gateway-config for backward compatibility.

#Create the Limit ConfigMap

Create a ConfigMap in the same namespace as the Registry deployment.

Example:

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"

Apply it:

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

#Configuration Keys

#Global Keys

#Optional Rule Key

Each rule contains:

• path: A regular expression used to match a repository path
• limit.max_image_size: The size limit applied when the rule matches
• limit.tag_count_limit: The tag count limit applied when the rule matches

Rules are evaluated in order, and the first matching rule takes effect.

For each rule, set both limit.max_image_size and limit.tag_count_limit.

#Configuration Examples

#Example 1: Global Limits Only

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

Effect:

• All repositories use the same default size limit and tag count limit.

#Example 2: Per-Repository Overrides

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"

Effect:

• project-a/* is limited to 100MB and 3 tags.
• project-b/release/* is limited to 5GB and 20 tags.
• Other repositories use the global defaults.

#Apply Changes

After you create or update the ConfigMap, the Registry proxy loads the new rules automatically.

Allow a short propagation delay before the new limits take effect.

#Verify the Configuration

1. Check that the ConfigMap exists:

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

2. Check that the Registry deployment is running:

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

3. Push an image to a repository covered by the rule and verify the result.

Example:

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

If the Registry uses a self-signed certificate or plain HTTP, add the global flag --insecure-registry.

Expected behavior:

• When the image size exceeds the configured limit, the push is rejected.
• When the repository already has the maximum allowed number of tags, the push is rejected.

#Recommended Practices

• Start with global defaults, then add path-based rules only where needed.
• Use repository path conventions that make rule matching predictable.
• Keep the ConfigMap name stable across updates.
• Verify changes in a non-production environment before applying them to production.

#Troubleshooting

#The limits do not take effect

Check the following:

• spec.config.registryLimitConfig.enabled is set to true
• The ConfigMap name matches spec.config.registryLimitConfig.configMapName
• The ConfigMap exists in the Registry namespace
• Repository paths in rules match the actual push target

#A rule does not match the expected repository

Check the regular expression in path.

Rules are matched in order, so an earlier rule may already have taken effect.

#Existing environments still use registry-gateway-config

The runtime still supports the legacy ConfigMap name.

For new environments, use image-registry-limit-config.