ECR-creds-refresher

Source: Dev.to

Authentication methods for private registries

• Configure the container runtime on each node – e.g., k3s checks for the presence of /etc/rancher/k3s/registries.yaml and incorporates its settings into the containerd configuration to authenticate to the private registry.
• Use a kubelet credential provider plugin – configure the kubelet to invoke a plugin binary that dynamically fetches registry credentials.

Motivation

In this case the goal was to pull images from AWS Elastic Container Registry (ECR) without being able to modify the cluster‑level configurations mentioned above. The ecr-creds-refresher operator provides a convenient workaround.

Prerequisites

1. An AWS user or role with the necessary ECR permissions.
2. Valid AWS credentials available to the cluster (e.g., AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or temporary credentials when assuming a role).

Note: An ECR authentication token grants access to any Amazon ECR registry that the IAM principal can reach and is valid for 12 hours.

Example pod that fails without proper credentials

kubectl run test \
  --image=255656399702.dkr.ecr.us-east-1.amazonaws.com/os/alpine:latest \
  --image-pull-policy=Always \
  -- sleep 5

The pod will enter ImagePullBackOff because it cannot authenticate to the private ECR repository.

Required fixes

1. Create a secret that stores AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
2. Obtain an authentication token for ECR. This is exactly what ecr-creds-refresher automates.

How ecr-creds-refresher works

• Startup: Reads the AWS credentials from the configured secret (the secret can reside in any namespace).
• Watch: Monitors ECRPullSecret custom resources. On creation, update, or resume, it:
  1. Retrieves a fresh ECR token from AWS.
  2. Updates the secret that holds the token.
  3. Patches the default ServiceAccount in the namespaces specified by the custom resource.
• Periodic refresh: Regularly renews the ECR token and updates all relevant secrets in the desired namespaces.

Desired namespaces are the namespaces where you intend to run pods that pull images from private ECR repositories. These namespaces are configurable via the operator’s custom resource.

Demo & Repository

• Demo: 🔄 Operator 👉 demo
• Source code: ecr-creds-refresher (GitHub repository)