Support

Customizing the Entrypoint with RStudio Workbench / RStudio Server Pro, Job Launcher, and Kubernetes

Follow

When RStudio Workbench (previously RStudio Server Pro) is launching R sessions on Kubernetes via the RStudio Job Launcher, customers occasionally need to customize the startup process to do things like start sssd (domain join the container) or provision the execution environment (read group membership from an environment variable, retrieve group memberships, etc.).

 

It is important to do this properly so that the RStudio Job Launcher can continue to function as designed.

 

Define the Entrypoint script

First, your session containers need to have a custom entrypoint script. This can be either built into the container or mounted via a configmap. For the purposes of our example, we will use an entrypoint script at /usr/local/bin/startup.sh

The entrypoint script can contain any arbitrary shell script, provided that it does the following:

  • Does not alter the arguments provided to the script
  • Ends in the following section:
# Launch the session based on RSTUDIO_TYPE
if [ -z "$RSTUDIO_TYPE" -o "$RSTUDIO_TYPE" == "session" ]; then
echo "Starting RStudio session..."
exec "/usr/lib/rstudio-server/bin/rserver-launcher" "$@"
elif [ "$RSTUDIO_TYPE" == "adhoc" ]; then
echo "Starting RStudio adhoc job..."
exec "/bin/bash" "$@"
else
echo "ERROR: Unknown RSTUDIO_TYPE: ${RSTUDIO_TYPE}"
exit 1
fi

For the purposes of our example, here is our entrypoint script:

/usr/local/bin/startup.sh

#!/bin/bash
echo -e 'The r-session container is starting\n'

# show that this initial process runs as root inside the pod
id
# Launch the session based on RSTUDIO_TYPE
if [ -z "$RSTUDIO_TYPE" -o "$RSTUDIO_TYPE" == "session" ]; then
echo "Starting RStudio session..."
exec "/usr/lib/rstudio-server/bin/rserver-launcher" "$@"
elif [ "$RSTUDIO_TYPE" == "adhoc" ]; then
echo "Starting RStudio adhoc job..."
exec "/bin/bash" "$@"
else
echo "ERROR: Unknown RSTUDIO_TYPE: ${RSTUDIO_TYPE}"
exit 1
fi

 

Set up the launcher-env file

NOTE: Without this step, "launcher jobs" / "adhoc jobs" will not work.

You may notice that jobs are launched differently based on whether they are "sessions" (i.e. interactive RStudio, Jupyter, or VSCode sessions) or non-interactive "adhoc jobs" / "launcher jobs." As a result, we need to use the launcher-env file to tell our entrypoint how to behave:


/etc/rstudio/launcher-env

JobType: session
Environment: RSTUDIO_TYPE=session

JobType: adhoc
Environment: RSTUDIO_TYPE=adhoc

 

Alter the Job to use the Entrypoint Script

In order to get the RStudio Job Launcher to execute this entrypoint script instead of the canonical /usr/lib/rstudio-server/bin/rserver-launcher, we will use the job-json-overrides specification to alter the submitted Kubernetes jobs. This process is articulated more thoroughly in this article.

 

We will define a job-json-overrides file as follows:

/etc/rstudio/entrypoint.json

"/usr/local/bin/startup.sh"

And add the following line to the relevant profiles sections in our launcher.kubernetes.profiles.conf file:

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

[*]
job-json-overrides="/spec/template/spec/containers/0/command/0":"/etc/rstudio/entrypoint.json"

 

Test that it works

Now restart the rstudio-launcher service and launch a new job. You should see that the job specification is altered to use the new entrypoint script.

$ kubectl get pod session-5ab10cfc78a31fb9c8280-rstudio---rstudio-session-8-sfdgw -o yaml | grep -A 1 command
--
command:
- /usr/local/bin/startup.sh

And you can see the effect of the custom entrypoint script in the session logs:

The r-session container is starting 
uid=0(root) gid=0(root) groups=0(root)
Starting RStudio Session

 

Troubleshooting

Troubleshooting an improper configuration here is quite tricky since the RStudio Job Launcher does not expose invalid job configuration, but responds with "Kubernetes API failure". 

We intend to improve the product's verbosity in the future so that these types of customization are easier to implement.

Other times, the job config is valid "enough" to launch, but fails immediately. In this case, we recommend looking at the job config with kubectl get pods -o yaml

As with most debugging, start with the simplest configuration you can and slowly iterate to the configuration that you desire, changing one thing at a time.

 

If you have questions, never hesitate to reach out to support@rstudio.com

 

Comments