Jupyter Deploy AWS EKS OIDC template

The AWS EKS OIDC Template deploys JupyterLab workspaces on an Amazon EKS cluster, with HTTPS, GitHub OAuth via Dex, and the Jupyter K8s operator for workspace lifecycle management.

Multiple users get isolated workspaces with persistent storage, idle shutdown, and role-based access control — all managed through jupyter-deploy.

Documentation: jupyter-deploy.readthedocs.io

The AWS EKS OIDC Template is maintained and supported by AWS.

10k View

When a user navigates to the deployment URL, they authenticate via GitHub through a Dex OIDC flow. Once authenticated, the Jupyter K8s operator provisions a workspace pod on the cluster with a dedicated persistent volume. Traefik routes HTTPS traffic to the workspace, and an authmiddleware component validates JWT session cookies on every request.

Administrators use jupyter-deploy to monitor cluster health, manage workspaces, and inspect platform components — without needing direct Kubernetes access.

Prerequisites

AWS account

The template creates AWS resources (VPC, EKS cluster, node groups, IAM roles, ECR, Route 53 records). Your local environment needs access to valid AWS credentials.

If you do not have an AWS account, follow the official guide to create one.

If you already have an AWS account, make sure your CLI credentials are configured.

Get and register a domain

The template serves workspace URLs under a subdomain of your own domain. You will need to specify this domain when you configure the project.

If you already own a domain, register it with Amazon Route 53 using this guide.

If you do not own a domain yet, you can buy one through Amazon Route 53 using this guide.

Setup a GitHub OAuth app

The template gates access with GitHub identities. You grant access to GitHub teams, which must belong to your GitHub organization.

If you do not have a GitHub organization, you can create one using this guide.

Note: A personal app also works, but the organization may require third-party application approval before it can read private membership.

Next, create a new OAuth app:

• for your organization: Settings → Developer settings → OAuth Apps → New OAuth App
• for a personal app, log on to GitHub in your web browser, then use this link.

See the GitHub documentation for details.

Next, configure your OAuth app:

Finally, save the client ID, generate a client secret, and save that too. You will need them to run jd config.

Note: The callback URL uses /dex/callback (not /oauth2/callback as in the base template), because authentication goes through Dex as the OIDC identity provider. It must match your <subdomain> and <domain> exactly.

Usage

Installation

Recommended: create or activate a Python virtual environment.

uv add "jupyter-deploy[aws,k8s]" jupyter-deploy-tf-aws-eks-oidc

Or with pip:

pip install "jupyter-deploy[aws,k8s]" jupyter-deploy-tf-aws-eks-oidc

jupyter-deploy also needs these tools installed locally; jd config prompts you to install any that are missing: Terraform (>= 1.5.7), the AWS CLI, kubectl, Helm and yq.

Project setup

mkdir my-eks-deployment
cd my-eks-deployment

jd init . -E terraform -P aws -I eks -T oidc

Configure and deploy

jd config
jd up

The first deployment takes approximately 25-30 minutes.

User interface

# open the web UI
jd open

# configure kubectl to access your cluster
jd cluster login

Manage user workspaces

# list all workspaces
jd server list

# check workspace status
jd server status --name my-workspace --scope default

# open a running workspace in your web browser
jd open --server-name my-workspace --scope default

# stop/start a workspace
jd server stop --name my-workspace --scope default
jd server start --name my-workspace --scope default

# view workspace logs
jd server logs --name my-workspace --scope default

# open an interactive shell
jd server connect --name my-workspace --scope default

Manage cluster

# aggregated health check
jd health

# cluster control plane status
jd cluster status

# configure local kubeconfig
jd cluster login

Manage components

# health dashboard for all platform components
jd health --components

# list the platform components
jd component list

# view component logs
jd component logs --name dex

# restart a component (deployment only)
jd component restart --name oauth2-proxy

# reconcile a component (HelmRelease only; re-asserts desired state)
jd component reconcile --name workspace-router-chart

Take down

This operation removes all the resources associated with this project in your AWS account.

jd down

Architecture

Cluster and networking

The template creates a VPC with public and private subnets across two availability zones. EKS nodes run in private subnets; the Network Load Balancer (NLB) sits in public subnets and forwards HTTPS/443 to Traefik pods. Amazon Route 53 manages DNS via external-dns. Public TLS terminates at the NLB with an ACM certificate and is re-encrypted to Traefik, which presents a certificate from a private CA that cert-manager mints in the cluster.

Platform components

The platform layer handles routing, authentication, and workspace lifecycle:

• Traefik — Ingress controller and reverse proxy
• Dex — OIDC identity provider (federates to GitHub)
• OAuth2 Proxy — Handles sign-in flow for unauthenticated users
• Authmiddleware — Validates JWT session cookies via ForwardAuth
• Jupyter K8s operator — Reconciles Workspace CRDs into Deployments and persistent volumes

Authentication flow

Authentication uses a two-path model:

Browser access — OAuth2 Proxy redirects unauthenticated requests through Dex to GitHub. After authentication, Authmiddleware issues a JWT session cookie. Authmiddleware validates subsequent requests by checking the JWT directly.

CLI access — jd cluster login configures kubeconfig with an EKS exec-based auth provider using AWS IAM credentials, bypassing the OIDC flow entirely.

Compute

Three kinds of node pool, each dedicated to a different job and each with its own autoscaling policy:

• platform — EKS managed node group for the control-plane pods (operator, Karpenter, KEDA, cert-manager, external-dns); the Cluster Autoscaler sizes it
• routing — Karpenter pool for the ingress and auth tier (Traefik, Dex, OAuth2 Proxy, Authmiddleware, web UI); always on, and grows with the KEDA-scaled routing pods
• workspace pools — Karpenter pools for user workspace pods, one per workspace_nodepools entry plus an optional GPU pool; these scale to zero

A single jupyter-deploy/role Kubernetes label drives pod placement: every node carries it, and every pod selects its tier through a matching nodeSelector. The Karpenter pools carry the role as a taint as well, so a pod without the matching toleration can never land on them; the platform node group stays untainted. The platform node group auto-detects its AMI type from the instance family (CPU, GPU, Neuron; x86_64 or arm64).

Storage

Each workspace gets a dedicated EBS persistent volume mounted at /home/jovyan. Data persists across workspace stop/start cycles and pod restarts.

Custom workspace images

The template optionally creates ECR repositories and a CodeBuild project for building custom workspace images from Dockerfiles in the applications/ directory.

Details

Networking

The template creates a VPC with public and private subnets across two availability zones. EKS nodes run in private subnets; the Network Load Balancer (NLB) sits in public subnets and forwards HTTPS/443 to Traefik pods.

Amazon Route 53 manages DNS. The template references a Hosted Zone for your domain (which must already exist) and relies on external-dns to create DNS records pointing your subdomain to the NLB.

TLS

Public TLS terminates at the NLB with an AWS Certificate Manager (ACM) certificate that the template requests for <subdomain>.<domain> and validates via DNS against your hosted zone.

The NLB then re-encrypts to Traefik, so nothing crosses the VPC in plaintext. Traefik presents a certificate from a private CA that cert-manager mints inside the cluster; the NLB does not verify it, so it needs no public trust. cert-manager therefore makes no AWS API calls and holds no IAM role.

The NLB registers only nodes labeled jupyter-deploy/role=routing as targets, matching where Traefik runs.

Compute

The template creates a single platform EKS managed node group for control-plane-only pods, and Karpenter NodePools for the routing and workspace tiers. The managed node group auto-detects the appropriate EKS-optimized AMI type for its instance type; Karpenter nodes use the al2023@latest AMI alias.

Application Images

The template creates infrastructure for building custom workspace images:

• ECR repository — One repository per application type. Stores the built container images.
• CodeBuild project — Builds Dockerfiles from the applications/ directory and pushes to ECR.
• IAM role — CodeBuild service role with permissions for ECR push and CloudWatch Logs.

IAM

The template creates several IAM roles:

• Cluster role — The EKS control plane assumes this role
• Node roles — One per node group, with managed policies for ECR pull, EKS worker nodes, and CNI
• Pod identity associations — external-dns uses EKS Pod Identity for Route 53 access
• Admin access entries — The template always authorizes the caller's IAM principal. Roles in admin_role_names and users in admin_user_names get cluster admin and workspace admin permissions. For stable state across caller switches, list every role/user that may run jd config or jd up
• Workspace Bedrock roles — One per workspace namespace with Bedrock access, bound to the namespace's workspace service account through EKS Pod Identity, so Claude Code and Codex work in workspaces with no setup

Helm charts

RBAC

The template deploys a github-rbac local chart that creates namespace-scoped Role and RoleBinding resources. Each workspace namespace gets a Role granting workspace CRUD permissions, which a RoleBinding ties to its GitHub teams: with workspace_namespaces empty, default is the only workspace namespace and binds every team in oauth_allowed_teams; otherwise each entry creates a namespace (or adopts default) bound to the entry's teams only. Every oauth_allowed_teams team also gets a read-only (get/list) Role in workspace_shared_namespace for discovering shared WorkspaceTemplate and WorkspaceAccessStrategy resources.

Presets

The template provides two variable presets:

• defaults-all.tfvars — comprehensive preset with all recommended values
• defaults-base.tfvars — minimal preset that additionally prompts for node group configuration

Inputs

Outputs

License

The AWS EKS OIDC Template is licensed under the MIT License.