Configure a container registry

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 authentication

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. Use the Kalix CLI to configure the Docker credentials helper:

> 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.

When the command completes successfully, it lists the hostname of KCR for all available regions.

Docker configuration file successfully updated.
Available Kalix Container Registry hosts per region:
REGION         ORGANIZATION   ORGANIZATION_ID                        KALIX CONTAINER REGISTRY
gcp-us-east1   PUBLIC         NONE                                   kcr.us-east-1.kalix.io
gcp-us-east1   acme           cde1044c-b973-4220-8f65-0f7d317bb458   kcr.us-east-1.kalix.io

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 for the current Kalix region can be obtained using the CLI.

> kalix container-registry print
REGION         ORGANIZATION   ORGANIZATION_ID                        KALIX CONTAINER REGISTRY
gcp-us-east1   PUBLIC         NONE                                   kcr.us-east-1.kalix.io
gcp-us-east1   acme           cde1044c-b973-4220-8f65-0f7d317bb458   kcr.us-east-1.kalix.io

An image can be made available to a specific project or all projects within an organization. The image URL path selects the organization 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 the acme organization:

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

As you can see, the directory structure in KCR has the same structure as Kalix in general, 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.

Configuring build tools for KCR

Your build tool 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 with the KCR domain name and your Kalix organization name

pom.xml
  <properties>
    ....
    <kalixContainerRegistry>kcr.us-east-1.kalix.io</kalixContainerRegistry>
    <kalixOrganization>acme</kalixOrganization>
    <dockerImage>${kalixContainerRegistry}/${kalixOrganization}/${project.artifactId}</dockerImage>
  </properties>

and run

mvn deploy
sbt

Update your build.sbt with the KCR domain name and your Kalix organization name

dockerRepository := Some("kcr.us-east-1.kalix.io")
dockerUsername := Some("acme") // Kalix organization name

and run

sbt Docker/publish
npm

Update your package.json with the KCR domain name and your Kalix organization name

package.json
"dockerImage": "kcr.us-east-1.kalix.io/acme/shopping-cart"

and run

npm run deploy
This command not only pushes the image 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 a member of the Acme organization, with an image in the project my-trial-project.

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