Skip to content

Workbench on Astrolift (AWS)

The Calliope AI Workbench inside Astrolift. The Workbench hub runs as pods pinned to the tenant cluster's on-demand anchor node, user servers run as pods on the Spot pool, homes live on EFS, sign-in goes through Cognito, and the hub is reached through Astrolift's load balancer. There is no hub task, no Workbench load balancer and no second Aurora cluster.

On AWS this card joins infrastructure that already exists. The Workbench creates a DNS zone of its own while Astrolift answers on one it is handed, so the wizard withdraws "Create a dedicated stack" for this pair: Astrolift adopts a VPC, ECS cluster, Aurora cluster and load balancer already in the account, and the Workbench uses those through Astrolift. In an account with none of them, install each product on its own instead.

Not yet validated end to end

Written from the installer source as of release 0.1.57. No step on this page has been run end to end on a clean AWS account yet. Read the known blockers first. The Workbench cluster runtime has been certified on a local kind cluster only, with a stand-in hub image; the real hub image, the EFS CSI mount, IRSA, Cognito sign-in, the load balancer rule and the peering to an adopted Workbench's VPC have not run on real EKS.

What you need

The common prerequisites, the existing infrastructure, and these values for What we need from you:

Group Field Notes
Deployment Deployment name Must differ from any Workbench deployment name already in the account
Admin email The first Workbench account; the invitation is sent here
Image registry Where the Workbench images are pulled from, for example 123456789012.dkr.ecr.us-west-2.amazonaws.com
DNS Domain, Hosted zone ID The zone dedicated to this deployment
Workbench hostname Workbench subdomain Optional; the hub answers on hub.<domain> by default
Network VPC ID, Private subnet IDs Required; Public subnet IDs optional
Container cluster ECS cluster Required
Database Cluster identifier, Cluster writer endpoint, Master credentials secret ARN The Aurora cluster Astrolift creates its databases inside
Load balancer and certificate Load balancer ARN, HTTPS listener ARN, Certificate ARN Astrolift attaches host rules to that listener

The adoptable values are, one for one, the outputs of an existing Workbench ECS deployment. The optional group "Workbench on the Astrolift cluster: adopt an existing Workbench" takes an existing Workbench's EFS, Cognito pool and client, hub secret and database instead of creating new ones; leave it empty for a new Workbench. The plan opens the adopted file system's mount target group on NFS (2049) and the adopted database's group on 5432 to the cluster's nodes. When either sits in a VPC other than the one Astrolift joins, the plan peers that VPC to Astrolift's and routes only between the two VPCs' CIDRs; same account and region only, and overlapping CIDRs are refused. The peering needs ec2:CreateVpcPeeringConnection, ec2:AcceptVpcPeeringConnection, ec2:ModifyVpcPeeringConnectionOptions and ec2:DeleteVpcPeeringConnection in the credentials the Deployment Manager runs under. A role made by the installer's bootstrap holds them only from the bootstrap version that added them (on CloudFormation, the stack's fifth policy part), so run the current bootstrap again for a role made before that.

Capacity must be on-demand, or Spot with the on-demand anchor; the hub never runs on Spot.

Choose it

  1. Choose what to install: Workbench on Astrolift.
  2. Pick the cloud: AWS and a region.
  3. Pick a footprint.
  4. Review the drawing: the card sets "What the products share" to Share everything and "Where the Workbench runs" to On the Astrolift tenant cluster. "Network and database" resolves to reuse. Keep "Tenant runtime" on Create a cluster; otherwise the Workbench falls back to its own ECS runtime.
  5. Fill in the values, review Before we start, and finish setup.

The card resolves to two units: Calliope AI Workbench on the Astrolift cluster (state workbench-cluster.tfstate) and Astrolift.

Apply

Astrolift adds no rules to the security groups of the Aurora cluster and load balancer it joins, and the Workbench unit adds rules only to the groups named under "adopt an existing Workbench"; the rest belong to their owner. Before you deploy, make sure the adopted Aurora cluster admits connections on TCP 5432 from inside the VPC (for example a rule for the VPC's CIDR): Astrolift's services, its database bootstrap at the end of its apply, the tenant nodes and the hub's database job all connect to it.

On Install, Astrolift first:

  1. Dry run Plan Astrolift, read the plan, Deploy it. Its apply records eks_cluster_name, eks_oidc_provider_arn, eks_node_security_group_id, eks_anchor_node_group_name and alb_security_group_id (empty when the load balancer is adopted).
  2. Let the adopted load balancer reach the hub: add a rule to the tenant nodes' security group (eks_node_security_group_id) admitting the load balancer's security group on TCP 30808, the hub's NodePort. The Workbench unit adds this rule only for a load balancer Astrolift created.
  3. Dry run Plan Calliope AI Workbench on the Astrolift cluster. It is refused, by name, until step 1 has been recorded. Expect one target group, one listener rule, one listener certificate, one DNS record, one Auto Scaling attachment, the EFS CSI add-on and its role, the file system policy, the IRSA role <deployment>-workbench-hub, the namespace and bootstrap namespace, hub-secrets, the volume and claim efs-shared-pvc, the hub-public NodePort service and the junohub release. Adopting a file system or database adds its rule on the adopted group, and one in another VPC adds the peering connection and routes both ways. Deploy it.

The cluster fetches the hub's Helm chart from hub.jupyter.org during the apply, so the nodes need that egress.

Verify

curl -fsS https://hub.<domain>/hub/health

The tenant cluster's API is private by default; from inside the VPC, with the AWS identity that applied the install:

aws eks update-kubeconfig --name <deployment>-astrolift --region <region>
kubectl -n calliopeai get pod -l component=hub -o wide

The hub pod runs on the anchor node and the hub's target group shows the anchor healthy. https://hub.<domain> signs in through Cognito with the admin account; spawning a lab starts a jupyter-<user> pod on a Spot node with its home under homes/<user> on EFS.

First app and first agent run

On Astrolift, as in Astrolift standalone.

Undo

Teardown enforces the order: Calliope AI Workbench on the Astrolift cluster first; Astrolift is refused while it stands. Then Astrolift. The VPC, ECS cluster, Aurora cluster, load balancer, listener and certificate you supplied are kept, as is the hosted zone; remove the security group rules you added yourself. Then remove the state store and the Deployment Manager as in Undo.