Notebooks as Controllers

Last updated on 2026-11-02 | Edit this page

Overview

Questions

  • How do you set up and use SageMaker notebooks for machine learning tasks?
  • How can you manage compute resources efficiently using SageMaker’s controller notebook approach?

Objectives

  • Explain why the lesson works from a SageMaker notebook instance, and what the controller pattern is.
  • Create a tagged notebook instance on a small instance type, open the lesson notebooks in it, and stop it when done.

Setting up our notebook environment

In this episode we set up the SageMaker notebook instance that every later episode runs from.

What a SageMaker notebook instance is

A SageMaker notebook instance is a virtual machine that AWS runs for you with JupyterLab already installed, a set of Python kernels that come with the AWS SDKs (boto3 and the SageMaker Python SDK), and an IAM role attached that decides what the code running on it may do in your account. You create it from the console and open JupyterLab in a browser tab. Compute is billed per second while it is running and not while it is stopped. The instance’s disk is separate: the files you keep under /home/ec2-user/SageMaker/ survive a stop, and that storage volume keeps billing at about $0.14 per GB-month (about $2.80 a month for the 20 GB this lesson asks for) until the instance is deleted.

Using the notebook as a controller

The notebook instance is a controller: a small, cheap machine where you write code and use the SageMaker Python SDK to launch larger instances for model training, batch processing, and hyperparameter tuning. Those instances start, run your script, write their results to S3, and shut themselves down, so you pay for powerful hardware only for the minutes a job needs it.

Diagram from the overview episode: S3 buckets at the top, the notebook instance on the left launching SageMaker training, tuning and processing jobs, and Bedrock on the right
The notebook instance launches jobs and calls Bedrock; S3 holds the data and the outputs

The notebook is the box on the left of the diagram from the overview episode. Everything else in the picture is launched or called from it, and every later episode uses this same instance.

Why we work from a notebook instance in this lesson

The SageMaker SDK runs anywhere Python does, so the lesson could be run from a laptop. We use a notebook instance for four reasons:

  • No credential setup. The IAM role attached to the instance authorizes every call made from it, so there is nothing to install or log in to. Working from a laptop is not hard, aws configure sso and aws sso login take a few minutes, but in a room of a hundred people that is a hundred setups, plus SSO sessions expiring mid-episode and the occasional person pasting an access key instead. The role sidesteps all of it.
  • Everyone has the same environment. The kernels, the SDK version and the paths are identical for every learner, so a cell that works for the instructor works for you.
  • Instructors can see what happened. Every notebook instance in the shared account shows up in the console, and an instructor can open yours and see the notebook that launched a job, with its outputs. Jobs launched from a laptop are just as visible in the job list, but the code that launched them is on your machine, so when something breaks or a charge looks wrong there is less to go on.
  • No egress charges. AWS bills data transfer when it leaves AWS, not when it moves within a region. The notebook instance sits in the same region as your bucket, so reading or downloading files from S3 to the instance is free. Pulling the same files to a laptop is a transfer out of AWS, $0.09 per GB, wherever the laptop is: “region” means the AWS data center your resources live in, and a machine outside AWS is never in one.

We’ll follow these steps to create our first “SageMaker notebook instance”.

  • In the AWS Console, search for SageMaker.
  • Recommended: Select the star icon next to Amazon SageMaker AI to save SageMaker as a bookmark in your AWS toolbar
  • Select Amazon SageMaker AI

2. Create a new notebook instance

  • In the SageMaker left-side menu, click on Notebook instances, then click Create notebook instance.

  • Notebook name: the same words as your bucket, capitalized: Challenge-LastnameFirstname, e.g. SinkOrSwim-DoeJohn. One instance serves the whole workshop; the individual .ipynb notebooks inside it are where the per-episode work lives. SageMaker allows letters, digits and hyphens (no spaces or underscores, up to 63 characters); capitals are fine here and in tags, only bucket names must be lowercase. The Titanic episodes reuse this name as the prefix of their training jobs, which is how you find your jobs in a shared account.

  • Instance type: sets the CPU, memory and price of the virtual machine. Our notebook is a controller, so pick a small one: ml.t3.medium (2 vCPU, 4 GB RAM, $0.05/hour). The jobs we launch from it will run on more powerful instances; the supplemental Instances for ML page compares them.

  • Platform identifier: leave the default.

  • Additional configuration: holds the Volume size in GB of the instance’s persistent disk, default 5 GB. Expand it and set 20 GB: the RAG episodes unpack about a gigabyte of PDFs and page images, the fine-tuning episode keeps its data here, and 5 GB fills up on the second run. The disk is the one thing a stopped instance keeps billing for, $0.14 per GB-month, so 20 GB is $2.80 a month until the instance is deleted. Do not go larger than that without a reason, and the reason is rarely your dataset. The disk only has to hold what the notebook itself opens. A dataset a training job reads stays in S3 and is copied onto the job’s own instance, which has its own disk, set per job, so a 50 GB dataset needs no change here. What cannot go through this notebook at all is anything bigger than its memory, 4 GB on an ml.t3.medium. The Accessing S3 episode says what to do with a file that size, and the Instances for ML page sizes the job instances by dataset. If the disk does fill, stop the instance, choose Edit, and raise the volume size. It can grow, not shrink.

  • Permissions and encryption:

    • IAM role: Select ml-sagemaker-use. It is pre-configured for this workshop with access to SageMaker and, for the RAG episodes, Bedrock, with some restrictions to prevent overuse or misuse of resources; ml-sagemaker-bedrock-use, if the list offers it, is the same thing. Outside of the workshop, you create or select a role that includes the AmazonSageMakerFullAccess policy and, for Bedrock, the policy in the Account preparation checklist instructor page.
    • Root access: leave the default. pip install into the kernels needs no root; root is for system packages, which nothing in the lesson installs.
    • Encryption key (skip): While we won’t use this feature for the workshop, it is possible to specify a KMS key for encrypting data at rest if needed.

  • Network (skip): leave the defaults.

  • Git repositories configuration (skip): leave it empty; the lesson repository is cloned from a notebook cell below.

  • Tags (NOT OPTIONAL): the same three keys you put on your bucket, with the same values except Purpose. Tags never propagate from one resource to another, so the instance needs its own copy; the previous episode’s callout on why these keys and no others applies here too.

    Key Value
    Project your challenge, one of WattBot2026, BadgerScribe, BadgerCode, BrainDecoding, PoisonedWell, SnapshotWI, or SinkOrSwim for the workshop itself
    Name your name, e.g. DoeJohn
    Purpose what this resource is for, Notebook

    Same spelling as on the bucket. The Project and Purpose lists from the S3 episode apply to every job you launch from this instance, and a value off them is refused at the first launch; the training episode shows what that looks like and how to check first.

    Screenshot showing the three required tags on a SageMaker notebook instance
    Tag Setup Example

  • Click Create notebook instance.

Load pre-filled Jupyter notebooks

The new instance appears in the list with status Pending. It takes three to five minutes to change to InService, and the Open JupyterLab link does not appear until it does; refreshing the page does not speed it up. Starting a stopped instance later takes about as long. Once it is InService, click Open JupyterLab next to it. In JupyterLab, create a new notebook with the conda_python3 kernel (we aren’t training anything yet, so the plain Python environment is enough).

In the new notebook, run:

SH 

!pwd
!ls

The first line prints /home/ec2-user/SageMaker: new notebooks start in that folder. The second lists it: the notebook you just created, and a folder called lost+found. That folder is not yours and holds nothing: Linux puts one at the top of every formatted disk for its repair tool, and SageMaker/ is its own disk. Leave it alone. That disk is the volume whose size you set under Additional configuration on the create form (20 GB). The rest of the instance lives on the system disk and is reset when the instance stops; SageMaker/ is the only place that survives a stop. JupyterLab’s file browser opens there for that reason, and it is where everything in this lesson goes.

Now clone the lesson repository into it:

SH 

!git clone https://github.com/carpentries-incubator/ML_with_AWS_SageMaker.git

Then open ML_with_AWS_SageMaker/notebooks/04_Accessing-S3-via-SageMaker-notebooks.ipynb from the file browser to begin the first notebook.

At the end of class: stop the instance

A notebook instance bills for every second it is InService. At the end of class, go to Notebook instances, select yours and choose Stop. Your files under /home/ec2-user/SageMaker (including the repos you clone) survive a Stop and are there when you start it again; packages you pip install are not, so expect to reinstall them. When the workshop is over, Delete the instance: a stopped instance still bills for its storage volume ($0.14 per GB-month), and the cleanup episode walks through this.

Key Points
  • Use a minimal SageMaker notebook instance as a controller to manage larger, resource-intensive tasks.
  • The notebook does not do the heavy computation; later episodes use it to launch training, tuning and processing jobs on separate instances.
  • Every resource gets the same three tags; they never propagate, so each new resource needs its own.
  • Stop the notebook instance at the end of class, and delete it when the workshop is over.