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:
$ 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:
$ 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:
$ 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:
$ kubectl delete deployment hello-node
deployment.extensions "hello-node" deleted
Step 1) Configure RStudio Server Pro with Launcher
Add the following lines to the RStudio Server Pro configuration file (default /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://<RSP-IP-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 <RSP-IP-ADDRESS> with the IP address of RStudio Server Pro. You should also change the protocol and port if you are using HTTPS or a different port.
The <RSP-IP-ADDRESS> needs to be reachable from the containers in Kubernetes to the instance of RStudio Server Pro.
Step 2) Configure Launcher settings and plugins
Add the following lines to the Launcher configuration file (default /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=Local
type=Local
[cluster]
name=Kubernetes
type=Kubernetes
Step 3) Configure profile for Launcher Kubernetes plugin
Add the following lines to the Launcher profiles configuration file (default /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
Replace <DOCKER-IMAGE> with the Docker image to use for R sessions and jobs.
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.
Step 4) Provision and configure NFS server
Step 4a) 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.
Step 4b) 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.
Step 5) Configure NFS mounts for Launcher
Add the following lines to the Launcher mounts configuration file (default /etc/rstudio/launcher-mounts), which is the NFS server and mount path that will be used by the containers to mount the home directory for each user:
# 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.
Step 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:
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
Step 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:
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 (default /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.
Step 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:
For RHEL/CentOS:
sudo update-ca-trust
For Ubuntu:
sudo update-ca-certificates
Step 9) Restart RStudio Server Pro and Launcher Services
sudo rstudio-server restart
sudo rstudio-launcher restart
Step 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:
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.
Step 11) 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.
Comments