Switch to an external Docker registry at runtime

This tutorial shows how you can switch to an external Docker registry in a specific Namespace, with Serverless already installed on your cluster. This example relies on the default Namespace but you can use any other. You will create a Secret custom resource (CR) with credentials to one of these registries:

After this change, any Function deployed in the default Namespace will store images in this registry.

CAUTION: Function images are not cached in the Docker Hub. The reason is that this registry is not compatible with the caching logic defined in Kaniko that Serverless uses for building images.


  • Docker Hub
  • GCR
  • ACR


Create required cloud resources

To create cloud resources required for a given registry provider, follow the steps described in the Set an external Docker registry tutorial.

Create a Secret CR

Create a Secret CR in the default Namespace. Such a Secret must contain the serverless.kyma-project.io/remote-registry: config label and the required data (username, password, serverAddress, and registryAddress):

Click to copy
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
type: kubernetes.io/dockerconfigjson
name: serverless-registry-config
namespace: default
serverless.kyma-project.io/remote-registry: config
username: {VALUE}
password: {VALUE}
serverAddress: {VALUE}
registryAddress: {VALUE}

CAUTION: If you want to create a cluster-wide Secret, you must create it in the kyma-system Namespace and add the serverless.kyma-project.io/config: credentials label. Read more about requirements for Secret CRs.

Test the registry switch

Create a Function in the default Namespace and check if the Function's Deployment points to the external registry using this command:

Click to copy
kubectl get pods -n default -l serverless.kyma-project.io/resource=deployment -o jsonpath='{ ...image }'