Spinifex's ECR service is an AWS-compatible, OCI-compliant container registry. You create repositories with aws ecr, authenticate Docker with a registry token, and docker push / docker pull exactly as you would on AWS — and your EKS clusters can pull from it directly.

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):

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.

:::tabs @tab AWS CLI

1. Create a repository

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:

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

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

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

@tab Spinifex UI

From the left navigation open ECR → Repositories.

The ECR Repositories list in the Spinifex console, showing a repository with its registry URI, tag mutability, and creation date

1. Create a repository

Click Create Repository.
Enter the repository name and, optionally, set tag mutability (mutable or immutable).
Submit — the repository appears in the list with its full registry URI.

2. Copy the push commands

Open the repository to see its detail page. The Push commands panel lists the exact aws ecr get-login-password | docker login, docker build, docker tag, and docker push commands, pre-filled with your registry host and repository URI — use the Copy button and run them locally.

A repository detail page in the Spinifex console, with the Push commands panel showing the docker login, build, tag, and push commands

3. Manage the repository

The Permissions tab edits the repository's access policy.
The Lifecycle tab manages retention rules, and Tag immutability can be toggled from the detail page.
The Scan tab reflects that image scanning is not supported on Spinifex.
Delete a repository from the Delete action in the repositories list.

@tab Terraform

Repositories can be managed as code with the standard aws_ecr_repository resource, with the AWS provider pointed at Spinifex's ecr endpoint:

provider "aws" {
  region = "ap-southeast-2"

  endpoints {
    ecr = "https://<your-spinifex-gateway>"
    sts = "https://<your-spinifex-gateway>"
  }
}

resource "aws_ecr_repository" "my_app" {
  name = "my-app"
}

output "repository_url" {
  value = aws_ecr_repository.my_app.repository_url
}

export AWS_PROFILE=spinifex
tofu init
tofu apply

Then authenticate Docker and push using the repository_url output, following steps 2–4 in the AWS CLI tab.

:::

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.

README.md Unescape Escape

ECR (Container Registry)

Overview

Prerequisites

Instructions

1. Create a repository

2. Authenticate Docker

3. Build, tag, and push

4. Verify and pull

1. Create a repository

2. Copy the push commands

3. Manage the repository

Troubleshooting

README.md