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: Helm Chart Reference

Posit Connect Server Configuration

All values under the config key are merged to create the final rstudio-connect.gcfg configuration file that will be used by Posit Connect. The keys and values will be included as-is in the final config. For example, if your values.yaml contains:

config:
  Abc:
    xyz: "This is a config value"
  MultiExample:
    Color:
      - "black"
      - "blue"
  'NamedSection "Alpha"':
    Url: http://example.org
  'Section With Spaces':
    Enabled: "Always true"

Then your resulting rstudio-connect.gcfg would include:

[Abc]
xyz = "This is a config value"

[MultiExample]
Color = "black"
Color = "blue"

[Named Section "Alpha"]
Url = http://example.org

[Section With Spaces]
Enabled = "Always true"

Dealing with Special Characters

String values which contain special characters may require further attention. For example, values containing ; or # may be interpreted as comments in your resulting rstudio-connect.gcfg configuration. This is most likely to affect chart values nested under config.*, but the problem is not exclusive to these values.

Here are some examples of special cases:

Note

Each of these examples wraps the value in single-quotes in order to preserve the double-quotes in the final configuration

config:
  SpecialCharacters:
    Property1: '"simple"'
    Property2: '"a string with spaces"'
    Property3: '"escape \"quotes\" in a string like this"'
    Property4: '"A string containing # and ;"'

The your resulting rstudio-connect.gcfg would then include:

[SpecialCharacters]
Property1 = "simple"
Property2 = "a string with spaces"
Property3 = "escape \"quotes\" in a string like this"
Property4 = "A string containing # and ;"

Installing an Alternate Version of Posit Connect

By default, the Helm chart’s appVersion specifies the version of Posit Connect that will be used for your installation.

This value can be modified by setting the following in your values.yaml:

versionOverride: "2022.05.0"

Setting Resource Requirements for Connect

The minimum recommended system requirements when running Posit Connect in production can be specified using the resources.requests configuration key of the Helm chart. To specify a maximum resource limit, use the resources.limits configuration instead.

Note

The configurations below apply only to the Posit Connect server container. Connect does not yet support resource requests/limits on a per-content basis. A future version of Connect will have this capability. The Setting Resource Requirements for Content section describes how to configure resource constraints for all content.

Note

Pods that exceed the resource allocations defined by resources.limits may be evicted by Kubernetes.

resources:
  requests:
    enabled: true
    memory: "8G"
    cpu: "4"

Setting a Default Service Account for Content

Users may configure the Kubernetes service account used by content jobs globally via the helm chart. Please note that this service account is used by all content launched by Posit Connect.

To apply this configuration, modify the values.yaml to contain values like the following:

launcher:
  templateValues:
    pod:
      serviceAccountName: "global-service-account"

This will be used to populate Connect’s Launcher.KubernetesDefaultServiceAccount configuration option, which sets the global default service account used by content pods.

Using the above configuration, content pods will execute with the following specification:

spec:
  serviceAccountName: global-service-account

Setting Resource Requirements for Content

Users may configure content resource constraints globally via the helm chart. Please note that these constraints are applied to all content launched by Posit Connect.

To apply these configurations, modify the values.yaml to contain values like the following:

launcher:
  launcherKubernetesProfilesConf:
    "*":
      default-cpus: .5
      default-mem-mb: 512
      cpu-request-ratio: .5
      memory-request-ratio: .5

When the Pod is launched in Kubernetes, this translates to the following resource requests and limits:

spec:
  containers:
    - name: rs-launcher-container
      resources:
        limits:
          cpu: 500m
          memory: 512M
        requests:
          cpu: 250m
          memory: 256M

You may notice that the requests and limits contain different values. You can use the memory-request-ratio and cpu-request-ratio settings to tune the proportion of the total resource limits that is requested by the Pod. For example, setting memory-request-ratio: .5 and default-mem-mb: 512 results in limits.memory: 512M and requests.memory: 256M.

Creating Custom Images for Content Execution

Sometimes it is necessary to customize the image that will be used to execute content in a Kubernetes environment. This may be necessary when one of your R or Python dependencies require an external OS dependency on the underlying host (e.g. GDAL). In this example we will build a new container image with GDAL available for use by our R or Python content. We will then update our Posit Connect installation to use the new content image.

Note

Posit provides a set of content runtime images with various R and Python versions already installed. These images also include many common OS dependencies, such as GDAL.

Starting with a minimal Dockerfile:

FROM ubuntu:bionic

# Install GDAL and curl
RUN export DEBIAN_FRONTEND=noninteractive && \
        apt-get update && \
        apt-get install -y \
        curl \
        gdal-bin \
        libgdal-dev \
        && \
        rm -rf /var/lib/apt/lists/*

# Install R
ARG R_DISTRIBUTION=ubuntu-1804
ARG R_VERSION=3.6.3
ARG R_INSTALLER=r-${R_VERSION}_1_amd64.deb
RUN curl -fsSL -O https://cdn.rstudio.com/r/${R_DISTRIBUTION}/pkgs/${R_INSTALLER} && \
    export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -f -y ./${R_INSTALLER} && \
    rm ${R_INSTALLER} && \
    rm -rf /var/lib/apt/lists/*

Build the docker image:

docker build . -t rstudio/custom-gdal:bionic

Note

You will also need to docker push the image to your organization’s docker registry so that it is accessible from your Kubernetes cluster.

Next, we will generate a custom runtime.yaml using the provided utility scripts, which is used to tell Posit Connect about our new image:

./build-image-yaml.sh rstudio/custom-gdal:bionic > custom-runtime.yaml

Now, we can provide the contents of our custom-runtime.yaml to our helm install command so that Helm can inject the configuration when deploying Posit Connect.

Note

If you are updating a previous Helm release of Posit Connect, then you should use helm upgrade ... instead.

helm install connect rstudio/rstudio-connect \
  --set launcher.customRuntimeYaml="$(cat custom-runtime.yaml)" \
  --set license.key="<your-rstudio-connect-license-key>" \
  --set config.Postgres.Password="<your-postgres-database-password>" \
  --values values.yaml

You should now see log messages during Posit Connect startup indicating that the custom image is loaded and available for use by your content:

2021/06/30 15:39:57 Loading cluster definition /etc/rstudio-connect/runtime.yaml
2021/06/30 15:39:57 Environment Kubernetes::rstudio/custom-gdal:bionic is configured with interpreters:
R (nearest matching):
    - 3.6.3: /opt/R/3.6.3/bin/R
Python (major-minor matching):
    - none