Customize a SageMaker notebook instance using an LCC script - Amazon SageMaker
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Customize a SageMaker notebook instance using an LCC script

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 Resources.

Amazon Managed Policies for Amazon SageMaker that give permissions to create SageMaker resources already include permissions to add tags while creating those resources.

A lifecycle configuration (LCC) provides shell scripts that run only when you create the notebook instance or whenever you start one. When you create a notebook instance, you can create a new LCC or attach an LCC that you already have. Lifecycle configuration scripts are useful for the following use cases:

  • Installing packages or sample notebooks on a notebook instance

  • Configuring networking and security for a notebook instance

  • Using a shell script to customize a notebook instance

You can also use a lifecycle configuration script to access Amazon services from your notebook. For example, you can create a script that lets you use your notebook to control other Amazon resources, such as an Amazon EMR instance.

We maintain a public repository of notebook lifecycle configuration scripts that address common use cases for customizing notebook instances at https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples.

Note

Each script has a limit of 16384 characters.

The value of the $PATH environment variable that is available to both scripts is /usr/local/sbin:/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin. The working directory, which is the value of the $PWD environment variable, is /.

View CloudWatch Logs for notebook instance lifecycle configurations in log group /aws/sagemaker/NotebookInstances in log stream [notebook-instance-name]/[LifecycleConfigHook].

Scripts cannot run for longer than 5 minutes. If a script runs for longer than 5 minutes, it fails and the notebook instance is not created or started. To help decrease the run time of scripts, try the following:

  • Cut down on necessary steps. For example, limit which conda environments in which to install large packages.

  • Run tasks in parallel processes.

  • Use the nohup command in your script.

You can see a list of notebook instance lifecycle configurations you previously created by choosing Lifecycle configuration in the SageMaker console. You can attach a notebook instance LCC when you create a new notebook instance. For more information about creating a notebook instance, see Create an Amazon SageMaker notebook instance.

To create a lifecycle configuration
  1. Open the SageMaker console at https://console.amazonaws.cn/sagemaker/.

  2. On the left navigation pane, choose Admin configurations.

  3. Under Admin configurations, choose Lifecycle configurations.

  4. From the Lifecycle configurations page, choose the Notebook Instance tab.

  5. Choose Create configuration.

  6. For Name, type a name using alphanumeric characters and "-", but no spaces. The name can have a maximum of 63 characters.

  7. (Optional) To create a script that runs when you create the notebook and every time you start it, choose Start notebook.

  8. In the Start notebook editor, type the script.

  9. (Optional) To create a script that runs only once, when you create the notebook, choose Create notebook.

  10. In the Create notebook editor, type the script configure networking.

  11. Choose Create configuration.