Beam supports importing images from custom public and private registries.
Public Docker Registries
You can import existing images from remote Docker registries, like Docker Hub, Google Artifact Registry, ECR, GitHub Container Registry, NVIDIA and more.
Just supply a base_image
argument to Image
.
from beam import endpoint, Image
image = (
Image(
base_image="docker.io/nvidia/cuda:12.3.1-runtime-ubuntu20.04",
python_version="python3.9",
)
.add_commands(["apt-get update -y", "apt-get install neovim -y"])
.add_python_packages(["torch"])
)
@endpoint(image=image)
def handler():
import torch
return {"torch_version": torch.__version__}
Beam only supports Debian-based images. In addition, make sure your image is
built for the correct x86 architecture.
Private Docker Registries
Beam supports importing images from the following private registries: AWS ECR, Google Artifact Registry, Docker Hub, GitHub Container Registry, and NVIDIA Container Registry.
Private registries require credentials, and you can pass the credentials to Beam in two ways: as a dictionary, or exported from your shell so Beam can automatically lookup the values.
Passing Credentials as a Dictionary
You can provide the values for the registry as a dictionary directly, like this:
from beam import Image
image = Image(
base_image="111111111111.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
base_image_creds={
"AWS_ACCESS_KEY_ID": "xxxx",
"AWS_SECRET_ACCESS_KEY": "xxxx",
"AWS_REGION": "xxxx"
},
)
Passing Credentials from your Environment
Alternatively, you can export your credentials in your shell and pass the environment variable names to base_image_creds
as a list:
from beam import Image
image = Image(
base_image="111111111111.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
base_image_creds=[
"AWS_ACCESS_KEY_ID",
"AWS_SECRET_ACCESS_KEY",
"AWS_SESSION_TOKEN",
"AWS_REGION"
],
)
AWS ECR
To use a private image from Amazon ECR, export your AWS environment variables. Then configure the Image object with those environment variables.
You can authenticate with either your static AWS credentials or an AWS STS
token. If you use the AWS STS token, your AWS_SESSION_TOKEN
key must also be
set.
from beam import Image
image = Image(
python_version="python3.12",
base_image="111111111111.dkr.ecr.us-east-1.amazonaws.com/my-image:latest",
base_image_creds=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"]
)
@endpoint(image=image)
def handler():
pass
GCP Artifact Registry
To use a private image from Google Artifact Registry, export your access token.
export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token --project=my-project)
Then configure the Image object to use the environment variable.
from beam import Image
image = Image(
python_version="python3.12",
base_image="us-east4-docker.pkg.dev/my-project/my-repo/my-image:0.1.0",
base_image_creds=["GCP_ACCESS_TOKEN"]
)
@endpoint(image=image)
def handler():
pass
NVIDIA GPU Cloud (NGC)
To use a private image from NVIDIA GPU Cloud, export your API key.
export NGC_API_KEY=abc123
Then configure the Image object to use the environment variable.
from beam import Image
image = Image(
python_version="python3.12",
base_image="nvcr.io/nvidia/tensorrt:24.10-py3",
base_image_creds=["NGC_API_KEY"]
)
@endpoint(image=image)
def handler():
pass
Docker Hub
To use a private image from Docker Hub, export your Docker Hub credentials.
export DOCKERHUB_USERNAME=user123
export DOCKERHUB_PASSWORD=pass123
Then configure the Image object with those environment variables.
from beam import Image
image = Image(
python_version="python3.12",
base_image="docker.io/my-org/my-image:0.1.0",
base_image_creds=["DOCKERHUB_USERNAME", "DOCKERHUB_PASSWORD"]
)
@endpoint(image=image)
def handler():
pass
GitHub Container Registry
To use a private image from GitHub Container Registry, export your GitHub credentials. You will need a personal access token.
export GITHUB_USERNAME=user123
export GITHUB_TOKEN=token123
Then configure the Image object with those environment variables.
from beam import Image
image = Image(
python_version="python3.12",
base_image="ghcr.io/my-username/my-image:0.1.0",
base_image_creds=["GITHUB_USERNAME", "GITHUB_TOKEN"]
)
@endpoint(image=image)
def handler():
pass