Skip to main content

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

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:

{
  "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:

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​