AWS ECR#

This page provides detailed instructions for using Amazon Elastic Container Registry (ECR) with NVIDIA Cloud Functions, including credential setup, authentication requirements, and image usage.

Important

The guidance provided on this page is specifically designed for and tested with BYOC (Bring Your Own Cluster) configurations. If you are using a different deployment model, please consult with your NVIDIA representative for specific configuration requirements.

Prerequisites#

AWS Account Requirements#

You must have an AWS account with an ECR repository containing the images you want to use. The ECR repository must be accessible and contain images built for the correct architecture.

IAM Permissions for Private ECR#

Your AWS credentials must have the following IAM permissions for ECR access:

ecr:GetAuthorizationToken - Required to obtain authentication tokens
ecr:BatchGetImage - Required to pull container images
ecr:GetDownloadUrlForLayer - Required to download image layers
ecr:BatchCheckLayerAvailability - Required to check layer availability
ecr:DescribeImages - Required to retrieve metadata about container images

Here’s a minimal IAM policy for ECR pull access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchCheckLayerAvailability",
        "ecr:DescribeImages"
      ],
      "Resource": "arn:aws:ecr:<region>:<account-id>:repository/<repository-name>"
    }
  ]
}

Note

ecr:GetAuthorizationToken applies at the registry level and must use "Resource": "*". Repository-specific actions (ecr:BatchGetImage, ecr:GetDownloadUrlForLayer, ecr:BatchCheckLayerAvailability, ecr:DescribeImages) should be scoped to the specific repository ARN(s) you want to allow access to: "Resource": "arn:aws:ecr:<region>:<account-id>:repository/<repository-name>"

IAM Permissions for Public ECR#

For ECR public registries, the following IAM policy is required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr-public:GetAuthorizationToken",
        "sts:GetServiceBearerToken"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr-public:DescribeImages"
      ],
      "Resource": "arn:aws:ecr-public::<account-id>:repository/<repository-name>"
    }
  ]
}

Note

ecr-public:GetAuthorizationToken and sts:GetServiceBearerToken apply at the registry level and must use "Resource": "*". Repository-specific actions (ecr-public:DescribeImages) should be scoped to the specific repository ARN(s) you want to allow access to: "Resource": "arn:aws:ecr-public::<account-id>:repository/<repository-name>"

Note

Third party registry does not support anonymous user for ECR public registry yet.

Creating AWS Access Keys#

To create AWS access keys for ECR authentication:

Registry Hostname Patterns#

AWS ECR uses specific hostname patterns that must be followed exactly:

ECR Private registry hostname pattern:

<account_id>.dkr.ecr.<region>.amazonaws.com

Where: - <account_id> is your AWS account ID (12-digit number) - <region> is the AWS region where your ECR repository is located

Examples: - 123456789012.dkr.ecr.us-east-1.amazonaws.com - 987654321098.dkr.ecr.eu-west-1.amazonaws.com

ECR Public registry hostname pattern:

public.ecr.aws

Example: - public.ecr.aws/my-alias/my-repository:tag

Image Architecture Requirements#

NVIDIA Cloud Functions supports both amd64 (x86_64) and ARM64 architectures. For optimal compatibility across different GPU types, including GB200 which requires ARM64, you should build and push multi-platform Docker images.

To build a multi-platform image:

# Build and push multi-platform image (recommended)
docker buildx build --platform linux/amd64,linux/arm64 -t <account_id>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag> --push .

# Or build for specific architecture only
docker buildx build --platform linux/amd64 -t <account_id>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag> --push .
docker buildx build --platform linux/arm64 -t <account_id>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag> --push .

Adding Registry Credentials#

In the UI#

Navigate to the Cloud Functions console
Go to Settings → Registry Credentials
Click Add Credential

Select AWS ECR as the registry type
Enter the following information: - Hostname: Your ECR registry hostname (e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com) - Access Key ID: Your AWS Access Key ID - Secret Access Key: Your AWS Secret Access Key

Click Save to store the credentials

Note

The UI automatically normalizes the hostname format and handles credential encoding.

In the CLI#

Use the NGC CLI to create AWS ECR credentials:

For Private ECR:

export AWS_ACCOUNT_ID=<your aws account id>
export AWS_REGION=<your aws region>
export AWS_ACCESS_KEY_ID=<your aws access key id>
export AWS_SECRET_ACCESS=<your aws secret access>

#1. Add registry credential to NVCF
ngc cf registry-credential create --hostname $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com --name aws-ecr-private-credential --key $AWS_SECRET_ACCESS --aws-access-key $AWS_ACCESS_KEY_ID --type CONTAINER

#2. Use registry during function creation
# Create the function using the ECR image
ngc cf function create --inference-port 8000 --container-image $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/pytriton_echo_sample:1.0 --name aws-ecr-function --inference-url /v2/models/echo/infer

#3. For additional CLI documentation run
ngc cloud-function registry-credential create --help

For ECR Public:

export AWS_ACCESS_KEY_ID=<your aws access key id>
export AWS_SECRET_ACCESS=<your aws secret access>

#1. Add registry credential to NVCF
ngc cf registry-credential create --hostname public.ecr.aws --name aws-ecr-public-credential --key $AWS_SECRET_ACCESS --aws-access-key $AWS_ACCESS_KEY_ID --type CONTAINER

#2. Use registry during function creation
# Create the function using the ECR Public image
ngc cf function create --inference-port 8000 --container-image public.ecr.aws/<alias-or-id>/pytriton_echo_sample:1.0 --name aws-ecr-public-function --inference-url /v2/models/echo/infer

#3. For additional CLI documentation run
ngc cloud-function registry-credential create --help

In the NGC API#

Create AWS ECR credentials using the NVCF NGC API:

curl -X POST https://api.ngc.nvidia.com/v2/nvcf/registry-credentials \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registryHostname": "123456789012.dkr.ecr.us-east-1.amazonaws.com",
    "secret": {
        "name": "ecr-credential",
        "value": "QUtJQUlPU0ZBR0VYR0VST0tFWTpzZWNyZXRrZXl2YWx1ZQ=="
    },
    "artifactTypes": ["CONTAINER"]
  }'

Base64 Encoding Credentials#

For API usage, you must base64-encode your credentials in the format AccessKeyID:SecretAccessKey:

echo -n "AKIAIOSFAGEXGEROKEY:secretkeyvalue" | base64

Using Credentials#

Once you’ve added AWS ECR credentials, you can reference private images when creating or deploying functions. Use the full ECR image URI format:

<account_id>.dkr.ecr.<region>.amazonaws.com/<repository>:<tag>

Example: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

The credentials will be automatically used to authenticate with ECR when pulling images.

For detailed function creation and deployment instructions, see:

Function Creation - Creating functions with custom images

AWS ECR Container Create Function Interface

Function Deployment - Deploying functions

Troubleshooting#

Common Issues and Solutions#

Authentication Failures (401/403 errors)

Verify your AWS Access Key ID and Secret Access Key are correct
Ensure your IAM user/role has the required ECR permissions
Check that the credentials haven’t expired

Wrong Region/Hostname

Verify the ECR hostname follows the exact pattern: <account_id>.dkr.ecr.<region>.amazonaws.com
Ensure the region in the hostname matches where your ECR repository is located
Double-check your AWS account ID (12-digit number)

Image Pull Failures

Verify the image exists in the specified ECR repository
Check that the image tag is correct and accessible
Ensure the image is built for amd64 architecture (not ARM64)

Missing IAM Permissions

Verify your IAM policy includes all required ECR permissions
Check that the policy is attached to your IAM user or role
Ensure there are no explicit deny statements blocking access

AWS ECR#

Prerequisites#

AWS Account Requirements#

IAM Permissions for Private ECR#

IAM Permissions for Public ECR#

Creating AWS Access Keys#

Registry Hostname Patterns#

Image Architecture Requirements#

Adding Registry Credentials#

In the UI#

In the CLI#

In the NGC API#

Base64 Encoding Credentials#

Using Credentials#

Troubleshooting#

Common Issues and Solutions#

References#

AWS ECR Documentation#

AWS ECR#

Prerequisites#

AWS Account Requirements#

IAM Permissions for Private ECR#

IAM Permissions for Public ECR#

Creating AWS Access Keys#

Registry Hostname Patterns#

Image Architecture Requirements#

Adding Registry Credentials#

In the UI#

In the CLI#

In the NGC API#

Base64 Encoding Credentials#

Using Credentials#

Troubleshooting#

Common Issues and Solutions#

References#

AWS ECR Documentation#

Related Documentation#