---
sidebar_label: ECR cross-account access
toc_max_heading_level: 3
doc_id: c4a21f37-8b90-4e15-b3d2-6e097f4a5c18
description: >-
  How to configure ECR cross-account pull access in nullplatform so clusters
  in different AWS accounts can pull images from a centralized ECR registry.
keywords:
  - ECR
  - cross-account
  - asset repository
  - ECR policy
  - AWS IAM
  - OpenTofu
  - container registry
---

# ECR cross-account access

If you store Docker images in a centralized ECR registry in one AWS account and run your clusters in different AWS accounts, you need to grant those accounts pull access to the registry.

Nullplatform applies the policy automatically: when an application is created, the application workflow manager attaches the configured repository policy to each new ECR repository via `SetRepositoryPolicy`. You configure that policy once in the **Asset Repository** provider settings, and it's applied consistently from that point on.

There are two ways to define which accounts get access:

- **Organization OU** (recommended): grant access to all accounts under an AWS Organizational Unit. New accounts added to the OU inherit access automatically, with no configuration changes required.
- **Account list**: explicitly enumerate the AWS account IDs. Works across AWS Organizations boundaries, but requires updating the policy each time a new account is added.

## Prerequisites

- An ECR asset repository already configured in nullplatform
- The IAM role used by nullplatform (`nullplatform-<cluster-name>-application-role`) must have the `ecr:SetRepositoryPolicy` permission. If you set up ECR using the `nullplatform/asset/ecr` OpenTofu module, this permission is already included.
- **Role**: [Ops](/docs/authorization/roles)

## Option A: Organization OU (recommended)

Use this when all accounts belong to the same AWS Organization. Any account added to the OU in the future gets pull access automatically.

Go to **Platform settings > Asset repository**, open your ECR configuration, and set the **Repository policy** field (under **Storage configuration**) to the following JSON. Replace `o-xxxxxxxxxx/*/ou-xxxx-xxxxxxxx/*` with your organization's OU path:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPull",
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:DescribeRepositories",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Condition": {
        "ForAnyValue:StringLike": {
          "aws:PrincipalOrgPaths": "o-xxxxxxxxxx/*/ou-xxxx-xxxxxxxx/*"
        }
      }
    }
  ]
}
```

:::tip
Define the policy at the OU level rather than listing individual accounts. Accounts added to the OU later inherit pull access automatically.
:::

## Option B: Account list

Use this when accounts span multiple AWS Organizations or you have a small, stable set of accounts.

Set the following variables in your `nullplatform/asset/ecr` OpenTofu module:

```hcl
module "ecr" {
  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/asset/ecr?ref=<version>"

  cluster_name = "your-cluster-name"
  nrn          = "organization=1:account=2"

  enable_cross_account_pull       = true
  repository_policy_pull_accounts = ["111122223333", "444455556666"]
}
```

`repository_policy_pull_accounts` takes the AWS account IDs of the accounts that need to pull images. You must provide at least one. The account where the ECR registry lives is always included automatically.

Run `tofu apply`. This sets the `setup.policy` field in the Asset Repository ECR provider configuration to an `aws:PrincipalAccount` policy scoped to the listed account IDs.

:::info
Both options apply the policy when a repository is created. Existing repositories are not affected. To grant access to existing repositories, attach the policy manually in the AWS console.
:::

## Next steps

- [AWS ECR configuration](/docs/providers/supported-integrations/assets-repository/ecr): ECR provider configuration reference
- [Providers overview](/docs/providers/overview): how provider inheritance and overrides work across the resource hierarchy