When your apps are run on Beam, they are attached to a custom Runtime, which you can customize with your own Image.

The Image object encapsulates the container image your code will run in.

Beam containers have two defaults to be aware of:

Default Container OS: Ubuntu 20.04

Default CUDA: CUDA 12.2

​
Adding custom base images

You can import existing images from remote Docker registries, like Dockerhub, Google Artifact Registry, ECR, Github Container Registry, Nvidia and more.

Just supply a base_image argument to Image.

from beam import App, Runtime, Image, PythonVersion

app = App(
    name="custom-image",
    runtime=Runtime(
        image=Image(
            python_version=PythonVersion.Python310, # Defaults to Python3.8 if no version is provided
            base_image="docker.io/nvidia/cuda:12.3.1-runtime-ubuntu20.04",
            python_packages=["numpy"],
            commands=["apt-get update && apt-get install -y ffmpeg"],
        )
    ),
)
Beam only supports Debian-based images.

​
Private registries

Beam includes support for pulling from private ECR registries.

To pull from an ECR registry, add your registry name to the base_image field.

​
Configure your Beam app

from beam import App, Image, Runtime, PythonVersion


app = App(
    name="ecr-example",
    runtime=Runtime(
        image=Image(
            python_version=PythonVersion.Python310, # Defaults to Python3.8 if no version is provided
            # Import base image from private ECR registry
            base_image="683656326992.dkr.ecr.us-east-1.amazonaws.com/beam-test",
            base_image_creds=Image.get_credentials_from_env(
                ["AWS_ACCESS_KEY", "AWS_SECRET_KEY", "AWS_REGION"]
            ),
        )
    ),
)

​
Add an AWS IAM role

You must create an IAM user with the following policy attached. This allows Beam to generate an authentication token to download the image from your private registry.

Your AWS IAM credentials will be used to pull your image, but they are not stored in our system.

Make sure to update the Resource below with the ARN of your desired repository.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:BatchCheckLayerAvailability"
            ],
            "Resource": "arn:aws:ecr:us-east-1:683656326989:your-ecr-repository/name"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        }
    ]
}

​
Source credentials

Beam will read your credentials from a local .env file, using the Image.get_credentials_from_env() method in the Beam SDK. Your .env file should look like this:

#!/bin/bash

export AWS_ACCESS_KEY=YOUR_KEY
export AWS_SECRET_KEY=YOUR_KEY
export AWS_REGION=YOUR_REGION

Run source .env to source the .env file to your shell.

​
Adding shell commands

You can also run any shell commands you want in the environment before it starts up. Just pass them into the commands field in your app definition.

Below, we’ll customize our image with requests and some shell commands:

from beam import App, Runtime, Image

app = App(
    name="custom-container-example",
    runtime=Runtime(
        image=Image(
            python_packages=["requests"],
            commands=["apt-get update && pip install beautifulsoup4"],
        ),
    ),
)

​
Adding Python packages

You can add Python packages to the runtime in the python_packages field:

from beam import Image

Image(
    python_version="python3.8",
    python_packages=['numpy', 'pandas'],
)
Beam will default to Python 3.8 if no python_version is provided.

Alternatively, you can pass in a path to a requirements.txt file:

from beam import Image

Image(python_packages="requirements.txt")

Was this page helpful?

Cancelling TasksGPU Acceleration