Configuring registries

Akka Serverless will need the correct permissions to access your packaged Cloudstate services. You can setup Docker credentials to secure the username/password for each Docker Registry server.

If Cloudstate services' Docker images require a password to access, you need to set Docker credentials per Docker server per 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 us.gcr.io/my-project/my-image, the Docker server is https://us.gcr.io. If there is no Docker server in the Docker image tag, it is using Docker Hub with default server https://index.docker.io/v1/.

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 us.gcr.io/my-project/my-image, the server is https://us.gcr.io. 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 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

Docker credentials can be listed using the akkasls docker list-credentials command:

$ akkasls docker list-credentials
ID                                     SERVER              USERNAME    EMAIL
89e41d75-aa70-4b9c-805f-ea35ee2622f0   https://us.gcr.io   _json_key   in@valid.com

Removing Docker credentials

Docker credentials can be deleted using the akkasls docker delete-credentials command. To delete them, you will need the ID of the credentials, which can be identified using the list credentials command:

akkasls docker delete-credentials <credentials-uuid>

Docker Hub

To set up Docker credentials for Docker Hub, pass https://index.docker.io/v1/ with the username, email, and password for your account. For example,

akkasls docker add-credentials --docker-server https://index.docker.io/v1/ \
  --docker-username <my-username> \
  --docker-email <my-email> \
  --docker-password <my-password>

Limits on unauthenticated and free useage

Docker has rate limits new tab for unauthenticated and free Docker Hub usage. For unauthenticated users pull rates are limited based on 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 so 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 providing 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. Detailed instructions on how to configure this can be found here, below are steps for getting started quickly.

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

    gcloud iam service-accounts create cloudstate-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:cloudstate-docker-reader@<gcp-project-id>.iam.gserviceaccount.com" \
      --role "roles/storage.objectViewer"
  3. Generate a key file for your service account:

    gcloud iam service-accounts keys create keyfile.json \
      --iam-account cloudstate-docker-reader@<gcp-project-id>.iam.gserviceaccount.com
  4. Configure your Cloudstate 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 gcr.io, us.gcr.io, eu.gcr.io or asia.gcr.io. Below we use us.gcr.io:

    akkasls docker add-credentials --docker-server https://us.gcr.io \
      --docker-username _json_key \
      --docker-email anyemail@example.com \
      --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 cloudstate-registry

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

    SP_PASSWD=$(az ad sp create-for-rbac --name http://cloudstate-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://cloudstate-docker-reader —query appId —output tsv)
  4. Configure your Cloudstate project to use these credentials, by passing in the outputs of the previous commands:

    akkasls docker add-credentials --docker-server cloudstate-registry.azurecr.io \
      --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.

Bintray

To set up Docker credentials for Bintray, use the following:

  • Username: the account username.

  • Password: the API key as password (NOTE: You can find API key in Bintray website under "Edit Profile" section.)

  • Email: the account email.

  • Server: The first part of the Docker image tag. For example, if your image is at my-registry.bintray.io/cloudstate-samples/shopping-cart-js:latest, the server is my-registry.bintray.io without http(s) prefix.

For example,

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