Container Registries


Container Registries store and manage container images ready for use when they are needed in a deployment. Developers (or at least the CI pipelines they trigger) "push" built images into a registry and a Kubernetes cluster will "pull" images out of a registry as needed - usually as part of a deployment.
There are many different providers of container registries, and they can be provided as managed services or be self-hosted. The basic mechanics of pushing and pulling images to or from registries are the same across all providers. However, the way that these requests are authenticated can be very different across different providers.
Humanitec provides a way of centrally managing the credentials required to push or pull images out of a registry. This makes it easy to pull images from private registries even if they are hosted in a different cloud to where the Kubernetes cluster is hosted. For example, using Humanitec it is straightforward to pull images from a private Elastic Container Registry (ECR) in AWS from a Kubernetes cluster running in Azure. Humanitec ensures that the short-lived tokens required to authenticate with the ECR are generated and kept up to date in the Azure cluster.

Why does Humanitec need access to my registry?

Humanitec actually does not need access to your container registry. The only parts of your infrastructure that need access are usually the CI pipeline to push the images into the registry and the Kubernetes cluster to pull the images during deployments. Humanitec can help out by being a central place to manage credentials that can be inserted into your CI pipeline or Kubernetes cluster.
In most cases, when everything is hosted on one cloud provider, everything works out of the box. That is, image pulls from a cluster will automatically be authenticated for Kubernetes clusters running in the same project or account.
In this case, it is not necessary to add your container registry credentials to Humanitec if you do not want Humanitec to provide credentials to the CI Pipeline.

Providing credentials to a CI Pipeline

Pushing to registries such as ECR or Google Container Registry (GCR) can be complex from 3rd party CI pipelines. This is because both ECR and GCR do not support long-lived static credentials. It is necessary to fetch temporary credentials using either a command-line tool or directly via the API in order to authenticate with the registry.
If you have registered a registry with Humanitec, you can optionally provide credentials for the registry to your CI pipeline. This means your CI pipeline can fetch a set of valid credentials with a single API request using a Humanitec static token. The static token needs to be issued for a service user that has the ArtefactContributer role on the Humanitec Organization.
Here is an example request:
curl \
-H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
-H "Content-Type: "application/json" \
In the above example:
  • HUMANITEC_TOKEN contains the token issued for a service user which holds the ArtefactContributer on the organization.
  • HUMANITEC_ORG is the organization.
  • REGISTRY_ID is the ID chosen for the registry.
The response will be a JSON object with username and password properties.

Creating registry credential secrets in Kubernetes

Whenever a container registry is configured in Humanitec, any image that is hosted on that registry will cause a registry credentials secret to being injected as part of the deployment.
The registry is determined by the longest prefix match of the supplied image path.

Adding a container registry to Humanitec

  1. 1.
    Start in the Registries tab in Organization Settings.
  2. 2.
    Select the type of registry you want to add. (Note Azure Container Registry (ACR) can be added as a "Basic Container Registry".)
  3. 3.
    Choose an ID to identify this registry with. It must be a valid Humanitec ID.
  4. 4.
    Enter the root path for this registry. This should include the domain and any project paths, for example:
  5. 5.
    Enter the credentials required to access the registry:
    • For Basic registries e.g. DockerHub, JFrog Artifactory, Azure Container Registry, or Harbor, this is just a username and password. For Azure, this should be a token for a Service Principle account and with the necessary roles to access ACR.
    • For AWS Elastic Container Registry, this must be the AWS Key and AWS Secret Key for an IAM user with the permissions for the ECR registry in question.
    • For Google Container Registry (GCR), this should be a JSON static token for a user with permissions on the GCR in question.
  6. 6.
    Choose whether to expose the container registry credentials to CI pipelines.
  7. 7.
    Click the Create button to add the registry to Humanitec.
Add registry, steps 1 & 2
Add registry, steps 3 - 7
Our CLI is currently in closed beta. Please contact us if you want to learn more.
The API documentation for registries management will be updated shortly.
Adding private Docker Hub registries
Many systems treat Docker Hub registries as a special case and so will treat unqualified image paths as being hosted on Docker Hub by default. As Humanitec uses prefix matching to identify which registry a particular image path uses, it is important to set the "URL" field to include as a prefix to any private Docker Hub registry being added. For example, if you have set up an organization in Docker Hub called my-organization then the URL should be