Summary

Our installation procedure is a series of commands executed inside a docker container. We can walk you through the installation yourself, or create an IAM user with the required permissions and send us the access credentials. We will then manage Saturn for you. The installation generates terraform yaml which provisions an EKS cluster in your AWS account, and then generates kubernetes yaml which will be applied to that cluster.

Requirements

  • A machine with Docker
  • An AWS account that has access to the following permissions
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "admin",
                "Effect": "Allow",
                "Action": [
                    "iam:*",
                    "ec2:*",
                    "autoscaling:*",
                    "eks:*"
                ],
                "Resource": "*"
            },
            {
                "Sid": "s3",
                "Effect": "Allow",
                "Action": "s3:*",
                "Resource": ["arn:aws:s3:::saturn*/*", "arn:aws:s3:::saturn*"]
            },
            {
                "Sid": "ecr",
                "Effect": "Allow",
                "Action": "ecr:*",
                "Resource": "arn:aws:ecr:*:*:repository/saturn*"
            }
        ]
    }
            

Steps

  1. write the configuration file
    region: "${cloud-region}"
    vpc_id: "${vpc-id}"
    public_subnets:
      - "${public-subnet-id1}"
      - "${public-subnet-id2}"
    private_subnets:
      - "${private-subnet-id1}"
      - "${private-subnet-id2}"
    worker_subnets:
      - "${saturn-private-subnet-id}"
    worker_zones:
      - "${saturn-zone}"
    worker_groups:
      - name: medium
        asg_min_size: 1
        asg_max_size: 5
        asg_desired_capacity: 1
        instance_type: t3.medium
      - name: xl
        asg_min_size: 0
        asg_max_size: 5
        asg_desired_capacity: 0
        instance_type: t3.xlarge
    sizes:
      - display: 'Micro - 0.5 cores - 1 GB RAM'
        cores: [0.5, 1.0]
        memory: ['750M', '1G']
        name: 'micro'
      - display: 'Medium - 2 cores - 4 GB RAM'
        cores: [0.5, 2.0]
        memory: ['3G', '4G']
        name: 'medium'
    disk_space:
      - name: "3G"
      - name: "20G"
      - name: "60G"
    saturn_bucket_name: "${saturn-data-bucket-name}"
    docker_host: "${name-of-ECR-docker-host}"
    domain: "${saturn-domain}"
    use_ssl: False
    admin_email: ${admin_email}"
    smtp_info:
      host: smtp.mailgun.org
      port: 587
      user: "${smtp-email-address}"
      password: "${smtp-password}"
    license_id: "${license-id}"
            

    EKS requires at least 2 zone - however Saturn generally uses only 1 zone. Saturn persists user home directories in EBS, which is limited to a single zone, so high availability does not help. For the configuration, we need the VPC id, and public and private subnet ids for each zone in your VPC. You also need to pick a specific zone for Saturn.

    cloud-region - The region your saturn installation will run in. For example, we typically run in us-east-2.
    admin_email - Your email address.
    vpc-id - The ID of the VPC you wish to install Saturn into.
    public-subnet-id[1-3] - The ID of the public subnets in your VPC
    private-subnet-id[1-3] - The ID of the private subnets in your VPC
    saturn-private-subnet-id - The ID of the private subnet that you want for Saturn
    saturn-zone - The zone of saturn-private-subnet-id
    worker_groups - The workers you wish to use for Saturn. The example uses 2 worker groups. The desired capacity of the first group should be 1.
    sizes - The size of Jupyter instances users get access to. cores and memory are expressed as upper and lower bounds. These do not have to match up identically with the worker groups, however if you have memory and cpu requests here that exceed your largest worker size, they won't be runnable
    disk_space - Choices for home directory size in Saturn
    saturn-data-bucket-name - Saturn provision an s3 bucket to store data.
    name-of-ECR-docker-host - Name of ECR host for your account. For example ours is 369111250314.dkr.ecr.us-east-2.amazonaws.com
    saturn-domain - The domain you want to host Saturn. For example, if you choose saturn.yourcompany.com, Saturn will run on app.saturn.yourcompany.com, JupyterHub will run on main.saturn.yourcompany.com, and an anonymous JupyterHub(for publishing) will run on anon.saturn.yourcompany.com
    smtp-email-address, smtp-password, license-id - We will give you these values. If you would like - we can configure this such that you use your own smtp server, however by default we manage smtp for you.

    After completeing the configuration file, please create a directory, /tmp/install and write the configuration file into that location as /tmp/install/config.yaml

  2. Provision AWS resources Please create a directory on your machine /tmp/install, and copy the aws config that has sufficient credentials into /tmp/intall/.aws

    To create terraform yaml, please execute:
    docker run -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 python main.py cluster /root/config.yaml
            
    This sets up terraform yaml in /tmp/install/terraform
    To provision the EKS cluster, please execute the following. It may take 10 minutes to complete:
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "cd /root/terraform/cluster; terraform init; terraform apply ."
            
    At this point we strongly recommend that you create a git repository with the contents of /tmp/install/terraform You will need this later if you wish to tear down these resources, or update them
  3. Install Saturn in to the resulting Kubernetes cluster.
    Create kubernetes yaml:
    docker run -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 python main.py kube /root/config.yaml
            

    Authenticate with the kubernetes cluster
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "aws eks update-kubeconfig --name saturn-cluster"
            
    Install nginx ingress, the cluster autoscaler, and Saturn into kubernetes
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "kubectl apply -f /root/kube/cluster-autoscaler"
            
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "kubectl apply -f /root/kube/nginx-ingress"
            
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "kubectl apply -f /root/kube/cluster"
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "kubectl apply -f /root/kube/saturn"
            
  4. Finish DNS settings. The above steps will create a load balancer where Saturn Cluster will listen to http requests. Execute
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.5.5 /bin/sh -c "kubectl get service saturn-nginx-ingress-controller"
            
    The output will look like
    NAME                              TYPE           CLUSTER-IP   EXTERNAL-IP                                                               PORT(S)                      AGE
    saturn-nginx-ingress-controller   LoadBalancer   172.20.9.4   a17cbfc63860211e9a80906e394062ec-1742857715.us-east-2.elb.amazonaws.com   80:31009/TCP,443:30353/TCP   32s
            
    Then add a wildcard CNAME dns entry for the domain you decided to use for Saturn. In our case, that is:
    *.saturn.yourcompany.com
    mapping to
    a17cbfc63860211e9a80906e394062ec-1742857715.us-east-2.elb.amazonaws.com
  5. Add users You should receive an email to reset the password of the admin account admin . Please reset the password, and then login to Saturn. Once you are logged in, please login to the admin panel (it should be under /admin/setup, but there should be a link on the side of your dashboard). Here you can create new users. They will each get password reset requests.