Installation (Kubernetes)

Saturn Cloud can be installed on any Kubernetes cluster using the saturn-helm-operator. This guide covers installing on a cluster you already manage, without any cloud-specific Terraform or wrapper charts.

Prerequisites

• A running Kubernetes cluster (v1.28+) with kubectl access
• Helm 3 installed

1. Register Your Organization

Register with Saturn Cloud to receive provisioning credentials. Use cloud=k0rdent for generic Kubernetes installations:

curl -X POST https://manager.saturnenterprise.io/api/v2/customers/register \
    -H "Content-Type: application/json" \
    -d '{
      "name": "your-organization-name",
      "email": "your-email@example.com",
      "cloud": "k0rdent"
    }'

2. Activate Your Account

You will receive an activation email with a token. Activate using:

curl -X POST https://manager.saturnenterprise.io/v2/activate \
    -H "Content-Type: application/json" \
    -d '{"token": "YOUR_ACTIVATION_TOKEN"}'

Or use the activation link in the email directly.

After activation, you will receive a sample values.yaml containing a bootstrap API token and default configuration values.

curl -X POST https://manager.saturnenterprise.io/v2/resend-setup \
    -H "Content-Type: application/json" \
    -d '{
      "name": "your-organization-name",
      "email": "your-email@example.com"
    }'

3. Prepare Your Cluster

Before installing, your cluster needs some configuration.

Node Scheduling

The operator accepts nodeSelector and tolerations configuration for both system components and user workloads. These are optional. If omitted, Kubernetes schedules based on resource requests alone.

Node labels and selectors are useful when you want explicit control over placement, for example keeping the Saturn Cloud control plane on CPU-only nodes and off expensive GPU nodes. A typical setup:

# Label nodes for system components
kubectl label node <node-name> node.saturncloud.io/role=system

# Optionally taint them so only system pods land there
kubectl taint node <node-name> node.saturncloud.io/role=system:NoSchedule

If you configure node selectors, set them in your values.yaml:

nodeScheduling:
  nodeSelector:
    node.saturncloud.io/role: "system"
  tolerations:
  - key: "node.saturncloud.io/role"
    operator: "Equal"
    value: "system"
    effect: "NoSchedule"

For user workloads, each entry in instanceConfig.sizes maps to Kubernetes resource requests/limits and an optional node_role that becomes a node selector. If you omit node_role, scheduling is based purely on resource requests, and Kubernetes places the pod on any node with sufficient capacity.

GPU Nodes (Optional)

GPU nodes are not required for initial installation. You can add them later. When adding GPU nodes:

• Install NVIDIA device drivers and the NVIDIA device plugin (or set saturnComponents.clusterSetup.values.nvidiaDevicePluginEnabled: true in your values to let Saturn Cloud deploy it)
• Optionally label GPU nodes if you want to use node selectors for GPU instance sizes

4. Install the Operator

Add the Saturn Cloud Helm repository and install the operator using your values.yaml:

helm repo add saturncloud https://charts.saturnenterprise.io
helm repo update

Edit the sample values.yaml you received during activation. The key values to customize:

createNamespaces: true

# Required: your cluster
clusterName: "my-cluster"
cloudProvider: "k0rdent"
region: "us-east-1"
availabilityZone: "us-east-1"       # can match region if your cluster has no distinct AZs

# From activation
bootstrapToken: "your-bootstrap-token"

# These are derived from your organization name during registration.
# Your installation will be hosted at <orgname>.saturnenterprise.io
domain: "my-org.saturnenterprise.io"
adminEmail: "admin@example.com"
customerName: "my-org"
baseUrl: "https://app.my-org.saturnenterprise.io"
sshDomain: "ssh.my-org.saturnenterprise.io"

# Disable node selectors if you don't use node labels
nodeScheduling:
  nodeSelector: null
  tolerations: null

# Instance sizes available to users
instanceConfig:
  default_cpu: cpu-large
  default_gpu: ""
  sizes:
  - name: cpu-large
    cores: 4
    memory: 16Gi
    gpu: 0
    display_name: "CPU Large (4 vCPU, 16GB)"
    node_role: cpu-large
  - name: cpu-2xlarge
    cores: 16
    memory: 64Gi
    gpu: 0
    display_name: "CPU 2XLarge (16 vCPU, 64GB)"
    node_role: null
    node_affinity_config: []

Your installation will be hosted at <orgname>.saturnenterprise.io. SSL termination and DNS are handled automatically through the bootstrap token mechanism.

Each instanceConfig.sizes entry defines the CPU and memory resource requests for that instance size. Placement is controlled by two optional fields:

• node_affinity_config: a full Kubernetes node affinity expression, giving you complete control over scheduling
• node_role: if node_affinity_config is omitted, Saturn Cloud constructs a node.saturncloud.io/role node selector from this value

If both are omitted, Kubernetes schedules based on resource requests alone.

Install:

helm install saturn saturncloud/saturn-helm-operator \
    -f values.yaml \
    --namespace saturn-system \
    --create-namespace

Next Steps

• Operations: Upgrades, failure modes, and day-to-day operations
• Customization: Customize node pools, deploy additional services, integrate with existing tools
• Admin Guide: Invite users, manage groups, monitor resources, run reports