Skip to main content

Image Registries

The Raftt environment controller requires access to the image registries from which the workload images are pulled. This is to fetch their metadata, including the entrypoint, args and more. If the images are publicly available (for example, on Dockerhub), nothing needs to be done. Otherwise, it may be necessary to configure access to private registries.

We support several different kinds of authentication, as required by various image registries. Generally, if there are secrets in the namespace with the type, we will try to load them and use them to fetch. Otherwise, you can configure access to registries as follows.


ECR access cannot be granted by a long-lived secret value, since tokens are limited to 12 hours. To overcome this, the environment controller has built-in support for the ecr-credential-helper, which converts between IAM permissions granted by a role to docker credentials. To configure, add the following to your .raftt file:

registries=["", ""])

Replacing the hosts in the registries param with the correct ones for you.

This depends on the environment controller having access to an IAM role which grants read access to the relevant ECR repositories. There are two ways in which this is supported:

  1. If the nodes have the required access, and pods can access the node metadata server, no further configuration is needed.
  2. If the nodes do not have the required access, or you have blocked it off from pods, you can:
    1. Follow to create a Kubernetes service account with access to an IAM role.
    2. Set the following value in the raftt.yml:
workloadIdentityServiceAccount: <name of service account>

This will make the environment controller deployment use the named service account, which will give it the required permissions. For this to take effect, run raftt cleanup and raftt connect again.

GCR / Google Artifact Registry

There are two options for supporting GCR repositories. One is to use Workload Identity, and create a Kubernetes service account linked to a GCP service account with the required permissions, and have the environment controller use it. The other is to take the GCP service account's token and create a Kubernetes secret, with which the environment controller will be able to access the registry.

Workload Identity

  1. Create a service account with the required permissions (i.e. Artifact Registry Reader).
  2. Follow to allow access to the GCP service account permissions from Kubernetes
  3. Add the following to your raftt.yml file:
searchLocalDockerRegistry: true
  1. Add the following to your .raftt file

Which enables the docker-credential-gcr helper in the environment controller.

For this to take effect, run raftt cleanup and raftt connect again.


  1. Create a GCP service account with the required permissions (i.e. Artifact Registry Reader), and save the token in json format.
  2. Extract from the GCR secret the email - it should be one of the json fields.
  3. Run the following, creating a secret allowing access to GCR in the namespace you are using, replacing:
    1. NAMESPACE with the relevant namespace
    2. SECRET_NAME with a name. This does not matter. Example - “gcr-secret”
    3. EMAIL with the email extracted in step 2.
    4. FILENAME with the filename of the downloaded token.
kubectl -n NAMESPACE create secret docker-registry SECRET_NAME \
--docker-server=REGISTRY_URL \
--docker-username=_json_key \
--docker-email=EMAIL \
--docker-password="$(cat FILENAME | base64 -d)"

Note: GCR also supports a base64-encoded version of the password, in which case the username should be _json_key_base64.

kubectl -n secrets edit secret SECRET_NAME

Minikube local registry

When using minikube it is possible to build images locally directly to Minikube's registry, using a command like eval $(minikube -p minikube docker-env). In that case, we need to allow the environment controller to access the internal registry. To do that, add:

searchLocalDockerRegistry: true

For this to take effect, run raftt cleanup and raftt connect again.

Other registry

Generally, any registry that is accessed through Kubernetes ImagePullSecrets should work fine, as the environment controller knows to use them if needed.

If you have a different requirement, let us know.