# SageMaker JupyterLab JupyterLab Create a JupyterLab space within Amazon SageMaker Studio to launch the JupyterLab application. A JupyterLab space is a private or shared space within Studio that manages the storage and compute resources needed to run the JupyterLab application. The JupyterLab application is a web-based interactive development environment (IDE) for notebooks, code, and data. Use the JupyterLab application's flexible and extensive interface to configure and arrange machine learning (ML) workflows. By default, the JupyterLab application comes with the SageMaker Distribution image. The distribution image has popular packages, such as the following: + PyTorch + TensorFlow + Keras + NumPy + Pandas + Scikit-learn You can use shared spaces to collaborate on your Jupyter notebooks with other users in real time. For more information about shared spaces, see [Collaboration with shared spaces](domain-space.md). Within the JupyterLab application, you can use Amazon Q Developer, a generative AI powered code companion to generate, debug, and explain your code. For information about using Amazon Q Developer, see [JupyterLab user guide](studio-updated-jl-user-guide.md). For information about setting up Amazon Q Developer, see [JupyterLab administrator guide](studio-updated-jl-admin-guide.md). Build unified analytics and ML workflows in same Jupyter notebook. Run interactive Spark jobs on Amazon EMR and AWS Glue serverless infrastructure, right from your notebook. Monitor and debug jobs faster using the inline Spark UI. In a few steps, you can automate your data prep by scheduling the notebook as a job. The JupyterLab application helps you work collaboratively with your peers. Use the built-in Git integration within the JupyterLab IDE to share and version code. Bring your own file storage system if you have an Amazon EFS volume. The JupyterLab application runs on a single Amazon Elastic Compute Cloud (Amazon EC2) instance and uses a single Amazon Elastic Block Store (Amazon EBS) volume for storage. You can switch faster instances or increase the Amazon EBS volume size for your needs. The JupyterLab 4 application runs in a JupyterLab space within Studio. Studio Classic uses the JupyterLab 3 application. JupyterLab 4 provides the following benefits: + A faster IDE than Amazon SageMaker Studio Classic, especially with large notebooks + Improved document search + A more performant and accessible text editor For more information about JupyterLab, see [JupyterLab Documentation](https://jupyterlab.readthedocs.io/en/stable/#). **Topics** + [ # JupyterLab user guide ](studio-updated-jl-user-guide.md) + [ # JupyterLab administrator guide ](studio-updated-jl-admin-guide.md) # JupyterLab user guide This guide shows JupyterLab users how to run analytics and machine learning workflows within SageMaker Studio. You can get fast storage and scale your compute up or down, depending on your needs. JupyterLab supports both private and shared spaces. Private spaces are scoped to a single user in a domain. Shared spaces let other users in your domain collaborate with you in real time. For information about Studio spaces, see [Amazon SageMaker Studio spaces](studio-updated-spaces.md). To get started using JupyterLab, create a space and launch your JupyterLab application. The space running your JupyterLab application is a JupyterLab space. The JupyterLab space uses a single Amazon EC2 instance for your compute and a single Amazon EBS volume for your storage. Everything in your space such as your code, git profile, and environment variables are stored on the same Amazon EBS volume. The volume has 3000 IOPS and a throughput of 125 megabytes per second (MBps). You can use the fast storage to open and run multiple Jupyter notebooks on the same instance. You can also switch kernels in a notebook very quickly. Your administrator has configured the default Amazon EBS storage settings for your space. The default storage size is 5 GB, but you can increase the amount of space that you get. You can talk to your administrator to provide you with guidelines. You can switch the Amazon EC2 instance type that you’re using to run JupyterLab, scaling your compute up or down depending on your needs. The **Fast launch** instances start up much faster than the other instances. Your administrator might provide you with a lifecycle configuration that customizes your environment. You can specify the lifecycle configuration when you create the space. If your administrator gives you access to an Amazon EFS, you can configure your JupyterLab space to access it. By default, the JupyterLab application uses the SageMaker distribution image. This includes support for many machine learning, analytics, and deep learning packages. However, if you need a custom image, your administrator can help provide access to the custom images. The Amazon EBS volume persists independently from the life of an instance. You won’t lose your data when you change instances. Use the conda and pip package management libraries to create reproducible custom environments that persist even when you switch instance types. After you open JupyterLab, you can configure your environment using the terminal. To open the terminal, navigate to the **Launcher** and choose **Terminal**. The following are examples of different ways that you can configure an environment in JupyterLab. **Note** Within Studio, you can use lifecycle configurations to customize your environment, but we recommend using a package manager instead. Using lifecycle configurations is a more error-prone method. It’s easier to add or remove dependencies than it is to debug a lifecycle configuration script. It can also increase the JupyterLab startup time. For information about lifecycle configurations, see [Lifecycle configurations with JupyterLab](jl-lcc.md). **Topics** + [ # Create a space ](studio-updated-jl-user-guide-create-space.md) + [ # Configure a space ](studio-updated-jl-user-guide-configure-space.md) + [ # Customize your environment using a package manager ](studio-updated-jl-user-guide-customize-package-manager.md) + [ # Clean up a conda environment ](studio-updated-jl-clean-up-conda.md) + [ # Share conda environments between instance types ](studio-updated-jl-create-conda-share-environment.md) + [ # Use Amazon Q to Expedite Your Machine Learning Workflows ](studio-updated-jl-user-guide-use-amazon-q.md) # Create a space To get started using JupyterLab, create a space or choose the space that your administrator created for you and open JupyterLab. Use the following procedure to create a space and open JupyterLab. **To create a space and open JupyterLab** 1. Open Studio. For information about opening Studio, see [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. Choose **JupyterLab**. 1. Choose **Create JupyterLab space**. 1. For **Name**, specify the name of the space. 1. (Optional) Select **Share with my domain** to create a shared space. 1. Choose **Create space**. 1. (Optional) For **Instance**, specify the Amazon EC2 instance that runs the space. 1. (Optional) For **Image**, specify an image that your administrator provided to customize your environment. **Important** Custom IAM policies that allow Studio users to create spaces must also grant permissions to list images (`sagemaker: ListImage`) to view custom images. To add the permission, see [ Add or remove identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *AWS Identity and Access Management* User Guide. [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker AI resources already include permissions to list images while creating those resources. 1. (Optional) For **Space Settings**, specify the following: + **Storage (GB)** – Up to 100 GB or the amount that your administrator specifies. + **Lifecycle Configuration** – A lifecycle configuration that your administrator specifies. + **Attach custom EFS filesystem** – An Amazon EFS to which your administrator provides access. 1. Choose **Run space**. 1. Choose **Open JupyterLab**. # Configure a space After you create a JupyterLab space, you can configure it to do the following: + Change the instance type. + Change the storage volume. + (Admin set up required) Use a custom image. + (Admin set up required) Use a lifecycle configuration. + (Admin set up required) Attach a custom Amazon EFS. **Important** You must stop the JupyterLab space every time you configure it. Use the following procedure to configure the space. **To configure a space** 1. Within Studio, navigate to the JupyterLab application page. 1. Choose the name of the space. 1. (Optional) For **Image**, specify an image that your administrator provided to customize your environment. **Important** Custom IAM policies that allow Studio users to create spaces must also grant permissions to list images (`sagemaker: ListImage`) to view custom images. To add the permission, see [ Add or remove identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *AWS Identity and Access Management* User Guide. [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker AI resources already include permissions to list images while creating those resources. 1. (Optional) For **Space Settings**, specify the following: + **Storage (GB)** – Up to 100 GB or the amount that your administrator configured for the space. + **Lifecycle Configuration** – A lifecycle configuration that your administrator provides. + **Attach custom EFS filesystem** – An Amazon EFS to which your administrator provides access. 1. Choose **Run space**. When you open the JupyterLab application, your space has the updated configuration. # Customize your environment using a package manager Use pip or conda to customize your environment. We recommend using package managers instead of lifecycle configuration scripts. ## Create and activate your custom environment This section provides examples of different ways that you can configure an environment in JupyterLab. A basic conda environment has the minimum number of packages that are required for your workflows in SageMaker AI. Use the following template to a create a basic conda environment: ``` # initialize conda for shell interaction conda init # create a new fresh environment conda create --name test-env # check if your new environment is created successfully conda info --envs # activate the new environment conda activate test-env # install packages in your new conda environment conda install pip boto3 pandas ipykernel # list all packages install in your new environment conda list # parse env name information from your new environment export CURRENT_ENV_NAME=$(conda info | grep "active environment" | cut -d : -f 2 | tr -d ' ') # register your new environment as Jupyter Kernel for execution python3 -m ipykernel install --user --name $CURRENT_ENV_NAME --display-name "user-env:($CURRENT_ENV_NAME)" # to exit your new environment conda deactivate ``` The following image shows the location of the environment that you've created. ![\[The test-env environment is displayed in the top right corner of the screen.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/juptyer-notebook-environment-location.png) To change your environment, choose it and select an option from the dropdown menu. ![\[The checkmark and its corresponding text shows an example environment that you previously created.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/jupyter-notebook-select-env.png) Choose **Select** to select a kernel for the environment. ## Create a conda environment with a specific Python version Cleaning up conda environments that you’re not using can help free up disk space and improve performance. Use the following template to clean up a conda environment: ``` # create a conda environment with a specific python version conda create --name py38-test-env python=3.8.10 # activate and test your new python version conda activate py38-test-env & python3 --version # Install ipykernel to facilicate env registration conda install ipykernel # parse env name information from your new environment export CURRENT_ENV_NAME=$(conda info | grep "active environment" | cut -d : -f 2 | tr -d ' ') # register your new environment as Jupyter Kernel for execution python3 -m ipykernel install --user --name $CURRENT_ENV_NAME --display-name "user-env:($CURRENT_ENV_NAME)" # deactivate your py38 test environment conda deactivate ``` ## Create a conda environment with a specific set of packages Use the following template to create a conda environment with a specific version of Python and set of packages: ``` # prefill your conda environment with a set of packages, conda create --name py38-test-env python=3.8.10 pandas matplotlib=3.7 scipy ipykernel # activate your conda environment and ensure these packages exist conda activate py38-test-env # check if these packages exist conda list | grep -E 'pandas|matplotlib|scipy' # parse env name information from your new environment export CURRENT_ENV_NAME=$(conda info | grep "active environment" | cut -d : -f 2 | tr -d ' ') # register your new environment as Jupyter Kernel for execution python3 -m ipykernel install --user --name $CURRENT_ENV_NAME --display-name "user-env:($CURRENT_ENV_NAME)" # deactivate your conda environment conda deactivate ``` ## Clone conda from an existing environment Clone your conda environment to preserve its working state. You experiment in the cloned environment without having to worry about introducing breaking changes in your test environment. Use the following command to clone an environment. ``` # create a fresh env from a base environment conda create --name py310-base-ext --clone base # replace 'base' with another env # activate your conda environment and ensure these packages exist conda activate py310-base-ext # install ipykernel to register your env conda install ipykernel # parse env name information from your new environment export CURRENT_ENV_NAME=$(conda info | grep "active environment" | cut -d : -f 2 | tr -d ' ') # register your new environment as Jupyter Kernel for execution python3 -m ipykernel install --user --name $CURRENT_ENV_NAME --display-name "user-env:($CURRENT_ENV_NAME)" # deactivate your conda environment conda deactivate ``` ## Clone conda from a reference YAML file Create a conda environment from a reference YAML file. The following is an example of a YAML file that you can use. ``` # anatomy of a reference environment.yml name: py311-new-env channels: - conda-forge dependencies: - python=3.11 - numpy - pandas - scipy - matplotlib - pip - ipykernel - pip: - git+https://github.com/huggingface/transformers ``` Under `pip`, we recommend specifying only the dependencies that aren't available with conda. Use the following commands to create a conda environment from a YAML file. ``` # create your conda environment conda env create -f environment.yml # activate your env conda activate py311-new-env ``` # Clean up a conda environment Cleaning up conda environments that you’re not using can help free up disk space and improve performance. Use the following template to clean up a conda environment: ``` # list your environments to select an environment to clean conda info --envs # or conda info -e # once you've selected your environment to purge conda remove --name test-env --all # run conda environment list to ensure the target environment is purged conda info --envs # or conda info -e ``` # Share conda environments between instance types Share conda environments You can share conda environments by saving them to an Amazon EFS directory outside of your Amazon EBS volume. Another user can access the environment in the directory where you saved it. **Important** There are limitations with sharing your environments. For example, we don't recommend an environment meant to run on a GPU Amazon EC2 instance over an environment running on a CPU instance. Use the following commands as a template to specify the target directory where you’re creating a custom environment. You’re creating a conda within a particular path. You create it within the Amazon EFS directory. You can spin up a new instance and do conda activate path and do it within the Amazon EFS. ``` # if you know your environment path for your conda environment conda create --prefix /home/sagemaker-user/my-project/py39-test python=3.9 # activate the env with full path from prefix conda activate home/sagemaker-user/my-project/py39-test # parse env name information from your new environment export CURRENT_ENV_NAME=$(conda info | grep "active environment" | awk -F' : ' '{print $2}' | awk -F'/' '{print $NF}') # register your new environment as Jupyter Kernel for execution python3 -m ipykernel install --user --name $CURRENT_ENV_NAME --display-name "user-env-prefix:($CURRENT_ENV_NAME)" # deactivate your conda environment conda deactivate ``` # Use Amazon Q to Expedite Your Machine Learning Workflows Amazon Q Developer is your AI-powered companion for machine learning development. With Amazon Q Developer, you can: + Receive step-by-step guidance on using SageMaker AI features independently or in combination with other AWS services. + Get sample code to get started on your ML tasks such as data preparation, training, inference, and MLOps. + Receive troubleshooting assistance to debug and resolve errors encountered while running code. Amazon Q Developer seamlessly integrates into your JupyterLab environment. To use Amazon Q Developer, choose the **Q** from the left-hand navigation of your JupyterLab environment or Code Editor environment. If you don't see the **Q** icon, your administrator needs to set it up for you. For more information about setting up Amazon Q Developer, see [Set up Amazon Q Developer for your users](studio-updated-amazon-q-admin-guide-set-up.md). Amazon Q automatically provides suggestions to help you write your code. You can also ask for suggestions through the chat interface. # JupyterLab administrator guide **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 guide for administrators describes SageMaker AI JupyterLab resources, such as those from Amazon Elastic Block Store (Amazon EBS) and Amazon Elastic Compute Cloud (Amazon EC2). The topics also show how to provide user access and change storage size. A SageMaker AI JupyterLab space is composed of the following resources: + A distinct Amazon EBS volume that stores all of the data, such as the code and the environment variables. + The Amazon EC2 instance used to run the space. + The image used to run JupyterLab. **Note** Applications do not have access to the EBS volume of other applications. For example, Code Editor, based on Code-OSS, Visual Studio Code - Open Source doesn't have access to the EBS volume for JupyterLab. For more information about EBS volumes, see [Amazon Elastic Block Store (Amazon EBS)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html). You can use the Amazon SageMaker API to do the following: + Change the default storage size of the EBS volume for your users. + Change the maximum size of the EBS storage + Specify the user settings for the application. For example, you can specify whether the user is using a custom image or a code repository. + Specify the support application type. The default size of the Amazon EBS volume is 5 GB. You can increase the volume size to a maximum of 16,384 GB. If you don't do anything, your users can increase their volume size to 100 GB. The volume size can be changed only once within a six hour period. The kernels associated with the JupyterLab application run on the same Amazon EC2 instance that runs JupyterLab. When you create a space, the latest version of the SageMaker Distribution Image is used by default. For more information about SageMaker Distribution Images, see [SageMaker Studio image support policy](sagemaker-distribution.md). **Important** For information about updating the space to use the latest version of the SageMaker AI Distribution Image, see [Update the SageMaker Distribution Image](studio-updated-jl-update-distribution-image.md). The working directory of your users within the storage volume is `/home/sagemaker-user`. If you specify your own AWS KMS key to encrypt the volume, everything in the working directory is encrypted using your customer managed key. If you don't specify an AWS KMS key, the data inside `/home/sagemaker-user` is encrypted with an AWS managed key. Regardless of whether you specify an AWS KMS key, all of the data outside of the working directory is encrypted with an AWS Managed Key. The following sections walk you through the configurations that you need to perform as an administrator. **Topics** + [ # Give your users access to spaces ](studio-updated-jl-admin-guide-permissions.md) + [ # Change the default storage size for your JupyterLab users ](studio-updated-jl-admin-guide-storage-size.md) + [ # Lifecycle configurations with JupyterLab ](jl-lcc.md) + [ # Git repos in JupyterLab ](studio-updated-jl-admin-guide-git-attach.md) + [ # Custom images ](studio-updated-jl-admin-guide-custom-images.md) + [ # Update the SageMaker Distribution Image ](studio-updated-jl-update-distribution-image.md) + [ # Delete unused resources ](studio-updated-jl-admin-guide-clean-up.md) + [ # Quotas ](studio-updated-jl-admin-guide-quotas.md) # Give your users access to spaces To give users access to private or shared spaces, you must attach a permissions policy to their IAM roles. You can also use the permissions policy to restrict private spaces and their associated applications to a specific user profile. The following permissions policy grants access to private and shared spaces. This allows users to create their own space and list other spaces within their domain. A user with this policy can't access the private space of a different user. For information about Studio spaces, see [Amazon SageMaker Studio spaces](studio-updated-spaces.md). The policy provides users with permissions to the following: + Private spaces or shared spaces. + A user profile for accessing those spaces. To provide permissions, you can scope down the permissions of the following policy and add it to the IAM roles of your users. You can also use this policy to restrict your spaces, and their associated applications, to a specific user profile. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sagemaker:CreateApp", "sagemaker:DeleteApp" ], "Resource": "arn:aws:sagemaker:us-east-2:111122223333:app/*", "Condition": { "Null": { "sagemaker:OwnerUserProfileArn": "true" } } }, { "Sid": "SMStudioCreatePresignedDomainUrlForUserProfile", "Effect": "Allow", "Action": [ "sagemaker:CreatePresignedDomainUrl" ], "Resource": "arn:aws:sagemaker:us-east-2: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-2:111122223333:*/*", "Condition": { "Null": { "sagemaker:TaggingAction": "false" } } }, { "Sid": "SMStudioRestrictSharedSpacesWithoutOwners", "Effect": "Allow", "Action": [ "sagemaker:CreateSpace", "sagemaker:UpdateSpace", "sagemaker:DeleteSpace" ], "Resource": "arn:aws:sagemaker:us-east-2: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-2:111122223333:space/sagemaker:DomainId/*", "Condition": { "ArnLike": { "sagemaker:OwnerUserProfileArn": "arn:aws:sagemaker:us-east-2: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-2:111122223333:app/sagemaker:DomainId/*", "Condition": { "ArnLike": { "sagemaker:OwnerUserProfileArn": "arn:aws:sagemaker:us-east-2:111122223333:user-profile/sagemaker:DomainId/sagemaker:UserProfileName" }, "StringEquals": { "sagemaker:SpaceSharingType": [ "Private" ] } } } ] } ``` ------ # Change the default storage size for your JupyterLab users You can change the default storage settings for your users. You can also change the default storage settings based on your organizational requirements and the needs of your users. To change the storage size, this section provides commands to do the following: 1. Update the Amazon EBS storage settings in the Amazon SageMaker AI domain (domain). 1. Create a user profile and specify the storage settings within it. Use the following AWS Command Line Interface (AWS CLI) commands to change the default storage size. Use the following AWS CLI command to update the domain: ``` aws --region AWS Region sagemaker update-domain \ --domain-id domain-id \ --default-user-settings '{ "SpaceStorageSettings": { "DefaultEbsStorageSettings":{ "DefaultEbsVolumeSizeInGb":5, "MaximumEbsVolumeSizeInGb":100 } } }' ``` Use the following AWS CLI command to create the user profile and specify the default storage settings: ``` aws --region AWS Region sagemaker create-user-profile \ --domain-id domain-id \ --user-profile-name user-profile-name \ --user-settings '{ "SpaceStorageSettings": { "DefaultEbsStorageSettings":{ "DefaultEbsVolumeSizeInGb":5, "MaximumEbsVolumeSizeInGb":100 } } }' ``` Use the following AWS CLI commands to update the default storage settings in the user profile: ``` aws --region AWS Region sagemaker update-user-profile \ --domain-id domain-id \ --user-profile-name user-profile-name \ --user-settings '{ "SpaceStorageSettings": { "DefaultEbsStorageSettings":{ "DefaultEbsVolumeSizeInGb":25, "MaximumEbsVolumeSizeInGb":200 } } }' ``` # Lifecycle configurations with JupyterLab Lifecycle configurations are shell scripts that are triggered by JupyterLab lifecycle events, such as starting a new JupyterLab notebook. You can use lifecycle configurations to automate customization for your JupyterLab environment. This customization includes installing custom packages, configuring notebook extensions, preloading datasets, and setting up source code repositories. Using lifecycle configurations gives you flexibility and control to configure JupyterLab to meet your specific needs. For example, you can create a minimal set of base container images with the most commonly used packages and libraries. Then you can use lifecycle configurations to install additional packages for specific use cases across your data science and machine learning teams. **Note** Each script has a limit of **16,384 characters**. **Topics** + [ # Lifecycle configuration creation ](jl-lcc-create.md) + [ # Debug lifecycle configurations ](jl-lcc-debug.md) + [ # Detach lifecycle configurations ](jl-lcc-delete.md) # Lifecycle configuration creation This topic includes instructions for creating and associating a lifecycle configuration with JupyterLab. You use the AWS Command Line Interface (AWS CLI) or the AWS Management Console to automate customization for your JupyterLab environment. Lifecycle configurations are shell scripts triggered by JupyterLab lifecycle events, such as starting a new JupyterLab notebook. For more information about lifecycle configurations, see [Lifecycle configurations with JupyterLab](jl-lcc.md). ## Create a lifecycle configuration (AWS CLI) Create a lifecycle configuration (AWS CLI) Learn how to create a lifecycle configuration using the AWS Command Line Interface (AWS CLI) to automate customization for your Studio environment. ### Prerequisites 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). ### Step 1: Create a lifecycle configuration The following procedure shows how to create a lifecycle configuration script that prints `Hello World`. **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-jl-lcc \ --studio-lifecycle-config-content $LCC_CONTENT \ --studio-lifecycle-config-app-type 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. ### Step 2: Attach the lifecycle configuration to your Amazon SageMaker AI domain (domain) and user profile Step 2: Attach the lifecycle configuration 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. 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] } }' ``` ## Create a lifecycle configuration (Console) Create a lifecycle configuration (Console) Learn how to create a lifecycle configuration using the AWS Management Console to automate customization for your Studio environment. ### Step 1: Create a lifecycle configuration Use the following procedure to create a lifecycle configuration script that prints `Hello World`. **To create a lifecycle configuration** 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 **Lifecycle configurations**. 1. Choose the **JupyterLab** tab. 1. Choose **Create configuration**. 1. For **Name**, specify the name of the lifecycle configuration. 1. For the text box under **Scripts**, specify the following lifecycle configuration: ``` #!/bin/bash set -eux echo 'Hello World!' ``` 1. Choose **Create configuration**. ### Step 2: Attach the lifecycle configuration to your Amazon SageMaker AI domain (domain) and user profile Step 2: Attach the lifecycle configuration Lifecycle configuration scripts 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 attach multiple lifecycle configurations to a domain or user profile for JupyterLab. Use the following procedure to attach a lifecycle configuration to a domain. **To attach a lifecycle configuration to a domain** 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 to attach the lifecycle configuration to. 1. From the **Domain details**, choose the **Environment** tab. 1. Under **Lifecycle configurations for personal Studio apps**, choose **Attach**. 1. Under **Source**, choose **Existing configuration**. 1. Under **Studio lifecycle configurations**, select the lifecycle configuration that you created in the previous step. 1. Select **Attach to domain**. Use the following procedure to attach a lifecycle configuration to a user profile. **To attach a lifecycle configuration to a user profile** 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 contains the user profile to attach the lifecycle configuration to. 1. Under **User profiles**, select the user profile. 1. From the **User Details** page, choose **Edit**. 1. On the left navigation, choose **Studio settings**. 1. Under **Lifecycle configurations attached to user**, choose **Attach**. 1. Under **Source**, choose **Existing configuration**. 1. Under **Studio lifecycle configurations**, select the lifecycle configuration that you created in the previous step. 1. Choose **Attach to user profile**. # Debug lifecycle configurations 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 ](#jl-lcc-debug-logs) + [ ## Lifecycle configuration timeout ](#jl-lcc-debug-timeout) ## 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, 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 ``` ## Lifecycle configuration timeout 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. # Detach lifecycle configurations Detach lifecycle configurations To update your script, you must create a new lifecycle configuration script and attach it to the respective Amazon SageMaker AI domain (domain), user profile, or shared space. A lifecycle configuration script can't be changed after it's created. For more information about creating and attaching the lifecycle configuration, see [Lifecycle configuration creation](jl-lcc-create.md). The following section shows how to detach a lifecycle configuration using the AWS Command Line Interface (AWS CLI). ## Detach using the AWS CLI To detach a lifecycle configuration using the (AWS CLI), remove the desired lifecycle configuration from the list of lifecycle configurations attached to the resource. You then pass the list as part of the respective command: + [update-user-profile](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-user-profile.html) + [update-domain](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html) + [update-space](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-space.html) For example, the following command removes all lifecycle configurations for the JupyterLab application that's attached to the domain. ``` aws sagemaker update-domain --domain-id domain-id \ --region region \ --default-user-settings '{ "JupyterLabAppSettings": { "LifecycleConfigArns": [] } }' ``` # Git repos in JupyterLab Git repos JupyterLab offers a Git extension to enter the URL of a Git repository (repo), clone it into an environment, push changes, and view the commit history. You can also attach suggested Git repo URLs to a Amazon SageMaker AI domain (domain) or user profile. The following sections show how to attach or detach Git repo URLs. **Topics** + [ # Attach a Git repository (AWS CLI) ](studio-updated-git-attach-cli.md) + [ # Detach Git repo URLs ](studio-updated-git-detach.md) # Attach a Git repository (AWS CLI) This section shows how to attach a Git repository (repo) URL using the AWS CLI. After you attach the Git repo URL, you can clone it by following the steps in [Clone a Git repo in Amazon SageMaker Studio](#studio-updated-tasks-git). ## Prerequisites Before you begin, complete the following prerequisites: + Update the AWS CLI by following the steps in [Installing the current AWS Command Line Interface 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 more information, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). ## Attach the Git repo to a Amazon SageMaker AI domain (domain) or user profile Git repo URLs that are associated at the domain level are inherited by all users. However, Git repo URLs that are associated at the user profile level are scoped to a specific user. You can attach multiple Git repo URLs to a Amazon SageMaker AI domain or to a user profile by passing a list of repository URLs. The following sections show how to attach a Git repo URL to your domain and your user profile. ### Attach to a Amazon SageMaker AI domain The following command attaches a Git repo URL to an existing domain: ``` aws sagemaker update-domain --region region --domain-id domain-id \ --default-user-settings JupyterLabAppSettings={CodeRepositories=[{RepositoryUrl="repository"}]} ``` ### Attach to a user profile The following command attaches a Git repo URL to an existing user profile: ``` aws sagemaker update-user-profile --domain-id domain-id --user-profile-name user-name\ --user-settings JupyterLabAppSettings={CodeRepositories=[{RepositoryUrl="repository"}]} ``` ## Clone a Git repo in Amazon SageMaker Studio Amazon SageMaker Studio connects to a local Git repo only. To access the files in the repo, clone the Git repo from within Studio. To do so, Studio offers a Git extension for you to enter the URL of a Git repo, clone it into your environment, push changes, and view commit history. If the repo is private and requires credentials to access, you receive a prompt to enter your user credentials. Your credentials include your username and personal access token. For more information about personal access tokens, see [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Admins can also attach suggested Git repository URLs at the Amazon SageMaker AI domain or user profile level. Users can then select the repo URL from the list of suggestions and clone that into Studio. For more information about attaching suggested repos, see [Attach Suggested Git Repos to Amazon SageMaker Studio Classic](studio-git-attach.md). # Detach Git repo URLs This section shows how to detach Git repository URLs from an Amazon SageMaker AI domain (domain) or a user profile. You can detach repo URLs by using the AWS Command Line Interface (AWS CLI) or the Amazon SageMaker AI console. ## Detach a Git repo using the AWS CLI Detach using the AWS CLI To detach all Git repo URLs from a domain or user profile, you must pass an empty list of code repositories. This list is passed as part of the `JupyterLabAppSettings` parameter in an `update-domain` or `update-user-profile` command. To detach only one Git repo URL, pass the code repositories list without the desired Git repo URL. ### Detach from an Amazon SageMaker AI domain The following command detaches all Git repo URLs from a domain: ``` aws sagemaker update-domain --region region --domain-name domain-name \ --domain-settings JupyterLabAppSettings={CodeRepositories=[]} ``` ### Detach from a user profile The following command detaches all Git repo URLs from a user profile: ``` aws sagemaker update-user-profile --domain-name domain-name --user-profile-name user-name\ --user-settings JupyterLabAppSettings={CodeRepositories=[]} ``` # Custom images If you need functionality that is different than what's provided by SageMaker distribution, you can bring your own image with your custom extensions and packages. You can also use it to personalize the JupyterLab UI for your own branding or compliance needs. The following page will provide JupyterLab-specific information and templates to create your own custom SageMaker AI images. This is meant to supplement the Amazon SageMaker Studio information and instructions on creating your own SageMaker AI image and bringing your own image to Studio. To learn about custom Amazon SageMaker AI images and how to bring your own image to Studio, see [Bring your own image (BYOI)](studio-updated-byoi.md). **Topics** + [ ## Health check and URL for applications ](#studio-updated-jl-admin-guide-custom-images-app-healthcheck) + [ ## Dockerfile examples ](#studio-updated-jl-custom-images-dockerfile-templates) ## Health check and URL for applications + `Base URL` – The base URL for the BYOI application must be `jupyterlab/default`. You can only have one application and it must always be named `default`. + `HealthCheck API` – SageMaker AI uses the health check endpoint at port `8888` to check the health of the JupyterLab application. `jupyterlab/default/api/status` is the endpoint for the health check. + `Home/Default URL` – 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`. + Authentication – To enable authentication for your users, turn off the Jupyter notebooks token or password based authentication and allow all origins. ## Dockerfile examples The following examples are `Dockerfile`s that meets the above information and [Custom image specifications](studio-updated-byoi-specs.md). **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*. ------ #### [ Example AL2023 Dockerfile ] The following is an example AL2023 Dockerfile that meets the above information and [Custom image specifications](studio-updated-byoi-specs.md). ``` FROM public.ecr.aws/amazonlinux/amazonlinux:2023 ARG NB_USER="sagemaker-user" ARG NB_UID=1000 ARG NB_GID=100 # Install Python3, pip, and other dependencies RUN yum install -y \ python3 \ python3-pip \ python3-devel \ gcc \ shadow-utils && \ useradd --create-home --shell /bin/bash --gid "${NB_GID}" --uid ${NB_UID} ${NB_USER} && \ yum clean all RUN python3 -m pip install --no-cache-dir \ 'jupyterlab>=4.0.0,<5.0.0' \ urllib3 \ jupyter-activity-monitor-extension \ --ignore-installed # Verify versions RUN python3 --version && \ jupyter lab --version USER ${NB_UID} CMD jupyter lab --ip 0.0.0.0 --port 8888 \ --ServerApp.base_url="/jupyterlab/default" \ --ServerApp.token='' \ --ServerApp.allow_origin='*' ``` ------ #### [ Example Amazon SageMaker Distribution Dockerfile ] The following is a example Amazon SageMaker Distribution Dockerfile that meets the above information and [Custom image specifications](studio-updated-byoi-specs.md). ``` FROM public.ecr.aws/sagemaker/sagemaker-distribution:latest-cpu ARG NB_USER="sagemaker-user" ARG NB_UID=1000 ARG NB_GID=100 ENV MAMBA_USER=$NB_USER USER root RUN apt-get update RUN micromamba install sagemaker-inference --freeze-installed --yes --channel conda-forge --name base USER $MAMBA_USER ENTRYPOINT ["entrypoint-jupyter-server"] ``` ------ # Update the SageMaker Distribution Image **Important** This topic assumes that you've created a space and given the user access to it. For more information, see [Give your users access to spaces](studio-updated-jl-admin-guide-permissions.md). Update the JupyterLab spaces that you've already created to use the latest version of the SageMaker Distribution Image to access the latest features. You can use either the Studio UI or the AWS Command Line Interface (AWS CLI) to update the image. The following sections provide information about updating an image. ## Update the image (UI) Updating the image involves restarting the JupyterLab space of your user. Use the following procedure to update your user's JupyterLab space with the latest image. **To update the image (UI)** 1. Open Studio. For information about opening Studio, see [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. Choose **JupyterLab**. 1. Select the JupyterLab space of your user. 1. Choose **Stop space**. 1. For **Image**, select an updated version of the SageMaker AI Distribution Image. For the latest image, choose **Latest**. 1. Choose **Run space**. ## Update the image (AWS CLI) This section assumes that you have the AWS Command Line Interface (AWS CLI) installed. For information about installing the AWS CLI, see [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). To update the image, you must the do the following for your user's space: 1. Delete the JupyterLab application 1. Update the space 1. Create the application **Important** You must have the following information ready before you start updating the image: domain ID – The ID of your user's Amazon SageMaker AI domain. Application type – JupyterLab. Application name – default. Space name – The name specified for the space. Instance type – The Amazon EC2 instance type that you're using to run the application. For example, `ml.t3.medium`. SageMaker Image ARN – The Amazon Resource Name (ARN) of the SageMaker AI Distribution Image. You can provide the latest version of the SageMaker AI Distribution Image by specifying either `sagemaker-distribution-cpu` or `sagemaker-distribution-gpu` as the resource identifier. To delete the JupyterLab application, run the following command: ``` aws sagemaker delete-app \ --domain-id your-user's-domain-id --app-type JupyterLab \ --app-name default \ --space-name name-of-your-user's-space ``` To update your user's space, run the following command: ``` aws sagemaker update-space \ --space-name name-of-your-user's-space \ --domain-id your-user's-domain-id ``` If you've updated the space successfully, you'll see the space ARN in the response: ``` { "SpaceArn": "arn:aws:sagemaker:AWS Region:111122223333:space/your-user's-domain-id/name-of-your-user's-space" } ``` To create the application, run the following command: ``` aws sagemaker create-app \ --domain-id your-user's-domain-id \ --app-type JupyterLab \ --app-name default \ --space-name name-of-your-user's-space \ --resource-spec "InstanceType=instance-type,SageMakerImageArn=arn:aws:sagemaker:AWS Region:555555555555:image/sagemaker-distribution-resource-identifier" ``` # Delete unused resources To avoid incurring additional costs running JupyterLab, we recommend deleting unused resources in the following order: 1. JupyterLab applications 1. Spaces 1. User profiles 1. domains Use the following AWS Command Line Interface (AWS CLI) commands to delete resources within a domain: ------ #### [ Delete a JupyterLab application ] ``` aws --region AWS Region sagemaker delete-app --domain-id example-domain-id --app-name default --app-type JupyterLab --space-name example-space-name ``` ------ #### [ Delete a space ] **Important** If you delete a space, you delete the Amazon EBS volume associated with it. We recommend backing up any valuable data before you delete your space. ``` aws --region AWS Region sagemaker delete-space --domain-id example-domain-id --space-name example-space-name ``` ------ #### [ Delete a user profile ] ``` aws --region AWS Region sagemaker delete-user-profile --domain-id example-domain-id --user-profile example-user-profile ``` ------ # Quotas JupyterLab, has quotas for the following: + The sum of all Amazon EBS volumes within an AWS account. + The instance types that are available for your users. + The number of instances for a particular that your users can launch. To get more storage and compute for your users, request an increase to your AWS quotas. For more information about requesting a quota increase, see [Amazon SageMaker AI endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/sagemaker.html).