Configuring Docker registries

Akka Serverless needs the correct permissions to access container images. Set up Docker credentials to secure the username and password for each Docker Registry server.

If your registry requires a password, set the Docker credentials per Docker server, per Docker project. The Docker server that hosts the Docker Registry is the first part of the Docker image tag. For example, if your image is at, the Docker server is If there is no Docker server in the Docker image tag, it is using Docker Hub with default server.

This topic provides details for using:

A private Docker registry

If your Docker images are deployed to a Docker registry that is not publicly accessible configure credentials for Akka Serverless to pull from that registry.

Adding Docker credentials

Add Docker credentials to your project using the akkasls docker add-credentials command:

akkasls docker add-credentials --docker-server <my-server> \ (1)
  --docker-username <my-username> \ (2)
  --docker-email <my-email> \ (3)
  --docker-password <my-password> (4)
1 Server: The first part of the Docker image tag. For example, if your image is at, the server is This field is mandatory.
2 Username: The username. This field is optional.
3 Email: The email. This field is optional, though most Docker registries require it, sometimes filled with any email address.
4 Password: The password. This field is mandatory.

Listing Docker credentials

List Docker credentials with the akkasls docker list-credentials command:

akkasls docker list-credentials

The results should look something like:

ID                                     SERVER              USERNAME    EMAIL
89e41d75-aa70-4b9c-805f-ea35ee2622f0   _json_key

Removing Docker credentials

To delete credentials, use the 'ID' returned from the akkasls docker list-credentials command as the UUID in the akkasls docker delete-credentials command:

akkasls docker delete-credentials <credentials-uuid>

Docker Hub

Set up Docker credentials for Docker Hub using the akkasls docker add-credentials command:

akkasls docker add-credentials
  --docker-server \ (1)
  --docker-username <my-username> \ (2)
  --docker-email <my-email> \ (3)
  --docker-password <my-password>(4)
1 Your Docker Hub registry server URL
2 Your Docker username
3 Your Docker email
4 Your Docker account password

Limits on unauthenticated and free usage

Docker has rate limits new tab for unauthenticated and free Docker Hub usage. For unauthenticated users, pull rates are limited for individual IP address (e.g., for anonymous users: 100 pulls per 6 hours per IP address). For our outbound traffic, Akka Serverless leverages a limited set of IP addresses. This means that unauthenticated pulls might be rate limited. The limit for unauthenticated pulls is shared with all users of the Akka Serverless platform.

This is why we recommend configuring your registry to provide authentication details new tab. For authenticated users, pull requests are based on that account and not on the IP. For a detailed overview of account limits see this new tab page.

Check whether you’re using Docker Hub public images by checking the FROM command in your Dockerfile. If there is no registry URL in front of the image and tag, that image pulls from Docker Hub when it runs. For example, FROM lightbend/akka:latest pulls the latest available version of the lightbend/akka container from Docker Hub.

Google Container Registry

Use the following steps for Google Container Registries (GCR).

Before you begin:

  • Have a GCP account and have the Registry API enabled.

  • Have the ID that corresponds with a GCP project.

Configuring a private registry causes Akka Serverless to fail to deploy the sidecar. Because, the sidecar image is currently hosted in a private registry. The host credentials will be overwritten if another registry is configured.
  1. Create the service account.

    In the following example the service account is named akkaserverless-docker-reader. Run the create command in your terminal if you have the GCP shell tools installed. Or, run the command from the browser using Cloud Shell Terminal in the Google Cloud Platform (GCP) project.

      gcloud iam service-accounts create akkaserverless-docker-reader
  2. Grant the GCP storage object viewer role to the service account.

    In the following example, replace <gcp-project-id> with the GCP project ID.

      gcloud projects add-iam-policy-binding <gcp-project-id> \
      --member "serviceAccount:akkaserverless-docker-reader@<gcp-project-id>" \
      --role "roles/storage.objectViewer"
  3. Generate the service account _json_key.

    gcloud iam service-accounts keys create keyfile.json \
      --iam-account akkaserverless-docker-reader@<gcp-project-id>
  4. Configure your Akka Serverless project to use these credentials, by passing the contents of the key file as the password.

    In the following example the GCR server is configured as``. This value can be changed to any of the following:,, or
    akkasls docker add-credentials --docker-server \
      --docker-username _json_key \
      --docker-email \
      --docker-password "$(cat keyfile.json)"
Find detailed configuration instructions in the Google documentation new tab.

Azure Container Registry

To add credentials for Azure Container Registry (ACR), create a service principal, and use the generated username and password credentials to authenticate with Akka Serverless.

Use the following steps to configure an ACR registry:
  1. Get the full registry ID for subsequent commands for the Azure Container Registry called akkaserverless-registry.

    ACR_REGISTRY_ID=$(az acr show —name akkaserverless-registry —query id —output tsv)
  2. Create the service principal and return a password. In this case we’re calling the service principal akkaserverless-docker-reader and use a role that only allows pulling containers from ACR.

    SP_PASSWD=$(az ad sp create-for-rbac --name http://akkaserverless-docker-reader --scopes $ACR_REGISTRY_ID --role acrpull --query password --output tsv)
  3. Get the application ID of the service principal to use as the username for the docker credentials.

    SP_APP_ID=$(az ad sp show —id http://akkaserverless-docker-reader —query appId —output tsv)
  4. Configure your Akka Serverless project to use these credentials, by passing in the outputs of the previous commands:

    akkasls docker add-credentials --docker-server \
      --docker-username "$SP_APP_ID" \
      --docker-password "$SP_PASSWD"

Amazon Elastic Container Registry

Amazon ECR is not supported at this time, because Kubernetes native support for ECR requires running the Kubernetes cluster on an EC2 instance running that is running in the same account as the ECR registry. In ths case the ECR only supports short-lived tokens for authentication.