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.
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.
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.
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 email@example.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
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 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.
The following paths are supported by KCR:
Available to a single project
my-projectwithin an organization
Available to all projects with within
my-projectin the personal account
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.
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
prod projects in the
|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.|
Pass the repository and username as below:
sbt Docker/publish -Ddocker.registry=kcr.us-east-1.kalix.io -Ddocker.username=acm
"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.
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
kalix service deploy \ my-service \ kcr.us-east-1.kalix.io/robert/my-trial-project/test-service:latest
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
Username: The username (optional).
Email: The email address (optional).
Password: The password (mandatory).
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)
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.
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 firstname.lastname@example.org
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>
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
Username: Your username.
Email: Your email address.
Password: Your password.
To connect your Kalix project to Docker Hub, the parameters you need are:
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.
Docker has rate limits 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.
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.
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
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"
Generate the service account
gcloud iam service-accounts keys create keyfile.json \ --iam-account kalix-docker-reader@<gcp-project-id>.iam.gserviceaccount.com
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 email@example.com \ --docker-password "$(cat keyfile.json)"
Find detailed configuration instructions in the Google documentation .
To connect your Kalix project to Azure Container Registry (ACR), the parameters you need are:
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.