Skip to content

Configuring RStudio Server Pro with Launcher and Kubernetes

Info

Launcher is a new feature of RStudio Server Pro 1.2 that is only available under named user licensing. RStudio Server Pro 1.2 without Launcher is available under existing server-based licensing. For questions about using Launcher with RStudio Server Pro, please contact sales@rstudio.com.

Overview

These steps represent a minimal configuration of RStudio Server Pro with Launcher and Kubernetes.

Prerequisites

  • RStudio Server Pro 1.2 or higher
  • NFS server that is configured with RStudio Server Pro for home directory project storage
  • Kubernetes cluster
    • Kubernetes API endpoint
    • Kubernetes cluster CA certificate
    • Access to kubectl to create namespaces, service accounts, cluster roles, and role bindings
  • Access to Docker image registry (if working within an offline environment)

Pre-Flight Configuration Checks

Verifying active Kubernetes worker nodes - On a machine with kubectl configured, ensure that you have one or more worker nodes that are ready to accept pods as part of the Kubernetes cluster by running the following command:

Terminal

$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
ip-172-31-12-54.ec2.internal Ready <none> 90d v1.11.5
ip-172-31-15-141.ec2.internal Ready <none> 90d v1.11.5
ip-172-31-18-59.ec2.internal Ready <none> 90d v1.11.5
ip-172-31-20-112.ec2.internal Ready <none> 90d v1.11.5

Verifying functionality with a test deployment - On a machine with kubectl configured, ensure that you are able to deploy a sample application to your Kubernetes cluster by running the following command:

Terminal

$ kubectl create deployment hello-node --image=gcr.io/google-samples/node-hello:1.0

And confirm that the pod is running by using the following command:

Terminal

$ kubectl get pods
NAME READY STATUS RESTARTS AGE
hello-node-6d6cd9679f-mllr7 1/1 Running 0 1m

Then, you can clean up the test deployment by running the following command:

Terminal

$ kubectl delete deployment hello-node
deployment.extensions "hello-node" deleted

1. Configure RStudio Server Pro with Launcher

Add the following lines to the RStudio Server Pro configuration file:

File: /etc/rstudio/rserver.conf

# Launcher Config
launcher-address=127.0.0.1
launcher-port=5559
launcher-sessions-enabled=1
launcher-default-cluster=Kubernetes
launcher-sessions-callback-address=http://<SERVER-ADDRESS>:8787
launcher-sessions-container-run-as-root=0
launcher-sessions-create-container-user=1

In the launcher-sessions-callback-address setting, you should replace <SERVER-ADDRESS> with the DNS name or IP address of RStudio Server Pro. You should also change the protocol and port if you are using HTTPS or a different port.

The <SERVER-ADDRESS> needs to be reachable from the containers in Kubernetes to the instance of RStudio Server Pro.

2. Configure Launcher settings and plugins

Add the following lines to the Launcher configuration file:

File: /etc/rstudio/launcher.conf

[server]
address=127.0.0.1
port=5559
server-user=rstudio-server
admin-group=rstudio-server
authorization-enabled=1
thread-pool-size=4
enable-debug-logging=1

[cluster]
name=Kubernetes
type=Kubernetes

3. Configure profile for Launcher Kubernetes plugin

Add the following lines to the Launcher profiles configuration file:

File: /etc/rstudio/launcher.kubernetes.profiles.conf

[*]
default-cpus=1
default-mem-mb=512
max-cpus=2
max-mem-mb=1024
container-images=rstudio/r-session-complete:centos7-1.2.1335-1-r-3.5.3
default-container-image=rstudio/r-session-complete:centos7-1.2.1335-1-r-3.5.3
allow-unknown-images=0

For more information on using Docker images with Launcher, refer to the support article on Using Docker images with RStudio Server Pro, Launcher, and Kubernetes.

4. Provision and configure NFS server

a) Provision an NFS server that exports the /home directory. We recommend configuring an NFS server on a machine that runs separately from RStudio Server Pro and Launcher.

b) On the machine with RStudio Server Pro and Launcher, mount the NFS share at /home.

RStudio Server Pro stores project data for each user in their respective home directory. Shared home directory storage via NFS is required for configurations of RStudio Server Pro and Launcher. Additional NFS mounts can be used with Launcher to make read-only or read-write shared data storage available within the containers.

Similar to any NFS configuration, all machines (e.g., the machine with the NFS server and the machine with RStudio Server Pro and Launcher) should have the same users with matching user IDs and group IDs to avoid permission or ownership issues across NFS client machines.

5. Configure NFS mounts for Launcher

Add the following lines to the Launcher mounts configuration file, which is the NFS server and mount path that will be used by the containers to mount the home directory for each user:

File: /etc/rstudio/launcher-mounts

# Home directory mount for RSP, Launcher, and Kubernetes
Host: <NFS-IP-ADDRESS>
Path: /home/{USER}
MountPath: /home/{USER}
ReadOnly: false
Cluster: Kubernetes

Replace <NFS-IP-ADDRESS> with the IP address of your NFS server. The Path and MountPath contain the special variable {USER} to indicate that the user’s name will be substituted when the container starts, so there is no need to change that variable in this configuration file.

6. Create Kubernetes resources for Launcher sessions and jobs

Run the following commands in a terminal to create the rstudio namespace and required service account, cluster role, and role bindings:

Terminal

$ kubectl create namespace rstudio
$ kubectl create serviceaccount job-launcher --namespace rstudio
$ kubectl create rolebinding job-launcher-admin \
    --clusterrole=cluster-admin \
    --group=system:serviceaccounts:rstudio \
    --namespace=rstudio
$ kubectl create clusterrole job-launcher-clusters \
    --verb=get,watch,list \
    --resource=nodes
$ kubectl create clusterrolebinding job-launcher-list-clusters \
    --clusterrole=job-launcher-clusters \
    --group=system:serviceaccounts:rstudio
$ kubectl create clusterrole job-launcher-api \
    --verb=impersonate \
    --resource=users,groups,serviceaccounts
$ kubectl create rolebinding job-launcher-impersonation \
    --clusterrole=job-launcher-api \
    --group=system:serviceaccounts:rstudio \
    --namespace=rstudio

7. Configure Launcher with Kubernetes

Obtain the Kubernetes token for the service account in the rstudio namespace by running the following command in your terminal:

Terminal

$ kubectl get secret $(kubectl get serviceaccount job-launcher --namespace=rstudio -o jsonpath='{.secrets[0].name}') --namespace=rstudio -o jsonpath='{.data.token}' | base64 -d

Add the following lines to the Launcher Kubernetes configuration file:

File: /etc/rstudio/launcher.kubernetes.conf

api-url=<KUBERNETES-API-ENDPOINT>
auth-token=<KUBERNETES-CLUSTER-TOKEN>

where <KUBERNETES-API-ENDPOINT> is the URL for the Kubernetes API, and <KUBERNETES-CLUSTER-TOKEN> is the Kubernetes service account token from the previous step in this section.

8. Configure Kubernetes CA Certificate

Add the Kubernetes CA certificate for your cluster to /usr/share/pki/ca-trust-source/anchors/launcher.crt (on RHEL/CentOS) or /usr/local/share/ca-certificates/launcher.crt (on Ubuntu).

Ensure that the certificate is not base64 encoded and that it starts with -----BEGIN CERTIFICATE-----.

Run the following command in a terminal to add the Kubernetes CA certificate to the system certificate chain:

$ sudo update-ca-trust
$ sudo update-ca-certificates

9. Restart RStudio Server Pro and Launcher Services

Terminal

$ sudo rstudio-server restart
$ sudo rstudio-launcher restart

10. Test RStudio Server Pro with Launcher and Kubernetes

Run the following command to test the installation and configuration of RStudio Server Pro with Launcher and Kubernetes:

Terminal

$ sudo rstudio-server stop
$ sudo rstudio-server verify-installation --verify-user=<USER>
$ sudo rstudio-server start

Replace <USER> with a valid username of a user that is setup to run RStudio Server Pro in your installation. You only need to run this test once for one valid user to verify that RStudio Server Pro and Launcher can successfully communicate with Kubernetes and start sessions/jobs.

Refer to the Troubleshooting section in the RStudio Server Pro Administration Guide for more information on using the Launcher verification tool.

Perform Additional Configuration

For more information on configuring RStudio Server Pro and Launcher, including configuring additional shared file storage mounts, environment variables, and ports, refer to the following reference documentation:

Troubleshooting RStudio Server Pro and Launcher

Refer to the support article on Troubleshooting Launcher in RStudio Server Pro for additional information on troubleshooting RStudio Server Pro with Launcher and Kubernetes.