# Machine learning environments offered by Amazon SageMaker AI **Important** Amazon SageMaker Studio and Amazon SageMaker Studio Classic are two of the machine learning environments that you can use to interact with SageMaker AI. If your domain was created after November 30, 2023, Studio is your default experience. If your domain was created before November 30, 2023, Amazon SageMaker Studio Classic is your default experience. To use Studio if Amazon SageMaker Studio Classic is your default experience, see [Migration from Amazon SageMaker Studio Classic](studio-updated-migrate.md). When you migrate from Amazon SageMaker Studio Classic to Amazon SageMaker Studio, there is no loss in feature availability. Studio Classic also exists as an IDE within Amazon SageMaker Studio to help you run your legacy machine learning workflows. SageMaker AI supports the following machine learning environments: + *Amazon SageMaker Studio* (Recommended): The latest web-based experience for running ML workflows with a suite of IDEs. Studio supports the following applications: + Amazon SageMaker Studio Classic + Code Editor, based on Code-OSS, Visual Studio Code - Open Source + JupyterLab + Amazon SageMaker Canvas + RStudio + *Amazon SageMaker Studio Classic*: Lets you build, train, debug, deploy, and monitor your machine learning models. + *Amazon SageMaker Notebook Instances*: Lets you prepare and process data, and train and deploy machine learning models from a compute instance running the Jupyter Notebook application. + *Amazon SageMaker Studio Lab*: Studio Lab is a free service that gives you access to AWS compute resources, in an environment based on open-source JupyterLab, without requiring an AWS account. + *Amazon SageMaker Canvas*: Gives you the ability to use machine learning to generate predictions without needing to code. + *Amazon SageMaker geospatial*: Gives you the ability to build, train, and deploy geospatial models. + *RStudio on Amazon SageMaker AI*: RStudio is an IDE for [R](https://aws.amazon.com/blogs/opensource/getting-started-with-r-on-amazon-web-services/), with a console, syntax-highlighting editor that supports direct code execution, and tools for plotting, history, debugging and workspace management. + *SageMaker HyperPod*: SageMaker HyperPod lets you provision resilient clusters for running machine learning (ML) workloads and developing state-of-the-art models such as large language models (LLMs), diffusion models, and foundation models (FMs). To use these machine learning environments, you or your organization's administrator must create an Amazon SageMaker AI domain. The exceptions are Studio Lab, SageMaker Notebook Instances, and SageMaker HyperPod. Instead of manually provisioning resources and managing permissions for yourself and your users, you can create a Amazon DataZone domain. The process of creating a Amazon DataZone domain creates a corresponding Amazon SageMaker AI domain with AWS Glue or Amazon Redshift databases for your ETL workflows. Setting up a domain through Amazon DataZone reduces the amount of time it takes to set up SageMaker AI environments for your users. For more information about setting up a Amazon SageMaker AI domain within Amazon DataZone, see [Set up SageMaker Assets (administrator guide)](sm-assets-set-up.md). Users within the Amazon DataZone domain have permissions to all Amazon SageMaker AI actions, but their permissions are scoped down to resources within the Amazon DataZone domain. Creating a Amazon DataZone domain streamlines creating a domain that allows your users to share data and models with each other. For information about how they can share data and models, see [Controlled access to assets with Amazon SageMaker Assets](sm-assets.md). **Topics** + [ # Amazon SageMaker Studio ](studio-updated.md) + [ # SageMaker JupyterLab ](studio-updated-jl.md) + [ # Amazon SageMaker notebook instances ](nbi.md) + [ # Amazon SageMaker Studio Lab ](studio-lab.md) + [ # Amazon SageMaker Canvas ](canvas.md) + [ # Amazon SageMaker geospatial capabilities ](geospatial.md) + [ # RStudio on Amazon SageMaker AI ](rstudio.md) + [ # Code Editor in Amazon SageMaker Studio ](code-editor.md) + [ # Amazon SageMaker HyperPod ](sagemaker-hyperpod.md) + [ # Generative AI in SageMaker notebook environments ](jupyterai.md) + [ # Amazon Q Developer ](studio-updated-amazon-q.md) + [ # Amazon SageMaker Partner AI Apps overview ](partner-apps.md) # Amazon SageMaker Studio **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). Amazon SageMaker Studio is the latest web-based experience for running ML workflows. Studio offers a suite of integrated development environments (IDEs). These include Code Editor, based on Code-OSS, Visual Studio Code - Open Source, a new JupyterLab application, RStudio, and Amazon SageMaker Studio Classic. For more information, see [Applications supported in Amazon SageMaker Studio](studio-updated-apps.md). The new web-based UI in Studio is faster and provides access to all SageMaker AI resources, including jobs and endpoints, in one interface. ML practitioners can also choose their preferred IDE to accelerate ML development. A data scientist can use JupyterLab to explore data and tune models. In addition, a machine learning operations (MLOps) engineer can use Code Editor with the pipelines tool in Studio to deploy and monitor models in production. The previous Studio experience is still being supported as Amazon SageMaker Studio Classic. Studio Classic is the default experience for existing customers, and is available as an application in Studio. For more information about Studio Classic, see [Amazon SageMaker Studio Classic](studio.md). For information about how to migrate from Studio Classic to Studio, see [Migration from Amazon SageMaker Studio Classic](studio-updated-migrate.md). Studio offers the following benefits: + A new JupyterLab application that has a faster start-up time and is more reliable than the existing Studio Classic application. For more information, see [SageMaker JupyterLab](studio-updated-jl.md). + A suite of IDEs that open in a separate tab, including the new Code Editor, based on Code-OSS, Visual Studio Code - Open Source application. Users can interact with supported IDEs in a full screen experience. For more information, see [Applications supported in Amazon SageMaker Studio](studio-updated-apps.md). + Access to all of your SageMaker AI resources in one place. Studio displays running instances across all of your applications.  + Access to all training jobs in a single view, regardless of whether they were scheduled from notebooks or initiated from Amazon SageMaker JumpStart. + Simplified model deployment workflows and endpoint management and monitoring directly from Studio. You don't need to access the SageMaker AI console. + Automatic creation of all configured applications when you onboard to a domain. For information about onboarding to a domain, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). + An improved JumpStart experience where you can discover, import, register, fine tune, and deploy a foundation model. For more information, see [SageMaker JumpStart pretrained models](studio-jumpstart.md). **Topics** + [ # Launch Amazon SageMaker Studio ](studio-updated-launch.md) + [ # Amazon SageMaker Studio UI overview ](studio-updated-ui.md) + [ # Amazon EFS auto-mounting in Studio ](studio-updated-automount.md) + [ # Idle shutdown ](studio-updated-idle-shutdown.md) + [ # Applications supported in Amazon SageMaker Studio ](studio-updated-apps.md) + [ # Connect your Remote IDE to SageMaker spaces with remote access ](remote-access.md) + [ # Bring your own image (BYOI) ](studio-updated-byoi.md) + [ # Lifecycle configurations within Amazon SageMaker Studio ](studio-lifecycle-configurations.md) + [ # Amazon SageMaker Studio spaces ](studio-updated-spaces.md) + [ # Trusted identity propagation with Studio ](trustedidentitypropagation.md) + [ # Perform common UI tasks ](studio-updated-common.md) + [ # NVMe stores with Amazon SageMaker Studio ](studio-updated-nvme.md) + [ # Local mode support in Amazon SageMaker Studio ](studio-updated-local.md) + [ # View your Studio running instances, applications, and spaces ](studio-updated-running.md) + [ # Stop and delete your Studio running applications and spaces ](studio-updated-running-stop.md) + [ # SageMaker Studio image support policy ](sagemaker-distribution.md) + [ # Amazon SageMaker Studio pricing ](studio-updated-cost.md) + [ # Troubleshooting ](studio-updated-troubleshooting.md) + [ # Migration from Amazon SageMaker Studio Classic ](studio-updated-migrate.md) + [ # Amazon SageMaker Studio Classic ](studio.md) # Launch Amazon SageMaker Studio **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). This page's topics demonstrate how to launch Amazon SageMaker Studio from the Amazon SageMaker AI console and the AWS Command Line Interface (AWS CLI). **Topics** + [ ## Prerequisites ](#studio-updated-launch-prereq) + [ ## Launch from the Amazon SageMaker AI console ](#studio-updated-launch-console) + [ ## Launch using the AWS CLI ](#studio-updated-launch-cli) ## Prerequisites Before you begin, complete the following prerequisites: + Onboard to a SageMaker AI domain with Studio access. If you don't have permissions to set Studio as the default experience for your domain, contact your administrator. For more information, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). + Update the AWS CLI by following the steps in [Installing the current AWS CLI Version](https://docs.aws.amazon.com//cli/latest/userguide/install-cliv1.html#install-tool-bundled). + From your local machine, run `aws configure` and provide your AWS credentials. For information about AWS credentials, see [Understanding and getting your AWS credentials](https://docs.aws.amazon.com//general/latest/gr/aws-sec-cred-types.html). ## Launch from the Amazon SageMaker AI console Complete the following procedure to launch Studio from the Amazon SageMaker AI console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, choose Studio. 1. From the Studio landing page, select the domain and user profile for launching Studio. 1. Choose **Open Studio**. 1. To launch Studio, choose **Launch personal Studio**. ## Launch using the AWS CLI This section demonstrates how to launch Studio using the AWS CLI. The procedure to access Studio using the AWS CLI depends if the domain uses AWS Identity and Access Management (IAM) authentication or AWS IAM Identity Center authentication. You can use the AWS CLI to launch Studio by creating a presigned domain URL when your domain uses IAM authentication. For information about launching Studio with IAM Identity Center authentication, see [Use custom setup for Amazon SageMaker AI](onboard-custom.md). ### Launch if Studio is the default experience The following code snippet demonstrates how to launch Studio from the AWS CLI using a presigned domain URL if Studio is the default experience. For more information, see [create-presigned-domain-url](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-presigned-domain-url.html). ``` aws sagemaker create-presigned-domain-url \ --region region \ --domain-id domain-id \ --user-profile-name user-profile-name \ --session-expiration-duration-in-seconds 43200 ``` ### Launch if Amazon SageMaker Studio Classic is your default experience The following code snippet demonstrates how to launch Studio from the AWS CLI using a presigned domain URL if Studio Classic is the default experience. For more information, see [create-presigned-domain-url](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-presigned-domain-url.html). ``` aws sagemaker create-presigned-domain-url \ --region region \ --domain-id domain-id \ --user-profile-name user-profile-name \ --session-expiration-duration-in-seconds 43200 \ --landing-uri studio:: ``` # Amazon SageMaker Studio UI overview **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). The Amazon SageMaker Studio user interface is split into three distinct parts. This page gives information about the distinct parts and their components. + **Navigation bar**– This section of the UI includes the URL, breadcrumbs, notifications, and user options. + **Navigation pane**– This section of the UI includes a list of the applications that are supported in Studio and options for the main workflows in Studio. + **Content pane**– The main working area that displays the current page of the Studio UI that you have open. ![\[Amazon SageMaker Studio home page with navigation pane and content pane (main working area).\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/monarch/studio-updated-ui.png) **Topics** + [ ## Amazon SageMaker Studio navigation bar ](#studio-updated-ui-top) + [ ## Amazon SageMaker Studio navigation pane ](#studio-updated-ui-left) + [ ## Studio content pane ](#studio-updated-ui-working) ## Amazon SageMaker Studio navigation bar The navigation bar of the Studio UI includes the URL, breadcrumbs, notifications, and user options. **URL Structure** The URL of Studio changes as you navigate the UI. When you navigate to a different page in the UI, the URL changes to reflect that page. With the updated URL, you open any page in the Studio UI directly without navigating to the landing page first. **Breadcrumbs** As you navigate through the Studio UI, the breadcrumbs keep track of the parent pages of the current page. By choosing one of these breadcrumbs, you can navigate to parent pages in the UI. **Notifications** The notifications section of the UI gives information about important changes to Studio, updates to applications, and issues to resolve. **User options** Choose the user options icon (![\[User icon with a circular avatar placeholder and a downward-pointing arrow.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/monarch/user-settings.png)) to get information about the user profile that is currently using Studio, and gives the option to sign out of Studio.  ## Amazon SageMaker Studio navigation pane **Navigation pane** The navigation pane of the UI includes a list of the applications that are supported in Studio. It also provides options for the main workflows in Studio. This section of the UI can be used in an expanded or collapsed state. To change whether the section is expanded or collapsed, select the **Collapse** icon (![\[Square icon with "ID" text representing an identity or identification concept.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/monarch/collapse-ui.png)). **Applications** The applications section lists the applications that are available in Studio. If you choose one of the application types, you are directed to the landing page for that application. **Workflows** The list of workflows includes all of the available actions that you can take in Studio. Choose one of the options to navigate to the landing page for that workflow. If there are multiple workflows available for that option, choosing the option opens a dropdown menu where you can select the desired landing page. The following list describes the options and provides a link for more information. + **Home**– The main landing page with an overview, getting started, and what’s new. + **Running instances**– All of the instances that are currently running in Studio. For more information, see [View your Studio running instances, applications, and spaces](studio-updated-running.md). + **Data**– Data preparation options where you can collaborate to store, explore, prepare, transform, and share your data.  + For more information about Amazon SageMaker Data Wrangler, see [Data preparation](canvas-data-prep.md). + For more information about Amazon SageMaker Feature Store, see [Create, store, and share features with Feature Store](feature-store.md). + For more information about Amazon EMR clusters, see [Data preparation using Amazon EMR](studio-notebooks-emr-cluster.md). + **Auto ML**– Automatically build, train, tune, and deploy machine learning (ML) models. For more information, see [Amazon SageMaker Canvas](canvas.md). + **Experiments**– Create, manage, analyze, and compare your machine learning experiments using Amazon SageMaker Experiments. For more information, see [Amazon SageMaker Experiments in Studio Classic](experiments.md). + **Jobs**– View jobs created in Studio.  + For more information about training, see [Model training](train-model.md). + For more information about model evaluation, see [Understand options for evaluating large language models with SageMaker Clarify](clarify-foundation-model-evaluate.md). + **Pipelines**– Automate your ML workflow with Amazon SageMaker Pipelines, which provides resources to help you build, track, and manage your pipeline resources. For more information, see [Pipelines](pipelines.md). + **Models**– Organize your models into groups and collections in the model registry, where you can manage model versions, view metadata, and deploy models to production. For more information, see [Model Registration Deployment with Model Registry](model-registry.md). + **JumpStart**– Amazon SageMaker JumpStart provides pretrained, open-source models for a wide range of problem types to help you get started with machine learning. For more information, see [SageMaker JumpStart pretrained models](studio-jumpstart.md). + **Deployments**– Deploy your machine learning (ML) models for inference. + For more information about Amazon SageMaker Inference Recommender, see [Amazon SageMaker Inference Recommender](inference-recommender.md). + For more information about endpoints, see [Deploy models for inference](deploy-model.md). ## Studio content pane The main working area is also called the content pane. It displays the current page of the Studio UI that you have open. **Studio home page** The Studio home page is the primary landing page in the main working area. The home page includes two distinct tabs. There is an **Overview** tab and a **Getting started** tab. **Overview** The **Overview** tab includes options to start spaces for popular application types, get started with pre-built and automated solutions for ML workflows, and links to common tasks in the Studio UI. **Getting started** The **Getting started** tab includes information, guidance, and resources on how to begin with Studio. This includes a guided tour of the Studio UI, a link to documentation about Studio, and a selection of quick tips. # Amazon EFS auto-mounting in Studio Amazon SageMaker AI supports automatically mounting a folder in an Amazon EFS volume for each user in a domain. Using this folder, users can share data between their own private spaces. However, users cannot share data with other users in the domain. Users only have access to their own folder. The user’s folder can be accessed through a folder named `user-default-efs` . This folder is present in the `$HOME` directory of the Studio application. For information about opting out of Amazon EFS auto-mounting, see [Opt out of Amazon EFS auto-mounting](studio-updated-automount-optout.md). Amazon EFS auto-mounting also facilitates the migration of data from Studio Classic to Studio. For more information, see [(Optional) Migrate data from Studio Classic to Studio](studio-updated-migrate-data.md). **Access point information** When auto-mounting is activated, SageMaker AI uses an Amazon EFS access point to facilitate access to the data in the Amazon EFS volume. For more information about access points, see [Working with Amazon EFS access points](https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html) SageMaker AI creates a unique access point for each user profile in the domain during user profile creation or during application creation for an existing user profile. The POSIX user value of the access point matches the `HomeEfsFileSystemUid` value of the user profile that SageMaker AI creates the access point for. To get the value of the user, see [DescribeUserProfile](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeUserProfile.html#sagemaker-DescribeUserProfile-response-HomeEfsFileSystemUid). The root directory path is also set to the same value as the POSIX user value.  SageMaker AI sets the permissions of the new directory to the following values: + Owner user ID: `POSIX user value` + Owner group ID: `0` + Permissions `700` The access point is required to access the Amazon EFS volume. As a result, you cannot delete or update the access point without losing access to the Amazon EFS volume. **Error resolution** If SageMaker AI encounters an issue when auto-mounting the Amazon EFS user folder during application creation, the application is still created. However, in this case, SageMaker AI creates a file named `error.txt` instead of mounting the Amazon EFS folder. This file describes the error encountered, as well as steps to resolve it. SageMaker AI creates the `error.txt` file in the `user-default-efs` folder located in the `$HOME` directory of the application. # Opt out of Amazon EFS auto-mounting You can opt-out of Amazon SageMaker AI auto-mounting Amazon EFS user folders during domain and user profile creation or for an existing domain or user profile. ## Opt out during domain creation You can opt out of Amazon EFS auto-mounting when creating a domain using either the console or the AWS Command Line Interface. ### Console Complete the following steps to opt out of Amazon EFS auto-mounting when creating a domain from the console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. Complete the steps in [Use custom setup for Amazon SageMaker AI](onboard-custom.md) with the following modification to set up a domain. + On the **Configure storage** step, turn off **Automatically mount EFS storage and data**. ### AWS CLI Use the following command to opt out of Amazon EFS auto-mounting during domain creation using the AWS CLI. For more information about creating a domain using the AWS CLI, see [Use custom setup for Amazon SageMaker AI](onboard-custom.md). ``` aws --region region sagemaker create-domain \ --domain-name "my-domain-$(date +%s)" \ --vpc-id default-vpc-id \ --subnet-ids subnet-ids \ --auth-mode IAM \ --default-user-settings "ExecutionRole=execution-role-arn,AutoMountHomeEFS=Disabled" \ --default-space-settings "ExecutionRole=execution-role-arn" ``` ## Opt out for an existing domain You can opt out of Amazon EFS auto-mounting for an existing domain using either the console or the AWS CLI. ### Console Complete the following steps to opt out of Amazon EFS auto-mounting when updating a domain from the console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation under **Admin configurations**, choose **Domains**. 1. On the **Domains** page, select the domain that you want to opt out of Amazon EFS auto-mounting for. 1. On the **Domain details** page, select the **Domain settings** tab. 1. Navigate to the **Storage configurations** section. 1. Select **Edit**. 1. From the **Edit storage settings** page, turn off **Automatically mount EFS storage and data**. 1. Select **Submit**. ### AWS CLI Use the following command to opt out of Amazon EFS auto-mounting while updating an existing domain using the AWS CLI. ``` aws --region region sagemaker update-domain \ --domain-id domain-id \ --default-user-settings "AutoMountHomeEFS=Disabled" ``` ## Opt out during user profile creation You can opt out of Amazon EFS auto-mounting when creating a user profile using either the console or the AWS CLI. ### Console Complete the following steps to opt out of Amazon EFS auto-mounting when creating a user profile from the console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. Complete the steps in [Add user profiles](domain-user-profile-add.md) with the following modification to create a user profile. + On the **Data and Storage** step, turn off **Inherit settings from domain**. This allows the user to have a different value than the defaults that are set for the domain.  + Turn off **Automatically mount EFS storage and data**. ### AWS CLI Use the following command to opt out of Amazon EFS auto-mounting during user profile creation using the AWS CLI. For more information about creating a user profile using the AWS CLI, see [Add user profiles](domain-user-profile-add.md). ``` aws --region region sagemaker create-user-profile \ --domain-id domain-id \ --user-profile-name "user-profile-$(date +%s)" \ --user-settings "ExecutionRole=arn:aws:iam::account-id:role/execution-role-name,AutoMountHomeEFS=Enabled/Disabled/DefaultAsDomain" ``` ## Opt out for an existing user profile You can opt out of Amazon EFS auto-mounting for an existing user profile using either the console or the AWS CLI. ### Console Complete the following steps to opt out of Amazon EFS auto-mounting when updating a user profile from the console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation under **Admin configurations**, choose **Domains**. 1. On the **Domains** page, select the domain containing the user profile that you want to opt out of Amazon EFS auto-mounting for. 1. On the **Domains details** page, select the **User profiles** tab. 1. Select the user profile to update. 1. From the **User Details** tab, navigate to the **AutoMountHomeEFS** section. 1. Select **Edit**. 1. From the **Edit storage settings** page, turn off **Inherit settings from domain**. This allows the user to have a different value than the defaults that are set for the domain.  1. Turn off **Automatically mount EFS storage and data**. 1. Select **Submit**. ### AWS CLI Use the following command to opt out of Amazon EFS auto-mounting while updating an existing user profile using the AWS CLI. ``` aws --region region sagemaker update-user-profile \ --domain-id domain-id \ --user-profile-name user-profile-name \ --user-settings "AutoMountHomeEFS=DefaultAsDomain" ``` # Idle shutdown Amazon SageMaker AI supports shutting down idle resources to manage costs and prevent cost overruns due to cost accrued by idle, billable resources. It accomplishes this by detecting an app’s idle state and performing an app shutdown when idle criteria are met. SageMaker AI supports idle shutdown for the following applications. Idle shutdown must be set for each application type independently. + JupyterLab + Code Editor, based on Code-OSS, Visual Studio Code - Open Source Idle shutdown can be set at either the domain or user profile level. When idle shutdown is set at the domain level, the idle shutdown settings apply to all applications created in the domain. When set at the user profile level, the idle shutdown settings apply only to the specific users that they are set for. User profile settings override domain settings.  **Note** Idle shutdown requires the usage of the `SageMaker-distribution` (SMD) image with v2.0 or newer. Domains using an older SMD version can’t use the feature. These users must use an LCC to manage auto-shutdown instead. ## Definition of idle Idle shutdown settings only apply when the application becomes idle with no jobs running. SageMaker AI doesn’t start the idle shutdown timing until the instance becomes idle. The definition on idle differs based on whether the application type is JupyterLab or Code Editor. For JupyterLab applications, the instance is considered idle when the following conditions are met: + No active Jupyter kernel sessions + No active Jupyter terminal sessions For Code Editor applications, the instance is considered idle when the following conditions are met: + No text file or notebook changes + No files being viewed + No interaction with the terminal # Set up idle shutdown The following sections show how to set up idle shutdown from either the console or using the AWS CLI. Idle shutdown can be set at either the domain or user profile level. ## Prerequisites To use idle shutdown with your application, you must complete the following prerequisites. + Ensure that your application is using the SageMaker Distribution (SMD) version 2.0. You can select this version during application creation or update the image version of the application after creation. For more information, see [Update the SageMaker Distribution Image](studio-updated-jl-update-distribution-image.md) . + For applications built with custom images, idle shutdown is supported if your custom image is created with SageMaker Distribution (SMD) version 2.0 or later as the base image. If the custom image is created with a different base image, then you must install the [jupyter-activity-monitor-extension >= 0.3.1](https://anaconda.org/conda-forge/jupyter-activity-monitor-extension) extension on the image and attach the image to your Amazon SageMaker AI domain for JupyterLab applications. For more information about custom images, see [Bring your own image (BYOI)](studio-updated-byoi.md). ## From the Console The following sections show how to enable idle shutdown from the console. ### Add when creating a new domain 1. Create a domain by following the steps in [Use custom setup for Amazon SageMaker AI](onboard-custom.md) 1. When configuring the application settings in the domain, navigate to either the Code Editor or JupyterLab section.  1. Select **Enable idle shutdown**. 1. Enter a default idle shutdown time in minutes. This values defaults to `10,080` if no value is entered. 1. (Optional) Select **Allow users to set custom idle shutdown time** to allow users to modify the idle shutdown time. + Enter a maximum value that users can set the default idle shutdown time to. You must enter a maximum value. The minimum value is set by Amazon SageMaker AI and must be `60`. ### Add to an existing domain **Note** If idle shutdown is set when applications are running, they must be restarted for idle shutdown settings to take effect. 1. Navigate to the domain. 1. Choose the **App Configurations** tab. 1. From the **App Configurations** tab, navigate to either the Code Editor or JupyterLab section. 1. Select **Edit**. 1. Select **Enable idle shutdown**. 1. Enter a default idle shutdown time in minutes. This values defaults to `10,080` if no value is entered. 1. (Optional) Select **Allow users to set custom idle shutdown time** to allow users to modify the idle shutdown time. + Enter a maximum value that users can set the default idle shutdown time to. You must enter a maximum value. The minimum value is set by Amazon SageMaker AI and must be `60`. 1. Select **Submit**. ### Add when creating a new user profile 1. Add a user profile by following the steps at [Add user profiles](domain-user-profile-add.md) 1. When configuring the application settings for the user profile, navigate to either the Code Editor or JupyterLab section. 1. Select **Enable idle shutdown**. 1. Enter a default idle shutdown time in minutes. This values defaults to `10,080` if no value is entered. 1. (Optional) Select **Allow users to set custom idle shutdown time** to allow users to modify the idle shutdown time. + Enter a maximum value that users can set the default idle shutdown time to. You must enter a maximum value. The minimum value is set by Amazon SageMaker AI and must be `60`. 1. Select “Save Changes”. ### Add to an existing user profile Note: If idle shutdown is set when applications are running, they must be restarted for idle shutdown settings to take effect. 1. Navigate to the user profile. 1. Choose the **App Configurations** tab. 1. From the ****App Configurations**** tab, navigate to either the Code Editor or JupyterLab section.  1. Select **Edit**. 1. Idle shutdown settings will show domain settings by default if configured for the domain. 1. Select **Enable idle shutdown**. 1. Enter a default idle shutdown time in minutes. This values defaults to `10,080` if no value is entered. 1. (Optional) Select **Allow users to set custom idle shutdown time** to allow users to modify the idle shutdown time. + Enter a maximum value that users can set the default idle shutdown time to. You must enter a maximum value. The minimum value is set by Amazon SageMaker AI and must be `60`. 1. Select **Save Changes**. ## From the AWS CLI The following sections show how to enable idle shutdown using the AWS CLI. **Note** To enforce a specific timeout value from the AWS CLI, you must set `IdleTimeoutInMinutes`, `MaxIdleTimeoutInMinutes`, and `MinIdleTimeoutInMinutes` to the same value. ### Domain The following command shows how to enable idle shutdown when updating an existing domain. To add idle shutdown for a new domain, use the `create-domain` command instead. **Note** If idle shutdown is set when applications are running, they must be restarted for idle shutdown settings to take effect. ``` aws sagemaker update-domain --region region --domain-id domain-id \ --default-user-settings file://default-user-settings.json ## default-user-settings.json example for enforcing the default timeout { "JupyterLabAppSettings": { "AppLifecycleManagement": { "IdleSettings": { "LifecycleManagement": "ENABLED", "IdleTimeoutInMinutes": 120, "MaxIdleTimeoutInMinutes": 120, "MinIdleTimeoutInMinutes": 120 } } } ## default-user-settings.json example for letting users customize the default timeout, between 2-5 hours { "JupyterLabAppSettings": { "AppLifecycleManagement": { "IdleSettings": { "LifecycleManagement": "ENABLED", "IdleTimeoutInMinutes": 120, "MinIdleTimeoutInMinutes": 120, "MaxIdleTimeoutInMinutes": 300 } } } ``` ### User profile The following command shows how to enable idle shutdown when updating an existing user profile. To add idle shutdown for a new user profile, use the `create-user-profile` command instead. **Note** If idle shutdown is set when applications are running, they must be restarted for idle shutdown settings to take effect. ``` aws sagemaker update-user-profile --region region --domain-id domain-id \ --user-profile-name user-profile-name --user-settings file://user-settings.json ## user-settings.json example for enforcing the default timeout { "JupyterLabAppSettings": { "AppLifecycleManagement": { "IdleSettings": { "LifecycleManagement": "ENABLED", "IdleTimeoutInMinutes": 120, "MaxIdleTimeoutInMinutes": 120, "MinIdleTimeoutInMinutes": 120 } } } ## user-settings.json example for letting users customize the default timeout, between 2-5 hours { "JupyterLabAppSettings": { "AppLifecycleManagement": { "IdleSettings": { "LifecycleManagement": "ENABLED", "IdleTimeoutInMinutes": 120, "MinIdleTimeoutInMinutes": 120, "MaxIdleTimeoutInMinutes": 300 } } } ``` # Update default idle shutdown settings You can update the default idle shutdown settings at either the domain or user profile level. **Note** If idle shutdown is set when applications are running, they must be restarted for idle shutdown settings to take effect. ## Update domain settings 1. Navigate to the domain. 1. Choose the **App Configurations** tab. 1. From the **App Configurations** tab, navigate to either the Code Editor or JupyterLab section.  1. In the section for the application that you want to modify the idle shutdown time limit for, select **Edit**. 1. Update the idle shutdown settings for the domain. 1. Select **Save Changes**. ## Update user profile settings 1. Navigate to the domain. 1. Choose the **User profiles** tab. 1. From the **User profiles** tab, select the user profile to edit. 1. From the **User profile** page, choose the **Applications** tab. 1. On the **Applications** tab, navigate to either the Code Editor or JupyterLab section.  1. In the section for the application that you want to modify the idle shutdown time limit for, select **Edit**. 1. Update the idle shutdown settings for the user profile. 1. Select **Save Changes**. # Modify your idle shutdown time limit Users may be able to modify the idle shutdown time limit if the admin gives access when adding support for idle shutdown. If support for idle shutdown is added, there may be a limit applied to the maximum time for idle shutdown. A user can set the value anywhere between the lower limit and upper limit. 1. Launch Amazon SageMaker Studio by following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. From the **Applications** section, select the application type to update the idle shutdown time for. 1. Select the space to update. 1. Update **Idle shutdown (mins)** with your desired value. **Note** If idle shutdown is set when applications are running, they must be restarted for idle shutdown settings to take effect. # Applications supported in Amazon SageMaker Studio **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). Amazon SageMaker Studio supports the following applications: + **Code Editor, based on Code-OSS, Visual Studio Code - Open Source**– Code Editor offers a lightweight and powerful integrated development environment (IDE) with familiar shortcuts, terminal, and advanced debugging capabilities and refactoring tools. It is a fully managed, browser-based application in Studio. For more information, see [Code Editor in Amazon SageMaker Studio](code-editor.md). + **Amazon SageMaker Studio Classic**– Amazon SageMaker Studio Classic is a web-based IDE for machine learning. With Studio Classic, you can build, train, debug, deploy, and monitor your machine learning models. For more information, see [Amazon SageMaker Studio Classic](studio.md). + **JupyterLab**–JupyterLab offers a set of capabilities that augment the fully managed notebook offering. It includes kernels that start in seconds, a pre-configured runtime with popular data science, machine learning frameworks, and high performance block storage. For more information, see [SageMaker JupyterLab](studio-updated-jl.md). + **Amazon SageMaker Canvas**– With SageMaker Canvas, you can use machine learning to generate predictions without writing code. With Canvas, you can chat with popular large language models (LLMs), access ready-to-use models, or build a custom model that's trained on your data. For more information, see [Amazon SageMaker Canvas](canvas.md). + **RStudio**– RStudio is an integrated development environment for R. It includes a console and syntax-highlighting editor that supports running code directly. It also includes tools for plotting, history, debugging, and workspace management. For more information, see [RStudio on Amazon SageMaker AI](rstudio.md). # Connect your Remote IDE to SageMaker spaces with remote access You can remotely connect from your Remote IDE to Amazon SageMaker Studio spaces. You can use your customized local IDE setup, including AI-assisted development tools and custom extensions, with the scalable compute resources in Amazon SageMaker AI. This guide provides concepts and setup instructions for administrators and users. A Remote IDE connection establishes a secure connection between your local IDE and SageMaker spaces. This connection lets you: + **Access SageMaker AI compute resources** — Run code on scalable SageMaker AI infrastructure from your local environment + **Maintain security boundaries** — Work within the same security framework as SageMaker AI + **Keep your familiar IDE experience** — Use compatible local extensions, themes, and configurations that support remote development **Note** Not all IDE extensions are compatible with remote development. Extensions that require local GUI components, have architecture dependencies, or need specific client-server interactions may not work properly in the remote environment. Verify that your required extensions support remote development before use. **Topics** + [ ## Key concepts ](#remote-access-key-concepts) + [ ## Connection methods ](#remote-access-connection-methods) + [ ## Supported IDEs ](#remote-access-supported-ides) + [ ## IDE version requirements ](#remote-access-ide-version-requirements) + [ ## Operating system requirements ](#remote-access-os-requirements) + [ ## Local machine prerequisites ](#remote-access-local-prerequisites) + [ ## Image requirements ](#remote-access-image-requirements) + [ ## Instance requirements ](#remote-access-instance-requirements) + [ # Set up remote access ](remote-access-remote-setup.md) + [ # Set up Remote IDE ](remote-access-local-ide-setup.md) + [ # Supported AWS Regions ](remote-access-supported-regions.md) ## Key concepts + **Remote connection** — A secure tunnel between your Remote IDE and a SageMaker space. This connection enables interactive development and code execution using SageMaker AI compute resources. + [https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-spaces.html](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-spaces.html) — A dedicated environment within Amazon SageMaker Studio where you can manage your storage and resources for your Studio applications. + **Deep link** — A button (direct URL) from the SageMaker UI that initiates a remote connection to your local IDE. ## Connection methods There are three main ways to connect your Remote IDE to SageMaker spaces: + **Deep link access** — You can connect directly to a specific space by using the **Open space with** button available in SageMaker AI. This uses URL patterns to establish a remote connection and open your SageMaker space in your Remote IDE. + [https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/welcome.html](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/welcome.html) — You can authenticate with AWS Toolkit for Visual Studio Code. This allows you to connect to spaces and open a remotely connected window from your Remote IDE. + **SSH terminal connection** — You can connect via command line using SSH configuration. ## Supported IDEs Remote connection to Studio spaces supports: + [Visual Studio Code](https://code.visualstudio.com/) + [Kiro](https://kiro.dev/) + [Cursor](https://cursor.com/home) ## IDE version requirements The following table lists the minimum version requirements for each supported Remote IDE. | IDE | Minimum version | | --- | --- | | Visual Studio Code | [v1.90](https://code.visualstudio.com/updates/v1_90) or greater. We recommend using the [latest stable version](https://code.visualstudio.com/updates). | | Kiro | v0.10.78 or greater | | Cursor | v2.6.18 or greater | The AWS Toolkit extension is required to connect your Remote IDE to Studio spaces. For Kiro and Cursor, AWS Toolkit extension version v3.100 or greater is required. ## Operating system requirements You need one of the following operating systems to remotely connect to Studio spaces: + macOS 13\$1 + Windows 10 + [Windows 10 support ends on October 14, 2025](https://support.microsoft.com/en-us/windows/windows-10-support-ends-on-october-14-2025-2ca8b313-1946-43d3-b55c-2b95b107f281) + Windows 11 + Linux + For VS Code, install the official [Microsoft VS Code for Linux](https://code.visualstudio.com/docs/setup/linux), not an open-source version ## Local machine prerequisites Before connecting your Remote IDE to Studio spaces, ensure your local machine has the required dependencies and network access. **Important** Environments with software installation restrictions may prevent users from installing required dependencies. The AWS Toolkit for Visual Studio Code automatically searches for these dependencies when initiating remote connections and will prompt for installation if any are missing. Coordinate with your IT department to ensure these components are available. **Required local dependencies** Your local machine must have the following components installed: + **[Remote-SSH Extension](https://code.visualstudio.com/docs/remote/ssh)** — Remote development extension for your IDE (available in the extension marketplace for VS Code, Kiro, and Cursor) + **[Session Manager plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)** — Required for secure session management + **SSH Client** — Standard component on most machines ([OpenSSH recommended for Windows](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)) + **IDE CLI Command** — Typically included with IDE installation (for example, `code` for VS Code, `kiro` for Kiro, `cursor` for Cursor) **Platform-specific requirements** + **Windows users** — PowerShell 5.1 or later is required for SSH terminal connections **Network connectivity requirements** Your local machine must have network access to [Session Manager endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html). For example, in US East (N. Virginia) (us-east-1) these can be: + ssm.us-east-1.amazonaws.com + ssm.us-east-1.api.aws + ssmmessages.us-east-1.amazonaws.com + ec2messages.us-east-1.amazonaws.com ## Image requirements **SageMaker Distribution images** When using SageMaker Distribution with remote access, use [SageMaker Distribution](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-distribution.html) version 2.7 or later. **Custom images** When you [Bring your own image (BYOI)](studio-updated-byoi.md) with remote access, ensure that you follow the [custom image specifications](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-byoi-specs.html) and ensure the following dependencies are installed: + `curl` or `wget` — Required for downloading AWS CLI components + `unzip` — Required for extracting AWS CLI installation files + `tar` — Required for archive extraction + `gzip` — Required for compressed file handling ## Instance requirements + **Memory** — 8GB or more + **Instance types** — Use instances with at least 8GB of memory. The following instance types are *not* supported due to insufficient memory (less than 8GB): `ml.t3.medium`, `ml.c7i.large`, `ml.c6i.large`, `ml.c6id.large`, and `ml.c5.large`. For a more complete list of instance types, see the [Amazon EC2 On-Demand Pricing page](https://aws.amazon.com/ec2/pricing/on-demand/). **Topics** + [ ## Key concepts ](#remote-access-key-concepts) + [ ## Connection methods ](#remote-access-connection-methods) + [ ## Supported IDEs ](#remote-access-supported-ides) + [ ## IDE version requirements ](#remote-access-ide-version-requirements) + [ ## Operating system requirements ](#remote-access-os-requirements) + [ ## Local machine prerequisites ](#remote-access-local-prerequisites) + [ ## Image requirements ](#remote-access-image-requirements) + [ ## Instance requirements ](#remote-access-instance-requirements) + [ # Set up remote access ](remote-access-remote-setup.md) + [ # Set up Remote IDE ](remote-access-local-ide-setup.md) + [ # Supported AWS Regions ](remote-access-supported-regions.md) # Set up remote access Before users can connect their Remote IDE to Studio spaces, the administrator must configure permissions. This section provides instructions for administrators on how to set up their Amazon SageMaker AI domain with remote access. Different connection methods require different IAM permissions. Configure the appropriate permissions based on how your users will connect. Use the following workflow along with the permissions aligned with the connection method. **Important** Currently remote IDE connections are authenticated using IAM credentials, not IAM Identity Center. This applies for domains that use the IAM Identity Center [authentication method](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-custom.html#onboard-custom-authentication-details) for your users to access the domain. If you prefer not to use IAM authentication for remote connections, you can opt-out by disabling this feature using the `RemoteAccess` conditional key in your IAM policies. For more information, see [Remote access enforcement](remote-access-remote-setup-abac.md#remote-access-remote-setup-abac-remote-access-enforcement). When using IAM credentials, Remote IDE connections may maintain active sessions even after you log out of your IAM Identity Center session. Sometimes, these Remote IDE connections can persist for up to 12 hours. To ensure the security of your environment, administrators must review session duration settings where possible and be cautious when using shared workstations or public networks. 1. Choose one of the following connection method permissions that align with your users’ [Connection methods](remote-access.md#remote-access-connection-methods). 1. [Create a custom IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) based on the connection method permission. **Topics** + [ ## Step 1: Configure security and permissions ](#remote-access-remote-setup-permissions) + [ ## Step 2: Enable remote access for your space ](#remote-access-remote-setup-enable) + [ # Advanced access control ](remote-access-remote-setup-abac.md) + [ # Set up Studio to run with subnets without internet access within a VPC ](remote-access-remote-setup-vpc-subnets-without-internet-access.md) + [ # Set up automated Studio space filtering when using the AWS Toolkit ](remote-access-remote-setup-filter.md) ## Step 1: Configure security and permissions **Topics** + [ ### Method 1: Deep link permissions ](#remote-access-remote-setup-method-1-deep-link-permissions) + [ ### Method 2: AWS Toolkit permissions ](#remote-access-remote-setup-method-2-aws-toolkit-permissions) + [ ### Method 3: SSH terminal permissions ](#remote-access-remote-setup-method-3-ssh-terminal-permissions) **Important** Using broad permissions for `sagemaker:StartSession`, especially with a wildcard resource `*` creates the risk that any user with this permission can initiate a session against any SageMaker Space app in the account. This can lead to the impact of data scientists unintentionally accessing other users’ SageMaker Spaces. For production environments, you should scope down these permissions to specific space ARNs to enforce the principle of least privilege. See [Advanced access control](remote-access-remote-setup-abac.md) for examples of more granular permission policies using resource ARNs, tags, and network-based constraints. ### Method 1: Deep link permissions For users connecting via deep links from the SageMaker UI, use the following permission and attach it to your SageMaker AI [space execution role](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html#sagemaker-roles-get-execution-role-space) or [domain execution role](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html#sagemaker-roles-get-execution-role). If the space execution role is not configured, the domain execution role is used by default. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RestrictStartSessionOnSpacesToUserProfile", "Effect": "Allow", "Action": [ "sagemaker:StartSession" ], "Resource": "arn:*:sagemaker:*:*:space/${sagemaker:DomainId}/*", "Condition": { "ArnLike": { "sagemaker:ResourceTag/sagemaker:user-profile-arn": "arn:aws:sagemaker:*:*:user-profile/${sagemaker:DomainId}/${sagemaker:UserProfileName}" } } } ] } ``` ------ ### Method 2: AWS Toolkit permissions For users connecting through the AWS Toolkit for Visual Studio Code extension, attach the following policy to one of the following: + For IAM authentication, attach this policy to the IAM user or role + For IdC authentication, attach this policy to the [Permission sets](https://docs.aws.amazon.com/singlesignon/latest/userguide/permissionsetsconcept.html) managed by the IdC To show only spaces relevant to the authenticated user, see [Filtering overview](remote-access-remote-setup-filter.md#remote-access-remote-setup-filter-overview). **Important** The following policy using `*` as the resource constraint is only recommended for quick testing purposes. For production environments, you should scope down these permissions to specific space ARNs to enforce the principle of least privilege. See [Advanced access control](remote-access-remote-setup-abac.md) for examples of more granular permission policies using resource ARNs, tags, and network-based constraints. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sagemaker:ListSpaces", "sagemaker:DescribeSpace", "sagemaker:ListApps", "sagemaker:DescribeApp", "sagemaker:DescribeDomain", "sagemaker:UpdateSpace", "sagemaker:CreateApp", "sagemaker:DeleteApp", "sagemaker:AddTags" ], "Resource": "*" }, { "Sid": "AllowStartSessionOnSpaces", "Effect": "Allow", "Action": "sagemaker:StartSession", "Resource": [ "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/space-name-1", "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/space-name-2" ] } ] } ``` ------ ### Method 3: SSH terminal permissions For SSH terminal connections, the `StartSession` API is called by the SSH proxy command script below, using the local AWS credentials. See [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) for information and instructions on setting up the user's local AWS credentials. To use these permissions: 1. Attach this policy to the IAM user or role associated with the local AWS credentials. 1. If using a named credential profile, modify the proxy command in your SSH config: ``` ProxyCommand '/home/user/sagemaker_connect.sh' '%h' YOUR_CREDENTIAL_PROFILE_NAME ``` **Note** The policy needs to be attached to the IAM identity (user/role) used in your local AWS credentials configuration, not to the Amazon SageMaker AI domain execution role. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowStartSessionOnSpecificSpaces", "Effect": "Allow", "Action": "sagemaker:StartSession", "Resource": [ "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/space-name-1", "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/space-name-2" ] } ] } ``` ------ After setup, users can run `ssh my_studio_space_abc` to start up the space. For more information, see [Method 3: Connect from the terminal via SSH CLI](remote-access-local-ide-setup.md#remote-access-local-ide-setup-local-vs-code-method-3-connect-from-the-terminal-via-ssh-cli). ## Step 2: Enable remote access for your space After you set up the permissions, you must toggle on **Remote Access** and start your space in Studio before the user can connect using their Remote IDE. This setup only needs to be done once. **Note** If your users are connecting using [Method 2: AWS Toolkit permissions](#remote-access-remote-setup-method-2-aws-toolkit-permissions), you do not necessarily need this step. AWS Toolkit for Visual Studio users can enable remote access from the Toolkit. **Activate remote access for your Studio space** 1. [Launch Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-launch.html#studio-updated-launch-console). 1. Open the Studio UI. 1. Navigate to your space. 1. In the space details, toggle on **Remote Access**. 1. Choose **Run space**. # Advanced access control Amazon SageMaker AI supports [attribute-based access control (ABAC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) to achieve fine-grained access control for Remote IDE connections using ABAC policies. The following are example ABAC policies for Remote IDE connections. **Topics** + [ ## Remote access enforcement ](#remote-access-remote-setup-abac-remote-access-enforcement) + [ ## Tag-based access control ](#remote-access-remote-setup-abac-tag-based-access-control) ## Remote access enforcement Control access to resources using the `sagemaker:RemoteAccess` condition key. This is supported by both `CreateSpace` and `UpdateSpace` APIs. The following example uses `CreateSpace`. You can ensure that users cannot create spaces with remote access enabled. This helps maintain security by defaulting to more restricted access settings. The following policy ensures users can: + Create new Studio spaces where remote access is explicitly disabled + Create new Studio spaces without specifying any remote access settings ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "DenyCreateSpaceRemoteAccessEnabled", "Effect": "Deny", "Action": [ "sagemaker:CreateSpace", "sagemaker:UpdateSpace" ], "Resource": "arn:aws:sagemaker:*:*:space/*", "Condition": { "StringEquals": { "sagemaker:RemoteAccess": [ "ENABLED" ] } } }, { "Sid": "AllowCreateSpace", "Effect": "Allow", "Action": [ "sagemaker:CreateSpace", "sagemaker:UpdateSpace" ], "Resource": "arn:aws:sagemaker:*:*:space/*" } ] } ``` ------ ## Tag-based access control Implement [tag-based](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html) access control to restrict connections based on resource and principal tags. You can ensure users can only access resources appropriate for their role and project assignments. You can use the following policy to: + Allow users to connect only to spaces that match their assigned team, environment, and cost center + Implement fine-grained access control based on organizational structure In the following example, the space is tagged with the following: ``` { "Team": "ML", "Environment": "Production", "CostCenter": "12345" } ``` You can have a role that contains the following policy to match resource and principal tags: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RestrictStartSessionOnTaggedSpacesInDomain", "Effect": "Allow", "Action": [ "sagemaker:StartSession" ], "Resource": [ "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/*" ], "Condition": { "StringEquals": { "aws:ResourceTag/Team": "${aws:PrincipalTag/Team}", "aws:ResourceTag/Environment": "${aws:PrincipalTag/Environment}", "aws:ResourceTag/CostCenter": "${aws:PrincipalTag/CostCenter}", "aws:ResourceTag/IDC_UserName": "${aws:PrincipalTag/IDC_UserName}" } } } ] } ``` ------ When the role’s tags match, the user has permission to start the session and remotely connect to their space. See [Control access to AWS resources using tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) for more information. # Set up Studio to run with subnets without internet access within a VPC This guide shows you how to connect to Amazon SageMaker Studio spaces from your Remote IDE when your Amazon SageMaker AI domain runs in private subnets without internet access. You’ll learn about connectivity requirements and setup options to establish secure remote connections in isolated network environments. You can configure Amazon SageMaker Studio to run in VPC only mode with subnets without internet access. This setup enhances security for your machine learning workloads by operating in an isolated network environment where all traffic flows through the VPC. To enable external communications while maintaining security, use VPC endpoints for AWS services and configure VPC PrivateLink for required AWS dependencies. **IDE support for private subnet connections** The following table shows the supported connection methods for each Remote IDE when connecting to Studio spaces in private subnets without internet access. | Connection method | VS Code | Kiro | Cursor | | --- | --- | --- | --- | | HTTP Proxy support | Supported | Supported | Not supported | | Pre-packaged remote server and extensions | Supported | Not supported | Not supported | **Important** Cursor is not supported for connecting to Studio spaces in private subnets without outbound internet access. **Topics** + [ ## Studio remote access network requirements ](#remote-access-remote-setup-vpc-subnets-without-internet-access-network-requirements) + [ ## Setup Studio remote access network ](#remote-access-remote-setup-vpc-subnets-without-internet-access-setup) ## Studio remote access network requirements **VPC mode limitations** Studio in VPC mode only supports private subnets. Studio cannot work with subnets directly attached with an Internet Gateway (IGW). Remote IDE connections share the same limitations as SageMaker AI. For more information, see [Connect Studio notebooks in a VPC to external resources](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-notebooks-and-internet-access.html). ### VPC PrivateLink requirements When SageMaker AI runs in private subnets, configure these SSM VPC endpoints in addition to standard VPC endpoints required for SageMaker. For more information, see [Connect Studio Through a VPC Endpoint](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-interface-endpoint.html). + `com.amazonaws.REGION.ssm` + `com.amazonaws.REGION.ssmmessages` **VPC endpoint policy recommendations** The following are the recommended VPC endpoint policies that allow the necessary actions for remote access while using the `aws:PrincipalIsAWSService` condition to ensure only AWS services like Amazon SageMaker AI can make the calls. For more information about the `aws:PrincipalIsAWSService` condition key, see [the documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalisawsservice). **SSM endpoint policy** Use the following policy for the `com.amazonaws.REGION.ssm` endpoint: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": [ "ssm:CreateActivation", "ssm:RegisterManagedInstance", "ssm:DeleteActivation", "ssm:DeregisterManagedInstance", "ssm:AddTagsToResource", "ssm:UpdateInstanceInformation", "ssm:UpdateInstanceAssociationStatus", "ssm:DescribeInstanceInformation", "ssm:ListInstanceAssociations", "ssm:ListAssociations", "ssm:GetDocument", "ssm:PutInventory" ], "Resource": "*", "Condition": { "BoolIfExists": { "aws:PrincipalIsAWSService": "true" } } } ] } ``` **SSM Messages endpoint policy** Use the following policy for the `com.amazonaws.REGION.ssmmessages` endpoint: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*", "Condition": { "BoolIfExists": { "aws:PrincipalIsAWSService": "true" } } } ] } ``` **VS Code specific network requirements** Remote VS Code connection requires VS Code remote development, which needs specific network access to install the remote server and extensions. See the [remote development FAQ](https://code.visualstudio.com/docs/remote/faq) in the Visual Studio Code documentation for full network requirements. The following is a summary of the requirements: + Access to Microsoft’s VS Code server endpoints is needed to install and update the VS Code remote server. + Access to Visual Studio Marketplace and related CDN endpoints is required for installing VS Code extensions through the extension panel (alternatively, extensions can be installed manually using VSIX files without internet connection). + Some extensions may require access to additional endpoints for downloading their specific dependencies. See the extension’s documentation for their specific connectivity requirements. **Kiro specific network requirements** Remote Kiro connection requires Kiro remote development, which needs specific network access to install the remote server and extensions. For firewall and proxy server configuration, see [Kiro firewall configuration](https://kiro.dev/docs/privacy-and-security/firewalls/). The requirements are similar to VS Code: + Access to Kiro server endpoints is needed to install and update the Kiro remote server. + Access to extension marketplace and related CDN endpoints is required for installing Kiro extensions through the extension panel. + Some extensions may require access to additional endpoints for downloading their specific dependencies. See the extension’s documentation for their specific connectivity requirements. ## Setup Studio remote access network You have the following options to connect your Remote IDE to Studio spaces in private subnets: + HTTP Proxy (supported for VS Code and Kiro) + Pre-packaged remote server and extensions (VS Code only) ### Set up HTTP Proxy with controlled allow-listing When your Studio space is behind a firewall or proxy, allow access to your IDE server and extension-related CDNs and endpoints. 1. Set up a public subnet to run the HTTP proxy (such as Squid), where you can configure which websites to allow. Ensure that the HTTP proxy is accessible by SageMaker spaces. 1. The public subnet can be in the same VPC used by the Studio or in separate VPC peered with all the VPCs used by Amazon SageMaker AI domains. ### Set up Pre-packaged remote server and extensions (VS Code only) **Note** This option is only available for Visual Studio Code. Kiro and Cursor do not support pre-packaged remote server setup. When your Studio spaces can’t access external endpoints to download VS Code remote server and extensions, you can pre-package them. With this approach, you export a tarball containing the `.VS Code-server` directory for a specific version of VS Code. Then, you use a SageMaker AI Lifecycle Configuration (LCC) script to copy and extract the tarball into the home directory (`/home/sagemaker-user`) of the Studio spaces. This LCC-based solution works with both AWS-provided and custom images. Even when you’re not using private subnets, this approach accelerates the setup of the VS Code remote server and pre-installed extensions. **Instructions for pre-packaging your VS Code remote server and extensions** 1. Install VS Code on your local machine. 1. Launch a Linux-based (x64) Docker container with SSH enabled, either locally or via a Studio space with internet access. We recommend using a temporary Studio space with remote access and internet enabled for simplicity. 1. Connect your installed VS Code to the local Docker container via Remote SSH or connect to the Studio space via the Studio remote VS Code feature. VS Code installs the remote server into `.VS Code-server` in the home directory in the remote container during connection. See [Example Dockerfile usage for pre-packaging your VS Code remote server and extensions](remote-access-local-ide-setup-vpc-no-internet.md#remote-access-local-ide-setup-vpc-no-internet-pre-packaged-vs-code-remote-server-and-extensions-example-dockerfile) for more information. 1. After connecting remotely, ensure you use the VS Code Default profile. 1. Install the required VS Code extensions and validate their functionality. For example, create and run a notebook to install Jupyter notebook-related extensions in the VS Code remote server. Ensure you [install the AWS Toolkit for Visual Studio Code extension](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/setup.html) after connecting to the remote container. 1. Archive the `$HOME/.VS Code-server` directory (for example, `VS Code-server-with-extensions-for-1.100.2.tar.gz`) in either the local Docker container or in the terminal of the remotely connected Studio space. 1. Upload the tarball to Amazon S3. 1. Create an [LCC script](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-lifecycle-configurations.html) ([Example LCC script (LCC-install-VS Code-server-v1.100.2)](remote-access-local-ide-setup-vpc-no-internet.md#remote-access-local-ide-setup-vpc-no-internet-pre-packaged-vs-code-remote-server-and-extensions-example-lcc)) that: + Downloads the specific archive from Amazon S3. + Extracts it into the home directory when a Studio space in a private subnet launches. 1. (Optional) Extend the LCC script to support per-user VS Code server tarballs stored in user-specific Amazon S3 folders. 1. (Optional) Maintain version-specific LCC scripts ([Example LCC script (LCC-install-VS Code-server-v1.100.2)](remote-access-local-ide-setup-vpc-no-internet.md#remote-access-local-ide-setup-vpc-no-internet-pre-packaged-vs-code-remote-server-and-extensions-example-lcc)) that you can attach to your spaces, ensuring compatibility between your local VS Code client and the remote server. # Set up automated Studio space filtering when using the AWS Toolkit Users can filter spaces in the AWS Toolkit for Visual Studio Code explorer to display only relevant spaces. This section provides information on filtering and how to set up automated filtering. This setup only applies when using the [Method 2: AWS Toolkit in the Remote IDE](remote-access-local-ide-setup.md#remote-access-local-ide-setup-local-vs-code-method-2-aws-toolkit-in-vs-code) method to connect from your Remote IDE to Amazon SageMaker Studio spaces. See [Set up remote access](remote-access-remote-setup.md) for more information. **Topics** + [ ## Filtering overview ](#remote-access-remote-setup-filter-overview) + [ ## Set up when connecting with IAM credentials ](#remote-access-remote-setup-filter-set-up-iam-credentials) ## Filtering overview **Manual filtering** allows users to manually select which user profiles to display spaces for through the AWS Toolkit interface. This method works for all authentication types and takes precedence over automated filtering. To manually filter, see [Manual filtering](remote-access-local-ide-setup-filter.md#remote-access-local-ide-setup-filter-manual). **Automated filtering** automatically shows only spaces relevant to the authenticated user. This filtering behavior depends on the authentication method during sign-in. See [connecting to AWS from the Toolkit](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/connect.html#connect-to-aws) in the Toolkit for VS Code User Guide for more information. The following lists the sign-in options. + **Authenticate and connect with SSO**: Automated filtering works by default. + **Authenticate and connect with IAM credentials**: Automated filtering **requires administrator setup** for the following IAM credentials. Without this setup, AWS Toolkit cannot identify which spaces belong to the user, so all spaces are shown by default. + **Using IAM user credentials** + **Using assumed IAM role session credentials** ## Set up when connecting with IAM credentials **When using IAM user credentials** Toolkit for VS Code can match spaces belonging to user profiles that start with the authenticated IAM user name or assumed role session name. To set this up: **Note** Administrators must configure Studio user profile names to follow this naming convention for automated filtering to work correctly. + Administrators must ensure Studio user profile names follow the naming convention: + For IAM users: prefix with `IAM-user-name-` + For assumed roles: prefix with `assumed-role-session-name-` + `aws sts get-caller-identity` returns the identity information used for matching + Spaces belonging to the matched user profiles will be automatically filtered in the Toolkit for VS Code **When using assumed IAM role session credentials** In addition to the setup when using IAM user credentials above, you will need to ensure session ARNs include user identifiers as prefixes that match. You can configure trust policies that ensure session ARNs include user identifiers as prefixes. [Create a trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) and attach it to the assumed role used for authentication. This setup is not required for direct IAM user credentials or IdC authentication. **Set up trust policy for IAM role session credentials example** Create a trust policy that enforces role sessions to include the IAM user name. The following is an example policy: ``` { "Statement": [ { "Sid": "RoleTrustPolicyRequireUsernameForSessionName", "Effect": "Allow", "Action": "sts:AssumeRole", "Principal": {"AWS": "arn:aws:iam::ACCOUNT:root"}, "Condition": { "StringLike": {"sts:RoleSessionName": "${aws:username}"} } } ] } ``` # Set up Remote IDE After administrators complete the instructions in [Connect your Remote IDE to SageMaker spaces with remote access](remote-access.md), you can connect your Remote IDE to your remote SageMaker spaces. **Topics** + [ ## Set up your local environment ](#remote-access-local-ide-setup-local-environment) + [ ## Connect to your Remote IDE ](#remote-access-local-ide-setup-local-vs-code) + [ # Connect to VPC with subnets without internet access ](remote-access-local-ide-setup-vpc-no-internet.md) + [ # Filter your Studio spaces ](remote-access-local-ide-setup-filter.md) ## Set up your local environment Install your preferred Remote IDE on your local machine: + [Visual Studio Code](https://code.visualstudio.com/) + [Kiro](https://kiro.dev/) + [Cursor](https://cursor.com/home) For information on the version requirements, see [IDE version requirements](remote-access.md#remote-access-ide-version-requirements). ## Connect to your Remote IDE Before you can establish a connection from your Remote IDE to your remote SageMaker spaces, your administrator must [Set up remote access](remote-access-remote-setup.md). Your administrator sets up a specific method for you to establish a connection. Choose the method that was set up for you. **Topics** + [ ### Method 1: Deep link from Studio UI ](#remote-access-local-ide-setup-local-vs-code-method-1-deep-link-from-studio-ui) + [ ### Method 2: AWS Toolkit in the Remote IDE ](#remote-access-local-ide-setup-local-vs-code-method-2-aws-toolkit-in-vs-code) + [ ### Method 3: Connect from the terminal via SSH CLI ](#remote-access-local-ide-setup-local-vs-code-method-3-connect-from-the-terminal-via-ssh-cli) ### Method 1: Deep link from Studio UI Use the following procedure to establish a connection using deep link. 1. [Launch Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-launch.html#studio-updated-launch-console). 1. In the Studio UI, navigate to your space. 1. Choose **Open in VS Code**, **Open in Kiro**, or **Open in Cursor** button for your preferred IDE. Ensure that your preferred IDE is already installed on your local computer. 1. When prompted, confirm to open your IDE. Your IDE opens with another pop-up to confirm. Once completed, the remote connection is established. ### Method 2: AWS Toolkit in the Remote IDE Use the following procedure to establish a connection using the AWS Toolkit for Visual Studio Code. This method is available for VS Code, Kiro, and Cursor. 1. Open your Remote IDE (VS Code, Kiro, or Cursor). 1. Open the AWS Toolkit extension. 1. [Connect to AWS](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/connect.html). 1. In the AWS Explorer, expand **SageMaker AI**, then expand **Studio**. 1. Find your Studio space. 1. Choose the **Connect** icon next to your space to start it. **Note** Stop and restart the space in the Toolkit for Visual Studio to enable remote access, if not already connected. If the space is not using a supported [instance size](https://docs.aws.amazon.com/sagemaker/latest/dg/remote-access.html#remote-access-instance-requirements), you will be asked to change the instance. ### Method 3: Connect from the terminal via SSH CLI Choose one of the following platform options to view the procedure to establish a connection using the SSH CLI. **Note** Ensure that you have the latest versions of the [Local machine prerequisites](remote-access.md#remote-access-local-prerequisites) installed before following the instructions below. If you [Bring your own image (BYOI)](studio-updated-byoi.md), ensure you have installed the required dependencies listed in [Image requirements](remote-access.md#remote-access-image-requirements) before proceeding ------ #### [ Linux/macOS ] Create a shell script (for example, `/home/user/sagemaker_connect.sh`): ``` #!/bin/bash # Disable the -x option if printing each command is not needed. set -exuo pipefail SPACE_ARN="$1" AWS_PROFILE="${2:-}" # Validate ARN and extract region if [[ "$SPACE_ARN" =~ ^arn:aws[-a-z]*:sagemaker:([a-z0-9-]+):[0-9]{12}:space\/[^\/]+\/[^\/]+$ ]]; then AWS_REGION="${BASH_REMATCH[1]}" else echo "Error: Invalid SageMaker Studio Space ARN format." exit 1 fi # Optional profile flag PROFILE_ARG=() if [[ -n "$AWS_PROFILE" ]]; then PROFILE_ARG=(--profile "$AWS_PROFILE") fi # Start session START_SESSION_JSON=$(aws sagemaker start-session \ --resource-identifier "$SPACE_ARN" \ --region "${AWS_REGION}" \ "${PROFILE_ARG[@]}") # Extract fields using grep and sed SESSION_ID=$(echo "$START_SESSION_JSON" | grep -o '"SessionId": "[^"]*"' | sed 's/.*: "//;s/"$//') STREAM_URL=$(echo "$START_SESSION_JSON" | grep -o '"StreamUrl": "[^"]*"' | sed 's/.*: "//;s/"$//') TOKEN=$(echo "$START_SESSION_JSON" | grep -o '"TokenValue": "[^"]*"' | sed 's/.*: "//;s/"$//') # Validate extracted values if [[ -z "$SESSION_ID" || -z "$STREAM_URL" || -z "$TOKEN" ]]; then echo "Error: Failed to extract session information from sagemaker start session response." exit 1 fi # Call session-manager-plugin session-manager-plugin \ "{\"streamUrl\":\"$STREAM_URL\",\"tokenValue\":\"$TOKEN\",\"sessionId\":\"$SESSION_ID\"}" \ "$AWS_REGION" "StartSession" ``` 1. Make the script executable: ``` chmod +x /home/user/sagemaker_connect.sh ``` 1. Configure `$HOME/.ssh/config` to add the following entry: ``` Host space-name HostName 'arn:PARTITION:sagemaker:us-east-1:111122223333:space/domain-id/space-name' ProxyCommand '/home/user/sagemaker_connect.sh' '%h' ForwardAgent yes AddKeysToAgent yes StrictHostKeyChecking accept-new ``` For example, the `PARTITION` can be `aws`. If you need to use a [named AWS credential profile](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-configure-files-using-profiles), change the proxy command as follows: ``` ProxyCommand '/home/user/sagemaker_connect.sh' '%h' YOUR_CREDENTIAL_PROFILE_NAME ``` + Connect via SSH or run SCP command: ``` ssh space-name scp file_abc space-name:/tmp/ ``` ------ #### [ Windows ] **Prerequisites for Windows:** + PowerShell 5.1 or later + SSH client (OpenSSH recommended) Create a PowerShell script (for example, `C:\Users\user-name\sagemaker_connect.ps1`): ``` # sagemaker_connect.ps1 param( [Parameter(Mandatory=$true)] [string]$SpaceArn, [Parameter(Mandatory=$false)] [string]$AwsProfile = "" ) # Enable error handling $ErrorActionPreference = "Stop" # Validate ARN and extract region if ($SpaceArn -match "^arn:aws[-a-z]*:sagemaker:([a-z0-9-]+):[0-9]{12}:space\/[^\/]+\/[^\/]+$") { $AwsRegion = $Matches[1] } else { Write-Error "Error: Invalid SageMaker Studio Space ARN format." exit 1 } # Build AWS CLI command $awsCommand = @("sagemaker", "start-session", "--resource-identifier", $SpaceArn, "--region", $AwsRegion) if ($AwsProfile) { $awsCommand += @("--profile", $AwsProfile) } try { # Start session and capture output Write-Host "Starting SageMaker session..." -ForegroundColor Green $startSessionOutput = & aws @awsCommand # Try to parse JSON response try { $sessionData = $startSessionOutput | ConvertFrom-Json } catch { Write-Error "Failed to parse JSON response: $_" Write-Host "Raw response was:" -ForegroundColor Yellow Write-Host $startSessionOutput exit 1 } $sessionId = $sessionData.SessionId $streamUrl = $sessionData.StreamUrl $token = $sessionData.TokenValue # Validate extracted values if (-not $sessionId -or -not $streamUrl -or -not $token) { Write-Error "Error: Failed to extract session information from sagemaker start session response." Write-Host "Parsed response was:" -ForegroundColor Yellow Write-Host ($sessionData | ConvertTo-Json) exit 1 } Write-Host "Session started successfully. Connecting..." -ForegroundColor Green # Create session manager plugin command $sessionJson = @{ streamUrl = $streamUrl tokenValue = $token sessionId = $sessionId } | ConvertTo-Json -Compress # Escape the JSON string $escapedJson = $sessionJson -replace '"', '\"' # Call session-manager-plugin & session-manager-plugin "$escapedJson" $AwsRegion "StartSession" } catch { Write-Error "Failed to start session: $_" exit 1 } ``` + Configure `C:\Users\user-name\.ssh\config` to add the following entry: ``` Host space-name HostName "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/space-name" ProxyCommand "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe" -ExecutionPolicy RemoteSigned -File "C:\\Users\\user-name\\sagemaker_connect.ps1" "%h" ForwardAgent yes AddKeysToAgent yes User sagemaker-user StrictHostKeyChecking accept-new ``` ------ # Connect to VPC with subnets without internet access Before connecting your Remote IDE to Studio spaces in private subnets without internet access, ensure your administrator has [Set up Studio to run with subnets without internet access within a VPC](remote-access-remote-setup-vpc-subnets-without-internet-access.md). You have the following options to connect your Remote IDE to Studio spaces in private subnets: + Set up HTTP Proxy (supported for VS Code and Kiro) + Pre-packaged remote server and extensions (VS Code only) **Important** Cursor is not supported for connecting to Studio spaces in private subnets without outbound internet access. **Topics** + [ ## HTTP Proxy with controlled allow-listing ](#remote-access-local-ide-setup-vpc-no-internet-http-proxy-with-controlled-allow-listing) + [ ## Pre-packaged remote server and extensions (VS Code only) ](#remote-access-local-ide-setup-vpc-no-internet-pre-packaged-vs-code-remote-server-and-extensions) ## HTTP Proxy with controlled allow-listing When your Studio space is behind a firewall or proxy, ask your administrator to allow access to your IDE server and extension-related CDNs and endpoints. For more information, see [Set up HTTP Proxy with controlled allow-listing](remote-access-remote-setup-vpc-subnets-without-internet-access.md#remote-access-remote-setup-vpc-subnets-without-internet-access-setup-http-proxy-with-controlled-allow-listing). ------ #### [ VS Code ] Configure the HTTP proxy for VS Code remote development by providing the proxy URL with the `remote.SSH.httpProxy` or `remote.SSH.httpsProxy` setting. **Note** Consider enabling "Remote.SSH: Use Curl And Wget Configuration Files" to use the configuration from the remote environment’s `curlrc` and `wgetrc` files. This is so that the `curlrc` and `wgetrc` files, placed in their respective default locations in the SageMaker space, can be used for enabling certain cases. ------ #### [ Kiro ] Configure the HTTP proxy for Kiro remote development by setting the `aws.sagemaker.ssh.kiro.httpsProxy` setting to your HTTP or HTTPS proxy endpoint. If you use MCP (Model Context Protocol) servers in Kiro, you also need to add the proxy environment variables to your MCP server configuration: ``` "env": { "http_proxy": "${http_proxy}", "https_proxy": "${https_proxy}" } ``` ------ This option works when you are allowed to set up HTTP proxy and lets you install additional extensions flexibly, as some extensions require a public endpoint. ## Pre-packaged remote server and extensions (VS Code only) **Note** This option is only available for Visual Studio Code. Kiro and Cursor do not support pre-packaged remote server setup. When your Studio spaces can’t access external endpoints to download VS Code remote server and extensions, you can pre-package them. With this approach, your administrator can export a tarball containing the `.VS Code-server` directory for a specific version of VS Code. Then, the administrator uses a SageMaker AI Lifecycle Configuration (LCC) script to copy and extract the tarball into your home directory (`/home/sagemaker-user`). For more information, see [Set up Pre-packaged remote server and extensions (VS Code only)](remote-access-remote-setup-vpc-subnets-without-internet-access.md#remote-access-remote-setup-vpc-subnets-without-internet-access-setup-pre-packaged-vs-code-remote-server-and-extensions). **Instructions for using pre-packaging for your VS Code remote server and extensions** 1. Install VS Code on your local machine 1. When you connect to the SageMaker space: + Use the Default profile to ensure compatibility with pre-packaged extensions. Otherwise, you’ll need to install extensions using downloaded VSIX files after connecting to the Studio space. + Choose a VS Code version specific LCC script to attach to the space when you launch the space. ### Example Dockerfile usage for pre-packaging your VS Code remote server and extensions The following is a sample Dockerfile to launch a local container with SSH server pre-installed, if it is not possible to create a space with remote access and internet enabled. **Note** In this example the SSH server does not require authentication and is only used for exporting the VS Code remote server. The container should be built and run on an x64 architecture. ``` FROM amazonlinux:2023 # Install OpenSSH server and required tools RUN dnf install -y \ openssh-server \ shadow-utils \ passwd \ sudo \ tar \ gzip \ && dnf clean all # Create a user with no password RUN useradd -m -s /bin/bash sagemaker-user && \ passwd -d sagemaker-user # Add sagemaker-user to sudoers via wheel group RUN usermod -aG wheel sagemaker-user && \ echo 'sagemaker-user ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/sagemaker-user && \ chmod 440 /etc/sudoers.d/sagemaker-user # Configure SSH to allow empty passwords and password auth RUN sed -i 's/^#\?PermitEmptyPasswords .*/PermitEmptyPasswords yes/' /etc/ssh/sshd_config && \ sed -i 's/^#\?PasswordAuthentication .*/PasswordAuthentication yes/' /etc/ssh/sshd_config # Generate SSH host keys RUN ssh-keygen -A # Expose SSH port EXPOSE 22 WORKDIR /home/sagemaker-user USER sagemaker-user # Start SSH server CMD ["bash"] ``` Use the following commands to build and run the container: ``` # Build the image docker build . -t remote_server_export # Run the container docker run --rm -it -d \ -v /tmp/remote_access/.VS Code-server:/home/sagemaker-user/.VS Code-server \ -p 2222:22 \ --name remote_server_export \ remote_server_export # change the permisson for the mounted folder docker exec -i remote_server_export \ bash -c 'sudo chown sagemaker-user:sagemaker-user ~/.VS Code-server' # start the ssh server in the container docker exec -i remote_server_export bash -c 'sudo /usr/sbin/sshd -D &' ``` Connect using the following command: ``` ssh sagemaker-user@localhost -p 2222 ``` Before this container can be connected, configure the following in the `.ssh/config` file. Afterwards you will be able to see the `remote_access_export` as a host name in the remote SSH side panel when connecting. For example: ``` Host remote_access_export HostName localhost User=sagemaker-user Port 2222 ForwardAgent yes ``` Archive `/tmp/remote_access/.VS Code-server` and follow the steps in Pre-packaged VS Code remote server and extensions to connect and install the extension. After unzipping, ensure that the `.VS Code-server` folder shows as the parent folder. ``` cd /tmp/remote_access/ sudo tar -czvf VS Code-server-with-extensions-for-1.100.2.tar.gz .VS Code-server ``` ### Example LCC script (LCC-install-VS Code-server-v1.100.2) The following is an example of how to install a specific version of VS Code remote server. ``` #!/bin/bash set -x remote_server_file=VS Code-server-with-extensions-for-1.100.2.tar.gz if [ ! -d "${HOME}/.VS Code-server" ]; then cd /tmp aws s3 cp s3://S3_BUCKET/remote_access/${remote_server_file} . tar -xzvf ${remote_server_file} mv .VS Code-server "${HOME}" rm ${remote_server_file} else echo "${HOME}/.VS Code-server already exists, skipping download and install." fi ``` # Filter your Studio spaces You can use filtering to display only the relevant Amazon SageMaker AI spaces in the AWS Toolkit for Visual Studio Code explorer. The following provides information on manual filtering and automated filtering. For more information on the definitions of manual and automatic filtering, see [Filtering overview](remote-access-remote-setup-filter.md#remote-access-remote-setup-filter-overview). This setup only applies when using the [Method 2: AWS Toolkit in the Remote IDE](remote-access-local-ide-setup.md#remote-access-local-ide-setup-local-vs-code-method-2-aws-toolkit-in-vs-code) method to connect from your Remote IDE to Amazon SageMaker Studio spaces. See [Set up remote access](remote-access-remote-setup.md) for more information. **Topics** + [ ## Manual filtering ](#remote-access-local-ide-setup-filter-manual) + [ ## Automatic filtering setup when using IAM credentials to sign-in ](#remote-access-local-ide-setup-filter-automatic-IAM-credentials) ## Manual filtering To manually filter displayed spaces: + Open your Remote IDE and navigate to the Toolkit for VS Code side panel explorer + Find the **SageMaker AI** section + Choose the filter icon on the right of the SageMaker AI section header. This will open a dropdown menu. + In the dropdown menu, select the user profiles for which you want to display spaces ## Automatic filtering setup when using IAM credentials to sign-in Automated filtering depends on the authentication method during sign-in. See [Connecting to AWS from the Toolkit](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/connect.html#connect-to-aws) in the Toolkit for VS Code User Guide for more information. When you authenticate and connect with **IAM Credentials**, automated filtering requires [Set up when connecting with IAM credentials](remote-access-remote-setup-filter.md#remote-access-remote-setup-filter-set-up-iam-credentials). Without this setup, if users opt-in for identity filtering, no spaces will be shown. Once the above is set up, AWS Toolkit matches spaces belonging to user profiles that start with the authenticated IAM user name or assumed role session name. Automatic filtering is opt-in for users: + Open your Remote IDE settings + Navigate to the **AWS Toolkit** extension + Find **Enable Identity Filtering** + Choose to enable automatic filtration of spaces based on your AWS identity # Supported AWS Regions The following table lists the AWS Regions where Remote IDE connections to Studio spaces are supported, along with the IDEs available in each Region. | AWS Region | VS Code | Kiro | Cursor | | --- | --- | --- | --- | | us-east-1 | Supported | Supported | Supported | | us-east-2 | Supported | Supported | Supported | | us-west-1 | Supported | Supported | Supported | | us-west-2 | Supported | Supported | Supported | | af-south-1 | Supported | Supported | Supported | | ap-east-1 | Supported | Supported | Supported | | ap-south-1 | Supported | Supported | Supported | | ap-northeast-1 | Supported | Supported | Supported | | ap-northeast-2 | Supported | Supported | Supported | | ap-northeast-3 | Supported | Supported | Supported | | ap-southeast-1 | Supported | Supported | Supported | | ap-southeast-2 | Supported | Supported | Supported | | ap-southeast-3 | Supported | Supported | Supported | | ap-southeast-5 | Supported | Supported | Supported | | ca-central-1 | Supported | Supported | Supported | | eu-central-1 | Supported | Supported | Supported | | eu-central-2 | Supported | Supported | Supported | | eu-north-1 | Supported | Supported | Supported | | eu-south-1 | Supported | Supported | Supported | | eu-south-2 | Supported | Supported | Supported | | eu-west-1 | Supported | Supported | Supported | | eu-west-2 | Supported | Supported | Supported | | eu-west-3 | Supported | Supported | Supported | | il-central-1 | Supported | Supported | Supported | | me-central-1 | Supported | Not supported | Not supported | | me-south-1 | Supported | Not supported | Not supported | | sa-east-1 | Supported | Supported | Supported | # 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 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 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} ``` # Lifecycle configurations within Amazon SageMaker Studio Lifecycle configurations (LCCs) are scripts that administrators and users can use to automate the customization of the following applications within your Amazon SageMaker Studio environment: + Amazon SageMaker AI JupyterLab + Code Editor, based on Code-OSS, Visual Studio Code - Open Source + Studio Classic + Notebook instance Customizing your application includes: + Installing custom packages + Configuring extensions + Preloading datasets + Setting up source code repositories Users create and attach built-in lifecycle configurations to their own user profiles. Administrators create and attach default or built-in lifecycle configurations at the domain, space, or user profile level. **Important** Amazon SageMaker Studio first runs the built-in lifecycle configuration and then runs the default LCC. Amazon SageMaker AI won't resolve package conflicts between the user and administrator LCCs. For example, if the built-in LCC installs `python3.11` and the default LCC installs `python3.12`, Studio installs `python3.12`. # Create and attach lifecycle configurations You can create and attach lifecycle configurations using either the AWS Management Console or the AWS Command Line Interface. **Topics** + [ ## Create and attach lifecycle configurations (AWS CLI) ](#studio-lifecycle-configurations-create-cli) + [ ## Create and attach lifecycle configurations (console) ](#studio-lifecycle-configurations-create-console) ## Create and attach lifecycle configurations (AWS CLI) **Important** Before you begin, complete the following prerequisites: Update the AWS CLI by following the steps in [Installing the current AWS CLI Version](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html#install-tool-bundled). From your local machine, run `aws configure` and provide your AWS credentials. For information about AWS credentials, see [Understanding and getting your AWS credentials](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html). Onboard to Amazon SageMaker AI domain. For conceptual information, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). For a quickstart guide, see [Use quick setup for Amazon SageMaker AI](onboard-quick-start.md). The following procedure shows how to create a lifecycle configuration script that prints `Hello World` within Code Editor or JupyterLab. **Note** Each script can have up to **16,384 characters**. 1. From your local machine, create a file named `my-script.sh` with the following content: ``` #!/bin/bash set -eux echo 'Hello World!' ``` 1. Use the following to convert your `my-script.sh` file into base64 format. This requirement prevents errors that occur from spacing and line break encoding. ``` LCC_CONTENT=`openssl base64 -A -in my-script.sh` ``` 1. Create a lifecycle configuration for use with Studio. The following command creates a lifecycle configuration that runs when you launch an associated `JupyterLab` application: ``` aws sagemaker create-studio-lifecycle-config \ --region region \ --studio-lifecycle-config-name my-lcc \ --studio-lifecycle-config-content $LCC_CONTENT \ --studio-lifecycle-config-app-type application-type ``` For `studio-lifecycle-config-app-type`, specify either *CodeEditor* or *JupyterLab*. **Note** The ARN of the newly created lifecycle configuration that is returned. This ARN is required to attach the lifecycle configuration to your application. To ensure that the environments are customized properly, users and administrators use different commands to attach lifecycle configurations. ### Attach default lifecycle configurations (administrator) To attach the lifecycle configuration, you must update the `UserSettings` for your domain or user profile. Lifecycle configuration scripts that are associated at the domain level are inherited by all users. However, scripts that are associated at the user profile level are scoped to a specific user. You can create a new user profile, domain, or space with a lifecycle configuration attached by using the following commands: + [create-user-profile](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-user-profile.html) + [create-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-domain.html) + [create-space](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-space.html) The following command creates a user profile with a lifecycle configuration for a JupyterLab application. Add the lifecycle configuration ARN from the preceding step to the `JupyterLabAppSettings` of the user. You can add multiple lifecycle configurations at the same time by passing a list of them. When a user launches a JupyterLab application with the AWS CLI, they can specify a lifecycle configuration instead of using the default one. The lifecycle configuration that the user passes must belong to the list of lifecycle configurations in `JupyterLabAppSettings`. ``` # Create a new UserProfile aws sagemaker create-user-profile --domain-id domain-id \ --user-profile-name user-profile-name \ --region region \ --user-settings '{ "JupyterLabAppSettings": { "LifecycleConfigArns": [lifecycle-configuration-arn-list] } }' ``` The following command creates a user profile with a lifecycle configuration for a Code Editor application. Add the lifecycle configuration ARN from the preceding step to the `CodeEditorAppSettings` of the user. You can add multiple lifecycle configurations at the same time by passing a list of them. When a user launches a Code Editor application with the AWS CLI, they can specify a lifecycle configuration instead of using the default one. The lifecycle configuration that the user passes must belong to the list of lifecycle configurations in `CodeEditorAppSettings`. ``` # Create a new UserProfile aws sagemaker create-user-profile --domain-id domain-id \ --user-profile-name user-profile-name \ --region region \ --user-settings '{ "CodeEditorAppSettings": { "LifecycleConfigArns": [lifecycle-configuration-arn-list] } }' ``` ### Attach built-in lifecycle configurations (user) To attach the lifecycle configuration, you must update the `UserSettings` for your user profile. The following command creates a user profile with a lifecycle configuration for a JupyterLab application. Add the lifecycle configuration ARN from the preceding step to the `JupyterLabAppSettings` of your user profile. ``` # Update a UserProfile aws sagemaker update-user-profile --domain-id domain-id \ --user-profile-name user-profile-name \ --region region \ --user-settings '{ "JupyterLabAppSettings": { "BuiltInLifecycleConfigArn":"lifecycle-configuration-arn" } }' ``` The following command creates a user profile with a lifecycle configuration for a Code Editor application. Add the lifecycle configuration ARN from the preceding step to the `CodeEditorAppSettings` of your user profile. The lifecycle configuration that the user passes must belong to the list of lifecycle configurations in `CodeEditorAppSettings`. ``` # Update a UserProfile aws sagemaker update-user-profile --domain-id domain-id \ --user-profile-name user-profile-name \ --region region \ --user-settings '{ "CodeEditorAppSettings": { "BuiltInLifecycleConfigArn":"lifecycle-configuration-arn" } }' ``` ## Create and attach lifecycle configurations (console) To create and attach lifecycle configurations in the AWS Management Console, navigate to the [Amazon SageMaker AI console](https://console.aws.amazon.com/sagemaker) and choose **Lifecycle configurations** in the left-hand navigation. The console will guide you through the process of creating the lifecycle configuration. # Debug lifecycle configurations The following topics show how to get information about and debug your lifecycle configurations. **Topics** + [ ## Verify lifecycle configuration process from CloudWatch Logs ](#studio-lifecycle-configurations-debug-logs) + [ # Lifecycle configuration timeout ](studio-lifecycle-configurations-debug-timeout.md) ## Verify lifecycle configuration process from CloudWatch Logs Lifecycle configurations only log `STDOUT` and `STDERR`. `STDOUT` is the default output for bash scripts. You can write to `STDERR` by appending `>&2` to the end of a bash command. For example, `echo 'hello'>&2`. Logs for your lifecycle configurations are published to your AWS account using Amazon CloudWatch. These logs can be found in the `/aws/sagemaker/studio` log stream in the CloudWatch console. 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Choose **Logs** from the left navigation pane. From the dropdown menu, select **Log groups**. 1. On the **Log groups** page, search for `aws/sagemaker/studio`. 1. Select the log group. 1. On the **Log group details** page, choose the **Log streams** tab. 1. To find the logs for a specific space and app, search the log streams using the following format: ``` domain-id/space-name/app-type/default/LifecycleConfigOnStart ``` For example, to find the lifecycle configuration logs for domain ID `d-m85lcu8vbqmz`, space name `i-sonic-js`, and application type `JupyterLab`, use the following search string: ``` d-m85lcu8vbqmz/i-sonic-js/JupyterLab/default/LifecycleConfigOnStart ``` 1. To view the script execution logs, select the log stream appended with `LifecycleConfigOnStart`. # Lifecycle configuration timeout There is a lifecycle configuration timeout limitation of 5 minutes. If a lifecycle configuration script takes longer than 5 minutes to run, you get an error. To resolve this error, make sure that your lifecycle configuration script completes in less than 5 minutes. To help decrease the runtime of scripts, try the following: + Reduce unnecessary steps. For example, limit which conda environments to install large packages in. + Run tasks in parallel processes. + Use the nohup command in your script to make sure that hangup signals are ignored so that the script runs without stopping. # Amazon SageMaker Studio spaces **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). Spaces are used to manage the storage and resource needs of some Amazon SageMaker Studio applications. Each space is composed of multiple resources and can be either private or shared. Each space has a 1:1 relationship with an instance of an application. Every supported application that is created gets its own space. The following applications in Studio run on spaces: + [Code Editor in Amazon SageMaker Studio](code-editor.md) + [SageMaker JupyterLab](studio-updated-jl.md) + [Amazon SageMaker Studio Classic](studio.md) A space is composed of the following resources: + A storage volume. + For Studio Classic, the space is connected to the shared Amazon Elastic File System (Amazon EFS) volume for the domain. + For other applications, a distinct Amazon Elastic Block Store (Amazon EBS) volume is attached to the space. All applications are given their own Amazon EBS volume. Applications do not have access to the Amazon EBS volume of other applications. For more information about Amazon EBS volumes, see [Amazon Elastic Block Store (Amazon EBS)](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/AmazonEBS.html). + The application type of the space. + The image that the application is based on. Spaces can be either private or shared: + **Private**: Private spaces are scoped to a single user in a domain. Private spaces cannot be shared with other users. All applications that support spaces also support private spaces. + **Shared**: Shared spaces are accessible by all users in the domain. For more information about shared spaces, see [Collaboration with shared spaces](domain-space.md). Spaces can be created in domains that use either AWS IAM Identity Center or AWS Identity and Access Management (IAM) authentication. The following sections give general information about how to access spaces. For specific information about creating and accessing a space, see the documentation for the respective application type of the space that you're creating. For information about viewing, stopping, or deleting your applications, instances, or spaces, see [Stop and delete your Studio running applications and spaces](studio-updated-running-stop.md). **Topics** + [ # Launch spaces ](studio-updated-spaces-access.md) + [ # Collaboration with shared spaces ](domain-space.md) # Launch spaces The following sections give information about accessing spaces in a domain. Spaces can be accessed in one of the following ways: + from the Amazon SageMaker AI console + from Studio + using the AWS CLI ## Accessing spaces from the Amazon SageMaker AI console **To access spaces from the Amazon SageMaker AI console** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. Under **Admin configurations**, choose **Domains**. 1. From the list of domains, select the domain that contains the spaces. 1. On the **Domain details** page, select the **Space management** tab. For more information about managing spaces, see [Collaboration with shared spaces](domain-space.md). 1. From the list of spaces for that domain, select the space to launch. 1. Choose **Launch Studio** for the space that you want to launch. ## Accessing spaces from Studio Follow these steps to access spaces from Studio for a specific application type. **To access spaces from Studio** 1. Open Studio by following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. Select the application type with spaces that you want to access. ## Accessing spaces using the AWS CLI The following sections show how to access a space from the AWS Command Line Interface (AWS CLI). The procedures are for domains that use AWS Identity and Access Management (IAM) or AWS IAM Identity Center authentication. ### IAM authentication The following procedure outlines generally how to access a space using IAM authentication from the AWS CLI. 1. Create a presigned domain URL specifying the name of the space that you want to access. ``` aws \     --region region \     sagemaker \     create-presigned-domain-url \     --domain-id domain-id \     --user-profile-name user-profile-name \     --space-name space-name ``` 1. Navigate to the URL. ### Accessing a space in IAM Identity Center authentication The following procedure outlines how to access a space using IAM Identity Center authentication from the AWS CLI. 1. Use the following command to return the URL associated with the space. ``` aws \     --region region \     sagemaker \     describe-space \     --domain-id domain-id \     --space-name space-name ``` 1. Append the respective redirect parameter for the application type to the URL to be federated through IAM Identity Center. For more information about the redirect parameters, see [describe-space](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/describe-space.html). 1. Navigate to the URL to be federated through IAM Identity Center. # Collaboration with shared spaces An Amazon SageMaker Studio Classic shared space consists of a shared JupyterServer application and a shared directory. A JupyterLab shared space consists of a shared JupyterLab application and a shared directory within Amazon SageMaker Studio. All user profiles in a domain have access to all shared spaces in the domain. Amazon SageMaker AI automatically scopes resources in a shared space within the context of the Amazon SageMaker Studio Classic application that you launch in that shared space. Resources in a shared space include notebooks, files, experiments, and models. Use shared spaces to collaborate with other users in real-time using features like automatic tagging, real time co-editing of notebooks, and customization. Shared spaces are available in: + Amazon SageMaker Studio Classic + JupyterLab A Studio Classic shared space only supports Studio Classic and KernelGateway applications. A shared space only supports the use of a JupyterLab 3 image Amazon Resource Name (ARN). For more information, see [JupyterLab Versioning in Amazon SageMaker Studio Classic](studio-jl.md). Amazon SageMaker AI automatically tags all SageMaker AI resources that you create within the scope of a shared space. You can use these tags to monitor costs and plan budgets using tools, such as AWS Budgets. A shared space uses the same VPC settings as the domain that it's created in. **Note** Shared spaces do not support the use of Amazon SageMaker Data Wrangler or Amazon EMR cross-account clusters. **Automatic tagging** All resources created in a shared space are automatically tagged with a domain ARN tag and shared space ARN tag. The domain ARN tag is based on the domain ID, while the shared space ARN tag is based on the shared space name. You can use these tags to monitor AWS CloudTrail usage. For more information, see [Log Amazon SageMaker API Calls with AWS CloudTrail](https://docs.aws.amazon.com//sagemaker/latest/dg/logging-using-cloudtrail.html). You can also use these tags to monitor costs with AWS Billing and Cost Management. For more information, see [Using AWS cost allocation tags](https://docs.aws.amazon.com//awsaccountbilling/latest/aboutv2/cost-alloc-tags.html). **Real time co-editing of notebooks** A key benefit of a shared space is that it facilitates collaboration between members of the shared space in real time. Users collaborating in a workspace get access to a shared Studio Classic application where they can access, read, and edit their notebooks in real time. Real time collaboration is only supported for JupyterServer applications within a shared space. Users with access to a shared space can simultaneously open, view, edit, and execute Jupyter notebooks in the shared Studio Classic or JupyterLab application in that space. The notebook indicates each co-editing user with a different cursor that shows the user profile name. While multiple users can view the same notebook, co-editing is best suited for small groups of two to five users. To track changes being made by multiple users, we strongly recommended using Studio Classic's built-in Git-based version control. **JupyterServer 2** To use shared spaces in Studio Classic, Jupyter Server version 2 is required. Certain JupyterLab extensions and packages can forcefully downgrade Jupyter Server to version 1. This prevents the use of shared space. Run the following from the command prompt to change the version number and continue using shared spaces. ``` conda activate studio pip install jupyter-server==2.0.0rc3 ``` **Customize a shared space** To attach a lifecycle configuration or custom image to a shared space, you must use the AWS CLI. For more information about creating and attaching lifecycle configurations, see [Create and Associate a Lifecycle Configuration with Amazon SageMaker Studio Classic](studio-lcc-create.md). For more information about creating and attaching custom images, see [Custom Images in Amazon SageMaker Studio Classic](studio-byoi.md). # Create a shared space **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. The following topic demonstrates how to create a shared space in an existing Amazon SageMaker AI domain. If you created your domain without support for shared spaces, you must add support for shared spaces to your existing domain before you can create a shared space. **Topics** + [ ## Add shared space support to an existing domain ](#domain-space-add) + [ ## Create a shared space ](#domain-space-create-app) ## Add shared space support to an existing domain You can use the SageMaker AI console or the AWS CLI to add support for shared spaces to an existing domain. If the domain is using `VPC only` network access, then you can only add shared space support using the AWS CLI. ### Console Complete the following procedure to add support for Studio Classic shared spaces to an existing domain from the SageMaker AI console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. From the list of domains, select the domain that you want to open the **domain settings** page for. 1. On the **domain details** page, choose the **domain settings** tab. 1. Choose **Edit**. 1. For **Space default execution role**, set an IAM role that is used by default for all shared spaces created in the domain. 1. Choose **Next**. 1. Choose **Next**. 1. Choose **Next**. 1. Choose **Submit**. ### AWS CLI ------ #### [ Studio Classic ] Run the following command from the terminal of your local machine to add default shared space settings to a domain from the AWS CLI. If you are adding default shared space settings to a domain within an Amazon VPC, you must also include a list of security groups. Studio Classic shared spaces only support the use of JupyterLab 3 image ARNs. For more information, see [JupyterLab Versioning in Amazon SageMaker Studio Classic](studio-jl.md). ``` # Public Internet domain aws --region region \ sagemaker update-domain \ --domain-id domain-id \ --default-space-settings "ExecutionRole=execution-role-arn,JupyterServerAppSettings={DefaultResourceSpec={InstanceType=example-instance-type,SageMakerImageArn=sagemaker-image-arn}}" # VPCOnly domain aws --region region \ sagemaker update-domain \ --domain-id domain-id \ --default-space-settings "ExecutionRole=execution-role-arn,JupyterServerAppSettings={DefaultResourceSpec={InstanceType=system,SageMakerImageArn=sagemaker-image-arn}},SecurityGroups=[security-groups]" ``` Use the following command to verify that the default shared space settings have been updated. ``` aws --region region \ sagemaker describe-domain \ --domain-id domain-id ``` ------ #### [ JupyterLab ] Run the following command from the terminal of your local machine to add default shared space settings to a domain from the AWS CLI. If you are adding default shared space settings to a domain within an Amazon VPC, you must also include a list of security groups. Studio Classic shared spaces only support the use of JupyterLab 4 image ARNs. For more information, see [JupyterLab Versioning in Amazon SageMaker Studio Classic](studio-jl.md). ``` # Public Internet domain aws --region region \ sagemaker update-domain \ --domain-id domain-id \ --default-space-settings "ExecutionRole=execution-role-arn", JupyterLabAppSettings={DefaultResourceSpec={InstanceType=example-instance-type,SageMakerImageArn=sagemaker-image-arn}}" # VPCOnly domain aws --region region \ sagemaker update-domain \ --domain-id domain-id \ --default-space-settings "ExecutionRole=execution-role-arn, SecurityGroups=[security-groups]" ``` Use the following command to verify that the default shared space settings have been updated. ``` aws --region region \ sagemaker describe-domain \ --domain-id domain-id ``` ------ ## Create a shared space The following sections demonstrate how to create a shared space from the Amazon SageMaker AI console, Amazon SageMaker Studio, or the AWS CLI. ### Create from Studio Use the following procedures to create a shared space in a domain from Studio. ------ #### [ Studio Classic ] 1. Navigate to Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. From the Studio UI, find the applications pane on the left side. 1. From the applications pane, select **Studio Classic**. 1. Choose **Create Studio Classic space** 1. In the pop up window, enter a name for the space. 1. Choose **Create space**. ------ #### [ JupyterLab ] 1. Navigate to Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. From the Studio UI, find the applications pane on the left side. 1. From the applications pane, select **JupyterLab**. 1. Choose **Create JupyterLab space** 1. In the pop up window, enter a name for the space. 1. Choose **Create space**. ------ ### Create from the console Complete the following procedure to create a shared space in a domain from the SageMaker AI console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. From the list of domains, select the domain that you want to create a shared space for. 1. On the **domain details** page, choose the **Space management** tab. 1. Choose **Create**. 1. Enter a name for your shared space. shared space names within a domain must be unique. The execution role for the shared space is set to the domain IAM execution role. ### Create from AWS CLI This section shows how to create a shared space from the AWS CLI. You cannot set the execution role of a shared space when creating or updating it. The `DefaultDomainExecRole` can only be set when creating or updating the domain. shared spaces only support the use of JupyterLab 3 image ARNs. For more information, see [JupyterLab Versioning in Amazon SageMaker Studio Classic](studio-jl.md). To create a shared space from the AWS CLI, run one of the following commands from the terminal of your local machine. ------ #### [ Studio Classic ] ``` aws --region region \ sagemaker create-space \ --domain-id domain-id \ --space-name space-name \ --space-settings '{ "JupyterServerAppSettings": { "DefaultResourceSpec": { "SageMakerImageArn": "sagemaker-image-arn", "InstanceType": "system" } } }' ``` ------ #### [ JupyterLab ] ``` aws --region region \ sagemaker create-space \ --domain-id domain-id \ --space-name space-name \ --ownership-settings "{\"OwnerUserProfileName\": \"user-profile-name\"}" \ --space-sharing-settings "{\"SharingType\": \"Shared\"}" \ --space-settings "{\"AppType\": \"JupyterLab\"}" ``` ------ # Get information about shared spaces **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the Studio Classic application. For information about using the updated Studio experience, see [Amazon SageMaker Studio](studio-updated.md). Studio Classic is still maintained for existing workloads but is no longer available for onboarding. You can only stop or delete existing Studio Classic applications and cannot create new ones. We recommend that you [migrate your workload to the new Studio experience](studio-updated-migrate.md). This guide shows how to access a list of shared spaces in an Amazon SageMaker AI domain with the Amazon SageMaker AI console, Amazon SageMaker Studio, or the AWS CLI. It also shows how to view details of a shared space from the AWS CLI. **Topics** + [ ## List shared spaces ](#domain-space-list-spaces) + [ ## View shared space details ](#domain-space-describe) ## List shared spaces The following topic describes how to view a list of shared spaces within a domain from the SageMaker AI console or the AWS CLI. ### List shared spaces from Studio Complete the following procedure to view a list of the shared spaces in a domain from Studio. 1. Navigate to Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. From the Studio UI, find the applications pane on the left side. 1. From the applications pane, select **Studio Classic** or **JupyterLab**. You can view the spaces that are being used to run the application type. ### List shared spaces from the console Complete the following procedure to view a list of the shared spaces in a domain from the SageMaker AI console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. From the list of domains, select the domain that you want to view the list of shared spaces for. 1. On the **domain details** page, choose the **Space management** tab. ### List shared spaces from the AWS CLI To list the shared spaces in a domain from the AWS CLI, run the following command from the terminal of your local machine. ``` aws --region region \ sagemaker list-spaces \ --domain-id domain-id ``` ## View shared space details The following section describes how to view shared space details from the SageMaker AI console, Studio, or the AWS CLI. ### View shared spaces details from Studio Complete the following procedure to view the details of a shared spaces in a domain from Studio. 1. Navigate to Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. From the Studio UI, find the applications pane on the left side. 1. From the applications pane, select **Studio Classic** or **JupyterLab**. You can view the spaces that are running the application. 1. Select the name of the space that you want to view more details for. ### View shared space details from the console You can view the details of a shared space from the SageMaker AI console using the following procedure. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. From the list of domains, select the domain that you want to view the list of shared spaces for. 1. On the **domain details** page, choose the **Space management** tab. 1. Select the name of the space to open a new page that lists details about the shared space. ### View shared space details from the AWS CLI To view the details of a shared space from the AWS CLI, run the following command from the terminal of your local machine. ``` aws --region region \ sagemaker describe-space \ --domain-id domain-id \ --space-name space-name ``` # Edit a shared space You can only edit the details for an Amazon SageMaker Studio Classic or JupyterLab shared space using the AWS CLI. You can't edit the details of a shared space from the Amazon SageMaker AI console. You can only update workspace attributes when there are no running applications in the shared space. ------ #### [ Studio Classic ] To edit the details of a Studio Classic shared space from the AWS CLI, run the following one of the following commands from the terminal of your local machine. shared spaces only support the use of JupyterLab 3 image ARNs. For more information, see [JupyterLab Versioning in Amazon SageMaker Studio Classic](studio-jl.md). ``` aws --region region \ sagemaker update-space \ --domain-id domain-id \ --space-name space-name \ --query SpaceArn --output text \ --space-settings '{ "JupyterServerAppSettings": { "DefaultResourceSpec": { "SageMakerImageArn": "sagemaker-image-arn", "InstanceType": "system" } } }' ``` ------ #### [ JupyterLab ] To edit the details of a JupyterLab shared space from the AWS CLI, run the following one of the following commands from the terminal of your local machine. shared spaces only support the use of JupyterLab 4 image ARNs. For more information, see [SageMaker JupyterLab](studio-updated-jl.md). ``` aws --region region \ sagemaker update-space \ --domain-id domain-id \ --space-name space-name \ --space-settings "{ "SpaceStorageSettings": { "EbsStorageSettings": { "EbsVolumeSizeInGb":100 } } } }" ``` ------ # Delete a shared space **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the Studio Classic application. For information about using the updated Studio experience, see [Amazon SageMaker Studio](studio-updated.md). Studio Classic is still maintained for existing workloads but is no longer available for onboarding. You can only stop or delete existing Studio Classic applications and cannot create new ones. We recommend that you [migrate your workload to the new Studio experience](studio-updated-migrate.md). The following topic shows how to delete an Amazon SageMaker Studio Classic shared space from the Amazon SageMaker AI console or AWS CLI. A shared space can only be deleted if it has no running applications. **Topics** + [ ## Console ](#domain-space-delete-console) + [ ## AWS CLI ](#domain-space-delete-cli) ## Console Complete the following procedure to delete a shared space in the Amazon SageMaker AI domain from the SageMaker AI console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. From the list of domains, select the domain that you want to create a shared space for. 1. On the **domain details** page, choose the **Space management** tab. 1. Select the shared space that you want to delete. The shared space must not contain any non-failed apps. 1. Choose **Delete**. This opens a new window. 1. Choose **Yes, delete space**. 1. Enter *delete* in the field. 1. Choose **Delete space**. ## AWS CLI To delete a shared space from the AWS CLI, run the following command from the terminal of your local machine. ``` aws --region region \ sagemaker delete-space \ --domain-id domain-id \ --space-name space-name ``` # Trusted identity propagation with Studio Trusted identity propagation is an AWS IAM Identity Center feature that administrators of connected AWS services can use to grant and audit access to service data. Access to this data is based on user attributes such as group associations. Setting up trusted identity propagation requires collaboration between the administrators of connected AWS services and the IAM Identity Center administrator. For more information, see [Prerequisites and considerations](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overall-prerequisites.html). The Amazon SageMaker Studio and IAM Identity Center administrators can collaborate to connect the services for trusted identity propagation. Trusted identity propagation addresses enterprise authentication needs across AWS services by simplifying: + Enhanced auditing that tracks actions to specific users + Access management for data science and machine learning workloads through integration with compatible AWS services + Compliance requirements in regulated industries Studio supports trusted identity propagation for audit purposes and access control with connected AWS services. Trusted identity propagation in Studio does not directly handle authentication or authorization decisions within Studio itself. Instead, it propagates identity context information to compatible services that can use this information for access control. When you use trusted identity propagation with Studio, your IAM Identity Center identity propagates to connected AWS services, creating more granular permissions and security governance. **Topics** + [ # Trusted identity propagation architecture and compatibility ](trustedidentitypropagation-compatibility.md) + [ # Setting up trusted identity propagation for Studio ](trustedidentitypropagation-setup.md) + [ # Monitoring and auditing with CloudTrail ](trustedidentitypropagation-auditing.md) + [ # User background sessions ](trustedidentitypropagation-user-background-sessions.md) + [ # How to connect with other AWS services with trusted identity propagation enabled ](trustedidentitypropagation-connect-other.md) # Trusted identity propagation architecture and compatibility Trusted identity propagation integrates AWS IAM Identity Center with Amazon SageMaker Studio and other connected AWS services to propagate users' identity context across services. The following page summarizes the trusted identity propagation architecture and compatibility with SageMaker AI. For a comprehensive overview of how trusted identity propagation works across AWS, see [Trusted identity propagation overview](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html). The key components of the trusted identity propagation architecture include: + **Trusted identity propagation**: A methodology of propagating user's identity context between applications and services + **Identity context**: Information about a user + **Identity-enhanced IAM role session**: Identity-enhanced role sessions have an added identity context that carries a user identifier to the AWS service that it calls + **Connected AWS services**: Other AWS services that can recognize the identity context that is propagated through trusted identity propagation Trusted identity propagation allows connected AWS services to make access decisions based on a user's identity. Within Studio itself, IAM roles are used as carriers of the identity context rather than for making access control decisions. The identity context is propagated to connected AWS services where it can be used for both access control and audit purposes. See [trusted identity propagation considerations](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overall-prerequisites.html#trustedidentitypropagation-considerations) for more information. When you enable trusted identity propagation with Studio and authenticate through IAM Identity Center, SageMaker AI: + Captures the user's identity context from the IAM Identity Center + Creates an identity-enhanced IAM role session that include the user's identity context + Passes identity-enhanced IAM role session to compatible AWS services when the user accesses resources + Enables downstream AWS services to make access decisions and log activities based on the user identity ## Compatible SageMaker AI features Trusted identity propagation works with the following Studio features: + [Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-launch.html) private spaces (JupyterLab and Code Editor, based on Code-OSS, Visual Studio Code - Open Source) **Note** When Studio launches with trusted identity propagation enabled, it uses your identity context in addition to your execution role permissions. However, the following processes during instance setup will only use the execution role permissions, without the identity context: Lifecycle Configuration, Bring-Your-Own-Image, CloudWatch agent for user log forwarding. [Remote access](https://docs.aws.amazon.com/sagemaker/latest/dg/remote-access.html) is not currently supported with trusted identity propagation. When you use assume role operations within Studio notebooks, the assumed roles don't propagate trusted identity propagation context. Only the original execution role maintains the identity context. + [SageMaker Training](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html) + [SageMaker Processing](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html) + [SageMaker AI realtime hosting](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-options.html) + [SageMaker Pipelines](https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-overview.html) + [SageMaker real-time inference](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html) + [SageMaker Asynchronous Inference](https://docs.aws.amazon.com/sagemaker/latest/dg/async-inference.html) + [Managed MLflow](https://docs.aws.amazon.com/sagemaker/latest/dg/mlflow.html) ## Compatible AWS services Trusted identity propagation for Amazon SageMaker Studio integrates with compatible AWS services, where trusted identity propagation is enabled. See [use cases](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-integrations.html) for a comprehensive list with examples on how to enable trusted identity propagation. The trusted identity propagation compatible services include the following. + [Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/workgroups-identity-center.html) + [Amazon EMR on EC2](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-idc-start.html) + [EMR Serverless](https://docs.aws.amazon.com/emr/latest/EMR-Serverless-UserGuide/security-iam-service-trusted-prop.html) + [AWS Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/identity-center-integration.html) + [Amazon Redshift Data API](https://docs.aws.amazon.com/redshift/latest/mgmt/data-api-trusted-identity-propagation.html) + Amazon S3 (via [Amazon S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-get-started.html)) + [AWS Glue Connections](https://docs.aws.amazon.com/glue/latest/dg/security-trusted-identity-propagation.html) When trusted identity propagation is enabled with SageMaker AI, each other AWS service with trusted identity propagation is enabled is connected. Once they are connected they recognize and use the user's identity context for access control and auditing. ## Supported AWS Regions Studio supports trusted identity propagation where [IAM Identity Center is supported](https://docs.aws.amazon.com/singlesignon/latest/userguide/regions.html) and Studio with IAM Identity Center authentication is supported. Studio supports trusted identity propagation in the following AWS Regions: + af-south-1 + ap-east-1 + ap-northeast-1 + ap-northeast-2 + ap-northeast-3 + ap-south-1 + ap-southeast-1 + ap-southeast-2 + ap-southeast-3 + ca-central-1 + eu-central-1 + eu-central-2 + eu-north-1 + eu-south-1 + eu-west-1 + eu-west-2 + eu-west-3 + il-central-1 + me-south-1 + sa-east-1 + us-east-1 + us-east-2 + us-west-1 + us-west-2 # Setting up trusted identity propagation for Studio Setting up trusted identity propagation for Amazon SageMaker Studio requires your Amazon SageMaker AI domain to have IAM Identity Center authentication method configured. This section guides you through the prerequisites and steps needed to enable and configure trusted identity propagation for your Studio users. **Topics** + [ ## Prerequisites ](#trustedidentitypropagation-setup-prerequisites) + [ ## Enable trusted identity propagation for your Amazon SageMaker AI domain ](#trustedidentitypropagation-setup-enable) + [ ## Configure your SageMaker AI execution role ](#trustedidentitypropagation-setup-permissions) ## Prerequisites Before setting up trusted identity propagation for SageMaker AI, set up your IAM Identity Center using the following instructions. **Note** Ensure that your IAM Identity Center and domain are in the same region. + [IAM Identity Center trusted identity propagation prerequisites](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overall-prerequisites.html#trustedidentitypropagation-prerequisites) + [Set up IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) + [Add users to your IAM Identity Center directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) ## Enable trusted identity propagation for your Amazon SageMaker AI domain **Important** You can only enable trusted identity propagation for domains with AWS IAM Identity Center authentication method configured. Your IAM Identity Center and Amazon SageMaker AI domain must be in the same AWS Region. Use one of the following options to learn how to enable trusted identity propagation for a new or existing domain. ------ #### [ New domain - console ] **Enable trusted identity propagation for a new domain using the SageMaker AI console** 1. Open the [Amazon SageMaker AI console](https://console.aws.amazon.com/sagemaker). 1. Navigate to **Domains**. 1. [Create a custom domain](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-custom.html). The domain must have the **AWS IAM Identity Center** authentication method configured. 1. In the **Trusted identity propagation** section, choose to **Enable the trusted identity propagation for all users on this domain**. 1. Complete the custom creation process. ------ #### [ Existing domain - console ] **Enable trusted identity propagation for an existing domain using the SageMaker AI console** **Note** For trusted identity propagation to work properly after it is enabled for an existing domain, users will need to restart their existing IAM Identity Center sessions. To do so, either: Users will need to log out and log back in to their existing IAM Identity Center sessions Administrators can [end active sessions for their workforce users](https://docs.aws.amazon.com/singlesignon/latest/userguide/end-active-sessions.html). 1. Open the [Amazon SageMaker AI console](https://console.aws.amazon.com/sagemaker). 1. Navigate to **Domains**. 1. Select your existing domain. The domain must have the **AWS IAM Identity Center** authentication method configured. 1. In the **Domain settings** tab, choose **Edit** in the **Authentication and permissions** section. 1. Choose to **Enable the trusted identity propagation for all users on this domain**. 1. Complete the domain configuration. ------ #### [ Existing domain - AWS CLI ] Enable trusted identity propagation for an existing domain using the AWS CLI **Note** For trusted identity propagation to work properly after it is enabled for an existing domain, users will need to restart their existing IAM Identity Center sessions. To do so, either: Users will need to log out and log back in to their existing IAM Identity Center sessions Administrators can [end active sessions for their workforce users](https://docs.aws.amazon.com/singlesignon/latest/userguide/end-active-sessions.html). ``` aws sagemaker update-domain \ --region $REGION \ --domain-id $DOMAIN_ID \ --domain-settings "TrustedIdentityPropagationSettings={Status=ENABLED}" ``` + `DOMAIN_ID` is the Amazon SageMaker AI domain ID. See [View domains](https://docs.aws.amazon.com/sagemaker/latest/dg/domain-view.html) for more information. + `REGION` is the AWS Region of your Amazon SageMaker AI domain. You can find this at the top right of any AWS console page. ------ ## Configure your SageMaker AI execution role To enable trusted identity propagation for your Studio users, all trusted identity propagation roles need the set the following context permissions. Update the trust policy for all roles to include the `sts:AssumeRole` and `sts:SetContext` actions. Use the following policy when you [update your role trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-trust-policy.html). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "sagemaker.amazonaws.com" ] }, "Action": [ "sts:AssumeRole", "sts:SetContext" ] } ] } ``` ------ # Monitoring and auditing with CloudTrail With trusted identity propagation enabled, AWS CloudTrail logs include the identity information of the specific user who performed an action, rather than just the IAM role. This provides enhanced auditing capabilities for compliance and security. To view identity information in CloudTrail logs: + Open the [CloudTrail console](https://console.aws.amazon.com/cloudtrail). + Choose **Event history** from the left navigation pane. + Choose events from SageMaker AI and related services. + Under the **Event record** find `onBehalfOf` key. This contains the `userId` key and other user identification information that can be mapped to a specific IAM Identity Center user. See [CloudTrail use cases for IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/sso-cloudtrail-use-cases.html) for more information. # User background sessions User background sessions continue even when the user is no longer active. These allow for long-running jobs that can continue even after the user has logged off. This can be enabled through SageMaker AI's trusted identity propagation. The following page explains the configuration options and behaviors for user background sessions. **Note** Existing active user sessions are not impacted when trusted identity propagation is enabled. The default duration applies only to new user sessions or restarted sessions. User background sessions apply to any long-running SageMaker AI workflows or jobs with persistent states. This includes, but is not limited to, any SageMaker AI resources that maintain execution status or require ongoing monitoring. For example, SageMaker Training, Processing, and Pipelines execution jobs. **Topics** + [ ## Configure user background session ](#configure-user-background-sessions) + [ ## Default user background session duration ](#default-user-background-session-duration) + [ ## Impact of disabling trusted identity propagation in Studio ](#user-background-session-impact-disable-trustedidentitypropagation-studio) + [ ## Impact of disabling user background sessions in the IAM Identity Center console ](#user-background-session-impact-disable-trustedidentitypropagation-identity-center) + [ ## Runtime considerations ](#user-background-session-runtime-considerations) ## Configure user background session Once trusted identity propagation for Amazon SageMaker Studio is enabled, default duration limits can be configured through the [user background sessions in the IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/user-background-sessions.html). ## Default user background session duration By default, all user background sessions have a duration limit of 7 days. Administrators can [modify this duration in the IAM Identity Center console](https://docs.aws.amazon.com/singlesignon/latest/userguide/user-background-sessions.html). This setting applies at the IAM Identity Center instance level, affecting all supported IAM Identity Center applications and Studio domains within that instance. When trusted identity propagation is enabled, administrators in the SageMaker AI console will find a banner with the following information: + The duration limit for user background sessions + A link to the IAM Identity Center console where administrators can change this configuration + The duration can be set to any value from 15 minutes up to 90 days An error message will occur when a user background session has expired. You can use the link to the IAM Identity Center console to update the duration. ## Impact of disabling trusted identity propagation in Studio If an administrator disables trusted identity propagation, after initially enabling it, in the SageMaker AI console: + Existing jobs continue to run without interruption when user background sessions are enabled. + When user background sessions are disabled, any long-running SageMaker AI workflows or jobs with persistent states will switch to using interactive sessions. This includes, but is not limited to, any SageMaker AI resources that maintain execution status or require ongoing monitoring. For example, Amazon SageMaker Training and Processing jobs. + Users can restart expired jobs from checkpoints. + New jobs run with IAM role credentials and do not propagate the identity context. ## Impact of disabling user background sessions in the IAM Identity Center console When the user background session is **disabled** for the IAM Identity Center instance, the SageMaker AI job uses user interactive sessions. When using interactive sessions, a SageMaker AI job will fail within 15 minutes when: + The user logs out + The interactive session is revoked by the administrator When the user background session is **enabled** for the IAM Identity Center instance, the SageMaker AI job uses user background sessions. When using interactive sessions, a SageMaker AI job will fail within 15 minutes when: + The user background session expires + The user background session is manually revoked by an administrator The following provides example behavior with SageMaker Training jobs. When an administrator enables trusted identity propagation but disables [user background sessions](https://docs.aws.amazon.com/singlesignon/latest/userguide/user-background-sessions.html) in the IAM Identity Center console: + If a user stays logged in, their Training jobs created while background sessions are disabled fallback to the interactive session. + If the user logs off, the session expires and Training jobs depending on the interactive session will fail. + Users can restart their Training job from the last checkpoint. The session duration is determined by what is set for the interactive session duration in the IAM Identity Center console. + If a user disables background sessions **after** starting a job, the job will continue to use its existing background sessions. In other words, SageMaker AI will not create any new background sessions. The same behavior applies if background sessions are enabled at the IAM Identity Center instance level but disabled specifically for the Studio application using [IAM Identity Center APIs](https://docs.aws.amazon.com/singlesignon/latest/APIReference/welcome.html). ## Runtime considerations When an administrator sets `MaxRuntimeInSeconds` for long-running Training or Processing jobs that is lower than the user background session duration, SageMaker AI runs the job for the minimum of either `MaxRuntimeInSeconds` or user background session duration. For more information about `MaxRuntimeInSeconds`, see [CreateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html#sagemaker-CreateTrainingJob-request-StoppingCondition). See [user background sessions in the IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/user-background-sessions.html) for information on how to set the runtime. # How to connect with other AWS services with trusted identity propagation enabled When trusted identity propagation is enabled for your Amazon SageMaker AI domain, the domain users can connect to other trusted identity propagation enabled AWS services. When trusted identity propagation is enabled, your identity context is automatically propagated to compatible services, allowing for fine-grained access control and improved auditing across your machine learning workflows. This integration eliminates the need for complex IAM role switching and provides a unified identity experience across AWS services. The following pages provide information on how to connect Amazon SageMaker Studio to other AWS services when trusted identity propagation is enabled. **Topics** + [ # Connect Studio JupyterLab notebooks to Amazon S3 Access Grants with trusted identity propagation enabled ](trustedidentitypropagation-s3-access-grants.md) + [ # Connect Studio JupyterLab notebooks to Amazon EMR with trusted identity propagation enabled ](trustedidentitypropagation-emr-ec2.md) + [ # Connect your Studio JupyterLab notebooks to EMR Serverless with trusted identity propagation enabled ](trustedidentitypropagation-emr-serverless.md) + [ # Connect Studio JupyterLab notebooks to Redshift Data API with trusted identity propagation enabled ](trustedidentitypropagation-redshift-data-apis.md) + [ # Connect Studio JupyterLab notebooks to Lake Formation and Athena with trusted identity propagation enabled ](trustedidentitypropagation-lake-formation-athena.md) # Connect Studio JupyterLab notebooks to Amazon S3 Access Grants with trusted identity propagation enabled You can use [Amazon S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html) to flexibly grant identity-based fine-grain access control to Amazon S3 locations. These grant Amazon S3 buckets access directly to your corporate users and groups. The following pages provides information and instructions on how to use Amazon S3 Access Grants with trusted identity propagation for SageMaker AI. ## Prerequisites To connect Studio to Lake Formation and Athena with trusted identity propagation enabled, ensure you have completed the following prerequisites: + [Setting up trusted identity propagation for Studio](trustedidentitypropagation-setup.md) + Follow the [getting started with Amazon S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-get-started.html) to set up Amazon S3 Access Grants for your bucket. See [scaling data access with Amazon S3 Access Grants](https://aws.amazon.com/blogs/storage/scaling-data-access-with-amazon-s3-access-grants/) for more information. **Note** Standard Amazon S3 APIs do not automatically work with Amazon S3 Access Grants. You must explicitly use Amazon S3 Access Grants APIs. See [Managing access with Amazon S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html) for more information. **Topics** + [ ## Prerequisites ](#s3-access-grants-prerequisites) + [ # Connect Amazon S3 Access Grants with Studio JupyterLab notebooks ](s3-access-grants-setup.md) + [ # Connect Studio JupyterLab notebooks to Amazon S3 Access Grants with Training and Processing jobs ](trustedidentitypropagation-s3-access-grants-jobs.md) # Connect Amazon S3 Access Grants with Studio JupyterLab notebooks Use the following information to grant Amazon S3 Access Grants in Studio JupyterLab notebooks. After Amazon S3 Access Grants is set up, [add the following permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) to your domain or user [execution role](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html#sagemaker-roles-get-execution-role). + `us-east-1` is your AWS Region + `111122223333` is your AWS account ID + `S3-ACCESS-GRANT-ROLE` is your Amazon S3 Access Grant role ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowDataAccessAPI", "Effect": "Allow", "Action": [ "s3:GetDataAccess" ], "Resource": [ "arn:aws:s3:us-east-1:111122223333:access-grants/default" ] }, { "Sid": "RequiredForTIP", "Effect": "Allow", "Action": "sts:SetContext", "Resource": "arn:aws:iam::111122223333:role/S3-ACCESS-GRANT-ROLE" } ] } ``` ------ Ensure that your Amazon S3 Access Grants role's trust policy allows the `sts:SetContext` and `sts:AssumeRole` actions. The following is an example policy for when you [update your role trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-trust-policy.html). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "access-grants.s3.amazonaws.com" ] }, "Action": [ "sts:AssumeRole", "sts:SetContext" ], "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333", "aws:SourceArn": "arn:aws:s3:us-east-1:111122223333:access-grants/default" } } } ] } ``` ------ ## Use Amazon S3 Access Grants to call Amazon S3 The following is an example Python script showing how Amazon S3 Access Grants can be used to call Amazon S3. This assumes you have already successfully set up trusted identity propagation with SageMaker AI. ``` import boto3 from botocore.config import Config def get_access_grant_credentials(account_id: str, target: str, permission: str = 'READ'): s3control = boto3.client('s3control') response = s3control.get_data_access( AccountId=account_id, Target=target, Permission=permission ) return response['Credentials'] def create_s3_client_from_credentials(credentials) -> boto3.client: return boto3.client( 's3', aws_access_key_id=credentials['AccessKeyId'], aws_secret_access_key=credentials['SecretAccessKey'], aws_session_token=credentials['SessionToken'] ) # Create client credentials = get_access_grant_credentials('111122223333', "s3://tip-enabled-bucket/tip-enabled-path/") s3 = create_s3_client_from_credentials(credentials) s3.list_objects(Bucket="tip-enabled-bucket", Prefix="tip-enabled-path/") ``` If you use a path to an Amazon S3 bucket where Amazon S3 access grant is not enabled, the call will fail. For other programming languages, see [Managing access with Amazon S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html) for more information. # Connect Studio JupyterLab notebooks to Amazon S3 Access Grants with Training and Processing jobs Use the following information to grant Amazon S3 Access Grants to access data in Amazon SageMaker Training and Processing jobs. When a user with trusted identity propagation enabled launches a SageMaker Training or Processing job that needs to access Amazon S3 data: + SageMaker AI calls Amazon S3 Access Grants to get temporary credentials based on the user's identity + If successful, these temporary credentials access the Amazon S3 data + If unsuccessful, SageMaker AI falls back to using the IAM role credentials **Note** To enforce that all of the permission are granted through Amazon S3 Access Grants, you will need to remove related Amazon S3 access permission your execution role and attach them to your corresponding [Amazon S3 Access Grant](https://docs.aws.amazon.com/singlesignon/latest/userguide/tip-tutorial-s3.html#tip-tutorial-s3-create-grant). **Topics** + [ ## Considerations ](#s3-access-grants-jobs-considerations) + [ ## Set up Amazon S3 Access Grants with Training and Processing jobs ](#s3-access-grants-jobs-setup) ## Considerations Amazon S3 Access Grants cannot be used with [Pipe mode](https://docs.aws.amazon.com/sagemaker/latest/dg/augmented-manifest-stream.html) for both SageMaker Training and Processing for Amazon S3 input. When trusted identity propagation is enabled, you cannot launch a SageMaker Training Job with the following feature + Remote Debug + Debugger + Profiler When trusted identity propagation is enabled, you cannot launch a Processing job with the following feature + DatasetDefinition ## Set up Amazon S3 Access Grants with Training and Processing jobs After Amazon S3 Access Grants is set up, [add the following permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) to your domain or user [execution role](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html#sagemaker-roles-get-execution-role). + `us-east-1` is your AWS Region + `111122223333` is your AWS account ID + `S3-ACCESS-GRANT-ROLE` is your Amazon S3 Access Grant role ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowDataAccessAPI", "Effect": "Allow", "Action": [ "s3:GetDataAccess", "s3:GetAccessGrantsInstanceForPrefix" ], "Resource": [ "arn:aws:s3:us-east-1:111122223333:access-grants/default" ] }, { "Sid": "RequiredForIdentificationPropagation", "Effect": "Allow", "Action": "sts:SetContext", "Resource": "arn:aws:iam::111122223333:role/S3-ACCESS-GRANT-ROLE" } ] } ``` ------ # Connect Studio JupyterLab notebooks to Amazon EMR with trusted identity propagation enabled Connecting Amazon SageMaker Studio JupyterLab notebooks to Amazon EMR clusters enables you to leverage the distributed computing power of Amazon EMR for large-scale data processing and analytics workloads. With trusted identity propagation enabled, your identity context is propagated to Amazon EMR, allowing for fine-grained access control and comprehensive audit trails. The following page provides instructions on how to connect your Studio notebook to Amazon EMR clusters. Once set up, you can use the `Connect to Cluster` option in your Studio notebook. To connect Studio to Amazon EMR with trusted identity propagation enabled, ensure you have completed the following setups: + [Setting up trusted identity propagation for Studio](trustedidentitypropagation-setup.md) + [Getting started with AWS IAM Identity Center integration for Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-idc-start.html) + [Enable communications between Studio and Amazon EMR clusters](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-notebooks-emr-cluster.html) **Connect to the Amazon EMR cluster** For a full list of options on how to connect your JupyterLab notebook to Amazon EMR, see [Connect to an Amazon EMR cluster](https://docs.aws.amazon.com/sagemaker/latest/dg/connect-emr-clusters.html). # Connect your Studio JupyterLab notebooks to EMR Serverless with trusted identity propagation enabled Amazon EMR Serverless provides a serverless option for running Apache Spark and Apache Hive applications without managing clusters. When integrated with trusted identity propagation, EMR Serverless automatically scales compute resources while maintaining your identity context for access control and auditing. This approach eliminates the operational overhead of cluster management while preserving the security benefits of identity-based access control. The following section provides information on how to connect your trusted identity propagation enabled Studio with the EMR Serverless. To connect Studio to Amazon EMR Serverless with trusted identity propagation enabled, ensure you have completed the following setups: + [Setting up trusted identity propagation for Studio](trustedidentitypropagation-setup.md) + [Trusted identity propagation with EMR Serverless](https://docs.aws.amazon.com/emr/latest/EMR-Serverless-UserGuide/security-iam-service-trusted-prop.html) + [Enable communications between Studio and EMR Serverless](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-notebooks-emr-serverless.html) **Connect to the EMR Serverless application** For a full list of options on how to connect your JupyterLab notebook to EMR Serverless, see [Connect to an EMR Serverless application](https://docs.aws.amazon.com/sagemaker/latest/dg/connect-emr-serverless-application.html). # Connect Studio JupyterLab notebooks to Redshift Data API with trusted identity propagation enabled Amazon Redshift Data API enables you to interact with your Amazon Redshift clusters programmatically without managing persistent connections. When combined with trusted identity propagation, the Redshift Data API provides secure, identity-based access to your data warehouse, allowing you to run SQL queries and retrieve results while maintaining full audit trails of user activities. This integration is particularly valuable for data science workflows that require access to structured data stored in Redshift. The following page includes information and instructions on how to connect trusted identity propagation with Amazon SageMaker Studio to Redshift Data API. To connect Studio to Redshift Data API with trusted identity propagation enabled, ensure you have completed the following setups: + [Setting up trusted identity propagation for Studio](trustedidentitypropagation-setup.md) + [Using Redshift Data API with trusted identity propagation](https://docs.aws.amazon.com/redshift/latest/mgmt/data-api-trusted-identity-propagation.html) + Ensure your execution role has relevant permissions for Redshift Data API. See [authorizing access](https://docs.aws.amazon.com/redshift/latest/mgmt/data-api-access.html) for more information. + [Simplify access management with Amazon Redshift and AWS Lake Formation for users in an External Identity Provider](https://aws.amazon.com/blogs/big-data/simplify-access-management-with-amazon-redshift-and-aws-lake-formation-for-users-in-an-external-identity-provider/) # Connect Studio JupyterLab notebooks to Lake Formation and Athena with trusted identity propagation enabled AWS Lake Formation and Amazon Athena work together to provide a comprehensive data lake solution with fine-grained access control and serverless query capabilities. Lake Formation centralizes permissions management for your data lake, while Athena provides interactive query services. When integrated with trusted identity propagation, this combination enables data scientists to access only the data they're authorized to see, with all queries and data access automatically logged for compliance and auditing purposes. The following page provides information and instructions on how to connect trusted identity propagation with Amazon SageMaker Studio to Lake Formation and Athena To connect Studio to Lake Formation and Athena with trusted identity propagation enabled, ensure you have completed the following setups: + [Setting up trusted identity propagation for Studio](trustedidentitypropagation-setup.md) + [Create a Lake Formation role](https://docs.aws.amazon.com/lake-formation/latest/dg/prerequisites-identity-center.html) + [Connect Lake Formation with IAM Identity Center](https://docs.aws.amazon.com/lake-formation/latest/dg/connect-lf-identity-center.html) + Create Lake Formation resources: + [Database](https://docs.aws.amazon.com/lake-formation/latest/dg/creating-database.html) + [Tables](https://docs.aws.amazon.com/lake-formation/latest/dg/creating-tables.html) + [Create Athena workgroup](https://docs.aws.amazon.com/athena/latest/ug/creating-workgroups.html) + Choose **AthenaSQL** for the engine + Choose **IAM Identity Center** for authentication method + Create a new service role + Ensure that the IAM Identity Center users have access to the query result location using Amazon S3 Access Grants + [Granting database permissions using the named resource method](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-database-permissions.html) # Perform common UI tasks **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). The following sections describe how to perform common tasks in the Amazon SageMaker Studio UI. For an overview of the Studio user interface, see [Amazon SageMaker Studio UI overview](studio-updated-ui.md). **Set cookie preferences** 1. Launch Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. At the bottom of the Studio user interface, choose **Cookie Preferences**. 1. Select the check box for each type of cookie that you want Amazon SageMaker AI to use. 1. Choose **Save preferences**. **Manage notifications** Notifications give information about important changes to Studio, updates to applications, and issues to resolve. 1. Launch Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. On the top navigation bar, choose the **Notifications** icon (![\[Logo for Notifications, a cloud service with a stylized bell icon.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/monarch/notification.png)). 1. From the list of notifications, select the notification to get information about it. **Leave feedback** We take your feedback seriously. We encourage you to provide feedback. At the top navigation of Studio, choose **Provide feedback**. **Sign out** Signing out of the Studio UI is different than closing the browser window. Signing out clears session data from the browser and deletes unsaved changes. This same behavior also happens when the Studio session times out. This happens after 5 minutes. 1. Launch Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. Choose the **User options** icon (![\[User icon with a circular avatar placeholder and a downward-pointing arrow.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/monarch/user-settings.png)). 1. Choose **Sign out**. 1. In the pop-up window, choose **Sign out**. # NVMe stores with Amazon SageMaker Studio Amazon SageMaker Studio applications and their associated notebooks run on Amazon Elastic Compute Cloud (Amazon EC2) instances. Some of the Amazon EC2 instance types, such as the `ml.m5d` instance family, offer non-volatile memory express (NVMe) solid state drives (SSD) instance stores. NVMe instance stores are local ephemeral disk stores that are physically connected to an instance for fast temporary storage. Studio applications support NVMe instance stores for supported instance types. For more information about instance types and their associated NVMe store volumes, see the [Amazon Elastic Compute Cloud Instance Type Details](https://aws.amazon.com/ec2/instance-types/). This topic provides information about accessing and using NVMe instance stores, as well as considerations when using NVMe instance stores with Studio. ## Considerations The following considerations apply when using NVMe instance stores with Studio. + An NVMe instance store is temporary storage. The data stored on the NVMe store is deleted when the instance is terminated, stopped, or hibernated. When using NVMe stores with Studio applications, the data on the NVMe instance store is lost whenever the application is deleted, restarted, or patched. We recommend that you back up valuable data to persistent storage solutions, such as Amazon Elastic Block Store, Amazon Elastic File System, or Amazon Simple Storage Service. + Studio patches instances periodically to install new security updates. When an instance is patched, the instance is restarted. This restart results in the deletion of data stored in the NVMe instance store. We recommend that you frequently back up necessary data from the NVMe instance store to persistent storage solutions, such as Amazon Elastic Block Store, Amazon Elastic File System, or Amazon Simple Storage Service. + The following Studio applications support using NVMe storage: + JupyterLab + Code Editor, based on Code-OSS, Visual Studio Code - Open Source + KernelGateway ## Access NVMe instance stores When you select an instance type with attached NVMe instance stores to host a Studio application, the NVMe instance store directory is mounted to the application container at the following location: ``` /mnt/sagemaker-nvme ``` If an instance has more than 1 NVMe instance store attached to it, Studio creates a striped logical volume that spans all of the local disks attached. Studio then mounts this striped logical volume to the `/mnt/sagemaker-nvme` directory. As a result, the directory storage size is the sum of all NVMe instance store volume sizes attached to the instance. If the `/mnt/sagemaker-nvme` directory does not exist, verify that the instance type hosting your application has an attached NVMe instance store volume. # Local mode support in Amazon SageMaker Studio **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. Amazon SageMaker Studio applications support the use of local mode to create estimators, processors, and pipelines, then deploy them to a local environment. With local mode, you can test machine learning scripts before running them in Amazon SageMaker AI managed training or hosting environments. Studio supports local mode in the following applications: + Amazon SageMaker Studio Classic + JupyterLab + Code Editor, based on Code-OSS, Visual Studio Code - Open Source Local mode in Studio applications is invoked using the SageMaker Python SDK. In Studio applications, local mode functions similarly to how it functions in Amazon SageMaker notebook instances, with some differences. With the [Rootless Docker configuration](studio-updated-local-get-started.md#studio-updated-local-rootless) enabled, you can also access additional Docker registries through your VPC configuration, including on-premises repositories, and public registries. For more information about using local mode with the SageMaker Python SDK, see [Local Mode](https://sagemaker.readthedocs.io/en/stable/overview.html#local-mode). **Note** Studio applications do not support multi-container jobs in local mode. Local mode jobs are limited to a single instance for training, inference, and processing jobs. When creating a local mode job, the instance count configuration must be `1`.  ## Docker support As part of local mode support, Studio applications support limited Docker access capabilities. With this support, users can interact with the Docker API from Jupyter notebooks or the image terminal of the application. Customers can interact with Docker using one of the following: + [Docker CLI](https://docs.docker.com/engine/reference/run/) + [Docker Compose CLI ](https://docs.docker.com/compose/reference/) + Language specific Docker SDK clients Studio also supports limited Docker access capabilities with the following restrictions: + Usage of Docker networks is not supported. + Docker [volume](https://docs.docker.com/storage/volumes/) usage is not supported during container run. Only volume bind mount inputs are allowed during container orchestration. The volume bind mount inputs must be located on the Amazon Elastic File System (Amazon EFS) volume for Studio Classic. For JupyterLab and Code Editor applications, it must be located on the Amazon Elastic Block Store (Amazon EBS) volume. + Container inspect operations are allowed. + Container port to host mapping is not allowed. However, you can specify a port for hosting. The endpoint is then accessible from Studio using the following URL: ``` http://localhost:port ``` ### Docker operations supported The following table lists all of the Docker API endpoints that are supported in Studio, including any support limitations. If an API endpoint is missing from the table, Studio doesn't support it. | API Documentation | Limitations | | --- | --- | | [SystemAuth](https://docs.docker.com/engine/api/v1.43/#tag/System/operation/SystemAuth) | | | [SystemEvents](https://docs.docker.com/engine/api/v1.43/#tag/System/operation/SystemEvents) | | | [SystemVersion](https://docs.docker.com/engine/api/v1.43/#tag/System/operation/SystemVersion) | | | [SystemPing](https://docs.docker.com/engine/api/v1.43/#tag/System/operation/SystemPing) | | | [SystemPingHead](https://docs.docker.com/engine/api/v1.43/#tag/System/operation/SystemPingHead) | | | [ContainerCreate](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerCreate) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-local.html) | | [ContainerStart](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerStart) | | | [ContainerStop](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerStop) | | | [ContainerKill](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerKill) | | | [ContainerDelete](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerDelete) | | | [ContainerList](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerList) | | | [ContainerLogs](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerLogs) | | | [ContainerInspect](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) | | | [ContainerWait](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerWait) | | | [ContainerAttach](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerAttach) | | | [ContainerPrune](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerPrune) | | | [ContainerResize](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerResize) | | | [ImageCreate](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageCreate) | VPC-only mode support is limited to Amazon ECR images in allowlisted accounts. With the [Rootless Docker configuration](studio-updated-local-get-started.md#studio-updated-local-rootless) enabled, you can also access additional Docker registries through your VPC configuration, including on-premises repositories, and public registries. | | [ImagePrune](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImagePrune) | | | [ImagePush](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImagePush) | VPC-only mode support is limited to Amazon ECR images in allowlisted accounts. With the [Rootless Docker configuration](studio-updated-local-get-started.md#studio-updated-local-rootless) enabled, you can also access additional Docker registries through your VPC configuration, including on-premises repositories, and public registries. | | [ImageList](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageList) | | | [ImageInspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) | | | [ImageGet](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageGet) | | | [ImageDelete](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageDelete) | | | [ImageBuild](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageBuild) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-local.html) | **Topics** + [ ## Docker support ](#studio-updated-local-docker) + [ # Getting started with local mode ](studio-updated-local-get-started.md) # Getting started with local mode The following sections outline the steps needed to get started with local mode in Amazon SageMaker Studio, including: + Completing prerequisites + Setting `EnableDockerAccess` + Docker installation ## Prerequisites Complete the following prerequisites to use local mode in Studio applications: + To pull images from an Amazon Elastic Container Registry repository, the account hosting the Amazon ECR image must provide access permission for the user’s execution role. The domain’s execution role must also allow Amazon ECR access. + Verify that you are using the latest version of the Studio Python SDK by using the following command:  ``` pip install -U sagemaker ``` + To use local mode and Docker capabilities, set the following parameter of the domain’s `DockerSettings` using the AWS Command Line Interface (AWS CLI):  ``` EnableDockerAccess : ENABLED ``` + Using `EnableDockerAccess`, you can also control whether users in the domain can use local mode. By default, local mode and Docker capabilities aren't allowed in Studio applications. For more information, see [Setting `EnableDockerAccess`](#studio-updated-local-enable). + Install the Docker CLI in the Studio application by following the steps in [Docker installation](#studio-updated-local-docker-installation). + For the [Rootless Docker configuration](#studio-updated-local-rootless), ensure your VPC has appropriate endpoints and routing configured for your desired Docker registries. ## Setting `EnableDockerAccess` The following sections show how to set `EnableDockerAccess` when the domain has public internet access or is in `VPC-only` mode. **Note** Changes to `EnableDockerAccess` only apply to applications created after the domain is updated. You must create a new application after updating the domain. **Public internet access** The following example commands show how to set `EnableDockerAccess` when creating a new domain or updating an existing domain with public internet access: ``` # create new domain aws --region region \ sagemaker create-domain --domain-name domain-name \ --vpc-id vpc-id \ --subnet-ids subnet-ids \ --auth-mode IAM \ --default-user-settings "ExecutionRole=execution-role" \ --domain-settings '{"DockerSettings": {"EnableDockerAccess": "ENABLED"}}' \ --query DomainArn \ --output text # update domain aws --region region \ sagemaker update-domain --domain-id domain-id \ --domain-settings-for-update '{"DockerSettings": {"EnableDockerAccess": "ENABLED"}}' ``` **`VPC-only` mode** When using a domain in `VPC-only` mode, Docker image push and pull requests are routed through the service VPC instead of the VPC configured by the customer. Because of this functionality, administrators can configure a list of trusted AWS accounts that users can make Amazon ECR Docker pull and push operations requests to. If a Docker image push or pull request is made to an AWS account that is not in the list of trusted AWS accounts, the request fails. Docker pull and push operations outside of Amazon Elastic Container Registry (Amazon ECR) aren't supported in `VPC-only` mode. The following AWS accounts are trusted by default: + The account hosting the SageMaker AI domain. + SageMaker AI accounts that host the following SageMaker images: + DLC framework images + Sklearn, Spark, XGBoost processing images To configure a list of additional trusted AWS accounts, specify the `VpcOnlyTrustedAccounts` value as follows: ``` aws --region region \ sagemaker update-domain --domain-id domain-id \ --domain-settings-for-update '{"DockerSettings": {"EnableDockerAccess": "ENABLED", "VpcOnlyTrustedAccounts": ["account-list"]}}' ``` **Note** When the [Rootless Docker configuration](#studio-updated-local-rootless) is enabled, `VpcOnlyTrustedAccounts` is ignored and Docker traffic routes through your VPC configuration, allowing access to any registry your VPC can reach. ## Rootless Docker configuration When [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DockerSettings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DockerSettings.html) is enabled, Studio uses a [rootless Docker daemon](https://docs.docker.com/engine/security/rootless/) that routes traffic through your VPC. This provides enhanced security and allows access to additional Docker registries. The key differences with `RootlessDocker` are: + Your VPC configuration determines which registries are accessible for Docker operations. `VpcOnlyTrustedAccounts` is ignored and Docker traffic routes through your VPC configuration. To use rootless Docker, you will need to set both `EnableDockerAccess` and `RootlessDocker` to `ENABLED` for your `DockerSettings`. For example, in the [Setting `EnableDockerAccess`](#studio-updated-local-enable) examples above, you can modify your domain settings to include: ``` '{"DockerSettings": {"EnableDockerAccess": "ENABLED", "RootlessDocker": "ENABLED"}}' ``` ## Docker installation To use Docker, you must manually install Docker from the terminal of your Studio application. The steps to install Docker are different if the domain has access to the internet or not. ### Internet access If the domain is created with public internet access or in `VPC-only` mode with limited internet access, use the following steps to install Docker. 1. (Optional) If your domain is created in `VPC-only` mode with limited internet access, create a public NAT gateway with access to the Docker website. For instructions, see [NAT gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html). 1. Navigate to the terminal of the Studio application that you want to install Docker in. 1. To return the operating system of the application, run the following command from the terminal: ``` cat /etc/os-release ``` 1. Install Docker following the instructions for the operating system of the application in the [Amazon SageMaker AI Local Mode Examples repository](https://github.com/aws-samples/amazon-sagemaker-local-mode/tree/main/sagemaker_studio_docker_cli_install). For example, install Docker on Ubuntu following the script at [https://github.com/aws-samples/amazon-sagemaker-local-mode/blob/main/sagemaker\$1studio\$1docker\$1cli\$1install/sagemaker-ubuntu-focal-docker-cli-install.sh](https://github.com/aws-samples/amazon-sagemaker-local-mode/blob/main/sagemaker_studio_docker_cli_install/sagemaker-ubuntu-focal-docker-cli-install.sh) with the following considerations: + If chained commands fail, run commands one at a time. + Studio only supports Docker version `20.10.X.` and Docker Engine API version `1.41`. + The following packages aren't required to use the Docker CLI in Studio and their installation can be skipped: + `containerd.io` + `docker-ce` + `docker-buildx-plugin` **Note** You do not need to start the Docker service in your applications. The instance that hosts the Studio application runs Docker service by default. All Docker API calls are routed through the Docker service automatically. 1. Use the exposed Docker socket for Docker interactions within Studio applications. By default, the following socket is exposed: ``` unix:///docker/proxy.sock ``` The following Studio application environmental variable for the default `USER` uses this exposed socket: ``` DOCKER_HOST ``` ### No internet access If the domain is created in `VPC-only` mode with no internet access, use the following steps to install Docker. 1. Navigate to the terminal of the Studio application that you want to install Docker in. 1. Run the following command from the terminal to return the operating system of the application: ``` cat /etc/os-release ``` 1. Download the required Docker `.deb` files to your local machine. For instructions about downloading the required files for the operating system of the Studio application, see [Install Docker Engine](https://docs.docker.com/engine/install/). For example, install Docker from a package on Ubuntu following the steps 1–4 in [Install from a package](https://docs.docker.com/engine/install/ubuntu/#install-from-a-package) with the following considerations: + Install Docker from a package. Using other methods to install Docker will fail. + Install the latest packages corresponding to Docker version `20.10.X`. + The following packages aren't required to use the Docker CLI in Studio. You don't need to install the following: + `containerd.io` + `docker-ce` + `docker-buildx-plugin` **Note** You do not need to start the Docker service in your applications. The instance that hosts the Studio application runs Docker service by default. All Docker API calls are routed through the Docker service automatically. 1. Upload the `.deb` files to the Amazon EFS file system or to the Amazon EBS file system of the application. 1. Manually install the `docker-ce-cli` and `docker-compose-plugin` `.deb` packages from the Studio application terminal. For more information and instructions, see step 5 in [Install from a package](https://docs.docker.com/engine/install/ubuntu/#install-from-a-package) on the Docker docs website. 1. Use the exposed Docker socket for Docker interactions within Studio applications. By default, the following socket is exposed: ``` unix:///docker/proxy.sock ``` The following Studio application environmental variable for the default `USER` uses this exposed socket: ``` DOCKER_HOST ``` # View your Studio running instances, applications, and spaces **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). The following topics include information and instructions about how to view your Studio running instances, applications, and spaces. For more information about Studio spaces, see [Amazon SageMaker Studio spaces](studio-updated-spaces.md). ## View your Studio running instances and applications The **Running instances** page gives information about all running application instances that were created in Amazon SageMaker Studio by the user, or were shared with the user. You can view and stop running instances for all of your applications and spaces. If an instance is stopped, it does not appear on this page. Stopped instances can be viewed from the landing page for their respective application types. You can view a list of running applications and their details in Studio. **To view running instances** 1. Launch Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. On the left navigation pane, choose **Running instances**. 1. From the **Running instances** page, you can view a list of running applications and details about those applications. To view non-running instances, from the left navigation pane choose, the relevant application under **Applications**. The non-running applications will have the **Stopped** status under the **Status** column. ## View your Studio spaces The **Spaces** section within your **Domain details** page gives information about Studio spaces within your domain. You can view, create, and delete spaces on this page. The spaces that you can view in the **Spaces** section are running spaces for the following: + JupyterLab private space. For information about JupyterLab, see [SageMaker JupyterLab](studio-updated-jl.md). + Code Editor private space. For information about Code Editor, based on Code-OSS, Visual Studio Code - Open Source, see [Code Editor in Amazon SageMaker Studio](code-editor.md). + Studio Classic shared space. For information about Studio Classic shared space, see [Collaboration with shared spaces](domain-space.md). There are no spaces for SageMaker Canvas, Studio Classic (private), or RStudio. **View your Studio spaces in a domain** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the domain where you want to view the spaces. 1. On the **Domain details** page, choose the **Space management** tab to open the **Spaces** section. **View your Studio spaces using the AWS CLI** Use the following command to list all spaces in your domain: ``` aws sagemaker list-spaces --region us-east-1 --domain-id domain-id ``` + `us-east-1` is your AWS Region. + *domain-id* is your domain ID. See [View domains](domain-view.md) for more information. # Stop and delete your Studio running applications and spaces The following page includes information and instructions on how to stop and delete unused Amazon SageMaker Studio resources to avoid unwanted additional costs. For the Studio resources you no longer you wish to use, you will need to both: + Stop the application: This stops both the application and deletes the instance that the application is running on. Once you stop an application you can start it back up again. + Delete the space: This deletes the Amazon EBS volume that was created for the application and instance. **Important** If you delete the space, you will lose access to the data within that space. Do not delete the space unless you're sure that you want to. For more information about the differences between Studio spaces and applications, see [View your Studio running instances, applications, and spaces](studio-updated-running.md). **Topics** + [ ## Stop your Amazon SageMaker Studio application ](#studio-updated-running-stop-app) + [ ## Delete a Studio space ](#studio-updated-running-stop-space) ## Stop your Amazon SageMaker Studio application To avoid additional charges from unused running applications, you must stop them. The following includes information on what stopping an application does and how to do it. + The following instructions uses the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteApp.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteApp.html) API to stop the application. This also stops the instance that the application is running on. + After you stop an application, you can start up the application again later. + When you stop an application, the files in the space will persist. You can run the application again and expect to have access to the same files that are stored in the space, as you did before deleting the application. + When you stop an application, the *metadata* for the application will be deleted within 24 hours. For more information, see the note in the `CreationTime` response element for the [DescribeApp](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeApp.html#sagemaker-DescribeApp-response-CreationTime) API. **Note** If the service detects that an application is unhealthy, it assumes the [AmazonSageMakerNotebooksServiceRolePolicy](security-iam-awsmanpol-notebooks.md#security-iam-awsmanpol-AmazonSageMakerNotebooksServiceRolePolicy) service linked role and deletes the application using the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteApp.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteApp.html) API. The following tabs provide instructions to stop an application from your domain using the Studio UI, the SageMaker AI console, or the AWS CLI. **Note** To view and stop all of your Studio running instances in one location, we recommend the [Stop applications using the Studio UI](#studio-updated-running-stop-app-using-studio-updated-ui) workflow from the following options. ### Stop applications using the Studio UI To stop your Studio applications using the Studio UI, use the following instructions. **To delete your applications (Studio UI)** 1. Launch Studio. This process may differ depending on your setup. For information about launching Studio, see [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. From the left navigation pane, choose **Running instances**. If the table on the page is empty, you don't have any running instances or applications in your spaces. 1. In the table under the **Name** and **Application** columns, find the space name and the application that you want to stop. 1. Choose the corresponding **Stop** button to stop the application. ### Stop applications using the SageMaker AI console To view or stop Studio running instances from a centralized location, see [Stop applications using the Studio UI](#studio-updated-running-stop-app-using-studio-updated-ui). Otherwise, use the following instructions. In the SageMaker AI console, you can only stop the running Studio applications for the spaces that you are able to view in the **Spaces** section of the console. For a list of the viewable spaces, see [View your Studio spaces](studio-updated-running.md#studio-updated-running-view-space). These steps show how to stop your Studio applications by using the SageMaker AI console. **To stop your applications (SageMaker AI console)** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the domain that you want to revert. 1. On the **Domain details** page, choose the **Space management** tab. 1. **Important** In the **Space management** tab, you have the option to delete the space. There is a difference between deleting the space and deleting an application. If you delete the space, you will lose access to the data within that space. Do not delete the space unless you're sure that you want to. To stop the application, in the **Space management** tab and under the **Name** column, choose the space for the application. 1. In the **Apps** section and under the **App type** column, search for the app to stop. 1. Under the **Action** column, choose the corresponding **Delete app** button. 1. In the pop-up box, choose **Yes, delete app**. After you do so the delete input field becomes available. 1. Enter **delete** in the delete input field to confirm deletion. 1. Choose **Delete**. ### Stop your domain applications using the AWS CLI To view or stop any of your Studio running instances from a centralized location, see [Stop applications using the Studio UI](#studio-updated-running-stop-app-using-studio-updated-ui). Otherwise, use the following instructions. The following code examples use the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteApp.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteApp.html) API to stop an application in an example domain. To stop your running **JupyterLab** or **Code Editor** instances, use the following code example: ``` aws sagemaker delete-app \ --domain-id example-domain-id \ --region AWS Region \ --app-name default \ --app-type example-app-type \ --space-name example-space-name ``` + To obtain your `example-domain-id`, use the following instructions: **To get `example-domain-id`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the relevant domain. 1. On the **Domain details** page, choose the **Domain settings** tab. 1. Copy the **Domain ID**. + To obtain your `AWS Region`, use the following instructions to ensure you are using the correct AWS Region for your domain: **To get `AWS Region`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the relevant domain. 1. On the **Domain details** page, verify that this is the relevant domain. 1. Expand the region dropdown list from the top right of the SageMaker AI console, and use the corresponding AWS Region ID to the right of your AWS Region name. For example, `us-west-1`. + For `example-app-type`, use the application type that's relevant to the application that you want to stop. For example, replace `example-app-type` with one of the following application types: + JupyterLab application type: `JupyterLab`. For information about JupyterLab, see [SageMaker JupyterLab](studio-updated-jl.md). + Code Editor application type: `CodeEditor`. For information about Code Editor, based on Code-OSS, Visual Studio Code - Open Source, see [Code Editor in Amazon SageMaker Studio](code-editor.md). + To obtain your `example-space-name`, use the following steps: **To get `example-space-name`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the relevant domain. 1. On the **Domain details** page, choose the **Space management** tab. 1. Copy the relevant space name. To stop running instances for **SageMaker Canvas**, **Studio Classic**, or **RStudio**, use the following code example: ``` aws sagemaker delete-app \ --domain-id example-domain-id \ --region AWS Region \ --app-name default \ --app-type example-app-type \ --user-profile example-user-name ``` + For `example-app-type`, use the application type relevant to the application that you want to stop. For example, replace `example-app-type` with one of the following application types: + SageMaker Canvas application type: `Canvas`. For information about SageMaker Canvas, see [Amazon SageMaker Canvas](canvas.md). + Studio Classic application type: `JupyterServer`. For information about Studio Classic, see [Amazon SageMaker Studio Classic](studio.md). + RStudio application type: `RStudioServerPro`. For information about RStudio, see [RStudio on Amazon SageMaker AI](rstudio.md). + To obtain your `example-user-name`, navigate to the **Domain details** page. + Next, choose the **User profiles** tab, and copy the relevant space name. For alternative instructions to stop your running Studio applications, see: + JupyterLab: [Delete unused resources](studio-updated-jl-admin-guide-clean-up.md). + Code Editor: [Shut down Code Editor resources](code-editor-use-log-out.md). + SageMaker Canvas: [Logging out of Amazon SageMaker Canvas](canvas-log-out.md). + Studio Classic: [Shut Down and Update Amazon SageMaker Studio Classic and Apps](studio-tasks-update.md). + RStudio: [Shut down RStudio](rstudio-shutdown.md). ## Delete a Studio space **Important** After you delete your space, you will lose all of the data stored in the space. We recommend that you back up your data before deleting your space. You will need to have administrator permissions, or at least have permissions to update domain, IAM, and Amazon S3, to delete a Studio space. + Spaces are used to manage the storage and resource needs of the relevant application. When you delete a space, the storage volume also deletes. Therefore, you lose access to the files stored on that space. For more information about Studio spaces, see [Amazon SageMaker Studio spaces](studio-updated-spaces.md). We recommend that you back up your data if you choose to delete a space. + After you delete a space, you can't access that space again. You can delete the Studio spaces that are viewable in the **Spaces** section of the console. For a list of the viewable spaces, see [View your Studio spaces](studio-updated-running.md#studio-updated-running-view-space). There are no spaces for SageMaker Canvas, Studio Classic (private), and RStudio. To stop and delete your SageMaker Canvas, Studio Classic (private), or RStudio applications, see [Stop your Amazon SageMaker Studio application](#studio-updated-running-stop-app). ### Delete a space using the SageMaker AI console The **Spaces** section within your **Domain details** page gives information about Studio spaces within your domain. You can view, create, and delete spaces on this page. **To view Studio spaces in a domain** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the domain where you want to view the spaces. 1. On the **Domain details**, choose **Space management** to open the **Spaces** section. 1. Select the space to delete. 1. Choose **Delete**. 1. In the pop-up box titled **Delete space**, you have two options: + If you already shut down all applications in the space, choose **Yes, delete space**. + If you still have applications running in the space, choose **Yes, shut down all apps and delete space**. 1. Enter **delete** in the delete input field to confirm deletion. 1. To delete the space, you have two options: + If you already shut down all applications in the space, choose **Delete space**. + If you still have applications running in the space, choose **Shut down all apps and delete space**. ### Delete a space using the AWS CLI Before you can delete a space using the AWS CLI, you must delete the application associated with it. For information about stopping your Studio applications, see [Stop your Amazon SageMaker Studio application](#studio-updated-running-stop-app). Use the following AWS CLI command to delete a space within a domain: ``` aws sagemaker delete-space \ --domain-id example-domain-id \ --region AWS Region \ --space-name example-space-name ``` + To obtain your `example-domain-id`, use the following instructions: **To get `example-domain-id`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the relevant domain. 1. On the **Domain details** page, choose the **Domain settings** tab. 1. Copy the **Domain ID**. + To obtain your `AWS Region`, use the following instructions to ensure you are using the correct AWS Region for your domain: **To get `AWS Region`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the relevant domain. 1. On the **Domain details** page, verify that this is the relevant domain. 1. Expand the region dropdown list from the top right of the SageMaker AI console, and use the corresponding AWS Region ID to the right of your AWS Region name. For example, `us-west-1`. + To obtain your `example-space-name`, use the following steps: **To get `example-space-name`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the relevant domain. 1. On the **Domain details** page, choose the **Space management** tab. 1. Copy the relevant space name. # SageMaker Studio image support policy **Important** Currently, all packages in SageMaker Distribution images are licensed for use with Amazon SageMaker AI and do not require additional commercial licenses. However, this might be subject to change in the future, and we recommend reviewing the licensing terms regularly for any updates. Amazon SageMaker Distribution is a set of Docker images available on SageMaker Studio that include popular frameworks for machine learning, data science, and visualization. The images include deep learning frameworks like PyTorch, TensorFlow and Keras; popular Python packages like numpy, scikit-learn and pandas; and IDEs like JupyterLab and Code Editor, based on Code-OSS, Visual Studio Code - Open Source. The distribution contains the latest versions of all these packages such that they are mutually compatible. This page details the support policy and availability for SageMaker Distribution Images on SageMaker Studio. ## Versioning, release cadence, and support policy The table below outlines the release schedule for SageMaker Distribution Image versions and their planned support. AWS provides ongoing functionality and security updates for supported image versions. New minor versions are released for major versions for 12 months, and supported minor versions receive ongoing functionality and security patches. In some cases, an image version may need to be designated end of support earlier than originally planned if (a) security issues cannot be addressed while maintaining semantic versioning guidelines or (b) any of our major dependencies, like Python, reach end-of-life. AWS releases ad-hoc major or minor versions on an as-needed basis. | Version | Description | Release cadence | Planned support | | --- | --- | --- | --- | | Major | Amazon SageMaker Distribution's major version releases involve upgrading all of its core dependencies to the latest compatible versions. These major releases may also add or remove packages as part of the update. Major versions are denoted by the first number in the version string, such as 1.0, 2.0, or 3.0. | 6 months | 18 months | | Minor | Amazon SageMaker Distribution's minor version releases include upgrading all of its core dependencies to the latest compatible minor versions within the same major version. SageMaker Distribution can add new packages during a minor version release. Minor versions are denoted by the second number in the version string, for example, 1.1, 1.2, or 2.1. | 1 month | 6 months | | Patch | Amazon SageMaker Distribution's patch version releases include updating all of its core dependencies to the latest compatible patch versions within the same minor version. SageMaker Distribution does not add or remove any packages during a patch version release. Patch versions are denoted by the third number in the version string, for example, 1.1.1, 1.2.1, or 2.1.3. Since patch versions are generally released for fixing security vulnerabilities, we recommend always upgrading to the newest patch version when they become available. | As necessary for fixing security vulnerabilities | Until new patch version is released | Each major version of the Amazon SageMaker Distribution is available for 18 months. During the first 12 months, new minor versions are released monthly. For the remaining 6 months, the existing minor versions continue to be supported. ## Supported image versions The tables below list the supported SageMaker Distribution image versions, their planned end of support dates, and their availability on SageMaker Studio. For image versions where support ends sooner than the planned end of support date, the versions continue to be available on Studio until the designated availability date. You can continue using the image to launch applications for up to 90 days or until the availability date on Studio, whichever comes first. For more information about such cases, reach out to Support. You can migrate to a newer supported version as soon as possible to ensure that you receive ongoing functionality and security updates. When choosing an image version in SageMaker Studio, we recommend that you choose a supported image version from the tables below. ### Supported major versions The following table lists the supported SageMaker Distribution major image versions. | Image version | Last minor version release | Supported until | Description | | --- | --- | --- | --- | | 1.x.x | Apr 30th, 2025 | Oct 30th, 2025 | SageMaker Distribution major version 1 is built with Python 3.10. | | 2.x.x | Aug 25th, 2025 | Feb 25th, 2026 | SageMaker Distribution major version 2 is built with Python 3.11. | | 3.x.x | Mar 29th, 2026 | Sep 29th, 2026 | SageMaker Distribution major version 3 is built with Python 3.12. | ### CPU image minor versions The following table lists the supported SageMaker Distribution minor image versions for CPUs. | Image version | Amazon ECR image URI | Planned end of support date | Availability on Studio until | Release notes | | --- | --- | --- | --- | --- | | 3.1.x | public.ecr.aws/sagemaker/sagemaker-distribution:3.1-cpu | Nov 19th, 2025 | Nov 19th, 2025 | [Release notes](https://github.com/aws/sagemaker-distribution/tree/main/build_artifacts/v3/v3.1) | | 3.0.x | public.ecr.aws/sagemaker/sagemaker-distribution:3.0-cpu | Jun 30th, 2025 | Sep 29th, 2025 | [Release notes](https://github.com/aws/sagemaker-distribution/tree/main/build_artifacts/v3/v3.0) | | 2.6.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.6-cpu | Jun 30th, 2025 | Oct 28th, 2025 | [Release notes](https://github.com/aws/sagemaker-distribution/tree/main/build_artifacts/v2/v2.6) | ### GPU image minor versions The following table lists the supported SageMaker Distribution minor image versions for GPUs. | Image version | Amazon ECR image URI | Planned end of support date | Availability on Studio until | Release notes for newest patch | | --- | --- | --- | --- | --- | | 3.1.x | public.ecr.aws/sagemaker/sagemaker-distribution:3.1-gpu | Nov 19th, 2025 | Nov 19th, 2025 | [Release notes](https://github.com/aws/sagemaker-distribution/tree/main/build_artifacts/v3/v3.1) | | 3.0.x | public.ecr.aws/sagemaker/sagemaker-distribution:3.0-gpu | Jun 30th, 2025 | Sep 29th, 2025 | [Release notes](https://github.com/aws/sagemaker-distribution/tree/main/build_artifacts/v3/v3.0) | | 2.6.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.6-gpu | Jun 30th, 2025 | Oct 28th, 2025 | [Release notes](https://github.com/aws/sagemaker-distribution/tree/main/build_artifacts/v2/v2.6) | ### Unsupported images The following table lists unsupported SageMaker Distribution image versions. | Image version | Amazon ECR image URI | End of support date | Availability on Studio until | | --- | --- | --- | --- | | 2.4.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.4-cpu public.ecr.aws/sagemaker/sagemaker-distribution:2.4-cpu | Sep 7th, 2025 | Sep 7th, 2025 | | 2.3.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.3-cpu public.ecr.aws/sagemaker/sagemaker-distribution:2.3-cpu | July 27th, 2025 | July 27th, 2025 | | 2.2.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.2-cpu public.ecr.aws/sagemaker/sagemaker-distribution:2.2-gpu | May 15th, 2025 | May 15th, 2025 | | 2.1.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.1-cpu public.ecr.aws/sagemaker/sagemaker-distribution:2.1-gpu | Apr 25th, 2025 | May 12th, 2025 | | 2.0.x | public.ecr.aws/sagemaker/sagemaker-distribution:2.0-cpu public.ecr.aws/sagemaker/sagemaker-distribution:2.0-gpu | Feb 25th, 2025 | Apr 21st, 2025 | | 1.13.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.13-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.13-gpu | May 15th, 2025 | Sep 20th, 2025 | | 1.12.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.12-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.12-gpu | July 23rd, 2025 | July 23rd, 2025 | | 1.11.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.11-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.11-gpu | Apr 1st, 2025 | May 12th, 2025 | | 1.10.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.10-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.10-gpu | Feb 5th, 2025 | Apr 10th, 2025 | | 1.9.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.9-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.9-gpu | Jan 15th, 2025 | Apr 10th, 2025 | | 1.8.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.8-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.8-gpu | Dec 31st, 2024 | Apr 10th, 2025 | | 1.7.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.7-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.7-gpu | Dec 15th, 2024 | Apr 10th, 2025 | | 1.6.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.6-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.6-gpu | Dec 15th, 2024 | Apr 10th, 2025 | | 1.5.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.5-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.5-gpu | Oct 31st, 2024 | Nov 1st, 2024 | | 1.4.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.4-cpu public.ecr.aws/sagemaker/sagemaker-distribution:1.4-gpu | Oct 31st, 2024 | Nov 1st, 2024 | | 1.3.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.3-cpu | June 28th, 2024 | Oct 18th, 2024 | | 1.2.x | public.ecr.aws/sagemaker/sagemaker-distribution:1.2-cpu | June 28th, 2024 | Oct 18th, 2024 | ### Frequently asked questions **What constitutes a major image version release?** Major image versions are released every 6 months. A major image version release for Amazon SageMaker Distribution involves upgrading all core dependencies to the latest compatible versions and may include adding or removing packages. Python framework is only upgraded with new major version releases. For example, with major version 2 release, Python framework was upgraded from 3.10 to 3.11, PyTorch was upgraded from 2.0 to 2.3, TensorFlow was upgraded from 2.14 to 2.17, Autogluon was upgraded from 0.8 to 1.1, and 4 packages were added to the image. **What constitutes a minor image version release?** Minor image versions are released for all supported major versions monthly. A minor image version release for Amazon SageMaker Distribution involves upgrading all core dependencies except Python and CUDA to the latest compatible minor versions within the same major version and may include adding new packages. For example, with a minor version release, langchain might be upgraded from 0.1 to 0.2 and jupyter-ai from 2.18 to 2.20. **What constitutes a patch image version release?** Patch image versions are released as necessary to fix security vulnerabilities. A patch image version release for Amazon SageMaker Distribution involves updating all of its core dependencies to the latest compatible patch versions within the same minor version. SageMaker Distribution does not add or remove any packages during a patch version release. For example, with a patch version release, matplotlib might be upgraded from 3.9.1 to 3.9.2 and boto3 from 1.34.131 to 1.34.162. **Where can I find the packages available in a specific image version?** Each image version has a `release.md` file in the [GitHub repository's](https://github.com/aws/sagemaker-distribution) `build_artifacts` folder, showing all packages and package versions for CPU and GPU images. Separate changelog files for CPU and GPU versions detail package upgrades. Changelogs compare the new image version to the previous. For example, version 1.9.0 compares to the latest patch version of 1.8, version 1.9.1 compares to 1.9.0, and version 2.0.0 compares to the latest patch version of the latest minor version available at the time. **How are images scanned for Common Vulnerabilities and Exposures (CVEs)?** Amazon SageMaker AI leverages [Amazon Elastic Container Registry (Amazon ECR) enhanced scanning](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning-enhanced.html) to automatically detect vulnerabilities and fixes for SageMaker Distribution Images. AWS continuously runs ECR enhanced scanning for the latest patch version of all supported image versions. When vulnerabilities are detected and a fix is available, AWS releases an updated image version to remediate the issue. **Can I still use older images after an image is no longer supported?** Images are available on SageMaker Studio until the designated availability date. Older images remain available in ECR after they reach end of support and are removed from Studio. You can download older image versions from ECR and [create a custom SageMaker image](studio-byoi-create.md). However, we highly recommend upgrading to a supported image version that continuously receives security updates and bug fixes. Customers who build their own custom images are responsible for scanning and patching their images. For more information, see the [AWS Shared Responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/). **Important** SageMaker Distribution v0.x.y is only used in Studio Classic. SageMaker Distribution v1.x.y is only used in JupyterLab. # Amazon SageMaker Studio pricing **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). There is no additional charge for using the Amazon SageMaker Studio UI.  The following do incur costs: + Amazon Elastic Block Store or Amazon Elastic File System volumes that are mounted with your applications. + Any jobs and resources that users launch from Studio applications. + Launching a JupyterLab application, even if no resources or jobs launched in the application. For information about how Amazon SageMaker Studio Classic is billed, see [Amazon SageMaker Studio Classic Pricing](studio-pricing.md). For more information about billing along with pricing examples, see [Amazon SageMaker Pricing](https://aws.amazon.com//sagemaker/pricing/). # Troubleshooting **Important** As of November 30, 2023, the previous Amazon SageMaker Studio experience is now named Amazon SageMaker Studio Classic. The following section is specific to using the updated Studio experience. For information about using the Studio Classic application, see [Amazon SageMaker Studio Classic](studio.md). **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. This section shows how to troubleshoot common problems in Amazon SageMaker Studio. ## Recovery mode Recovery mode allows you to access your Studio application when a configuration issue prevents your normal start up. It provides a simplified environment with essential functionality to help you diagnose and fix the issue. When an application fails to launch, you may see an error message about accessing recovery mode to address one of the following configuration issues. + Corrupted [https://docs.conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html](https://docs.conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html) file. For information on troubleshooting your `.condarc` file, see the [troubleshooting](https://docs.conda.io/projects/conda/en/latest/user-guide/troubleshooting.html) page in the *Conda user guide*. + Insufficient storage volume available. You can increase the Amazon EBS space storage available for the application or enter recovery mode to remove unnecessary data. For information on increasing the Amazon EBS volume size, see [request a quota size](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html) in the *Service Quotas Developer Guide*. In recovery mode: + Your home directory will differ from your normal start up. This directory is temporary and ensures that any corrupted configurations in your standard home directory does not impact your recovery mode operations. You can navigate to your standard home directory by using the command `cd /home/sagemaker-user`. + Standard mode: `/home/sagemaker-user` + Recovery mode: `/tmp/sagemaker-recovery-mode-home` + The conda environment uses a minimal base conda environment with essential packages only. The simplified conda setup helps isolate environment-related issues and provides basic functionality for troubleshooting. You can use the Studio UI or the AWS CLI to access the application in recovery mode. ### Use the Studio UI to access the application in recovery mode The following provides instructions on accessing your application in recovery mode. 1. If you have not already done so, launch the Studio UI by following the instructions in [Launch from the Amazon SageMaker AI console](studio-updated-launch.md#studio-updated-launch-console). 1. In the left navigation menu, under **Applications**, choose the application. 1. Choose the space you are having configuration issues with. The following steps become available to you when you have one one or more of the configuration issues mentioned previously. In this case, you will see a warning banner and **Recovery mode** message. **Note** The warning banner should have a recommended solution for the issue. Take note of it before proceeding. 1. Choose **Run space (Recovery mode)**. 1. To access your application in recovery mode, choose **Open *application* (Recovery mode)**. ### Use the AWS CLI to access the application in recovery mode To access your application in recovery mode, you must append `--recovery-mode` to your [create-app](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-app.html) AWS CLI command. The following provides an example on how to access your application in recovery mode. For the following example, you will need your: + *domain-id* To obtain your domain details, see [View domains](domain-view.md). + *space-name* To obtain the space names associated with your domain, see [Use the AWS CLI to view the SageMaker AI spaces in your domain](sm-console-domain-resources-view.md#sm-console-domain-resources-view-spaces-cli). + *app-name* The name of your application. To view your applications, see [Use the AWS CLI to view the SageMaker AI applications in your domain](sm-console-domain-resources-view.md#sm-console-domain-resources-view-apps-cli). ------ #### [ Access Code Editor application in recovery mode ] ``` aws sagemaker create-app \ --app-name app-name \ --app-type CodeEditor \ --domain-id domain-id \ --space-name space-name \ --recovery-mode ``` ------ #### [ Access JupyterLab application in recovery mode ] ``` aws sagemaker create-app \ --app-name app-name \ --app-type JupyterLab \ --domain-id domain-id \ --space-name space-name \ --recovery-mode ``` ------ ## Cannot delete the Code Editor or JupyterLab application This issue occurs when a user creates an application from Amazon SageMaker Studio, that is only available in Studio, then reverts their default experience to Studio Classic. As a result, the user cannot delete an application for Code Editor, based on Code-OSS, Visual Studio Code - Open Source or JupyterLab, because they can't access the Studio UI. To resolve this issue, notify your administrator so that they can delete the application manually using the AWS Command Line Interface (AWS CLI). ## EC2InsufficientCapacityError This issue occurs when you try to run a space and AWS does not currently have enough available on-demand capacity to fulfill your request. To resolve this issue, complete the following. + Wait a few minutes, then resubmit your request. Capacity can shift frequently. + Run the space with an alternate instance size or type. **Note** Capacity is available in different Availability Zones. To maximize capacity availability for users, we recommend setting up subnets in all Availability Zones. Studio retries all available Availability Zones for the domain. Instance type availability differs between regions. For a list of supported instances types per Region, see [Amazon SageMaker AI pricing](https://aws.amazon.com/sagemaker/pricing/)) The following table lists instance families and their recommended alternatives. | Instance family | CPU Type | vCPUs | Memory (GiB) | GPU type | GPUs | GPU Memory (GiB) | Recommended alternative | | --- | --- | --- | --- | --- | --- | --- | --- | | G4dn | 2nd Generation Intel Xeon Scalable Processors | 4 to 96 | 16 to 384 | NVIDIA T4 Tensor Core | 1 to 8 | 16 per GPU | G6 | | G5 | 2nd generation AMD EPYC processors | 4 to 192 | 16 to 768 | NVIDIA A10G Tensor core | 1 to 8 | 24 per GPU | G6e | | G6 | 3rd generation AMD EPYC processors | 4 to 192 | 16 to 768 | NVIDIA L4 Tensor Core | 1 to 8 | 24 per GPU | G4dn | | G6e | 3rd generation AMD EPYC processors | 4 to 192 | 32 to 1536 | NVIDIA L40S Tensor Core | 1 to 8 | 48 per GPU | G5, P4 | | P3 | Intel Xeon Scalable Processors | 8 to 96 | 61 to 768 | NVIDIA Tesla V100 | 1 to 8 | 16 per GPU (32 per GPU for P3dn) | G6e, P4 | | P4 | 2nd Generation Intel Xeon Scalable processors | 96 | 1152 | NVIDIA A100 Tensor Core | 8 | 320 (640 for P4de) | G6e | | P5 | 3rd Gen AMD EPYC processors | 192 | 2000 | NVIDIA H100 Tensor Core | 8 | 640 | P4de | ## Insufficient limit (quota increase required) This issue occurs when you get the following error message while attempting to run a space. ``` Error when creating application for space: ... : The account-level service limit is X Apps, with current utilization Y Apps and a request delta of 1 Apps. Please use Service Quotas to request an increase for this quota. ``` There is a default limit on the number of instances, for each instance type, that you can run in each AWS Region. This error means that you have reached that limit. To resolve this issue, request an instance limit increase for the AWS Region that you are launching the space in. For more information, see [Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html). ## Failure to load custom image This issue occurs when a SageMaker AI image is deleted before detaching the image from your domain. This can be seen when you view the **Environment** tab for your domain. To resolve this issue, you will need to create a temporary new image with the same name as the deleted one, detach the image, then delete the temporary image. Use the following instructions for a walk through. 1. If you have not already done so, launch the [SageMaker AI console](https://console.aws.amazon.com/sagemaker). 1. In the left navigation menu, under **Admin configurations**, choose **Domains**. 1. Choose your domain. 1. Choose the **Environment** tab. You will see the error message on this page. 1. Copy your image name from the image ARN. 1. In the left navigation menu, under **Admin configurations**, choose **Images**. 1. Choose **Create image**. 1. Follow the steps in the procedure, but ensure that your image name is the same as the image name from above. If you do not have an image in a Amazon ECR directory, see the instructions in [Create a custom image and push to Amazon ECR](studio-updated-byoi-how-to-prepare-image.md). 1. Once you have created your SageMaker AI image, navigate back to your domain **Environment** tab. You will see the image attached to your domain. 1. Select the image and choose **Detach**. 1. Follow the instructions to detach and delete the temporary SageMaker AI image. # Migration from Amazon SageMaker Studio Classic **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. When you open Amazon SageMaker Studio, the web-based UI is based on the chosen default experience. Amazon SageMaker AI currently supports two different default experiences: the Amazon SageMaker Studio experience and the Amazon SageMaker Studio Classic experience. To access the latest Amazon SageMaker Studio features, you must migrate existing domains from the Amazon SageMaker Studio Classic experience. When you migrate your default experience from Studio Classic to Studio, you don't lose any features, and can still access the Studio Classic IDE within Studio. For information about the added benefits of the Studio experience, see [Amazon SageMaker Studio](studio-updated.md). **Note** For existing customers that created their accounts before November 30, 2023, Studio Classic may be the default experience. You can enable Studio as your default experience using the AWS Command Line Interface (AWS CLI) or the Amazon SageMaker AI console. For more information about Studio Classic, see [Amazon SageMaker Studio Classic](studio.md). For customers that created their accounts after November 30, 2023, we recommend using Studio as the default experience because it contains various integrated development environments (IDEs), including the Studio Classic IDE, and other new features. JupyterLab 3 reached its end of maintenance date on May 15, 2024. After December 31, 2024, you can only create new Studio Classic notebooks on JupyterLab 3 for a limited period. However after December 31, 2024, SageMaker AI will no longer provide fixes for critical issues on Studio Classic notebooks on JupyterLab 3. We recommend that you migrate your workloads to the new Studio experience, which supports JupyterLab 4. + If Studio is your default experience, the UI is similar to the images found in [Amazon SageMaker Studio UI overview](studio-updated-ui.md). + If Studio Classic is your default experience, the UI is similar to the images found in [Amazon SageMaker Studio Classic UI Overview](studio-ui.md). To migrate, you must update an existing domain. Migrating an existing domain from Studio Classic to Studio requires three distinct phases: 1. ** Migrate the UI from Studio Classic to Studio**: One time, low lift task that requires creating a test domain to ensure Studio is compliant with your organization's network configurations before migrating the existing domain's UI from Studio Classic to Studio. 1. **(Optional) Migrate custom images and lifecycle configuration scripts**: Medium lift task for migrating your custom images and LCC scripts from Studio Classic to Studio. 1. **(Optional) Migrate data from Studio Classic to Studio**: Heavy lift task that requires using AWS DataSync to migrate data from the Studio Classic Amazon Elastic File System volume to either a target Amazon EFS or Amazon Elastic Block Store volume. 1. **(Optional) Migrate data flows from Data Wrangler in Studio Classic**: One time, low lift task for migrating your data flows from Data Wrangler in Studio Classic to Studio, which you can then access in the latest version of Studio through SageMaker Canvas. For more information, see [Migrate data flows from Data Wrangler](studio-updated-migrate-data.md#studio-updated-migrate-flows). The following topics show how to complete these phases to migrate an existing domain from Studio Classic to Studio. ## Automatic migration Between July 2024 and August 2024, we are automatically upgrading the default landing experience for users to the new Studio experience. This only changes the default landing UI to the updated Studio UI. The Studio Classic application is still accessible from the new Studio UI. To ensure that migration works successfully for your users, see [Migrate the UI from Studio Classic to Studio](studio-updated-migrate-ui.md). In particular, ensure the following: + the domain's execution role has the right permissions + the default landing experience is set to Studio + the domain's Amazon VPC, if applicable, is configured to Studio using the Studio VPC endpoint However, if you need to continue having Studio Classic as your default UI for a limited time, set the landing experience to Studio Classic explicitly. For more information, see [Set Studio Classic as the default experience](studio-updated-migrate-ui.md#studio-updated-migrate-revert). **Topics** + [ ## Automatic migration ](#studio-updated-migrate-auto) + [ # Complete prerequisites to migrate the Studio experience ](studio-updated-migrate-prereq.md) + [ # Migrate the UI from Studio Classic to Studio ](studio-updated-migrate-ui.md) + [ # (Optional) Migrate custom images and lifecycle configurations ](studio-updated-migrate-lcc.md) + [ # (Optional) Migrate data from Studio Classic to Studio ](studio-updated-migrate-data.md) # Complete prerequisites to migrate the Studio experience Migration of the default experience from Studio Classic to Studio is managed by the administrator of the existing domain. If you do not have permissions to set Studio as the default experience for the existing domain, contact your administrator. To migrate your default experience, you must have administrator permissions or at least have permissions to update the existing domain, AWS Identity and Access Management (IAM), and Amazon Simple Storage Service (Amazon S3). Complete the following prerequisites before migrating an existing domain from Studio Classic to Studio. + The AWS Identity and Access Management role used to complete migration must have a policy attached with at least the following permissions. For information about creating an IAM policy, see [Creating IAM policies](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_create.html). **Note** The release of Studio includes updates to the AWS managed policies. For more information, see [SageMaker AI Updates to AWS Managed Policies](security-iam-awsmanpol.md#security-iam-awsmanpol-updates). + Phase 1 required permissions: + `iam:CreateServiceLinkedRole` + `iam:PassRole` + `sagemaker:DescribeDomain` + `sagemaker:UpdateDomain` + `sagemaker:CreateDomain` + `sagemaker:CreateUserProfile` + `sagemaker:ListApps` + `sagemaker:AddTags` + `sagemaker:DeleteApp` + `sagemaker:DeleteSpace` + `sagemaker:UpdateSpace` + `sagemaker:DeleteUserProfile` + `sagemaker:DeleteDomain` + `s3:PutBucketCORS` + Phase 2 required permissions (Optional, only if using lifecycle configuration scripts): No additional permissions needed. If the existing domain has lifecycle configurations and custom images, the admin will already have the required permissions. + Phase 3 using custom Amazon Elastic File System required permissions (Optional, only if transfering data): + `efs:CreateFileSystem` + `efs:CreateMountTarget` + `efs:DescribeFileSystems` + `efs:DescribeMountTargets` + `efs:DescribeMountTargetSecurityGroups` + `efs:ModifyMountTargetSecurityGroups` + `ec2:DescribeSubnets` + `ec2:DescribeSecurityGroups` + `ec2:DescribeNetworkInterfaceAttribute` + `ec2:DescribeNetworkInterfaces` + `ec2:AuthorizeSecurityGroupEgress` + `ec2:AuthorizeSecurityGroupIngress` + `ec2:CreateNetworkInterface` + `ec2:CreateNetworkInterfacePermission` + `ec2:RevokeSecurityGroupIngress` + `ec2:RevokeSecurityGroupEgress` + `ec2:DeleteSecurityGroup` + `datasync:CreateLocationEfs` + `datasync:CreateTask` + `datasync:StartTaskExecution` + `datasync:DeleteTask` + `datasync:DeleteLocation` + `sagemaker:ListUserProfiles` + `sagemaker:DescribeUserProfile` + `sagemaker:UpdateDomain` + `sagemaker:UpdateUserProfile` + Phase 3 using Amazon Simple Storage Service required permissions (Optional, only if transfering data): + `iam:CreateRole` + `iam:GetRole` + `iam:AttachRolePolicy` + `iam:DetachRolePolicy` + `iam:DeleteRole` + `efs:DescribeFileSystems` + `efs:DescribeMountTargets` + `efs:DescribeMountTargetSecurityGroups` + `ec2:DescribeSubnets` + `ec2:CreateSecurityGroup` + `ec2:DescribeSecurityGroups` + `ec2:DescribeNetworkInterfaces` + `ec2:CreateNetworkInterface` + `ec2:CreateNetworkInterfacePermission` + `ec2:DetachNetworkInterfaces` + `ec2:DeleteNetworkInterface` + `ec2:DeleteNetworkInterfacePermission` + `ec2:CreateTags` + `ec2:AuthorizeSecurityGroupEgress` + `ec2:AuthorizeSecurityGroupIngress` + `ec2:RevokeSecurityGroupIngress` + `ec2:RevokeSecurityGroupEgress` + `ec2:DeleteSecurityGroup` + `datasync:CreateLocationEfs` + `datasync:CreateLocationS3` + `datasync:CreateTask` + `datasync:StartTaskExecution` + `datasync:DescribeTaskExecution` + `datasync:DeleteTask` + `datasync:DeleteLocation` + `sagemaker:CreateStudioLifecycleConfig` + `sagemaker:UpdateDomain` + `s3:ListBucket` + `s3:GetObject` + Access to AWS services from a terminal environment on either: + Your local machine using the AWS CLI version `2.13+`. Use the following command to verify the AWS CLI version. ``` aws --version ``` + AWS CloudShell. For more information, see [What is AWS CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) + From your local machine or AWS CloudShell, run the following command and provide your AWS credentials. For information about AWS credentials, see [Understanding and getting your AWS credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html). ``` aws configure ``` + Verify that the lightweight JSON processor, jq, is installed in the terminal environment. jq is required to parse AWS CLI responses. ``` jq --version ``` If jq is not installed, install it using one of the following commands: + ``` sudo apt-get install -y jq ``` + ``` sudo yum install -y jq ``` # Migrate the UI from Studio Classic to Studio The first phase for migrating an existing domain involves migrating the UI from Amazon SageMaker Studio Classic to Amazon SageMaker Studio. This phase does not include the migration of data. Users can continue working with their data the same way as they were before migration. For information about migrating data, see [(Optional) Migrate data from Studio Classic to Studio](studio-updated-migrate-data.md). Phase 1 consists of the following steps: 1. Update application creation permissions for new applications available in Studio. 1. Update the VPC configuration for the domain. 1. Upgrade the domain to use the Studio UI. ## Prerequisites Before running these steps, complete the prerequisites in [Complete prerequisites to migrate the Studio experience](studio-updated-migrate-prereq.md). ## Step 1: Update application creation permissions Before migrating the domain, update the domain's execution role to grant users permissions to create applications. 1. Create an AWS Identity and Access Management policy with one of the following contents by following the steps in [Creating IAM policies](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_create.html): + Use the following policy to grant permissions for all application types and spaces. **Note** If the domain uses the `SageMakerFullAccess` policy, you do not need to perform this action. `SageMakerFullAccess` grants permissions to create all applications. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "SMStudioUserProfileAppPermissionsCreateAndDelete", "Effect": "Allow", "Action": [ "sagemaker:CreateApp", "sagemaker:DeleteApp" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:app/*", "Condition": { "Null": { "sagemaker:OwnerUserProfileArn": "true" } } }, { "Sid": "SMStudioCreatePresignedDomainUrlForUserProfile", "Effect": "Allow", "Action": [ "sagemaker:CreatePresignedDomainUrl" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:user-profile/${sagemaker:DomainId}/${sagemaker:UserProfileName}" }, { "Sid": "SMStudioAppPermissionsListAndDescribe", "Effect": "Allow", "Action": [ "sagemaker:ListApps", "sagemaker:ListDomains", "sagemaker:ListUserProfiles", "sagemaker:ListSpaces", "sagemaker:DescribeApp", "sagemaker:DescribeDomain", "sagemaker:DescribeUserProfile", "sagemaker:DescribeSpace" ], "Resource": "*" }, { "Sid": "SMStudioAppPermissionsTagOnCreate", "Effect": "Allow", "Action": [ "sagemaker:AddTags" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:*/*", "Condition": { "Null": { "sagemaker:TaggingAction": "false" } } }, { "Sid": "SMStudioRestrictSharedSpacesWithoutOwners", "Effect": "Allow", "Action": [ "sagemaker:CreateSpace", "sagemaker:UpdateSpace", "sagemaker:DeleteSpace" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:space/${sagemaker:DomainId}/*", "Condition": { "Null": { "sagemaker:OwnerUserProfileArn": "true" } } }, { "Sid": "SMStudioRestrictSpacesToOwnerUserProfile", "Effect": "Allow", "Action": [ "sagemaker:CreateSpace", "sagemaker:UpdateSpace", "sagemaker:DeleteSpace" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:space/${sagemaker:DomainId}/*", "Condition": { "ArnLike": { "sagemaker:OwnerUserProfileArn": "arn:aws:sagemaker:us-east-1:111122223333:user-profile/${sagemaker:DomainId}/${sagemaker:UserProfileName}" }, "StringEquals": { "sagemaker:SpaceSharingType": [ "Private", "Shared" ] } } }, { "Sid": "SMStudioRestrictCreatePrivateSpaceAppsToOwnerUserProfile", "Effect": "Allow", "Action": [ "sagemaker:CreateApp", "sagemaker:DeleteApp" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:app/${sagemaker:DomainId}/*", "Condition": { "ArnLike": { "sagemaker:OwnerUserProfileArn": "arn:aws:sagemaker:us-east-1:111122223333:user-profile/${sagemaker:DomainId}/${sagemaker:UserProfileName}" }, "StringEquals": { "sagemaker:SpaceSharingType": [ "Private" ] } } }, { "Sid": "AllowAppActionsForSharedSpaces", "Effect": "Allow", "Action": [ "sagemaker:CreateApp", "sagemaker:DeleteApp" ], "Resource": "arn:aws:sagemaker:*:*:app/${sagemaker:DomainId}/*/*/*", "Condition": { "StringEquals": { "sagemaker:SpaceSharingType": [ "Shared" ] } } } ] } ``` ------ + Because Studio shows an expanded set of applications, users may have access to applications that weren't displayed before. Administrators can limit access to these default applications by creating an AWS Identity and Access Management (IAM) policy that grants denies permissions for some applications to specific users. **Note** Application type can be either `jupyterlab` or `codeeditor`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "DenySageMakerCreateAppForSpecificAppTypes", "Effect": "Deny", "Action": "sagemaker:CreateApp", "Resource": "arn:aws:sagemaker:us-east-1:111122223333:app/domain-id/*/app-type/*" } ] } ``` ------ 1. Attach the policy to the execution role of the domain. For instructions, follow the steps in [Adding IAM identity permissions (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console). ## Step 2: Update VPC configuration If you use your domain in `VPC-Only` mode, ensure your VPC configuration meets the requirements for using Studio in `VPC-Only` mode. For more information, see [Connect Amazon SageMaker Studio in a VPC to External Resources](studio-updated-and-internet-access.md). ## Step 3: Upgrade to the Studio UI Before you migrate your existing domain from Studio Classic to Studio, we recommend creating a test domain using Studio with the same configurations as your existing domain. ### (Optional) Create a test domain Use this test domain to interact with Studio, test out networking configurations, and launch applications, before migrating the existing domain. 1. Get the domain ID of your existing domain. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the existing domain. 1. On the **Domain details** page, choose the **Domain settings** tab. 1. Copy the **Domain ID**. 1. Add the domain ID of your existing domain. ``` export REF_DOMAIN_ID="domain-id" export SM_REGION="region" ``` 1. Use `describe-domain` to get important information about the existing domain. ``` export REF_EXECROLE=$(aws sagemaker describe-domain --region=$SM_REGION --domain-id=$REF_DOMAIN_ID | jq -r '.DefaultUserSettings.ExecutionRole') export REF_VPC=$(aws sagemaker describe-domain --region=$SM_REGION --domain-id=$REF_DOMAIN_ID | jq -r '.VpcId') export REF_SIDS=$(aws sagemaker describe-domain --region=$SM_REGION --domain-id=$REF_DOMAIN_ID | jq -r '.SubnetIds | join(",")') export REF_SGS=$(aws sagemaker describe-domain --region=$SM_REGION --domain-id=$REF_DOMAIN_ID | jq -r '.DefaultUserSettings.SecurityGroups | join(",")') export AUTHMODE=$(aws sagemaker describe-domain --region=$SM_REGION --domain-id=$REF_DOMAIN_ID | jq -r '.AuthMode') ``` 1. Validate the parameters. ``` echo "Execution Role: $REF_EXECROLE || VPCID: $REF_VPC || SubnetIDs: $REF_SIDS || Security GroupIDs: $REF_SGS || AuthMode: $AUTHMODE" ``` 1. Create a test domain using the configurations from the existing domain. ``` IFS=',' read -r -a subnet_ids <<< "$REF_SIDS" IFS=',' read -r -a security_groups <<< "$REF_SGS" security_groups_json=$(printf '%s\n' "${security_groups[@]}" | jq -R . | jq -s .) aws sagemaker create-domain \ --domain-name "TestV2Config" \ --vpc-id $REF_VPC \ --auth-mode $AUTHMODE \ --subnet-ids "${subnet_ids[@]}" \ --app-network-access-type VpcOnly \ --default-user-settings " { \"ExecutionRole\": \"$REF_EXECROLE\", \"StudioWebPortal\": \"ENABLED\", \"DefaultLandingUri\": \"studio::\", \"SecurityGroups\": $security_groups_json } " ``` 1. After the test domain is `In Service`, use the test domain's ID to create a user profile. This user profile is used to launch and test applications. ``` aws sagemaker create-user-profile \ --region="$SM_REGION" --domain-id=test-domain-id \ --user-profile-name test-network-user ``` #### Test Studio functionality Launch the test domain using the `test-network-user` user profile. We suggest that you thoroughly test the Studio UI and create applications to test Studio functionality in `VPCOnly` mode. Test the following workflows: + Create a new JupyterLab Space, test environment and connectivity. + Create a new Code Editor, based on Code-OSS, Visual Studio Code - Open Source Space, test environment and connectivity. + Launch a new Studio Classic App, test environment and connectivity. + Test Amazon Simple Storage Service connectivity with test read and write actions. If these tests are successful, then upgrade the existing domain. If you encounter any failures, we recommended fixing your environment and connectivity issues before updating the existing domain. #### Clean up test domain resources After you have migrated the existing domain, clean up test domain resources. 1. Add the test domain's ID. ``` export TEST_DOMAIN="test-domain-id" export SM_REGION="region" ``` 1. List all applications in the domain that are in a running state. ``` active_apps_json=$(aws sagemaker list-apps --region=$SM_REGION --domain-id=$TEST_DOMAIN) echo $active_apps_json ``` 1. Parse the JSON list of running applications and delete them. If users attempted to create an application that they do not have permissions for, there may be spaces that are not captured in the following script. You must manually delete these spaces. ``` echo "$active_apps_json" | jq -c '.Apps[]' | while read -r app; do if echo "$app" | jq -e '. | has("SpaceName")' > /dev/null; then app_type=$(echo "$app" | jq -r '.AppType') app_name=$(echo "$app" | jq -r '.AppName') domain_id=$(echo "$app" | jq -r '.DomainId') space_name=$(echo "$app" | jq -r '.SpaceName') echo "Deleting App - AppType: $app_type || AppName: $app_name || DomainId: $domain_id || SpaceName: $space_name" aws sagemaker delete-app --region=$SM_REGION --domain-id=$domain_id \ --app-type $app_type --app-name $app_name --space-name $space_name echo "Deleting Space - AppType: $app_type || AppName: $app_name || DomainId: $domain_id || SpaceName: $space_name" aws sagemaker delete-space --region=$SM_REGION --domain-id=$domain_id \ --space-name $space_name else app_type=$(echo "$app" | jq -r '.AppType') app_name=$(echo "$app" | jq -r '.AppName') domain_id=$(echo "$app" | jq -r '.DomainId') user_profile_name=$(echo "$app" | jq -r '.UserProfileName') echo "Deleting Studio Classic - AppType: $app_type || AppName: $app_name || DomainId: $domain_id || UserProfileName: $user_profile_name" aws sagemaker delete-app --region=$SM_REGION --domain-id=$domain_id \ --app-type $app_type --app-name $app_name --user-profile-name $user_profile_name fi done ``` 1. Delete the test user profile. ``` aws sagemaker delete-user-profile \ --region=$SM_REGION --domain-id=$TEST_DOMAIN \ --user-profile-name "test-network-user" ``` 1. Delete the test domain. ``` aws sagemaker delete-domain \ --region=$SM_REGION --domain-id=$TEST_DOMAIN ``` After you have tested Studio functionality with the configurations in your test domain, migrate the existing domain. When Studio is the default experience for a domain, Studio is the default experience for all users in the domain. However, the user settings takes precedence over the domain settings. Therefore, if a user has their default experience set to Studio Classic in their user settings, then that user will have Studio Classic as their default experience. You can migrate the existing domain by updating it from the SageMaker AI console, the AWS CLI, or AWS CloudFormation. Choose one of the following tabs to view the relevant instructions. ### Set Studio as the default experience for the existing domain using the SageMaker AI console You can set Studio as the default experience for the existing domain by using the SageMaker AI console. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane expand **Admin configurations** and choose **Domains**. 1. Choose the existing domain that you want to enable Studio as the default experience for. 1. On the **Domain details** page expand **Enable the new Studio**. 1. (Optional) To view the details about the steps involved in enabling Studio as your default experience, choose **View details**. The page shows the following. + In the **SageMaker Studio Overview** section you can view the applications that are included or available in the Studio web-based interface. + In the **Enablement process** section you can view descriptions of the workflow tasks to enable Studio. **Note** You will need to migrate your data manually. For instructions about migrating your data, see [(Optional) Migrate data from Studio Classic to Studio](studio-updated-migrate-data.md). + In the **Revert to Studio Classic experience** section you can view how to revert back to Studio Classic after enabling Studio as your default experience. 1. To begin the process to enable Studio as your default experience, choose **Enable the new Studio**. 1. In the **Specify and configure role** section, you can view the default applications that are automatically included in Studio. To prevent users from running these applications, choose the AWS Identity and Access Management (IAM) Role that has an IAM policy that denies access. For information about how to create a policy to limit access, see [Step 1: Update application creation permissions](#studio-updated-migrate-limit-apps). 1. In the **Choose default S3 bucket to attach CORS policy** section, you can give Studio access to Amazon S3 buckets. The default Amazon S3 bucket, in this case, is the default Amazon S3 bucket for your Studio Classic. In this step you can do the following: + Verify the domain’s default Amazon S3 bucket to attach the CORS policy to. If your domain does not have a default Amazon S3 bucket, SageMaker AI creates an Amazon S3 bucket with the correct CORS policy attached. + You can include 10 additional Amazon S3 buckets to attach the CORS policy to. If you wish to include more than 10 buckets, you can add them manually. For more information about manually attaching the CORS policy to your Amazon S3 buckets, see [(Optional) Update your CORS policy to access Amazon S3 buckets](#studio-updated-migrate-cors). To proceed, select the check box next to **Do you agree to overriding any existing CORS policy on the chosen Amazon S3 buckets?**. 1. The **Migrate data** section contains information about the different data storage volumes for Studio Classic and Studio. Your data will not be migrated automatically through this process. For instructions about migrating your data, lifecycle configurations, and JupyterLab extensions, see [(Optional) Migrate data from Studio Classic to Studio](studio-updated-migrate-data.md). 1. Once you have completed the tasks on the page and verified your configuration, choose **Enable the new Studio**. ### Set Studio as the default experience for the existing domain using the AWS CLI To set Studio as the default experience for the existing domain using the AWS CLI, use the [update-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html) call. You must set `ENABLED` as the value for `StudioWebPortal`, and set `studio::` as the value for `DefaultLandingUri` as part of the `default-user-settings` parameter.  `StudioWebPortal` indicates if the Studio experience is the default experience and `DefaultLandingUri` indicates the default experience that the user is directed to when accessing the domain. In this example, setting these values on a domain level (in `default-user-settings`) makes Studio the default experience for users within the domain. If a user within the domain has their `StudioWebPortal` set to `DISABLED` and `DefaultLandingUri` set to `app:JupyterServer:` on a user level (in `UserSettings`), this takes precedence over the domain settings. In other words, that user will have Studio Classic as their default experience, regardless of the domain settings. The following code example shows how to set Studio as the default experience for users within the domain: ``` aws sagemaker update-domain \ --domain-id existing-domain-id \ --region AWS Region \ --default-user-settings ' { "StudioWebPortal": "ENABLED", "DefaultLandingUri": "studio::" } ' ``` + To obtain your `existing-domain-id`, use the following instructions: **To get `existing-domain-id`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the existing domain. 1. On the **Domain details** page, choose the **Domain settings** tab. 1. Copy the **Domain ID**. + To ensure you are using the correct AWS Region for your domain, use the following instructions: **To get `AWS Region`** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the existing domain. 1. On the **Domain details** page, verify that this is the existing domain. 1. Expand the AWS Region dropdown list from the top right of the SageMaker AI console, and use the corresponding AWS Region ID to the right of your AWS Region name. For example, `us-west-1`. After you migrate your default experience to Studio, you can give Studio access to Amazon S3 buckets. For example, you can include access to your Studio Classic default Amazon S3 bucket and additional Amazon S3 buckets. To do so, you must manually attach a [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (CORS) configuration to the Amazon S3 buckets. For more information about how to manually attach the CORS policy to your Amazon S3 buckets, see [(Optional) Update your CORS policy to access Amazon S3 buckets](#studio-updated-migrate-cors). Similarly, you can set Studio as the default experience when you create a domain from the AWS CLI using the [create-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/create-domain.html) call.  ### Set Studio as the default experience for the existing domain using the AWS CloudFormation You can set the default experience when creating a domain using the AWS CloudFormation. For an CloudFormation migration template, see [SageMaker Studio Administrator IaC Templates](https://github.com/aws-samples/sagemaker-studio-admin-iac-templates/tree/main?tab=readme-ov-file#phase-1-migration). For more information about creating a domain using CloudFormation, see [Creating Amazon SageMaker AI domain using CloudFormation](https://github.com/aws-samples/cloudformation-studio-domain?tab=readme-ov-file#creating-sagemaker-studio-domains-using-cloudformation). For information about the domain resource supported by AWS CloudFormation, see [AWS::SageMaker AI::Domain](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-resource-sagemaker-domain.html#cfn-sagemaker-domain-defaultusersettings). After you migrate your default experience to Studio, you can give Studio access to Amazon S3 buckets. For example, you can include access to your Studio Classic default Amazon S3 bucket and additional Amazon S3 buckets. To do so, you must manually attach a [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (CORS) configuration to the Amazon S3 buckets. For information about how to manually attach the CORS policy to your Amazon S3 buckets, see [(Optional) Update your CORS policy to access Amazon S3 buckets](#studio-updated-migrate-cors). ### (Optional) Update your CORS policy to access Amazon S3 buckets In Studio Classic, users can create, list, and upload files to Amazon Simple Storage Service (Amazon S3) buckets. To support the same experience in Studio, administrators must attach a [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (CORS) configuration to the Amazon S3 buckets. This is required because Studio makes Amazon S3 calls from the internet browser. The browser invokes CORS on behalf of users. As a result, all of the requests to Amazon S3 buckets fail unless the CORS policy is attached to the Amazon S3 buckets. You may need to manually attach the CORS policy to Amazon S3 buckets for the following reasons. + If there is already an existing Amazon S3 default bucket that doesn’t have the correct CORS policy attached when you migrate the existing domain's default experience to Studio. + If you are using the AWS CLI to migrate the existing domain's default experience to Studio. For information about using the AWS CLI to migrate, see [Set Studio as the default experience for the existing domain using the AWS CLI](#studio-updated-migrate-set-studio-updated-cli). + If you want to attach the CORS policy to additional Amazon S3 buckets. **Note** If you plan to use the SageMaker AI console to enable Studio as your default experience, the Amazon S3 buckets that you attach the CORS policy to will have their existing CORS policies overridden during the migration. For this reason, you can ignore the following manual instructions. However, if you have already used the SageMaker AI console to migrate and want to include more Amazon S3 buckets to attach the CORS policy to, then continue with the following manual instructions. The following procedure shows how to manually add a CORS configuration to an Amazon S3 bucket. **To add a CORS configuration to an Amazon S3 bucket** 1. Verify that there is an Amazon S3 bucket in the same AWS Region as the existing domain with the following name. For instructions, see [Viewing the properties for an Amazon S3 bucket](https://docs.aws.amazon.com//AmazonS3/latest/userguide/view-bucket-properties.html). ``` sagemaker-region-account-id ``` 1. Add a CORS configuration with the following content to the default Amazon S3 bucket. For instructions, see [Configuring cross-origin resource sharing (CORS)](https://docs.aws.amazon.com//AmazonS3/latest/userguide/enabling-cors-examples.html). ``` [ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "POST", "PUT", "GET", "HEAD", "DELETE" ], "AllowedOrigins": [ "https://*.sagemaker.aws" ], "ExposeHeaders": [ "ETag", "x-amz-delete-marker", "x-amz-id-2", "x-amz-request-id", "x-amz-server-side-encryption", "x-amz-version-id" ] } ] ``` ### (Optional) Migrate from Data Wrangler in Studio Classic to SageMaker Canvas Amazon SageMaker Data Wrangler exists as its own feature in the Studio Classic experience. When you enable Studio as your default experience, use the [Amazon SageMaker Canvas](https://docs.aws.amazon.com/sagemaker/latest/dg/canvas.html) application to access Data Wrangler functionality. SageMaker Canvas is an application in which you can train and deploy machine learning models without writing any code, and Canvas provides data preparation features powered by Data Wrangler. The new Studio experience doesn’t support the classic Data Wrangler UI, and you must create a Canvas application if you want to continue using Data Wrangler. However, you must have the necessary permissions to create and use Canvas applications. Complete the following steps to attach the necessary permissions policies to your SageMaker AI domain's or user’s AWS IAM role. **To grant permissions for Data Wrangler functionality inside Canvas** 1. Attach the AWS managed policy [AmazonSageMakerFullAccess](https://docs.aws.amazon.com/sagemaker/latest/dg/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonSageMakerFullAccess) to your user’s IAM role. For a procedure that shows you how to attach IAM policies to a role, see [Adding IAM identity permissions (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console) in the *AWS IAM User Guide.* If this permissions policy is too permissive for your use case, you can create scoped-down policies that include at least the following permissions: ``` { "Sid": "AllowStudioActions", "Effect": "Allow", "Action": [ "sagemaker:CreatePresignedDomainUrl", "sagemaker:DescribeDomain", "sagemaker:ListDomains", "sagemaker:DescribeUserProfile", "sagemaker:ListUserProfiles", "sagemaker:DescribeSpace", "sagemaker:ListSpaces", "sagemaker:DescribeApp", "sagemaker:ListApps" ], "Resource": "*" }, { "Sid": "AllowAppActionsForUserProfile", "Effect": "Allow", "Action": [ "sagemaker:CreateApp", "sagemaker:DeleteApp" ], "Resource": "arn:aws:sagemaker:region:account-id:app/domain-id/user-profile-name/canvas/*", "Condition": { "Null": { "sagemaker:OwnerUserProfileArn": "true" } } } ``` 1. Attach the AWS managed policy [AmazonSageMakerCanvasDataPrepFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerCanvasDataPrepFullAccess.html) to your user’s IAM role. After attaching the necessary permissions, you can create a Canvas application and log in. For more information, see [Getting started with using Amazon SageMaker Canvas](canvas-getting-started.md). When you’ve logged into Canvas, you can directly access Data Wrangler and begin creating data flows. For more information, see [Data preparation](canvas-data-prep.md) in the Canvas documentation. ### (Optional) Migrate from Autopilot in Studio Classic to SageMaker Canvas [Amazon SageMaker Autopilot](https://docs.aws.amazon.com/sagemaker/AWSIronmanApiDoc/integ/npepin-studio-migration-autopilot-to-canvas/latest/dg/autopilot-automate-model-development.html) exists as its own feature in the Studio Classic experience. When you migrate to using the updated Studio experience, use the [Amazon SageMaker Canvas](https://docs.aws.amazon.com/sagemaker/latest/dg/canvas.html) application to continue using the same automated machine learning (AutoML) capabilities via a user interface (UI). SageMaker Canvas is an application in which you can train and deploy machine learning models without writing any code, and Canvas provides a UI to run your AutoML tasks. The new Studio experience doesn’t support the classic Autopilot UI. You must create a Canvas application if you want to continue using Autopilot's AutoML features via a UI. However, you must have the necessary permissions to create and use Canvas applications. + If you are accessing SageMaker Canvas from Studio, add those permissions to the execution role of your SageMaker AI domain or user profile. + If you are accessing SageMaker Canvas from the Console, add those permissions to your user’s AWS IAM role. + If you are accessing SageMaker Canvas via a [presigned URL](https://docs.aws.amazon.com/sagemaker/latest/dg/setting-up-canvas-sso.html#canvas-optional-access), add those permissions to the IAM role that you're using for Okta SSO access. To enable AutoML capabilities in Canvas, add the following policies to your execution role or IAM user role. + AWS managed policy: [`CanvasFullAccess`.](https://docs.aws.amazon.com/sagemaker/latest/dg/security-iam-awsmanpol-canvas.html#security-iam-awsmanpol-AmazonSageMakerCanvasFullAccess) + Inline policy: ``` { "Sid": "AllowAppActionsForUserProfile", "Effect": "Allow", "Action": [ "sagemaker:CreateApp", "sagemaker:DeleteApp" ], "Resource": "arn:aws:sagemaker:region:account-id:app/domain-id/user-profile-name/canvas/*", "Condition": { "Null": { "sagemaker:OwnerUserProfileArn": "true" } } } ``` **To attach IAM policies to an execution role** 1. **Find the execution role attached to your SageMaker AI user profile** 1. In the SageMaker AI console [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/), navigate to **Domains**, then choose your SageMaker AI domain. 1. The execution role ARN is listed under *Execution role* on the **User Details** page of your user profile. Make note of the execution role name in the ARN. 1. In the IAM console [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/), choose **Roles**. 1. Search for your role by name in the search field. 1. Select the role. 1. Add policies to the role 1. In the IAM console [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/), choose **Roles**. 1. Search for your role by name in the search field. 1. Select the role. 1. In the **Permissions** tab, navigate to the dropdown menu **Add permissions**. 1. + For managed policies: Select **Attach policies**, search for the name of the manage policy you want to attach. Select the policy then choose **Add permissions**. + For inline policies: Select **Create inline policy**, paste your policy in the JSON tab, choose next, name your policy, and choose **Create**. For a procedure that shows you how to attach IAM policies to a role, see [Adding IAM identity permissions (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console) in the *AWS IAM User Guide.* After attaching the necessary permissions, you can create a Canvas application and log in. For more information, see [Getting started with using Amazon SageMaker Canvas](canvas-getting-started.md). ## Set Studio Classic as the default experience Administrators can revert to Studio Classic as the default experience for an existing domain. This can be done through the AWS CLI. **Note** When Studio Classic is set as the default experience on a domain level, Studio Classic is the default experience for all users in the domain. However, settings on a user level takes precedence over the domain level settings. So if a user has their default experience set to Studio, then that user will have Studio as their default experience. To revert to Studio Classic as the default experience for the existing domain using the AWS CLI, use the [update-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html) call. As part of the `default-user-settings` field, you must set: + `StudioWebPortal` value to `DISABLED`. + `DefaultLandingUri` value to `app:JupyterServer:` `StudioWebPortal` indicates if the Studio experience is the default experience and `DefaultLandingUri` indicates the default experience that the user is directed to when accessing the domain. In this example, setting these values on a domain level (in `default-user-settings`) makes Studio Classic the default experience for users within the domain. If a user within the domain has their `StudioWebPortal` set to `ENABLED` and `DefaultLandingUri` set to `studio::` on a user level (in `UserSettings`), this takes precedence over the domain level settings. In other words, that user will have Studio as their default experience, regardless of the domain level settings. The following code example shows how to set Studio Classic as the default experience for users within the domain: ``` aws sagemaker update-domain \ --domain-id existing-domain-id \ --region AWS Region \ --default-user-settings ' { "StudioWebPortal": "DISABLED", "DefaultLandingUri": "app:JupyterServer:" } ' ``` Use the following instructions to obtain your `existing-domain-id`. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the existing domain. 1. On the **Domain details** page, choose the **Domain settings** tab. 1. Copy the **Domain ID**. To obtain your `AWS Region`, use the following instructions to ensure you are using the correct AWS Region for your domain. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation pane, expand **Admin configurations** and choose **Domains**. 1. Choose the existing domain. 1. On the **Domain details** page, verify that this is the existing domain. 1. Expand the AWS Region dropdown list from the top right of the SageMaker AI console, and use the corresponding AWS Region ID to the right of your AWS Region name. For example, `us-west-1`. # (Optional) Migrate custom images and lifecycle configurations You must update your custom images and lifecycle configuration (LCC) scripts to work with the simplified local run model in Amazon SageMaker Studio. If you have not created custom images or lifecycle configurations in your domain, skip this phase. Amazon SageMaker Studio Classic operates in a split environment with: + A `JupyterServer` application running the Jupyter Server. + Studio Classic notebooks running on one or more `KernelGateway` applications. Studio has shifted away from a split environment. Studio runs the JupyterLab and Code Editor, based on Code-OSS, Visual Studio Code - Open Source applications in a local runtime model. For more information about the change in architecture, see [Boost productivity on Amazon SageMaker Studio](https://aws.amazon.com/blogs//machine-learning/boost-productivity-on-amazon-sagemaker-studio-introducing-jupyterlab-spaces-and-generative-ai-tools/). ## Migrate custom images Your existing Studio Classic custom images may not work in Studio. We recommend creating a new custom image that satisfies the requirements for use in Studio. The release of Studio simplifies the process to build custom images by providing [SageMaker Studio image support policy](sagemaker-distribution.md). SageMaker AI Distribution images include popular libraries and packages for machine learning, data science, and data analytics visualization. For a list of base SageMaker Distribution images and Amazon Elastic Container Registry account information, see [Amazon SageMaker Images Available for Use With Studio Classic Notebooks](notebooks-available-images.md). To build a custom image, complete one of the following. + Extend a SageMaker Distribution image with custom packages and modules. These images are pre-configured with JupyterLab and Code Editor, based on Code-OSS, Visual Studio Code - Open Source. + Build a custom Dockerfile file by following the instructions in [Bring your own image (BYOI)](studio-updated-byoi.md). You must install JupyterLab and the open source CodeServer on the image to make it compatible with Studio. ## Migrate lifecycle configurations Because of the simplified local runtime model in Studio, we recommend migrating the structure of your existing Studio Classic LCCs. In Studio Classic, you often have to create separate lifecycle configurations for both KernelGateway and JupyterServer applications. Because the JupyterServer and KernelGateway applications run on separate compute resources within Studio Classic, Studio Classic LCCs can be one of either type: + JupyterServer LCC: These LCCs mostly govern a user’s home actions, including setting proxy, creating environment variables, and auto-shutdown of resources. + KernelGateway LCC: These LCCs govern Studio Classic notebook environment optimizations. This includes updating numpy package versions in the `Data Science 3.0` kernel and installing the snowflake package in `Pytorch 2.0 GPU` kernel. In the simplified Studio architecture, you only need one LCC script that runs at application start up. While migration of your LCC scripts varies based on development environment, we recommend combining JupyterServer and KernelGateway LCCs to build a combined LCC. LCCs in Studio can be associated with one of the following applications: + JupyterLab + Code Editor Users can select the LCC for the respective application type when creating a space or use the default LCC set by the admin. **Note** Existing Studio Classic auto-shutdown scripts do not work with Studio. For an example Studio auto-shutdown script, see [SageMaker Studio Lifecycle Configuration examples](https://github.com/aws-samples/sagemaker-studio-apps-lifecycle-config-examples). ### Considerations when refactoring LCCs Consider the following differences between Studio Classic and Studio when refactoring your LCCs. + JupyterLab and Code Editor applications, when created, are run as `sagemaker-user` with `UID:1001` and `GID:101`. By default, `sagemaker-user` has permissions to assume sudo/root permissions. KernelGateway applications are run as `root` by default. + SageMaker Distribution images that run inside JupyterLab and Code Editor apps use the Debian-based package manager, `apt-get`. + Studio JupyterLab and Code Editor applications use the Conda package manager. SageMaker AI creates a single base Python3 Conda environment when a Studio application is launched. For information about updating packages in the base Conda environment and creating new Conda environments, see [JupyterLab user guide](studio-updated-jl-user-guide.md). In contrast, not all KernelGateway applications use Conda as a package manager. + The Studio JupyterLab application uses `JupyterLab 4.0`, while Studio Classic uses `JupyterLab 3.0`. Validate that all JupyterLab extensions you use are compatible with `JupyterLab 4.0`. For more information about extensions, see [Extension Compatibility with JupyterLab 4.0](https://github.com/jupyterlab/jupyterlab/issues/14590). # (Optional) Migrate data from Studio Classic to Studio Studio Classic and Studio use two different types of storage volumes. Studio Classic uses a single Amazon Elastic File System (Amazon EFS) volume to store data across all users and shared spaces in the domain. In Studio, each space gets its own Amazon Elastic Block Store (Amazon EBS) volume. When you update the default experience of an existing domain, SageMaker AI automatically mounts a folder in an Amazon EFS volume for each user in a domain. As a result, users are able to access files from Studio Classic in their Studio applications. For more information, see [Amazon EFS auto-mounting in Studio](studio-updated-automount.md). You can also opt out of Amazon EFS auto-mounting and manually migrate the data to give users access to files from Studio Classic in Studio applications. To accomplish this, you must transfer the files from the user home directories to the Amazon EBS volumes associated with those spaces. The following section gives information about this workflow. For more information about opting out of Amazon EFS auto-mounting, see [Opt out of Amazon EFS auto-mounting](studio-updated-automount-optout.md). ## Manually migrate all of your data from Studio Classic The following section describes how to migrate all of the data from your Studio Classic storage volume to the new Studio experience. When manually migrating a user's data, code, and artifacts from Studio Classic to Studio, we recommend one of the following approaches: 1. Using a custom Amazon EFS volume 1. Using Amazon Simple Storage Service (Amazon S3) If you used Amazon SageMaker Data Wrangler in Studio Classic and want to migrate your data flow files, then choose one of the following options for migration: + If you want to migrate all of the data from your Studio Classic storage volume, including your data flow files, go to [Manually migrate all of your data from Studio Classic](#studio-updated-migrate-data-all) and complete the section **Use Amazon S3 to migrate data**. Then, skip to the [Import the flow files into Canvas](#studio-updated-migrate-flows-import) section. + If you only want to migrate your data flow files and no other data from your Studio Classic storage volume, skip to the [Migrate data flows from Data Wrangler](#studio-updated-migrate-flows) section. ### Prerequisites Before running these steps, complete the prerequisites in [Complete prerequisites to migrate the Studio experience](studio-updated-migrate-prereq.md). You must also complete the steps in [Migrate the UI from Studio Classic to Studio](studio-updated-migrate-ui.md). ### Choosing an approach Consider the following when choosing an approach to migrate your Studio Classic data. ** Pros and cons of using a custom Amazon EFS volume** In this approach, you use an Amazon EFS-to-Amazon EFS AWS DataSync task (one time or cadence) to copy data, then mount the target Amazon EFS volume to a user’s spaces. This gives users access to data from Studio Classic in their Studio compute environments. Pros: + Only the user’s home directory data is visible in the user's spaces. There is no data cross-pollination. + Syncing from the source Amazon EFS volume to a target Amazon EFS volume is safer than directly mounting the source Amazon EFS volume managed by SageMaker AI into spaces. This avoids the potential to impact home directory user files. + Users have the flexibility to continue working in Studio Classic and Studio applications, while having their data available in both applications if AWS DataSync is set up on a regular cadence. + No need for repeated push and pull with Amazon S3. Cons: + No write access to the target Amazon EFS volume mounted to user's spaces. To get write access to the target Amazon EFS volume, customers would need to mount the target Amazon EFS volume to an Amazon Elastic Compute Cloud instance and provide appropriate permissions for users to write to the Amazon EFS prefix. + Requires modification to the security groups managed by SageMaker AI to allow network file system (NFS) inbound and outbound flow. + Costs more than using Amazon S3. + If [migrating data flows from Data Wrangler in Studio Classic](#studio-updated-migrate-flows), you must follow the steps for manually exporting flow files. **Pros and cons of using Amazon S3** In this approach, you use an Amazon EFS-to-Amazon S3 AWS DataSync task (one time or cadence) to copy data, then create a lifecycle configuration to copy the user’s data from Amazon S3 to their private space’s Amazon EBS volume. Pros: + If the LCC is attached to the domain, users can choose to use the LCC to copy data to their space or to run the space with no LCC script. This gives users the choice to copy their files only to the spaces they need. + If an AWS DataSync task is set up on a cadence, users can restart their Studio application to get the latest files. + Because the data is copied over to Amazon EBS, users have write permissions on the files. + Amazon S3 storage is cheaper than Amazon EFS. + If [migrating data flows from Data Wrangler in Studio Classic](#studio-updated-migrate-flows), you can skip the manual export steps and directly import the data flows into SageMaker Canvas from Amazon S3. Cons: + If administrators need to prevent cross-pollination, they must create AWS Identity and Access Management policies at the user level to ensure users can only access the Amazon S3 prefix that contains their files. ### Use a custom Amazon EFS volume to migrate data In this approach, you use an Amazon EFS-to-Amazon EFS AWS DataSync to copy the contents of a Studio Classic Amazon EFS volume to a target Amazon EFS volume once or in a regular cadence, then mount the target Amazon EFS volume to a user’s spaces. This gives users access to data from Studio Classic in their Studio compute environments. 1. Create a target Amazon EFS volume. You will transfer data into this Amazon EFS volume and mount it to a corresponding user's space using prefix-level mounting. ``` export SOURCE_DOMAIN_ID="domain-id" export AWS_REGION="region" export TARGET_EFS=$(aws efs create-file-system --performance-mode generalPurpose --throughput-mode bursting --encrypted --region $REGION | jq -r '.FileSystemId') echo "Target EFS volume Created: $TARGET_EFS" ``` 1. Add variables for the source Amazon EFS volume currently attached to the domain and used by all users. The domain's Amazon Virtual Private Cloud information is required to ensure the target Amazon EFS is created in the same Amazon VPC and subnet, with the same security group configuration. ``` export SOURCE_EFS=$(aws sagemaker describe-domain --domain-id $SOURCE_DOMAIN_ID | jq -r '.HomeEfsFileSystemId') export VPC_ID=$(aws sagemaker describe-domain --domain-id $SOURCE_DOMAIN_ID | jq -r '.VpcId') echo "EFS managed by SageMaker: $SOURCE_EFS | VPC: $VPC_ID" ``` 1. Create an Amazon EFS mount target in the same Amazon VPC and subnet as the source Amazon EFS volume, with the same security group configuration. The mount target takes a few minutes to be available. ``` export EFS_VPC_ID=$(aws efs describe-mount-targets --file-system-id $SOURCE_EFS | jq -r ".MountTargets[0].VpcId") export EFS_AZ_NAME=$(aws efs describe-mount-targets --file-system-id $SOURCE_EFS | jq -r ".MountTargets[0].AvailabilityZoneName") export EFS_AZ_ID=$(aws efs describe-mount-targets --file-system-id $SOURCE_EFS | jq -r ".MountTargets[0].AvailabilityZoneId") export EFS_SUBNET_ID=$(aws efs describe-mount-targets --file-system-id $SOURCE_EFS | jq -r ".MountTargets[0].SubnetId") export EFS_MOUNT_TARG_ID=$(aws efs describe-mount-targets --file-system-id $SOURCE_EFS | jq -r ".MountTargets[0].MountTargetId") export EFS_SG_IDS=$(aws efs describe-mount-target-security-groups --mount-target-id $EFS_MOUNT_TARG_ID | jq -r '.SecurityGroups[]') aws efs create-mount-target \ --file-system-id $TARGET_EFS \ --subnet-id $EFS_SUBNET_ID \ --security-groups $EFS_SG_IDS ``` 1. Create Amazon EFS source and destination locations for the AWS DataSync task. ``` export SOURCE_EFS_ARN=$(aws efs describe-file-systems --file-system-id $SOURCE_EFS | jq -r ".FileSystems[0].FileSystemArn") export TARGET_EFS_ARN=$(aws efs describe-file-systems --file-system-id $TARGET_EFS | jq -r ".FileSystems[0].FileSystemArn") export EFS_SUBNET_ID_ARN=$(aws ec2 describe-subnets --subnet-ids $EFS_SUBNET_ID | jq -r ".Subnets[0].SubnetArn") export ACCOUNT_ID=$(aws ec2 describe-security-groups --group-id $EFS_SG_IDS | jq -r ".SecurityGroups[0].OwnerId") export EFS_SG_ID_ARN=arn:aws:ec2:$REGION:$ACCOUNT_ID:security-group/$EFS_SG_IDS export SOURCE_LOCATION_ARN=$(aws datasync create-location-efs --subdirectory "/" --efs-filesystem-arn $SOURCE_EFS_ARN --ec2-config SubnetArn=$EFS_SUBNET_ID_ARN,SecurityGroupArns=$EFS_SG_ID_ARN --region $REGION | jq -r ".LocationArn") export DESTINATION_LOCATION_ARN=$(aws datasync create-location-efs --subdirectory "/" --efs-filesystem-arn $TARGET_EFS_ARN --ec2-config SubnetArn=$EFS_SUBNET_ID_ARN,SecurityGroupArns=$EFS_SG_ID_ARN --region $REGION | jq -r ".LocationArn") ``` 1. Allow traffic between the source and target network file system (NFS) mounts. When a new domain is created, SageMaker AI creates 2 security groups. + NFS inbound security group with only inbound traffic. + NFS outbound security group with only outbound traffic. The source and target NFS are placed inside the same security groups. You can allow traffic between these mounts from the AWS Management Console or AWS CLI. + Allow traffic from the AWS Management Console 1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/). 1. Choose **Security Groups**. 1. Search for the existing domain's ID on the **Security Groups** page. ``` d-xxxxxxx ``` The results should return two security groups that include the domain ID in the name. + `security-group-for-inbound-nfs-domain-id` + `security-group-for-outbound-nfs-domain-id` 1. Select the inbound security group ID. This opens a new page with details about the security group. 1. Select the **Outbound Rules** tab. 1. Select **Edit outbound rules**. 1. Update the existing outbound rules or add a new outbound rule with the following values: + **Type**: NFS + **Protocol**: TCP + **Port range**: 2049 + **Destination**: security-group-for-outbound-nfs-*domain-id* \$1 *security-group-id* 1. Choose **Save rules**. 1. Select the **Inbound Rules** tab. 1. Select **Edit inbound rules**. 1. Update the existing inbound rules or add a new outbound rule with the following values: + **Type**: NFS + **Protocol**: TCP + **Port range**: 2049 + **Destination**: security-group-for-outbound-nfs-*domain-id* \$1 *security-group-id* 1. Choose **Save rules**. + Allow traffic from the AWS CLI 1. Update the security group inbound and outbound rules with the following values: + **Protocol**: TCP + **Port range**: 2049 + **Group ID**: Inbound security group ID or outbound security group ID ``` export INBOUND_SG_ID=$(aws ec2 describe-security-groups --filters "Name=group-name,Values=security-group-for-inbound-nfs-$SOURCE_DOMAIN_ID" | jq -r ".SecurityGroups[0].GroupId") export OUTBOUND_SG_ID=$(aws ec2 describe-security-groups --filters "Name=group-name,Values=security-group-for-outbound-nfs-$SOURCE_DOMAIN_ID" | jq -r ".SecurityGroups[0].GroupId") echo "Outbound SG ID: $OUTBOUND_SG_ID | Inbound SG ID: $INBOUND_SG_ID" aws ec2 authorize-security-group-egress \ --group-id $INBOUND_SG_ID \ --protocol tcp --port 2049 \ --source-group $OUTBOUND_SG_ID aws ec2 authorize-security-group-ingress \ --group-id $OUTBOUND_SG_ID \ --protocol tcp --port 2049 \ --source-group $INBOUND_SG_ID ``` 1. Add both the inbound and outbound security groups to the source and target Amazon EFS mount targets. This allows traffic between the 2 Amazon EFS mounts. ``` export SOURCE_EFS_MOUNT_TARGET=$(aws efs describe-mount-targets --file-system-id $SOURCE_EFS | jq -r ".MountTargets[0].MountTargetId") export TARGET_EFS_MOUNT_TARGET=$(aws efs describe-mount-targets --file-system-id $TARGET_EFS | jq -r ".MountTargets[0].MountTargetId") aws efs modify-mount-target-security-groups \ --mount-target-id $SOURCE_EFS_MOUNT_TARGET \ --security-groups $INBOUND_SG_ID $OUTBOUND_SG_ID aws efs modify-mount-target-security-groups \ --mount-target-id $TARGET_EFS_MOUNT_TARGET \ --security-groups $INBOUND_SG_ID $OUTBOUND_SG_ID ``` 1. Create a AWS DataSync task. This returns a task ARN that can be used to run the task on-demand or as part of a regular cadence. ``` export EXTRA_XFER_OPTIONS='VerifyMode=ONLY_FILES_TRANSFERRED,OverwriteMode=ALWAYS,Atime=NONE,Mtime=NONE,Uid=NONE,Gid=NONE,PreserveDeletedFiles=REMOVE,PreserveDevices=NONE,PosixPermissions=NONE,TaskQueueing=ENABLED,TransferMode=CHANGED,SecurityDescriptorCopyFlags=NONE,ObjectTags=NONE' export DATASYNC_TASK_ARN=$(aws datasync create-task --source-location-arn $SOURCE_LOCATION_ARN --destination-location-arn $DESTINATION_LOCATION_ARN --name "SMEFS_to_CustomEFS_Sync" --region $REGION --options $EXTRA_XFER_OPTIONS | jq -r ".TaskArn") ``` 1. Start a AWS DataSync task to automatically copy data from the source Amazon EFS to the target Amazon EFS mount. This does not retain the file's POSIX permissions, which allows users to read from the target Amazon EFS mount, but not write to it. ``` aws datasync start-task-execution --task-arn $DATASYNC_TASK_ARN ``` 1. Mount the target Amazon EFS volume on the domain at the root level. ``` aws sagemaker update-domain --domain-id $SOURCE_DOMAIN_ID \ --default-user-settings '{"CustomFileSystemConfigs": [{"EFSFileSystemConfig": {"FileSystemId": "'"$TARGET_EFS"'", "FileSystemPath": "/"}}]}' ``` 1. Overwrite every user profile with a `FileSystemPath` prefix. The prefix includes the user’s UID, which is created by SageMaker AI. This ensure user’s only have access to their data and prevents cross-pollination. When a space is created in the domain and the target Amazon EFS volume is mounted to the application, the user’s prefix overwrites the domain prefix. As a result, SageMaker AI only mounts the `/user-id` directory on the user's application. ``` aws sagemaker list-user-profiles --domain-id $SOURCE_DOMAIN_ID | jq -r '.UserProfiles[] | "\(.UserProfileName)"' | while read user; do export uid=$(aws sagemaker describe-user-profile --domain-id $SOURCE_DOMAIN_ID --user-profile-name $user | jq -r ".HomeEfsFileSystemUid") echo "$user $uid" aws sagemaker update-user-profile --domain-id $SOURCE_DOMAIN_ID --user-profile-name $user --user-settings '{"CustomFileSystemConfigs": [{"EFSFileSystemConfig":{"FileSystemId": "'"$TARGET_EFS"'", "FileSystemPath": "'"/$uid/"'"}}]}' done ``` 1. Users can then select the custom Amazon EFS filesystem when launching an application. For more information, see [JupyterLab user guide](studio-updated-jl-user-guide.md) or [Launch a Code Editor application in Studio](code-editor-use-studio.md). ### Use Amazon S3 to migrate data In this approach, you use an Amazon EFS-to-Amazon S3 AWS DataSync task to copy the contents of a Studio Classic Amazon EFS volume to an Amazon S3 bucket once or in a regular cadence, then create a lifecycle configuration to copy the user’s data from Amazon S3 to their private space’s Amazon EBS volume. **Note** This approach only works for domains that have internet access. 1. Set the source Amazon EFS volume ID from the domain containing the data that you are migrating. ``` timestamp=$(date +%Y%m%d%H%M%S) export SOURCE_DOMAIN_ID="domain-id" export AWS_REGION="region" export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text) export EFS_ID=$(aws sagemaker describe-domain --domain-id $SOURCE_DOMAIN_ID | jq -r '.HomeEfsFileSystemId') ``` 1. Set the target Amazon S3 bucket name. For information about creating an Amazon S3 bucket, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html). The bucket used must have a CORS policy as described in [(Optional) Update your CORS policy to access Amazon S3 buckets](studio-updated-migrate-ui.md#studio-updated-migrate-cors). Users in the domain must also have permissions to access the Amazon S3 bucket. In this example, we are copying files to a prefix named `studio-new`. If you are using a single Amazon S3 bucket to migrate multiple domains, use the `studio-new/` prefix to restrict permissions to the files using IAM. ``` export BUCKET_NAME=s3-bucket-name export S3_DESTINATION_PATH=studio-new ``` 1. Create a trust policy that gives AWS DataSync permissions to assume the execution role of your account. ``` export TRUST_POLICY=$(cat <