# Bring your own image (BYOI)
Bring your own image (BYOI)

An image is a file that identifies the kernels, language packages, and other dependencies required to run your applications. It includes:
+ Programming languages (like Python or R)
+ Kernels
+ Libraries and packages
+ Other necessary software

Amazon SageMaker Distribution (`sagemaker-distribution`) is a set of Docker images that include popular frameworks and packages for machine learning, data science, and visualization. For more information, see [SageMaker Studio image support policy](sagemaker-distribution.md).

If you need different functionality, you can bring your own image (BYOI). You may want to create a custom image if:
+ You need a specific version of a programming language or library
+ You want to include custom tools or packages
+ You're working with specialized software not available in the standard images

## Key terminology


The following section defines key terms for bringing your own image to use with SageMaker AI.
+ **Dockerfile:** A text-based document with instructions for building a Docker image. This identifies the language packages and other dependencies for your Docker image.
+ **Docker image:** A packaged set of software and dependencies built from a Dockerfile.
+ **SageMaker AI image store:** A storage of your custom images in SageMaker AI.

**Topics**
+ [

## Key terminology
](#studio-updated-byoi-basics)
+ [

# Custom image specifications
](studio-updated-byoi-specs.md)
+ [

# How to bring your own image
](studio-updated-byoi-how-to.md)
+ [

# Launch a custom image in Studio
](studio-updated-byoi-how-to-launch.md)
+ [

# View your custom image details
](studio-updated-byoi-view-images.md)
+ [

# Speed up container startup with SOCI
](soci-indexing.md)
+ [

# Detach and clean up custom image resources
](studio-updated-byoi-how-to-detach-from-domain.md)

# Custom image specifications
Image specifications

The image that you specify in your Dockerfile must match the specifications in the following sections to create the image successfully.

**Topics**
+ [

## Running the image
](#studio-updated-byoi-specs-run)
+ [

## Specifications for the user and file system
](#studio-updated-byoi-specs-user-and-filesystem)
+ [

## Health check and URL for applications
](#studio-updated-byoi-specs-app-healthcheck)
+ [

## Dockerfile samples
](#studio-updated-byoi-specs-dockerfile-templates)

## Running the image


The following configurations can be made by updating your [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html). For an example, see [Update container configuration](studio-updated-byoi-how-to-container-configuration.md).
+ `Entrypoint` – You can configure `ContainerEntrypoint` and `ContainerArguments` that are passed to the container at runtime. We recommend configuring your entry point using `ContainerConfig`. See the above link for an example.
+ `EnvVariables` – When using Studio, you can define custom `ContainerEnvironment` variables for your container. You can optionally update your environmental variables using `ContainerConfig`. See the above link for an example.

  SageMaker AI-specific environment variables take precedence and will override any variables with the same names. For example, SageMaker AI automatically provides environment variables prefixed with `AWS_` and `SAGEMAKER_` to ensure proper integration with AWS services and SageMaker AI functionality. The following are a few example SageMaker AI-specific environment variables:
  + `AWS_ACCOUNT_ID`
  + `AWS_REGION`
  + `AWS_DEFAULT_REGION`
  + `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`
  + `SAGEMAKER_SPACE_NAME`
  + `SAGEMAKER_APP_TYPE`

## Specifications for the user and file system

+ `WorkingDirectory` – The Amazon EBS volume for your space is mounted on the path `/home/sagemaker-user`. You can't change the mount path. Use the `WORKDIR` instruction to set the working directory of your image to a folder within `/home/sagemaker-user`.
+ `UID` – The user ID of the Docker container. UID=1000 is a supported value. You can add sudo access to your users. The IDs are remapped to prevent a process running in the container from having more privileges than necessary.
+ `GID` – The group ID of the Docker container. GID=100 is a supported value. You can add sudo access to your users. The IDs are remapped to prevent a process running in the container from having more privileges than necessary.
+ Metadata directories – The `/opt/.sagemakerinternal` and `/opt/ml` directories that are used by AWS. The metadata file in `/opt/ml` contains metadata about resources such as `DomainId`.

  Use the following command to show the file system contents:

  ```
  cat /opt/ml/metadata/resource-metadata.json
  ```
+ Logging directories – `/var/log/studio` are reserved for the logging directories of your applications and the extensions associated with it. We recommend that you don't use these folders in creating your image.

## Health check and URL for applications


The health check and URL depend on the applications. Choose the following link associated with the application you are building the image for.
+ [Health check and URL for applications](code-editor-custom-images.md#code-editor-custom-images-app-healthcheck) for Code Editor
+ [Health check and URL for applications](studio-updated-jl-admin-guide-custom-images.md#studio-updated-jl-admin-guide-custom-images-app-healthcheck) for JupyterLab

## Dockerfile samples


For Dockerfile samples that meet both the requirements on this page and your specific application needs, navigate to the sample Dockerfiles in the respective application's section. The following options include Amazon SageMaker Studio applications. 
+ [Dockerfile examples](code-editor-custom-images.md#code-editor-custom-images-dockerfile-templates) for Code Editor
+ [Dockerfile examples](studio-updated-jl-admin-guide-custom-images.md#studio-updated-jl-custom-images-dockerfile-templates) for JupyterLab

**Note**  
If you are bringing your own image to SageMaker Unified Studio, you will need to follow the [Dockerfile specifications](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html) in the *Amazon SageMaker Unified Studio User Guide*.  
`Dockerfile` examples for SageMaker Unified Studio can be found in [Dockerfile example](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html#byoi-specifications-example) in the *Amazon SageMaker Unified Studio User Guide*.

# How to bring your own image
How to BYOI

The following pages will provide instructions on how to bring your own custom image. Ensure that the following prerequisites are satisfied before continuing.

## Prerequisites


You will need to complete the following prerequisites to bring your own image to Amazon SageMaker AI.
+ Set up the Docker application. For more information, see [Get started](https://docs.docker.com/get-started/) in the *Docker documentation*.
+ Install the latest AWS CLI by following the steps in [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS Command Line Interface User Guide for Version 2*.
+ Permissions to access the Amazon Elastic Container Registry (Amazon ECR) service. For more information, see [Amazon ECR Managed Policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html) in the *Amazon ECR User Guide*.
+ An AWS Identity and Access Management role that has the [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) policy attached.

**Topics**
+ [

## Prerequisites
](#studio-updated-byoi-how-to-prerequisites)
+ [

# Create a custom image and push to Amazon ECR
](studio-updated-byoi-how-to-prepare-image.md)
+ [

# Attach your custom image to your domain
](studio-updated-byoi-how-to-attach-to-domain.md)
+ [

# Update container configuration
](studio-updated-byoi-how-to-container-configuration.md)

# Create a custom image and push to Amazon ECR


This page provides instructions on how to create a local Dockerfile, build the container image, and add it to Amazon Elastic Container Registry (Amazon ECR).

**Note**  
In the following examples, the tags are not specified, and the tag `latest` is applied by default. If you would like to specify a tag, you will need to append `:tag` to end of the image names. For more information, see [docker image tag](https://docs.docker.com/reference/cli/docker/image/tag/) in the *Docker documentation*.

**Topics**
+ [

## Create a local Dockerfile and build the container image
](#studio-updated-byoi-how-to-create-local-dockerfile)
+ [

## Add a Docker image to Amazon ECR
](#studio-updated-byoi-add-container-image)

## Create a local Dockerfile and build the container image


Use the following instructions to create a Dockerfile with your desired software and dependencies.

**To create your Dockerfile**

1. First set your variables for the AWS CLI commands that follow.

   ```
   LOCAL_IMAGE_NAME=local-image-name
   ```

   `local-image-name` is the name of the container image on your local device, that you define here.

1. Create a text-based document, named `Dockerfile`, that meet the specifications in [Custom image specifications](studio-updated-byoi-specs.md).

   `Dockerfile` examples for supported applications can be found in [Dockerfile samples](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates).
**Note**  
If you are bringing your own image to SageMaker Unified Studio, you will need to follow the [Dockerfile specifications](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html) in the *Amazon SageMaker Unified Studio User Guide*.  
`Dockerfile` examples for SageMaker Unified Studio can be found in [Dockerfile example](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html#byoi-specifications-example) in the *Amazon SageMaker Unified Studio User Guide*.

1. In the directory containing your `Dockerfile`, build the Docker image using the following command. The period (`.`) specifies that the `Dockerfile` should be in the context of the build command.

   ```
   docker build -t ${LOCAL_IMAGE_NAME} .
   ```

   After the build completes, you can list your container image information with the following command.

   ```
   docker images
   ```

1. (Optional) You can test your image by using the following command.

   ```
   docker run -it ${LOCAL_IMAGE_NAME}
   ```

   In the output you will find that your server is running at a URL, like `http://127.0.0.1:8888/...`. You can test the image by copying the URL into the browser. 

   If this does not work, you may need to include `-p port:port` in the docker run command. This option maps the exposed port on the container to a port on the host system. For more information about docker run, see the [Running containers](https://docs.docker.com/engine/containers/run/) in the *Docker documentation*.

   Once you have verified that the server is working, you can stop the server and shut down all kernels before continuing. The instructions are viewable the output.

## Add a Docker image to Amazon ECR


To add a container image to Amazon ECR, you will need to do the following.
+ Create an Amazon ECR repository.
+ Log in to your default registry.
+ Push the image to the Amazon ECR repository.

**Note**  
The Amazon ECR repository must be in the same AWS Region as the domain you are attaching the image to.

**To build and push the container image to Amazon ECR**

1. First set your variables for the AWS CLI commands that follow.

   ```
   ACCOUNT_ID=account-id
   REGION=aws-region
   ECR_REPO_NAME=ecr-repository-name
   ```
   + `account-id` is your account ID. You can find this at the top right of any AWS console page. For example, the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).
   + `aws-region` is the AWS Region of your Amazon SageMaker AI domain. You can find this at the top right of any AWS console page. 
   + `ecr-repository-name` is the name of your Amazon Elastic Container Registry repository, that you define here. To view your Amazon ECR repositories, see the [Amazon ECR console](https://console.aws.amazon.com/ecr).

1. Log in to Amazon ECR and sign in to Docker.

   ```
   aws ecr get-login-password \
       --region ${REGION} | \
       docker login \
       --username AWS \
       --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com
   ```

   On a successful authentication, you will receive a succeeded log in message.
**Important**  
If you receive an error, you may need to install or upgrade to the latest version of the AWS CLI. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*.

1. Tag the image in a format compatible with Amazon ECR, to push to your repository.

   ```
   docker tag \
       ${LOCAL_IMAGE_NAME} \
       ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/${ECR_REPO_NAME}
   ```

1. Create an Amazon ECR repository using the AWS CLI. To create the repository using the Amazon ECR console, see [Creating an Amazon ECR private repository to store images](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html).

   ```
   aws ecr create-repository \
       --region ${REGION} \
       --repository-name ${ECR_REPO_NAME}
   ```

1. Push the image to your Amazon ECR repository. You can also tag the Docker image.

   ```
   docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/${ECR_REPO_NAME}
   ```

Once the image has been successfully added to your Amazon ECR repository, you can view it in the [Amazon ECR console](https://console.aws.amazon.com/ecr).

# Attach your custom image to your domain


This page provides instructions on how to attach your custom image to your domain. Use the following procedure to use the Amazon SageMaker AI console to navigate to your domain and start the **Attach image** process.

The following instructions assume that you have pushed an image to a Amazon ECR repository in the same AWS Region as your domain. If you have not already done so, see [Create a custom image and push to Amazon ECR](studio-updated-byoi-how-to-prepare-image.md).

When you choose to attach an image, you will have two options:
+ Attach a **New image**: This option will create an image and image version in your SageMaker AI image store and then attach it to your domain.
**Note**  
If you are continuing the BYOI process, from [Create a custom image and push to Amazon ECR](studio-updated-byoi-how-to-prepare-image.md), use the **New image** option.
+ Attach an **Existing image**: If you have already created your intended custom image in the SageMaker AI image store, use this option. This option attaches an existing custom image to your domain. To view your custom images in the SageMaker AI image store, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).

------
#### [ New image ]

**To attach a new image to your domain**

1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).

1. Expand the **Admin configurations** section, if not already done so.

1. Under **Admin configurations**, choose **Domains**.

1. From the list of **Domains**, select the domain you want to attach the image to.
**Note**  
If you are attaching the image to a SageMaker Unified Studio project and you need clarification on which domain to use, see [View the SageMaker AI domain details associated with your project](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain).

1. Open the **Environment** tab.

1. In the **Custom images for personal Studio apps** section, choose **Attach image**.

1. For the **Image source**, choose **New image**.

1. Include your Amazon ECR image URI. The format is as follows.

   ```
   account-id.dkr.ecr.aws-region.amazonaws.com/repository-name:tag
   ```

   1. To obtain your Amazon ECR image URI, navigate to your [Amazon ECR private repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) page.

   1. Choose your repository name link.

   1. Choose the **Copy URI** icon that corresponds to your image version (**Image tag**).

1. Follow the rest of the instructions to attach your custom image.
**Note**  
Ensure that you are using the application type consistent with your `Dockerfile`. For more information, see [Dockerfile samples](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates).

Once the image has been successfully attached to your domain, you will be able to view it in the **Environment** tab.

------
#### [ Existing image ]

**To attach an existing image to your domain**

1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).

1. Expand the **Admin configurations** section, if not already done so.

1. Under **Admin configurations**, choose **Domains**.

1. From the list of **Domains**, select the domain you want to attach the image to.
**Note**  
If you are attaching the image to a SageMaker Unified Studio project and you need clarification on which domain to use, see [View the SageMaker AI domain details associated with your project](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain).

1. Open the **Environment** tab.

1. In the **Custom images for personal Studio apps** section, choose **Attach image**.

1. For the **Image source**, choose **Existing image**.

1. Choose an existing image and image version from the SageMaker AI image store.

   If you are unable to view your image version, you may need to create an image version. For more information, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).

1. Follow the rest of the instructions to attach your custom image.
**Note**  
Ensure that you are using the application type consistent with your `Dockerfile`. For more information, see [Dockerfile samples](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates).

Once the image has been successfully attached to your domain, you will be able to view it in the **Environment** tab.

------

Once your image has been successfully attached to your domain, the domain users can choose the image for their application. For more information, see [Launch a custom image in Studio](studio-updated-byoi-how-to-launch.md).

**Note**  
If you have attached a custom image to your SageMaker Unified Studio project, you will need to launch the application from within SageMaker Unified Studio. For more information, see [Launch your custom image](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-launch-custom-image.html) in the *Amazon SageMaker Unified Studio User Guide*.

# Update container configuration


You can bring custom Docker images into your machine learning workflows. A key aspect of customizing these images is configuring the container configurations, or [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html). The following page provides an example on how to configure your `ContainerConfig`. 

An entrypoint is the command or script that runs when the container starts. Custom entrypoints enable you to set up your environment, initialize services, or perform any necessary setup before your application launches. 

This example provides instructions on how to configure a custom entrypoint, for your JupyterLab application, using the AWS CLI. This example assumes that you have already created a custom image and domain. For instructions, see [Attach your custom image to your domain](studio-updated-byoi-how-to-attach-to-domain.md).

1. First set your variables for the AWS CLI commands that follow.

   ```
   APP_IMAGE_CONFIG_NAME=app-image-config-name
   ENTRYPOINT_FILE=entrypoint-file-name
   ENV_KEY=environment-key
   ENV_VALUE=environment-value
   REGION=aws-region
   DOMAIN_ID=domain-id
   IMAGE_NAME=custom-image-name
   IMAGE_VERSION=custom-image-version
   ```
   + `app-image-config-name` is the name of your application image configuration.
   + `entrypoint-file-name` is the name of your container's entrypoint script. For example, `entrypoint.sh`.
   + `environment-key` is the name of your environment variable.
   + `environment-value` is the value assigned to your environment variable.
   + `aws-region` is the AWS Region of your Amazon SageMaker AI domain. You can find this at the top right of any AWS console page. 
   + `domain-id` is your domain ID. To view your domains, see [View domains](domain-view.md).
   + `custom-image-name` is the name of your custom image. To view your custom image details, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).

     If you followed the instructions in [Attach your custom image to your domain](studio-updated-byoi-how-to-attach-to-domain.md), you may want to use the same image name you used in that process.
   + `custom-image-version` is the version number of your custom image. This should be an integer, representing the version of your image. To view your custom image details, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).

1. Use the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAppImageConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAppImageConfig.html) API to create an image configuration.

   ```
   aws sagemaker create-app-image-config \
       --region ${REGION} \
       --app-image-config-name "${APP_IMAGE_CONFIG_NAME}" \
       --jupyter-lab-app-image-config "ContainerConfig = {
           ContainerEntrypoint = "${ENTRYPOINT_FILE}", 
           ContainerEnvironmentVariables = {
               "${ENV_KEY}"="${ENV_VALUE}"
           }
       }"
   ```

1. Use the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) API to update the default settings for your domain. This will attach the custom image as well as the application image configuration. 

   ```
   aws sagemaker update-domain \
       --region ${REGION} \
       --domain-id "${DOMAIN_ID}" \
       --default-user-settings "{
           \"JupyterLabAppSettings\": {
               \"CustomImages\": [
                   {
                       \"ImageName\": \"${IMAGE_NAME}\",
                       \"ImageVersionNumber\": ${IMAGE_VERSION},
                       \"AppImageConfigName\": \"${APP_IMAGE_CONFIG_NAME}\"
                   }
               ]
           }
       }"
   ```

# Launch a custom image in Studio


After you have attached a custom image to your Amazon SageMaker AI domain, the image becomes available to the users in the domain. Use the following instructions to launch an application with the custom image.

**Note**  
If you have attached a custom image to your SageMaker Unified Studio project, you will need to launch the application from within SageMaker Unified Studio. For more information, see [Launch your custom image](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-launch-custom-image.html) in the *Amazon SageMaker Unified Studio User Guide*.

1. Launch Amazon SageMaker Studio. For instructions, see [Launch Amazon SageMaker Studio](studio-updated-launch.md).

1. If not done so already, expand the **Applications** section.

1. Choose the application from the **Applications** section. If you do not see the application available, the application may be hidden from you. In this case, contact your administrator.

1. To create a space, choose **\$1 Create *application* space** and follow the instructions to create the space.

   To choose an existing space, choose the link name of the space you want to open.

   

1. Under **Image**, choose the image you want to use.

   If the **Image** dropdown is unavailable, you may need to stop your space. Choose **Stop space** to do so.

1. Confirm the settings for the space and choose **Run space**.

# View your custom image details


The following page provides instructions on how to view your custom image details in the SageMaker AI image store.

## View custom image details (console)


The following provides instructions on how to view your custom images using the SageMaker AI console. In this section, you can view and edit your image details.

**View your custom images (console)**

1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).

1. Expand the **Admin configurations** section.

1. Under **Admin configurations**, choose **Images**.

1. From the list of **Custom images**, select the hyperlink of your image name.

## View custom image details (AWS CLI)


The following section shows an example on how to view your custom images using the AWS CLI.

```
aws sagemaker list-images \
       --region aws-region
```

# Speed up container startup with SOCI


SOCI (Seekable Open Container Initiative) indexing enables lazy loading of custom container images in [Amazon SageMaker Studio](studio-updated.md) or [Amazon SageMaker Unified Studio](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html). SOCI significantly reduces startup times by roughly 30-70% for your custom [Bring your own image (BYOI)](studio-updated-byoi.md) containers. Latency improvement varies depending on the size of the image, hosting instance availability, and other application dependencies. SOCI creates an index that allows containers to launch with only necessary components, fetching additional files on-demand as needed.

SOCI addresses slow container startup times, that interrupt iterative machine learning (ML) development workflows, for custom images. As ML workloads become more complex, container images have grown larger, creating startup delays that hamper development cycles.

**Topics**
+ [

## Key benefits
](#soci-indexing-key-benefits)
+ [

## How SOCI indexing works
](#soci-indexing-how-works)
+ [

## Architecture components
](#soci-indexing-architecture-components)
+ [

## Supported tools
](#soci-indexing-supported-tools)
+ [

# Permissions for SOCI indexing
](soci-indexing-setup.md)
+ [

# Create SOCI indexes with nerdctl and SOCI CLI example
](soci-indexing-example-create-indexes.md)
+ [

# Integrate SOCI-indexed images with Studio example
](soci-indexing-example-integrate-studio.md)

## Key benefits

+ **Faster iteration cycles**: Reduce container startup, depending on image and instance types
+ **Universal optimization**: Extend performance benefits to all custom BYOI containers in Studio

## How SOCI indexing works


SOCI creates a specialized metadata index that maps your container image's internal file structure. This index enables access to individual files without downloading the entire image. The SOCI index is stored as an OCI (Open Container Initiative) compliant artifact in [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) and linked to your original container image, preserving image digests and signature validity.

When you launch a container in Studio, the system uses the SOCI index to identify and download only essential files needed for startup. Additional components are fetched in parallel as your application requires them.

## Architecture components

+ **Original container image**: Your base container stored in Amazon ECR
+ **SOCI index artifact**: Metadata mapping your image's file structure
+ **OCI Image Index manifest**: Links your original image and SOCI index
+ **Finch container runtime**: Enables lazy loading integration with Studio

## Supported tools



| Tool | Integration | 
| --- | --- | 
| nerdctl | Requires containerd setup | 
| Finch CLI | Native SOCI support | 
| Docker \$1 SOCI CLI | Additional tooling required | 

**Topics**
+ [

## Key benefits
](#soci-indexing-key-benefits)
+ [

## How SOCI indexing works
](#soci-indexing-how-works)
+ [

## Architecture components
](#soci-indexing-architecture-components)
+ [

## Supported tools
](#soci-indexing-supported-tools)
+ [

# Permissions for SOCI indexing
](soci-indexing-setup.md)
+ [

# Create SOCI indexes with nerdctl and SOCI CLI example
](soci-indexing-example-create-indexes.md)
+ [

# Integrate SOCI-indexed images with Studio example
](soci-indexing-example-integrate-studio.md)

# Permissions for SOCI indexing


Create SOCI indexes for your container images and store them in Amazon ECR before using SOCI indexing with [Amazon SageMaker Studio](studio-updated.md) or [Amazon SageMaker Unified Studio](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html).

**Topics**
+ [

## Prerequisites
](#soci-indexing-setup-prerequisites)
+ [

## Required IAM permissions
](#soci-indexing-setup-iam-permissions)

## Prerequisites

+ AWS account with an [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started.html) (IAM) role with permissions to manage
  + [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)
  + [Amazon SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/gs.html)
+ [Amazon ECR private repositories](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Repositories.html) for storing your container images
+ [AWS CLI v2.0\$1](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) configured with appropriate credentials
+ The following container tools:
  + Required: [soci-snapshotter](https://github.com/awslabs/soci-snapshotter)
  + Options:
    + [nerdctl](https://github.com/containerd/nerdctl)
    + [finch](https://github.com/runfinch/finch)

## Required IAM permissions


Your IAM role needs permissions to:
+ Create and manage SageMaker AI resources (domains, images, app configs).
  + You may use the [SageMakerFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFullAccess.html) AWS managed policy. For more permission details, see [AWS managed policy: AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess).
+ [IAM permissions for pushing an image to an Amazon ECR private repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-push-iam.html).

# Create SOCI indexes with nerdctl and SOCI CLI example


The following page provides an example on how to create SOCI indexes with nerdctl and SOCI CLI.

**Create SOCI indexes example**

1. First set your variables for the AWS CLI commands that follow. The following is an example of setting up your variables.

   ```
   ACCOUNT_ID="111122223333"
   REGION="us-east-1"
   REPOSITORY_NAME="repository-name"
   ORIGINAL_IMAGE_TAG="original-image-tag"
   SOCI_IMAGE_TAG="soci-indexed-image-tag"
   ```

   Variable definitions:
   + `ACCOUNT_ID` is your AWS account ID
   + `REGION` is the AWS Region of your Amazon ECR private registry
   + `REPOSITORY_NAME` is the name of your Amazon ECR private registry
   + `ORIGINAL_IMAGE_TAG` is the tag of your original image
   + `SOCI_IMAGE_TAG` is the tag of your SOCI-indexed image

1. Install required tools:

   ```
   # Install SOCI CLI, containerd, and nerdctl
   sudo yum install soci-snapshotter
   sudo yum install containerd jq  
   sudo systemctl start soci-snapshotter
   sudo systemctl restart containerd
   sudo yum install nerdctl
   ```

1. Set your registry variables:

   ```
   REGISTRY_USER=AWS
   REGISTRY="$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com"
   ```

1. Export your region and authenticate to Amazon ECR:

   ```
   export AWS_REGION=$REGION
   REGISTRY_PASSWORD=$(/usr/local/bin/aws ecr get-login-password --region $AWS_REGION)
   echo $REGISTRY_PASSWORD | sudo nerdctl login -u $REGISTRY_USER --password-stdin $REGISTRY
   ```

1. Pull your original container image:

   ```
   sudo nerdctl pull $REGISTRY/$REPOSITORY_NAME:$ORIGINAL_IMAGE_TAG
   ```

1. Create the SOCI index:

   ```
   sudo nerdctl image convert --soci $REGISTRY/$REPOSITORY_NAME:$ORIGINAL_IMAGE_TAG $REGISTRY/$REPOSITORY_NAME:$SOCI_IMAGE_TAG
   ```

1. Push the SOCI-indexed image:

   ```
   sudo nerdctl push --platform linux/amd64 $REGISTRY/$REPOSITORY_NAME:$SOCI_IMAGE_TAG
   ```

This process creates two artifacts for the original container image in your ECR repository:
+ SOCI index - Metadata enabling lazy loading
+ Image Index manifest - OCI-compliant manifest

# Integrate SOCI-indexed images with Studio example


You must reference the SOCI-indexed image tag to use SOCI-indexed images in Studio, rather than the original container image tag. Use the tag you specified during the SOCI conversion process (e.g., `SOCI_IMAGE_TAG` in the [Create SOCI indexes with nerdctl and SOCI CLI example](soci-indexing-example-create-indexes.md)).

**Integrate SOCI-indexed images example**

1. First set your variables for the AWS CLI commands that follow. The following is an example of setting up your variables.

   ```
   ACCOUNT_ID="111122223333"
   REGION="us-east-1"
   IMAGE_NAME="sagemaker-image-name"
   IMAGE_CONFIG_NAME="sagemaker-image-config-name"
   ROLE_ARN="your-role-arn"
   DOMAIN_ID="domain-id"
   SOCI_IMAGE_TAG="soci-indexed-image-tag"
   ```

   Variable definitions:
   + `ACCOUNT_ID` is your AWS account ID
   + `REGION` is the AWS Region of your Amazon ECR private registry
   + `IMAGE_NAME` is the name of your SageMaker image
   + `IMAGE_CONFIG_NAME` is the name of your SageMaker image configuration
   + `ROLE_ARN` is the ARN of your execution role with the permissions listed in [Required IAM permissions](soci-indexing-setup.md#soci-indexing-setup-iam-permissions)
   + `DOMAIN_ID` is the [domain ID](https://docs.aws.amazon.com/sagemaker/latest/dg/domain-view.html)
**Note**  
If you are attaching the image to a SageMaker Unified Studio project and you need clarification on which domain to use, see [View the SageMaker AI domain details associated with your project](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain).
   + `SOCI_IMAGE_TAG` is the tag of your SOCI-indexed image

1. Export your region:

   ```
   export AWS_REGION=$REGION
   ```

1. Create a SageMaker image:

   ```
   aws sagemaker create-image \
       --image-name "$IMAGE_NAME" \
       --role-arn "$ROLE_ARN"
   ```

1. Create a SageMaker Image Version using your SOCI index URI:

   ```
   IMAGE_INDEX_URI="$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$IMAGE_NAME:$SOCI_IMAGE_TAG"
   
   aws sagemaker create-image-version \
       --image-name "$IMAGE_NAME" \
       --base-image "$IMAGE_INDEX_URI"
   ```

1. Create an application image configuration and update your Amazon SageMaker AI domain to include the custom image for your app. You can do this for Code Editor, based on Code-OSS, Visual Studio Code - Open Source (Code Editor) and JupyterLab applications. Choose the application option below to view the steps.

------
#### [ Code Editor ]

   Create an application image configuration for Code Editor:

   ```
   aws sagemaker create-app-image-config \
       --app-image-config-name "$IMAGE_CONFIG_NAME" \
       --code-editor-app-image-config '{ "FileSystemConfig": { "MountPath": "/home/sagemaker-user", "DefaultUid": 1000, "DefaultGid": 100 } }'
   ```

   Update your Amazon SageMaker AI domain to include the custom image for Code Editor:

   ```
   aws sagemaker update-domain \
       --domain-id "$DOMAIN_ID" \
       --default-user-settings '{
           "CodeEditorAppSettings": {
           "CustomImages": [{
               "ImageName": "$IMAGE_NAME", 
               "AppImageConfigName": "$IMAGE_CONFIG_NAME"
           }]
       }
   }'
   ```

------
#### [ JupyterLab ]

   Create an application image configuration for JupyterLab:

   ```
   aws sagemaker create-app-image-config \
       --app-image-config-name "$IMAGE_CONFIG_NAME" \
       --jupyter-lab-app-image-config '{ "FileSystemConfig": { "MountPath": "/home/sagemaker-user", "DefaultUid": 1000, "DefaultGid": 100 } }'
   ```

   Update your Amazon SageMaker AI domain to include the custom image for JupyterLab:

   ```
   aws sagemaker update-domain \
       --domain-id "$DOMAIN_ID" \
       --default-user-settings '{
           "JupyterLabAppSettings": {
           "CustomImages": [{
               "ImageName": "$IMAGE_NAME", 
               "AppImageConfigName": "$IMAGE_CONFIG_NAME"
           }]
       }
   }'
   ```

------

1. After you update your domain to include your custom image, you can create an application in Studio using your custom image. When you [Launch a custom image in Studio](studio-updated-byoi-how-to-launch.md) ensure that you are using your custom image.

# Detach and clean up custom image resources


The following page provides instructions on how to detach your custom images and clean up the related resources using the Amazon SageMaker AI console or the AWS Command Line Interface (AWS CLI). 

**Important**  
You must first detach your custom image from your domain before deleting the image from the SageMaker AI image store. If not, you may experience errors while viewing your domain information or attaching new custom images to your domain.   
If you are experiencing an error loading a custom image, see [Failure to load custom image](studio-updated-troubleshooting.md#studio-updated-troubleshooting-custom-image). 

## Detach and delete custom images (console)


The following provides instructions on how to detach your custom images from SageMaker AI and clean up your custom image resources using the console.

**Detach your custom image from your domain**

1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).

1. Expand the **Admin configurations** section.

1. Under **Admin configurations**, choose **Domains**.

1. From the list of **domains**, select a domain.

1. Open the **Environment** tab.

1. For **Custom images for personal Studio apps**, select the checkboxes for the images you want to detach.

1. Choose **Detach**.

1. Follow the instructions to detach.

**Delete your custom image**

1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).

1. Expand the **Admin configurations** section, if not already done so.

1. Under **Admin configurations**, choose **Images**.

1. From the list of **Images**, select an image you would like to delete.

1. Choose **Delete**.

1. Follow the instructions to delete your image and all its versions from SageMaker AI.

**Delete your custom images and repository from Amazon ECR**
**Important**  
This will also delete any container images and artifacts in this repository.

1. Open the [Amazon ECR console](https://console.aws.amazon.com/ecr).

1. If not already done so, expand the left navigation pane.

1. Under **Private registry**, choose **Repositories**.

1. Select the repositories you wish to delete.

1. Choose **Delete**.

1. Follow the instructions to delete.

## Detach and delete custom images (AWS CLI)


The following section shows an example on how to detach your custom images using the AWS CLI.

1. First set your variables for the AWS CLI commands that follow.

   ```
   ACCOUNT_ID=account-id
   REGION=aws-region
   APP_IMAGE_CONFIG=app-image-config
   SAGEMAKER_IMAGE_NAME=custom-image-name
   ```
   + `aws-region` is the AWS Region of your Amazon SageMaker AI domain. You can find this at the top right of any AWS console page. 
   + `app-image-config` is the name of your application image configuration. Use the following AWS CLI command to list the application image configurations in your AWS Region.

     ```
     aws sagemaker list-app-image-configs \
            --region ${REGION}
     ```
   + `custom-image-name` is the custom image name. Use the following AWS CLI command to list the images in your AWS Region.

     ```
     aws sagemaker list-images \
            --region ${REGION}
     ```

1. To detach the image and image versions from your domain using these instructions, you will need to create or update a domain configuration json file.
**Note**  
If you followed the instructions in [Attach your custom image to your domain](studio-updated-byoi-how-to-attach-to-domain.md), you may have updated your domain using the file named `update-domain.json`.   
If you do not have that file, you can create a new json file instead.

   Create a file named `update-domain.json` that you will use to update your domain.

1. To delete the custom images, you will need to leave `CustomImages` blank, such that `"CustomImages": []`. Choose one of the following to view example configuration files for Code Editor or JupyterLab.

------
#### [ Code Editor: update domain configuration file example ]

   A configuration file example for Code Editor, using [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CodeEditorAppSettings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CodeEditorAppSettings.html).

   ```
   {
       "DomainId": "domain-id",
       "DefaultUserSettings": {
           "CodeEditorAppSettings": {
               "CustomImages": [
               ]
           }
       }
   }
   ```

------
#### [ JupyterLab: update domain configuration file example ]

   A configuration file example for JupyterLab, using [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_JupyterLabAppSettings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_JupyterLabAppSettings.html).

   ```
   {
       "DomainId": "domain-id",
       "DefaultUserSettings": {
           "JupyterLabAppSettings": {
               "CustomImages": [
               ]
           }
       }
   }
   ```

------

   `domain-id` is the domain ID that your image is attached to. Use the following command to list your domains.

   ```
   aws sagemaker list-domains \
         --region ${REGION}
   ```

1. Save the file.

1. Call the [update-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html) AWS CLI using the update domain configuration file, `update-domain.json`.
**Note**  
Before you can update the custom images, you must delete all of the **applications** in your domain. You **do not** need to delete user profiles or shared spaces. For instructions on deleting applications, choose one of the following options.  
If you want to use the SageMaker AI console, see [Shut down SageMaker AI resources in your domain](sm-console-domain-resources-shut-down.md).
If you want to use the AWS CLI, use steps 1 through 3 of [Delete an Amazon SageMaker AI domain (AWS CLI)](gs-studio-delete-domain.md#gs-studio-delete-domain-cli).

   ```
   aws sagemaker update-domain \
       --cli-input-json file://update-domain.json \
       --region ${REGION}
   ```

1. Delete the app image config.

   ```
   aws sagemaker delete-app-image-config \
       --app-image-config-name ${APP_IMAGE_CONFIG}
   ```

1. Delete the custom image. This also deletes all of the image versions. This does not delete the Amazon ECR container image and image versions. To do so, use the optional steps below.

   ```
   aws sagemaker delete-image \
       --image-name ${SAGEMAKER_IMAGE_NAME}
   ```

1. (Optional) Delete your Amazon ECR resources. The following list provides AWS CLI commands to obtain your Amazon ECR resource information for the steps below.

   1. Set your variables for the AWS CLI commands that follow.

      ```
      ECR_REPO_NAME=ecr-repository-name
      ```

      `ecr-repository-name` is the name of your Amazon Elastic Container Registry repository. 

      To list the details of your repositories, use the following command.

      ```
      aws ecr describe-repositories \
              --region ${REGION}
      ```

   1. Delete your repository from Amazon ECR. 
**Important**  
This will also delete any container images and artifacts in this repository.

      ```
      aws ecr delete-repository \
            --repository-name ${ECR_REPO_NAME} \
            --force \
            --region ${REGION}
      ```