Configure Registry Cache

Prerequisites

• A SAP BTP, Kyma runtime instance running on the BTP platform.
• Administrative access to the Kyma runtime with kubeconfig and the kubectl tool.
• The Registry Cache module installed on your Kyma cluster.

Basic Configuration

RegistryCacheConfig is a namespace-scoped resource and can be created in any namespace.

To configure Registry Cache, create a RegistryCacheConfig custom resource (CR). The following example uses the test namespace — create it first if it doesn't exist:

kubectl create namespace test

kubectl create -f - <<EOF 
apiVersion: core.kyma-project.io/v1beta1
kind: RegistryCacheConfig
metadata:
  name: config1
  namespace: test
spec:
  upstream: docker.io
  volume:
    size: 100Gi
EOF

Once applied, Kyma Control Plane (KCP) processes the resource and configures a caching layer for the specified upstream registry (in this case, docker.io). The volume.size field specifies the size of the persistent volume used to store cached images.

You can create multiple RegistryCacheConfig resources to cache different upstream registries. Each resource must have a unique name, and each upstream registry must be unique across all resources in the cluster.

After creating a RegistryCacheConfig resource, verify that KCP processed it successfully by checking the resource status:

kubectl get registrycacheconfig <name> -n <namespace> -o jsonpath='{.status.state}'

The expected output values are:

• Pending — KCP is processing the configuration.
• Ready — the caching layer has been configured successfully.
• Error — KCP-side processing failed. Check status.conditions for details, or see RegistryCacheConfig.

Providing Credentials for Upstream Repository

If the upstream registry requires authentication, create a Kubernetes Secret in the same namespace as the RegistryCacheConfig resource and reference it in the spec.secretReferenceName field. The Secret must be immutable and of type generic.

Note:

The credential Secret must exist on the cluster before applying the RegistryCacheConfig resource.

1. Set environment variables with the upstream registry credentials:

   export USERNAME=<your username>
   export PASSWORD=<your password>

2. Create the namespace if it doesn't exist:

   kubectl create namespace test

3. Create an immutable Secret named rc-secret in the test namespace:

   kubectl create -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: rc-secret
     namespace: test
   type: Opaque
   immutable: true
   data:
     username: $(echo -n $USERNAME | base64 | tr -d '\n')
     password: $(echo -n $PASSWORD | base64 | tr -d '\n')
   EOF

   For Google Artifact Registry, the username is _json_key and the password is the service account key in JSON format. Follow steps 3a–3b instead of step 3 above.

   3a. Base64-encode the service account key:

   export PASSWORD=$(echo -nE $SERVICE_ACCOUNT_KEY_JSON | base64 | tr -d '\n')

   3b. Create an immutable Secret with the encoded key as the password:

   kubectl create -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: rc-secret
     namespace: test
   type: Opaque
   immutable: true
   data:
     username: $(echo -n "_json_key" | base64 | tr -d '\n')
     password: $PASSWORD
   EOF

4. Apply the Registry Cache configuration referencing the created Secret:

   kubectl create -f - <<EOF
   apiVersion: core.kyma-project.io/v1beta1
   kind: RegistryCacheConfig
   metadata:
     name: config2
     namespace: test
   spec:
     upstream: <protected registry URL>
     secretReferenceName: rc-secret
     volume:
       size: 100Gi
   EOF

Note:

When using a private registry, the same credentials must be stored in two Kubernetes Secrets:

• The Secret referenced in spec.secretReferenceName — used by Registry Cache to authenticate against the upstream registry when pulling images to cache.
• An imagePullSecret on each workload — used by containerd to authenticate directly against the upstream registry as a fallback when Registry Cache is unavailable.

Do not remove the imagePullSecret from your workloads when configuring credentials for Registry Cache. If the cache is unavailable, containerd falls back to the upstream registry and requires the credentials directly.

Rotating Credentials

Credential Secrets are immutable and cannot be updated in place. To rotate credentials:

1. Create a new Secret with the updated credentials. Use a different name (for example, rc-secret-v2):

   kubectl create -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: rc-secret-v2
     namespace: <namespace>
   type: Opaque
   immutable: true
   data:
     username: $(echo -n $USERNAME | base64 | tr -d '\n')
     password: $(echo -n $PASSWORD | base64 | tr -d '\n')
   EOF

2. Update spec.secretReferenceName in the existing RegistryCacheConfig resource to reference the new Secret:

   kubectl patch registrycacheconfig <name> -n <namespace> \
     --type=merge -p '{"spec":{"secretReferenceName":"rc-secret-v2"}}'

3. Once the RegistryCacheConfig is in Ready state, delete the old Secret:

   kubectl delete secret rc-secret -n <namespace>

Advanced Configuration

For all available configuration fields and their defaults, see RegistryCacheConfig.

Validation of Registry Cache Configuration

When you apply a RegistryCacheConfig resource, the Registry Cache webhook validates the configuration on the Kyma runtime side before the Kubernetes API accepts it. If the configuration is invalid, the API rejects the request and returns an error — no CR is created.

Example error message:

admission webhook "registrycacheconfig-v1beta1.kb.io" denied the request: spec.upstream: Invalid value: "dockerrrrr.io": upstream is not DNS resolvable

If the CR is accepted, KCP processes it. The status transitions from Pending to Ready on success, or to Error if KCP-side processing fails. Check status.conditions for details.

Note:

KCP periodically reconciles RegistryCacheConfig resources. During reconciliation, a CR in Ready state transitions back to Pending and then returns to Ready once reconciliation completes. This is expected behavior.

The following table describes the validation rules for each field:

Field	Validation
spec.upstream	Must be a valid DNS-resolvable host (no scheme). Must be unique across all RegistryCacheConfig resources in the cluster. Port, if specified, must be in the range 1–65535.
spec.remoteURL	Must have the format <scheme><host>[:<port>] where <scheme> is https:// or http:// and <host>[:<port>] corresponds to the upstream. Must be DNS resolvable.
spec.secretReferenceName	The referenced Secret must exist in the same namespace as the RegistryCacheConfig resource, be immutable, and contain exactly the username and password data keys.
spec.volume.size	Must be a positive value in a format recognized by Go's resource.Quantity (for example, 10Gi). Immutable after creation.
spec.volume.storageClassName	The referenced storage class must be available. Immutable after creation.
spec.garbageCollection.ttl	Must be in a format recognized by Go's time.ParseDuration (for example, 24h). Set to 0s to disable garbage collection. Cannot be re-enabled once disabled.
spec.proxy.httpProxy	Must be a valid URL starting with http:// or https://.
spec.proxy.httpsProxy	Must be a valid URL starting with http:// or https://.
spec.http.tls	Must be a valid boolean indicating whether TLS is enabled.

Managing Registry Cache Configuration

Listing Registry Cache Configurations

To list all RegistryCacheConfig resources across all namespaces, run:

kubectl get registrycacheconfig -A

To list resources in a specific namespace, run:

kubectl get registrycacheconfig -n <namespace>

Deleting a Registry Cache Configuration

To delete a RegistryCacheConfig resource, run:

kubectl delete registrycacheconfig <name> -n <namespace>

For example:

kubectl delete registrycacheconfig config -n test