Support

Using Job Json Overrides with RStudio Server Pro and Kubernetes

Follow

RStudio Server Pro, when configured with the RStudio Job Launcher, can start user sessions (RStudio, Jupyter, Jupyter Lab) on Kubernetes running inside of containers.

When it launches user sessions, it creates a "job" on Kubernetes. If you need to customize that "job spec" that gets delivered to Kubernetes, then you can use "job json overrides" to alter the job spec before it gets sent.

A more robust option would be to use Kubernetes Operators , but that is outside the scope of this article. Instead, we will explore a handful of use cases for job-json-overrides below.

Formal documentation on this topic is available in the RStudio Job Launcher Admin Guide.

Kubernetes Profiles

The job-json-overrides specification lives within the "Launcher Kubernetes Profiles" convention. This allows specifying different job execution parameters by linux username or linux group name. These specifics are additive, so it is important to understand how they operate. You can read more about this configuration file here. By convention, it lives at /etc/rstudio/launcher.kubernetes.profiles.conf .

Warning

It is important to be aware that changing the job spec for RStudio Server Pro Launcher Jobs can break RStudio Server Pro's successful launching of jobs in many different ways. For instance:

- If you remove or alter important attributes that RStudio Server Pro depends on

- If you create an invalid job spec

Also, it is worth noting that today we do not have any utilities to make this modification process testable. As a result, we recommend using job-json-overrides sparingly, and only to add functionality to the job spec (instead of overwriting or removing).

Important Note

Each option below is illustrated as a standalone example. You can have multiple job-json-overrides specified for the same user / group by comma-delimiting them.

job-json-overrides="/spec/path":"/file/path","/spec/path2":"/file/path2"

Examples

To get started with our examples, create the /etc/rstudio/job-json-overrides directory. This is the directory that we will store configuration within

# mkdir -p /etc/rstudio/job-json-overrides

Run the pod as "privileged"

Configure Job Json Overrides

In certain cases (debugging, some low level system library is in use, etc.), it is important that the pod is running with elevated privileges. To set this up, add the following job-json-overrides line to the appropriate group in your launcher kubernetes profiles configuration. For our example, we will set this for all users on the server

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

 [*]
allow-unknown-images=1
job-json-overrides="/spec/template/spec/containers/0/securityContext":"/etc/rstudio/job-json-overrides/securityContext"

Create an Override File

Now, create the file /etc/rstudio/job-json-overrides/securityContext with the following contents:

/etc/rstudio/job-json-overrides/securityContext

{
"privileged": true
}

 

Verify

Now restart the rstudio-launcher service, and new jobs should be launched as privileged containers! You can confirm using kubectl once a job has been launched

# kubectl -n rstudio get pod mypodname -o yaml | grep securityContext -A 1
securityContext:
privileged: true
--
securityContext: {}
serviceAccount: default

Attach a ConfigMap

Config Maps can be useful for including configuration into pods. This is particularly useful for the rsession.conf file and other related configuration that might be helpful for users (without building that configuration into the image itself).

Create a Config Map

First, you must create a config map with the appropriate input that you want to mount into your containers.

Given a file at session-config.yaml with the following contents:

session-config.yaml

apiVersion: v1
data:
rsession.conf: |
default-rsconnect-server=https://my.connect.example.com
kind: ConfigMap
metadata:
name: session-config
namespace: rstudio

You can create the configmap with:

kubectl apply -f session-config.yaml

 

Configure Job Json Overrides

Create an appropriate line for job-json-overrides in your Launcher Kubernetes Profiles configuration. In this case, we need two job-json-overrides: one for the volume, and one to mount the volume to the container.

[*]
allow-unknown-images=1
job-json-overrides="/spec/template/spec/volumes/-":"/etc/rstudio/job-json-overrides/volumes","/spec/template/spec/containers/0/volumeMounts/-":"/etc/rstudio/job-json-overrides/volumeMounts"

 

Create Each Override File

Now create the following two files in /etc/rstudio/job-json-overrides (making any modifications as needed for the files within your configmap):

/etc/rstudio/job-json-overrides/volumes

{
"configMap": {
"name": "session-config",
"items": [
{
"path": "rsession.conf",
"key": "rsession.conf"
}
]
},
"name": "session-config"
}

/etc/rstudio/job-json-overrides/volumeMounts

{
"mountPath": "/etc/rstudio/rsession.conf",
"name": "session-config",
"subPath": "rsession.conf"
}

 

Verify

That should do it! Now restart the rstudio-launcher service and launch a new job. You should be able to see the rsession.conf file from your configmap at the path specified.

Tips

  • The JSON pointer RFC is a useful (if highly technical) reference
  • Test on a staging server first!
  • When appending to an array, you must either specify an index (i.e. [0] for the first item) or a "-" to specify "overwrite the entire array." You can see this in use for the "Create a Config Map" example

Comments