Summary

Our installation procedure involves using the Google Cloud Console to provision a Kubernetes Cluster, and a few IAM accounts and roles. The installation then generates kubernetes yaml which will be applied to that cluster. We can walk you through the installation yourself, or you can create an IAM user with the required permissions and send us the access credentials. We will then manage Saturn for you

Requirements

  • A machine with Docker.
  • A Google Cloud Platform account that has sufficient permissions to create IAM users and roles, Kubernetes Clusters, Storage Buckets, and Cloud Registries.

Steps

  1. Prep our installation working directory.
    mkdir /tmp/install
            
  2. Create a kubernetes cluster. Navigate to the kubernetes engine page of GCP and click on Create Cluster

    You will be taken to the following form

    You can choose whatever name you want for the Name (we will choose saturn-cluster). Select Zonal for Location Type, and enter the zone of the VPC or Subnet you wish to connect to. Then click More Options under the default node pool so we can enable autoscaling.

    To start with, we recommend 1 Node, with a min pool size of 1 and a max pool size of 10. We also recommend bumping the machine type to have 4 vCPUs. Make sure you click save at the bottom.

    Now at the bottom of the cluster form click on Availability, networking, security, and additional features . Under Network, Select the network for your VPC, as well as the appropriate Subnet.

  3. Create a service account for Saturn. Navigate to the service account page of the GCP Console. Click on Create Service Account at the top of the page. In the form, choose a name for the service account, saturn-admin. You should grant the role of Storage Object Admin. At step 3, please click on Create Key and select JSON. Save the key to /tmp/install/gcp.json

  4. Setup the Container Registry. Activate the Container Registry API. Then we have to push an image to the registry in order to create a storage bucket.

    docker pull registry:2
    docker push gcr.io/${project-id}/registry:2
              

  5. Setup Google Cloud Storage permissions. Navigate to the Cloud Storage browser. You should see a bucket for the docker registry. artifacts.${project_id}.appspot.com Click the menu button on the right of the bucket in order to edit bucket permissions.

    Click on Add Member, Select the service account we just created, and assign the role of Storage Object Admin

    Create a new bucket for Saturn. Choose a name like saturn-data, and select Zonal, and choose the region for your kubernetes cluster. You don't need to add permissions here, we can do that on the previous screen just like before. Again, add the service account as Storage Object Admin

  6. write the configuration file to /tmp/install/gcp-config.yaml
    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: "gcr.io/${project-id}"
    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}"
            


    admin_email - Your email address.
    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 - the bucket to store data.
    name-of-GCR-docker-host - Name of GCR host for your account. For example ours is gcr.io/saturn-onprem.
    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.

  7. Install Saturn in to the resulting Kubernetes cluster.
    Create kubernetes yaml:
    docker run -v /tmp/install:/root saturncloud/saturn-gcp:2.0 python main.py kube /root/config.yaml
            

    Authenticate with the kubernetes cluster
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "gcloud container clusters get-credentials ${cluster-name}"
            
    Install nginx ingress, the cluster autoscaler, and Saturn into kubernetes
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl apply -f /root/kube/cluster-autoscaler"
            
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl apply -f /root/kube/nginx-ingress"
            
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl apply -f /root/kube/saturn"
            
  8. 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-gcp:2.0 /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   33.24.64.1   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
    33.24.64.1
  9. 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.