Configuring registries

Akka Serverless will need the correct permissions to access your packaged service images. You can set up Docker credentials to secure the username and password for each Docker Registry server.

If your registry requires a password, you need to set 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

The following provide details for using:

A private Docker registry

If your Docker images are deployed to a Docker registry that is not publicly accessible, you will need to configure credentials for Akka Serverless to be able to pull from that registry.

Adding Docker credentials

Docker credentials can be added to your project using the akkasls docker add-credentials command. You will need the following information:

  • Server: The first part of the Docker image tag. For example, if your image is at, the server is This field is mandatory.

  • Username: The username. This field is optional.

  • Email: The email. This field is optional, though most Docker registries require it, sometimes filled with any email address.

  • Password: The password. This field is mandatory.

Once you have the above, you can add the Docker credentials to Akka Serverless using the following command:

akkasls docker add-credentials --docker-server <my-server> \
  --docker-username <my-username> \
  --docker-email <my-email> \
  --docker-password <my-password>

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, you will need their ID, which is output by the akkasls docker list-credentials command. Delete Docker credentials with the akkasls docker delete-credentials command:

akkasls docker delete-credentials <credentials-uuid>

Docker Hub

To set up Docker credentials for Docker Hub, pass akkasls docker add-credentials the URL` with the username, email, and password for your account. For example,

akkasls docker add-credentials --docker-server \
  --docker-username <my-username> \
  --docker-email <my-email> \
  --docker-password <my-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.

You can 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 will pull 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

To add credentials for a Google Container Registry (GCR), you need to create a service account, and supply the JSON key for that service account as the password for the credentials, with a username of _json_key. Find detailed configuration instructions in the Google documentation new tab. We provide steps below for getting started quickly.

At time of writing, configuring a private registry will cause Akka Serverless to fail to deploy the sidecar, as the sidecar image is currently hosted in a private registry whose credentials will be overwritten if another registry is configured. We hope to lift this restriction soon.
  1. Create the service account, in this case we’re calling the service account akkaserverless-docker-reader:

    gcloud iam service-accounts create akkaserverless-docker-reader
  2. Grant the GCP storage object viewer role to the service account, to do this you will need your GCP project’s id:

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

    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. You will need to specify the GCR server here, either,, or Below we use

    akkasls docker add-credentials --docker-server \
      --docker-username _json_key \
      --docker-email \
      --docker-password "$(cat keyfile.json)"

Azure Container Registry

To add credentials for Azure Container Registry (ACR), you need to create a service principal, and supply the username and password generated for it. Detailed instructions on how to configure this can be found here new tab, below are steps for getting started quickly.

  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. The next step is to get the application ID of the service principal which is used 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, since Kubernetes native support for ECR requires running the Kubernetes cluster on an EC2 instance running in the same account as the ECR registry. This is due to ECR only supporting short-lived tokens for authentication.