Deploying Saturn Cloud on a Managed Service for Kubernetes® cluster

​

Costs

• Managed Kubernetes nodes
• Compute disks
• Shared filesystem
• Object Storage bucket

​

Prerequisites

1. You need this role because the deployment adds service accounts to the editors and viewers groups of your tenant.
2. Install and configure the Nebius AI Cloud CLI.
3. Install Terraform 1.8 or later. The recipe uses provider functions that earlier versions of Terraform don’t support.
4. Install kubectl. Terraform uses kubectl to move the system components of the cluster to the system nodes.
5. Install jq to extract IDs from the JSON data returned by the Nebius AI Cloud CLI.
6. Generate an SSH key pair.

​

Steps

​

Sign up in Saturn Cloud

1. Go to the Saturn Cloud registration page.
2. Specify the following settings:
   • Organization Name: Name of your organization in Saturn Cloud. The name becomes part of your Saturn Cloud domain. For example, if the name is my-team, the domain is my-team.saturnenterprise.io.
   • Email Address: Email address of the Saturn Cloud administrator.
   • Cloud Provider: Nebius.
3. Click Create Account.
4. Open the activation email from Saturn Cloud. This email includes a command that activates your account—run this command. After that, Saturn Cloud sends the second email with the setup instructions and the terraform.tfvars file. The file contains the configuration of your Saturn Cloud installation, including a bootstrap token. Only download the file from this email. Don’t create a repository based on the instructions in the email. You’ll use the saturncloud-reference-terraform repository instead.

curl -X POST https://manager.saturnenterprise.io/v2/resend-setup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<organization_name>",
    "email": "<email_address>"
  }'

​

Prepare infrastructure

1. Clone the Saturn Cloud reference Terraform repository and go to the nebius directory:
   git clone https://github.com/saturncloud/saturncloud-reference-terraform.git
   cd saturncloud-reference-terraform/nebius
   
2. Replace the terraform.tfvars file in the nebius directory with the file from the Saturn Cloud email.
3. Add the path of your public SSH key to terraform.tfvars, for example:
   ssh_public_key = {
     path = "~/.ssh/id_ed25519.pub"
   }
   
   The nodes of the cluster use this key. If you don’t add the path, Terraform uses ~/.ssh/id_rsa.pub, and terraform apply fails if id_rsa.pub doesn’t exist.
4. Save the IDs of your tenant and project, and the region of the project, to environment variables:
   export NEBIUS_TENANT_ID=<tenant_ID>
   export NEBIUS_PROJECT_ID=<project_ID>
   export NEBIUS_REGION=<region>
   
   For more information, see:
   • How to get a tenant ID
   • How to get a project ID
   • List of regions
   The setup email asks you to set a region in terraform.tfvars. You don’t need to do this because the environment.sh script sets the region from the NEBIUS_REGION environment variable.
5. In the nebius directory of the cloned repository, run the environment.sh script:
   source ./environment.sh
   
   The script creates the following resources:
   • The saturn-cloud-sa service account in the editors group of your tenant.
   • A bucket for the Terraform state, with versioning enabled.
   • An access key of the service account, so that Terraform can access the bucket. The access key expires after one day.
   The script also saves the values that Terraform needs to environment variables. For example, it saves an IAM access token, which expires after 12 hours, and the ID of the first subnet in your project, which the cluster uses. The first time you run the script, it shows an error that the saturn-cloud-sa service account is not found. You can ignore this error because the script creates the service account right after this check.

​

Deploy Saturn Cloud and Nebius AI Cloud resources

1. (Optional) If you want to change the configuration of the node groups (for example, the region doesn’t support the default gpu-h200-sxm Compute platform), uncomment and adjust the node_pools parameter in the terraform.tfvars file. Thus, Terraform only creates node groups with configuration from this parameter. In node_pools, in terraform.tfvars:
   • Preserve the group with the cpu-d3 platform and the 4vcpu-16gb preset because Saturn Cloud builds images on these nodes.
   • Replace the gpu-h200-sxm platform with the required one, if needed.
   • If you don’t need nodes with eight GPUs, remove the group with the 8gpu-128vcpu-1600gb preset. If you keep it, specify an InfiniBand™ fabric in the infiniband_fabric parameter.
   For the supported values of the platforms and presets, see the nebius/validation.tf file.
2. (Optional) If you want to change the size of the shared filesystem, add the filestore_disk_size_gibibytes parameter to terraform.tfvars and set the size in GiB.
3. To use up-to-date versions of resources and to make sure that the resources are created successfully, update the following files in the repository:
   • In the provider.tf file, in provider "nebius", set the following contents:
     domain = "api.nebius.cloud:443"
     default_labels = {
       "msp.nebius.com/skypilot-context-name" = "saturn-cluster"
     }
     
     If provider "nebius" already includes some contents, replace them with the lines above.
   • In the terraform.tf file, in required_providers.nebius, update source and version to the following:
     source  = "nebius/nebius"
     version = ">= 0.6.8"
     
   • In the terraform.tfvars file, specify an up-to-date Kubernetes version: k8s_version = "<version>". To get the up-to-date version, see Available Kubernetes versions.
   • In the nebius/mk8s.tf file, add the following contents to the nebius_mk8s_v1_cluster resource:
     lifecycle {
       ignore_changes = [labels]
     }
     
4. Initialize Terraform in the working directory:
   terraform init
   
5. Apply the changes:
   terraform apply
   
   Terraform creates the following resources in your project in Nebius AI Cloud:
   • Managed Kubernetes cluster with a group of system nodes and the node groups from node_pools.
   • Shared filesystem.
   • Service account that the nodes use to pull images from Container Registry.
   You can check these resources in the web console. Terraform creates the resources. After that, Saturn Cloud installs its components in the Managed Kubernetes cluster. The resource creation and component installation can take about 15 minutes in total. When the installation is complete, Saturn Cloud sends a welcome email to the administrator’s email address.

​

Log in to Saturn Cloud

1. Open the welcome email from Saturn Cloud and follow the link for resetting a password. The link expires in 4 hours.
   If the browser shows that the website can’t be found, the DNS record for your Saturn Cloud domain isn’t available yet. Wait 15 minutes and try again.
2. On this website, set the password of the admin user. After that, the Saturn Cloud dashboard opens automatically.

​

Test the deployment

1. On the Dashboard page, click Create a resource.
2. On the Instance Size step, select the values that correspond to your configuration:
   • Cloud: Nebius.
   • GPU Type and Memory: should correspond to the preset in the Terraform manifest. For example, if you specify the 1gpu-16vcpu-200gb preset in node_pools, in terraform.tfvars, select the H200 GPU type and the 200Gi memory.
   After that, select the suggested configuration and click Next.
3. On the Resource Type step, select New Python Server and click Next.
4. On the Details step, specify a name for the workspace in the Name field and click Create Resource.
5. On the workspace page that opens, click Start. Wait until the status of the workspace changes to Running. The cluster first adds a node for the workspace, so the workspace can take a few minutes to start.
6. Click Jupyter Lab.
7. In JupyterLab, create a notebook and run the following code:
   import os
   print(os.cpu_count())
   
   The output is the number of vCPUs in the preset of the node group that you selected.
8. Stop the workspace in Saturn Cloud. Close the JupyterLab window and then click Stop on the workspace page. In the window that opens, click Yes to confirm the action.

​

How to delete the created resources

1. On the workspace page in Saturn Cloud, click Delete to delete the workspace. In the window that opens, click Yes to confirm the action.
2. Go to the nebius directory of the cloned repository and run the environment.sh script again:
   export NEBIUS_TENANT_ID=<tenant_ID>
   export NEBIUS_PROJECT_ID=<project_ID>
   export NEBIUS_REGION=<region>
   source ./environment.sh
   
   Terraform reads the project and subnet IDs, the IAM access token, and the access key to the bucket with the Terraform state from environment variables that the script sets. These variables exist only in the terminal session where you ran the script, and the token and the key expire. The script sets the variables again.
3. Get the ID of the Managed Kubernetes cluster:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK
   • REST API

   nebius mk8s cluster get-by-name \
     --name saturn-cluster \
     --format jsonpath='{.metadata.id}'
   

   clusterService := sdk.Services().MK8S().V1().Cluster()
   cluster, err := clusterService.GetByName(
       ctx,
       &common.GetByNameRequest{
           Name: "saturn-cluster",
       },
   )
   if err != nil {
       return err
   }
   fmt.Println(cluster.GetMetadata().GetId())
   

   cluster_service = ClusterServiceClient(sdk)
   cluster = await cluster_service.get_by_name(
       GetByNameRequest(name="saturn-cluster"),
   )
   print(cluster.metadata.id)
   

   const clusterService = new ClusterService(sdk);
   const cluster = await clusterService.getByName(
     GetByNameRequest.create({
       name: "saturn-cluster",
     }),
   );
   console.log(cluster.metadata?.id);
   

   curl --request GET \
     --url 'https://api.nebius.cloud/mk8s/v1/clusters/get-by-name' \
     --get \
     --data-urlencode "parentId=<project_ID>" \
     --data-urlencode "name=saturn-cluster" \
     --header "Authorization: Bearer <access_token>" \
     | jq -r '.metadata.id'
   
   Save the received ID. The disks of the workspaces have the cluster ID in their labels. After Terraform deletes the cluster, use this ID to find these disks.
4. Delete the resources that Terraform created:
   terraform destroy
   
   The command can fail with the Error uninstalling release error. In this case, run the command again.
5. Get the IDs of the disks that the cluster created for Saturn Cloud workspaces:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK
   • REST API

   nebius compute disk list \
     --format json \
     | jq -r --arg CLUSTER_ID "<cluster_ID>" '.items[]?
       | select(.metadata.labels["compute.csi.nebius.com/cluster-id"] == $CLUSTER_ID)
       | .metadata.id'
   

   diskService := sdk.Services().Compute().V1().Disk()
   clusterLabel := "compute.csi.nebius.com/cluster-id"
   disks, err := diskService.List(
       ctx,
       &compute.ListDisksRequest{
           ParentId: "<project_ID>",
       },
   )
   if err != nil {
       return err
   }
   for _, disk := range disks.GetItems() {
       labels := disk.GetMetadata().GetLabels()
       if labels[clusterLabel] == "<cluster_ID>" {
           fmt.Println(disk.GetMetadata().GetId())
       }
   }
   

   disk_service = DiskServiceClient(sdk)
   cluster_label = "compute.csi.nebius.com/cluster-id"
   disks = await disk_service.list(
       ListDisksRequest(parent_id="<project_ID>"),
   )
   for disk in disks.items:
       if (
           disk.metadata.labels.get(cluster_label)
           == "<cluster_ID>"
       ):
           print(disk.metadata.id)
   

   const diskService = new DiskService(sdk);
   const clusterLabel = "compute.csi.nebius.com/cluster-id";
   const disks = await diskService.list(
     ListDisksRequest.create({
       parentId: "<project_ID>",
     }),
   );
   for (const disk of disks.items) {
     if (
       disk.metadata?.labels[clusterLabel]
       === "<cluster_ID>"
     ) {
       console.log(disk.metadata?.id);
     }
   }
   

   curl --request GET \
     --url 'https://api.nebius.cloud/compute/v1/disks' \
     --get \
     --data-urlencode "parentId=<project_ID>" \
     --header "Authorization: Bearer <access_token>" \
     | jq -r --arg CLUSTER_ID "<cluster_ID>" '.items[]?
       | select(.metadata.labels["compute.csi.nebius.com/cluster-id"] == $CLUSTER_ID)
       | .metadata.id'
   
6. Delete the disks with these IDs.
7. Delete the bucket that stores the Terraform state. Its name starts with tfstate-saturn-cloud-.
8. Delete the service account saturn-cloud-sa. Nebius AI Cloud also deletes its access keys and removes it from the editors group.

​

See also

• Installation (Nebius) in Saturn Cloud documentation