This site is archived

Posit Connect support for off-host content execution has entered General Availability (GA).
Documentation about off-host execution is now included in the Connect Admin Guide.
The instructions presented here were associated with the off-host execution beta and are now obsolete.

Appendix: Config file reference

Config file settings for Posit Connect server running outside of Kubernetes

If you already have a working installation of Posit Connect and do not plan to run the Posit Connect server as a container on Kubernetes, you can still use the remote execution features, but you will need to modify Posit Connect’s main rstudio-connect.gcfg configuration yourself. If you are using Helm to manage your deployment, the Posit Connect Helm Chart will manage many of these configurations for you but you will need to migrate your existing rstudio-connect.gcfg configuration into the Helm Chart’s values.yaml file. See Helm Chart Reference for further information.

Installation Requirements

Kubernetes Cluster

You will need a Kubernetes cluster that meets the requirements documented in Posit Job Launcher - RBAC.

Most deployments will run Posit Connect as a container inside the same Kubernetes cluster that is used to execute Posit Connect content, though this is not required.

Namespace

Create a namespace for Posit Connect. This namespace should be separate from namespaces you use for Posit Workbench. We recommend an rstudio-connect namespace rather than the rstudio name suggested by the Job Launcher instructions.

Service Account

Create a service account that Posit Connect will use to launch jobs. Even if you are not using the Helm chart to deploy Posit Connect, it can still help generate the Kubernetes YAML needed to create the service account. The following command produces the YAML to create a service account with the necessary privileges:

helm template \
    --release-name rsc \
    --namespace rstudio-connect \
    --set experimental.launcher.enabled=true \
    --set rbac.create=true \
    --show-only=templates/rbac.yaml \
    rstudio/rstudio-connect

This service account is named rsc-rstudio-connect.

Storage

The variable data associated with your deployed content must be in a networked location (NFS) available to the Posit Connect process and the Kubernetes cluster.

Database

You will need a PostgreSQL server with a blank database and a database user with the ability to create and modify database tables, in addition to read/write permissions.

Images

You will need one or more images capable of running your R or Python content, and one or more YAML files describing the available images. See Image definition and configuration for more detailed information.

Posit Connect Server Configuration

To use Kubernetes content execution, you will need to make several changes to the /etc/rstudio-connect/rstudio-connect.gcfg configuration file. This documentation explains the various configuration settings that are needed by Posit Connect and how to determine an appropriate value for each.

This example configuration instructs Posit Connect to use the Posit Job Launcher with Kubernetes.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Launcher]
Enabled = true
Kubernetes = true
KubernetesAPIURL = "https://my-k8s-cluster.company.com"
KubernetesAuthToken = "<base64 encoded Kubernetes auth token...>"
DataDir = "nfs.company.com:/mnt/rstudio-connect"
ClusterDefinition = "/etc/rstudio-connect/runtimes.yaml"

The Posit Connect process must be restarted after making configuration changes.

Settings

This section describes the configuration necessary to enable the use of Kubernetes with your selected images. See the Posit Connect Admin Guide for a description of the property types.

Warning

All of these settings are experimental and not yet part of the public Posit Connect documentation.

Most installations configure these settings in the /etc/rstudio-connect/rstudio-connect.gcfg file.

`Launcher.Enabled`

A Boolean setting that indicates that Posit Connect should use the Posit Launcher to run its content.

[Launcher]
Enabled = true

`Launcher.Kubernetes`

A Boolean setting that indicates that Posit Launcher should use Kubernetes to run its Jobs.

[Launcher]
Kubernetes = true

`Launcher.KubernetesAPIURL`

The Launcher.KubernetesAPIURL specifies the location of your Kubernetes cluster. This setting should be configured with the base URL of your Kubernetes cluster API (up to, but not including, the /api endpoint.)

; /etc/rstudio-connect/rstudio-connect.gcfg
[Launcher]
KubernetesAPIURL = "https://my-k8s-cluster.company.com"

Your Kubernetes cluster may use the KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT environment variables to make information about the Kubernetes service available to nodes running within the cluster.

You can build your Kubernetes API URL using these variables:

export KUBERNETES_API_URL="https://${KUBERNETES_SERVICE_HOST}:${KUBERNETES_SERVICE_PORT}"

Posit Connect will use the KUBERNETES_API_URL environment variable as the default value for its Launcher.KubernetesAPIURL setting; you do not need to configure this setting when defining the KUBERNETES_API_URL environment variable.

`Launcher.KubernetesAuthToken`

The Launcher.KubernetesAuthToken setting should be configured with the auth token for your target service account. If you used the YAML generated by the Helm chart, then the token belongs to the rsc-rstudio-connect service account in the rstudio-connect namespace.

The token must be base64 encoded and can be retrieved with these commands:

# Get the name of the secret associated with the serviceaccount
KUBERNETES_AUTH_SECRET=$(kubectl get serviceaccount rsc-rstudio-connect --namespace=rstudio-connect -o jsonpath='{.secrets[0].name}')

# Read the secret and encode as base64
kubectl get secret $KUBERNETES_AUTH_SECRET --namespace=rstudio-connect -o jsonpath='{.data.token}' | base64 -d

# => <base64 encoded Kubernetes auth token...>

The Posit Connect configuration specifying the auth token:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Launcher]
KubernetesAuthToken = "<base64 encoded Kubernetes auth token...>"

Posit Connect will use the KUBERNETES_AUTH_TOKEN environment variable as the default value for its Launcher.KubernetesAuthToken setting; you do not need to configure this setting when defining the KUBERNETES_AUTH_TOKEN environment variable.

`Launcher.KubernetesNamespace`

The Launcher.KubernetesNamespace specifies the Kubernetes namespace where Posit Connect launches its jobs. This must be the same namespace you used to create your target service account. This setting is unnecessary if you are using the default rstudio-connect namespace.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Launcher]
KubernetesNamespace = "rstudio-connect"

`Launcher.DataDir`

A string setting that indicates an NFS location where the Posit Connect variable data is stored.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Launcher]
DataDir = "nfs.company.com:/mnt/rstudio-connect"

The Launcher.DataDir must reference the same physical storage as you are using as your Server.DataDir. The Server.DataDir indicates a path available within the container or server where Posit Connect is running. The Launcher.DataDir, in comparison, is an NFS location that Posit Connect will mount into new containers launched by Posit Connect for executing content.

Given an NFS location of nfs.company.com:/mnt/rstudio-connect, you might mount that as /data/rstudio-connect within your Posit Connect server or container. This scenario has the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
DataDir = "/data/rstudio-connect"

[Launcher]
DataDir = "nfs.company.com:/mnt/rstudio-connect"

`Launcher.ClusterDefinition`

A multi-string setting that indicates a set of YAML files that define the images permitted to be used in Kubernetes. These images are available for building and running your content.

[Launcher]
ClusterDefinition = "/etc/rstudio-connect/py3.9.yaml"
ClusterDefinition = "/etc/rstudio-connect/r4.0.yaml"

See our images documentation for additional details about constructing these YAML files.