Configure container registries

Your Kalix services, and any dependencies they need, are sent to Kalix as container images which can be produced using the Docker command line tool, or tools such as Buildah. Before deploying, the container must be made available for Kalix in a container registry.

Kalix provides a built-in Kalix Container Registry which is readily set up for your use. Alternatively, even external container registries are supported with Kalix.

Kalix Container Registry

The Kalix Container Registry (KCR) can be used by all Kalix users to deploy services and is available in all Kalix regions.

Using the KCR for deploying your Kalix services is easy as authentication is built-in. Another benefit is that deployments, restarts and scaling does not depend on any connectivity to external registries.

Prerequisites

Before continuing, the following prerequisites have to be checked.

The current user must be logged in to Kalix.
You must have Docker installed and accessible to the current user.

Execute the kalix auth current-login to verify that you are logged into Kalix. (Use kalix auth login, if not.)

> kalix auth current-login
ba6f49b0-c4e1-cccc-ffff-30053f652c42   user test@lightbend.com   true       CLI login from the machine.localdomain(127.0.0.1)   3d21h

Check that you have the Docker client installed. The minimum required version of Docker is 18.03.

> docker --version
Docker version 23.0.6, build ef23cbc431

Configuring KCR

The Kalix Container Registry uses an access token generated by Kalix to authorize the user and determine if they can push images to the registry.

An intermediate credential helper generates the access token using the Kalix CLI whenever a docker push command is issued.

Ensure you are on the correct Kalix project. (Set the target project with kalix config set project <project name>.)
```
kalix config get-project
```

Set up the credential helper using the Kalix CLI. This command will ask if you want to register the credential helper in the docker configuration file.

> kalix auth container-registry configure
This operation will update your '.docker/config.json' file. Do you want to continue?
Use the arrow keys to navigate: ↓ ↑ → ←
? >:
  ▸ No
    Yes

Select "Yes" to continue.

If the command completes successfully, it will output the hostname of KCR in the current Kalix region.

The docker configuration file was successfully updated.
Kalix Container Registry path is: 'kcr.us-east-1.kalix.io'
Use this path to push images to the container registry. The same path is also used when deploying the service.

The Kalix Container Registry is now configured.

Pushing an image to KCR

Pushing images to KCR works the same as pushing to any other Docker registry: using the Docker client, you tag an image and push it.

The fully qualified domain name of KCR in the current Kalix region can always be obtained using the CLI.

> kalix auth container-registry print
Kalix Container Registry fully qualified domain name is: 'kcr.us-east-1.kalix.io'
Use this path to push images to the container registry. The same path is also used when deploying the service.

An image can be made available to a specific project or all projects within an organisation. The image URL path selects the organisation and project and the domain name selects the KCR region.

Image paths

The following paths are supported by KCR:

Available to a single project my-project within an organization acme:

kcr.us-east-1.kalix.io/acme/my-project/my-image:tag
Available to all projects with within acme:

kcr.us-east-1.kalix.io/acme/my-image:tag
Available to my-project in the personal account robert:

kcr.us-east-1.kalix.io/robert/my-project/my-image:tag

As you can see, the directory structure in KCR has the same structure as Kalix in general, a user or an organization has one or more projects that can host images.

Organizations can store images in the organizational root to enable deployment of the image in any project within the organization.

For example:

If we first push an image to the Acme organization.

docker push kcr.us-east-1.kalix.io/acme/shopping-cart:latest

This image is now available to both the stage and prod projects in the acme organization.

Your build manager can push the image for you instead. To do that, make sure to configure the image path on your project for the respective tool, as shown below.

Maven

Update your pom.xml as such <dockerImage>kcr.us-east-1.kalix.io/acme/${project.artifactId}</dockerImage> and run:

mvn deploy

sbt

Pass the repository and username as below:

sbt Docker/publish -Ddocker.registry=kcr.us-east-1.kalix.io -Ddocker.username=acm

npm

Update your package.json as such "dockerImage": "kcr.us-east-1.kalix.io/acme/shopping-cart", and run:

npm run deploy

This command not only pushes the image out but also deploys the service with the given image in the default project.

Deploying a service using an image from KCR

When deploying a Kalix service specify the same image URL as above with the kalix service deploy command:

Deploying a service as a member of the Acme organization.

kalix service deploy \
  shopping-cart-service \
  kcr.us-east-1.kalix.io/acme/shopping-cart:latest

Deploying a service as trial user robert in the project my-trial-project.

kalix service deploy \
  my-service \
  kcr.us-east-1.kalix.io/robert/my-trial-project/test-service:latest

Using External Container Registries

To use an external container registry with Kalix, you need to give Kalix permissions to connect to your registry. To add credentials for your container registry to Kalix, you can use the Kalix CLI or the Kalix Console.

If the container registry you’re using does not require authentication, you don’t have to add any credentials. Kalix will automatically pull the container image using the URL you use to deploy your service.

There are four parameters you need to specify, depending on the registry you want to connect to:

Server: The first part of the container image URL. For example, if your image is at us.gcr.io/my-project/my-image, the server is https://us.gcr.io (mandatory).
Username: The username (optional).
Email: The email address (optional).
Password: The password (mandatory).

Use the kalix docker add-credentials command.

kalix 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
2	Username
3	Email
4	Password

Listing credentials

To list all container registry credentials for your Kalix project, you can use the Kalix CLI or the Kalix Console. For security purposes, neither the CLI nor the Console will show the password of the configured registry.

Use the kalix docker list-credentials command:

kalix docker list-credentials

The results should look something like:

ID                                     SERVER              USERNAME    EMAIL
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   https://us.gcr.io   _json_key   user@example.com

Removing credentials

To remove container registry credentials from your Kalix project, you can use the Kalix CLI or the Kalix Console.

Use the 'ID' returned from the kalix docker list-credentials command as the ID in the kalix docker delete-credentials command:

kalix docker delete-credentials <credentials-id>

Supported external registries

Private container registries

To connect your Kalix project to private or self-hosted container registries, the parameters you need are:

Server: The full URL of your container registry, including the API version (like https://mycontainerregistry.example.com/v1/).
Username: Your username.
Email: Your email address.
Password: Your password.

Docker Hub

To connect your Kalix project to Docker Hub, the parameters you need are:

Server: https://index.docker.io/v1/.
Username: Your Docker Hub username.
Email: Your Docker Hub email address.
Password: Your Docker Hub password or Personal Access Token.

When you use the Kalix Console, you don’t need to provide the Server URL.

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 based on IP address (anonymous, or unauthenticated, users have a limit of 100 container image pulls per 6 hours per IP address). Kalix leverages a limited set of IP addresses to connect to Docker Hub. This means that unauthenticated image pulls might be rate limited. The limit for unauthenticated pulls is shared by all users of the Kalix platform.

Google Container Registry

To connect your Kalix project to Google Container Registry (GCR), you’ll need:

An active Google Cloud Platform account.
The Registry API enabled on your Google Cloud project.
The ID that corresponds with your GCP project.
1. Create the service account.
  
  In the following example the service account is named kalix-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 kalix-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:kalix-docker-reader@<gcp-project-id>.iam.gserviceaccount.com" \ --role "roles/storage.objectViewer"
3. Generate the service account _json_key.
  gcloud iam service-accounts keys create keyfile.json \ --iam-account kalix-docker-reader@<gcp-project-id>.iam.gserviceaccount.com
4. Configure your Kalix project to use these credentials, by passing the contents of the key file as the password.
  kalix docker add-credentials --docker-server https://us.gcr.io \ --docker-username _json_key \ --docker-email anyemail@example.com \ --docker-password "$(cat keyfile.json)"
  Find detailed configuration instructions in the Google documentation .

Azure Container Registry

To connect your Kalix project to Azure Container Registry (ACR), the parameters you need are:

Server: <registry name>.azurecr.io.

Password: The password is based on the "service principal." To create a service principal (like kalix-docker-reader) run the command below.

ACR_REGISTRY_ID=$(az acr show —name kalix-registry —query id —output tsv)

SP_PASSWD=$(az ad sp create-for-rbac --name http://kalix-docker-reader --scopes $ACR_REGISTRY_ID --role acrpull --query password --output tsv)

Username: The username is the application ID of the "service principal." To retrieve the ID, run the command below.
```
SP_APP_ID=$(az ad sp show —id http://kalix-docker-reader —query appId —output tsv)
```

When you use the Kalix Console, you only need to fill in the registry name for the Server URL.