Skip to content
Mulgamulga

ECR (Container Registry)

Store and serve container images from Spinifex's AWS-compatible Elastic Container Registry — create a repository, authenticate Docker, push and pull images, and let your EKS workers pull from it, using the AWS CLI, the Spinifex console, or Terraform.

ecrcontainersdockerregistryoci
OverviewPrerequisitesInstructionsTroubleshooting

Overview

ECR on Spinifex serves a private container registry on the Spinifex gateway endpoint — the same host:9999 you already use for the AWS API. Authentication is account-scoped by token, so you push and pull at the gateway host and never need extra DNS:

<spinifex-gateway-host>:9999/<repository>

aws ecr describe-repositories and aws ecr get-login-password return the exact host to use — always prefer that value. Where real DNS is configured, the AWS-parity per-account host <account-id>.dkr.ecr.<region>.<your-spinifex-domain>:9999 also works.

Each repository holds image manifests and their layers. Images are stored in object storage (Predastore) in a per-account bucket, with blobs content-addressed and de-duplicated across repositories. Authentication is token-based: aws ecr get-login-password mints a short-lived bearer token that docker login uses against the registry's /v2/ endpoint.

What works today

  • Repository lifecycle — CreateRepository, DeleteRepository, DescribeRepositories.
  • OCI push and pull — blobs, manifests, and tags, including cross-repository blob mounts.
  • Token auth — GetAuthorizationToken plus bearer/basic auth on /v2/.
  • Repository policies — set, get, and delete a repository policy document.

Current limitations

  • Image scanning is not supported — scan APIs return an explicit "operation not supported" error.
  • No automatic garbage collection yet — deleting images does not yet reclaim underlying blobs.
  • Lifecycle-policy enforcement and tag-immutability enforcement are not active.

Prerequisites

  • Spinifex running, with the AWS CLI configured for the spinifex profile (see Installing Spinifex).
  • Docker installed locally to build, push, and pull images.
  • Docker trusting the Spinifex CA. The registry serves TLS signed by the Spinifex local CA. Install it into the host trust store once (Docker uses the host root pool for registry TLS, so this covers every account endpoint without per-host config):
bash
sudo cp /etc/spinifex/ca.pem /usr/local/share/ca-certificates/spinifex-local-ca.crt
sudo update-ca-certificates
sudo systemctl restart docker
  • The registry endpoint — the Spinifex gateway host:9999. aws ecr get-login-password and aws ecr describe-repositories return the exact host:port; copy it from there rather than constructing it by hand.
  • For EKS pulls: worker nodes need the AmazonEC2ContainerRegistryReadOnly policy on their node IAM role (the EKS prerequisites already include this) and network egress to the registry endpoint.

Instructions

Create a repository and push an image using your preferred tool.

1. Create a repository

bash
export AWS_PROFILE=spinifex

aws ecr create-repository --repository-name my-app
aws ecr describe-repositories --repository-names my-app \
  --query 'repositories[0].repositoryUri'

The repositoryUri is the value you tag and push to — the gateway host:9999 with the repository path, port included (for example 192.0.2.10:9999/my-app). Use it verbatim; don't hand-build a hostname.

2. Authenticate Docker

Take the registry host straight from the API so the :9999 port is correct:

bash
REGISTRY=$(aws ecr describe-repositories --repository-names my-app \
  --query 'repositories[0].repositoryUri' --output text | cut -d/ -f1)

aws ecr get-login-password --region <region> \
  | docker login --username AWS --password-stdin "$REGISTRY"

3. Build, tag, and push

bash
docker build -t my-app:latest .
docker tag my-app:latest "$REGISTRY/my-app:latest"
docker push "$REGISTRY/my-app:latest"

4. Verify and pull

bash
aws ecr describe-images --repository-name my-app
docker pull "$REGISTRY/my-app:latest"

Troubleshooting

docker login fails with an authorization error. The token is account-scoped and short-lived. Re-run aws ecr get-login-password to mint a fresh token, and confirm the registry host in docker login matches your account's endpoint (aws ecr describe-repositories returns it).

docker push cannot reach the registry. Use the exact host from aws ecr describe-repositories — the Spinifex gateway host:9999. Docker dials it directly, so the :9999 port must be present (without it docker tries :443 and fails). If you are using the AWS-parity <account-id>.dkr.ecr… hostname instead, that path needs DNS resolving it to the gateway — prefer the gateway host the API returns.

EKS workers cannot pull an image. Confirm the node IAM role has AmazonEC2ContainerRegistryReadOnly and that the workers have egress to the registry endpoint (an Internet Gateway or NAT Gateway route). See the EKS prerequisites.

Image-scanning commands return an error. Image scanning is not supported on Spinifex; the scan APIs intentionally reject these calls. Remove scan-on-push configuration from your tooling.

A pushed image still appears after deletion frees no space. Garbage collection of unreferenced blobs is not yet automatic — deleting an image removes its manifest and tags but does not immediately reclaim the underlying layers.