diff --git a/examples/connect/application-configuration/index.qmd b/examples/connect/application-configuration/index.qmd index c8475c970..3870a0c47 100644 --- a/examples/connect/application-configuration/index.qmd +++ b/examples/connect/application-configuration/index.qmd @@ -15,5 +15,16 @@ These settings are recommend for most deployments and are described below: {{< include ../_prereqs.qmd >}} +## Kubernetes + +Recommended for Connect 2026.04.0 and later. + +```{.yaml include="rstudio-connect-recommended-app-config-kubernetes.yaml" filename="values.yaml"} +``` + +## Launcher + +For Connect versions older than 2026.04.0. + ```{.yaml include="rstudio-connect-recommended-app-config.yaml" filename="values.yaml"} ``` diff --git a/examples/connect/application-configuration/rstudio-connect-recommended-app-config-kubernetes.yaml b/examples/connect/application-configuration/rstudio-connect-recommended-app-config-kubernetes.yaml new file mode 100644 index 000000000..a5e43f6ef --- /dev/null +++ b/examples/connect/application-configuration/rstudio-connect-recommended-app-config-kubernetes.yaml @@ -0,0 +1,126 @@ + +replicas: 2 # TODO: Adjust the amount depending on your requirements + +# Using a license file with the helm chart: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-file +# If you would like to use a license key see this documentation: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-key +license: + file: + secret: posit-licenses # TODO: Change to the secret name in your cluster + secretKey: connect.lic # TODO: Change to the secret key containing your Connect license + +# Configures Connect shared storage +sharedStorage: + create: true + mount: true + storageClassName: nfs-sc-rwx # TODO: Change to a RWX StorageClass available in your cluster + # volumeName: connect-shared-pv-name # Only needed if PVs have been statically provisioned, in which case this will need to match the PV name. + requests: + storage: 100G + +extraObjects: + # Required to set a custom PyPI repo + - apiVersion: v1 + kind: ConfigMap + metadata: + name: pip-config-connect + data: + # TODO: if using Posit Package Manager, edit the below to match your package manager python repo URL + pip.conf: | + [global] + timeout = 60 + index-url = https://packagemanager.posit.co/pypi/latest/simple + trusted-host = packagemanager.posit.co + + # Required for authenticated R (not Python) repositories + - apiVersion: v1 + kind: ConfigMap + metadata: + name: curlrc-config-connect + data: + .curlrc: | + --netrc-file /etc/netrc + +launcher: + enabled: false + +backends: + kubernetes: + enabled: true # Required for Off-Host Execution mode (Connect 2026.04.0 and later) + defaultResourceJobBase: + spec: + template: + spec: + volumes: + # Required to set a custom Python repo + - name: pip-config-volume + configMap: + name: pip-config-connect + + # Required for authenticated R and Python repositories + # See the following documentation for more details: + # https://packagemanager.posit.co/__docs__/admin/connect.html#authenticated-repositories + # This secret must contain a netrc file with credentials to access your private repositories. + # Here is an example of how to create this secret: + # kubectl create secret generic connect-netrc --from-file=netrc=/path/to/your/netrc --namespace your-connect-namespace + - name: netrc-config-volume + secret: + secretName: connect-netrc + + # Required for authenticated R (not Python) repositories + - name: curlrc-config-volume + configMap: + name: curlrc-config-connect + + containers: + - name: connect-content # Must use this exact name for the content container + volumeMounts: + # Required to set a custom Python repo + - mountPath: /etc/pip.conf + name: pip-config-volume + subPath: pip.conf + + # Required for authenticated R and Python repositories + - mountPath: /etc/netrc + name: netrc-config-volume + subPath: netrc + + # Required for authenticated R (not Python) repositories + - mountPath: /etc/.curlrc + name: curlrc-config-volume + subPath: .curlrc + + env: + # Required for authenticated R and Python repositories + - name: NETRC + value: /etc/netrc + + # Required for authenticated R (not Python) repositories + - name: CURL_HOME + value: /etc + +securityContext: + privileged: false + +# The config section overwrites values in Posit Connect's main +# .gcfg configuration file. +config: + # Configures the Postgres connection for Posit Connect. + Database: + Provider: "Postgres" + Postgres: + # The URL syntax below is to utilize a PostgreSQL database installed + # in the cluster as described in the Kubernetes Cluster Preparation + # page of this guide. Change this URL if your PostgreSQL database is + # setup externally or in a different location. + URL: "postgres://connect@postgres.example.com:5432/connect?sslmode=disable" + Password: "" # TODO: Remove this line and instead set the password during helm install with --set config.Postgres.Password=. + + "RPackageRepository \"CRAN\"": + URL: https://packagemanager.posit.co/cran/__linux__/jammy/latest # TODO: If using Package Manager change to match your package manager R repo url + # If using other R repos, add them here using the below format + # "RPackageRepository \"INTERNAL\"": + # URL: https://packagemanager.posit.co/cran/__linux__/jammy/latest + Quarto: + Enabled: true diff --git a/examples/connect/auth/rstudio-connect-oidc.yaml b/examples/connect/auth/rstudio-connect-oidc.yaml index 169bc382a..0028acdd3 100644 --- a/examples/connect/auth/rstudio-connect-oidc.yaml +++ b/examples/connect/auth/rstudio-connect-oidc.yaml @@ -16,9 +16,6 @@ sharedStorage: requests: storage: 100G -launcher: - enabled: true # Required for Off-Host Execution mode - # The config section overwrites values in Posit Connect's main # .gcfg configuration file. config: diff --git a/examples/connect/auth/rstudio-connect-saml.yaml b/examples/connect/auth/rstudio-connect-saml.yaml index 763c890ac..510e5cf87 100644 --- a/examples/connect/auth/rstudio-connect-saml.yaml +++ b/examples/connect/auth/rstudio-connect-saml.yaml @@ -16,9 +16,6 @@ sharedStorage: requests: storage: 100G -launcher: - enabled: true # Required for Off-Host Execution mode - # The config section overwrites values in Posit Connect's main # .gcfg configuration file. config: diff --git a/examples/connect/container-images/custom-images.qmd b/examples/connect/container-images/custom-images.qmd index 0b73badc1..a63e17a1e 100644 --- a/examples/connect/container-images/custom-images.qmd +++ b/examples/connect/container-images/custom-images.qmd @@ -8,13 +8,26 @@ This example deploys Posit Connect using custom images instead of the default pu There are a minimum of three images that Connect requires to function in Off-Host Execution mode. They are listed below with their cooresponding default public repositories. -- Connect service container [rstudio/rstudio-connect](https://hub.docker.com/r/rstudio/rstudio-connect) -- Content container [rstudio/content-base](https://hub.docker.com/r/rstudio/content-base) -- Content init container [rstudio/rstudio-connect-content-init](https://hub.docker.com/r/rstudio/rstudio-connect-content-init) +- Connect service container [posit/connect](https://hub.docker.com/r/posit/connect) +- Content container [posit/connect-content](https://hub.docker.com/r/posit/connect-content) +- Content init container [posit/connect-content-init](https://hub.docker.com/r/posit/connect-content-init) -There are several content contents listed as execution enviornments by default on initial Connect startup based on the listing in the [default-runtime.yaml](https://github.com/rstudio/helm/blob/main/charts/rstudio-connect/default-runtime.yaml) file. Setting `customRuntimeYaml` will instead use the execution environments defined in that section instead of the default ones. Additional content containers may be added to provide more R, Python and Quarto versions and other system dependencies. See the [Content Execution Environment](https://docs.posit.co/connect/admin/appendix/off-host/execution-environments/) section in the Connect Admin Guide for more details. +Additional content containers may be added to provide more R, Python, and Quarto versions and other system dependencies. See the [Content Execution Environment](https://docs.posit.co/connect/admin/appendix/off-host/execution-environments/) section in the Connect Admin Guide for more details. {{< include ../_prereqs.qmd >}} +## Kubernetes + +Recommended for Connect 2026.04.0 and later. + +Define content images with `executionEnvironments`. Changes take effect on every `helm upgrade` without requiring a pod restart or database reset. + +```{.yaml include="rstudio-connect-custom-image-kubernetes.yaml" filename="values.yaml"} +``` + +## Launcher + +For Connect versions older than 2026.04.0. + ```{.yaml include="rstudio-connect-custom-image.yaml" filename="values.yaml"} ``` diff --git a/examples/connect/container-images/private-images.qmd b/examples/connect/container-images/private-images.qmd index cfad496bc..21762707c 100644 --- a/examples/connect/container-images/private-images.qmd +++ b/examples/connect/container-images/private-images.qmd @@ -8,19 +8,33 @@ This example deploys Posit Connect using custom images in registries requiring a There are a minimum of three images that Connect requires to function in Off-Host Execution mode. They are listed below with their cooresponding default public repositories on ghcr.io -- Connect service container [ghcr.io/rstudio/rstudio-connect](https://github.com/rstudio/rstudio-docker-products/pkgs/container/rstudio-connect) -- Content container [ghcr.io/rstudio/content-base](https://github.com/rstudio/rstudio-docker-products/pkgs/container/content-base) -- Content init container [ghcr.io/rstudio/rstudio-connect-content-init](https://github.com/rstudio/rstudio-docker-products/pkgs/container/rstudio-connect-content-init) +- Connect service container [ghcr.io/posit-dev/connect](https://github.com/posit-dev/images-connect/pkgs/container/connect) +- Content container [ghcr.io/posit-dev/connect-content](https://github.com/posit-dev/images-connect/pkgs/container/connect-content) +- Content init container [ghcr.io/posit-dev/connect-content-init](https://github.com/posit-dev/images-connect/pkgs/container/connect-content-init) -There are several content contents listed as execution enviornments by default on initial Connect startup based on the listing in the [default-runtime.yaml](https://github.com/rstudio/helm/blob/main/charts/rstudio-connect/default-runtime.yaml) file. Setting `customRuntimeYaml` will instead use the execution environments defined in that section instead of the default ones. Additional content containers may be added to provide more R, Python and Quarto versions and other system dependencies. See the [Content Execution Environment](https://docs.posit.co/connect/admin/appendix/off-host/execution-environments/) section in the Connect Admin Guide for more details. +Additional content containers may be added to provide more R, Python, and Quarto versions and other system dependencies. See the [Content Execution Environment](https://docs.posit.co/connect/admin/appendix/off-host/execution-environments/) section in the Connect Admin Guide for more details. -These images can be pulled from your own container registry instead of the public Posit provided images. +These images can be pulled from your own container registry instead of the public Posit provided images. This example also shows where to provide private registry credentials in the form of a Kubernetes secret of type `kubernetes.io/dockercfg`. The registry credentials secret must be specified in two places in the values to apply to Connect, content and init containers (shown in the example below). -Also note the `launcher.templateValues.pod.imagePullSecrets` provides the pod-level `imagePullSecret` that provides the secret to pull the `launcher.defaultInitContainer` as well. {{< include ../_prereqs.qmd >}} +## Kubernetes + +Recommended for Connect 2026.04.0 and later. + +The `backends.kubernetes.defaultResourceJobBase.spec.template.spec.imagePullSecrets` provides the pod-level `imagePullSecret` for content and init containers. + +```{.yaml include="rstudio-connect-custom-image-private-kubernetes.yaml" filename="values.yaml"} +``` + +## Launcher + +For Connect versions older than 2026.04.0. + +The `launcher.templateValues.pod.imagePullSecrets` provides the pod-level `imagePullSecret` that provides the secret to pull the `launcher.defaultInitContainer` as well. + ```{.yaml include="rstudio-connect-custom-image-private.yaml" filename="values.yaml"} ``` diff --git a/examples/connect/container-images/rstudio-connect-custom-image-kubernetes.yaml b/examples/connect/container-images/rstudio-connect-custom-image-kubernetes.yaml new file mode 100644 index 000000000..b707d75cf --- /dev/null +++ b/examples/connect/container-images/rstudio-connect-custom-image-kubernetes.yaml @@ -0,0 +1,71 @@ + +# Using a license file with the helm chart: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-file +# If you would like to use a license key see this documentation: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-key +license: + file: + secret: posit-licenses # TODO: Change to the secret name in your cluster + secretKey: connect.lic # TODO: Change to the secret key containing your Connect license + +# Configures Connect shared storage +sharedStorage: + create: true + mount: true + storageClassName: nfs-sc-rwx # TODO: Change to a RWX StorageClass available in your cluster + # volumeName: connect-shared-pv-name # Only needed if PVs have been statically provisioned, in which case this will need to match the PV name. + requests: + storage: 100G + +# Define the custom image for the Connect pod(s) +image: + repository: ghcr.io/posit-dev/connect # TODO: Change to match your custom image repository + tagPrefix: "" # New posit-dev/images-connect images do not use a tag prefix + tag: "" # TODO: Change to match your custom image tag. By default when this is left blank the chart app version is automatically filled out. + +launcher: + enabled: false + +backends: + kubernetes: + enabled: true # Required for Off-Host Execution mode (Connect 2026.04.0 and later) + # Define the custom image(s) for the content pod(s) init container + defaultInitContainer: + repository: ghcr.io/posit-dev/connect-content-init # TODO: Change to match your custom image repository + tagPrefix: "" # New posit-dev/images-connect images do not use a tag prefix + tag: "" # TODO: Change to match your custom image tag. By default when this is left blank the chart app version is automatically filled out. + +# Define the custom image(s) for the content pod(s). +# Unlike launcher.customRuntimeYaml, changes take effect on every helm upgrade +# without requiring a pod restart or database reset. +executionEnvironments: + # TODO: Add custom images based on the below template + - name: ghcr.io/posit-dev/connect-content:R4.5.2-python3.14.3-ubuntu-24.04 # TODO: Change to match your custom image repository + title: "Custom Runtime" # TODO: Change to a descriptive title + description: "Runtime with R 4.5.2 and Python 3.14.3" # TODO: Change to a descriptive description + python: + installations: + - path: /opt/python/3.14.3/bin/python3 # TODO: Change to match the Python path available in your image + version: 3.14.3 # TODO: Change to match the Python version available in your image + r: + installations: + - path: /opt/R/4.5.2/bin/R # TODO: Change to match the R path available in your image + version: 4.5.2 # TODO: Change to match the R version available in your image + quarto: + installations: + - path: /opt/quarto/1.8.27/bin/quarto # TODO: Change to match the quarto path available in your image + version: 1.8.27 # TODO: Change to match the Quarto version available in your image + +# The config section overwrites values in Posit Connect's main +# .gcfg configuration file. +config: + # Configures the Postgres connection for Posit Connect. + Database: + Provider: "Postgres" + Postgres: + # The URL syntax below is to utilize a PostgreSQL database installed + # in the cluster as described in the Kubernetes Cluster Preparation + # page of this guide. Change this URL if your PostgreSQL database is + # setup externally or in a different location. + URL: "postgres://connect@postgres.example.com:5432/connect?sslmode=disable" + Password: "" # TODO: Remove this line and instead set the password during helm install with --set config.Postgres.Password=. diff --git a/examples/connect/container-images/rstudio-connect-custom-image-private-kubernetes.yaml b/examples/connect/container-images/rstudio-connect-custom-image-private-kubernetes.yaml new file mode 100644 index 000000000..e1a04bd14 --- /dev/null +++ b/examples/connect/container-images/rstudio-connect-custom-image-private-kubernetes.yaml @@ -0,0 +1,78 @@ +# Using a license file with the helm chart: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-file +# If you would like to use a license key see this documentation: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-key +license: + file: + secret: posit-licenses # TODO: Change to the secret name in your cluster + secretKey: connect.lic # TODO: Change to the secret key containing your Connect license + +# Configures Connect shared storage +sharedStorage: + create: true + mount: true + storageClassName: nfs-sc-rwx # TODO: Change to a RWX StorageClass available in your cluster + # volumeName: connect-shared-pv-name # Only needed if PVs have been statically provisioned, in which case this will need to match the PV name. + requests: + storage: 100G + +# Define the custom image for the Connect pod(s) +image: + repository: ghcr.io/posit-dev/connect # TODO: Change to match your custom image repository + tagPrefix: "" # New posit-dev/images-connect images do not use a tag prefix + tag: "" # TODO: Change to match your custom image tag. By default when this is left blank the chart app version is automatically filled out. + imagePullSecrets: + - name: private-registery-creds # TODO: Change this to match the secret of type kubernetes.io/dockercfg in your cluster containing authentication credentials to your registry. More information: https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets + +launcher: + enabled: false + +backends: + kubernetes: + enabled: true # Required for Off-Host Execution mode (Connect 2026.04.0 and later) + # Define the custom image(s) for the content pod(s) init container + defaultInitContainer: + repository: ghcr.io/posit-dev/connect-content-init # TODO: Change to match your custom image repository + tagPrefix: "" # New posit-dev/images-connect images do not use a tag prefix + tag: "" # TODO: Change to match your custom image tag. By default when this is left blank the chart app version is automatically filled out. + defaultResourceJobBase: + spec: + template: + spec: + imagePullSecrets: + - name: private-registery-creds # TODO: Change this to match the secret of type kubernetes.io/dockercfg in your cluster containing authentication credentials to your registry. More information: https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets + +# Define the custom image(s) for the content pod(s). +# Unlike launcher.customRuntimeYaml, changes take effect on every helm upgrade +# without requiring a pod restart or database reset. +executionEnvironments: + # TODO: Add custom images based on the below template + - name: ghcr.io/posit-dev/connect-content:R4.5.2-python3.14.3-ubuntu-24.04 # TODO: Change to match your custom image repository + title: "Custom Runtime" # TODO: Change to a descriptive title + description: "Runtime with R 4.5.2 and Python 3.14.3" # TODO: Change to a descriptive description + python: + installations: + - path: /opt/python/3.14.3/bin/python3 # TODO: Change to match the Python path available in your image + version: 3.14.3 # TODO: Change to match the Python version available in your image + r: + installations: + - path: /opt/R/4.5.2/bin/R # TODO: Change to match the R path available in your image + version: 4.5.2 # TODO: Change to match the R version available in your image + quarto: + installations: + - path: /opt/quarto/1.8.27/bin/quarto # TODO: Change to match the quarto path available in your image + version: 1.8.27 # TODO: Change to match the Quarto version available in your image + +# The config section overwrites values in Posit Connect's main +# .gcfg configuration file. +config: + # Configures the Postgres connection for Posit Connect. + Database: + Provider: "Postgres" + Postgres: + # The URL syntax below is to utilize a PostgreSQL database installed + # in the cluster as described in the Kubernetes Cluster Preparation + # page of this guide. Change this URL if your PostgreSQL database is + # setup externally or in a different location. + URL: "postgres://connect@postgres.example.com:5432/connect?sslmode=disable" + Password: "" # TODO: Remove this line and instead set the password during helm install with --set config.Postgres.Password=. diff --git a/examples/connect/index.qmd b/examples/connect/index.qmd index 0372c5987..adf710f2f 100644 --- a/examples/connect/index.qmd +++ b/examples/connect/index.qmd @@ -6,7 +6,14 @@ listing: --- -The examples in this directory provide a starting point for deploying Posit Connect in different configurations. +The examples in this directory provide a starting point for deploying Posit Connect in different configurations. + +Posit Connect supports two backends for off-host execution: + +- **`backends.kubernetes`** (recommended) -- Connect 2026.04.0 and later manages content Jobs and Services directly. +- **Launcher** -- For Connect versions older than 2026.04.0. Existing installations can upgrade using the [upgrade guide](upgrade-launcher-to-kubernetes/launcher-to-kubernetes.qmd). + +Examples that involve off-host execution configuration provide values for both backends, with the recommended `backends.kubernetes` approach shown first. Each example has a beginning description and a series of `TODO` comments. Before using an example, read through all the comments and ensure you address each `TODO`. diff --git a/examples/connect/storage/additional-volumes.qmd b/examples/connect/storage/additional-volumes.qmd index 77abaecc2..1682d3fc7 100644 --- a/examples/connect/storage/additional-volumes.qmd +++ b/examples/connect/storage/additional-volumes.qmd @@ -7,10 +7,23 @@ category: "Storage" This example shows how to mount a `ConfigMap` to the Connect pod and a `PVC` is mounted to content pods. This pattern of specifying the volumes and volumeMounts will work for a variety of volume types: `PVC`, `ConfigMap`, etc. -Depending on the need to add additional volumes, you may only need to mount to the Connect service or content pods but not both. +Depending on the need to add additional volumes, you may only need to mount to the Connect service or content pods but not both. For example, if you need to add TLS certificates for Connect via a `ConfigMap` then the content pods do not need the `ConfigMap` mounted. {{< include ../_prereqs.qmd >}} +## Kubernetes + +Recommended for Connect 2026.04.0 and later. + +Specify content container volumes and mounts under `backends.kubernetes.defaultResourceJobBase` using standard Kubernetes Job spec fields. Name the content container `connect-content`. + +```{.yaml include="rstudio-connect-with-additional-mounts-kubernetes.yaml" filename="values.yaml"} +``` + +## Launcher + +For Connect versions older than 2026.04.0. + ```{.yaml include="rstudio-connect-with-additional-mounts.yaml" filename="values.yaml"} ``` diff --git a/examples/connect/storage/rstudio-connect-with-additional-mounts-kubernetes.yaml b/examples/connect/storage/rstudio-connect-with-additional-mounts-kubernetes.yaml new file mode 100644 index 000000000..bf6038381 --- /dev/null +++ b/examples/connect/storage/rstudio-connect-with-additional-mounts-kubernetes.yaml @@ -0,0 +1,69 @@ +# Using a license file with the helm chart: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-file +# If you would like to use a license key see this documentation: +# https://github.com/rstudio/helm/tree/main/charts/rstudio-connect#license-key +license: + file: + secret: posit-licenses # TODO: Change to the secret name in your cluster + secretKey: connect.lic # TODO: Change to the secret key containing your Connect license + +# Configures Connect shared storage +sharedStorage: + create: true + mount: true + storageClassName: nfs-sc-rwx # TODO: Change to a RWX StorageClass available in your cluster + # volumeName: connect-shared-pv-name # Only needed if PVs have been statically provisioned, in which case this will need to match the PV name. + requests: + storage: 100G + +# This section is used to mount to the Connect container which is +# often used to add in additional configuration and TLS certificates +# which are not needed in the content containers. +pod: + volumeMounts: + - mountPath: /etc/connect-certs # TODO: Change to your desired mount path + name: ldap-certificate # TODO: Change to match the volume name below + volumes: + - name: ldap-certificate # TODO: Change to match the volumeMounts name above + # Can be any type of volume... persistentVolumeClaim, configMap, etc. + # Can also provision a PVC, PV, ConfigMap, etc via `extraObjects` if desired + configMap: + name: connect-ldap-certificate # TODO: Change to match your ConfigMap name + +launcher: + enabled: false + +# This section is only needed if you need to mount to the content containers +# which is often the case if you need to mount data for content to access +backends: + kubernetes: + enabled: true # Required for Off-Host Execution mode (Connect 2026.04.0 and later) + defaultResourceJobBase: + spec: + template: + spec: + volumes: + - name: shared-data # TODO: Ensure matches the name specified in volumeMounts below + # Can be any type of volume... persistentVolumeClaim, configMap, etc. + # Can also provision a PVC or PV via `extraObjects` if desired + persistentVolumeClaim: + claimName: shared-data-pvc # TODO: Change to an available PVC name + containers: + - name: connect-content # Must use this exact name for the content container + volumeMounts: + - mountPath: /mnt/data # TODO: Change to your desired mount path + name: shared-data # TODO: Ensure matches the name specified in volumes above + +# The config section overwrites values in Posit Connect's main +# .gcfg configuration file. +config: + # Configures the Postgres connection for Posit Connect. + Database: + Provider: "Postgres" + Postgres: + # The URL syntax below is to utilize a PostgreSQL database installed + # in the cluster as described in the Kubernetes Cluster Preparation + # page of this guide. Change this URL if your PostgreSQL database is + # setup externally or in a different location. + URL: "postgres://connect@postgres.example.com:5432/connect?sslmode=disable" + Password: "" # TODO: Remove this line and instead set the password during helm install with --set config.Postgres.Password=.