To energy up AI workflows on Amazon Elastic Kubernetes Service (Amazon EKS), knowledge scientists want interactive IDEs like JupyterLab and Code Editor. But operating these IDEs often means leaving the cluster that hosts their pipelines, shifting to a standalone JupyterHub deployment or a neighborhood laptop computer. That change leaves them with out the GPU nodes, shared storage, and AWS Id and Entry Administration (IAM) roles their pipelines rely on. The Amazon SageMaker AI Areas add-on for Amazon EKS closes that hole. It runs managed JupyterLab and Code Editor environments on the cluster that you just already function. Standing up a standalone JupyterHub surroundings with GPU entry, storage, and authentication usually takes a platform group 3–5 days. With the add-on, an information scientist launches a completely configured Area in about 5 minutes.
On this publish, you put in the SageMaker AI Areas add-on on an Amazon EKS cluster. You arrange the supporting add-ons and IAM roles, deploy the AWS Load Balancer Controller, request a TLS certificates, and create an AWS Key Administration System (AWS KMS) encryption key. You then create your first Area and attain it via a presigned URL within the browser and from VS Code over SSH-over-SSM. Lastly, you overview find out how to transfer your group to OpenID Join (OIDC) sign-in with Amazon Cognito.
Answer overview
The answer runs on a single EKS cluster in three layers:
Consolidating interactive and coaching workloads on one cluster retains GPU nodes busy between jobs. This could elevate GPU utilization by as much as 30 p.c in contrast with a devoted pocket book fleet. It additionally avoids the price of an always-on GPU surroundings, which may run into 1000’s of {dollars} a month.
Determine 1: Answer structure
Conditions
To observe alongside, you want an AWS account with the AWS Command Line Interface (AWS CLI) 2.x or later configured in your goal AWS Area, plus kubectl 1.30 or later and Helm v3. You additionally want a Route 53 public hosted zone for a website you personal, referenced as all through this publish, and IAM permissions to create roles, insurance policies, EKS add-ons, entry entries, Pod Id associations, ACM certificates, and KMS keys. The Areas add-on should be model 0.1.4 or later, as a result of earlier variations supported Amazon SageMaker HyperPod solely.
Determine 2: Route 53 hosted zone with validation information
Set these variables as soon as. The remainder of the publish reuses them.
Each IAM position on this publish is assumed by a Kubernetes service account via EKS Pod Id, so all of them share one belief coverage. Put it aside as soon as and reuse it:
Notice: This walkthrough creates assets that incur AWS prices: an internet-facing ALB, EBS volumes, and an EKS cluster. SSM advanced-instances tier provides about $0.00695/hr per Area pod. Observe the Cleanup part once you end.
Create the EKS cluster
Cluster creation itself follows the usual EKS getting began information. What issues right here is assembly 4 Areas-specific necessities. Maintain EKS Auto Mode disabled, as a result of the add-on requires basic EC2-backed nodes on Kubernetes 1.30 or later. Use a digital non-public cloud (VPC) with private and non-private subnets throughout a minimum of two Availability Zones, with a NAT gateway serving the non-public subnets, and set cluster endpoint entry to Private and non-private. Throughout creation, add the EKS Pod Id Agent, Amazon EBS CSI Driver, Cert supervisor, and Exterior DNS add-ons, however maintain off on Amazon SageMaker Areas and the AWS Load Balancer Controller. You put in these later. Lastly, create a managed node group in your non-public subnets with Amazon Linux 2023, m5.xlarge or bigger, and a couple of nodes. Skip forward in case you already run a cluster that matches.
One step is commonly neglected. Tag each subnet within the VPC so the AWS Load Balancer Controller can uncover them, and tag them earlier than you put in the Areas add-on. In any other case, the controller can place the ALB on non-public subnets, making Areas unreachable.
Arrange the inspiration
With the cluster operating, you level kubectl at it, verify the add-on pods are wholesome, and provides Exterior DNS the Route 53 permissions that it must handle DNS information.
- Configure kubectl:
Each staff report
Prepared:NAME STATUS ROLES AGE VERSION ip-10-0-1-42.ec2.inside Prepared38m v1.34.6-eks-bbe087e ip-10-0-2-96.ec2.inside Prepared 38m v1.34.6-eks-bbe087e - Affirm the system pods are wholesome throughout the add-on namespaces with
kubectl get pods -A. Each pod inkube-system,cert-manager, andexternal-dnsought to beWorkingearlier than you proceed. - Exterior DNS wants Route 53 permissions to handle information. Create the position, connect a least-privilege coverage, and bind it via Pod Id:
Safety notice: Scope every Pod Id position to minimal actions and assets. Favor express useful resource ARNs over wildcards, and make sure solely the supposed service account can assume the position.
Set up the AWS Load Balancer Controller
The AWS Load Balancer Controller provisions the ALB that fronts your Areas UI. Set up it with Helm.
- Outline the controller’s IAM coverage, position, and Pod Id affiliation:
- Set up the Helm chart. Go
vpcIdandareaexplicitly. On chart v3.2+, the controller fails if it auto-detects the VPC via EC2 metadata, which EKS blocks for pods.Each controller replicas come up:
NAME READY UP-TO-DATE AVAILABLE AGE aws-load-balancer-controller 2/2 2 2 174m
Create the certificates, key, and SSM configuration
The Areas add-on wants a TLS certificates, a KMS key for JWT encryption, and SSM service settings for distant entry.
- Request an ACM certificates masking your area and a wildcard, utilizing DNS validation, then learn again the CNAME information ACM expects:
Look ahead to the certificates standing to succeed in Issued, then copy the ARN.
Determine 3: Certificates issued for the area
Safety notice: DNS validation verifies area possession and triggers ACM computerized renewal. Maintain the validation CNAMEs in Route 53. Eradicating them breaks renewal.
- Create a KMS encryption key. The auth middleware calls
kms:GenerateDataKeyper JWT, so the important thing should be symmetricENCRYPT_DECRYPT, which is the CLI default: - Activate the SSM advanced-instances tier. Session Supervisor tunnels to hybrid managed situations, which is what VS Code distant makes use of, require this tier (about $0.00695/hr per Area pod):
Set up the Areas add-on
You create IAM roles for the Areas controller and auth middleware, then set up the add-on.
- Begin with the SSM managed-instance position that every Area pod makes use of within the SSM fleet:
- Subsequent, create the Areas controller position. It wants SSM, PassRole, and KMS permissions. Save the next coverage as
spaces-controller-policy.json, changing,, andwith your personal values:Create the position and connect the coverage:
- Bind controller and auth middleware service accounts to this position via Pod Id:
Safety notice: For tighter separation of duties, cut up this into two roles: one with SSM actions for the controller, and one with KMS encrypt and decrypt for the auth middleware.
- Outline
addon-config.yamlalong with your area, certificates ARN, key ARN, and managed-node position title: - Set up the add-on:
- Ballot till the add-on reaches
ACTIVE(about three minutes):The add-on stories
ACTIVEwith an emptypointslisting: - Affirm all Areas pods are
Working:The controller, two auth middleware replicas, and two Traefik routers ought to all be
Working:NAME READY STATUS RESTARTS AGE jupyter-k8s-controller-manager-65fcd4d67f-* 1/1 Working 0 3h13m workspace-auth-middleware-c7f7fbb6d-* 1/1 Working 0 3h13m workspace-auth-middleware-c7f7fbb6d-* 1/1 Working 0 3h13m workspace-traefik-router-755d494fbf-* 1/1 Working 0 3h13m workspace-traefik-router-755d494fbf-* 1/1 Working 0 3h13m
Grant person entry and create a Area
With the add-on wholesome, you grant a person entry to the cluster and create the primary JupyterLab Area. Entry depends on an EKS entry entry scoped to a single namespace, so customers can’t attain assets outdoors it.
- Grant entry via an EKS entry entry. Within the EKS console, navigate to your cluster’s Entry tab and select Create entry entry. Select your IAM person or position, then add
AmazonSagemakerHyperpodSpacePolicyfor thedefaultnamespace.
Determine 4: Entry entry for namespace
Safety notice: Favor namespace-scoped entry over cluster-wide insurance policies so customers can’t modify assets outdoors their namespace.
- Checklist the pre-installed Workspace templates and entry methods:
You see
sagemaker-jupyter-template,sagemaker-code-editor-template, andhyperpod-access-strategyinjupyter-k8s-system. Reference these in your Workspace reasonably than repeating configuration inline. - Outline
workspace.yamlfor a JupyterLab Area:accessType: OwnerOnlyrestricts browser entry to the IAM principal that created the Area. UsePublicfor any namespace-authorized person. - Apply and look ahead to the Area to grow to be Accessible:
workspace.workspace.jupyter.org/my-space createdFirst-time startup takes about 5 minutes. The cluster pulls the 4 GB SageMaker Distribution picture and registers the pod with SSM.
Determine 5: Area operating
Join within the browser
The Areas controller points a short-lived, presigned URL that carries the person’s encrypted token. You generate one, then navigate to it in your browser.
- Generate a short-lived presigned URL:
Discover
standing.workspaceConnectionUrlwithin the response and navigate to the URL in your browser:Safety notice: Presigned URLs carry the person’s KMS-encrypted JWT with a 5-minute expiry enforced by the
expdeclare. This worth isn’t configurable within the present add-on model. Don’t log or share presigned URLs over unencrypted channels. For sturdy entry, use VS Code distant.
Determine 6: JupyterLab on the customized area
Join from VS Code
For a neighborhood IDE expertise, VS Code connects to the Area pod via an SSM tunnel, with no browser, area, or ALB required.
- Set up VS Code, the AWS Toolkit extension, and the Session Supervisor plugin regionally.
- Generate a VS Code connection URL by creating the identical WorkspaceConnection useful resource as earlier than, with
workspaceConnectionType: vscode-remoteas a substitute ofweb-ui. This time the response carries avscode://deep hyperlink as a substitute of an HTTPS URL: - Paste the
vscode://URL into your browser. The browser prompts you to open the hyperlink in VS Code.
Determine 7: Browser opens VS Code
- Settle for the immediate. AWS Toolkit establishes an SSH-over-SSM tunnel to the Area, and VS Code attaches to the distant filesystem.
Determine 8: VS Code with distant kernel
For personal-subnet configurations and SDK alternate options, see Distant entry to SageMaker AI Areas.
Register with company credentials utilizing OIDC
Entry to date depends on IAM customers and roles. To let your group register with company credentials as a substitute, register an OIDC supplier with the cluster and bind Kubernetes role-based entry management (RBAC) to id supplier teams. Kubernetes then authorizes individuals by group membership, with no IAM principal per person.
The open supply jupyter-deploy mission ships an aws-eks-oidc template that units this up for you. Dex runs within the cluster because the OIDC supplier, Amazon EKS trusts it as an id supplier, and an online console provides your group self-service workspace administration. The template provisions its personal VPC and cluster, so run it alongside the cluster from this publish.
Determine 9: Self-managed OIDC with Amazon Cognito
The template ships a Dex connector for GitHub. Amazon Cognito works via the generic oidc connector in Dex as a substitute, and wishes two declare mappings that GitHub by no means requires. Amazon EKS reads the username from the preferred_username declare, which Cognito doesn’t situation, so map it from e-mail. Cognito additionally publishes group membership as cognito:teams reasonably than teams. Miss the username mapping and requests attain the API server with no resolvable person, and the console stories an expired session reasonably than an authorization error. The template binds its RBAC position to a bunch named , so create a Cognito group with that actual title and add your customers to it.
Your group then indicators in on the Cognito managed login web page. With a single connector configured, Dex skips the supplier chooser.
Determine 10: Cognito managed login
The console lists and creates workspaces beneath that id.
Determine 11: Self-service workspace administration
Opening one launches JupyterLab, licensed because the Cognito person.
Determine 12: JupyterLab for the Cognito person
Cleanup
To keep away from ongoing prices, delete assets in reverse order.
- Delete the Area and the add-on:
- Uninstall the Load Balancer Controller and remaining add-ons:
- Delete the IAM roles, insurance policies, and Pod Id associations you created (
ExternalDNSRole,AWSLoadBalancerControllerRole,AWSLoadBalancerControllerIAMPolicy,SageMakerSpacesControllerRole,SageMakerSpacesSSMManagedNodeRole). - Delete the certificates, schedule the KMS key for deletion (7-day minimal), and take away the Route 53 information.
- Revert the SSM advanced-instances tier to cease per-instance prices throughout the account:
- Delete the node group and EKS cluster, and delete the VPC in case you created it for this walkthrough.
Notice: Skipping these steps continues to incur prices for the EKS cluster, node group, EBS volumes, ALB, and every registered hybrid occasion on superior tier.
Conclusion
On this publish, you put in the SageMaker AI Areas add-on on an Amazon EKS cluster and configured browser and VS Code entry. You additionally noticed find out how to transfer your group to OIDC sign-in with Amazon Cognito. By consolidating interactive IDEs onto the cluster you already run, you handle one surroundings as a substitute of two and lower time-to-first-notebook from days to minutes.
To go additional, connect AWS WAF, federate further suppliers, cut up controller and auth middleware IAM roles, or set namespace-level useful resource quotas.
For associated approaches, see:
In regards to the authors

