Schedule your notebooks from any JupyterLab surroundings utilizing the Amazon SageMaker JupyterLab extension

Jupyter notebooks are extremely favored by knowledge scientists for his or her means to interactively course of knowledge, construct ML fashions, and check these fashions by making inferences on knowledge. Nevertheless, there are situations wherein knowledge scientists might desire to transition from interactive growth on notebooks to batch jobs. Examples of such use circumstances embrace scaling up a characteristic engineering job that was beforehand examined on a small pattern dataset on a small pocket book occasion, working nightly reviews to achieve insights into enterprise metrics, and retraining ML fashions on a schedule as new knowledge turns into out there.

Migrating from interactive growth on notebooks to batch jobs required you to repeat code snippets from the pocket book right into a script, package deal the script with all its dependencies right into a container, and schedule the container to run. To run this job repeatedly on a schedule, you needed to arrange, configure, and oversee cloud infrastructure to automate deployments, leading to a diversion of precious time away from core knowledge science growth actions.

To assist simplify the method of transferring from interactive notebooks to batch jobs, in December 2022, Amazon SageMaker Studio and Studio Lab launched the aptitude to run notebooks as scheduled jobs, utilizing notebook-based workflows. Now you can use the identical functionality to run your Jupyter notebooks from any JupyterLab surroundings reminiscent of Amazon SageMaker pocket book cases and JupyterLab working in your native machine. SageMaker gives an open-source extension that may be put in on any JupyterLab surroundings and be used to run notebooks as ephemeral jobs and on a schedule.

On this put up, we present you tips on how to run your notebooks out of your native JupyterLab surroundings as scheduled pocket book jobs on SageMaker.

Resolution overview

The answer structure for scheduling pocket book jobs from any JupyterLab surroundings is proven within the following diagram. The SageMaker extension expects the JupyterLab surroundings to have legitimate AWS credentials and permissions to schedule pocket book jobs. We focus on the steps for establishing credentials and AWS Identity and Access Management (IAM) permissions later on this put up. Along with the IAM person and assumed position session scheduling the job, you additionally want to offer a job for the pocket book job occasion to imagine for entry to your knowledge in Amazon Simple Storage Service (Amazon S3) or to connect with Amazon EMR clusters as wanted.

Within the following sections, we present tips on how to arrange the structure and set up the open-source extension, run a pocket book with the default configurations, and in addition use the superior parameters to run a pocket book with customized settings.

Stipulations

For this put up, we assume a domestically hosted JupyterLab surroundings. You possibly can observe the identical set up steps for an surroundings hosted within the cloud as nicely.

The next steps assume that you have already got a sound Python 3 and JupyterLab surroundings (this extension works with JupyterLab v3.0 or larger).

Set up the AWS Command Line Interface (AWS CLI) if you happen to don’t have already got it put in. See Installing or updating the latest version of the AWS CLI for directions.

Arrange IAM credentials

You want an IAM person or an energetic IAM position session to submit SageMaker pocket book jobs. To arrange your IAM credentials, you possibly can configure the AWS CLI together with your AWS credentials in your IAM person, or assume an IAM position. For directions on establishing your credentials, see Configuring the AWS CLI. The IAM principal (person or assumed position) wants the next permissions to schedule pocket book jobs. So as to add the coverage to your principal, check with Adding IAM identity permissions.

{
    "Model": "2012-10-17",
    "Assertion": [
        {
            "Sid": "EventBridgeSchedule",
            "Effect": "Allow",
            "Action": [
                "events:TagResource",
                "events:DeleteRule",
                "events:PutTargets",
                "events:DescribeRule",
                "events:EnableRule",
                "events:PutRule",
                "events:RemoveTargets",
                "events:DisableRule"
            ],
            "Useful resource": "*",
            "Situation": {
                "StringEquals": {
                    "aws:ResourceTag/sagemaker:is-scheduling-notebook-job": "true"
                }
            }
        },
        {
            "Sid": "IAMPassRoleToNotebookJob",
            "Impact": "Enable",
            "Motion": "iam:PassRole",
            "Useful resource": "arn:aws:iam::*:position/SagemakerJupyterScheduler*",
            "Situation": {
                "StringLike": {
                    "iam:PassedToService": [
                        "sagemaker.amazonaws.com",
                        "events.amazonaws.com"
                    ]
                }
            }
        },
        {
            "Sid": "IAMListRoles",
            "Impact": "Enable",
            "Motion": "iam:ListRoles",
            "Useful resource": "*" 
        },
        {
            "Sid": "S3ArtifactsAccess",
            "Impact": "Enable",
            "Motion": [
                "s3:PutEncryptionConfiguration",
                "s3:CreateBucket",
                "s3:PutBucketVersioning",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:GetObject",
                "s3:GetEncryptionConfiguration",
                "s3:DeleteObject",
                "s3:GetBucketLocation"
            ],
            "Useful resource": [
                "arn:aws:s3:::sagemaker-automated-execution-*"
            ]
        },
        {
            "Sid": "S3DriverAccess",
            "Impact": "Enable",
            "Motion": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:GetBucketLocation"
            ],
            "Useful resource": [
                "arn:aws:s3:::sagemakerheadlessexecution-*"
            ]
        },
        {
            "Sid": "SagemakerJobs",
            "Impact": "Enable",
            "Motion": [
                "sagemaker:DescribeTrainingJob",
                "sagemaker:StopTrainingJob",
                "sagemaker:DescribePipeline",
                "sagemaker:CreateTrainingJob",
                "sagemaker:DeletePipeline",
                "sagemaker:CreatePipeline"
            ],
            "Useful resource": "*",
            "Situation": {
                "StringEquals": {
                    "aws:ResourceTag/sagemaker:is-scheduling-notebook-job": "true"
                }
            }
        },
         {
            "Sid": "AllowSearch",
            "Impact": "Enable",
            "Motion": "sagemaker:Search",
            "Useful resource": "*"
        },
         {
            "Sid": "SagemakerTags",
            "Impact": "Enable",
            "Motion": [
                "sagemaker:ListTags",
                "sagemaker:AddTags"
            ],
            "Useful resource": [
                "arn:aws:sagemaker:*:*:pipeline/*",
                "arn:aws:sagemaker:*:*:space/*",
                "arn:aws:sagemaker:*:*:training-job/*",
                "arn:aws:sagemaker:*:*:user-profile/*"
            ]
        },
        {
            "Sid": "ECRImage",
            "Impact": "Enable",
            "Motion": [
                "ecr:GetAuthorizationToken",
                "ecr:BatchGetImage"
            ],
            "Useful resource": "*"
        }
   ]
}

In case your pocket book jobs have to be encrypted with buyer managed AWS Key Management Service (AWS KMS) keys, add the coverage assertion permitting AWS KMS entry as nicely. For a pattern coverage, see Install policies and permissions for local Jupyter environments.

Arrange an IAM position for the pocket book job occasion

SageMaker requires an IAM position to run jobs on the person’s behalf, reminiscent of working the pocket book job. This position ought to have entry to the sources required for the pocket book to finish the job, reminiscent of entry to knowledge in Amazon S3.

The scheduler extension robotically appears to be like for IAM roles within the AWS account, with the prefix SagemakerJupyterScheduler to run the pocket book jobs.

To create an IAM position, create an execution role for Amazon SageMaker with the AmazonSageMakerFullAccess coverage. Identify the position SagemakerJupyterSchedulerDemo, or present a reputation with the anticipated prefix.

After the position is created, on the Belief relationships tab, select Edit belief coverage. Change the present belief coverage with the next:

{
    "Model": "2012-10-17",
    "Assertion": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "sagemaker.amazonaws.com",
                    "events.amazonaws.com"
                ]
            },
            "Motion": "sts:AssumeRole"
        }
    ]
}

The AmazonSageMakerFullAccess coverage is pretty permissive and is usually most popular for experimentation and getting began with SageMaker. We strongly encourage you to create a minimal scoped coverage for any future workloads in accordance with safety finest practices in IAM. For the minimal set of permissions required for the pocket book job, see Install policies and permissions for local Jupyter environments.

Set up the extension

Open a terminal in your native machine and set up the extension by working the next command:

pip set up amazon-sagemaker-jupyter-scheduler

After this command runs, you can begin JupyterLab by working jupyter lab.

For those who’re putting in the extension from throughout the JupyterLab terminal, restart the Jupyter server to load the extension. You possibly can restart the Jupyter server by selecting Shut Down on the File menu out of your JupyterLab, and beginning JupyterLab out of your command line by working jupyter lab.

Submit a pocket book job

After the extension is put in in your surroundings, you possibly can run any self-contained pocket book as an ephemeral job. Let’s submit a easy “Good day world” pocket book to run as a scheduled job.

1. On the File menu, select New and Pocket book.
2. Enter the next contents:

   # set up packages
   !pip set up pandas
   !pip set up boto3
   
   # import block
   import boto3
   import pandas as pd
   
   # obtain a pattern dataset
   s3 = boto3.consumer("s3")
   # Load the dataset
   file_name = "abalone.csv"
   s3.download_file(
       "sagemaker-sample-files", f"datasets/tabular/uci_abalone/abalone.csv", file_name
   )
   
   # show the dataset
   df = pd.read_csv(file_name)
   df.head()

After the extension is efficiently put in, you’ll see the pocket book scheduling icon on the pocket book.

3. Select the icon to create a pocket book job.
   

Alternatively, you possibly can right-click on the pocket book in your file explorer and select Create pocket book job.

4. Present the job identify, enter file, compute sort, and extra parameters.
5. Go away the remaining settings on the default and select Create.
   
   

After the job is scheduled, you’re redirected to the Pocket book Jobs tab, the place you possibly can view the record of pocket book jobs and their standing, and examine the pocket book output and logs after the job is full. You can even entry this pocket book jobs window from the Launcher, as proven within the following screenshot.

Superior configurations

Out of your native compute, notebooks robotically run on the SageMaker Base Python picture, which is the official Python 3.8 picture from Docker Hub with Boto3 and the AWS CLI included. In real-world circumstances, knowledge scientists want to put in particular packages or frameworks for his or her notebooks. There are 3 ways to attain a reproducible surroundings:

• On the easiest possibility, you possibly can set up the packages and frameworks straight on the primary cell of your pocket book.
• You can even present an initialization script within the Further choices part, pointing to a bash script in your native storage that’s run by the pocket book job when the pocket book begins up. Within the following part, we present an instance of utilizing initialization scripts to put in packages.
• Lastly, if you need most flexibility in configuring your run surroundings, you possibly can construct your personal customized picture with a Python3 kernel, push the picture to Amazon Elastic Container Registry (Amazon ECR), and supply the ECR picture URI to your pocket book job beneath Further choices. The ECR picture ought to observe the necessities for SageMaker photographs, as listed in Custom SageMaker image specifications.

As well as, your enterprise may arrange guardrails like working jobs in internet-free mode inside an Amazon VPC, utilizing a customized least-privilege position for the job, and implementing encryption. You possibly can specify such configurations in your pocket book jobs within the Further choices part as nicely. For an in depth record of superior configurations, see Additional options.

Add an initialization script

To showcase the initialization script, we now run the pattern pocket book for Studio pocket book jobs out there on GitHub. To run this pocket book, you’ll want to set up the required packages via an initialization script. Full the next steps:

1. Out of your JupyterLab terminal, run the next command to obtain the file:

   curl https://uncooked.githubusercontent.com/aws/amazon-sagemaker-examples/most important/sagemaker-notebook-jobs/studio-scheduling/scheduled-example.ipynb > scheduled-example.ipynb

2. On the File menu, select New and Textual content file.
3. Enter the next contents to your file, and save the file beneath the identify init-script.sh:

   echo "Putting in required packages"
   
   pip set up --upgrade sagemaker
   pip set up pandas numpy matplotlib scikit-learn

4. Select scheduled-example.ipynb out of your file explorer to open the pocket book.
5. Select the pocket book job icon to schedule the pocket book, and broaden the Further choices part.
6. For Initialization script location, enter the complete path of your script.
   

You can even optionally customise the enter and output S3 folders in your pocket book job. SageMaker creates an enter folder in a specified S3 location to retailer the enter recordsdata, and creates an output S3 folder the place the pocket book outputs are saved. You possibly can specify encryption, IAM position, and VPC configurations right here. See Constraints and considerations for customized picture and VPC specs.

7. For now, merely replace the initialization script, select Run now for the schedule, and select Create.

When the job is full, you possibly can view the pocket book with outputs and the output log beneath Output recordsdata, as proven within the following screenshot. Within the output log, it’s best to be capable of see the initialization script being run earlier than working the pocket book.

To additional customise your pocket book job surroundings, you should utilize your personal picture by specifying the ECR URI of your customized picture. For those who’re bringing your personal picture, make sure you set up a Python3 kernel when constructing your picture. For a pattern Dockerfile that may run a pocket book utilizing TensorFlow, see the next code:

FROM tensorflow/tensorflow:newest
RUN pip set up ipykernel && 
        python -m ipykernel set up --sys-prefix

Conclusion

On this put up, we confirmed you tips on how to run your notebooks from any JupyterLab surroundings hosted domestically as SageMaker coaching jobs, utilizing the SageMaker Jupyter scheduler extension. Having the ability to run notebooks in a headless method, on a schedule, enormously reduces undifferentiated heavy lifting for the info scientists, reminiscent of refactoring notebooks to Python scripts, establishing Amazon EventBridge occasion triggers, and creating AWS Lambda features or SageMaker pipelines to start out the coaching jobs. SageMaker pocket book jobs are run on demand, so that you solely pay for the time that the pocket book is run, and you should utilize the pocket book jobs extension to view the pocket book outputs anytime out of your JupyterLab surroundings. We encourage you to strive scheduled pocket book jobs, and join with the Machine Learning & AI community on re:Post for suggestions!

In regards to the authors

Bhadrinath Pani is a Software program Growth Engineer at Amazon Net Companies, engaged on Amazon SageMaker interactive ML merchandise, with over 12 years of expertise in software program growth throughout domains like automotive, IoT, AR/VR, and pc imaginative and prescient. At the moment, his most important focus is on growing machine studying instruments aimed toward simplifying the expertise for knowledge scientists. In his free time, he enjoys spending time together with his household and exploring the great thing about the Pacific Northwest.

Durga Sury is an ML Options Architect on the Amazon SageMaker Service SA crew. She is enthusiastic about making machine studying accessible to everybody. In her 4 years at AWS, she has helped arrange AI/ML platforms for enterprise prospects. When she isn’t working, she loves bike rides, thriller novels, and lengthy walks along with her 5-year-old husky.