From cebaaf6fefdb66a6a9876e857dcbab18c4d16786 Mon Sep 17 00:00:00 2001 From: edavidaja Date: Tue, 7 May 2024 13:12:35 -0400 Subject: [PATCH 01/67] updated posit-docs extension --- _environment | 2 + .../posit-dev/posit-docs/_extension.yml | 49 +++---- .../posit-docs/assets/_analytics.html | 40 ++++++ .../assets/images/posit-guide-dm.svg | 1 + .../assets/images/posit-guide-ltmd.svg | 1 + .../assets/images/posit-guide-open-dm.svg | 1 + .../assets/images/posit-guide-open-ltmd.svg | 1 + .../assets/images/posit-logo-black-TM.svg | 2 +- _extensions/posit-dev/posit-docs/theme.scss | 121 +++++++++++++++++- _quarto.yml | 32 ++++- images/favicon.svg | 21 +++ images/posit-guide-dm.svg | 1 + images/posit-guide-ltmd.svg | 1 + images/posit-guide-open-dm.svg | 1 + images/posit-guide-open-ltmd.svg | 1 + images/posit-icon-fullcolor.svg | 22 ++++ images/posit-logo-black-TM.svg | 1 + images/posit-logo-fullcolor-TM.svg | 1 + 18 files changed, 256 insertions(+), 43 deletions(-) create mode 100644 _environment create mode 100644 _extensions/posit-dev/posit-docs/assets/_analytics.html create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg create mode 100644 images/favicon.svg create mode 100644 images/posit-guide-dm.svg create mode 100644 images/posit-guide-ltmd.svg create mode 100644 images/posit-guide-open-dm.svg create mode 100644 images/posit-guide-open-ltmd.svg create mode 100644 images/posit-icon-fullcolor.svg create mode 100644 images/posit-logo-black-TM.svg create mode 100644 images/posit-logo-fullcolor-TM.svg diff --git a/_environment b/_environment new file mode 100644 index 00000000..3f26336d --- /dev/null +++ b/_environment @@ -0,0 +1,2 @@ +CURRENT_YEAR=2024 +PRODUCT_VERSION=2024.x diff --git a/_extensions/posit-dev/posit-docs/_extension.yml b/_extensions/posit-dev/posit-docs/_extension.yml index 4b25a124..5e7f0b4d 100644 --- a/_extensions/posit-dev/posit-docs/_extension.yml +++ b/_extensions/posit-dev/posit-docs/_extension.yml @@ -1,42 +1,33 @@ title: posit-docs -author: Ashley Henry -version: 0.2.0 -quarto-requred: ">=1.3.340" +author: Ashley Henry, David Aja, Aron Atkins +version: 3.0.0 +quarto-required: ">=1.3.340" contributes: project: project: type: website website: - title: favicon: "assets/images/favicon.svg" bread-crumbs: true navbar: pinned: true logo: "assets/images/posit-icon-fullcolor.svg" logo-alt: "Posit Documentation" - sidebar: - style: "floating" - collapse-level: 1 - search: true - pinned: false - page-footer: - left: - - text: © 2024 Posit Software, PBC - url: "https://posit.co" - center: | - Posit Product 12345 - right: - - icon: book - href: https://docs.posit.co - - icon: question-circle-fill - href: https://support.posit.co/hc/en-us - - icon: lightbulb-fill - href: https://solutions.posit.co - formats: - html: - theme: [theme.scss] - link-external-icon: true - link-external-newwindow: true - toc: true - toc-expand: true + - icon: "list" + menu: + - text: "docs.posit.co" + href: "https://docs.posit.co" + - text: "Posit Support" + href: "https://support.posit.co/hc/en-us/" + search: + copy-button: true + show-item-context: true + format: + html: + theme: [theme.scss] + link-external-icon: true + link-external-newwindow: true + toc: true + toc-expand: true + include-in-header: "assets/_analytics.html" diff --git a/_extensions/posit-dev/posit-docs/assets/_analytics.html b/_extensions/posit-dev/posit-docs/assets/_analytics.html new file mode 100644 index 00000000..6ba70366 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/_analytics.html @@ -0,0 +1,40 @@ + + diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg new file mode 100644 index 00000000..b0c67d11 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg new file mode 100644 index 00000000..f2c33c23 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg new file mode 100644 index 00000000..d6b0e2b2 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg new file mode 100644 index 00000000..77464c09 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg index b85676de..3b159987 100644 --- a/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/theme.scss b/_extensions/posit-dev/posit-docs/theme.scss index bad2b7b1..418bd8b4 100644 --- a/_extensions/posit-dev/posit-docs/theme.scss +++ b/_extensions/posit-dev/posit-docs/theme.scss @@ -18,6 +18,11 @@ $posit-burgundy-1:#78384F; $posit-burgundy-2:#542938; $primary: $posit-blue; + +// Feature preview heading colors +$preview-header: #EE6331; /* posit orange, contrast: 8.45 */ +$preview-header-border: darken($preview-header, 5%); + // scss-docs-end color-variables // Typography @@ -75,6 +80,26 @@ $list-group-color: $primary !default; font-weight: 500; } +/* Style for the version included in the website title */ +.navbar-title small { + font-size: 14px; + display: block; + padding-left: 1em; +} + +/* Posit logo - navbar or footer */ +#footer-right-posit-logo { + width: 70px; + min-width: 70px; +} + +#footer-right-logo { + width: 20px; + min-width: 20px; + margin-left: -3px !important; + margin-right: -3px !important; +} + .nav-link { font-family: $font-family-monospace; text-transform: uppercase; @@ -98,22 +123,37 @@ $list-group-color: $primary !default; font-family: $font-family-sans-serif; } +/* Sidebar and toc */ + +/* Left nav */ +.sidebar-item-container .active { + font-weight: 500; +} + +/* Left nav - letter spacing */ +.sidebar-navigation li a { + letter-spacing: .03em; + font-size: 16px; +} + /* Mini TOC */ .sidebar nav[role=doc-toc]>ul li a { text-transform: none !important; font-family: $font-family-sans-serif; - font-size: 16px; - font-weight: 300 !important; - letter-spacing: .05em !important; + font-weight: 400 !important; + letter-spacing: -0.2px !important; +} + +.sidebar nav[role=doc-toc] ul>li>a.active, .sidebar nav[role=doc-toc] ul>li>ul>li>a.active { + font-weight: 700 !important; } /* Left nav - letter spacing */ .sidebar-navigation li a { - letter-spacing: .03em; - font-size: 16px; + letter-spacing: -0.2px; + line-height: normal; } - /* Posit logo - footer */ #footer-logo { width: 70px; @@ -125,7 +165,74 @@ $list-group-color: $primary !default; min-height: min-content; } +// Font + +/* Body font */ +body { + letter-spacing: -0.2px !important; + } + +// Specialty headers + +/* the feature PREVIEW header */ +.preview-header > h1:after, +.preview-header > h2:after, +.preview-header > h3:after, +.preview-header > h4:after, +header h1 .preview-header { + content: "Preview feature"; + margin-left: 1em; + position: relative; + border-radius: 50rem !important; + top: -0.5em; +} + +.preview-header > h1:after, +.preview-header > h2:after, +.preview-header > h3:after, +.preview-header > h4:after, +header h1 .preview-header, +div span.preview-feature { + color: $preview-header; + border: 1px solid $preview-header-border; + font-weight: 400; + font-size: 9pt !important; + padding: 0rem 0.4rem; +} + +div span.preview-feature { + margin-left: 1em; + text-transform: uppercase; +} + +// Lists + /* List disc colors */ li::marker { - color: $primary; + color: $primary; +} + +/* Callout steps for images with multiple items/steps shown in single image */ +ol.groovyAlpha { + list-style: none; + counter-reset: list-counter; + } + +ol.groovyAlpha li { + counter-increment: list-counter; +} + +ol.groovyAlpha li > p:before { + content: counter(list-counter, lower-alpha); + width: 16px; + height: 16px; + text-align: center; + margin-right: 10px; + color: #fff; + background-color: #fc403b; + display: inline-block; + border-radius: 8px; + font-size: 9px; + line-height: 16px; + vertical-align: middle; } diff --git a/_quarto.yml b/_quarto.yml index 3f2c9fa6..11cd7a54 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -1,5 +1,8 @@ project: type: posit-docs + pre-render: | + ./helm-docs --chart-search-root=charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl + ./helm-docs --chart-search-root=other-charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl render: - charts/rstudio-workbench/README.md - charts/rstudio-workbench/NEWS.md @@ -19,17 +22,34 @@ project: filters: - include-code-files -format: - posit-docs-html: - toc: true - website: title: Posit Helm Charts + site-url: https://docs.posit.co/helm bread-crumbs: true repo-url: https://github.com/rstudio/helm repo-actions: [edit, issue] - page-footer: - center: Posit Helm Charts + page-footer: + left: | + Copyright © 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. + center: | + Posit Helm Charts {{< env PRODUCT_VERSION >}} + right: + - icon: question-circle-fill + href: "https://support.posit.co/hc/en-us" + - icon: lightbulb-fill + href: "https://solutions.posit.co/" + - text: "" + href: "https://docs.posit.co/" + - text: "" + href: "https://posit.co/" + navbar: + right: + - icon: "list" + menu: + - text: "docs.posit.co" + href: "https://docs.posit.co" + - text: "Posit Support" + href: "https://support.posit.co/hc/en-us/" sidebar: style: "floating" collapse-level: 1 diff --git a/images/favicon.svg b/images/favicon.svg new file mode 100644 index 00000000..d154019f --- /dev/null +++ b/images/favicon.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + diff --git a/images/posit-guide-dm.svg b/images/posit-guide-dm.svg new file mode 100644 index 00000000..b0c67d11 --- /dev/null +++ b/images/posit-guide-dm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/posit-guide-ltmd.svg b/images/posit-guide-ltmd.svg new file mode 100644 index 00000000..f2c33c23 --- /dev/null +++ b/images/posit-guide-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/posit-guide-open-dm.svg b/images/posit-guide-open-dm.svg new file mode 100644 index 00000000..d6b0e2b2 --- /dev/null +++ b/images/posit-guide-open-dm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/posit-guide-open-ltmd.svg b/images/posit-guide-open-ltmd.svg new file mode 100644 index 00000000..77464c09 --- /dev/null +++ b/images/posit-guide-open-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/posit-icon-fullcolor.svg b/images/posit-icon-fullcolor.svg new file mode 100644 index 00000000..ec7f5525 --- /dev/null +++ b/images/posit-icon-fullcolor.svg @@ -0,0 +1,22 @@ + + + + + + diff --git a/images/posit-logo-black-TM.svg b/images/posit-logo-black-TM.svg new file mode 100644 index 00000000..3b159987 --- /dev/null +++ b/images/posit-logo-black-TM.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/posit-logo-fullcolor-TM.svg b/images/posit-logo-fullcolor-TM.svg new file mode 100644 index 00000000..30512e6b --- /dev/null +++ b/images/posit-logo-fullcolor-TM.svg @@ -0,0 +1 @@ + \ No newline at end of file From e29a3185db6aced50ed65ca334b75141e31a09d6 Mon Sep 17 00:00:00 2001 From: edavidaja Date: Fri, 10 May 2024 15:40:43 -0400 Subject: [PATCH 02/67] run helm-docs as quarto pre-render --- .github/workflows/chart-doc.yaml | 30 ++++++++++++++++-------------- Justfile | 15 +++++++++------ _quarto.yml | 4 ++-- 3 files changed, 27 insertions(+), 22 deletions(-) diff --git a/.github/workflows/chart-doc.yaml b/.github/workflows/chart-doc.yaml index 249220fe..06e82c12 100644 --- a/.github/workflows/chart-doc.yaml +++ b/.github/workflows/chart-doc.yaml @@ -20,19 +20,22 @@ jobs: with: version: v3.6.3 + - name: install Just + uses: extractions/setup-just@v2 + - name: Install helm-docs env: - version: 1.5.0 + HELM_DOCS_VERSION: 1.13.1 run: | - echo "Installing helm-docs version $version" - curl -L -o helm-docs.tar.gz https://github.com/norwoodj/helm-docs/releases/download/v${version}/helm-docs_${version}_Linux_x86_64.tar.gz - tar -xzvf helm-docs.tar.gz helm-docs - rm -rf helm-docs.tar.gz + just setup + + - name: Install Quarto + uses: quarto-dev/quarto-actions/setup@v2 + with: + version: pre-release - - name: Run helm-docs - run: | - ./helm-docs --chart-search-root=charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl - ./helm-docs --chart-search-root=other-charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl + - name: Render Quarto Project + uses: quarto-dev/quarto-actions/render@v2 - name: Commit results run: | @@ -62,13 +65,12 @@ jobs: with: version: v3.6.3 + - name: install Just + uses: extractions/setup-just@v2 + - name: Compute and update dependent files run: | - set -xe - cd ./charts/rstudio-launcher-rbac && helm dependency build && cd - - helm template -n rstudio rstudio-launcher-rbac ./charts/rstudio-launcher-rbac --set removeNamespaceReferences=true > examples/rbac/rstudio-launcher-rbac.yaml - CHART_VERSION=$(helm show chart ./charts/rstudio-launcher-rbac | grep '^version' | cut -d ' ' -f 2) - cp examples/rbac/rstudio-launcher-rbac.yaml examples/rbac/rstudio-launcher-rbac-${CHART_VERSION}.yaml + just rbac - name: Commit results run: | diff --git a/Justfile b/Justfile index 9afbf6f2..3b5fbc64 100644 --- a/Justfile +++ b/Justfile @@ -1,13 +1,16 @@ DIFF := "diff" +HELM_DOCS_VERSION := env_var_or_default("HELM_DOCS_VERSION", "1.13.1") +OS := if os() == "macos" {"Darwin"} else if os() == "linux" {"Linux"} else if os() == "windows" {"Windows"} else {""} +ARCH := if arch() == "aarch64" {"arm64"} else if arch() == "x86_64" {"x86_64"} else {""} setup: #!/bin/bash - # TODO: idempotency - - # TODO: check for macos - mkdir -p ./bin/helm-docs-1.5.0/ - curl -L https://github.com/norwoodj/helm-docs/releases/download/v1.5.0/helm-docs_1.5.0_Darwin_x86_64.tar.gz | tar -xzvf - -C ./bin/helm-docs-1.5.0/ - ln -s $PWD/bin/helm-docs-1.5.0/helm-docs $PWD/bin/helm-docs + set -xe + echo "Installing helm-docs version {{HELM_DOCS_VERSION}}" + mkdir -p bin + curl -L -s https://github.com/norwoodj/helm-docs/releases/download/v{{HELM_DOCS_VERSION}}/helm-docs_{{HELM_DOCS_VERSION}}_{{OS}}_{{ARCH}}.tar.gz -o bin/helm-docs.tar.gz + tar -C ./bin -xz -f bin/helm-docs.tar.gz helm-docs + rm -rf bin/helm-docs.tar.gz update-lock: #!/bin/bash diff --git a/_quarto.yml b/_quarto.yml index 11cd7a54..8554e84c 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -1,8 +1,8 @@ project: type: posit-docs pre-render: | - ./helm-docs --chart-search-root=charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl - ./helm-docs --chart-search-root=other-charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl + ./bin/helm-docs --chart-search-root=charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl + ./bin/helm-docs --chart-search-root=other-charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl render: - charts/rstudio-workbench/README.md - charts/rstudio-workbench/NEWS.md From 93ab6e5df3a10dbde4f3f421614ab99823c6508f Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Fri, 10 May 2024 20:31:31 -0400 Subject: [PATCH 03/67] Workbench review --- charts/rstudio-workbench/README.md | 311 ++++++++++++++++------------- examples/workbench/index.qmd | 2 +- index.qmd | 10 +- 3 files changed, 179 insertions(+), 144 deletions(-) diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9cda63d7..01abf0ab 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,4 +1,7 @@ -# Posit Workbench +--- +title: Posit Workbench +code-overflow: wrap +--- ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) @@ -7,19 +10,23 @@ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm diff upgrade`. * Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart + changes and the documentation below on how to use the chart. -## Installing the Chart +## Installing the chart To install the chart with the release name `my-release` at version 0.7.3: @@ -29,59 +36,65 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: -``` + +```bash helm search repo rstudio/rstudio-workbench -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or the address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` + + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against directly placing it in your values file. -### License File +### License file We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` +```bash +kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic +``` Second, specify the following values: @@ -94,39 +107,48 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-workbench.lic` +```bash +--set-file license.file.contents=licenses/rstudio-workbench.lic +``` -### License Key +### License key -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument: -### License Server +```bash +--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX +``` -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +### License server -## General Principles +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument: + +```bash +--set license.server= +``` + +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by RStudio Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by RStudio Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to get the service account information off of the RStudio Workbench pod for use in launching jobs. +- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files These configuration values all take the form of usual helm values -so you can set the database password with something like: +so you can set the database password with similar to: -``` +```bash ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -136,87 +158,77 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable - -- Session Configuration - - These configuration files are mounted into the server and - are mounted into the session pods as well. - - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. + +- Session Configuration: + - Configuration files: `repos.conf`, `rsession.conf`, `notifications.conf` + - These configuration files are mounted into the server and + the session pods. + - Located in the `config.session.<< name of file >>` helm values + - Mounted at `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: - These configuration files are mounted into the server and session pods as well - `odbc.ini` and other similar shared secrets - located in `config.sessionSecret.<< name of file>>` helm values - mounted at `/mnt/session-secret/` -- Secret Configuration +- Secret Configuration: - These configuration files are mounted into the server with more restrictive permissions (0600) - `database.conf`, `openid-client-secret`, `databricks.conf` - They are located in the `config.secret.<< name of file >>` helm values - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration +- Server Configuration: - These configuration files are mounted into the server (.ini file format) - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - They are located at `config.server.<< name of file >>` helm values - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration +- Server DCF Configuration: - These configuration files are mounted into the server (.dcf file format) - `launcher-mounts`, `launcher-env` - They are located at `config.serverDcf.<< name of file >>` helm values - included at `/mnt/configmap/rstudio/` -- Profiles Configuration +- Profiles Configuration: - These configuration files are mounted into the server (.ini file format) - `launcher.kubernetes.profiles.conf` - They are located at `config.profiles.<< name of file >>` helm values - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart + - See the [Profiles](#rstudio-profiles) section below for more information +- Prestart: - This is provided by the helm chart in a configmap - It is mounted into the pod at `/scripts/` - `prestart-workbench.bash` is used to start workbench - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`) - Located at `config.userProvisioning.<< name of file >>` helm values - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration +- Custom Startup Configuration: - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default + - Use the `.ini` file format, by default - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration + - As with all configuration files above, can override with a verbatim string if desired: + - Located at `config.startupCustom.<< name of file >>` helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: - `pam` configuration files - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - -### Configuring R and Python repositories - -#### R repositories - -R package repositories can be configured with `config.session.repos.conf`. + - Mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` - -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). +### Configuring Python and R repositories #### Python repositories -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -``` +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: + +```yaml launcher: useTemplates: true @@ -228,29 +240,43 @@ config: trusted-host: packagemanager.posit.co ``` -## User Provisioning +#### R repositories -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +R package repositories can be configured with `config.session.repos.conf`: + +```yaml +config: + session: + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest +``` + +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. + +## User provisioning + +Provisioning users in RStudio Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: + +However, it is important to use caution for the following: - UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames + time. Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because + some operating systems disallow `@` signs in linux usernames. - `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily + to configure a user management service, be careful that it does not exit unnecessarily. We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM @@ -259,7 +285,7 @@ When starting sessions on RStudio Workbench, PAM configuration is often very imp an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -279,17 +305,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -312,17 +338,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -339,6 +365,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -350,23 +377,28 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: + +### Job Json overrides -### Job Json Overrides +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: the "target" part of the job spec to replace + - `name`: a unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: a YAML value that is translated directly to JSON and injected into the job spec at `target`. -Note that several examples are provided +Several examples are provided in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) (however, examples do not use the helm chart syntax there). -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md).x ```yaml config: @@ -386,10 +418,11 @@ config: - "two-image:tag ``` -## Sealed Secrets +## Sealed secrets + This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -397,7 +430,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values diff --git a/examples/workbench/index.qmd b/examples/workbench/index.qmd index 6b6ec2c0..2a3fb88a 100644 --- a/examples/workbench/index.qmd +++ b/examples/workbench/index.qmd @@ -12,7 +12,7 @@ Before using an example, read through all the comments and ensure you address ea While each example focuses on one or more particular configurations, RStudio Workbench has some standard requirements listed in each example. -Each example will need the following to run correctly: +Each example needs the following to run correctly: - PostgreSQL database specified in the Workbench configuration - License key or file specified diff --git a/index.qmd b/index.qmd index 319ec014..435cdc7b 100644 --- a/index.qmd +++ b/index.qmd @@ -1,13 +1,15 @@ -# Posit Helm Charts +--- +title: Posit Helm Charts +--- [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/rstudio)](https://artifacthub.io/packages/search?repo=rstudio) [![GitHub license](https://img.shields.io/github/license/rstudio/helm.svg)](https://github.com/rstudio/helm/blob/main/LICENSE) ## Usage -1. Install [Helm](https://helm.sh). Please refer to Helm's [documentation](https://helm.sh/docs/) for more information on getting started. +1. Install [Helm](https://helm.sh). Please refer to the [Helm documentation](https://helm.sh/docs/) for more information on getting started. -2. Add the Posit Helm repo: +2. Add the Posit Helm repository: ```console helm repo add rstudio https://helm.rstudio.com @@ -17,4 +19,4 @@ ```console helm search repo rstudio - ``` + ``` \ No newline at end of file From 43fb469045c11165f49fdd6d29b17e84ef2c6e34 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Fri, 10 May 2024 20:54:07 -0400 Subject: [PATCH 04/67] New version of posit theme installed --- _environment | 1 + .../posit-dev/posit-docs/_extension.yml | 54 ++- .../posit-dev/posit-docs/_posit-colors.scss | 37 ++ .../posit-docs/assets/_analytics.html | 40 ++ .../assets/images/exclamation-circle-dm.svg | 4 + .../assets/images/exclamation-circle.svg | 4 + .../assets/images/exclamation-triangle-dm.svg | 4 + .../assets/images/exclamation-triangle.svg | 4 + .../assets/images/info-circle-dm.svg | 4 + .../posit-docs/assets/images/info-circle.svg | 4 + .../assets/images/posit-guide-dm.svg | 1 + .../assets/images/posit-guide-ltmd.svg | 1 + .../assets/images/posit-guide-open-dm.svg | 1 + .../assets/images/posit-guide-open-ltmd.svg | 1 + .../assets/images/posit-logo-black-TM.svg | 2 +- .../posit-dev/posit-docs/theme-dark.scss | 342 ++++++++++++++++ _extensions/posit-dev/posit-docs/theme.scss | 366 +++++++++++++++--- _quarto.yml | 22 +- images/posit-guide-ltmd.svg | 1 + images/posit-icon-fullcolor.svg | 22 ++ 20 files changed, 826 insertions(+), 89 deletions(-) create mode 100644 _environment create mode 100644 _extensions/posit-dev/posit-docs/_posit-colors.scss create mode 100644 _extensions/posit-dev/posit-docs/assets/_analytics.html create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/info-circle.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg create mode 100644 _extensions/posit-dev/posit-docs/theme-dark.scss create mode 100644 images/posit-guide-ltmd.svg create mode 100644 images/posit-icon-fullcolor.svg diff --git a/_environment b/_environment new file mode 100644 index 00000000..e8b49748 --- /dev/null +++ b/_environment @@ -0,0 +1 @@ +CURRENT_YEAR=2024 \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/_extension.yml b/_extensions/posit-dev/posit-docs/_extension.yml index 4b25a124..9f03f0f2 100644 --- a/_extensions/posit-dev/posit-docs/_extension.yml +++ b/_extensions/posit-dev/posit-docs/_extension.yml @@ -1,42 +1,36 @@ title: posit-docs -author: Ashley Henry -version: 0.2.0 -quarto-requred: ">=1.3.340" +author: Ashley Henry, David Aja, Aron Atkins +version: 4.0.1 +quarto-required: ">=1.3.340" contributes: project: project: type: website website: - title: favicon: "assets/images/favicon.svg" bread-crumbs: true navbar: pinned: true logo: "assets/images/posit-icon-fullcolor.svg" - logo-alt: "Posit Documentation" - sidebar: - style: "floating" - collapse-level: 1 - search: true - pinned: false - page-footer: - left: - - text: © 2024 Posit Software, PBC - url: "https://posit.co" - center: | - Posit Product 12345 - + logo-alt: "Posit Documentation" right: - - icon: book - href: https://docs.posit.co - - icon: question-circle-fill - href: https://support.posit.co/hc/en-us - - icon: lightbulb-fill - href: https://solutions.posit.co - formats: - html: - theme: [theme.scss] - link-external-icon: true - link-external-newwindow: true - toc: true - toc-expand: true + - icon: "list" + aria-label: 'Drop-down menu for additional Posit resources' + menu: + - text: "docs.posit.co" + href: "https://docs.posit.co" + - text: "Posit Support" + href: "https://support.posit.co/hc/en-us/" + search: + copy-button: true + show-item-context: true + format: + html: + theme: + light: [theme.scss] + dark: [theme-dark.scss] + link-external-icon: true + link-external-newwindow: true + toc: true + toc-expand: true + include-in-header: "assets/_analytics.html" diff --git a/_extensions/posit-dev/posit-docs/_posit-colors.scss b/_extensions/posit-dev/posit-docs/_posit-colors.scss new file mode 100644 index 00000000..e4bf13a3 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/_posit-colors.scss @@ -0,0 +1,37 @@ +/* Posit Color definitions */ +$posit-blue: #447099; +$posit-light-blue-1: #d1dbe5; +$posit-light-blue-2: #a2b8cb; +$posit-light-blue-3: #7494b1; +$posit-dark-blue-1: #305775; +$posit-dark-blue-2: #213d4f; + +$posit-orange: #ee6331; +$posit-light-orange-1: #edccbf; +$posit-light-orange-2: #eba38c; +$posit-dark-orange-1: #ab4d26; +$posit-dark-orange-2: #80361c; +$posit-dark-orange-3: #451f12; + +$posit-gray: #404041; +$posit-light-gray-1: #c2c2c4; +$posit-light-gray-2: #949494; +$posit-dark-gray-1: #333333; + +$posit-teal: #419599; +$posit-light-teal-1: #c2d9d9; +$posit-light-teal-2: #94bdbf; +$posit-light-teal-3: #70a3a6; +$posit-dark-teal-1: #297075; +$posit-dark-teal-2: #1f4f4f; +$posit-dark-teal-3: #122b2b; + +$posit-green: #72994e; + +$posit-burgundy: #9a4665; +$posit-light-burgundy-1: #d9c4cc; +$posit-light-burgundy-2: #bf96a3; +$posit-light-burgundy-3: #a67380; +$posit-dark-burgundy-1: #78384f; +$posit-dark-burgundy-2: #542938; +$posit-dark-burgundy-3: #2e171f; diff --git a/_extensions/posit-dev/posit-docs/assets/_analytics.html b/_extensions/posit-dev/posit-docs/assets/_analytics.html new file mode 100644 index 00000000..6ba70366 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/_analytics.html @@ -0,0 +1,40 @@ + + diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg new file mode 100644 index 00000000..fbdfd203 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg new file mode 100644 index 00000000..6098c8b2 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg new file mode 100644 index 00000000..63db9932 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg new file mode 100644 index 00000000..65d947c9 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg new file mode 100644 index 00000000..6a5c164d --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/info-circle.svg b/_extensions/posit-dev/posit-docs/assets/images/info-circle.svg new file mode 100644 index 00000000..f4f803ad --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/info-circle.svg @@ -0,0 +1,4 @@ + + + + diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg new file mode 100644 index 00000000..b0c67d11 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-dm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg new file mode 100644 index 00000000..f2c33c23 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg new file mode 100644 index 00000000..d6b0e2b2 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-dm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg new file mode 100644 index 00000000..77464c09 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-guide-open-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg index b85676de..9121db29 100644 --- a/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/theme-dark.scss b/_extensions/posit-dev/posit-docs/theme-dark.scss new file mode 100644 index 00000000..ec1e26d4 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/theme-dark.scss @@ -0,0 +1,342 @@ +/*-- scss:defaults --*/ + +// import font +@import url("https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap"); + +// import shared colors +@import '_posit-colors'; + +/*-- scss:variables --*/ +$primary: $posit-teal; +$dark-md-body: $posit-light-gray-1; +$dark-md-background: #0c1721; + +// Feature preview heading colors +$preview-header: $posit-orange; /* posit orange, contrast: 8.45 */ +$preview-header-border: darken($preview-header, 5%); + +// scss-docs-end color-variables + +// Typography +// Font, line-height, and color for body text, headings, and more. + +//scss-font-start font-variables +$font-family-sans-serif: "Open Sans", "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, + sans-serif, system-ui; +$font-family-monospace: "Source Code Pro", monospace; +$font-family-emoji: "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; +$font-size-base: 1rem; +// scss-docs-end font-variables + +//font and body color + +$body-color: $dark-md-body; +$popover-bg: $posit-green !default; + +// scss-docs-start font-sizes - seems that I have to keep these in the style sheet? +$h1-font-size: 44px; +$h2-font-size: 28px; +x h1 { + size: $h1-font-size; +} +h2 { + size: $h2-font-size; +} +// scss-docs-end font-sizes + +// Headings +// scss-docs-start headings-variables +$headings-color: #ffffff; +// scss-docs-end headings-variables + +// Customize the navbar +$navbar-bg: lighten($dark-md-background, 5%); +$navbar-fg: #ffffff; + +// CSS overrides + +// Body +// +// Settings for the `` element. + +//$body-color: $posit-green !default; +$body-bg: $dark-md-background !default; // dark mode change + +// Nav and footer + +/* Nav bar */ + +.navbar-title { + color: #ffffff; // dark theme change +} + +.nav-link { + font-family: $font-family-monospace; + text-transform: uppercase; + letter-spacing: 0.03em; + font-size: 14px !important; + font-weight: 500 !important; + color: #fff !important; +} + +.navbar-nav .nav-link.active, +.navbar-nav .nav-link.show { + color: $posit-teal !important; + font-weight: 700 !important; +} + +/* Nav bar right hamburger menu */ + +.dropdown-item:hover, +.dropdown-item:focus { + color: var(--bs-dropdown-link-hover-color); + background-color: #0f1c29 !important; +} + +/* Footer */ + +.nav-footer { + color: #ffffff !important; + border-top: solid $posit-gray 1px; +} + +/* Footer icons */ +.nav-footer a { + color: #ffffff !important; +} + +// Footnotes + +.footnote-back { + color: $posit-light-teal-2; +} + +// Breadcrumbs + +.quarto-title-breadcrumbs .breadcrumb li:last-of-type a { + color: $posit-light-gray-1 !important; +} + +// Page navigation + +.nav-page .nav-page-text { + color: $posit-light-gray-1; +} + +/* Inline code */ +p code:not(.sourceCode), +li code:not(.sourceCode), +td code:not(.sourceCode) { + background-color: #6e768166 !important; + color: #ffffff; +} + +// Code blocks + +/* Code block title*/ + +.quarto-dark .code-with-filename .code-with-filename-file { + background-color: #000000 !important; + border: none; +} + +.code-with-filename strong { + color: #6e9ac3; +} + +/* Code block background */ +$code-block-bg: lighten($dark-md-background, 10%); + +/* Copy button */ + +$btn-code-copy-color: $posit-light-blue-2; +$btn-code-copy-color-active: #ffffff; +$callout-icon-scale: 70%; + +// Tabs and pills + +/* Tabs */ + +.nav-tabs .nav-link.active { + color: $posit-teal !important; +} + +.nav-tabs .nav-link { + text-transform: none !important; + font-family: $font-family-sans-serif; + color: #ffffff !important; +} + +.nav-tabs .nav-link:hover, +.nav-link:focus { + color: $posit-teal !important; +} + +/* Pills */ + +.nav-pills .nav-link.active, +.nav-pills .show > .nav-link { + background-color: $posit-dark-teal-1 !important; +} + +.nav-pills .nav-link:hover, +.nav-link:focus { + isolation: isolate; + // color: $posit-teal !important; + border: none !important; +} + +.nav-pills .nav-link.active, +.nav-link:hover { + color: #ffffff !important; +} + +// Sidebar and toc + +/* Left nav - letter spacing */ +.sidebar-navigation li a { + color: #ffffff; +} + +.sidebar-navigation li a:hover { + color: inherit; +} + +.sidebar-item-container .active, +div.sidebar-item-container .show > .nav-link, +div.sidebar-item-container .sidebar-link > code { + color: $posit-teal !important; +} + +// Lists + +/* List disc colors */ +li::marker { + color: $posit-teal; +} + +// Callouts + +.callout.callout-style-default:not(.no-icon) div.callout-title-container { + color: #ffffff !important; +} + +div.callout.callout-style-default > div.callout-header { + opacity: none; +} + +/* Note */ + +div.callout-note.callout { + border-left-color: $posit-dark-blue-2 !important; + border-right: 1px solid $posit-dark-blue-2 !important; + border-top: 1px solid $posit-dark-blue-2 !important; + border-bottom: 1px solid $posit-dark-blue-2 !important; +} + +div.callout-note .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/info-circle-dm.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzAwMDAwMCIgY2xhc3M9ImJpIGJpLWluZm8tY2lyY2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik04IDE1QTcgNyAwIDEgMSA4IDFhNyA3IDAgMCAxIDAgMTRtMCAxQTggOCAwIDEgMCA4IDBhOCA4IDAgMCAwIDAgMTYiLz4KICA8cGF0aCBkPSJtOC45MyA2LjU4OC0yLjI5LjI4Ny0uMDgyLjM4LjQ1LjA4M2MuMjk0LjA3LjM1Mi4xNzYuMjg4LjQ2OWwtLjczOCAzLjQ2OGMtLjE5NC44OTcuMTA1IDEuMzE5LjgwOCAxLjMxOS41NDUgMCAxLjE3OC0uMjUyIDEuNDY1LS41OThsLjA4OC0uNDE2Yy0uMi4xNzYtLjQ5Mi4yNDYtLjY4Ni4yNDYtLjI3NSAwLS4zNzUtLjE5My0uMzA0LS41MzN6TTkgNC41YTEgMSAwIDEgMS0yIDAgMSAxIDAgMCAxIDIgMCIvPgo8L3N2Zz4=") !important; +} + +div.callout-note.callout-style-default > .callout-header { + background-color: $posit-blue !important; +} + +/* Warning */ + +div.callout-warning.callout { + border-left-color: $posit-dark-orange-2 !important; + border-right: 1px solid $posit-dark-orange-2 !important; + border-top: 1px solid $posit-dark-orange-2 !important; + border-bottom: 1px solid $posit-dark-orange-2 !important; +} + +div.callout-warning .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-triangle-dm.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzAwMDAwMCIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLXRyaWFuZ2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik03LjkzOCAyLjAxNkEuMTMuMTMgMCAwIDEgOC4wMDIgMmEuMTMuMTMgMCAwIDEgLjA2My4wMTYuMTUuMTUgMCAwIDEgLjA1NC4wNTdsNi44NTcgMTEuNjY3Yy4wMzYuMDYuMDM1LjEyNC4wMDIuMTgzYS4yLjIgMCAwIDEtLjA1NC4wNi4xLjEgMCAwIDEtLjA2Ni4wMTdIMS4xNDZhLjEuMSAwIDAgMS0uMDY2LS4wMTcuMi4yIDAgMCAxLS4wNTQtLjA2LjE4LjE4IDAgMCAxIC4wMDItLjE4M0w3Ljg4NCAyLjA3M2EuMTUuMTUgMCAwIDEgLjA1NC0uMDU3bTEuMDQ0LS40NWExLjEzIDEuMTMgMCAwIDAtMS45NiAwTC4xNjUgMTMuMjMzYy0uNDU3Ljc3OC4wOTEgMS43NjcuOTggMS43NjdoMTMuNzEzYy44ODkgMCAxLjQzOC0uOTkuOTgtMS43Njd6Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDEyYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNS45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-warning.callout-style-default > .callout-header { + background-color: $posit-dark-orange-1 !important; +} + +/* Important */ + +div.callout-important.callout { + border-left-color: $posit-dark-burgundy-2 !important; + border-right: 1px solid $posit-dark-burgundy-2 !important; + border-top: 1px solid $posit-dark-burgundy-2 !important; + border-bottom: 1px solid $posit-dark-burgundy-2 !important; +} + +div.callout-important .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-circle-dm.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzAwMDAwMCIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLWNpcmNsZSIgdmlld0JveD0iMCAwIDE2IDE2Ij4KICA8cGF0aCBkPSJNOCAxNUE3IDcgMCAxIDEgOCAxYTcgNyAwIDAgMSAwIDE0bTAgMUE4IDggMCAxIDAgOCAwYTggOCAwIDAgMCAwIDE2Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDExYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNC45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-important.callout-style-default > .callout-header { + background-color: $posit-burgundy !important; +} + +// Tables + +.table > :not(caption) > * > * { + border-top: 2px solid #101e2b; +} + +/* Striped table styles */ + +.table-striped > tbody > tr:nth-of-type(odd) > * { + //--bs-table-bg-type: #001C2B !important; + --bs-table-bg-type: #101e2b !important; +} + +/* Striped table hover */ + +.table-hover > tbody > tr:hover > * { + //--bs-table-color-state: var(--bs-table-hover-color); + --bs-table-bg-state: #001c2b !important; +} + +// Table caption + +.panel-caption, +.figure-caption, +.subfigure-caption, +.table-caption, +figcaption, +caption { + font-size: 1rem; + color: $body-color !important; +} + +// Specialty headers + +/* the feature PREVIEW header */ +.preview-header > h1:after, +.preview-header > h2:after, +.preview-header > h3:after, +.preview-header > h4:after, +header h1 .preview-header, +div span.preview-feature { + background-color: $preview-header; + color: #ffffff; + border: 1px solid $preview-header-border; + font-weight: 600; + font-size: 9pt !important; + padding: 0rem 0.4rem; +} + +div span.preview-feature { + margin-left: 1em; + text-transform: uppercase; +} + +// Specialty lists +// Groovy list - dark mode change + +ol.groovyAlpha li > p:before { + content: counter(list-counter, lower-alpha); + font-weight: 600; +} diff --git a/_extensions/posit-dev/posit-docs/theme.scss b/_extensions/posit-dev/posit-docs/theme.scss index bad2b7b1..169d615b 100644 --- a/_extensions/posit-dev/posit-docs/theme.scss +++ b/_extensions/posit-dev/posit-docs/theme.scss @@ -1,40 +1,37 @@ /*-- scss:defaults --*/ // import font -@import url('https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap'); +@import url("https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap"); + +// import shared colors +@import '_posit-colors'; /*-- scss:variables --*/ +$primary: $posit-blue; -// scss-docs-start color-variables -$posit-blue: #447099; -$posit-dark-blue-1: #305775; -$posit-dark-blue-2: #213D4F; -$posit-orange: #EE6331; -$posit-gray: #404041; -$posit-teal: #419599; -$posit-green: #72994E; -$posit-burgundy:#9A4665; -$posit-burgundy-1:#78384F; -$posit-burgundy-2:#542938; +// Feature preview heading colors +$preview-header: #ee6331; /* posit orange, contrast: 8.45 */ +$preview-header-border: darken($preview-header, 5%); -$primary: $posit-blue; // scss-docs-end color-variables // Typography // Font, line-height, and color for body text, headings, and more. //scss-font-start font-variables -$font-family-sans-serif: "Open Sans", "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, system-ui; +$font-family-sans-serif: "Open Sans", "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, + sans-serif, system-ui; $font-family-monospace: "Source Code Pro", monospace; $font-family-emoji: "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; $font-size-base: 1rem; // scss-docs-end font-variables +//font and body color $body-color: $posit-gray; // scss-docs-start font-sizes -$h1-font-size:44px; -$h2-font-size:28px; +$h1-font-size: 44px; +$h2-font-size: 28px; h1 { size: $h1-font-size; @@ -44,7 +41,6 @@ h2 { } // scss-docs-end font-sizes - // Headings // scss-docs-start headings-variables $headings-font-weight: 300 !important; @@ -64,68 +60,334 @@ $list-group-color: $primary !default; // CSS overrides +// Body +// +// Settings for the `` element. + +/* Body font */ +body { + letter-spacing: -0.2px !important; +} + +// Nav and footer + +/* Navbar */ + .navbar { - box-shadow: 0 0 0.2rem #0000001a, 0 0.1rem 0.4rem #0003; - transition: transform .25s cubic-bezier(.1,.7,.1,1),box-shadow .25s; + box-shadow: + 0 0 0.2rem #0000001a, + 0 0.1rem 0.4rem #0003; + transition: + transform 0.25s cubic-bezier(0.1, 0.7, 0.1, 1), + box-shadow 0.25s; } .navbar-title { - font-family: $font-family-sans-serif; - font-size: $font-size-base; - font-weight: 500; + font-family: $font-family-sans-serif; + font-size: $font-size-base; + font-weight: 500; +} + +/* Style for the version included in the website title */ +.navbar-title small { + font-size: 14px; + display: block; + padding-left: 1em; } .nav-link { - font-family: $font-family-monospace; - text-transform: uppercase; - letter-spacing: .03em; - font-size: 14px !important; - font-weight: 500 !important; + font-family: $font-family-monospace; + text-transform: uppercase; + letter-spacing: 0.03em; + font-size: 14px !important; + font-weight: 500 !important; + color: $posit-gray !important; +} + +.navbar-nav .nav-link.active, +.navbar-nav .nav-link.show { + color: #000000 !important; + font-weight: 700 !important; } +/* Footer */ + .nav-footer { - font-family: $font-family-monospace; - text-transform: uppercase; - font-size: 14px; - border-top: solid #0000001a .01em; - align-items: center !important; + font-family: $font-family-monospace; + text-transform: uppercase; + font-size: 14px; + border-top: solid #0000001a 0.01em; + align-items: center !important; +} + +.nav-footer .nav-footer-center { + min-height: min-content; +} + +/* Footer icons */ + +/* Full Posit logo - currently, unused */ +#footer-right-full-posit-logo { + width: 70px; + min-width: 70px; +} + +/* Posit guide book */ +#footer-right-logo { + width: 24px; + min-width: 24px; + margin-left: -3px !important; + margin-right: -3px !important; + padding-top: 1px; +} + +/* Posit icon fullcolor */ +#footer-right-posit-logo { + width: 18px; + min-width: 18px; + margin-left: -3px !important; + margin-right: -3px !important; + padding-top: 1px; +} + +/* Posit logo - footer +#footer-logo { + width: 70px; + min-width: 70px; } +*/ -/* Tabs */ +.bi-question-circle-fill { + font-size: 18px !important; +} + +.bi-lightbulb-fill { + font-size: 18px !important; +} + +// Footnotes + +.footnote-back { + font-size: 16px !important; + font-weight: 900px !important; + color: $posit-dark-blue-1; +} + +// Tabs and pills + +/* Tabs */ .nav-tabs .nav-link { - text-transform: none !important; - font-family: $font-family-sans-serif; + text-transform: none !important; + font-family: $font-family-sans-serif; + color: $posit-gray !important; } -/* Mini TOC */ -.sidebar nav[role=doc-toc]>ul li a { - text-transform: none !important; - font-family: $font-family-sans-serif; - font-size: 16px; - font-weight: 300 !important; - letter-spacing: .05em !important; +.nav-tabs .nav-link.active, +.nav-tabs .nav-item.show .nav-link { + color: #000000 !important; +} + +.nav-tabs .nav-link:hover, +.nav-link:focus { + color: $posit-blue !important; +} + +/* Pills */ + +.nav-pills { + border: none !important; +} + +.nav-pills, +.panel-underline { + > .nav { + display: flex; + border: none !important; + flex-direction: row; + justify-content: center; + .nav-link { + cursor: pointer; + } + } +} + +.nav-pills > .nav .nav-link { + border: none !important; +} + +.nav-pills, +.panel-underline { + .tab-content { + padding-left: 0; + padding-right: 0; + border: none; + } +} + +.nav-pills .nav-link.active, +.nav-pills .nav-item.show .nav-link { + color: #ffffff !important; +} + +.nav-pills .nav-link:hover, +.nav-link:focus { + isolation: isolate; + color: $posit-blue !important; + border: none !important; +} + +.nav-pills .nav-link.active, +.nav-pills .show > .nav-link { + color: #ffffff !important; +} + +// Sidebar and toc + +/* Left nav */ +.sidebar-item-container .active { + font-weight: 500; } /* Left nav - letter spacing */ .sidebar-navigation li a { - letter-spacing: .03em; - font-size: 16px; + letter-spacing: 0.03em; + font-size: 16px; } +/* Left nav - letter spacing */ +.sidebar-navigation li a { + letter-spacing: -0.2px; + line-height: normal; +} -/* Posit logo - footer */ -#footer-logo { - width: 70px; - min-width: 70px; +/* Mini TOC */ +.sidebar nav[role="doc-toc"] > ul li a { + text-transform: none !important; + font-family: $font-family-sans-serif; + font-weight: 400 !important; + letter-spacing: -0.2px !important; } -/* Footer */ -.nav-footer .nav-footer-center { - min-height: min-content; +.sidebar nav[role="doc-toc"] ul > li > a.active, +.sidebar nav[role="doc-toc"] ul > li > ul > li > a.active { + font-weight: 700 !important; } +// Lists + /* List disc colors */ li::marker { - color: $primary; + color: $primary; +} + +// Callouts + +.callout.callout-style-default:not(.no-icon) div.callout-title-container { + color: $posit-dark-gray-1 !important; +} + +/* Note */ + +div.callout-note.callout { + border-left-color: $posit-blue !important; +} + +div.callout-note .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/info-circle.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzE3MjEyQiIgY2xhc3M9ImJpIGJpLWluZm8tY2lyY2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik04IDE1QTcgNyAwIDEgMSA4IDFhNyA3IDAgMCAxIDAgMTRtMCAxQTggOCAwIDEgMCA4IDBhOCA4IDAgMCAwIDAgMTYiLz4KICA8cGF0aCBkPSJtOC45MyA2LjU4OC0yLjI5LjI4Ny0uMDgyLjM4LjQ1LjA4M2MuMjk0LjA3LjM1Mi4xNzYuMjg4LjQ2OWwtLjczOCAzLjQ2OGMtLjE5NC44OTcuMTA1IDEuMzE5LjgwOCAxLjMxOS41NDUgMCAxLjE3OC0uMjUyIDEuNDY1LS41OThsLjA4OC0uNDE2Yy0uMi4xNzYtLjQ5Mi4yNDYtLjY4Ni4yNDYtLjI3NSAwLS4zNzUtLjE5My0uMzA0LS41MzN6TTkgNC41YTEgMSAwIDEgMS0yIDAgMSAxIDAgMCAxIDIgMCIvPgo8L3N2Zz4=") !important; +} + +div.callout-note.callout-style-default > .callout-header { + background-color: #dce7f2 !important; +} + +/* Warning */ +div.callout-warning.callout { + border-left-color: $posit-orange !important; +} + +div.callout-warning .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-triangle.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzQ1MUYxMiIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLXRyaWFuZ2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik03LjkzOCAyLjAxNkEuMTMuMTMgMCAwIDEgOC4wMDIgMmEuMTMuMTMgMCAwIDEgLjA2My4wMTYuMTUuMTUgMCAwIDEgLjA1NC4wNTdsNi44NTcgMTEuNjY3Yy4wMzYuMDYuMDM1LjEyNC4wMDIuMTgzYS4yLjIgMCAwIDEtLjA1NC4wNi4xLjEgMCAwIDEtLjA2Ni4wMTdIMS4xNDZhLjEuMSAwIDAgMS0uMDY2LS4wMTcuMi4yIDAgMCAxLS4wNTQtLjA2LjE4LjE4IDAgMCAxIC4wMDItLjE4M0w3Ljg4NCAyLjA3M2EuMTUuMTUgMCAwIDEgLjA1NC0uMDU3bTEuMDQ0LS40NWExLjEzIDEuMTMgMCAwIDAtMS45NiAwTC4xNjUgMTMuMjMzYy0uNDU3Ljc3OC4wOTEgMS43NjcuOTggMS43NjdoMTMuNzEzYy44ODkgMCAxLjQzOC0uOTkuOTgtMS43Njd6Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDEyYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNS45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-warning.callout-style-default > .callout-header { + background-color: #fad8ca !important; +} + +/* Important */ + +div.callout-important.callout { + border-left-color: $posit-burgundy !important; +} + +div.callout-important .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-circle.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzJFMTcxRiIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLWNpcmNsZSIgdmlld0JveD0iMCAwIDE2IDE2Ij4KICA8cGF0aCBkPSJNOCAxNUE3IDcgMCAxIDEgOCAxYTcgNyAwIDAgMSAwIDE0bTAgMUE4IDggMCAxIDAgOCAwYTggOCAwIDAgMCAwIDE2Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDExYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNC45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-important.callout-style-default > .callout-header { + background-color: #f2dae3 !important; +} + +// Specialty headers + +/* the feature PREVIEW header */ +.preview-header > h1:after, +.preview-header > h2:after, +.preview-header > h3:after, +.preview-header > h4:after, +header h1 .preview-header { + content: "Preview feature"; + margin-left: 1em; + position: relative; + border-radius: 50rem !important; + top: -0.5em; +} + +.preview-header > h1:after, +.preview-header > h2:after, +.preview-header > h3:after, +.preview-header > h4:after, +header h1 .preview-header, +div span.preview-feature { + color: $preview-header; + border: 1px solid $preview-header-border; + font-weight: 400; + font-size: 9pt !important; + padding: 0rem 0.4rem; +} + +div span.preview-feature { + margin-left: 1em; + text-transform: uppercase; +} + +// Specialty lists + +/* Callout steps for images with multiple items/steps shown in single image */ + +ol.groovyAlpha { + list-style: none; + counter-reset: list-counter; +} + +ol.groovyAlpha li { + counter-increment: list-counter; +} + +ol.groovyAlpha li > p:before { + content: counter(list-counter, lower-alpha); + width: 20px; + height: 20px; + text-align: center; + margin-right: 10px; + color: #fff; + background-color: #fc403b; + display: inline-block; + border-radius: 10px; + font-size: 14px; + line-height: 16px; + vertical-align: middle; } diff --git a/_quarto.yml b/_quarto.yml index 3f2c9fa6..0c8bbe0c 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -19,17 +19,27 @@ project: filters: - include-code-files -format: - posit-docs-html: - toc: true - website: title: Posit Helm Charts bread-crumbs: true repo-url: https://github.com/rstudio/helm repo-actions: [edit, issue] - page-footer: - center: Posit Helm Charts + page-footer: + left: | + Copyright © 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. + center: | + Posit Helm Charts + right: + - icon: question-circle-fill + aria-label: 'Link to Posit Support' + href: "https://support.posit.co/hc/en-us" + - icon: lightbulb-fill + aria-label: 'Link to Posit Solutions' + href: "https://solutions.posit.co/" + - text: "" + href: "https://docs.posit.co/" + - text: "" + href: "https://posit.co/" sidebar: style: "floating" collapse-level: 1 diff --git a/images/posit-guide-ltmd.svg b/images/posit-guide-ltmd.svg new file mode 100644 index 00000000..f2c33c23 --- /dev/null +++ b/images/posit-guide-ltmd.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/posit-icon-fullcolor.svg b/images/posit-icon-fullcolor.svg new file mode 100644 index 00000000..ec7f5525 --- /dev/null +++ b/images/posit-icon-fullcolor.svg @@ -0,0 +1,22 @@ + + + + + + From 989f77c963f9f97d4ad55ec3589b863846c13157 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Fri, 10 May 2024 20:55:01 -0400 Subject: [PATCH 05/67] Not sure what the start year should be here --- _quarto.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_quarto.yml b/_quarto.yml index 0c8bbe0c..19248660 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -26,7 +26,7 @@ website: repo-actions: [edit, issue] page-footer: left: | - Copyright © 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. + Copyright © 2???-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. center: | Posit Helm Charts right: From 61e6550506a1486e14b365ea5e8320c047515326 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 16:44:19 -0400 Subject: [PATCH 06/67] Home page updates --- index.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.qmd b/index.qmd index 435cdc7b..bc20cc3b 100644 --- a/index.qmd +++ b/index.qmd @@ -11,12 +11,12 @@ title: Posit Helm Charts 2. Add the Posit Helm repository: - ```console + ```{.bash} helm repo add rstudio https://helm.rstudio.com ``` 3. View charts: - ```console + ```{.bash} helm search repo rstudio ``` \ No newline at end of file From 5950a39120d0ed71e14ef6984293aaa02fc327fa Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 16:44:36 -0400 Subject: [PATCH 07/67] Initial workbench scrub - Editing pass - Heading changes in Examples --- charts/rstudio-workbench/README.md | 185 ++++++++---------- examples/examples.ejs | 4 +- .../application-configuration/index.qmd | 2 +- .../container-images/custom-images.qmd | 2 +- .../container-images/private-images.qmd | 2 +- 5 files changed, 87 insertions(+), 108 deletions(-) diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 01abf0ab..0acf0ee2 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -5,7 +5,7 @@ code-overflow: wrap ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Workbench_ +#### _Official Helm chart for Posit Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. @@ -45,7 +45,7 @@ helm search repo rstudio/rstudio-workbench -l To function, this chart requires the following: -* A license file, license key, or the address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the @@ -84,11 +84,10 @@ To function, this chart requires the following: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against directly placing it in your values file. +This chart supports activating the product using a *license file*. -### License file - -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend *against* directly placing the license file in your values file. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: @@ -111,37 +110,21 @@ Alternatively, license files can be set during `helm install` with the following --set-file license.file.contents=licenses/rstudio-workbench.lic ``` -### License key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument: - -```bash ---set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX -``` - -### License server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument: - -```bash ---set license.server= -``` - ## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. + valid `.ini` or `.dcf` file formats required by Workbench. - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. -- If you need to modify the jobs launched by RStudio Workbench, use `job-json-overrides`. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to get the service account information off of the RStudio Workbench pod for use in launching jobs. -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. - This is described in the [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values +These configuration values all take the form of usual Helm values so you can set the database password with similar to: ```bash @@ -161,63 +144,63 @@ The names of files are dynamically used, so you can add new files as needed. Bew so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change the `XDG_CONFIG_DIRS` environment variable. -- Session Configuration: - - Configuration files: `repos.conf`, `rsession.conf`, `notifications.conf` - - These configuration files are mounted into the server and - the session pods. - - Located in the `config.session.<< name of file >>` helm values - - Mounted at `/mnt/session-configmap/rstudio/` +- Session Configuration + - These configuration files are mounted into the server and + are mounted into the session pods. + - `repos.conf`, `rsession.conf`, `notifications.conf` + - Located in:
`config.session.<< name of file >>` Helm values + - Mounted at:
`/mnt/session-configmap/rstudio/` - Session Secret Configuration: - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
`config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
`/mnt/session-secret/` - Secret Configuration: - - These configuration files are mounted into the server with more restrictive permissions (0600) + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` + - Located in:
`config.secret.<< name of file >>` Helm values + - Mounted at:
`/mnt/secret-configmap/rstudio/` - Server Configuration: - - These configuration files are mounted into the server (.ini file format) + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` + - Located at:
`config.server.<< name of file >>` Helm values + - Mounted at:
`/mnt/configmap/rstudio/` - Server DCF Configuration: - - These configuration files are mounted into the server (.dcf file format) + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` + - Located at:
`config.serverDcf.<< name of file >>` Helm values + - Included at:
`/mnt/configmap/rstudio/` - Profiles Configuration: - - These configuration files are mounted into the server (.ini file format) + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the [Profiles](#rstudio-profiles) section below for more information + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
`/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. - Prestart: - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. - User Provisioning Configuration: - - These configuration files are used for configuring user provisioning (i.e., `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
`config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
`/etc/sssd/conf.d/` with `0600` permissions by default. - Custom Startup Configuration: - - `supervisord` service / unit definition `.conf` files - - Use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all configuration files above, can override with a verbatim string if desired: - - Located at `config.startupCustom.<< name of file >>` helm values: - ```yaml - config: - startupCustom: - myfile.conf: | - file-used-verbatim - ``` + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
`/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
`config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` - PAM configuration: - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` + - `pam` configuration files. + - Located at:
`config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
`/etc/pam.d/<< name of file >>` ### Configuring Python and R repositories @@ -228,17 +211,17 @@ pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mo - `launcher.useTemplates: true` is set - `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -```yaml -launcher: - useTemplates: true + ```yaml + launcher: + useTemplates: true -config: - session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co -``` + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` #### R repositories @@ -255,12 +238,12 @@ For more information about configuring CRAN repositories in Workbench, see the [ ## User provisioning -Provisioning users in RStudio Workbench containers is challenging. Session images create users automatically (with +Provisioning users in Workbench containers is challenging. Session images create users automatically (with consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) @@ -268,21 +251,22 @@ or a polling service (checks at regular intervals). Either can be written easily However, it is important to use caution for the following: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing can cause security issues and access by some users to access view they should not be allowed to see. -- Usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames. -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily. +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a +We do not provide such a service out of the box because we intend for Workbench to solve this problem in a future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For @@ -390,15 +374,11 @@ If you want to customize the job launch process (i.e., how sessions are defined) config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` ``` - Create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) becomes a configuration filename on disk. - - `json`: a YAML value that is translated directly to JSON and injected into the job spec at `target`. - -Several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md).x +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -420,7 +400,7 @@ config: ## Sealed secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): @@ -430,7 +410,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -579,4 +559,3 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - diff --git a/examples/examples.ejs b/examples/examples.ejs index 069909a4..4fdf632f 100644 --- a/examples/examples.ejs +++ b/examples/examples.ejs @@ -2,7 +2,7 @@ const postsByCategory = {}; const basicConfigPosts = []; items.forEach(item => { - if (item.category === "Basic Configuration") { + if (item.category === "Basic configuration") { basicConfigPosts.push(item) } else { if (!postsByCategory[item.category]) { @@ -14,7 +14,7 @@ items.forEach(item => { // Basic config first if (basicConfigPosts.length > 0) { %> -

Basic Configuration

+

Basic configuration

    <% basicConfigPosts.forEach(post => { %>
  • diff --git a/examples/workbench/application-configuration/index.qmd b/examples/workbench/application-configuration/index.qmd index 298a98ca..4551a908 100644 --- a/examples/workbench/application-configuration/index.qmd +++ b/examples/workbench/application-configuration/index.qmd @@ -1,5 +1,5 @@ --- -category: "Basic Configuration" +category: "Basic configuration" --- # Configuring Posit Workbench with Recommended Settings diff --git a/examples/workbench/container-images/custom-images.qmd b/examples/workbench/container-images/custom-images.qmd index df55c281..10ec1dab 100644 --- a/examples/workbench/container-images/custom-images.qmd +++ b/examples/workbench/container-images/custom-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Workbench with Custom Container Images diff --git a/examples/workbench/container-images/private-images.qmd b/examples/workbench/container-images/private-images.qmd index 886c926e..8a74b6cf 100644 --- a/examples/workbench/container-images/private-images.qmd +++ b/examples/workbench/container-images/private-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Workbench to Access Image Registries Requiring Authentication From d30fd76ddd827d37be8a7b2372c9d9eca6711da3 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:47:27 -0400 Subject: [PATCH 08/67] trying to standardize the content between the two files where I can --- charts/rstudio-connect/README.md | 77 +++++++++++++++--------------- charts/rstudio-workbench/README.md | 13 +++-- 2 files changed, 45 insertions(+), 45 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a44de207..f0f5dda9 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for RStudio Connect_ +#### _Official Helm chart for Posit Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. @@ -12,56 +12,63 @@ that are published by Data Scientists. Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. -## Installing the Chart + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.6.6: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-connect -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container - by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. + In this case, we recommend you: + * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + data in the container by using a + regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` + and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` +```{.bash} +kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic Second, specify the following values: @@ -74,29 +81,23 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-connect.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-connect.lic +``` -## General Principles +## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format required by rstudio-connect. - rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration File +## Configuration file The configuration values all take the form of usual helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 0acf0ee2..79dfc3f9 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -23,8 +23,7 @@ To ensure a stable production deployment: ::: * Before upgrading check for breaking changes using `helm diff upgrade`. -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes and the documentation below on how to use the chart. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. ## Installing the chart @@ -51,9 +50,9 @@ To function, this chart requires the following: * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: - * disable `homeStorage.create` and + * Disable `homeStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * mount them into the container by specifying + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your @@ -84,14 +83,14 @@ To function, this chart requires the following: ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a *license file*. - We recommend *against* directly placing the license file in your values file. - We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```bash +```{.bash} kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic ``` @@ -259,7 +258,7 @@ However, it is important to use caution for the following: - `supervisord` is configured by default to exit if any of its child processes exit. - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for Workbench to solve this problem in a +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a future release. Please contact your account representative if you have feedback or questions about this workflow. From f232c5b72dda5fde35471d7a97731737ff3bfded Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:48:32 -0400 Subject: [PATCH 09/67] helm fix --- charts/rstudio-connect/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index f0f5dda9..f02c37ea 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -94,7 +94,7 @@ required by rstudio-connect. ## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ```{.bash} From 1621561ae5a126be41306ddb88c2d6101b2ec909 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:53:30 -0400 Subject: [PATCH 10/67] Not sure if these should be formatted or not but I did it just in case --- charts/rstudio-connect/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index f02c37ea..860aaea9 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -88,8 +88,8 @@ Alternatively, license files can be set during `helm install` with the following ## General principles - In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by rstudio-connect. -- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +required by `rstudio-connect`. +- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration file From 6180e699ae90f24e2599c90ea7beb855e254c1e9 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:57:36 -0400 Subject: [PATCH 11/67] Minor edits to the configuration files --- examples/connect/application-configuration/index.qmd | 2 +- examples/connect/beta-migration/index.qmd | 2 +- examples/connect/container-images/custom-images.qmd | 2 +- examples/connect/container-images/private-images.qmd | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/connect/application-configuration/index.qmd b/examples/connect/application-configuration/index.qmd index 2ceb80c6..c8475c97 100644 --- a/examples/connect/application-configuration/index.qmd +++ b/examples/connect/application-configuration/index.qmd @@ -1,5 +1,5 @@ --- -category: "Basic Configuration" +category: "Basic configuration" --- # Configuring Posit Connect with Recommended Settings diff --git a/examples/connect/beta-migration/index.qmd b/examples/connect/beta-migration/index.qmd index 2993a3eb..99e81200 100644 --- a/examples/connect/beta-migration/index.qmd +++ b/examples/connect/beta-migration/index.qmd @@ -1,5 +1,5 @@ --- -category: "Beta Migration" +category: "Beta migration" --- # Off-Host Execution Beta User Migration diff --git a/examples/connect/container-images/custom-images.qmd b/examples/connect/container-images/custom-images.qmd index 5407c999..0b73badc 100644 --- a/examples/connect/container-images/custom-images.qmd +++ b/examples/connect/container-images/custom-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Connect with Custom Container Images diff --git a/examples/connect/container-images/private-images.qmd b/examples/connect/container-images/private-images.qmd index 6d387753..cfad496b 100644 --- a/examples/connect/container-images/private-images.qmd +++ b/examples/connect/container-images/private-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Connect to Access Image Registries Requiring Authentication From f1f8a24ff672a4161c09826c147941d38e2d0916 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 21:23:26 -0400 Subject: [PATCH 12/67] Missed heading change --- charts/rstudio-connect/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 860aaea9..bd2bd796 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -7,7 +7,7 @@ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and From 2f87134bb1db9640f6748bb3cffc59ba40f98a1f Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 21:27:03 -0400 Subject: [PATCH 13/67] Start of ppm edits --- charts/rstudio-pm/README.md | 41 +++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index b6f9d265..5e29c092 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,46 +2,51 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Package Manager_ +#### _Official Helm chart for Posit Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.5.25: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-pm -l ``` -## Upgrade Guidance +## Upgrade guidance ### 0.4.0 -- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to - fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. +* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`) +* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. + * To disable an automatic fixup / hook, set `enableMigrations=false`. -## Required Configuration +## Required configuration This chart requires the following in order to function: From be870e75c1464dcaf9256a4d39c7fc2fc7ffae50 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 12:33:26 +0000 Subject: [PATCH 14/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 83 ++++--- charts/rstudio-workbench/README.md | 379 ++++++++++++++--------------- 2 files changed, 225 insertions(+), 237 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 860aaea9..a44de207 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for Posit Connect_ +#### _Official Helm chart for RStudio Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. @@ -12,63 +12,56 @@ that are published by Data Scientists. Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether Helm is a good choice for your deployment. +if you need help deciding whether helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* "Pin" the version of the Helm chart that you are using. You can do - this using the: - * `helm dependency` command and the associated "Chart.lock" files _or_ - * the `--version` flag. +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check + for breaking changes +* Read [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart - :::{.callout-important} - This protects you from breaking changes** - ::: - -* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.6.6: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-connect -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you: - * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your - data in the container by using a - regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` - and `pod.volumeMounts`. + In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic +`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` Second, specify the following values: @@ -81,23 +74,29 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-connect.lic -``` +`--set-file license.file.contents=licenses/rstudio-connect.lic` -## General principles +### License Key -- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by `rstudio-connect`. -- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles + +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +required by rstudio-connect. +- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration file +## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: -```{.bash} +``` ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 79dfc3f9..9cda63d7 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,31 +1,25 @@ ---- -title: Posit Workbench -code-overflow: wrap ---- +# Posit Workbench ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Workbench_ +#### _Official Helm chart for RStudio Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.7.3: @@ -35,64 +29,59 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: - -```bash +``` helm search repo rstudio/rstudio-workbench -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: - * Disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: - - ```yaml - config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap - ``` +```yaml +config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap +``` ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File -- We recommend *against* directly placing the license file in your values file. -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic -``` +`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` Second, specify the following values: @@ -105,32 +94,39 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```bash ---set-file license.file.contents=licenses/rstudio-workbench.lic -``` +`--set-file license.file.contents=licenses/rstudio-workbench.lic` + +### License Key + +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. -## General principles +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by Workbench. - - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. -- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. - - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). -- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. -- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. - - This is described in the - [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. + valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are + below. +- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below + and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) + on the topic in general. +- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: + - Get the service account information off of the RStudio Workbench pod for use in launching jobs +- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter + [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration files -These configuration values all take the form of usual Helm values -so you can set the database password with similar to: +These configuration values all take the form of usual helm values +so you can set the database password with something like: -```bash +``` ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -140,135 +136,130 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change -the `XDG_CONFIG_DIRS` environment variable. +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change +the `XDG_CONFIG_DIRS` environment variable - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods. + are mounted into the session pods as well. - `repos.conf`, `rsession.conf`, `notifications.conf` - - Located in:
    `config.session.<< name of file >>` Helm values - - Mounted at:
    `/mnt/session-configmap/rstudio/` -- Session Secret Configuration: - - These configuration files are mounted into the server and session pods. - - `odbc.ini` and other similar shared secrets. - - Located in:
    `config.sessionSecret.<< name of file>>` Helm values - - Mounted at:
    `/mnt/session-secret/` -- Secret Configuration: - - These configuration files are mounted into the server with more restrictive permissions (0600). + - located in the `config.session.<< name of file >>` helm values + - mounted at `/mnt/session-configmap/rstudio/` +- Session Secret Configuration + - These configuration files are mounted into the server and session pods as well + - `odbc.ini` and other similar shared secrets + - located in `config.sessionSecret.<< name of file>>` helm values + - mounted at `/mnt/session-secret/` +- Secret Configuration + - These configuration files are mounted into the server with more restrictive permissions (0600) - `database.conf`, `openid-client-secret`, `databricks.conf` - - Located in:
    `config.secret.<< name of file >>` Helm values - - Mounted at:
    `/mnt/secret-configmap/rstudio/` -- Server Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located in the `config.secret.<< name of file >>` helm values + - mounted at `/mnt/secret-configmap/rstudio/` +- Server Configuration + - These configuration files are mounted into the server (.ini file format) - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - Located at:
    `config.server.<< name of file >>` Helm values - - Mounted at:
    `/mnt/configmap/rstudio/` -- Server DCF Configuration: - - These configuration files are mounted into the server (.dcf file format). + - They are located at `config.server.<< name of file >>` helm values + - mounted at `/mnt/configmap/rstudio/` +- Server DCF Configuration + - These configuration files are mounted into the server (.dcf file format) - `launcher-mounts`, `launcher-env` - - Located at:
    `config.serverDcf.<< name of file >>` Helm values - - Included at:
    `/mnt/configmap/rstudio/` -- Profiles Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located at `config.serverDcf.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` +- Profiles Configuration + - These configuration files are mounted into the server (.ini file format) - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` Helm values - - Included at:
    `/mnt/configmap/rstudio/` - - See the [Profiles](#rstudio-profiles) section below for more information. -- Prestart: - - This is provided by the Helm chart in a configmap. - - It is mounted into the pod at `/scripts/`. - - `prestart-workbench.bash` is used to start workbench. - - `prestart-launcher.bash` is used to start launcher. -- User Provisioning Configuration: - - These configuration files are used for configuring user provisioning (i.e., `sssd`). - - Located at:
    `config.userProvisioning.<< name of file >>` Helm values - - Mounted onto:
    `/etc/sssd/conf.d/` with `0600` permissions by default. -- Custom Startup Configuration: - - `supervisord` service / unit definition `.conf` files. - - Use the `.ini` file format by default. - - Mounted at:
    `/startup/custom` - - As with all configuration files above, you can override with a verbatim string if desired: - - Located at:
    `config.startupCustom.<< name of file >>` Helm values: - ```yaml - config: - startupCustom: - myfile.conf: | - file-used-verbatim - ``` -- PAM configuration: - - `pam` configuration files. - - Located at:
    `config.pam.<< name of file >>` Helm values - - Mounted verbatim as individual files (using `subPath` mounts) at:
    `/etc/pam.d/<< name of file >>` - -### Configuring Python and R repositories - -#### Python repositories - -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: - -- `launcher.useTemplates: true` is set -- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: - - ```yaml - launcher: - useTemplates: true + - They are located at `config.profiles.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` + - See the `Profiles` section below for more information +- Prestart + - This is provided by the helm chart in a configmap + - It is mounted into the pod at `/scripts/` + - `prestart-workbench.bash` is used to start workbench + - `prestart-launcher.bash` is used to start launcher +- User Provisioning Configuration + - These configuration files are used for configuring user provisioning (i.e. `sssd`) + - Located at `config.userProvisioning.<< name of file >>` helm values + - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default +- Custom Startup Configuration + - `supervisord` service / unit definition `.conf` files + - Located at `config.startupCustom.<< name of file >>` helm values + - Will use the `.ini` file format, by default + - Mounted at `/startup/custom` + - As with all config files above, can override with a verbatim string if desired, like so: +```yaml +config: + startupCustom: + myfile.conf: | + file-used-verbatim +``` +- PAM configuration + - `pam` configuration files + - Located at `config.pam.<< name of file >>` helm values + - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - config: - session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co - ``` +### Configuring R and Python repositories #### R repositories -R package repositories can be configured with `config.session.repos.conf`: +R package repositories can be configured with `config.session.repos.conf`. -```yaml +``` config: session: repos.conf: CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. +For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). -## User provisioning +#### Python repositories + +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. -Provisioning users in Workbench containers is challenging. Session images create users automatically (with -consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the -administrator. +``` +launcher: + useTemplates: true + +config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co +``` + +## User Provisioning + +Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with +consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the +administrator today. The most common way to provision users is via `sssd`. -The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. +However, it is important to be careful of a few points: -However, it is important to use caution for the following: - -- UID / GID consistency: - - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. - - Failing can cause security issues and access by some users to access view they should not be allowed to see. -- Usernames cannot have `@`. - - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. -- `supervisord` is configured by default to exit if any of its child processes exit. - - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. +- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across + time. Failing this can cause security issues and access by some users to files they should not be allowed to see +- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because + some operating systems disallow `@` signs in linux usernames +- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` + to configure a user management service, be careful that it does not exit unnecessarily -We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a -future release. Please contact your account representative if you have feedback or questions about this +We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a +future release. Please get in touch with your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -288,17 +279,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- If section header is `[*]`, it applies to all users. -- If a user's username is `myusername`, the section `[myusername]` applies to them. -- If a user is in the `allusers` group, then the section `[@allusers]` applies to them +- if section header is `[*]`, it applies to all users +- if a user's username is `myusername`, the section `[myusername]` will apply to them +- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. -In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: +In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: ```yaml config: @@ -321,17 +312,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` +- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` - ```yaml - some-key: - - value1 - - value2 - ``` +```yaml +some-key: + - value1 + - value2 +``` -- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -348,7 +339,6 @@ config: - value4 - value5 ``` - Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -360,24 +350,23 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -:::{.callout-note} -This appending/concatenation/array translation behavior only works with the helm chart. -::: +> NOTE: this appending/concatenation/array translation behavior only works with the helm chart -### Job Json overrides +### Job Json Overrides -If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: +If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following +configuration: + - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + - create an array of maps with the following keys: + - `target`: the "target" part of the job spec to replace + - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk + - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` -- Modify: - ```yaml - config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - ``` -- Create an array of maps with the following keys: - - `target`: The "target" part of the job spec to replace. - - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. - - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. +Note that several examples are provided +in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) +(however, examples do not use the helm chart syntax there). -Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. +Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) ```yaml config: @@ -397,11 +386,10 @@ config: - "two-image:tag ``` -## Sealed secrets +## Sealed Secrets +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. - -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. - `config.secret` - `config.sessionSecret` @@ -409,7 +397,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -558,3 +546,4 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + From f94d21b8a92df8a9f85b07564f382c9afc1eef48 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:35:13 -0400 Subject: [PATCH 15/67] PPM edits --- charts/rstudio-pm/README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 5e29c092..fde9eb3e 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -136,12 +136,12 @@ should be avoided if at all possible. ## General Principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration File -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -202,7 +202,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | | resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | | rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | @@ -232,8 +232,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - From 93c1265bb58af4cabad7a722985cafcf91fd9ee4 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 12:36:27 +0000 Subject: [PATCH 16/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 50 +++++++++++++++----------------- 2 files changed, 24 insertions(+), 28 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 066cd564..a44de207 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -7,7 +7,7 @@ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best practices +## Best Practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index fde9eb3e..b6f9d265 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,51 +2,46 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Package Manager_ +#### _Official Helm chart for RStudio Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.5.25: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-pm -l ``` -## Upgrade guidance +## Upgrade Guidance ### 0.4.0 -* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`) -* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. - * To disable an automatic fixup / hook, set `enableMigrations=false`. +- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to + fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. -## Required configuration +## Required Configuration This chart requires the following in order to function: @@ -136,12 +131,12 @@ should be avoided if at all possible. ## General Principles -- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: ``` @@ -202,7 +197,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | | resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | | rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | @@ -232,7 +227,8 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + From 6c276584693292f2293e0b5412c8f01f642ae7b3 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:37:53 -0400 Subject: [PATCH 17/67] Revert "Update helm-docs and README.md" This reverts commit 93c1265bb58af4cabad7a722985cafcf91fd9ee4. --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 50 +++++++++++++++++--------------- 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a44de207..066cd564 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -7,7 +7,7 @@ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index b6f9d265..fde9eb3e 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,46 +2,51 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Package Manager_ +#### _Official Helm chart for Posit Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.5.25: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-pm -l ``` -## Upgrade Guidance +## Upgrade guidance ### 0.4.0 -- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to - fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. +* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`) +* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. + * To disable an automatic fixup / hook, set `enableMigrations=false`. -## Required Configuration +## Required configuration This chart requires the following in order to function: @@ -131,12 +136,12 @@ should be avoided if at all possible. ## General Principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration File -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -197,7 +202,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | | resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | | rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | @@ -227,8 +232,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - From 016f4e5bc94e261bc0425070be188919130ac71f Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:41:46 -0400 Subject: [PATCH 18/67] Revert "Merge branch 'ah/editing-pass' of https://github.com/rstudio/helm into ah/editing-pass" This reverts commit 8713b44aabd5648808c214f4d0ffea886bd39ef3, reversing changes made to 2f87134bb1db9640f6748bb3cffc59ba40f98a1f. --- charts/rstudio-connect/README.md | 83 +++---- charts/rstudio-workbench/README.md | 379 +++++++++++++++-------------- 2 files changed, 237 insertions(+), 225 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 066cd564..bd2bd796 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for RStudio Connect_ +#### _Official Helm chart for Posit Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. @@ -12,56 +12,63 @@ that are published by Data Scientists. Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. -## Installing the Chart + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.6.6: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-connect -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container - by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. + In this case, we recommend you: + * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + data in the container by using a + regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` + and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` +```{.bash} +kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic Second, specify the following values: @@ -74,29 +81,23 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-connect.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-connect.lic +``` -## General Principles +## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format -required by rstudio-connect. -- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format +required by `rstudio-connect`. +- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration File +## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9cda63d7..79dfc3f9 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,25 +1,31 @@ -# Posit Workbench +--- +title: Posit Workbench +code-overflow: wrap +--- ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Workbench_ +#### _Official Helm chart for Posit Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.7.3: @@ -29,59 +35,64 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: -``` + +```bash helm search repo rstudio/rstudio-workbench -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * Disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` -## Licensing + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +## Licensing -### License File +This chart supports activating the product using a *license file*. -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend *against* directly placing the license file in your values file. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` +```{.bash} +kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic +``` Second, specify the following values: @@ -94,39 +105,32 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-workbench.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```bash +--set-file license.file.contents=licenses/rstudio-workbench.lic +``` -## General Principles +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values -so you can set the database password with something like: +These configuration values all take the form of usual Helm values +so you can set the database password with similar to: -``` +```bash ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -136,130 +140,135 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods as well. + are mounted into the session pods. - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` -- Secret Configuration - - These configuration files are mounted into the server with more restrictive permissions (0600) + - Located in:
    `config.session.<< name of file >>` Helm values + - Mounted at:
    `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
    `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
    `/mnt/session-secret/` +- Secret Configuration: + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration - - These configuration files are mounted into the server (.ini file format) + - Located in:
    `config.secret.<< name of file >>` Helm values + - Mounted at:
    `/mnt/secret-configmap/rstudio/` +- Server Configuration: + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration - - These configuration files are mounted into the server (.dcf file format) + - Located at:
    `config.server.<< name of file >>` Helm values + - Mounted at:
    `/mnt/configmap/rstudio/` +- Server DCF Configuration: + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` -- Profiles Configuration - - These configuration files are mounted into the server (.ini file format) + - Located at:
    `config.serverDcf.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` +- Profiles Configuration: + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration - - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - -### Configuring R and Python repositories + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. +- Prestart: + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
    `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
    `/etc/sssd/conf.d/` with `0600` permissions by default. +- Custom Startup Configuration: + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
    `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
    `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: + - `pam` configuration files. + - Located at:
    `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
    `/etc/pam.d/<< name of file >>` + +### Configuring Python and R repositories -#### R repositories +#### Python repositories -R package repositories can be configured with `config.session.repos.conf`. +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + ```yaml + launcher: + useTemplates: true -#### Python repositories + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +#### R repositories -``` -launcher: - useTemplates: true +R package repositories can be configured with `config.session.repos.conf`: +```yaml config: session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -## User Provisioning +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +## User provisioning + +Provisioning users in Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily +However, it is important to use caution for the following: + +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -279,17 +288,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -312,17 +321,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -339,6 +348,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -350,23 +360,24 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: -### Job Json Overrides +### Job Json overrides -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -Note that several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -386,10 +397,11 @@ config: - "two-image:tag ``` -## Sealed Secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +## Sealed secrets -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. + +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -397,7 +409,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -546,4 +558,3 @@ Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - From b04bd80996d7d318e9086cb4be15da85b3515555 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:59:31 -0400 Subject: [PATCH 19/67] additional readme edits --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 45 +++++++++++++----------------- charts/rstudio-workbench/README.md | 7 ++--- 3 files changed, 24 insertions(+), 30 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index bd2bd796..a06044aa 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -63,7 +63,7 @@ To function, this chart requires the following: This chart supports activating the product using a *license file*. -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index fde9eb3e..912d5039 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -50,7 +50,7 @@ helm search repo rstudio/rstudio-pm -l This chart requires the following in order to function: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for RSPM. * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. @@ -62,15 +62,16 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +This chart supports activating the product using a *license file*. -### License File -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic` +```{.bash} +kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic +``` Second, specify the following values: @@ -83,17 +84,11 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-pm.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-pm.lic +``` -## S3 Configuration +## S3 configuration Package Manager [can be configured to store its data in S3 buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), @@ -131,20 +126,20 @@ awsAccessKeyId: your-access-key-id awsSecretAccessKey: your-secret-access-key ``` -Bear in mind that static, long-lived credentials are the least secure option and +Consider that static, long-lived credentials are the least secure option and should be avoided if at all possible. -## General Principles +## General principles -- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format -required by rstudio-pm. +In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format +required by `rstudio-pm`. -## Configuration File +## Configuration file The configuration values all take the form of usual Helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` @@ -159,7 +154,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | awsAccessKeyId | bool | `false` | awsAccessKeyId is the access key id for s3 access, used also to gate file creation | | awsSecretAccessKey | string | `nil` | awsSecretAccessKey is the secret access key, needs to be filled if access_key_id is | | command | bool | `false` | command is the pod's run command. By default, it uses the container's default | -| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the rstudio-pm.gcfg file | +| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the `rstudio-pm`.gcfg file | | enableMigration | bool | `true` | Enable migrations for shared storage (if necessary) using Helm hooks. | | enableSandboxing | bool | `true` | Enable sandboxing of Git builds, which requires elevated security privileges for the Package Manager container. | | extraContainers | list | `[]` | sidecar container list | @@ -190,7 +185,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | pod.annotations | object | `{}` | annotations is a map of keys / values that will be added as annotations to the pods | | pod.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"runAsNonRoot":true,"runAsUser":999,"seccompProfile":{"type":"{{ if .Values.enableSandboxing }}Unconfined{{ else }}RuntimeDefault{{ end }}"}}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the main Package Manager container. Evaluated as a template. | | pod.env | list | `[]` | env is an array of maps that is injected as-is into the "env:" component of the pod.container spec | -| pod.labels | object | `{}` | Additional labels to add to the rstudio-pm pods | +| pod.labels | object | `{}` | Additional labels to add to the `rstudio-pm` pods | | pod.lifecycle | object | `{}` | Container [lifecycle hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/) | | pod.securityContext | object | `{}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the pod | | pod.serviceAccountName | string | `""` | Deprecated, use `serviceAccount.name` instead | @@ -201,9 +196,9 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | priorityClassName | string | `""` | The pod's priorityClassName | | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | -| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | +| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the `rstudio-pm` pod | | rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | -| rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | +| rstudioPMKey | bool | `false` | rstudioPMKey is the `rstudio-pm` key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | | service.loadBalancerIP | string | `""` | The external IP to use with `service.type` LoadBalancer, when supported by the cloud provider | diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 79dfc3f9..a2053022 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -85,8 +85,7 @@ To function, this chart requires the following: This chart supports activating the product using a *license file*. -- We recommend *against* directly placing the license file in your values file. -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: @@ -105,7 +104,7 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```bash +```{.bash} --set-file license.file.contents=licenses/rstudio-workbench.lic ``` @@ -126,7 +125,7 @@ Alternatively, license files can be set during `helm install` with the following These configuration values all take the form of usual Helm values so you can set the database password with similar to: -```bash +```{.bash} ... --set config.secret.database\.conf.password=mypassword ... ``` From 4538db93a26f70453817e4dd8f34f9488ffa4dcc Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 12:59:51 +0000 Subject: [PATCH 20/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 83 ++++--- charts/rstudio-pm/README.md | 93 +++---- charts/rstudio-workbench/README.md | 376 ++++++++++++++--------------- 3 files changed, 271 insertions(+), 281 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a06044aa..a44de207 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,73 +2,66 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for Posit Connect_ +#### _Official Helm chart for RStudio Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best practices +## Best Practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether Helm is a good choice for your deployment. +if you need help deciding whether helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* "Pin" the version of the Helm chart that you are using. You can do - this using the: - * `helm dependency` command and the associated "Chart.lock" files _or_ - * the `--version` flag. +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check + for breaking changes +* Read [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart - :::{.callout-important} - This protects you from breaking changes** - ::: - -* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.6.6: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-connect -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you: - * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your - data in the container by using a - regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` - and `pod.volumeMounts`. + In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic +`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` Second, specify the following values: @@ -81,23 +74,29 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-connect.lic -``` +`--set-file license.file.contents=licenses/rstudio-connect.lic` -## General principles +### License Key -- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by `rstudio-connect`. -- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles + +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +required by rstudio-connect. +- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration file +## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: -```{.bash} +``` ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 912d5039..b6f9d265 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,55 +2,50 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Package Manager_ +#### _Official Helm chart for RStudio Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.5.25: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-pm -l ``` -## Upgrade guidance +## Upgrade Guidance ### 0.4.0 -* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`) -* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. - * To disable an automatic fixup / hook, set `enableMigrations=false`. +- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to + fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. -## Required configuration +## Required Configuration This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for RSPM. * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. @@ -62,16 +57,15 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +### License File -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic -``` +`kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic` Second, specify the following values: @@ -84,11 +78,17 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-pm.lic -``` +`--set-file license.file.contents=licenses/rstudio-pm.lic` + +### License Key -## S3 configuration +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## S3 Configuration Package Manager [can be configured to store its data in S3 buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), @@ -126,20 +126,20 @@ awsAccessKeyId: your-access-key-id awsSecretAccessKey: your-secret-access-key ``` -Consider that static, long-lived credentials are the least secure option and +Bear in mind that static, long-lived credentials are the least secure option and should be avoided if at all possible. -## General principles +## General Principles -In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by `rstudio-pm`. +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +required by rstudio-pm. -## Configuration file +## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: -```{.bash} +``` ... --set config.Postgres.Password=mypassword ... ``` @@ -154,7 +154,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | awsAccessKeyId | bool | `false` | awsAccessKeyId is the access key id for s3 access, used also to gate file creation | | awsSecretAccessKey | string | `nil` | awsSecretAccessKey is the secret access key, needs to be filled if access_key_id is | | command | bool | `false` | command is the pod's run command. By default, it uses the container's default | -| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the `rstudio-pm`.gcfg file | +| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the rstudio-pm.gcfg file | | enableMigration | bool | `true` | Enable migrations for shared storage (if necessary) using Helm hooks. | | enableSandboxing | bool | `true` | Enable sandboxing of Git builds, which requires elevated security privileges for the Package Manager container. | | extraContainers | list | `[]` | sidecar container list | @@ -185,7 +185,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | pod.annotations | object | `{}` | annotations is a map of keys / values that will be added as annotations to the pods | | pod.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"runAsNonRoot":true,"runAsUser":999,"seccompProfile":{"type":"{{ if .Values.enableSandboxing }}Unconfined{{ else }}RuntimeDefault{{ end }}"}}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the main Package Manager container. Evaluated as a template. | | pod.env | list | `[]` | env is an array of maps that is injected as-is into the "env:" component of the pod.container spec | -| pod.labels | object | `{}` | Additional labels to add to the `rstudio-pm` pods | +| pod.labels | object | `{}` | Additional labels to add to the rstudio-pm pods | | pod.lifecycle | object | `{}` | Container [lifecycle hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/) | | pod.securityContext | object | `{}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the pod | | pod.serviceAccountName | string | `""` | Deprecated, use `serviceAccount.name` instead | @@ -196,9 +196,9 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | priorityClassName | string | `""` | The pod's priorityClassName | | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | -| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the `rstudio-pm` pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | -| rstudioPMKey | bool | `false` | rstudioPMKey is the `rstudio-pm` key used for the RStudio Package Manager service | +| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | +| rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | | service.loadBalancerIP | string | `""` | The external IP to use with `service.type` LoadBalancer, when supported by the cloud provider | @@ -227,7 +227,8 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index a2053022..9cda63d7 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,31 +1,25 @@ ---- -title: Posit Workbench -code-overflow: wrap ---- +# Posit Workbench ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Workbench_ +#### _Official Helm chart for RStudio Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.7.3: @@ -35,63 +29,59 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: - -```bash +``` helm search repo rstudio/rstudio-workbench -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: - * Disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: - - ```yaml - config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap - ``` +```yaml +config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap +``` ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic -``` +`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` Second, specify the following values: @@ -104,32 +94,39 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-workbench.lic -``` +`--set-file license.file.contents=licenses/rstudio-workbench.lic` -## General principles +### License Key + +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by Workbench. - - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. -- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. - - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). -- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. -- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. - - This is described in the - [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. + valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are + below. +- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below + and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) + on the topic in general. +- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: + - Get the service account information off of the RStudio Workbench pod for use in launching jobs +- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter + [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration files -These configuration values all take the form of usual Helm values -so you can set the database password with similar to: +These configuration values all take the form of usual helm values +so you can set the database password with something like: -```{.bash} +``` ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -139,135 +136,130 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change -the `XDG_CONFIG_DIRS` environment variable. +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change +the `XDG_CONFIG_DIRS` environment variable - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods. + are mounted into the session pods as well. - `repos.conf`, `rsession.conf`, `notifications.conf` - - Located in:
    `config.session.<< name of file >>` Helm values - - Mounted at:
    `/mnt/session-configmap/rstudio/` -- Session Secret Configuration: - - These configuration files are mounted into the server and session pods. - - `odbc.ini` and other similar shared secrets. - - Located in:
    `config.sessionSecret.<< name of file>>` Helm values - - Mounted at:
    `/mnt/session-secret/` -- Secret Configuration: - - These configuration files are mounted into the server with more restrictive permissions (0600). + - located in the `config.session.<< name of file >>` helm values + - mounted at `/mnt/session-configmap/rstudio/` +- Session Secret Configuration + - These configuration files are mounted into the server and session pods as well + - `odbc.ini` and other similar shared secrets + - located in `config.sessionSecret.<< name of file>>` helm values + - mounted at `/mnt/session-secret/` +- Secret Configuration + - These configuration files are mounted into the server with more restrictive permissions (0600) - `database.conf`, `openid-client-secret`, `databricks.conf` - - Located in:
    `config.secret.<< name of file >>` Helm values - - Mounted at:
    `/mnt/secret-configmap/rstudio/` -- Server Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located in the `config.secret.<< name of file >>` helm values + - mounted at `/mnt/secret-configmap/rstudio/` +- Server Configuration + - These configuration files are mounted into the server (.ini file format) - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - Located at:
    `config.server.<< name of file >>` Helm values - - Mounted at:
    `/mnt/configmap/rstudio/` -- Server DCF Configuration: - - These configuration files are mounted into the server (.dcf file format). + - They are located at `config.server.<< name of file >>` helm values + - mounted at `/mnt/configmap/rstudio/` +- Server DCF Configuration + - These configuration files are mounted into the server (.dcf file format) - `launcher-mounts`, `launcher-env` - - Located at:
    `config.serverDcf.<< name of file >>` Helm values - - Included at:
    `/mnt/configmap/rstudio/` -- Profiles Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located at `config.serverDcf.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` +- Profiles Configuration + - These configuration files are mounted into the server (.ini file format) - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` Helm values - - Included at:
    `/mnt/configmap/rstudio/` - - See the [Profiles](#rstudio-profiles) section below for more information. -- Prestart: - - This is provided by the Helm chart in a configmap. - - It is mounted into the pod at `/scripts/`. - - `prestart-workbench.bash` is used to start workbench. - - `prestart-launcher.bash` is used to start launcher. -- User Provisioning Configuration: - - These configuration files are used for configuring user provisioning (i.e., `sssd`). - - Located at:
    `config.userProvisioning.<< name of file >>` Helm values - - Mounted onto:
    `/etc/sssd/conf.d/` with `0600` permissions by default. -- Custom Startup Configuration: - - `supervisord` service / unit definition `.conf` files. - - Use the `.ini` file format by default. - - Mounted at:
    `/startup/custom` - - As with all configuration files above, you can override with a verbatim string if desired: - - Located at:
    `config.startupCustom.<< name of file >>` Helm values: - ```yaml - config: - startupCustom: - myfile.conf: | - file-used-verbatim - ``` -- PAM configuration: - - `pam` configuration files. - - Located at:
    `config.pam.<< name of file >>` Helm values - - Mounted verbatim as individual files (using `subPath` mounts) at:
    `/etc/pam.d/<< name of file >>` - -### Configuring Python and R repositories - -#### Python repositories - -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: - -- `launcher.useTemplates: true` is set -- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: - - ```yaml - launcher: - useTemplates: true + - They are located at `config.profiles.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` + - See the `Profiles` section below for more information +- Prestart + - This is provided by the helm chart in a configmap + - It is mounted into the pod at `/scripts/` + - `prestart-workbench.bash` is used to start workbench + - `prestart-launcher.bash` is used to start launcher +- User Provisioning Configuration + - These configuration files are used for configuring user provisioning (i.e. `sssd`) + - Located at `config.userProvisioning.<< name of file >>` helm values + - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default +- Custom Startup Configuration + - `supervisord` service / unit definition `.conf` files + - Located at `config.startupCustom.<< name of file >>` helm values + - Will use the `.ini` file format, by default + - Mounted at `/startup/custom` + - As with all config files above, can override with a verbatim string if desired, like so: +```yaml +config: + startupCustom: + myfile.conf: | + file-used-verbatim +``` +- PAM configuration + - `pam` configuration files + - Located at `config.pam.<< name of file >>` helm values + - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - config: - session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co - ``` +### Configuring R and Python repositories #### R repositories -R package repositories can be configured with `config.session.repos.conf`: +R package repositories can be configured with `config.session.repos.conf`. -```yaml +``` config: session: repos.conf: CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. +For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + +#### Python repositories + +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. + +``` +launcher: + useTemplates: true + +config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co +``` -## User provisioning +## User Provisioning -Provisioning users in Workbench containers is challenging. Session images create users automatically (with -consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the -administrator. +Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with +consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the +administrator today. The most common way to provision users is via `sssd`. -The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. +However, it is important to be careful of a few points: -However, it is important to use caution for the following: - -- UID / GID consistency: - - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. - - Failing can cause security issues and access by some users to access view they should not be allowed to see. -- Usernames cannot have `@`. - - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. -- `supervisord` is configured by default to exit if any of its child processes exit. - - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. +- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across + time. Failing this can cause security issues and access by some users to files they should not be allowed to see +- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because + some operating systems disallow `@` signs in linux usernames +- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` + to configure a user management service, be careful that it does not exit unnecessarily -We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a -future release. Please contact your account representative if you have feedback or questions about this +We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a +future release. Please get in touch with your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -287,17 +279,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- If section header is `[*]`, it applies to all users. -- If a user's username is `myusername`, the section `[myusername]` applies to them. -- If a user is in the `allusers` group, then the section `[@allusers]` applies to them +- if section header is `[*]`, it applies to all users +- if a user's username is `myusername`, the section `[myusername]` will apply to them +- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. -In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: +In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: ```yaml config: @@ -320,17 +312,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` +- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` - ```yaml - some-key: - - value1 - - value2 - ``` +```yaml +some-key: + - value1 + - value2 +``` -- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -347,7 +339,6 @@ config: - value4 - value5 ``` - Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -359,24 +350,23 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -:::{.callout-note} -This appending/concatenation/array translation behavior only works with the helm chart. -::: +> NOTE: this appending/concatenation/array translation behavior only works with the helm chart -### Job Json overrides +### Job Json Overrides -If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: +If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following +configuration: + - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + - create an array of maps with the following keys: + - `target`: the "target" part of the job spec to replace + - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk + - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` -- Modify: - ```yaml - config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - ``` -- Create an array of maps with the following keys: - - `target`: The "target" part of the job spec to replace. - - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. - - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. +Note that several examples are provided +in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) +(however, examples do not use the helm chart syntax there). -Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. +Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) ```yaml config: @@ -396,11 +386,10 @@ config: - "two-image:tag ``` -## Sealed secrets +## Sealed Secrets +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. - -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. - `config.secret` - `config.sessionSecret` @@ -408,7 +397,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -557,3 +546,4 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + From fbd17da6e6e1ad1d80ab0cdb512d77bcd97fa564 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 09:04:33 -0400 Subject: [PATCH 21/67] ppm examples --- examples/package-manager/container-images/custom-images.qmd | 2 +- examples/package-manager/container-images/private-images.qmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/package-manager/container-images/custom-images.qmd b/examples/package-manager/container-images/custom-images.qmd index ef765035..b8fbb38d 100644 --- a/examples/package-manager/container-images/custom-images.qmd +++ b/examples/package-manager/container-images/custom-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Package Manager with Custom Container Images diff --git a/examples/package-manager/container-images/private-images.qmd b/examples/package-manager/container-images/private-images.qmd index 5f9dd663..112614eb 100644 --- a/examples/package-manager/container-images/private-images.qmd +++ b/examples/package-manager/container-images/private-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Package Manager to Access Image Registries Requiring Authentication From 2ba00b07a0e52f1ee5c5ecdbd4f9565891b3d798 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 09:12:29 -0400 Subject: [PATCH 22/67] standardizing the before you begin --- charts/rstudio-pm/README.md | 2 +- charts/rstudio-workbench/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 912d5039..c50854a6 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -19,7 +19,7 @@ To ensure a stable production deployment: This protects you from breaking changes. ::: -* Before upgrading check for breaking changes using `helm diff upgrade`. +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. * Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. ## Installing the chart diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index a2053022..d533e169 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -22,7 +22,7 @@ To ensure a stable production deployment: This protects you from breaking changes. ::: -* Before upgrading check for breaking changes using `helm diff upgrade`. +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. * Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. ## Installing the chart From 40dc2cc1f3b48a9460abfe6deebeff920bd357c9 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:07:20 -0400 Subject: [PATCH 23/67] Chronicle edits --- charts/posit-chronicle/README.md | 58 +++++++++++++++++--------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index fd9522a1..308f3f3d 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -8,40 +8,43 @@ Chronicle helps data science managers and other stakeholders understand their organization's use of other Posit products, primarily Posit Connect and Workbench. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.3.0: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.0 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/posit-chronicle -l ``` ## Usage This chart deploys only the Chronicle server and is meant to be used in tandem -with the Workbench and Connect charts. To actually send data to the server, you -will need to run the Chronicle agent as a sidecar container on your -Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files +with the Workbench and Connect charts. To send data to the server, run the Chronicle agent as a sidecar container on your +Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files. -Here is an example of Helm values to run the agent sidecar in **Workbench**, +Here is an example of Helm values to run the agent sidecar in *Workbench*, where we set up a shared volume between containers for audit logs: ```yaml @@ -65,7 +68,7 @@ pod: value: "http://chronicle-server.default" ``` -And here is an example of Helm values for Connect, where a **Connect** +Here is an example of Helm values for *Connect*, where a Connect API key from a Kubernetes Secret is used to unlock more detailed metrics: ```yaml @@ -83,7 +86,7 @@ pod: key: apikey ``` -Note that it is up to the user to provision this Kubernetes Secret for the +It is up to the user to provision this Kubernetes Secret for the Connect API key. ## Storage Configuration @@ -102,8 +105,7 @@ config: ``` `retentionPeriod` controls how long usage data are kept. For example, `"120m"` -for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention. -(Units smaller than seconds or larger than days are not supported.) +for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention (units smaller than seconds or larger than days are not supported). You can also persist data to AWS S3 instead of (or in addition to) local storage: @@ -116,7 +118,7 @@ config: Region: "us-east-2" ``` -### Using Iam for S3 +### Using IAM for S3 If you are running on EKS, you can use [IAM Roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) @@ -131,9 +133,9 @@ serviceaccount: eks.amazonaws.com/role-arn: arn:aws:iam::123456789000:role/iam-role-name-here ``` -If you are unable to use IAM Roles for Service Accounts, there are any number of +If you are unable to use IAM Roles for Service Accounts, there are many alternatives for injecting AWS credentials into a container. As a fallback, -the S3 storage config allows specifying a profile: +the S3 storage `config` allows specifying a profile: ```yaml config: @@ -144,14 +146,14 @@ config: Region: "us-east-2" ``` -### Needed S3 Policy Permissions +### Needed S3 policy permissions The credentials Chronicle uses for S3 storage must have the following permissions enabled: -- `s3:GetObject` -- `s3:ListBucket` -- `s3:PutObject` -- `s3:DeleteObject` +* `s3:GetObject` +* `s3:ListBucket` +* `s3:PutObject` +* `s3:DeleteObject` ## Values From 1def75f9130f6479efa34132abdd6a887544c52d Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:07:34 -0400 Subject: [PATCH 24/67] PPM edits --- charts/rstudio-pm/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index c50854a6..dd63295e 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -14,7 +14,7 @@ To ensure a stable production deployment: * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. - + ::: {.callout-important} This protects you from breaking changes. ::: From ababf15d224fdd3ba93045e9d14128f1f91a2668 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:42:19 -0400 Subject: [PATCH 25/67] trying to "fix" everything --- charts/_templates.gotmpl | 72 ++--- charts/posit-chronicle/README.md | 8 +- charts/rstudio-connect/README.md | 5 +- charts/rstudio-pm/README.md | 5 +- charts/rstudio-workbench/README.md.gotmpl | 317 +++++++++++----------- 5 files changed, 214 insertions(+), 193 deletions(-) diff --git a/charts/_templates.gotmpl b/charts/_templates.gotmpl index bce09a9a..dce4b93c 100644 --- a/charts/_templates.gotmpl +++ b/charts/_templates.gotmpl @@ -40,49 +40,59 @@ Workbench. {{- define "rstudio.disclaimer" }} -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. {{- end }} {{- define "rstudio.best-practices" }} -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. + + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. {{- end }} {{- define "rstudio.install" }} {{- $isDev := (regexMatch "[0-9]+\\.[0-9]+\\.[0-9]+-[a-zA-Z\\.0-9]+" .Version) }} -## Installing the Chart +## Installing the chart To install the chart with the release name `my-release` at version {{ template "chart.version" . }}: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com {{- if not $isDev }} helm upgrade --install my-release rstudio/{{ template "chart.name" . }} --version={{ template "chart.version" . }} @@ -95,7 +105,7 @@ helm upgrade --install --devel my-release rstudio/{{ template "chart.name" . }} {{- end }} ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo {{ if $isDev }}--devel {{ end }}rstudio/{{ template "chart.name" . }} -l ``` @@ -106,15 +116,15 @@ helm search repo {{ if $isDev }}--devel {{ end }}rstudio/{{ template "chart.name ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic {{ .Name }}-license --from-file=licenses/{{ .Name }}.lic` +```{.bash} +kubectl create secret generic {{ .Name }}-license --from-file=licenses/{{ .Name }}.lic +``` Second, specify the following values: @@ -127,15 +137,9 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/{{ .Name }}.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/{{ .Name }}.lic +``` {{- end }} diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index 308f3f3d..98feb64e 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -1,4 +1,7 @@ -# Posit Chronicle +--- +title: Posit Chronicle +code-overflow: wrap +--- ![Version: 0.3.0](https://img.shields.io/badge/Version-0.3.0-informational?style=flat-square) ![AppVersion: 2024.03.0](https://img.shields.io/badge/AppVersion-2024.03.0-informational?style=flat-square) @@ -89,7 +92,7 @@ pod: It is up to the user to provision this Kubernetes Secret for the Connect API key. -## Storage Configuration +## Storage configuration Chronicle can be configured to persist data to a local Kubernetes Volume, AWS S3, or both. @@ -202,4 +205,3 @@ The credentials Chronicle uses for S3 storage must have the following permission ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a06044aa..5c6812fb 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -1,4 +1,7 @@ -# Posit Connect +--- +title: Posit Connect +code-overflow: wrap +--- ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index dd63295e..d892ff66 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -1,4 +1,7 @@ -# Posit Package Manager +--- +title: Posit Package Manager +code-overflow: wrap +--- ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) diff --git a/charts/rstudio-workbench/README.md.gotmpl b/charts/rstudio-workbench/README.md.gotmpl index b6398432..de45d2d0 100644 --- a/charts/rstudio-workbench/README.md.gotmpl +++ b/charts/rstudio-workbench/README.md.gotmpl @@ -8,62 +8,65 @@ {{ template "rstudio.install" . }} -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * Disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` {{ template "rstudio.licensing" . }} -## General Principles +## General principles + +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values +These configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -80,130 +83,133 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods as well. + are mounted into the session pods. - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` -- Secret Configuration - - These configuration files are mounted into the server with more restrictive permissions (0600) + - Located in:
    `config.session.<< name of file >>` Helm values + - Mounted at:
    `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
    `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
    `/mnt/session-secret/` +- Secret Configuration: + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration - - These configuration files are mounted into the server (.ini file format) + - Located in:
    `config.secret.<< name of file >>` Helm values + - Mounted at:
    `/mnt/secret-configmap/rstudio/` +- Server Configuration: + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration - - These configuration files are mounted into the server (.dcf file format) + - Located at:
    `config.server.<< name of file >>` Helm values + - Mounted at:
    `/mnt/configmap/rstudio/` +- Server DCF Configuration: + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` -- Profiles Configuration - - These configuration files are mounted into the server (.ini file format) + - Located at:
    `config.serverDcf.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` +- Profiles Configuration: + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration - - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. +- Prestart: + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
    `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
    `/etc/sssd/conf.d/` with `0600` permissions by default. +- Custom Startup Configuration: + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
    `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
    `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: + - `pam` configuration files. + - Located at:
    `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
    `/etc/pam.d/<< name of file >>` -### Configuring R and Python repositories - -#### R repositories +#### Python repositories -R package repositories can be configured with `config.session.repos.conf`. +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + ```yaml + launcher: + useTemplates: true -#### Python repositories + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +#### R repositories -``` -launcher: - useTemplates: true +R package repositories can be configured with `config.session.repos.conf`: +```yaml config: session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -## User Provisioning +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. + +## User provisioning -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +Provisioning users in Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily +However, it is important to use caution for the following: -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. + +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -217,23 +223,23 @@ config: # will be used verbatim ``` -## RStudio Profiles +## RStudio profiles Profiles are used to define product behavior (in `.ini` file format) based on user and group membership. Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -256,17 +262,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -283,6 +289,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -294,23 +301,24 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: -### Job Json Overrides +### Job Json overrides -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -Note that several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -330,10 +338,11 @@ config: - "two-image:tag ``` -## Sealed Secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +## Sealed secrets + +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -341,7 +350,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. {{ template "chart.valuesSection" . }} From 50a2092b0cbd5d08d335f6e871400993855d40a9 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 14:44:30 +0000 Subject: [PATCH 26/67] Update helm-docs and README.md --- charts/posit-chronicle/README.md | 49 ++-- charts/rstudio-connect/README.md | 53 ++-- charts/rstudio-launcher-rbac/README.md | 31 ++- charts/rstudio-library/README.md | 25 +- charts/rstudio-pm/README.md | 56 ++-- charts/rstudio-workbench/README.md | 367 +++++++++++++------------ 6 files changed, 301 insertions(+), 280 deletions(-) diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index 98feb64e..6b9f84d1 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -1,7 +1,4 @@ ---- -title: Posit Chronicle -code-overflow: wrap ---- +# Posit Chronicle ![Version: 0.3.0](https://img.shields.io/badge/Version-0.3.0-informational?style=flat-square) ![AppVersion: 2024.03.0](https://img.shields.io/badge/AppVersion-2024.03.0-informational?style=flat-square) @@ -15,10 +12,14 @@ Workbench. To ensure a stable production deployment: +## For production + +To ensure a stable production deployment: + * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. - + ::: {.callout-important} This protects you from breaking changes. ::: @@ -35,19 +36,19 @@ helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.0 ``` -To explore other chart versions, take a look at: - -```{.bash} +To explore other chart versions, look at: +``` helm search repo rstudio/posit-chronicle -l ``` ## Usage This chart deploys only the Chronicle server and is meant to be used in tandem -with the Workbench and Connect charts. To send data to the server, run the Chronicle agent as a sidecar container on your -Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files. +with the Workbench and Connect charts. To actually send data to the server, you +will need to run the Chronicle agent as a sidecar container on your +Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files -Here is an example of Helm values to run the agent sidecar in *Workbench*, +Here is an example of Helm values to run the agent sidecar in **Workbench**, where we set up a shared volume between containers for audit logs: ```yaml @@ -71,7 +72,7 @@ pod: value: "http://chronicle-server.default" ``` -Here is an example of Helm values for *Connect*, where a Connect +And here is an example of Helm values for Connect, where a **Connect** API key from a Kubernetes Secret is used to unlock more detailed metrics: ```yaml @@ -89,10 +90,10 @@ pod: key: apikey ``` -It is up to the user to provision this Kubernetes Secret for the +Note that it is up to the user to provision this Kubernetes Secret for the Connect API key. -## Storage configuration +## Storage Configuration Chronicle can be configured to persist data to a local Kubernetes Volume, AWS S3, or both. @@ -108,7 +109,8 @@ config: ``` `retentionPeriod` controls how long usage data are kept. For example, `"120m"` -for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention (units smaller than seconds or larger than days are not supported). +for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention. +(Units smaller than seconds or larger than days are not supported.) You can also persist data to AWS S3 instead of (or in addition to) local storage: @@ -121,7 +123,7 @@ config: Region: "us-east-2" ``` -### Using IAM for S3 +### Using Iam for S3 If you are running on EKS, you can use [IAM Roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) @@ -136,9 +138,9 @@ serviceaccount: eks.amazonaws.com/role-arn: arn:aws:iam::123456789000:role/iam-role-name-here ``` -If you are unable to use IAM Roles for Service Accounts, there are many +If you are unable to use IAM Roles for Service Accounts, there are any number of alternatives for injecting AWS credentials into a container. As a fallback, -the S3 storage `config` allows specifying a profile: +the S3 storage config allows specifying a profile: ```yaml config: @@ -149,14 +151,14 @@ config: Region: "us-east-2" ``` -### Needed S3 policy permissions +### Needed S3 Policy Permissions The credentials Chronicle uses for S3 storage must have the following permissions enabled: -* `s3:GetObject` -* `s3:ListBucket` -* `s3:PutObject` -* `s3:DeleteObject` +- `s3:GetObject` +- `s3:ListBucket` +- `s3:PutObject` +- `s3:DeleteObject` ## Values @@ -205,3 +207,4 @@ The credentials Chronicle uses for S3 storage must have the following permission ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 8a04dbf9..a2ae0ee1 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -1,7 +1,4 @@ ---- -title: Posit Connect -code-overflow: wrap ---- +# Posit Connect ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) @@ -10,33 +7,37 @@ code-overflow: wrap Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. -## Installing the Chart + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.6.6: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-connect -l ``` @@ -56,15 +57,15 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` +```{.bash} +kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic +``` Second, specify the following values: @@ -77,15 +78,9 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-connect.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-connect.lic +``` ## General Principles diff --git a/charts/rstudio-launcher-rbac/README.md b/charts/rstudio-launcher-rbac/README.md index 313d989f..496581b3 100644 --- a/charts/rstudio-launcher-rbac/README.md +++ b/charts/rstudio-launcher-rbac/README.md @@ -4,28 +4,35 @@ #### _RBAC definition for the RStudio Job Launcher_ -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production -## Installing the Chart +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.2.20: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-launcher-rbac --version=0.2.20 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-launcher-rbac -l ``` diff --git a/charts/rstudio-library/README.md b/charts/rstudio-library/README.md index 86e0ab9d..56a781e8 100644 --- a/charts/rstudio-library/README.md +++ b/charts/rstudio-library/README.md @@ -4,17 +4,24 @@ #### _Helm library helpers for use by official RStudio charts_ -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production + +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. # Usage diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 9fcaca95..24b0d743 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -1,7 +1,4 @@ ---- -title: Posit Package Manager -code-overflow: wrap ---- +# Posit Package Manager ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) @@ -10,28 +7,35 @@ code-overflow: wrap IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production -## Installing the Chart +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.5.25: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-pm -l ``` @@ -60,15 +64,15 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic` +```{.bash} +kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic +``` Second, specify the following values: @@ -81,15 +85,9 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-pm.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-pm.lic +``` ## S3 Configuration diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9cda63d7..0a5bb0a1 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -7,81 +7,91 @@ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production -## Installing the Chart +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.7.3: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-workbench -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * Disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` -## Licensing + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +## Licensing -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` +```{.bash} +kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic +``` Second, specify the following values: @@ -94,32 +104,27 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-workbench.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server +```{.bash} +--set-file license.file.contents=licenses/rstudio-workbench.lic +``` -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +## General principles -## General Principles +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values +These configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -136,130 +141,133 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods as well. + are mounted into the session pods. - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` -- Secret Configuration - - These configuration files are mounted into the server with more restrictive permissions (0600) + - Located in:
    `config.session.<< name of file >>` Helm values + - Mounted at:
    `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
    `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
    `/mnt/session-secret/` +- Secret Configuration: + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration - - These configuration files are mounted into the server (.ini file format) + - Located in:
    `config.secret.<< name of file >>` Helm values + - Mounted at:
    `/mnt/secret-configmap/rstudio/` +- Server Configuration: + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration - - These configuration files are mounted into the server (.dcf file format) + - Located at:
    `config.server.<< name of file >>` Helm values + - Mounted at:
    `/mnt/configmap/rstudio/` +- Server DCF Configuration: + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` -- Profiles Configuration - - These configuration files are mounted into the server (.ini file format) + - Located at:
    `config.serverDcf.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` +- Profiles Configuration: + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration - - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. +- Prestart: + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
    `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
    `/etc/sssd/conf.d/` with `0600` permissions by default. +- Custom Startup Configuration: + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
    `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
    `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: + - `pam` configuration files. + - Located at:
    `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
    `/etc/pam.d/<< name of file >>` -### Configuring R and Python repositories +#### Python repositories -#### R repositories +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -R package repositories can be configured with `config.session.repos.conf`. +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` + ```yaml + launcher: + useTemplates: true -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` -#### Python repositories - -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +#### R repositories -``` -launcher: - useTemplates: true +R package repositories can be configured with `config.session.repos.conf`: +```yaml config: session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -## User Provisioning +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +## User provisioning + +Provisioning users in Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily +However, it is important to use caution for the following: + +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -273,23 +281,23 @@ config: # will be used verbatim ``` -## RStudio Profiles +## RStudio profiles Profiles are used to define product behavior (in `.ini` file format) based on user and group membership. Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -312,17 +320,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -339,6 +347,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -350,23 +359,24 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: -### Job Json Overrides +### Job Json overrides -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -Note that several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -386,10 +396,11 @@ config: - "two-image:tag ``` -## Sealed Secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +## Sealed secrets + +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -397,7 +408,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values From b9905067aa8f68e3cec9a0ca62f93d4b620f9ddb Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:49:02 -0400 Subject: [PATCH 27/67] Description updates --- charts/rstudio-connect/Chart.yaml | 2 +- charts/rstudio-pm/Chart.yaml | 2 +- charts/rstudio-workbench/Chart.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/charts/rstudio-connect/Chart.yaml b/charts/rstudio-connect/Chart.yaml index 225d2322..5518cb08 100644 --- a/charts/rstudio-connect/Chart.yaml +++ b/charts/rstudio-connect/Chart.yaml @@ -1,5 +1,5 @@ name: rstudio-connect -description: Official Helm chart for RStudio Connect +description: Official Helm chart for Posit Connect version: 0.6.6 apiVersion: v2 appVersion: 2024.04.1 diff --git a/charts/rstudio-pm/Chart.yaml b/charts/rstudio-pm/Chart.yaml index 76a4357d..f9e32dfa 100644 --- a/charts/rstudio-pm/Chart.yaml +++ b/charts/rstudio-pm/Chart.yaml @@ -1,5 +1,5 @@ name: rstudio-pm -description: Official Helm chart for RStudio Package Manager +description: Official Helm chart for Posit Package Manager version: 0.5.25 apiVersion: v2 appVersion: 2024.04.0 diff --git a/charts/rstudio-workbench/Chart.yaml b/charts/rstudio-workbench/Chart.yaml index b44fb106..987b7ad6 100644 --- a/charts/rstudio-workbench/Chart.yaml +++ b/charts/rstudio-workbench/Chart.yaml @@ -1,5 +1,5 @@ name: rstudio-workbench -description: Official Helm chart for RStudio Workbench +description: Official Helm chart for Posit Workbench version: 0.7.3 apiVersion: v2 appVersion: 2024.04.0 From 95403c36a6494093be074d2a4d3f74e6e3e45e15 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Fri, 10 May 2024 20:31:31 -0400 Subject: [PATCH 28/67] Workbench review --- charts/rstudio-workbench/README.md | 311 ++++++++++++++++------------- examples/workbench/index.qmd | 2 +- index.qmd | 10 +- 3 files changed, 179 insertions(+), 144 deletions(-) diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9cda63d7..01abf0ab 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,4 +1,7 @@ -# Posit Workbench +--- +title: Posit Workbench +code-overflow: wrap +--- ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) @@ -7,19 +10,23 @@ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm diff upgrade`. * Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart + changes and the documentation below on how to use the chart. -## Installing the Chart +## Installing the chart To install the chart with the release name `my-release` at version 0.7.3: @@ -29,59 +36,65 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: -``` + +```bash helm search repo rstudio/rstudio-workbench -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or the address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` + + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against directly placing it in your values file. -### License File +### License file We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` +```bash +kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic +``` Second, specify the following values: @@ -94,39 +107,48 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-workbench.lic` +```bash +--set-file license.file.contents=licenses/rstudio-workbench.lic +``` -### License Key +### License key -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument: -### License Server +```bash +--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX +``` -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +### License server -## General Principles +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument: + +```bash +--set license.server= +``` + +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by RStudio Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by RStudio Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to get the service account information off of the RStudio Workbench pod for use in launching jobs. +- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files These configuration values all take the form of usual helm values -so you can set the database password with something like: +so you can set the database password with similar to: -``` +```bash ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -136,87 +158,77 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable - -- Session Configuration - - These configuration files are mounted into the server and - are mounted into the session pods as well. - - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. + +- Session Configuration: + - Configuration files: `repos.conf`, `rsession.conf`, `notifications.conf` + - These configuration files are mounted into the server and + the session pods. + - Located in the `config.session.<< name of file >>` helm values + - Mounted at `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: - These configuration files are mounted into the server and session pods as well - `odbc.ini` and other similar shared secrets - located in `config.sessionSecret.<< name of file>>` helm values - mounted at `/mnt/session-secret/` -- Secret Configuration +- Secret Configuration: - These configuration files are mounted into the server with more restrictive permissions (0600) - `database.conf`, `openid-client-secret`, `databricks.conf` - They are located in the `config.secret.<< name of file >>` helm values - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration +- Server Configuration: - These configuration files are mounted into the server (.ini file format) - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - They are located at `config.server.<< name of file >>` helm values - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration +- Server DCF Configuration: - These configuration files are mounted into the server (.dcf file format) - `launcher-mounts`, `launcher-env` - They are located at `config.serverDcf.<< name of file >>` helm values - included at `/mnt/configmap/rstudio/` -- Profiles Configuration +- Profiles Configuration: - These configuration files are mounted into the server (.ini file format) - `launcher.kubernetes.profiles.conf` - They are located at `config.profiles.<< name of file >>` helm values - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart + - See the [Profiles](#rstudio-profiles) section below for more information +- Prestart: - This is provided by the helm chart in a configmap - It is mounted into the pod at `/scripts/` - `prestart-workbench.bash` is used to start workbench - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`) - Located at `config.userProvisioning.<< name of file >>` helm values - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration +- Custom Startup Configuration: - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default + - Use the `.ini` file format, by default - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration + - As with all configuration files above, can override with a verbatim string if desired: + - Located at `config.startupCustom.<< name of file >>` helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: - `pam` configuration files - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - -### Configuring R and Python repositories - -#### R repositories - -R package repositories can be configured with `config.session.repos.conf`. + - Mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` - -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). +### Configuring Python and R repositories #### Python repositories -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -``` +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: + +```yaml launcher: useTemplates: true @@ -228,29 +240,43 @@ config: trusted-host: packagemanager.posit.co ``` -## User Provisioning +#### R repositories -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +R package repositories can be configured with `config.session.repos.conf`: + +```yaml +config: + session: + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest +``` + +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. + +## User provisioning + +Provisioning users in RStudio Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: + +However, it is important to use caution for the following: - UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames + time. Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because + some operating systems disallow `@` signs in linux usernames. - `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily + to configure a user management service, be careful that it does not exit unnecessarily. We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM @@ -259,7 +285,7 @@ When starting sessions on RStudio Workbench, PAM configuration is often very imp an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -279,17 +305,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -312,17 +338,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -339,6 +365,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -350,23 +377,28 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: + +### Job Json overrides -### Job Json Overrides +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: the "target" part of the job spec to replace + - `name`: a unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: a YAML value that is translated directly to JSON and injected into the job spec at `target`. -Note that several examples are provided +Several examples are provided in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) (however, examples do not use the helm chart syntax there). -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md).x ```yaml config: @@ -386,10 +418,11 @@ config: - "two-image:tag ``` -## Sealed Secrets +## Sealed secrets + This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -397,7 +430,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values diff --git a/examples/workbench/index.qmd b/examples/workbench/index.qmd index 6b6ec2c0..2a3fb88a 100644 --- a/examples/workbench/index.qmd +++ b/examples/workbench/index.qmd @@ -12,7 +12,7 @@ Before using an example, read through all the comments and ensure you address ea While each example focuses on one or more particular configurations, RStudio Workbench has some standard requirements listed in each example. -Each example will need the following to run correctly: +Each example needs the following to run correctly: - PostgreSQL database specified in the Workbench configuration - License key or file specified diff --git a/index.qmd b/index.qmd index 319ec014..435cdc7b 100644 --- a/index.qmd +++ b/index.qmd @@ -1,13 +1,15 @@ -# Posit Helm Charts +--- +title: Posit Helm Charts +--- [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/rstudio)](https://artifacthub.io/packages/search?repo=rstudio) [![GitHub license](https://img.shields.io/github/license/rstudio/helm.svg)](https://github.com/rstudio/helm/blob/main/LICENSE) ## Usage -1. Install [Helm](https://helm.sh). Please refer to Helm's [documentation](https://helm.sh/docs/) for more information on getting started. +1. Install [Helm](https://helm.sh). Please refer to the [Helm documentation](https://helm.sh/docs/) for more information on getting started. -2. Add the Posit Helm repo: +2. Add the Posit Helm repository: ```console helm repo add rstudio https://helm.rstudio.com @@ -17,4 +19,4 @@ ```console helm search repo rstudio - ``` + ``` \ No newline at end of file From 2ec1d03eccda9caf30f1b0ecd07ad5d864b72796 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Fri, 10 May 2024 20:54:07 -0400 Subject: [PATCH 29/67] New version of posit theme installed --- _environment | 1 - .../posit-dev/posit-docs/_extension.yml | 9 +- .../posit-dev/posit-docs/_posit-colors.scss | 37 ++ .../assets/images/exclamation-circle-dm.svg | 4 + .../assets/images/exclamation-circle.svg | 4 + .../assets/images/exclamation-triangle-dm.svg | 4 + .../assets/images/exclamation-triangle.svg | 4 + .../assets/images/info-circle-dm.svg | 4 + .../posit-docs/assets/images/info-circle.svg | 4 + .../assets/images/posit-logo-black-TM.svg | 2 +- .../posit-dev/posit-docs/theme-dark.scss | 342 ++++++++++++++++++ _extensions/posit-dev/posit-docs/theme.scss | 327 +++++++++++++---- _quarto.yml | 16 +- 13 files changed, 666 insertions(+), 92 deletions(-) create mode 100644 _extensions/posit-dev/posit-docs/_posit-colors.scss create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg create mode 100644 _extensions/posit-dev/posit-docs/assets/images/info-circle.svg create mode 100644 _extensions/posit-dev/posit-docs/theme-dark.scss diff --git a/_environment b/_environment index 3f26336d..0521a9f7 100644 --- a/_environment +++ b/_environment @@ -1,2 +1 @@ CURRENT_YEAR=2024 -PRODUCT_VERSION=2024.x diff --git a/_extensions/posit-dev/posit-docs/_extension.yml b/_extensions/posit-dev/posit-docs/_extension.yml index 5e7f0b4d..9f03f0f2 100644 --- a/_extensions/posit-dev/posit-docs/_extension.yml +++ b/_extensions/posit-dev/posit-docs/_extension.yml @@ -1,6 +1,6 @@ title: posit-docs author: Ashley Henry, David Aja, Aron Atkins -version: 3.0.0 +version: 4.0.1 quarto-required: ">=1.3.340" contributes: project: @@ -12,9 +12,10 @@ contributes: navbar: pinned: true logo: "assets/images/posit-icon-fullcolor.svg" - logo-alt: "Posit Documentation" + logo-alt: "Posit Documentation" right: - icon: "list" + aria-label: 'Drop-down menu for additional Posit resources' menu: - text: "docs.posit.co" href: "https://docs.posit.co" @@ -25,7 +26,9 @@ contributes: show-item-context: true format: html: - theme: [theme.scss] + theme: + light: [theme.scss] + dark: [theme-dark.scss] link-external-icon: true link-external-newwindow: true toc: true diff --git a/_extensions/posit-dev/posit-docs/_posit-colors.scss b/_extensions/posit-dev/posit-docs/_posit-colors.scss new file mode 100644 index 00000000..e4bf13a3 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/_posit-colors.scss @@ -0,0 +1,37 @@ +/* Posit Color definitions */ +$posit-blue: #447099; +$posit-light-blue-1: #d1dbe5; +$posit-light-blue-2: #a2b8cb; +$posit-light-blue-3: #7494b1; +$posit-dark-blue-1: #305775; +$posit-dark-blue-2: #213d4f; + +$posit-orange: #ee6331; +$posit-light-orange-1: #edccbf; +$posit-light-orange-2: #eba38c; +$posit-dark-orange-1: #ab4d26; +$posit-dark-orange-2: #80361c; +$posit-dark-orange-3: #451f12; + +$posit-gray: #404041; +$posit-light-gray-1: #c2c2c4; +$posit-light-gray-2: #949494; +$posit-dark-gray-1: #333333; + +$posit-teal: #419599; +$posit-light-teal-1: #c2d9d9; +$posit-light-teal-2: #94bdbf; +$posit-light-teal-3: #70a3a6; +$posit-dark-teal-1: #297075; +$posit-dark-teal-2: #1f4f4f; +$posit-dark-teal-3: #122b2b; + +$posit-green: #72994e; + +$posit-burgundy: #9a4665; +$posit-light-burgundy-1: #d9c4cc; +$posit-light-burgundy-2: #bf96a3; +$posit-light-burgundy-3: #a67380; +$posit-dark-burgundy-1: #78384f; +$posit-dark-burgundy-2: #542938; +$posit-dark-burgundy-3: #2e171f; diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg new file mode 100644 index 00000000..fbdfd203 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle-dm.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg new file mode 100644 index 00000000..6098c8b2 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-circle.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg new file mode 100644 index 00000000..63db9932 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle-dm.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg new file mode 100644 index 00000000..65d947c9 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/exclamation-triangle.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg b/_extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg new file mode 100644 index 00000000..6a5c164d --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/info-circle-dm.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/_extensions/posit-dev/posit-docs/assets/images/info-circle.svg b/_extensions/posit-dev/posit-docs/assets/images/info-circle.svg new file mode 100644 index 00000000..f4f803ad --- /dev/null +++ b/_extensions/posit-dev/posit-docs/assets/images/info-circle.svg @@ -0,0 +1,4 @@ + + + + diff --git a/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg b/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg index 3b159987..90331515 100644 --- a/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg +++ b/_extensions/posit-dev/posit-docs/assets/images/posit-logo-black-TM.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/_extensions/posit-dev/posit-docs/theme-dark.scss b/_extensions/posit-dev/posit-docs/theme-dark.scss new file mode 100644 index 00000000..ec1e26d4 --- /dev/null +++ b/_extensions/posit-dev/posit-docs/theme-dark.scss @@ -0,0 +1,342 @@ +/*-- scss:defaults --*/ + +// import font +@import url("https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap"); + +// import shared colors +@import '_posit-colors'; + +/*-- scss:variables --*/ +$primary: $posit-teal; +$dark-md-body: $posit-light-gray-1; +$dark-md-background: #0c1721; + +// Feature preview heading colors +$preview-header: $posit-orange; /* posit orange, contrast: 8.45 */ +$preview-header-border: darken($preview-header, 5%); + +// scss-docs-end color-variables + +// Typography +// Font, line-height, and color for body text, headings, and more. + +//scss-font-start font-variables +$font-family-sans-serif: "Open Sans", "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, + sans-serif, system-ui; +$font-family-monospace: "Source Code Pro", monospace; +$font-family-emoji: "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; +$font-size-base: 1rem; +// scss-docs-end font-variables + +//font and body color + +$body-color: $dark-md-body; +$popover-bg: $posit-green !default; + +// scss-docs-start font-sizes - seems that I have to keep these in the style sheet? +$h1-font-size: 44px; +$h2-font-size: 28px; +x h1 { + size: $h1-font-size; +} +h2 { + size: $h2-font-size; +} +// scss-docs-end font-sizes + +// Headings +// scss-docs-start headings-variables +$headings-color: #ffffff; +// scss-docs-end headings-variables + +// Customize the navbar +$navbar-bg: lighten($dark-md-background, 5%); +$navbar-fg: #ffffff; + +// CSS overrides + +// Body +// +// Settings for the `` element. + +//$body-color: $posit-green !default; +$body-bg: $dark-md-background !default; // dark mode change + +// Nav and footer + +/* Nav bar */ + +.navbar-title { + color: #ffffff; // dark theme change +} + +.nav-link { + font-family: $font-family-monospace; + text-transform: uppercase; + letter-spacing: 0.03em; + font-size: 14px !important; + font-weight: 500 !important; + color: #fff !important; +} + +.navbar-nav .nav-link.active, +.navbar-nav .nav-link.show { + color: $posit-teal !important; + font-weight: 700 !important; +} + +/* Nav bar right hamburger menu */ + +.dropdown-item:hover, +.dropdown-item:focus { + color: var(--bs-dropdown-link-hover-color); + background-color: #0f1c29 !important; +} + +/* Footer */ + +.nav-footer { + color: #ffffff !important; + border-top: solid $posit-gray 1px; +} + +/* Footer icons */ +.nav-footer a { + color: #ffffff !important; +} + +// Footnotes + +.footnote-back { + color: $posit-light-teal-2; +} + +// Breadcrumbs + +.quarto-title-breadcrumbs .breadcrumb li:last-of-type a { + color: $posit-light-gray-1 !important; +} + +// Page navigation + +.nav-page .nav-page-text { + color: $posit-light-gray-1; +} + +/* Inline code */ +p code:not(.sourceCode), +li code:not(.sourceCode), +td code:not(.sourceCode) { + background-color: #6e768166 !important; + color: #ffffff; +} + +// Code blocks + +/* Code block title*/ + +.quarto-dark .code-with-filename .code-with-filename-file { + background-color: #000000 !important; + border: none; +} + +.code-with-filename strong { + color: #6e9ac3; +} + +/* Code block background */ +$code-block-bg: lighten($dark-md-background, 10%); + +/* Copy button */ + +$btn-code-copy-color: $posit-light-blue-2; +$btn-code-copy-color-active: #ffffff; +$callout-icon-scale: 70%; + +// Tabs and pills + +/* Tabs */ + +.nav-tabs .nav-link.active { + color: $posit-teal !important; +} + +.nav-tabs .nav-link { + text-transform: none !important; + font-family: $font-family-sans-serif; + color: #ffffff !important; +} + +.nav-tabs .nav-link:hover, +.nav-link:focus { + color: $posit-teal !important; +} + +/* Pills */ + +.nav-pills .nav-link.active, +.nav-pills .show > .nav-link { + background-color: $posit-dark-teal-1 !important; +} + +.nav-pills .nav-link:hover, +.nav-link:focus { + isolation: isolate; + // color: $posit-teal !important; + border: none !important; +} + +.nav-pills .nav-link.active, +.nav-link:hover { + color: #ffffff !important; +} + +// Sidebar and toc + +/* Left nav - letter spacing */ +.sidebar-navigation li a { + color: #ffffff; +} + +.sidebar-navigation li a:hover { + color: inherit; +} + +.sidebar-item-container .active, +div.sidebar-item-container .show > .nav-link, +div.sidebar-item-container .sidebar-link > code { + color: $posit-teal !important; +} + +// Lists + +/* List disc colors */ +li::marker { + color: $posit-teal; +} + +// Callouts + +.callout.callout-style-default:not(.no-icon) div.callout-title-container { + color: #ffffff !important; +} + +div.callout.callout-style-default > div.callout-header { + opacity: none; +} + +/* Note */ + +div.callout-note.callout { + border-left-color: $posit-dark-blue-2 !important; + border-right: 1px solid $posit-dark-blue-2 !important; + border-top: 1px solid $posit-dark-blue-2 !important; + border-bottom: 1px solid $posit-dark-blue-2 !important; +} + +div.callout-note .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/info-circle-dm.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzAwMDAwMCIgY2xhc3M9ImJpIGJpLWluZm8tY2lyY2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik04IDE1QTcgNyAwIDEgMSA4IDFhNyA3IDAgMCAxIDAgMTRtMCAxQTggOCAwIDEgMCA4IDBhOCA4IDAgMCAwIDAgMTYiLz4KICA8cGF0aCBkPSJtOC45MyA2LjU4OC0yLjI5LjI4Ny0uMDgyLjM4LjQ1LjA4M2MuMjk0LjA3LjM1Mi4xNzYuMjg4LjQ2OWwtLjczOCAzLjQ2OGMtLjE5NC44OTcuMTA1IDEuMzE5LjgwOCAxLjMxOS41NDUgMCAxLjE3OC0uMjUyIDEuNDY1LS41OThsLjA4OC0uNDE2Yy0uMi4xNzYtLjQ5Mi4yNDYtLjY4Ni4yNDYtLjI3NSAwLS4zNzUtLjE5My0uMzA0LS41MzN6TTkgNC41YTEgMSAwIDEgMS0yIDAgMSAxIDAgMCAxIDIgMCIvPgo8L3N2Zz4=") !important; +} + +div.callout-note.callout-style-default > .callout-header { + background-color: $posit-blue !important; +} + +/* Warning */ + +div.callout-warning.callout { + border-left-color: $posit-dark-orange-2 !important; + border-right: 1px solid $posit-dark-orange-2 !important; + border-top: 1px solid $posit-dark-orange-2 !important; + border-bottom: 1px solid $posit-dark-orange-2 !important; +} + +div.callout-warning .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-triangle-dm.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzAwMDAwMCIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLXRyaWFuZ2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik03LjkzOCAyLjAxNkEuMTMuMTMgMCAwIDEgOC4wMDIgMmEuMTMuMTMgMCAwIDEgLjA2My4wMTYuMTUuMTUgMCAwIDEgLjA1NC4wNTdsNi44NTcgMTEuNjY3Yy4wMzYuMDYuMDM1LjEyNC4wMDIuMTgzYS4yLjIgMCAwIDEtLjA1NC4wNi4xLjEgMCAwIDEtLjA2Ni4wMTdIMS4xNDZhLjEuMSAwIDAgMS0uMDY2LS4wMTcuMi4yIDAgMCAxLS4wNTQtLjA2LjE4LjE4IDAgMCAxIC4wMDItLjE4M0w3Ljg4NCAyLjA3M2EuMTUuMTUgMCAwIDEgLjA1NC0uMDU3bTEuMDQ0LS40NWExLjEzIDEuMTMgMCAwIDAtMS45NiAwTC4xNjUgMTMuMjMzYy0uNDU3Ljc3OC4wOTEgMS43NjcuOTggMS43NjdoMTMuNzEzYy44ODkgMCAxLjQzOC0uOTkuOTgtMS43Njd6Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDEyYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNS45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-warning.callout-style-default > .callout-header { + background-color: $posit-dark-orange-1 !important; +} + +/* Important */ + +div.callout-important.callout { + border-left-color: $posit-dark-burgundy-2 !important; + border-right: 1px solid $posit-dark-burgundy-2 !important; + border-top: 1px solid $posit-dark-burgundy-2 !important; + border-bottom: 1px solid $posit-dark-burgundy-2 !important; +} + +div.callout-important .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-circle-dm.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzAwMDAwMCIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLWNpcmNsZSIgdmlld0JveD0iMCAwIDE2IDE2Ij4KICA8cGF0aCBkPSJNOCAxNUE3IDcgMCAxIDEgOCAxYTcgNyAwIDAgMSAwIDE0bTAgMUE4IDggMCAxIDAgOCAwYTggOCAwIDAgMCAwIDE2Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDExYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNC45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-important.callout-style-default > .callout-header { + background-color: $posit-burgundy !important; +} + +// Tables + +.table > :not(caption) > * > * { + border-top: 2px solid #101e2b; +} + +/* Striped table styles */ + +.table-striped > tbody > tr:nth-of-type(odd) > * { + //--bs-table-bg-type: #001C2B !important; + --bs-table-bg-type: #101e2b !important; +} + +/* Striped table hover */ + +.table-hover > tbody > tr:hover > * { + //--bs-table-color-state: var(--bs-table-hover-color); + --bs-table-bg-state: #001c2b !important; +} + +// Table caption + +.panel-caption, +.figure-caption, +.subfigure-caption, +.table-caption, +figcaption, +caption { + font-size: 1rem; + color: $body-color !important; +} + +// Specialty headers + +/* the feature PREVIEW header */ +.preview-header > h1:after, +.preview-header > h2:after, +.preview-header > h3:after, +.preview-header > h4:after, +header h1 .preview-header, +div span.preview-feature { + background-color: $preview-header; + color: #ffffff; + border: 1px solid $preview-header-border; + font-weight: 600; + font-size: 9pt !important; + padding: 0rem 0.4rem; +} + +div span.preview-feature { + margin-left: 1em; + text-transform: uppercase; +} + +// Specialty lists +// Groovy list - dark mode change + +ol.groovyAlpha li > p:before { + content: counter(list-counter, lower-alpha); + font-weight: 600; +} diff --git a/_extensions/posit-dev/posit-docs/theme.scss b/_extensions/posit-dev/posit-docs/theme.scss index 418bd8b4..0a4e222a 100644 --- a/_extensions/posit-dev/posit-docs/theme.scss +++ b/_extensions/posit-dev/posit-docs/theme.scss @@ -1,26 +1,16 @@ /*-- scss:defaults --*/ // import font -@import url('https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap'); +@import url("https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap"); -/*-- scss:variables --*/ - -// scss-docs-start color-variables -$posit-blue: #447099; -$posit-dark-blue-1: #305775; -$posit-dark-blue-2: #213D4F; -$posit-orange: #EE6331; -$posit-gray: #404041; -$posit-teal: #419599; -$posit-green: #72994E; -$posit-burgundy:#9A4665; -$posit-burgundy-1:#78384F; -$posit-burgundy-2:#542938; +// import shared colors +@import '_posit-colors'; +/*-- scss:variables --*/ $primary: $posit-blue; // Feature preview heading colors -$preview-header: #EE6331; /* posit orange, contrast: 8.45 */ +$preview-header: #ee6331; /* posit orange, contrast: 8.45 */ $preview-header-border: darken($preview-header, 5%); // scss-docs-end color-variables @@ -29,17 +19,19 @@ $preview-header-border: darken($preview-header, 5%); // Font, line-height, and color for body text, headings, and more. //scss-font-start font-variables -$font-family-sans-serif: "Open Sans", "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, system-ui; +$font-family-sans-serif: "Open Sans", "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, + sans-serif, system-ui; $font-family-monospace: "Source Code Pro", monospace; $font-family-emoji: "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; $font-size-base: 1rem; // scss-docs-end font-variables +//font and body color $body-color: $posit-gray; // scss-docs-start font-sizes -$h1-font-size:44px; -$h2-font-size:28px; +$h1-font-size: 44px; +$h2-font-size: 28px; h1 { size: $h1-font-size; @@ -49,7 +41,6 @@ h2 { } // scss-docs-end font-sizes - // Headings // scss-docs-start headings-variables $headings-font-weight: 300 !important; @@ -69,15 +60,39 @@ $list-group-color: $primary !default; // CSS overrides +// Body +// +// Settings for the `` element. + +/* Body font */ +body { + letter-spacing: -0.2px !important; +} + +// Nav and footer + +/* Navbar */ + .navbar { - box-shadow: 0 0 0.2rem #0000001a, 0 0.1rem 0.4rem #0003; - transition: transform .25s cubic-bezier(.1,.7,.1,1),box-shadow .25s; + box-shadow: + 0 0 0.2rem #0000001a, + 0 0.1rem 0.4rem #0003; + transition: + transform 0.25s cubic-bezier(0.1, 0.7, 0.1, 1), + box-shadow 0.25s; } .navbar-title { - font-family: $font-family-sans-serif; - font-size: $font-size-base; - font-weight: 500; + font-family: $font-family-sans-serif; + font-size: $font-size-base; + font-weight: 500; +} + +/* Style for the version included in the website title */ +.navbar-title small { + font-size: 14px; + display: block; + padding-left: 1em; } /* Style for the version included in the website title */ @@ -101,29 +116,153 @@ $list-group-color: $primary !default; } .nav-link { - font-family: $font-family-monospace; - text-transform: uppercase; - letter-spacing: .03em; - font-size: 14px !important; - font-weight: 500 !important; + font-family: $font-family-monospace; + text-transform: uppercase; + letter-spacing: 0.03em; + font-size: 14px !important; + font-weight: 500 !important; + color: $posit-gray !important; +} + +.navbar-nav .nav-link.active, +.navbar-nav .nav-link.show { + color: #000000 !important; + font-weight: 700 !important; } +/* Footer */ + .nav-footer { - font-family: $font-family-monospace; - text-transform: uppercase; - font-size: 14px; - border-top: solid #0000001a .01em; - align-items: center !important; + font-family: $font-family-monospace; + text-transform: uppercase; + font-size: 14px; + border-top: solid #0000001a 0.01em; + align-items: center !important; } -/* Tabs */ +.nav-footer .nav-footer-center { + min-height: min-content; +} + +/* Footer icons */ + +/* Full Posit logo - currently, unused */ +#footer-right-full-posit-logo { + width: 70px; + min-width: 70px; +} + +/* Posit guide book */ +#footer-right-logo { + width: 24px; + min-width: 24px; + margin-left: -3px !important; + margin-right: -3px !important; + padding-top: 1px; +} + +/* Posit icon fullcolor */ +#footer-right-posit-logo { + width: 18px; + min-width: 18px; + margin-left: -3px !important; + margin-right: -3px !important; + padding-top: 1px; +} + +/* Posit logo - footer +#footer-logo { + width: 70px; + min-width: 70px; +} +*/ + +.bi-question-circle-fill { + font-size: 18px !important; +} + +.bi-lightbulb-fill { + font-size: 18px !important; +} + +// Footnotes + +.footnote-back { + font-size: 16px !important; + font-weight: 900px !important; + color: $posit-dark-blue-1; +} + +// Tabs and pills + +/* Tabs */ .nav-tabs .nav-link { - text-transform: none !important; - font-family: $font-family-sans-serif; + text-transform: none !important; + font-family: $font-family-sans-serif; + color: $posit-gray !important; +} + +.nav-tabs .nav-link.active, +.nav-tabs .nav-item.show .nav-link { + color: #000000 !important; +} + +.nav-tabs .nav-link:hover, +.nav-link:focus { + color: $posit-blue !important; +} + +/* Pills */ + +.nav-pills { + border: none !important; +} + +.nav-pills, +.panel-underline { + > .nav { + display: flex; + border: none !important; + flex-direction: row; + justify-content: center; + .nav-link { + cursor: pointer; + } + } +} + +.nav-pills > .nav .nav-link { + border: none !important; +} + +.nav-pills, +.panel-underline { + .tab-content { + padding-left: 0; + padding-right: 0; + border: none; + } +} + +.nav-pills .nav-link.active, +.nav-pills .nav-item.show .nav-link { + color: #ffffff !important; +} + +.nav-pills .nav-link:hover, +.nav-link:focus { + isolation: isolate; + color: $posit-blue !important; + border: none !important; +} + +.nav-pills .nav-link.active, +.nav-pills .show > .nav-link { + color: #ffffff !important; } -/* Sidebar and toc */ +// Sidebar and toc /* Left nav */ .sidebar-item-container .active { @@ -132,45 +271,85 @@ $list-group-color: $primary !default; /* Left nav - letter spacing */ .sidebar-navigation li a { - letter-spacing: .03em; + letter-spacing: 0.03em; font-size: 16px; } +/* Left nav - letter spacing */ +.sidebar-navigation li a { + letter-spacing: -0.2px; + line-height: normal; +} + /* Mini TOC */ -.sidebar nav[role=doc-toc]>ul li a { - text-transform: none !important; - font-family: $font-family-sans-serif; - font-weight: 400 !important; - letter-spacing: -0.2px !important; +.sidebar nav[role="doc-toc"] > ul li a { + text-transform: none !important; + font-family: $font-family-sans-serif; + font-weight: 400 !important; + letter-spacing: -0.2px !important; } -.sidebar nav[role=doc-toc] ul>li>a.active, .sidebar nav[role=doc-toc] ul>li>ul>li>a.active { - font-weight: 700 !important; +.sidebar nav[role="doc-toc"] ul > li > a.active, +.sidebar nav[role="doc-toc"] ul > li > ul > li > a.active { + font-weight: 700 !important; } -/* Left nav - letter spacing */ -.sidebar-navigation li a { - letter-spacing: -0.2px; - line-height: normal; +// Lists + +/* List disc colors */ +li::marker { + color: $primary; } -/* Posit logo - footer */ -#footer-logo { - width: 70px; - min-width: 70px; +// Callouts + +.callout.callout-style-default:not(.no-icon) div.callout-title-container { + color: $posit-dark-gray-1 !important; } -/* Footer */ -.nav-footer .nav-footer-center { - min-height: min-content; +/* Note */ + +div.callout-note.callout { + border-left-color: $posit-blue !important; } -// Font +div.callout-note .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/info-circle.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzE3MjEyQiIgY2xhc3M9ImJpIGJpLWluZm8tY2lyY2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik04IDE1QTcgNyAwIDEgMSA4IDFhNyA3IDAgMCAxIDAgMTRtMCAxQTggOCAwIDEgMCA4IDBhOCA4IDAgMCAwIDAgMTYiLz4KICA8cGF0aCBkPSJtOC45MyA2LjU4OC0yLjI5LjI4Ny0uMDgyLjM4LjQ1LjA4M2MuMjk0LjA3LjM1Mi4xNzYuMjg4LjQ2OWwtLjczOCAzLjQ2OGMtLjE5NC44OTcuMTA1IDEuMzE5LjgwOCAxLjMxOS41NDUgMCAxLjE3OC0uMjUyIDEuNDY1LS41OThsLjA4OC0uNDE2Yy0uMi4xNzYtLjQ5Mi4yNDYtLjY4Ni4yNDYtLjI3NSAwLS4zNzUtLjE5My0uMzA0LS41MzN6TTkgNC41YTEgMSAwIDEgMS0yIDAgMSAxIDAgMCAxIDIgMCIvPgo8L3N2Zz4=") !important; +} -/* Body font */ -body { - letter-spacing: -0.2px !important; - } +div.callout-note.callout-style-default > .callout-header { + background-color: #dce7f2 !important; +} + +/* Warning */ +div.callout-warning.callout { + border-left-color: $posit-orange !important; +} + +div.callout-warning .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-triangle.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzQ1MUYxMiIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLXRyaWFuZ2xlIiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik03LjkzOCAyLjAxNkEuMTMuMTMgMCAwIDEgOC4wMDIgMmEuMTMuMTMgMCAwIDEgLjA2My4wMTYuMTUuMTUgMCAwIDEgLjA1NC4wNTdsNi44NTcgMTEuNjY3Yy4wMzYuMDYuMDM1LjEyNC4wMDIuMTgzYS4yLjIgMCAwIDEtLjA1NC4wNi4xLjEgMCAwIDEtLjA2Ni4wMTdIMS4xNDZhLjEuMSAwIDAgMS0uMDY2LS4wMTcuMi4yIDAgMCAxLS4wNTQtLjA2LjE4LjE4IDAgMCAxIC4wMDItLjE4M0w3Ljg4NCAyLjA3M2EuMTUuMTUgMCAwIDEgLjA1NC0uMDU3bTEuMDQ0LS40NWExLjEzIDEuMTMgMCAwIDAtMS45NiAwTC4xNjUgMTMuMjMzYy0uNDU3Ljc3OC4wOTEgMS43NjcuOTggMS43NjdoMTMuNzEzYy44ODkgMCAxLjQzOC0uOTkuOTgtMS43Njd6Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDEyYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNS45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-warning.callout-style-default > .callout-header { + background-color: #fad8ca !important; +} + +/* Important */ + +div.callout-important.callout { + border-left-color: $posit-burgundy !important; +} + +div.callout-important .callout-icon::before { + // base64 -i _extensions/posit-docs/assets/images/exclamation-circle.svg + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0iIzJFMTcxRiIgY2xhc3M9ImJpIGJpLWV4Y2xhbWF0aW9uLWNpcmNsZSIgdmlld0JveD0iMCAwIDE2IDE2Ij4KICA8cGF0aCBkPSJNOCAxNUE3IDcgMCAxIDEgOCAxYTcgNyAwIDAgMSAwIDE0bTAgMUE4IDggMCAxIDAgOCAwYTggOCAwIDAgMCAwIDE2Ii8+CiAgPHBhdGggZD0iTTcuMDAyIDExYTEgMSAwIDEgMSAyIDAgMSAxIDAgMCAxLTIgME03LjEgNC45OTVhLjkwNS45MDUgMCAxIDEgMS44IDBsLS4zNSAzLjUwN2EuNTUyLjU1MiAwIDAgMS0xLjEgMHoiLz4KPC9zdmc+") !important; +} + +div.callout-important.callout-style-default > .callout-header { + background-color: #f2dae3 !important; +} // Specialty headers @@ -205,34 +384,30 @@ div span.preview-feature { text-transform: uppercase; } -// Lists - -/* List disc colors */ -li::marker { - color: $primary; -} +// Specialty lists /* Callout steps for images with multiple items/steps shown in single image */ + ol.groovyAlpha { - list-style: none; - counter-reset: list-counter; - } - + list-style: none; + counter-reset: list-counter; +} + ol.groovyAlpha li { counter-increment: list-counter; } ol.groovyAlpha li > p:before { content: counter(list-counter, lower-alpha); - width: 16px; - height: 16px; + width: 20px; + height: 20px; text-align: center; margin-right: 10px; color: #fff; background-color: #fc403b; display: inline-block; - border-radius: 8px; - font-size: 9px; + border-radius: 10px; + font-size: 14px; line-height: 16px; vertical-align: middle; } diff --git a/_quarto.yml b/_quarto.yml index 8554e84c..3b34b996 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -32,24 +32,18 @@ website: left: | Copyright © 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. center: | - Posit Helm Charts {{< env PRODUCT_VERSION >}} + Posit Helm Charts right: - icon: question-circle-fill + aria-label: 'Link to Posit Support' href: "https://support.posit.co/hc/en-us" - icon: lightbulb-fill + aria-label: 'Link to Posit Solutions' href: "https://solutions.posit.co/" - - text: "" + - text: "" href: "https://docs.posit.co/" - - text: "" + - text: "" href: "https://posit.co/" - navbar: - right: - - icon: "list" - menu: - - text: "docs.posit.co" - href: "https://docs.posit.co" - - text: "Posit Support" - href: "https://support.posit.co/hc/en-us/" sidebar: style: "floating" collapse-level: 1 From a4ef6757202ac003e1d6164d76bb7d0e3865af72 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Fri, 10 May 2024 20:55:01 -0400 Subject: [PATCH 30/67] Not sure what the start year should be here --- _quarto.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_quarto.yml b/_quarto.yml index 3b34b996..2abeacf5 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -30,7 +30,7 @@ website: repo-actions: [edit, issue] page-footer: left: | - Copyright © 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. + Copyright © 2???-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. center: | Posit Helm Charts right: From 022d4995a30bc70c796d64b4508cfbfbfc7b9d29 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 16:44:19 -0400 Subject: [PATCH 31/67] Home page updates --- index.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.qmd b/index.qmd index 435cdc7b..bc20cc3b 100644 --- a/index.qmd +++ b/index.qmd @@ -11,12 +11,12 @@ title: Posit Helm Charts 2. Add the Posit Helm repository: - ```console + ```{.bash} helm repo add rstudio https://helm.rstudio.com ``` 3. View charts: - ```console + ```{.bash} helm search repo rstudio ``` \ No newline at end of file From b5dc2901c23e7bc7b304de1a6ada054a30b83310 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 16:44:36 -0400 Subject: [PATCH 32/67] Initial workbench scrub - Editing pass - Heading changes in Examples --- charts/rstudio-workbench/README.md | 185 ++++++++---------- examples/examples.ejs | 4 +- .../application-configuration/index.qmd | 2 +- .../container-images/custom-images.qmd | 2 +- .../container-images/private-images.qmd | 2 +- 5 files changed, 87 insertions(+), 108 deletions(-) diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 01abf0ab..0acf0ee2 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -5,7 +5,7 @@ code-overflow: wrap ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Workbench_ +#### _Official Helm chart for Posit Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. @@ -45,7 +45,7 @@ helm search repo rstudio/rstudio-workbench -l To function, this chart requires the following: -* A license file, license key, or the address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the @@ -84,11 +84,10 @@ To function, this chart requires the following: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against directly placing it in your values file. +This chart supports activating the product using a *license file*. -### License file - -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend *against* directly placing the license file in your values file. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: @@ -111,37 +110,21 @@ Alternatively, license files can be set during `helm install` with the following --set-file license.file.contents=licenses/rstudio-workbench.lic ``` -### License key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument: - -```bash ---set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX -``` - -### License server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument: - -```bash ---set license.server= -``` - ## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. + valid `.ini` or `.dcf` file formats required by Workbench. - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. -- If you need to modify the jobs launched by RStudio Workbench, use `job-json-overrides`. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to get the service account information off of the RStudio Workbench pod for use in launching jobs. -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. - This is described in the [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values +These configuration values all take the form of usual Helm values so you can set the database password with similar to: ```bash @@ -161,63 +144,63 @@ The names of files are dynamically used, so you can add new files as needed. Bew so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change the `XDG_CONFIG_DIRS` environment variable. -- Session Configuration: - - Configuration files: `repos.conf`, `rsession.conf`, `notifications.conf` - - These configuration files are mounted into the server and - the session pods. - - Located in the `config.session.<< name of file >>` helm values - - Mounted at `/mnt/session-configmap/rstudio/` +- Session Configuration + - These configuration files are mounted into the server and + are mounted into the session pods. + - `repos.conf`, `rsession.conf`, `notifications.conf` + - Located in:
    `config.session.<< name of file >>` Helm values + - Mounted at:
    `/mnt/session-configmap/rstudio/` - Session Secret Configuration: - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
    `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
    `/mnt/session-secret/` - Secret Configuration: - - These configuration files are mounted into the server with more restrictive permissions (0600) + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` + - Located in:
    `config.secret.<< name of file >>` Helm values + - Mounted at:
    `/mnt/secret-configmap/rstudio/` - Server Configuration: - - These configuration files are mounted into the server (.ini file format) + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` + - Located at:
    `config.server.<< name of file >>` Helm values + - Mounted at:
    `/mnt/configmap/rstudio/` - Server DCF Configuration: - - These configuration files are mounted into the server (.dcf file format) + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` + - Located at:
    `config.serverDcf.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` - Profiles Configuration: - - These configuration files are mounted into the server (.ini file format) + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the [Profiles](#rstudio-profiles) section below for more information + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
    `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. - Prestart: - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. - User Provisioning Configuration: - - These configuration files are used for configuring user provisioning (i.e., `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
    `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
    `/etc/sssd/conf.d/` with `0600` permissions by default. - Custom Startup Configuration: - - `supervisord` service / unit definition `.conf` files - - Use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all configuration files above, can override with a verbatim string if desired: - - Located at `config.startupCustom.<< name of file >>` helm values: - ```yaml - config: - startupCustom: - myfile.conf: | - file-used-verbatim - ``` + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
    `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
    `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` - PAM configuration: - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` + - `pam` configuration files. + - Located at:
    `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
    `/etc/pam.d/<< name of file >>` ### Configuring Python and R repositories @@ -228,17 +211,17 @@ pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mo - `launcher.useTemplates: true` is set - `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -```yaml -launcher: - useTemplates: true + ```yaml + launcher: + useTemplates: true -config: - session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co -``` + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` #### R repositories @@ -255,12 +238,12 @@ For more information about configuring CRAN repositories in Workbench, see the [ ## User provisioning -Provisioning users in RStudio Workbench containers is challenging. Session images create users automatically (with +Provisioning users in Workbench containers is challenging. Session images create users automatically (with consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) @@ -268,21 +251,22 @@ or a polling service (checks at regular intervals). Either can be written easily However, it is important to use caution for the following: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing can cause security issues and access by some users to access view they should not be allowed to see. -- Usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames. -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily. +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a +We do not provide such a service out of the box because we intend for Workbench to solve this problem in a future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For @@ -390,15 +374,11 @@ If you want to customize the job launch process (i.e., how sessions are defined) config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` ``` - Create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) becomes a configuration filename on disk. - - `json`: a YAML value that is translated directly to JSON and injected into the job spec at `target`. - -Several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md).x +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -420,7 +400,7 @@ config: ## Sealed secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): @@ -430,7 +410,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -579,4 +559,3 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - diff --git a/examples/examples.ejs b/examples/examples.ejs index 069909a4..4fdf632f 100644 --- a/examples/examples.ejs +++ b/examples/examples.ejs @@ -2,7 +2,7 @@ const postsByCategory = {}; const basicConfigPosts = []; items.forEach(item => { - if (item.category === "Basic Configuration") { + if (item.category === "Basic configuration") { basicConfigPosts.push(item) } else { if (!postsByCategory[item.category]) { @@ -14,7 +14,7 @@ items.forEach(item => { // Basic config first if (basicConfigPosts.length > 0) { %> -

    Basic Configuration

    +

    Basic configuration

      <% basicConfigPosts.forEach(post => { %>
    • diff --git a/examples/workbench/application-configuration/index.qmd b/examples/workbench/application-configuration/index.qmd index 298a98ca..4551a908 100644 --- a/examples/workbench/application-configuration/index.qmd +++ b/examples/workbench/application-configuration/index.qmd @@ -1,5 +1,5 @@ --- -category: "Basic Configuration" +category: "Basic configuration" --- # Configuring Posit Workbench with Recommended Settings diff --git a/examples/workbench/container-images/custom-images.qmd b/examples/workbench/container-images/custom-images.qmd index df55c281..10ec1dab 100644 --- a/examples/workbench/container-images/custom-images.qmd +++ b/examples/workbench/container-images/custom-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Workbench with Custom Container Images diff --git a/examples/workbench/container-images/private-images.qmd b/examples/workbench/container-images/private-images.qmd index 886c926e..8a74b6cf 100644 --- a/examples/workbench/container-images/private-images.qmd +++ b/examples/workbench/container-images/private-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Workbench to Access Image Registries Requiring Authentication From d90fedd6a2e4e602948d8cd5091a073254472cb6 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:47:27 -0400 Subject: [PATCH 33/67] trying to standardize the content between the two files where I can --- charts/rstudio-connect/README.md | 77 +++++++++++++++--------------- charts/rstudio-workbench/README.md | 13 +++-- 2 files changed, 45 insertions(+), 45 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a44de207..f0f5dda9 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for RStudio Connect_ +#### _Official Helm chart for Posit Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. @@ -12,56 +12,63 @@ that are published by Data Scientists. Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. -## Installing the Chart + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.6.6: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-connect -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container - by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. + In this case, we recommend you: + * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + data in the container by using a + regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` + and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` +```{.bash} +kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic Second, specify the following values: @@ -74,29 +81,23 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-connect.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-connect.lic +``` -## General Principles +## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format required by rstudio-connect. - rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration File +## Configuration file The configuration values all take the form of usual helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 0acf0ee2..79dfc3f9 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -23,8 +23,7 @@ To ensure a stable production deployment: ::: * Before upgrading check for breaking changes using `helm diff upgrade`. -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes and the documentation below on how to use the chart. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. ## Installing the chart @@ -51,9 +50,9 @@ To function, this chart requires the following: * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: - * disable `homeStorage.create` and + * Disable `homeStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * mount them into the container by specifying + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your @@ -84,14 +83,14 @@ To function, this chart requires the following: ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a *license file*. - We recommend *against* directly placing the license file in your values file. - We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```bash +```{.bash} kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic ``` @@ -259,7 +258,7 @@ However, it is important to use caution for the following: - `supervisord` is configured by default to exit if any of its child processes exit. - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for Workbench to solve this problem in a +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a future release. Please contact your account representative if you have feedback or questions about this workflow. From 190cc44cb1162f505226a773465ead203ec3c897 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:48:32 -0400 Subject: [PATCH 34/67] helm fix --- charts/rstudio-connect/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index f0f5dda9..f02c37ea 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -94,7 +94,7 @@ required by rstudio-connect. ## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ```{.bash} From a6bab1ce7f8bc2cada69851302b4bd7b0c5d6048 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:53:30 -0400 Subject: [PATCH 35/67] Not sure if these should be formatted or not but I did it just in case --- charts/rstudio-connect/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index f02c37ea..860aaea9 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -88,8 +88,8 @@ Alternatively, license files can be set during `helm install` with the following ## General principles - In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by rstudio-connect. -- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +required by `rstudio-connect`. +- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration file From 81ded35e8ced727f1b4c708a2c389e51fe970cd7 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 20:57:36 -0400 Subject: [PATCH 36/67] Minor edits to the configuration files --- examples/connect/application-configuration/index.qmd | 2 +- examples/connect/beta-migration/index.qmd | 2 +- examples/connect/container-images/custom-images.qmd | 2 +- examples/connect/container-images/private-images.qmd | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/connect/application-configuration/index.qmd b/examples/connect/application-configuration/index.qmd index 2ceb80c6..c8475c97 100644 --- a/examples/connect/application-configuration/index.qmd +++ b/examples/connect/application-configuration/index.qmd @@ -1,5 +1,5 @@ --- -category: "Basic Configuration" +category: "Basic configuration" --- # Configuring Posit Connect with Recommended Settings diff --git a/examples/connect/beta-migration/index.qmd b/examples/connect/beta-migration/index.qmd index 2993a3eb..99e81200 100644 --- a/examples/connect/beta-migration/index.qmd +++ b/examples/connect/beta-migration/index.qmd @@ -1,5 +1,5 @@ --- -category: "Beta Migration" +category: "Beta migration" --- # Off-Host Execution Beta User Migration diff --git a/examples/connect/container-images/custom-images.qmd b/examples/connect/container-images/custom-images.qmd index 5407c999..0b73badc 100644 --- a/examples/connect/container-images/custom-images.qmd +++ b/examples/connect/container-images/custom-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Connect with Custom Container Images diff --git a/examples/connect/container-images/private-images.qmd b/examples/connect/container-images/private-images.qmd index 6d387753..cfad496b 100644 --- a/examples/connect/container-images/private-images.qmd +++ b/examples/connect/container-images/private-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Connect to Access Image Registries Requiring Authentication From 5328f3b66b2d1794f834e629884e2257af387c39 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 21:23:26 -0400 Subject: [PATCH 37/67] Missed heading change --- charts/rstudio-connect/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 860aaea9..bd2bd796 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -7,7 +7,7 @@ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and From 8680940f84a2653ec2d266245fd5be395dacd2e1 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Mon, 13 May 2024 21:27:03 -0400 Subject: [PATCH 38/67] Start of ppm edits --- charts/rstudio-pm/README.md | 41 +++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index b6f9d265..5e29c092 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,46 +2,51 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Package Manager_ +#### _Official Helm chart for Posit Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.5.25: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-pm -l ``` -## Upgrade Guidance +## Upgrade guidance ### 0.4.0 -- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to - fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. +* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`) +* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. + * To disable an automatic fixup / hook, set `enableMigrations=false`. -## Required Configuration +## Required configuration This chart requires the following in order to function: From 0028366c0b45f5c52c442dd1d32f0e02959c9cae Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 12:33:26 +0000 Subject: [PATCH 39/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 83 ++++--- charts/rstudio-workbench/README.md | 379 ++++++++++++++--------------- 2 files changed, 225 insertions(+), 237 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index bd2bd796..066cd564 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for Posit Connect_ +#### _Official Helm chart for RStudio Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. @@ -12,63 +12,56 @@ that are published by Data Scientists. Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether Helm is a good choice for your deployment. +if you need help deciding whether helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* "Pin" the version of the Helm chart that you are using. You can do - this using the: - * `helm dependency` command and the associated "Chart.lock" files _or_ - * the `--version` flag. +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check + for breaking changes +* Read [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart - :::{.callout-important} - This protects you from breaking changes** - ::: - -* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.6.6: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-connect -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you: - * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your - data in the container by using a - regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` - and `pod.volumeMounts`. + In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic +`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` Second, specify the following values: @@ -81,23 +74,29 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-connect.lic -``` +`--set-file license.file.contents=licenses/rstudio-connect.lic` -## General principles +### License Key -- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by `rstudio-connect`. -- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles + +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +required by rstudio-connect. +- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration file +## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: -```{.bash} +``` ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 79dfc3f9..9cda63d7 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,31 +1,25 @@ ---- -title: Posit Workbench -code-overflow: wrap ---- +# Posit Workbench ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Workbench_ +#### _Official Helm chart for RStudio Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.7.3: @@ -35,64 +29,59 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: - -```bash +``` helm search repo rstudio/rstudio-workbench -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: - * Disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: - - ```yaml - config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap - ``` +```yaml +config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap +``` ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File -- We recommend *against* directly placing the license file in your values file. -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic -``` +`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` Second, specify the following values: @@ -105,32 +94,39 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```bash ---set-file license.file.contents=licenses/rstudio-workbench.lic -``` +`--set-file license.file.contents=licenses/rstudio-workbench.lic` + +### License Key + +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. -## General principles +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by Workbench. - - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. -- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. - - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). -- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. -- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. - - This is described in the - [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. + valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are + below. +- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below + and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) + on the topic in general. +- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: + - Get the service account information off of the RStudio Workbench pod for use in launching jobs +- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter + [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration files -These configuration values all take the form of usual Helm values -so you can set the database password with similar to: +These configuration values all take the form of usual helm values +so you can set the database password with something like: -```bash +``` ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -140,135 +136,130 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change -the `XDG_CONFIG_DIRS` environment variable. +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change +the `XDG_CONFIG_DIRS` environment variable - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods. + are mounted into the session pods as well. - `repos.conf`, `rsession.conf`, `notifications.conf` - - Located in:
      `config.session.<< name of file >>` Helm values - - Mounted at:
      `/mnt/session-configmap/rstudio/` -- Session Secret Configuration: - - These configuration files are mounted into the server and session pods. - - `odbc.ini` and other similar shared secrets. - - Located in:
      `config.sessionSecret.<< name of file>>` Helm values - - Mounted at:
      `/mnt/session-secret/` -- Secret Configuration: - - These configuration files are mounted into the server with more restrictive permissions (0600). + - located in the `config.session.<< name of file >>` helm values + - mounted at `/mnt/session-configmap/rstudio/` +- Session Secret Configuration + - These configuration files are mounted into the server and session pods as well + - `odbc.ini` and other similar shared secrets + - located in `config.sessionSecret.<< name of file>>` helm values + - mounted at `/mnt/session-secret/` +- Secret Configuration + - These configuration files are mounted into the server with more restrictive permissions (0600) - `database.conf`, `openid-client-secret`, `databricks.conf` - - Located in:
      `config.secret.<< name of file >>` Helm values - - Mounted at:
      `/mnt/secret-configmap/rstudio/` -- Server Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located in the `config.secret.<< name of file >>` helm values + - mounted at `/mnt/secret-configmap/rstudio/` +- Server Configuration + - These configuration files are mounted into the server (.ini file format) - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - Located at:
      `config.server.<< name of file >>` Helm values - - Mounted at:
      `/mnt/configmap/rstudio/` -- Server DCF Configuration: - - These configuration files are mounted into the server (.dcf file format). + - They are located at `config.server.<< name of file >>` helm values + - mounted at `/mnt/configmap/rstudio/` +- Server DCF Configuration + - These configuration files are mounted into the server (.dcf file format) - `launcher-mounts`, `launcher-env` - - Located at:
      `config.serverDcf.<< name of file >>` Helm values - - Included at:
      `/mnt/configmap/rstudio/` -- Profiles Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located at `config.serverDcf.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` +- Profiles Configuration + - These configuration files are mounted into the server (.ini file format) - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` Helm values - - Included at:
      `/mnt/configmap/rstudio/` - - See the [Profiles](#rstudio-profiles) section below for more information. -- Prestart: - - This is provided by the Helm chart in a configmap. - - It is mounted into the pod at `/scripts/`. - - `prestart-workbench.bash` is used to start workbench. - - `prestart-launcher.bash` is used to start launcher. -- User Provisioning Configuration: - - These configuration files are used for configuring user provisioning (i.e., `sssd`). - - Located at:
      `config.userProvisioning.<< name of file >>` Helm values - - Mounted onto:
      `/etc/sssd/conf.d/` with `0600` permissions by default. -- Custom Startup Configuration: - - `supervisord` service / unit definition `.conf` files. - - Use the `.ini` file format by default. - - Mounted at:
      `/startup/custom` - - As with all configuration files above, you can override with a verbatim string if desired: - - Located at:
      `config.startupCustom.<< name of file >>` Helm values: - ```yaml - config: - startupCustom: - myfile.conf: | - file-used-verbatim - ``` -- PAM configuration: - - `pam` configuration files. - - Located at:
      `config.pam.<< name of file >>` Helm values - - Mounted verbatim as individual files (using `subPath` mounts) at:
      `/etc/pam.d/<< name of file >>` - -### Configuring Python and R repositories - -#### Python repositories - -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: - -- `launcher.useTemplates: true` is set -- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: - - ```yaml - launcher: - useTemplates: true + - They are located at `config.profiles.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` + - See the `Profiles` section below for more information +- Prestart + - This is provided by the helm chart in a configmap + - It is mounted into the pod at `/scripts/` + - `prestart-workbench.bash` is used to start workbench + - `prestart-launcher.bash` is used to start launcher +- User Provisioning Configuration + - These configuration files are used for configuring user provisioning (i.e. `sssd`) + - Located at `config.userProvisioning.<< name of file >>` helm values + - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default +- Custom Startup Configuration + - `supervisord` service / unit definition `.conf` files + - Located at `config.startupCustom.<< name of file >>` helm values + - Will use the `.ini` file format, by default + - Mounted at `/startup/custom` + - As with all config files above, can override with a verbatim string if desired, like so: +```yaml +config: + startupCustom: + myfile.conf: | + file-used-verbatim +``` +- PAM configuration + - `pam` configuration files + - Located at `config.pam.<< name of file >>` helm values + - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - config: - session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co - ``` +### Configuring R and Python repositories #### R repositories -R package repositories can be configured with `config.session.repos.conf`: +R package repositories can be configured with `config.session.repos.conf`. -```yaml +``` config: session: repos.conf: CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. +For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). -## User provisioning +#### Python repositories + +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. -Provisioning users in Workbench containers is challenging. Session images create users automatically (with -consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the -administrator. +``` +launcher: + useTemplates: true + +config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co +``` + +## User Provisioning + +Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with +consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the +administrator today. The most common way to provision users is via `sssd`. -The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. +However, it is important to be careful of a few points: -However, it is important to use caution for the following: - -- UID / GID consistency: - - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. - - Failing can cause security issues and access by some users to access view they should not be allowed to see. -- Usernames cannot have `@`. - - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. -- `supervisord` is configured by default to exit if any of its child processes exit. - - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. +- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across + time. Failing this can cause security issues and access by some users to files they should not be allowed to see +- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because + some operating systems disallow `@` signs in linux usernames +- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` + to configure a user management service, be careful that it does not exit unnecessarily -We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a -future release. Please contact your account representative if you have feedback or questions about this +We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a +future release. Please get in touch with your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -288,17 +279,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- If section header is `[*]`, it applies to all users. -- If a user's username is `myusername`, the section `[myusername]` applies to them. -- If a user is in the `allusers` group, then the section `[@allusers]` applies to them +- if section header is `[*]`, it applies to all users +- if a user's username is `myusername`, the section `[myusername]` will apply to them +- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. -In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: +In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: ```yaml config: @@ -321,17 +312,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` +- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` - ```yaml - some-key: - - value1 - - value2 - ``` +```yaml +some-key: + - value1 + - value2 +``` -- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -348,7 +339,6 @@ config: - value4 - value5 ``` - Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -360,24 +350,23 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -:::{.callout-note} -This appending/concatenation/array translation behavior only works with the helm chart. -::: +> NOTE: this appending/concatenation/array translation behavior only works with the helm chart -### Job Json overrides +### Job Json Overrides -If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: +If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following +configuration: + - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + - create an array of maps with the following keys: + - `target`: the "target" part of the job spec to replace + - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk + - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` -- Modify: - ```yaml - config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - ``` -- Create an array of maps with the following keys: - - `target`: The "target" part of the job spec to replace. - - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. - - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. +Note that several examples are provided +in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) +(however, examples do not use the helm chart syntax there). -Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. +Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) ```yaml config: @@ -397,11 +386,10 @@ config: - "two-image:tag ``` -## Sealed secrets +## Sealed Secrets +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. - -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. - `config.secret` - `config.sessionSecret` @@ -409,7 +397,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -558,3 +546,4 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + From da7a2c9540cd716db335404c54b1a2780eafb6cd Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:35:13 -0400 Subject: [PATCH 40/67] PPM edits --- charts/rstudio-pm/README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 5e29c092..fde9eb3e 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -136,12 +136,12 @@ should be avoided if at all possible. ## General Principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration File -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -202,7 +202,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | | resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | | rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | @@ -232,8 +232,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - From 0e17b3ced01a018c2d775227763b7a064d9f7e65 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 12:36:27 +0000 Subject: [PATCH 41/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 50 +++++++++++++++----------------- 2 files changed, 24 insertions(+), 28 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 066cd564..a44de207 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -7,7 +7,7 @@ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best practices +## Best Practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index fde9eb3e..b6f9d265 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,51 +2,46 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Package Manager_ +#### _Official Helm chart for RStudio Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.5.25: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-pm -l ``` -## Upgrade guidance +## Upgrade Guidance ### 0.4.0 -* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`) -* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. - * To disable an automatic fixup / hook, set `enableMigrations=false`. +- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to + fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. -## Required configuration +## Required Configuration This chart requires the following in order to function: @@ -136,12 +131,12 @@ should be avoided if at all possible. ## General Principles -- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: ``` @@ -202,7 +197,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | | resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | | rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | @@ -232,7 +227,8 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + From 0d14e73dfa4a61643a50369f71afecc8523d699a Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:37:53 -0400 Subject: [PATCH 42/67] Revert "Update helm-docs and README.md" This reverts commit 93c1265bb58af4cabad7a722985cafcf91fd9ee4. --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 50 +++++++++++++++++--------------- 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a44de207..066cd564 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -7,7 +7,7 @@ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index b6f9d265..fde9eb3e 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,46 +2,51 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Package Manager_ +#### _Official Helm chart for Posit Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.5.25: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-pm -l ``` -## Upgrade Guidance +## Upgrade guidance ### 0.4.0 -- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to - fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. +* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`) +* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. + * To disable an automatic fixup / hook, set `enableMigrations=false`. -## Required Configuration +## Required configuration This chart requires the following in order to function: @@ -131,12 +136,12 @@ should be avoided if at all possible. ## General Principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration File -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -197,7 +202,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | | resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | | rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | @@ -227,8 +232,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - From 9b5cd2f88dd098aad22e5aafd506de8707ffa113 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:41:46 -0400 Subject: [PATCH 43/67] Revert "Merge branch 'ah/editing-pass' of https://github.com/rstudio/helm into ah/editing-pass" This reverts commit 8713b44aabd5648808c214f4d0ffea886bd39ef3, reversing changes made to 2f87134bb1db9640f6748bb3cffc59ba40f98a1f. --- charts/rstudio-connect/README.md | 83 +++---- charts/rstudio-workbench/README.md | 379 +++++++++++++++-------------- 2 files changed, 237 insertions(+), 225 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 066cd564..bd2bd796 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for RStudio Connect_ +#### _Official Helm chart for Posit Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. @@ -12,56 +12,63 @@ that are published by Data Scientists. Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. -## Installing the Chart + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.6.6: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/rstudio-connect -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container - by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. + In this case, we recommend you: + * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + data in the container by using a + regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` + and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` +```{.bash} +kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic Second, specify the following values: @@ -74,29 +81,23 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-connect.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-connect.lic +``` -## General Principles +## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format -required by rstudio-connect. -- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format +required by `rstudio-connect`. +- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration File +## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9cda63d7..79dfc3f9 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,25 +1,31 @@ -# Posit Workbench +--- +title: Posit Workbench +code-overflow: wrap +--- ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Workbench_ +#### _Official Helm chart for Posit Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.7.3: @@ -29,59 +35,64 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: -``` + +```bash helm search repo rstudio/rstudio-workbench -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * Disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` -## Licensing + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +## Licensing -### License File +This chart supports activating the product using a *license file*. -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend *against* directly placing the license file in your values file. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` +```{.bash} +kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic +``` Second, specify the following values: @@ -94,39 +105,32 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-workbench.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```bash +--set-file license.file.contents=licenses/rstudio-workbench.lic +``` -## General Principles +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values -so you can set the database password with something like: +These configuration values all take the form of usual Helm values +so you can set the database password with similar to: -``` +```bash ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -136,130 +140,135 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods as well. + are mounted into the session pods. - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` -- Secret Configuration - - These configuration files are mounted into the server with more restrictive permissions (0600) + - Located in:
      `config.session.<< name of file >>` Helm values + - Mounted at:
      `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
      `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
      `/mnt/session-secret/` +- Secret Configuration: + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration - - These configuration files are mounted into the server (.ini file format) + - Located in:
      `config.secret.<< name of file >>` Helm values + - Mounted at:
      `/mnt/secret-configmap/rstudio/` +- Server Configuration: + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration - - These configuration files are mounted into the server (.dcf file format) + - Located at:
      `config.server.<< name of file >>` Helm values + - Mounted at:
      `/mnt/configmap/rstudio/` +- Server DCF Configuration: + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` -- Profiles Configuration - - These configuration files are mounted into the server (.ini file format) + - Located at:
      `config.serverDcf.<< name of file >>` Helm values + - Included at:
      `/mnt/configmap/rstudio/` +- Profiles Configuration: + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration - - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - -### Configuring R and Python repositories + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
      `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. +- Prestart: + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
      `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
      `/etc/sssd/conf.d/` with `0600` permissions by default. +- Custom Startup Configuration: + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
      `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
      `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: + - `pam` configuration files. + - Located at:
      `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
      `/etc/pam.d/<< name of file >>` + +### Configuring Python and R repositories -#### R repositories +#### Python repositories -R package repositories can be configured with `config.session.repos.conf`. +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + ```yaml + launcher: + useTemplates: true -#### Python repositories + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +#### R repositories -``` -launcher: - useTemplates: true +R package repositories can be configured with `config.session.repos.conf`: +```yaml config: session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -## User Provisioning +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +## User provisioning + +Provisioning users in Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily +However, it is important to use caution for the following: + +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -279,17 +288,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -312,17 +321,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -339,6 +348,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -350,23 +360,24 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: -### Job Json Overrides +### Job Json overrides -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -Note that several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -386,10 +397,11 @@ config: - "two-image:tag ``` -## Sealed Secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +## Sealed secrets -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. + +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -397,7 +409,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -546,4 +558,3 @@ Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - From 14d897c99930b28695e02bd1584184718a757491 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 08:59:31 -0400 Subject: [PATCH 44/67] additional readme edits --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 45 +++++++++++++----------------- charts/rstudio-workbench/README.md | 7 ++--- 3 files changed, 24 insertions(+), 30 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index bd2bd796..a06044aa 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -63,7 +63,7 @@ To function, this chart requires the following: This chart supports activating the product using a *license file*. -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index fde9eb3e..912d5039 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -50,7 +50,7 @@ helm search repo rstudio/rstudio-pm -l This chart requires the following in order to function: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for RSPM. * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. @@ -62,15 +62,16 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +This chart supports activating the product using a *license file*. -### License File -We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic` +```{.bash} +kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic +``` Second, specify the following values: @@ -83,17 +84,11 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-pm.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-pm.lic +``` -## S3 Configuration +## S3 configuration Package Manager [can be configured to store its data in S3 buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), @@ -131,20 +126,20 @@ awsAccessKeyId: your-access-key-id awsSecretAccessKey: your-secret-access-key ``` -Bear in mind that static, long-lived credentials are the least secure option and +Consider that static, long-lived credentials are the least secure option and should be avoided if at all possible. -## General Principles +## General principles -- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format -required by rstudio-pm. +In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format +required by `rstudio-pm`. -## Configuration File +## Configuration file The configuration values all take the form of usual Helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` @@ -159,7 +154,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | awsAccessKeyId | bool | `false` | awsAccessKeyId is the access key id for s3 access, used also to gate file creation | | awsSecretAccessKey | string | `nil` | awsSecretAccessKey is the secret access key, needs to be filled if access_key_id is | | command | bool | `false` | command is the pod's run command. By default, it uses the container's default | -| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the rstudio-pm.gcfg file | +| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the `rstudio-pm`.gcfg file | | enableMigration | bool | `true` | Enable migrations for shared storage (if necessary) using Helm hooks. | | enableSandboxing | bool | `true` | Enable sandboxing of Git builds, which requires elevated security privileges for the Package Manager container. | | extraContainers | list | `[]` | sidecar container list | @@ -190,7 +185,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | pod.annotations | object | `{}` | annotations is a map of keys / values that will be added as annotations to the pods | | pod.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"runAsNonRoot":true,"runAsUser":999,"seccompProfile":{"type":"{{ if .Values.enableSandboxing }}Unconfined{{ else }}RuntimeDefault{{ end }}"}}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the main Package Manager container. Evaluated as a template. | | pod.env | list | `[]` | env is an array of maps that is injected as-is into the "env:" component of the pod.container spec | -| pod.labels | object | `{}` | Additional labels to add to the rstudio-pm pods | +| pod.labels | object | `{}` | Additional labels to add to the `rstudio-pm` pods | | pod.lifecycle | object | `{}` | Container [lifecycle hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/) | | pod.securityContext | object | `{}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the pod | | pod.serviceAccountName | string | `""` | Deprecated, use `serviceAccount.name` instead | @@ -201,9 +196,9 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | priorityClassName | string | `""` | The pod's priorityClassName | | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | -| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | +| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the `rstudio-pm` pod | | rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | -| rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | +| rstudioPMKey | bool | `false` | rstudioPMKey is the `rstudio-pm` key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | | service.loadBalancerIP | string | `""` | The external IP to use with `service.type` LoadBalancer, when supported by the cloud provider | diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 79dfc3f9..a2053022 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -85,8 +85,7 @@ To function, this chart requires the following: This chart supports activating the product using a *license file*. -- We recommend *against* directly placing the license file in your values file. -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: @@ -105,7 +104,7 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```bash +```{.bash} --set-file license.file.contents=licenses/rstudio-workbench.lic ``` @@ -126,7 +125,7 @@ Alternatively, license files can be set during `helm install` with the following These configuration values all take the form of usual Helm values so you can set the database password with similar to: -```bash +```{.bash} ... --set config.secret.database\.conf.password=mypassword ... ``` From dac609d115999a51ec053c1db74139a15bd307b4 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 09:04:33 -0400 Subject: [PATCH 45/67] ppm examples --- examples/package-manager/container-images/custom-images.qmd | 2 +- examples/package-manager/container-images/private-images.qmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/package-manager/container-images/custom-images.qmd b/examples/package-manager/container-images/custom-images.qmd index ef765035..b8fbb38d 100644 --- a/examples/package-manager/container-images/custom-images.qmd +++ b/examples/package-manager/container-images/custom-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Package Manager with Custom Container Images diff --git a/examples/package-manager/container-images/private-images.qmd b/examples/package-manager/container-images/private-images.qmd index 5f9dd663..112614eb 100644 --- a/examples/package-manager/container-images/private-images.qmd +++ b/examples/package-manager/container-images/private-images.qmd @@ -1,5 +1,5 @@ --- -category: "Container Images" +category: "Container images" --- # Configuring Posit Package Manager to Access Image Registries Requiring Authentication From 9ac8c932006b9d10f262c6fbbe22451aa51940ad Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 09:12:29 -0400 Subject: [PATCH 46/67] standardizing the before you begin --- charts/rstudio-pm/README.md | 2 +- charts/rstudio-workbench/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 912d5039..c50854a6 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -19,7 +19,7 @@ To ensure a stable production deployment: This protects you from breaking changes. ::: -* Before upgrading check for breaking changes using `helm diff upgrade`. +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. * Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. ## Installing the chart diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index a2053022..d533e169 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -22,7 +22,7 @@ To ensure a stable production deployment: This protects you from breaking changes. ::: -* Before upgrading check for breaking changes using `helm diff upgrade`. +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. * Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. ## Installing the chart From 9e4be90bd1781a60d3cd99c1e4125b63d9fdde81 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:07:20 -0400 Subject: [PATCH 47/67] Chronicle edits --- charts/posit-chronicle/README.md | 58 +++++++++++++++++--------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index fd9522a1..308f3f3d 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -8,40 +8,43 @@ Chronicle helps data science managers and other stakeholders understand their organization's use of other Posit products, primarily Posit Connect and Workbench. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: -## Installing the Chart +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.3.0: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.0 ``` To explore other chart versions, take a look at: -``` + +```{.bash} helm search repo rstudio/posit-chronicle -l ``` ## Usage This chart deploys only the Chronicle server and is meant to be used in tandem -with the Workbench and Connect charts. To actually send data to the server, you -will need to run the Chronicle agent as a sidecar container on your -Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files +with the Workbench and Connect charts. To send data to the server, run the Chronicle agent as a sidecar container on your +Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files. -Here is an example of Helm values to run the agent sidecar in **Workbench**, +Here is an example of Helm values to run the agent sidecar in *Workbench*, where we set up a shared volume between containers for audit logs: ```yaml @@ -65,7 +68,7 @@ pod: value: "http://chronicle-server.default" ``` -And here is an example of Helm values for Connect, where a **Connect** +Here is an example of Helm values for *Connect*, where a Connect API key from a Kubernetes Secret is used to unlock more detailed metrics: ```yaml @@ -83,7 +86,7 @@ pod: key: apikey ``` -Note that it is up to the user to provision this Kubernetes Secret for the +It is up to the user to provision this Kubernetes Secret for the Connect API key. ## Storage Configuration @@ -102,8 +105,7 @@ config: ``` `retentionPeriod` controls how long usage data are kept. For example, `"120m"` -for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention. -(Units smaller than seconds or larger than days are not supported.) +for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention (units smaller than seconds or larger than days are not supported). You can also persist data to AWS S3 instead of (or in addition to) local storage: @@ -116,7 +118,7 @@ config: Region: "us-east-2" ``` -### Using Iam for S3 +### Using IAM for S3 If you are running on EKS, you can use [IAM Roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) @@ -131,9 +133,9 @@ serviceaccount: eks.amazonaws.com/role-arn: arn:aws:iam::123456789000:role/iam-role-name-here ``` -If you are unable to use IAM Roles for Service Accounts, there are any number of +If you are unable to use IAM Roles for Service Accounts, there are many alternatives for injecting AWS credentials into a container. As a fallback, -the S3 storage config allows specifying a profile: +the S3 storage `config` allows specifying a profile: ```yaml config: @@ -144,14 +146,14 @@ config: Region: "us-east-2" ``` -### Needed S3 Policy Permissions +### Needed S3 policy permissions The credentials Chronicle uses for S3 storage must have the following permissions enabled: -- `s3:GetObject` -- `s3:ListBucket` -- `s3:PutObject` -- `s3:DeleteObject` +* `s3:GetObject` +* `s3:ListBucket` +* `s3:PutObject` +* `s3:DeleteObject` ## Values From cf4025cc2fd6e8794d126eae15ef715e0c1c5e1b Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:07:34 -0400 Subject: [PATCH 48/67] PPM edits --- charts/rstudio-pm/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index c50854a6..dd63295e 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -14,7 +14,7 @@ To ensure a stable production deployment: * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. - + ::: {.callout-important} This protects you from breaking changes. ::: From 131d374a050e5b3676358f259a96d023dc2df627 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:42:19 -0400 Subject: [PATCH 49/67] trying to "fix" everything --- charts/_templates.gotmpl | 72 ++--- charts/posit-chronicle/README.md | 8 +- charts/rstudio-connect/README.md | 5 +- charts/rstudio-pm/README.md | 5 +- charts/rstudio-workbench/README.md.gotmpl | 317 +++++++++++----------- 5 files changed, 214 insertions(+), 193 deletions(-) diff --git a/charts/_templates.gotmpl b/charts/_templates.gotmpl index bce09a9a..dce4b93c 100644 --- a/charts/_templates.gotmpl +++ b/charts/_templates.gotmpl @@ -40,49 +40,59 @@ Workbench. {{- define "rstudio.disclaimer" }} -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. {{- end }} {{- define "rstudio.best-practices" }} -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. + + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. {{- end }} {{- define "rstudio.install" }} {{- $isDev := (regexMatch "[0-9]+\\.[0-9]+\\.[0-9]+-[a-zA-Z\\.0-9]+" .Version) }} -## Installing the Chart +## Installing the chart To install the chart with the release name `my-release` at version {{ template "chart.version" . }}: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com {{- if not $isDev }} helm upgrade --install my-release rstudio/{{ template "chart.name" . }} --version={{ template "chart.version" . }} @@ -95,7 +105,7 @@ helm upgrade --install --devel my-release rstudio/{{ template "chart.name" . }} {{- end }} ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo {{ if $isDev }}--devel {{ end }}rstudio/{{ template "chart.name" . }} -l ``` @@ -106,15 +116,15 @@ helm search repo {{ if $isDev }}--devel {{ end }}rstudio/{{ template "chart.name ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic {{ .Name }}-license --from-file=licenses/{{ .Name }}.lic` +```{.bash} +kubectl create secret generic {{ .Name }}-license --from-file=licenses/{{ .Name }}.lic +``` Second, specify the following values: @@ -127,15 +137,9 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/{{ .Name }}.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/{{ .Name }}.lic +``` {{- end }} diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index 308f3f3d..98feb64e 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -1,4 +1,7 @@ -# Posit Chronicle +--- +title: Posit Chronicle +code-overflow: wrap +--- ![Version: 0.3.0](https://img.shields.io/badge/Version-0.3.0-informational?style=flat-square) ![AppVersion: 2024.03.0](https://img.shields.io/badge/AppVersion-2024.03.0-informational?style=flat-square) @@ -89,7 +92,7 @@ pod: It is up to the user to provision this Kubernetes Secret for the Connect API key. -## Storage Configuration +## Storage configuration Chronicle can be configured to persist data to a local Kubernetes Volume, AWS S3, or both. @@ -202,4 +205,3 @@ The credentials Chronicle uses for S3 storage must have the following permission ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) - diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a06044aa..5c6812fb 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -1,4 +1,7 @@ -# Posit Connect +--- +title: Posit Connect +code-overflow: wrap +--- ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index dd63295e..d892ff66 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -1,4 +1,7 @@ -# Posit Package Manager +--- +title: Posit Package Manager +code-overflow: wrap +--- ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) diff --git a/charts/rstudio-workbench/README.md.gotmpl b/charts/rstudio-workbench/README.md.gotmpl index b6398432..de45d2d0 100644 --- a/charts/rstudio-workbench/README.md.gotmpl +++ b/charts/rstudio-workbench/README.md.gotmpl @@ -8,62 +8,65 @@ {{ template "rstudio.install" . }} -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * Disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` {{ template "rstudio.licensing" . }} -## General Principles +## General principles + +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values +These configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -80,130 +83,133 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods as well. + are mounted into the session pods. - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` -- Secret Configuration - - These configuration files are mounted into the server with more restrictive permissions (0600) + - Located in:
      `config.session.<< name of file >>` Helm values + - Mounted at:
      `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
      `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
      `/mnt/session-secret/` +- Secret Configuration: + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration - - These configuration files are mounted into the server (.ini file format) + - Located in:
      `config.secret.<< name of file >>` Helm values + - Mounted at:
      `/mnt/secret-configmap/rstudio/` +- Server Configuration: + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration - - These configuration files are mounted into the server (.dcf file format) + - Located at:
      `config.server.<< name of file >>` Helm values + - Mounted at:
      `/mnt/configmap/rstudio/` +- Server DCF Configuration: + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` -- Profiles Configuration - - These configuration files are mounted into the server (.ini file format) + - Located at:
      `config.serverDcf.<< name of file >>` Helm values + - Included at:
      `/mnt/configmap/rstudio/` +- Profiles Configuration: + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration - - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
      `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. +- Prestart: + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
      `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
      `/etc/sssd/conf.d/` with `0600` permissions by default. +- Custom Startup Configuration: + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
      `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
      `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: + - `pam` configuration files. + - Located at:
      `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
      `/etc/pam.d/<< name of file >>` -### Configuring R and Python repositories - -#### R repositories +#### Python repositories -R package repositories can be configured with `config.session.repos.conf`. +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + ```yaml + launcher: + useTemplates: true -#### Python repositories + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +#### R repositories -``` -launcher: - useTemplates: true +R package repositories can be configured with `config.session.repos.conf`: +```yaml config: session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -## User Provisioning +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. + +## User provisioning -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +Provisioning users in Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily +However, it is important to use caution for the following: -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. + +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -217,23 +223,23 @@ config: # will be used verbatim ``` -## RStudio Profiles +## RStudio profiles Profiles are used to define product behavior (in `.ini` file format) based on user and group membership. Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -256,17 +262,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -283,6 +289,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -294,23 +301,24 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: -### Job Json Overrides +### Job Json overrides -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -Note that several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -330,10 +338,11 @@ config: - "two-image:tag ``` -## Sealed Secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +## Sealed secrets + +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -341,7 +350,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. {{ template "chart.valuesSection" . }} From ba364dc914fa53aa5c97e5c2238d95980d24619d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 12:59:51 +0000 Subject: [PATCH 50/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 83 ++++--- charts/rstudio-pm/README.md | 93 +++---- charts/rstudio-workbench/README.md | 376 ++++++++++++++--------------- 3 files changed, 271 insertions(+), 281 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 5c6812fb..8a04dbf9 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -5,73 +5,66 @@ code-overflow: wrap ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for Posit Connect_ +#### _Official Helm chart for RStudio Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best practices +## Best Practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether Helm is a good choice for your deployment. +if you need help deciding whether helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* "Pin" the version of the Helm chart that you are using. You can do - this using the: - * `helm dependency` command and the associated "Chart.lock" files _or_ - * the `--version` flag. +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check + for breaking changes +* Read [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart - :::{.callout-important} - This protects you from breaking changes** - ::: - -* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.6.6: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-connect -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a Persistent Volume Claim (PVC) that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. - In this case, we recommend you: - * Disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your - data in the container by using a - regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` - and `pod.volumeMounts`. + In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then + mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. + * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic +`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` Second, specify the following values: @@ -84,23 +77,29 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-connect.lic -``` +`--set-file license.file.contents=licenses/rstudio-connect.lic` -## General principles +### License Key -- In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by `rstudio-connect`. -- `rstudio-connect` does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles + +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +required by rstudio-connect. +- rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration file +## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: -```{.bash} +``` ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index d892ff66..9fcaca95 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -5,55 +5,50 @@ code-overflow: wrap ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Package Manager_ +#### _Official Helm chart for RStudio Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart - ::: {.callout-important} - This protects you from breaking changes. - ::: - -* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.5.25: -```{.bash} +```bash helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, take a look at: - -```{.bash} +``` helm search repo rstudio/rstudio-pm -l ``` -## Upgrade guidance +## Upgrade Guidance ### 0.4.0 -* When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`) -* A `chown` of persistent storage may be required. The issue has been recorded and the team is working to implement an automatic fix. - * To disable an automatic fixup / hook, set `enableMigrations=false`. +- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as + the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to + fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. -## Required configuration +## Required Configuration This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for RSPM. * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. @@ -65,16 +60,15 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +### License File -- We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. +We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic -``` +`kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic` Second, specify the following values: @@ -87,11 +81,17 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-pm.lic -``` +`--set-file license.file.contents=licenses/rstudio-pm.lic` -## S3 configuration +### License Key + +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## S3 Configuration Package Manager [can be configured to store its data in S3 buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), @@ -129,20 +129,20 @@ awsAccessKeyId: your-access-key-id awsSecretAccessKey: your-secret-access-key ``` -Consider that static, long-lived credentials are the least secure option and +Bear in mind that static, long-lived credentials are the least secure option and should be avoided if at all possible. -## General principles +## General Principles -In most places, we opt to pass Helm values over ConfigMaps. We translate these into the valid `.gcfg` file format -required by `rstudio-pm`. +- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +required by rstudio-pm. -## Configuration file +## Configuration File -The configuration values all take the form of usual Helm values +The configuration values all take the form of usual helm values so you can set the database password with something like: -```{.bash} +``` ... --set config.Postgres.Password=mypassword ... ``` @@ -157,7 +157,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | awsAccessKeyId | bool | `false` | awsAccessKeyId is the access key id for s3 access, used also to gate file creation | | awsSecretAccessKey | string | `nil` | awsSecretAccessKey is the secret access key, needs to be filled if access_key_id is | | command | bool | `false` | command is the pod's run command. By default, it uses the container's default | -| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the `rstudio-pm`.gcfg file | +| config | object | `{"HTTP":{"Listen":":4242"},"Metrics":{"Enabled":true}}` | config is a nested map of maps that generates the rstudio-pm.gcfg file | | enableMigration | bool | `true` | Enable migrations for shared storage (if necessary) using Helm hooks. | | enableSandboxing | bool | `true` | Enable sandboxing of Git builds, which requires elevated security privileges for the Package Manager container. | | extraContainers | list | `[]` | sidecar container list | @@ -188,7 +188,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | pod.annotations | object | `{}` | annotations is a map of keys / values that will be added as annotations to the pods | | pod.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"runAsNonRoot":true,"runAsUser":999,"seccompProfile":{"type":"{{ if .Values.enableSandboxing }}Unconfined{{ else }}RuntimeDefault{{ end }}"}}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the main Package Manager container. Evaluated as a template. | | pod.env | list | `[]` | env is an array of maps that is injected as-is into the "env:" component of the pod.container spec | -| pod.labels | object | `{}` | Additional labels to add to the `rstudio-pm` pods | +| pod.labels | object | `{}` | Additional labels to add to the rstudio-pm pods | | pod.lifecycle | object | `{}` | Container [lifecycle hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/) | | pod.securityContext | object | `{}` | the [securityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the pod | | pod.serviceAccountName | string | `""` | Deprecated, use `serviceAccount.name` instead | @@ -199,9 +199,9 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | priorityClassName | string | `""` | The pod's priorityClassName | | readinessProbe | object | `{"enabled":true,"failureThreshold":3,"httpGet":{"path":"/__ping__","port":4242},"initialDelaySeconds":3,"periodSeconds":3,"successThreshold":1,"timeoutSeconds":1}` | readinessProbe is used to configure the container's readinessProbe | | replicas | int | `1` | replicas is the number of replica pods to maintain for this service | -| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the `rstudio-pm` pod | -| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new Helm chart version. | -| rstudioPMKey | bool | `false` | rstudioPMKey is the `rstudio-pm` key used for the RStudio Package Manager service | +| resources | object | `{"limits":{"cpu":"2000m","enabled":false,"ephemeralStorage":"200Mi","memory":"4Gi"},"requests":{"cpu":"100m","enabled":false,"ephemeralStorage":"100Mi","memory":"2Gi"}}` | resources define requests and limits for the rstudio-pm pod | +| rootCheckIsFatal | bool | `true` | Whether the check for root accounts in the config file is fatal. This is meant to simplify migration to the new helm chart version. | +| rstudioPMKey | bool | `false` | rstudioPMKey is the rstudio-pm key used for the RStudio Package Manager service | | service.annotations | object | `{}` | Annotations for the service, for example to specify [an internal load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) | | service.clusterIP | string | `""` | The cluster-internal IP to use with `service.type` ClusterIP | | service.loadBalancerIP | string | `""` | The external IP to use with `service.type` LoadBalancer, when supported by the cloud provider | @@ -230,7 +230,8 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | strategy | object | `{"rollingUpdate":{"maxSurge":"100%","maxUnavailable":0},"type":"RollingUpdate"}` | The update strategy used by the main service pod. | | tolerations | list | `[]` | An array used verbatim as the pod's "tolerations" definition | | topologySpreadConstraints | list | `[]` | An array used verbatim as the pod's "topologySpreadConstraints" definition | -| versionOverride | string | `""` | A Package Manager version to override the "tag" for the Posit Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | +| versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index d533e169..9cda63d7 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,31 +1,25 @@ ---- -title: Posit Workbench -code-overflow: wrap ---- +# Posit Workbench ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for Posit Workbench_ +#### _Official Helm chart for RStudio Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For production +## For Production -To ensure a stable production deployment: +To ensure a stable production deployment, please: -* "Pin" the version of the Helm chart that you are using. You can do this using the: - * `helm dependency` command *and* the associated "Chart.lock" files *or* - * the `--version` flag. - - ::: {.callout-important} - This protects you from breaking changes. - ::: +* Ensure you "pin" the version of the Helm chart that you are using. You can do + this using the `helm dependency` command and the associated "Chart.lock" files + or the `--version` flag. **IMPORTANT: This protects you from breaking changes** +* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check + for breaking changes +* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking + changes, as well as documentation below on how to use the chart -* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. -* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. - -## Installing the chart +## Installing the Chart To install the chart with the release name `my-release` at version 0.7.3: @@ -35,63 +29,59 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, take a look at: - -```bash +``` helm search repo rstudio/rstudio-workbench -l ``` -## Required configuration +## Required Configuration -To function, this chart requires the following: +This chart requires the following in order to function: -* A license file. See the [Licensing](#licensing) section below for more details. +* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: - * Disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then - * Mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: - - ```yaml - config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap - ``` +```yaml +config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap +``` ## Licensing -This chart supports activating the product using a *license file*. +This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. + +### License File We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -```{.bash} -kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic -``` +`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` Second, specify the following values: @@ -104,32 +94,39 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -```{.bash} ---set-file license.file.contents=licenses/rstudio-workbench.lic -``` +`--set-file license.file.contents=licenses/rstudio-workbench.lic` -## General principles +### License Key + +Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. + +### License Server + +Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. + +## General Principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by Workbench. - - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. -- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. - - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). -- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. -- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. - - This is described in the - [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. + valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are + below. +- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below + and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) + on the topic in general. +- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: + - Get the service account information off of the RStudio Workbench pod for use in launching jobs +- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter + [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration files -These configuration values all take the form of usual Helm values -so you can set the database password with similar to: +These configuration values all take the form of usual helm values +so you can set the database password with something like: -```{.bash} +``` ... --set config.secret.database\.conf.password=mypassword ... ``` -The files are converted into configuration files, in the required format, via go-templating. If you want to "in-line" a configuration file or mount it verbatim, you can use a pattern like: +The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like: ```yaml config: @@ -139,135 +136,130 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change -the `XDG_CONFIG_DIRS` environment variable. +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change +the `XDG_CONFIG_DIRS` environment variable - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods. + are mounted into the session pods as well. - `repos.conf`, `rsession.conf`, `notifications.conf` - - Located in:
      `config.session.<< name of file >>` Helm values - - Mounted at:
      `/mnt/session-configmap/rstudio/` -- Session Secret Configuration: - - These configuration files are mounted into the server and session pods. - - `odbc.ini` and other similar shared secrets. - - Located in:
      `config.sessionSecret.<< name of file>>` Helm values - - Mounted at:
      `/mnt/session-secret/` -- Secret Configuration: - - These configuration files are mounted into the server with more restrictive permissions (0600). + - located in the `config.session.<< name of file >>` helm values + - mounted at `/mnt/session-configmap/rstudio/` +- Session Secret Configuration + - These configuration files are mounted into the server and session pods as well + - `odbc.ini` and other similar shared secrets + - located in `config.sessionSecret.<< name of file>>` helm values + - mounted at `/mnt/session-secret/` +- Secret Configuration + - These configuration files are mounted into the server with more restrictive permissions (0600) - `database.conf`, `openid-client-secret`, `databricks.conf` - - Located in:
      `config.secret.<< name of file >>` Helm values - - Mounted at:
      `/mnt/secret-configmap/rstudio/` -- Server Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located in the `config.secret.<< name of file >>` helm values + - mounted at `/mnt/secret-configmap/rstudio/` +- Server Configuration + - These configuration files are mounted into the server (.ini file format) - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - Located at:
      `config.server.<< name of file >>` Helm values - - Mounted at:
      `/mnt/configmap/rstudio/` -- Server DCF Configuration: - - These configuration files are mounted into the server (.dcf file format). + - They are located at `config.server.<< name of file >>` helm values + - mounted at `/mnt/configmap/rstudio/` +- Server DCF Configuration + - These configuration files are mounted into the server (.dcf file format) - `launcher-mounts`, `launcher-env` - - Located at:
      `config.serverDcf.<< name of file >>` Helm values - - Included at:
      `/mnt/configmap/rstudio/` -- Profiles Configuration: - - These configuration files are mounted into the server (.ini file format). + - They are located at `config.serverDcf.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` +- Profiles Configuration + - These configuration files are mounted into the server (.ini file format) - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` Helm values - - Included at:
      `/mnt/configmap/rstudio/` - - See the [Profiles](#rstudio-profiles) section below for more information. -- Prestart: - - This is provided by the Helm chart in a configmap. - - It is mounted into the pod at `/scripts/`. - - `prestart-workbench.bash` is used to start workbench. - - `prestart-launcher.bash` is used to start launcher. -- User Provisioning Configuration: - - These configuration files are used for configuring user provisioning (i.e., `sssd`). - - Located at:
      `config.userProvisioning.<< name of file >>` Helm values - - Mounted onto:
      `/etc/sssd/conf.d/` with `0600` permissions by default. -- Custom Startup Configuration: - - `supervisord` service / unit definition `.conf` files. - - Use the `.ini` file format by default. - - Mounted at:
      `/startup/custom` - - As with all configuration files above, you can override with a verbatim string if desired: - - Located at:
      `config.startupCustom.<< name of file >>` Helm values: - ```yaml - config: - startupCustom: - myfile.conf: | - file-used-verbatim - ``` -- PAM configuration: - - `pam` configuration files. - - Located at:
      `config.pam.<< name of file >>` Helm values - - Mounted verbatim as individual files (using `subPath` mounts) at:
      `/etc/pam.d/<< name of file >>` - -### Configuring Python and R repositories - -#### Python repositories - -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: - -- `launcher.useTemplates: true` is set -- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: - - ```yaml - launcher: - useTemplates: true + - They are located at `config.profiles.<< name of file >>` helm values + - included at `/mnt/configmap/rstudio/` + - See the `Profiles` section below for more information +- Prestart + - This is provided by the helm chart in a configmap + - It is mounted into the pod at `/scripts/` + - `prestart-workbench.bash` is used to start workbench + - `prestart-launcher.bash` is used to start launcher +- User Provisioning Configuration + - These configuration files are used for configuring user provisioning (i.e. `sssd`) + - Located at `config.userProvisioning.<< name of file >>` helm values + - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default +- Custom Startup Configuration + - `supervisord` service / unit definition `.conf` files + - Located at `config.startupCustom.<< name of file >>` helm values + - Will use the `.ini` file format, by default + - Mounted at `/startup/custom` + - As with all config files above, can override with a verbatim string if desired, like so: +```yaml +config: + startupCustom: + myfile.conf: | + file-used-verbatim +``` +- PAM configuration + - `pam` configuration files + - Located at `config.pam.<< name of file >>` helm values + - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` - config: - session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co - ``` +### Configuring R and Python repositories #### R repositories -R package repositories can be configured with `config.session.repos.conf`: +R package repositories can be configured with `config.session.repos.conf`. -```yaml +``` config: session: repos.conf: CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. +For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + +#### Python repositories + +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. + +``` +launcher: + useTemplates: true + +config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co +``` -## User provisioning +## User Provisioning -Provisioning users in Workbench containers is challenging. Session images create users automatically (with -consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the -administrator. +Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with +consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the +administrator today. The most common way to provision users is via `sssd`. -The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. +However, it is important to be careful of a few points: -However, it is important to use caution for the following: - -- UID / GID consistency: - - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. - - Failing can cause security issues and access by some users to access view they should not be allowed to see. -- Usernames cannot have `@`. - - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. -- `supervisord` is configured by default to exit if any of its child processes exit. - - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. +- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across + time. Failing this can cause security issues and access by some users to files they should not be allowed to see +- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because + some operating systems disallow `@` signs in linux usernames +- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` + to configure a user management service, be careful that it does not exit unnecessarily -We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a -future release. Please contact your account representative if you have feedback or questions about this +We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a +future release. Please get in touch with your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -287,17 +279,17 @@ Profiles are used to define product behavior (in `.ini` file format) based on us Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- If section header is `[*]`, it applies to all users. -- If a user's username is `myusername`, the section `[myusername]` applies to them. -- If a user is in the `allusers` group, then the section `[@allusers]` applies to them +- if section header is `[*]`, it applies to all users +- if a user's username is `myusername`, the section `[myusername]` will apply to them +- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. -In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: +In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: ```yaml config: @@ -320,17 +312,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` +- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` - ```yaml - some-key: - - value1 - - value2 - ``` +```yaml +some-key: + - value1 + - value2 +``` -- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -347,7 +339,6 @@ config: - value4 - value5 ``` - Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -359,24 +350,23 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -:::{.callout-note} -This appending/concatenation/array translation behavior only works with the helm chart. -::: +> NOTE: this appending/concatenation/array translation behavior only works with the helm chart -### Job Json overrides +### Job Json Overrides -If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: +If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following +configuration: + - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + - create an array of maps with the following keys: + - `target`: the "target" part of the job spec to replace + - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk + - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` -- Modify: - ```yaml - config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - ``` -- Create an array of maps with the following keys: - - `target`: The "target" part of the job spec to replace. - - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. - - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. +Note that several examples are provided +in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) +(however, examples do not use the helm chart syntax there). -Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. +Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) ```yaml config: @@ -396,11 +386,10 @@ config: - "two-image:tag ``` -## Sealed secrets +## Sealed Secrets +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. - -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. - `config.secret` - `config.sessionSecret` @@ -408,7 +397,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values @@ -557,3 +546,4 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + From a5f9e86df7c35f79be9abe23dbeefa4bcf5780ba Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 10:49:02 -0400 Subject: [PATCH 51/67] Description updates --- charts/rstudio-connect/Chart.yaml | 2 +- charts/rstudio-pm/Chart.yaml | 2 +- charts/rstudio-workbench/Chart.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/charts/rstudio-connect/Chart.yaml b/charts/rstudio-connect/Chart.yaml index 225d2322..5518cb08 100644 --- a/charts/rstudio-connect/Chart.yaml +++ b/charts/rstudio-connect/Chart.yaml @@ -1,5 +1,5 @@ name: rstudio-connect -description: Official Helm chart for RStudio Connect +description: Official Helm chart for Posit Connect version: 0.6.6 apiVersion: v2 appVersion: 2024.04.1 diff --git a/charts/rstudio-pm/Chart.yaml b/charts/rstudio-pm/Chart.yaml index 76a4357d..f9e32dfa 100644 --- a/charts/rstudio-pm/Chart.yaml +++ b/charts/rstudio-pm/Chart.yaml @@ -1,5 +1,5 @@ name: rstudio-pm -description: Official Helm chart for RStudio Package Manager +description: Official Helm chart for Posit Package Manager version: 0.5.25 apiVersion: v2 appVersion: 2024.04.0 diff --git a/charts/rstudio-workbench/Chart.yaml b/charts/rstudio-workbench/Chart.yaml index b44fb106..987b7ad6 100644 --- a/charts/rstudio-workbench/Chart.yaml +++ b/charts/rstudio-workbench/Chart.yaml @@ -1,5 +1,5 @@ name: rstudio-workbench -description: Official Helm chart for RStudio Workbench +description: Official Helm chart for Posit Workbench version: 0.7.3 apiVersion: v2 appVersion: 2024.04.0 From 1d74223238c5327d9379a8718e937464865c8da0 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 14:44:30 +0000 Subject: [PATCH 52/67] Update helm-docs and README.md --- charts/posit-chronicle/README.md | 49 ++-- charts/rstudio-connect/README.md | 53 ++-- charts/rstudio-launcher-rbac/README.md | 31 ++- charts/rstudio-library/README.md | 25 +- charts/rstudio-pm/README.md | 56 ++-- charts/rstudio-workbench/README.md | 367 +++++++++++++------------ 6 files changed, 301 insertions(+), 280 deletions(-) diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index 98feb64e..6b9f84d1 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -1,7 +1,4 @@ ---- -title: Posit Chronicle -code-overflow: wrap ---- +# Posit Chronicle ![Version: 0.3.0](https://img.shields.io/badge/Version-0.3.0-informational?style=flat-square) ![AppVersion: 2024.03.0](https://img.shields.io/badge/AppVersion-2024.03.0-informational?style=flat-square) @@ -15,10 +12,14 @@ Workbench. To ensure a stable production deployment: +## For production + +To ensure a stable production deployment: + * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. - + ::: {.callout-important} This protects you from breaking changes. ::: @@ -35,19 +36,19 @@ helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.0 ``` -To explore other chart versions, take a look at: - -```{.bash} +To explore other chart versions, look at: +``` helm search repo rstudio/posit-chronicle -l ``` ## Usage This chart deploys only the Chronicle server and is meant to be used in tandem -with the Workbench and Connect charts. To send data to the server, run the Chronicle agent as a sidecar container on your -Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files. +with the Workbench and Connect charts. To actually send data to the server, you +will need to run the Chronicle agent as a sidecar container on your +Workbench or Connect server pods by setting `pod.sidecar` in their respective `values.yaml` files -Here is an example of Helm values to run the agent sidecar in *Workbench*, +Here is an example of Helm values to run the agent sidecar in **Workbench**, where we set up a shared volume between containers for audit logs: ```yaml @@ -71,7 +72,7 @@ pod: value: "http://chronicle-server.default" ``` -Here is an example of Helm values for *Connect*, where a Connect +And here is an example of Helm values for Connect, where a **Connect** API key from a Kubernetes Secret is used to unlock more detailed metrics: ```yaml @@ -89,10 +90,10 @@ pod: key: apikey ``` -It is up to the user to provision this Kubernetes Secret for the +Note that it is up to the user to provision this Kubernetes Secret for the Connect API key. -## Storage configuration +## Storage Configuration Chronicle can be configured to persist data to a local Kubernetes Volume, AWS S3, or both. @@ -108,7 +109,8 @@ config: ``` `retentionPeriod` controls how long usage data are kept. For example, `"120m"` -for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention (units smaller than seconds or larger than days are not supported). +for 120 minutes, `"36h"` for 36 hours, `14d` for two weeks, or `"0"` for unbounded retention. +(Units smaller than seconds or larger than days are not supported.) You can also persist data to AWS S3 instead of (or in addition to) local storage: @@ -121,7 +123,7 @@ config: Region: "us-east-2" ``` -### Using IAM for S3 +### Using Iam for S3 If you are running on EKS, you can use [IAM Roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) @@ -136,9 +138,9 @@ serviceaccount: eks.amazonaws.com/role-arn: arn:aws:iam::123456789000:role/iam-role-name-here ``` -If you are unable to use IAM Roles for Service Accounts, there are many +If you are unable to use IAM Roles for Service Accounts, there are any number of alternatives for injecting AWS credentials into a container. As a fallback, -the S3 storage `config` allows specifying a profile: +the S3 storage config allows specifying a profile: ```yaml config: @@ -149,14 +151,14 @@ config: Region: "us-east-2" ``` -### Needed S3 policy permissions +### Needed S3 Policy Permissions The credentials Chronicle uses for S3 storage must have the following permissions enabled: -* `s3:GetObject` -* `s3:ListBucket` -* `s3:PutObject` -* `s3:DeleteObject` +- `s3:GetObject` +- `s3:ListBucket` +- `s3:PutObject` +- `s3:DeleteObject` ## Values @@ -205,3 +207,4 @@ The credentials Chronicle uses for S3 storage must have the following permission ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) + diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 8a04dbf9..a2ae0ee1 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -1,7 +1,4 @@ ---- -title: Posit Connect -code-overflow: wrap ---- +# Posit Connect ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) @@ -10,33 +7,37 @@ code-overflow: wrap Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. -## Best Practices +## Best practices Helm charts are very useful tools for deploying resources into Kubernetes, however, they do require some familiarity with kubernetes and `helm` itself. Please ensure you have adequate training and IT support before deploying these charts into production environments. Reach out to your account representative -if you need help deciding whether helm is a good choice for your deployment. +if you need help deciding whether Helm is a good choice for your deployment. To ensure reproducibility in your environment and insulate yourself from future changes, please: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use the `helm-diff` plugin and `helm diff upgrade` to check - for breaking changes -* Read [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +* "Pin" the version of the Helm chart that you are using. You can do + this using the: + * `helm dependency` command and the associated "Chart.lock" files _or_ + * the `--version` flag. -## Installing the Chart + :::{.callout-important} + This protects you from breaking changes** + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.6.6: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-connect -l ``` @@ -56,15 +57,15 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic` +```{.bash} +kubectl create secret generic rstudio-connect-license --from-file=licenses/rstudio-connect.lic +``` Second, specify the following values: @@ -77,15 +78,9 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-connect.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-connect.lic +``` ## General Principles diff --git a/charts/rstudio-launcher-rbac/README.md b/charts/rstudio-launcher-rbac/README.md index 313d989f..496581b3 100644 --- a/charts/rstudio-launcher-rbac/README.md +++ b/charts/rstudio-launcher-rbac/README.md @@ -4,28 +4,35 @@ #### _RBAC definition for the RStudio Job Launcher_ -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production -## Installing the Chart +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.2.20: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-launcher-rbac --version=0.2.20 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-launcher-rbac -l ``` diff --git a/charts/rstudio-library/README.md b/charts/rstudio-library/README.md index 86e0ab9d..56a781e8 100644 --- a/charts/rstudio-library/README.md +++ b/charts/rstudio-library/README.md @@ -4,17 +4,24 @@ #### _Helm library helpers for use by official RStudio charts_ -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production + +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. # Usage diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 9fcaca95..24b0d743 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -1,7 +1,4 @@ ---- -title: Posit Package Manager -code-overflow: wrap ---- +# Posit Package Manager ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) @@ -10,28 +7,35 @@ code-overflow: wrap IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production -## Installing the Chart +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.5.25: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-pm -l ``` @@ -60,15 +64,15 @@ This chart requires the following in order to function: ## Licensing -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. - -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic` +```{.bash} +kubectl create secret generic rstudio-pm-license --from-file=licenses/rstudio-pm.lic +``` Second, specify the following values: @@ -81,15 +85,9 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-pm.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server - -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +```{.bash} +--set-file license.file.contents=licenses/rstudio-pm.lic +``` ## S3 Configuration diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9cda63d7..0a5bb0a1 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -7,81 +7,91 @@ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. -## For Production +## For production -To ensure a stable production deployment, please: +To ensure a stable production deployment: -* Ensure you "pin" the version of the Helm chart that you are using. You can do - this using the `helm dependency` command and the associated "Chart.lock" files - or the `--version` flag. **IMPORTANT: This protects you from breaking changes** -* Before upgrading, to avoid breaking changes, use `helm diff upgrade` to check - for breaking changes -* Pay close attention to [`NEWS.md`](./NEWS.md) for updates on breaking - changes, as well as documentation below on how to use the chart +## For production -## Installing the Chart +To ensure a stable production deployment: + +* "Pin" the version of the Helm chart that you are using. You can do this using the: + * `helm dependency` command *and* the associated "Chart.lock" files *or* + * the `--version` flag. + + ::: {.callout-important} + This protects you from breaking changes. + ::: + +* Before upgrading check for breaking changes using `helm-diff` plugin and `helm diff upgrade`. +* Read [`NEWS.md`](./NEWS.md) for updates on breaking changes and the documentation below on how to use the chart. + +## Installing the chart To install the chart with the release name `my-release` at version 0.7.3: -```bash +```{.bash} helm repo add rstudio https://helm.rstudio.com helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` -To explore other chart versions, take a look at: +To explore other chart versions, look at: ``` helm search repo rstudio/rstudio-workbench -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the home directory for users. - * If `homeStorage.create` is set, a PVC that relies on the default storage class will be created to generate the + * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use - with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `homeStorage.create` and - create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying + with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you: + * Disable `homeStorage.create` and + create your own `PersistentVolume` and `PersistentVolumeClaim`, then + * Mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `homeStorage.name` and `homeStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your users' home directories, you'll need to mount your + * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes` and `pod.volumeMounts`. - * If you cannot use a `Volume` to mount the directories, you'll need to manually mount them during container startup + * If you cannot use a `Volume` to mount the directories, manually mount them during container startup with a mechanism similar to what is described below for joining to auth domains. - * If not using `homeStorage.create`, you'll need to configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. -* If using load balancing (by setting `replicas > 1`), you will need similar storage defined for `sharedStorage` to + * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions. +* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`. * A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default. You can include `sssd` configuration in `config.userProvisioning` like so: -```yaml -config: - userProvisioning: - mysssd.conf: - sssd: - config_file_version: 2 - services: nss, pam - domains: rstudio.com - domain/rstudio.com: - id_provider: ldap - auth_provider: ldap -``` -## Licensing + ```yaml + config: + userProvisioning: + mysssd.conf: + sssd: + config_file_version: 2 + services: nss, pam + domains: rstudio.com + domain/rstudio.com: + id_provider: ldap + auth_provider: ldap + ``` -This chart supports activating the product using a license file, license key, or license server. In the case of a license file or key, we recommend against placing it in your values file directly. +## Licensing -### License File +This chart supports activating the product using a *license file*. We recommend storing a license file as a `Secret` and setting the `license.file.secret` and `license.file.secretKey` values accordingly. First, create the secret declaratively with YAML or imperatively using the following command: -`kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic` +```{.bash} +kubectl create secret generic rstudio-workbench-license --from-file=licenses/rstudio-workbench.lic +``` Second, specify the following values: @@ -94,32 +104,27 @@ license: Alternatively, license files can be set during `helm install` with the following argument: -`--set-file license.file.contents=licenses/rstudio-workbench.lic` - -### License Key - -Set a license key directly in your values file (`license.key`) or during `helm install` with the argument `--set license.key=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`. - -### License Server +```{.bash} +--set-file license.file.contents=licenses/rstudio-workbench.lic +``` -Set a license server directly in your values file (`license.server`) or during `helm install` with the argument `--set license.server=`. +## General principles -## General Principles +## General principles - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the - valid `.ini` or `.dcf` file formats required by RStudio Workbench. Those config files and their mount locations are - below. -- If you need to modify the jobs launched by RStudio Workbench, you want to use `job-json-overrides`. There is a section on this below - and [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) - on the topic in general. -- The prestart scripts for RStudio Workbench and RStudio Launcher are highly customized to: - - Get the service account information off of the RStudio Workbench pod for use in launching jobs -- RStudio Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter - [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) + valid `.ini` or `.dcf` file formats required by Workbench. + - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. +- If you need to modify the jobs launched by Workbench, use `job-json-overrides`. + - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes). +- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs. +- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter. + - This is described in the + [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article. ## Configuration files -These configuration values all take the form of usual helm values +These configuration values all take the form of usual Helm values so you can set the database password with something like: ``` @@ -136,130 +141,133 @@ config: ``` The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values, -so moving them can have adverse effects. Also, if you use a different mounting paradigm, you will need to change -the `XDG_CONFIG_DIRS` environment variable +so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change +the `XDG_CONFIG_DIRS` environment variable. - Session Configuration - These configuration files are mounted into the server and - are mounted into the session pods as well. + are mounted into the session pods. - `repos.conf`, `rsession.conf`, `notifications.conf` - - located in the `config.session.<< name of file >>` helm values - - mounted at `/mnt/session-configmap/rstudio/` -- Session Secret Configuration - - These configuration files are mounted into the server and session pods as well - - `odbc.ini` and other similar shared secrets - - located in `config.sessionSecret.<< name of file>>` helm values - - mounted at `/mnt/session-secret/` -- Secret Configuration - - These configuration files are mounted into the server with more restrictive permissions (0600) + - Located in:
      `config.session.<< name of file >>` Helm values + - Mounted at:
      `/mnt/session-configmap/rstudio/` +- Session Secret Configuration: + - These configuration files are mounted into the server and session pods. + - `odbc.ini` and other similar shared secrets. + - Located in:
      `config.sessionSecret.<< name of file>>` Helm values + - Mounted at:
      `/mnt/session-secret/` +- Secret Configuration: + - These configuration files are mounted into the server with more restrictive permissions (0600). - `database.conf`, `openid-client-secret`, `databricks.conf` - - They are located in the `config.secret.<< name of file >>` helm values - - mounted at `/mnt/secret-configmap/rstudio/` -- Server Configuration - - These configuration files are mounted into the server (.ini file format) + - Located in:
      `config.secret.<< name of file >>` Helm values + - Mounted at:
      `/mnt/secret-configmap/rstudio/` +- Server Configuration: + - These configuration files are mounted into the server (.ini file format). - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf` - - They are located at `config.server.<< name of file >>` helm values - - mounted at `/mnt/configmap/rstudio/` -- Server DCF Configuration - - These configuration files are mounted into the server (.dcf file format) + - Located at:
      `config.server.<< name of file >>` Helm values + - Mounted at:
      `/mnt/configmap/rstudio/` +- Server DCF Configuration: + - These configuration files are mounted into the server (.dcf file format). - `launcher-mounts`, `launcher-env` - - They are located at `config.serverDcf.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` -- Profiles Configuration - - These configuration files are mounted into the server (.ini file format) + - Located at:
      `config.serverDcf.<< name of file >>` Helm values + - Included at:
      `/mnt/configmap/rstudio/` +- Profiles Configuration: + - These configuration files are mounted into the server (.ini file format). - `launcher.kubernetes.profiles.conf` - - They are located at `config.profiles.<< name of file >>` helm values - - included at `/mnt/configmap/rstudio/` - - See the `Profiles` section below for more information -- Prestart - - This is provided by the helm chart in a configmap - - It is mounted into the pod at `/scripts/` - - `prestart-workbench.bash` is used to start workbench - - `prestart-launcher.bash` is used to start launcher -- User Provisioning Configuration - - These configuration files are used for configuring user provisioning (i.e. `sssd`) - - Located at `config.userProvisioning.<< name of file >>` helm values - - Mounted onto `/etc/sssd/conf.d/` with `0600` permissions by default -- Custom Startup Configuration - - `supervisord` service / unit definition `.conf` files - - Located at `config.startupCustom.<< name of file >>` helm values - - Will use the `.ini` file format, by default - - Mounted at `/startup/custom` - - As with all config files above, can override with a verbatim string if desired, like so: -```yaml -config: - startupCustom: - myfile.conf: | - file-used-verbatim -``` -- PAM configuration - - `pam` configuration files - - Located at `config.pam.<< name of file >>` helm values - - Will be mounted verbatim as individual files (using `subPath` mounts) at `/etc/pam.d/<< name of file >>` + - They are located at `config.profiles.<< name of file >>` Helm values + - Included at:
      `/mnt/configmap/rstudio/` + - See the [Profiles](#rstudio-profiles) section below for more information. +- Prestart: + - This is provided by the Helm chart in a configmap. + - It is mounted into the pod at `/scripts/`. + - `prestart-workbench.bash` is used to start workbench. + - `prestart-launcher.bash` is used to start launcher. +- User Provisioning Configuration: + - These configuration files are used for configuring user provisioning (i.e., `sssd`). + - Located at:
      `config.userProvisioning.<< name of file >>` Helm values + - Mounted onto:
      `/etc/sssd/conf.d/` with `0600` permissions by default. +- Custom Startup Configuration: + - `supervisord` service / unit definition `.conf` files. + - Use the `.ini` file format by default. + - Mounted at:
      `/startup/custom` + - As with all configuration files above, you can override with a verbatim string if desired: + - Located at:
      `config.startupCustom.<< name of file >>` Helm values: + ```yaml + config: + startupCustom: + myfile.conf: | + file-used-verbatim + ``` +- PAM configuration: + - `pam` configuration files. + - Located at:
      `config.pam.<< name of file >>` Helm values + - Mounted verbatim as individual files (using `subPath` mounts) at:
      `/etc/pam.d/<< name of file >>` -### Configuring R and Python repositories +#### Python repositories -#### R repositories +pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods, it is important that: -R package repositories can be configured with `config.session.repos.conf`. +- `launcher.useTemplates: true` is set +- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI: -``` -config: - session: - repos.conf: - CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest -``` + ```yaml + launcher: + useTemplates: true -For more information about configuring CRAN repositories in Workbench refer to the [Admin Guide](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories). + config: + session: + pip.conf: + "global": + index-url: https://packagemanager.posit.co/pypi/latest/simple + trusted-host: packagemanager.posit.co + ``` -#### Python repositories - -pip can be configured with `config.session.pip.conf`. To ensure `pip.conf` is mounted into the session pods it is important that `launcher.useTemplates: true` is set and `pip.conf` settings are listed under `config.session` like in the example below for adding Posit Public Package Manager's PyPI. +#### R repositories -``` -launcher: - useTemplates: true +R package repositories can be configured with `config.session.repos.conf`: +```yaml config: session: - pip.conf: - "global": - index-url: https://packagemanager.posit.co/pypi/latest/simple - trusted-host: packagemanager.posit.co + repos.conf: + CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest ``` -## User Provisioning +For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section. -Provisioning users in RStudio Workbench containers is challenging. Session images have users created automatically (with -consistent UIDs / GIDs), but creating users in the Workbench containers is a responsibility that falls to the -administrator today. +## User provisioning + +Provisioning users in Workbench containers is challenging. Session images create users automatically (with +consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the +administrator. The most common way to provision users is via `sssd`. -The [latest RStudio Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) +The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning) has `sssd` included and running by default (see `userProvisioning` configuration files above). -The other way that this can be managed is via a lightweight "startup service" (runs once at startup and then sleeps forever) +The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever) or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language. -However, it is important to be careful of a few points: -- UID / GID consistency: linux usernames and their matching to UID/GID must be consistent across all nodes and across - time. Failing this can cause security issues and access by some users to files they should not be allowed to see -- usernames cannot have `@`. The `@` sign (often used in emails with SSO) is a problem for RStudio Workbench because - some operating systems disallow `@` signs in linux usernames -- `supervisord` is configured by default to exit if any of its child processes exit. If you use `config.startupCustom` - to configure a user management service, be careful that it does not exit unnecessarily +However, it is important to use caution for the following: + +- UID / GID consistency: + - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time. + - Failing can cause security issues and access by some users to access view they should not be allowed to see. +- Usernames cannot have `@`. + - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames. +- `supervisord` is configured by default to exit if any of its child processes exit. + - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily. -We do not provide such a service out of the box because we intend for RStudio Workbench to solve this problem in a -future release. Please get in touch with your account representative if you have feedback or questions about this +We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a +future release. Please contact your account representative if you have feedback or questions about this workflow. ### PAM -When starting sessions on RStudio Workbench, PAM configuration is often very important, even if PAM is not being used as -an authentication mechanism. The RStudio Workbench helm chart allows creating custom PAM files via the `config.pam` +When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as +an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam` values section. -Each key under `config.pam` will become a PAM config file, and will be mounted into `/etc/pam.d/` in the container. For +Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For example: ```yaml @@ -273,23 +281,23 @@ config: # will be used verbatim ``` -## RStudio Profiles +## RStudio profiles Profiles are used to define product behavior (in `.ini` file format) based on user and group membership. Sections define whether a set of configurations is applied to a user's jobs based on the following criteria: -- if section header is `[*]`, it applies to all users -- if a user's username is `myusername`, the section `[myusername]` will apply to them -- if a user is in the `allusers` group, then the section `[@allusers]` will apply to them +- If section header is `[*]`, it applies to all users. +- If a user's username is `myusername`, the section `[myusername]` applies to them. +- If a user is in the `allusers` group, then the section `[@allusers]` applies to them The product reads configuration from top to bottom and "last-in-wins" for a given configuration value. ### `/etc/rstudio/profiles` -The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the Workbench Admin Guide [User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more details. +The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information. -In the `values.yaml`, the content of `/etc/rstudio/profiles` should be defined in `config.server.profiles`. For example: +In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example: ```yaml config: @@ -312,17 +320,17 @@ session-timeout-minutes=60 ### `/etc/rstudio/launcher.kubernetes.profiles.conf` -The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` should be defined in `config.profiles.launcher.kubernetes.profiles.conf`. The `config.profiles` section has a couple of niceties that are added in by default. +The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf ` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default. -- YAML arrays like the following will be "comma-joined." For instance, the following will become: `some-key=value1,value2` +- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2` -```yaml -some-key: - - value1 - - value2 -``` + ```yaml + some-key: + - value1 + - value2 + ``` -- The `[*]` section will have arrays "appended" to user and group sections, along with "defaults" defined by the chart. +- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart. For example: @@ -339,6 +347,7 @@ config: - value4 - value5 ``` + Becomes: _/etc/rstudio/launcher.kubernetes.profiles.conf_ @@ -350,23 +359,24 @@ some-key: value1,value2 some-key: value1,value2,value3,value4 ``` -> NOTE: this appending/concatenation/array translation behavior only works with the helm chart +:::{.callout-note} +This appending/concatenation/array translation behavior only works with the helm chart. +::: -### Job Json Overrides +### Job Json overrides -If you want to customize the job launch process (i.e. how sessions are defined), you will need to edit the following -configuration: - - modify `config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` - - create an array of maps with the following keys: - - `target`: the "target" part of the job spec to replace - - `name`: a unique identifier (ideally with no spaces) that will become a config filename on disk - - `json`: a YAML value that will be translated directly to JSON and injected into the job spec at `target` +If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration: -Note that several examples are provided -in [this support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes) -(however, examples do not use the helm chart syntax there). +- Modify: + ```yaml + config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides` + ``` +- Create an array of maps with the following keys: + - `target`: The "target" part of the job spec to replace. + - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk. + - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`. -Alternatively, you can explore the docs in the [helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) +Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information. ```yaml config: @@ -386,10 +396,11 @@ config: - "two-image:tag ``` -## Sealed Secrets -This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. +## Sealed secrets + +This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`. -To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted. The chart does not support mixing encrypted values with unencrypted values. +To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values): - `config.secret` - `config.sessionSecret` @@ -397,7 +408,7 @@ To activate the use of `SealedSecret` templates instead of `Secret` templates in - `launcherPem` - `secureCookieKey` (or `global.secureCookieKey`) -Use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key which can be generated via an RSA tool such as helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID which can be generated via a UUID generator such as helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. +Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function. ## Values From 938307430b3b593a326634aa37e8760201dc70d3 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 14:49:38 +0000 Subject: [PATCH 53/67] Update helm-docs and README.md --- charts/rstudio-connect/README.md | 2 +- charts/rstudio-pm/README.md | 2 +- charts/rstudio-workbench/README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index a2ae0ee1..95b7cb19 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -2,7 +2,7 @@ ![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) -#### _Official Helm chart for RStudio Connect_ +#### _Official Helm chart for Posit Connect_ Business Users and Collaborators use R and Python data products on [Posit Connect](https://posit.co/products/enterprise/connect/) that are published by Data Scientists. diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 24b0d743..f2f7f113 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -2,7 +2,7 @@ ![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Package Manager_ +#### _Official Helm chart for Posit Package Manager_ IT Administrators use [Posit Package Manager](https://posit.co/products/enterprise/package-manager/) to control and manage R and Python packages that Data Scientists need to create and share data products. diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 0a5bb0a1..9a05e06d 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -2,7 +2,7 @@ ![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) -#### _Official Helm chart for RStudio Workbench_ +#### _Official Helm chart for Posit Workbench_ Data Scientists use [Posit Workbench](https://posit.co/products/enterprise/workbench/) to analyze data and create data products using R and Python. From fed23f8f00cb2f635094d88fc48a20c58a689775 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 11:35:52 -0400 Subject: [PATCH 54/67] =?UTF-8?q?idk=20what=20is=20right=20side=20up=20or?= =?UTF-8?q?=20upside=20down=20at=20this=20point....=20"=C2=AF\=5F(?= =?UTF-8?q?=E3=83=84)=5F/=C2=AF"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- charts/_templates.gotmpl | 4 ---- charts/rstudio-connect/README.md.gotmpl | 12 ++++++------ charts/rstudio-pm/README.md.gotmpl | 12 ++++++------ charts/rstudio-workbench/README.md.gotmpl | 2 -- 4 files changed, 12 insertions(+), 18 deletions(-) diff --git a/charts/_templates.gotmpl b/charts/_templates.gotmpl index dce4b93c..43e05938 100644 --- a/charts/_templates.gotmpl +++ b/charts/_templates.gotmpl @@ -44,10 +44,6 @@ Workbench. To ensure a stable production deployment: -## For production - -To ensure a stable production deployment: - * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. diff --git a/charts/rstudio-connect/README.md.gotmpl b/charts/rstudio-connect/README.md.gotmpl index 3906063a..edc81aa1 100644 --- a/charts/rstudio-connect/README.md.gotmpl +++ b/charts/rstudio-connect/README.md.gotmpl @@ -8,11 +8,11 @@ {{ template "rstudio.install" . }} -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. @@ -23,19 +23,19 @@ This chart requires the following in order to function: {{ template "rstudio.licensing" . }} -## General Principles +## General principles - In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format required by {{ template "chart.name" . }}. - {{ template "chart.name" . }} does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration File +## Configuration file The configuration values all take the form of usual helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-pm/README.md.gotmpl b/charts/rstudio-pm/README.md.gotmpl index d0d4cc81..62b20536 100644 --- a/charts/rstudio-pm/README.md.gotmpl +++ b/charts/rstudio-pm/README.md.gotmpl @@ -8,7 +8,7 @@ {{ template "rstudio.install" . }} -## Upgrade Guidance +## Upgrade guidance ### 0.4.0 @@ -16,7 +16,7 @@ the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. -## Required Configuration +## Required configuration This chart requires the following in order to function: @@ -32,7 +32,7 @@ This chart requires the following in order to function: {{ template "rstudio.licensing" . }} -## S3 Configuration +## S3 configuration Package Manager [can be configured to store its data in S3 buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), @@ -73,17 +73,17 @@ awsSecretAccessKey: your-secret-access-key Bear in mind that static, long-lived credentials are the least secure option and should be avoided if at all possible. -## General Principles +## General principles - In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format required by {{ template "chart.name" . }}. -## Configuration File +## Configuration file The configuration values all take the form of usual helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md.gotmpl b/charts/rstudio-workbench/README.md.gotmpl index de45d2d0..b2b9f10e 100644 --- a/charts/rstudio-workbench/README.md.gotmpl +++ b/charts/rstudio-workbench/README.md.gotmpl @@ -52,8 +52,6 @@ To function, this chart requires the following: ## General principles -## General principles - - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the valid `.ini` or `.dcf` file formats required by Workbench. - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. From acf5f1a894040ff7000a11d6a8d32f49d15246ff Mon Sep 17 00:00:00 2001 From: edavidaja Date: Tue, 14 May 2024 12:10:50 -0400 Subject: [PATCH 55/67] just docs --- _quarto.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/_quarto.yml b/_quarto.yml index 2abeacf5..8b3f08ba 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -1,8 +1,6 @@ project: type: posit-docs - pre-render: | - ./bin/helm-docs --chart-search-root=charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl - ./bin/helm-docs --chart-search-root=other-charts --template-files=README.md.gotmpl --template-files=./_templates.gotmpl + pre-render: just docs render: - charts/rstudio-workbench/README.md - charts/rstudio-workbench/NEWS.md From 2b74203d24d67d993bbd49a9f53eb640c7b2e4de Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 16:12:07 +0000 Subject: [PATCH 56/67] Update helm-docs and README.md --- charts/posit-chronicle/README.md | 6 +----- charts/rstudio-connect/README.md | 16 ++++++++-------- charts/rstudio-launcher-rbac/README.md | 6 +----- charts/rstudio-library/README.md | 6 +----- charts/rstudio-pm/README.md | 22 +++++++++------------- charts/rstudio-workbench/README.md | 10 ++-------- other-charts/prepull-daemonset/README.md | 2 +- 7 files changed, 23 insertions(+), 45 deletions(-) diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index 6b9f84d1..fa59101d 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -12,10 +12,6 @@ Workbench. To ensure a stable production deployment: -## For production - -To ensure a stable production deployment: - * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. @@ -206,5 +202,5 @@ The credentials Chronicle uses for S3 storage must have the following permission | storage.persistentVolumeSize | string | `"1Gi"` | | ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 95b7cb19..51625b56 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -42,11 +42,11 @@ To explore other chart versions, look at: helm search repo rstudio/rstudio-connect -l ``` -## Required Configuration +## Required configuration -This chart requires the following in order to function: +To function, this chart requires the following: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. +* A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. @@ -82,19 +82,19 @@ Alternatively, license files can be set during `helm install` with the following --set-file license.file.contents=licenses/rstudio-connect.lic ``` -## General Principles +## General principles - In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-connect. - rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) -## Configuration File +## Configuration file The configuration values all take the form of usual helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` @@ -143,7 +143,7 @@ The Helm `config` values are converted into the `rstudio-connect.gcfg` service c | license.file | object | `{"contents":false,"mountPath":"/etc/rstudio-licensing","mountSubPath":false,"secret":false,"secretKey":"license.lic"}` | the file section is used for licensing with a license file | | license.file.contents | bool | `false` | contents is an in-line license file | | license.file.mountPath | string | `"/etc/rstudio-licensing"` | mountPath is the place the license file will be mounted into the container | -| license.file.mountSubPath | bool | `false` | mountSubPath is whether to mount the subPath for the file secret. -- It can be preferable _not_ to enable this, because then updates propagate automatically | +| license.file.mountSubPath | bool | `false` | It can be preferable _not_ to enable this, because then updates propagate automatically | | license.file.secret | bool | `false` | secret is an existing secret with a license file in it | | license.file.secretKey | string | `"license.lic"` | secretKey is the key for the secret to use for the license file | | license.key | string | `nil` | key is the license to use | @@ -208,5 +208,5 @@ The Helm `config` values are converted into the `rstudio-connect.gcfg` service c | versionOverride | string | `""` | A Connect version to override the "tag" for the Posit Connect image and the Content Init image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) diff --git a/charts/rstudio-launcher-rbac/README.md b/charts/rstudio-launcher-rbac/README.md index 496581b3..80e453a2 100644 --- a/charts/rstudio-launcher-rbac/README.md +++ b/charts/rstudio-launcher-rbac/README.md @@ -8,10 +8,6 @@ To ensure a stable production deployment: -## For production - -To ensure a stable production deployment: - * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. @@ -65,5 +61,5 @@ helm template -n rstudio rstudio-launcher-rbac rstudio/rstudio-launcher-rbac | targetNamespaces | list | `[]` | The targetNamespaces that the launcher will be able to launch sessions into | ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) diff --git a/charts/rstudio-library/README.md b/charts/rstudio-library/README.md index 56a781e8..69f11cb9 100644 --- a/charts/rstudio-library/README.md +++ b/charts/rstudio-library/README.md @@ -8,10 +8,6 @@ To ensure a stable production deployment: -## For production - -To ensure a stable production deployment: - * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. @@ -38,5 +34,5 @@ If you are curious about its usage, take a look at the other charts (i.e. `rstud for `rstudio-library` in the `templates/` directory. ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index f2f7f113..6f9a3880 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -11,10 +11,6 @@ R and Python packages that Data Scientists need to create and share data product To ensure a stable production deployment: -## For production - -To ensure a stable production deployment: - * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. @@ -40,7 +36,7 @@ To explore other chart versions, look at: helm search repo rstudio/rstudio-pm -l ``` -## Upgrade Guidance +## Upgrade guidance ### 0.4.0 @@ -48,7 +44,7 @@ helm search repo rstudio/rstudio-pm -l the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. -## Required Configuration +## Required configuration This chart requires the following in order to function: @@ -89,7 +85,7 @@ Alternatively, license files can be set during `helm install` with the following --set-file license.file.contents=licenses/rstudio-pm.lic ``` -## S3 Configuration +## S3 configuration Package Manager [can be configured to store its data in S3 buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), @@ -130,17 +126,17 @@ awsSecretAccessKey: your-secret-access-key Bear in mind that static, long-lived credentials are the least secure option and should be avoided if at all possible. -## General Principles +## General principles - In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. -## Configuration File +## Configuration file The configuration values all take the form of usual helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.Postgres.Password=mypassword ... ``` @@ -175,7 +171,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | license.file | object | `{"contents":false,"mountPath":"/etc/rstudio-licensing","mountSubPath":false,"secret":false,"secretKey":"license.lic"}` | the file section is used for licensing with a license file | | license.file.contents | bool | `false` | contents is an in-line license file | | license.file.mountPath | string | `"/etc/rstudio-licensing"` | mountPath is the place the license file will be mounted into the container | -| license.file.mountSubPath | bool | `false` | mountSubPath is whether to mount the subPath for the file secret. -- It can be preferable _not_ to enable this, because then updates propagate automatically | +| license.file.mountSubPath | bool | `false` | It can be preferable _not_ to enable this, because then updates propagate automatically | | license.file.secret | bool | `false` | secret is an existing secret with a license file in it | | license.file.secretKey | string | `"license.lic"` | secretKey is the key for the secret to use for the license file | | license.key | string | `nil` | key is the license to use | @@ -208,7 +204,7 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | service.type | string | `"ClusterIP"` | The service type, usually ClusterIP (in-cluster only) or LoadBalancer (to expose the service using your cloud provider's load balancer) | | serviceAccount.annotations | object | `{}` | Annotations for the ServiceAccount, if any | | serviceAccount.create | bool | `true` | Whether to create a [Service Account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) | -| serviceAccount.labels | object | `{}` | | +| serviceAccount.labels | object | `{}` | Labels for the ServiceAccount, if any | | serviceAccount.name | string | When `serviceAccount.create` is `true` this defaults to the full name of the release | ServiceAccount to use, if any, or an explicit name for the one we create | | serviceMonitor.additionalLabels | object | `{}` | additionalLabels normally includes the release name of the Prometheus Operator | | serviceMonitor.enabled | bool | `false` | Whether to create a ServiceMonitor CRD for use with a Prometheus Operator | @@ -231,5 +227,5 @@ The Helm `config` values are converted into the `rstudio-pm.gcfg` service config | versionOverride | string | `""` | A Package Manager version to override the "tag" for the RStudio Package Manager image. Necessary until https://github.com/helm/helm/issues/8194 | ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 9a05e06d..070c33e2 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -11,10 +11,6 @@ products using R and Python. To ensure a stable production deployment: -## For production - -To ensure a stable production deployment: - * "Pin" the version of the Helm chart that you are using. You can do this using the: * `helm dependency` command *and* the associated "Chart.lock" files *or* * the `--version` flag. @@ -110,8 +106,6 @@ Alternatively, license files can be set during `helm install` with the following ## General principles -## General principles - - In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the valid `.ini` or `.dcf` file formats required by Workbench. - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below. @@ -477,7 +471,7 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables | license.file | object | `{"contents":false,"mountPath":"/etc/rstudio-licensing","mountSubPath":false,"secret":false,"secretKey":"license.lic"}` | the file section is used for licensing with a license file | | license.file.contents | bool | `false` | contents is an in-line license file | | license.file.mountPath | string | `"/etc/rstudio-licensing"` | mountPath is the place the license file will be mounted into the container | -| license.file.mountSubPath | bool | `false` | mountSubPath is whether to mount the subPath for the file secret. -- It can be preferable _not_ to enable this, because then updates propagate automatically | +| license.file.mountSubPath | bool | `false` | It can be preferable _not_ to enable this, because then updates propagate automatically | | license.file.secret | bool | `false` | secret is an existing secret with a license file in it | | license.file.secretKey | string | `"license.lic"` | secretKey is the key for the secret to use for the license file | | license.key | string | `nil` | key is the license to use | @@ -556,5 +550,5 @@ Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables | xdgConfigDirsExtra | list | `[]` | A list of additional XDG config dir paths | ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) diff --git a/other-charts/prepull-daemonset/README.md b/other-charts/prepull-daemonset/README.md index 5f5492b0..8358fc42 100644 --- a/other-charts/prepull-daemonset/README.md +++ b/other-charts/prepull-daemonset/README.md @@ -54,5 +54,5 @@ kubectl rollout restart daemonset/prepull-daemonset | updateStrategy | object | `{}` | | ---------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) +Autogenerated from chart metadata using [helm-docs v1.13.1](https://github.com/norwoodj/helm-docs/releases/v1.13.1) From 04840edc321b65fbdcb890c4728d4f9cfae832f9 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 13:13:27 -0400 Subject: [PATCH 57/67] I give up :) --- charts/_templates.gotmpl | 3 ++- charts/posit-chronicle/README.md | 3 ++- charts/rstudio-connect/README.md | 12 +++++++----- charts/rstudio-connect/README.md.gotmpl | 9 +++++---- charts/rstudio-launcher-rbac/README.md | 3 ++- charts/rstudio-pm/README.md | 20 +++++++++++--------- charts/rstudio-pm/README.md.gotmpl | 17 +++++++++-------- charts/rstudio-workbench/README.md | 5 +++-- charts/rstudio-workbench/README.md.gotmpl | 2 +- 9 files changed, 42 insertions(+), 32 deletions(-) diff --git a/charts/_templates.gotmpl b/charts/_templates.gotmpl index 43e05938..476b8082 100644 --- a/charts/_templates.gotmpl +++ b/charts/_templates.gotmpl @@ -102,7 +102,8 @@ helm upgrade --install --devel my-release rstudio/{{ template "chart.name" . }} ``` To explore other chart versions, look at: -``` + +```{.bash} helm search repo {{ if $isDev }}--devel {{ end }}rstudio/{{ template "chart.name" . }} -l ``` diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index fa59101d..35dac8c4 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -33,7 +33,8 @@ helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.0 ``` To explore other chart versions, look at: -``` + +```{.bash} helm search repo rstudio/posit-chronicle -l ``` diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 51625b56..60433c5f 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -38,7 +38,8 @@ helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 ``` To explore other chart versions, look at: -``` + +```{.bash} helm search repo rstudio/rstudio-connect -l ``` @@ -48,11 +49,12 @@ To function, this chart requires the following: * A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + * If you cannot use a `PersistentVolume` to properly mount your data directory, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. ## Licensing @@ -84,14 +86,14 @@ Alternatively, license files can be set during `helm install` with the following ## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-connect. - rstudio-connect does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ```{.bash} diff --git a/charts/rstudio-connect/README.md.gotmpl b/charts/rstudio-connect/README.md.gotmpl index edc81aa1..f39b4671 100644 --- a/charts/rstudio-connect/README.md.gotmpl +++ b/charts/rstudio-connect/README.md.gotmpl @@ -14,25 +14,26 @@ To function, this chart requires the following: * A license file. See the [Licensing](#licensing) section below for more details. * A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Connect. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. + * If `sharedStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + * If you cannot use a `PersistentVolume` to properly mount your data directory, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. {{ template "rstudio.licensing" . }} ## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by {{ template "chart.name" . }}. - {{ template "chart.name" . }} does not export many prometheus metrics on its own. Instead, we run a sidecar graphite exporter [as described here](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) ## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ```{.bash} diff --git a/charts/rstudio-launcher-rbac/README.md b/charts/rstudio-launcher-rbac/README.md index 80e453a2..4a3d1b1c 100644 --- a/charts/rstudio-launcher-rbac/README.md +++ b/charts/rstudio-launcher-rbac/README.md @@ -29,7 +29,8 @@ helm upgrade --install my-release rstudio/rstudio-launcher-rbac --version=0.2.20 ``` To explore other chart versions, look at: -``` + +```{.bash} helm search repo rstudio/rstudio-launcher-rbac -l ``` diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 6f9a3880..9a5f0481 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -32,7 +32,8 @@ helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 ``` To explore other chart versions, look at: -``` + +```{.bash} helm search repo rstudio/rstudio-pm -l ``` @@ -41,20 +42,21 @@ helm search repo rstudio/rstudio-pm -l ### 0.4.0 - When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to - fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. + the `rstudio-pm` user (with `uid:gid` `999:999`). +- A `chown` of persistent storage may be required. The team is working to implement an automatic fix. To disable the automatic fix/hook, set `enableMigrations=false`. ## Required configuration This chart requires the following in order to function: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. -* A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for RSPM. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. +* A license file. See the [Licensing](#licensing) section below for more details. +* A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Package Manager. + * If `sharedStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + * If you cannot use a `PersistentVolume` to properly mount your data directory, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. * Alternatively, S3 storage can be used. See the [S3 Configuration](#s3-configuration) section for details. @@ -128,12 +130,12 @@ should be avoided if at all possible. ## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by rstudio-pm. ## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ```{.bash} diff --git a/charts/rstudio-pm/README.md.gotmpl b/charts/rstudio-pm/README.md.gotmpl index 62b20536..e8d5ffd0 100644 --- a/charts/rstudio-pm/README.md.gotmpl +++ b/charts/rstudio-pm/README.md.gotmpl @@ -13,20 +13,21 @@ ### 0.4.0 - When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as - the `rstudio-pm` user (with `uid:gid` `999:999`). A `chown` of persistent storage may be required. We will try to - fix this up automatically. Set `enableMigrations=false` to disable the automatic fixup / hook. + the `rstudio-pm` user (with `uid:gid` `999:999`). +- A `chown` of persistent storage may be required. The team is working to implement an automatic fix. To disable the automatic fix/hook, set `enableMigrations=false`. ## Required configuration This chart requires the following in order to function: -* A license file, license key, or address of a running license server. See the [Licensing](#licensing) section below for more details. -* A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for RSPM. - * If `sharedStorage.create` is set, a PVC that relies on the default storage class will be created to generate the PersistentVolume. +* A license file. See the [Licensing](#licensing) section below for more details. +* A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the data directory for Package Manager. + * If `sharedStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the + PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend you disable `sharedStorage.create` and create your own `PersistentVolume` and `PersistentVolumeClaim`, then mount them into the container by specifying the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim` using `sharedStorage.name` and `sharedStorage.mount`. - * If you cannot use a `PersistentVolume` to properly mount your data directory, you'll need to mount your data in the container + * If you cannot use a `PersistentVolume` to properly mount your data directory, mount your data in the container by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`. * Alternatively, S3 storage can be used. See the [S3 Configuration](#s3-configuration) section for details. @@ -75,12 +76,12 @@ should be avoided if at all possible. ## General principles -- In most places, we opt to pass helm values over configmaps. We translate these into the valid `.gcfg` file format +- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format required by {{ template "chart.name" . }}. ## Configuration file -The configuration values all take the form of usual helm values +The configuration values all take the form of usual Helm values so you can set the database password with something like: ```{.bash} diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 070c33e2..88d90d5a 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -32,7 +32,8 @@ helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 ``` To explore other chart versions, look at: -``` + +```{.bash} helm search repo rstudio/rstudio-workbench -l ``` @@ -121,7 +122,7 @@ Alternatively, license files can be set during `helm install` with the following These configuration values all take the form of usual Helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.secret.database\.conf.password=mypassword ... ``` diff --git a/charts/rstudio-workbench/README.md.gotmpl b/charts/rstudio-workbench/README.md.gotmpl index b2b9f10e..cb32dc99 100644 --- a/charts/rstudio-workbench/README.md.gotmpl +++ b/charts/rstudio-workbench/README.md.gotmpl @@ -67,7 +67,7 @@ To function, this chart requires the following: These configuration values all take the form of usual Helm values so you can set the database password with something like: -``` +```{.bash} ... --set config.secret.database\.conf.password=mypassword ... ``` From 9b1a77aefedf36a851cf4afaf76378fc4f079760 Mon Sep 17 00:00:00 2001 From: Ashley Henry Date: Tue, 14 May 2024 13:25:27 -0400 Subject: [PATCH 58/67] Update README.md.gotmpl --- charts/rstudio-pm/README.md.gotmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-pm/README.md.gotmpl b/charts/rstudio-pm/README.md.gotmpl index e8d5ffd0..99c3aa41 100644 --- a/charts/rstudio-pm/README.md.gotmpl +++ b/charts/rstudio-pm/README.md.gotmpl @@ -36,7 +36,7 @@ This chart requires the following in order to function: ## S3 configuration Package Manager [can be configured to store its data in S3 -buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), +buckets](https://docs.posit.co/rspm/admin/file-storage/file-storage/#data-destinations), which eliminates the need to provision shared storage for multiple replicas. A `values.yaml` file using S3 might contain something like the following: From 34e1a930b021fead5ddbfae8b1035e4f13c954ba Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 17:26:30 +0000 Subject: [PATCH 59/67] Update helm-docs and README.md --- charts/rstudio-pm/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index 9a5f0481..f5b5c0d2 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -90,7 +90,7 @@ Alternatively, license files can be set during `helm install` with the following ## S3 configuration Package Manager [can be configured to store its data in S3 -buckets](https://docs.rstudio.com/rspm/admin/files-directories/#data-destinations), +buckets](https://docs.posit.co/rspm/admin/file-storage/file-storage/#data-destinations), which eliminates the need to provision shared storage for multiple replicas. A `values.yaml` file using S3 might contain something like the following: From d9745be33255e9c12b02093b4776ab7c58cb1159 Mon Sep 17 00:00:00 2001 From: edavidaja Date: Tue, 14 May 2024 14:35:30 -0400 Subject: [PATCH 60/67] bump chart versions --- .github/workflows/chart-doc.yaml | 2 +- charts/posit-chronicle/Chart.yaml | 2 +- charts/posit-chronicle/NEWS.md | 4 ++++ charts/rstudio-connect/Chart.yaml | 4 ++-- charts/rstudio-connect/NEWS.md | 6 +++++- charts/rstudio-launcher-rbac/Chart.yaml | 6 +++--- charts/rstudio-launcher-rbac/NEWS.md | 4 ++++ charts/rstudio-library/Chart.yaml | 4 ++-- charts/rstudio-library/NEWS.md | 4 ++++ charts/rstudio-pm/Chart.yaml | 4 ++-- charts/rstudio-pm/NEWS.md | 4 ++++ charts/rstudio-workbench/Chart.yaml | 4 ++-- charts/rstudio-workbench/NEWS.md | 4 ++++ 13 files changed, 38 insertions(+), 14 deletions(-) diff --git a/.github/workflows/chart-doc.yaml b/.github/workflows/chart-doc.yaml index 06e82c12..6da6c9c4 100644 --- a/.github/workflows/chart-doc.yaml +++ b/.github/workflows/chart-doc.yaml @@ -9,7 +9,7 @@ jobs: name: helm-docs steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - uses: r-lib/actions/pr-fetch@v2 with: diff --git a/charts/posit-chronicle/Chart.yaml b/charts/posit-chronicle/Chart.yaml index d3075872..a1719d0e 100644 --- a/charts/posit-chronicle/Chart.yaml +++ b/charts/posit-chronicle/Chart.yaml @@ -1,7 +1,7 @@ apiVersion: v2 name: posit-chronicle description: Official Helm chart for Posit Chronicle Server -version: 0.3.0 +version: 0.3.1 appVersion: 2024.03.0 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png home: https://www.posit.co diff --git a/charts/posit-chronicle/NEWS.md b/charts/posit-chronicle/NEWS.md index b810a951..dd6b6472 100644 --- a/charts/posit-chronicle/NEWS.md +++ b/charts/posit-chronicle/NEWS.md @@ -1,5 +1,9 @@ # Changelog +## 0.3.1 + +- Documentation site updates + ## 0.3.0 - Bump Chronicle to version 2024.03.0 diff --git a/charts/rstudio-connect/Chart.yaml b/charts/rstudio-connect/Chart.yaml index 5518cb08..a08b0773 100644 --- a/charts/rstudio-connect/Chart.yaml +++ b/charts/rstudio-connect/Chart.yaml @@ -1,6 +1,6 @@ name: rstudio-connect description: Official Helm chart for Posit Connect -version: 0.6.6 +version: 0.6.7 apiVersion: v2 appVersion: 2024.04.1 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png @@ -13,7 +13,7 @@ maintainers: url: https://github.com/sol-eng dependencies: - name: rstudio-library - version: 0.1.29 + version: 0.1.30 repository: file://../rstudio-library annotations: artifacthub.io/images: | diff --git a/charts/rstudio-connect/NEWS.md b/charts/rstudio-connect/NEWS.md index 36f8c37d..682e36f8 100644 --- a/charts/rstudio-connect/NEWS.md +++ b/charts/rstudio-connect/NEWS.md @@ -1,6 +1,10 @@ # Changelog -# 0.6.6 +## 0.6.7 + +- Documentation site updates + +## 0.6.6 - Bump Connect version to 2024.04.1 diff --git a/charts/rstudio-launcher-rbac/Chart.yaml b/charts/rstudio-launcher-rbac/Chart.yaml index d83849eb..4d7dbdb7 100644 --- a/charts/rstudio-launcher-rbac/Chart.yaml +++ b/charts/rstudio-launcher-rbac/Chart.yaml @@ -2,8 +2,8 @@ apiVersion: v2 name: rstudio-launcher-rbac description: RBAC definition for the RStudio Job Launcher type: application -version: 0.2.20 -appVersion: 0.2.20 +version: 0.2.21 +appVersion: 0.2.21 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png sources: - https://github.com/rstudio/helm @@ -13,7 +13,7 @@ maintainers: url: https://github.com/sol-eng dependencies: - name: rstudio-library - version: 0.1.29 + version: 0.1.30 repository: file://../rstudio-library keywords: - "data science" diff --git a/charts/rstudio-launcher-rbac/NEWS.md b/charts/rstudio-launcher-rbac/NEWS.md index 03e29eb4..e3834ea0 100644 --- a/charts/rstudio-launcher-rbac/NEWS.md +++ b/charts/rstudio-launcher-rbac/NEWS.md @@ -1,5 +1,9 @@ # Changelog +## 0.2.21 + +- Documentation site updates + ## 0.2.20 - Updates to support standalone documentation site diff --git a/charts/rstudio-library/Chart.yaml b/charts/rstudio-library/Chart.yaml index 3ca284ce..5be0c871 100644 --- a/charts/rstudio-library/Chart.yaml +++ b/charts/rstudio-library/Chart.yaml @@ -2,8 +2,8 @@ apiVersion: v2 name: rstudio-library description: Helm library helpers for use by official RStudio charts type: library -version: 0.1.29 -appVersion: 0.1.29 +version: 0.1.30 +appVersion: 0.1.30 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png home: https://www.rstudio.com diff --git a/charts/rstudio-library/NEWS.md b/charts/rstudio-library/NEWS.md index 9ac54457..0e68647c 100644 --- a/charts/rstudio-library/NEWS.md +++ b/charts/rstudio-library/NEWS.md @@ -1,5 +1,9 @@ # Changelog +## 0.1.30 + +- Documentation site updates + ## 0.1.29 - Updates to support standalone documentation site diff --git a/charts/rstudio-pm/Chart.yaml b/charts/rstudio-pm/Chart.yaml index f9e32dfa..e2747d72 100644 --- a/charts/rstudio-pm/Chart.yaml +++ b/charts/rstudio-pm/Chart.yaml @@ -1,6 +1,6 @@ name: rstudio-pm description: Official Helm chart for Posit Package Manager -version: 0.5.25 +version: 0.5.26 apiVersion: v2 appVersion: 2024.04.0 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png @@ -14,7 +14,7 @@ maintainers: url: https://github.com/rstudio/helm dependencies: - name: rstudio-library - version: 0.1.29 + version: 0.1.30 repository: file://../rstudio-library annotations: artifacthub.io/images: | diff --git a/charts/rstudio-pm/NEWS.md b/charts/rstudio-pm/NEWS.md index 491bdc2b..2d6c985f 100644 --- a/charts/rstudio-pm/NEWS.md +++ b/charts/rstudio-pm/NEWS.md @@ -1,5 +1,9 @@ # Changelog +## 0.5.26 + +- Documentation site updates + ## 0.5.25 - Update default Posit Package Manager version to 2024.04.0-20 diff --git a/charts/rstudio-workbench/Chart.yaml b/charts/rstudio-workbench/Chart.yaml index 987b7ad6..56b31234 100644 --- a/charts/rstudio-workbench/Chart.yaml +++ b/charts/rstudio-workbench/Chart.yaml @@ -1,6 +1,6 @@ name: rstudio-workbench description: Official Helm chart for Posit Workbench -version: 0.7.3 +version: 0.7.4 apiVersion: v2 appVersion: 2024.04.0 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png @@ -13,7 +13,7 @@ maintainers: url: https://github.com/sol-eng dependencies: - name: rstudio-library - version: 0.1.29 + version: 0.1.30 repository: file://../rstudio-library annotations: artifacthub.io/images: | diff --git a/charts/rstudio-workbench/NEWS.md b/charts/rstudio-workbench/NEWS.md index 1f0e7e46..f5efbca9 100644 --- a/charts/rstudio-workbench/NEWS.md +++ b/charts/rstudio-workbench/NEWS.md @@ -1,5 +1,9 @@ # Changelog +## 0.7.4 + +- Documentation site updates + ## 0.7.3 - Bump Workbench version to 2024.04.0 From 677a27a855fd4e6bfacf0d92aef4efe5cc30682c Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 18:36:39 +0000 Subject: [PATCH 61/67] Update helm-docs and README.md --- charts/posit-chronicle/README.md | 6 +++--- charts/rstudio-connect/README.md | 6 +++--- charts/rstudio-launcher-rbac/README.md | 6 +++--- charts/rstudio-library/README.md | 2 +- charts/rstudio-pm/README.md | 6 +++--- charts/rstudio-workbench/README.md | 6 +++--- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/charts/posit-chronicle/README.md b/charts/posit-chronicle/README.md index 35dac8c4..ea3b103e 100644 --- a/charts/posit-chronicle/README.md +++ b/charts/posit-chronicle/README.md @@ -1,6 +1,6 @@ # Posit Chronicle -![Version: 0.3.0](https://img.shields.io/badge/Version-0.3.0-informational?style=flat-square) ![AppVersion: 2024.03.0](https://img.shields.io/badge/AppVersion-2024.03.0-informational?style=flat-square) +![Version: 0.3.1](https://img.shields.io/badge/Version-0.3.1-informational?style=flat-square) ![AppVersion: 2024.03.0](https://img.shields.io/badge/AppVersion-2024.03.0-informational?style=flat-square) #### _Official Helm chart for Posit Chronicle Server_ @@ -25,11 +25,11 @@ To ensure a stable production deployment: ## Installing the chart -To install the chart with the release name `my-release` at version 0.3.0: +To install the chart with the release name `my-release` at version 0.3.1: ```{.bash} helm repo add rstudio https://helm.rstudio.com -helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.0 +helm upgrade --install my-release rstudio/posit-chronicle --version=0.3.1 ``` To explore other chart versions, look at: diff --git a/charts/rstudio-connect/README.md b/charts/rstudio-connect/README.md index 60433c5f..efaf5ee7 100644 --- a/charts/rstudio-connect/README.md +++ b/charts/rstudio-connect/README.md @@ -1,6 +1,6 @@ # Posit Connect -![Version: 0.6.6](https://img.shields.io/badge/Version-0.6.6-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) +![Version: 0.6.7](https://img.shields.io/badge/Version-0.6.7-informational?style=flat-square) ![AppVersion: 2024.04.1](https://img.shields.io/badge/AppVersion-2024.04.1-informational?style=flat-square) #### _Official Helm chart for Posit Connect_ @@ -30,11 +30,11 @@ To ensure reproducibility in your environment and insulate yourself from future ## Installing the chart -To install the chart with the release name `my-release` at version 0.6.6: +To install the chart with the release name `my-release` at version 0.6.7: ```{.bash} helm repo add rstudio https://helm.rstudio.com -helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.6 +helm upgrade --install my-release rstudio/rstudio-connect --version=0.6.7 ``` To explore other chart versions, look at: diff --git a/charts/rstudio-launcher-rbac/README.md b/charts/rstudio-launcher-rbac/README.md index 4a3d1b1c..abe0df9c 100644 --- a/charts/rstudio-launcher-rbac/README.md +++ b/charts/rstudio-launcher-rbac/README.md @@ -1,6 +1,6 @@ # rstudio-launcher-rbac -![Version: 0.2.20](https://img.shields.io/badge/Version-0.2.20-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.2.20](https://img.shields.io/badge/AppVersion-0.2.20-informational?style=flat-square) +![Version: 0.2.21](https://img.shields.io/badge/Version-0.2.21-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.2.21](https://img.shields.io/badge/AppVersion-0.2.21-informational?style=flat-square) #### _RBAC definition for the RStudio Job Launcher_ @@ -21,11 +21,11 @@ To ensure a stable production deployment: ## Installing the chart -To install the chart with the release name `my-release` at version 0.2.20: +To install the chart with the release name `my-release` at version 0.2.21: ```{.bash} helm repo add rstudio https://helm.rstudio.com -helm upgrade --install my-release rstudio/rstudio-launcher-rbac --version=0.2.20 +helm upgrade --install my-release rstudio/rstudio-launcher-rbac --version=0.2.21 ``` To explore other chart versions, look at: diff --git a/charts/rstudio-library/README.md b/charts/rstudio-library/README.md index 69f11cb9..142c0114 100644 --- a/charts/rstudio-library/README.md +++ b/charts/rstudio-library/README.md @@ -1,6 +1,6 @@ # rstudio-library -![Version: 0.1.29](https://img.shields.io/badge/Version-0.1.29-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) ![AppVersion: 0.1.29](https://img.shields.io/badge/AppVersion-0.1.29-informational?style=flat-square) +![Version: 0.1.30](https://img.shields.io/badge/Version-0.1.30-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) ![AppVersion: 0.1.30](https://img.shields.io/badge/AppVersion-0.1.30-informational?style=flat-square) #### _Helm library helpers for use by official RStudio charts_ diff --git a/charts/rstudio-pm/README.md b/charts/rstudio-pm/README.md index f5b5c0d2..abc3f0b3 100644 --- a/charts/rstudio-pm/README.md +++ b/charts/rstudio-pm/README.md @@ -1,6 +1,6 @@ # Posit Package Manager -![Version: 0.5.25](https://img.shields.io/badge/Version-0.5.25-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) +![Version: 0.5.26](https://img.shields.io/badge/Version-0.5.26-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) #### _Official Helm chart for Posit Package Manager_ @@ -24,11 +24,11 @@ To ensure a stable production deployment: ## Installing the chart -To install the chart with the release name `my-release` at version 0.5.25: +To install the chart with the release name `my-release` at version 0.5.26: ```{.bash} helm repo add rstudio https://helm.rstudio.com -helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.25 +helm upgrade --install my-release rstudio/rstudio-pm --version=0.5.26 ``` To explore other chart versions, look at: diff --git a/charts/rstudio-workbench/README.md b/charts/rstudio-workbench/README.md index 88d90d5a..85bef800 100644 --- a/charts/rstudio-workbench/README.md +++ b/charts/rstudio-workbench/README.md @@ -1,6 +1,6 @@ # Posit Workbench -![Version: 0.7.3](https://img.shields.io/badge/Version-0.7.3-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) +![Version: 0.7.4](https://img.shields.io/badge/Version-0.7.4-informational?style=flat-square) ![AppVersion: 2024.04.0](https://img.shields.io/badge/AppVersion-2024.04.0-informational?style=flat-square) #### _Official Helm chart for Posit Workbench_ @@ -24,11 +24,11 @@ To ensure a stable production deployment: ## Installing the chart -To install the chart with the release name `my-release` at version 0.7.3: +To install the chart with the release name `my-release` at version 0.7.4: ```{.bash} helm repo add rstudio https://helm.rstudio.com -helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.3 +helm upgrade --install my-release rstudio/rstudio-workbench --version=0.7.4 ``` To explore other chart versions, look at: From d72165a7d497df5dd409938a52b18913ade9560e Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 14 May 2024 18:36:54 +0000 Subject: [PATCH 62/67] Update rbac yaml --- .../rbac/rstudio-launcher-rbac-0.2.21.yaml | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 examples/rbac/rstudio-launcher-rbac-0.2.21.yaml diff --git a/examples/rbac/rstudio-launcher-rbac-0.2.21.yaml b/examples/rbac/rstudio-launcher-rbac-0.2.21.yaml new file mode 100644 index 00000000..3b322f8d --- /dev/null +++ b/examples/rbac/rstudio-launcher-rbac-0.2.21.yaml @@ -0,0 +1,88 @@ +--- +# Source: rstudio-launcher-rbac/templates/rbac.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: rstudio-launcher-rbac +--- +# Source: rstudio-launcher-rbac/templates/rbac.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: rstudio-launcher-rbac +rules: + - apiGroups: + - "" + resources: + - "serviceaccounts" + verbs: + - "list" + - apiGroups: + - "" + resources: + - "pods/log" + verbs: + - "get" + - "watch" + - "list" + - apiGroups: + - "" + resources: + - "pods" + - "pods/attach" + - "pods/exec" + verbs: + - "get" + - "create" + - "update" + - "patch" + - "watch" + - "list" + - "delete" + - apiGroups: + - "" + resources: + - "events" + verbs: + - "watch" + - apiGroups: + - "" + resources: + - "services" + verbs: + - "create" + - "get" + - "watch" + - "list" + - "delete" + - apiGroups: + - "batch" + resources: + - "jobs" + verbs: + - "create" + - "update" + - "patch" + - "get" + - "watch" + - "list" + - "delete" + - apiGroups: + - "metrics.k8s.io" + resources: + - "pods" + verbs: + - "get" +--- +# Source: rstudio-launcher-rbac/templates/rbac.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: rstudio-launcher-rbac +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: rstudio-launcher-rbac +subjects: + - kind: ServiceAccount + name: rstudio-launcher-rbac From 8fbad7d8a62e9ac8546fb2d9219a642f85624b60 Mon Sep 17 00:00:00 2001 From: edavidaja Date: Tue, 14 May 2024 19:27:08 -0400 Subject: [PATCH 63/67] add gh pages publish --- .github/workflows/publish.yml | 23 +++++++++++++++++++++++ _quarto.yml | 4 ++-- 2 files changed, 25 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..ec3c4b70 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,23 @@ +on: + workflow_dispatch: + +name: Quarto Publish + +jobs: + build-deploy: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - name: Render and Publish + uses: quarto-dev/quarto-actions/publish@v2 + with: + target: gh-pages + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index 8b3f08ba..109a5094 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -22,13 +22,13 @@ filters: website: title: Posit Helm Charts - site-url: https://docs.posit.co/helm + site-url: https://helm.rstudio.com bread-crumbs: true repo-url: https://github.com/rstudio/helm repo-actions: [edit, issue] page-footer: left: | - Copyright © 2???-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. + Copyright © {{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved. center: | Posit Helm Charts right: From 861678f8e44a3e6fd1bd5f8a7d999c8c50a0ad31 Mon Sep 17 00:00:00 2001 From: edavidaja Date: Wed, 15 May 2024 15:49:40 -0400 Subject: [PATCH 64/67] remove gh pages publish --- .github/workflows/publish.yml | 23 ----------------------- _quarto.yml | 2 +- 2 files changed, 1 insertion(+), 24 deletions(-) delete mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml deleted file mode 100644 index ec3c4b70..00000000 --- a/.github/workflows/publish.yml +++ /dev/null @@ -1,23 +0,0 @@ -on: - workflow_dispatch: - -name: Quarto Publish - -jobs: - build-deploy: - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - name: Check out repository - uses: actions/checkout@v4 - - - name: Set up Quarto - uses: quarto-dev/quarto-actions/setup@v2 - - - name: Render and Publish - uses: quarto-dev/quarto-actions/publish@v2 - with: - target: gh-pages - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index 109a5094..bcd59106 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -22,7 +22,7 @@ filters: website: title: Posit Helm Charts - site-url: https://helm.rstudio.com + site-url: https://docs.posit.co/helm bread-crumbs: true repo-url: https://github.com/rstudio/helm repo-actions: [edit, issue] From 7a49a2aa7f5ed0500258ec3555248c2d7de443cb Mon Sep 17 00:00:00 2001 From: Cole Arendt Date: Wed, 15 May 2024 19:58:13 -0400 Subject: [PATCH 65/67] update lockfiles --- charts/rstudio-connect/Chart.lock | 6 +++--- charts/rstudio-launcher-rbac/Chart.lock | 6 +++--- charts/rstudio-pm/Chart.lock | 6 +++--- charts/rstudio-workbench/Chart.lock | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/charts/rstudio-connect/Chart.lock b/charts/rstudio-connect/Chart.lock index 9ebc104b..0a3e8bb9 100644 --- a/charts/rstudio-connect/Chart.lock +++ b/charts/rstudio-connect/Chart.lock @@ -1,6 +1,6 @@ dependencies: - name: rstudio-library repository: file://../rstudio-library - version: 0.1.29 -digest: sha256:ccca30d883d295668402d63328b1d603911ef717b41207f9b3a2e4d1dd3af1a3 -generated: "2024-04-01T12:17:53.025791-04:00" + version: 0.1.30 +digest: sha256:dcf9d679b18cf99da3781b22797d639a2cbeb47b746dff7e7532b3e55261e938 +generated: "2024-05-15T19:57:52.620702-04:00" diff --git a/charts/rstudio-launcher-rbac/Chart.lock b/charts/rstudio-launcher-rbac/Chart.lock index 996a35e0..134100c0 100644 --- a/charts/rstudio-launcher-rbac/Chart.lock +++ b/charts/rstudio-launcher-rbac/Chart.lock @@ -1,6 +1,6 @@ dependencies: - name: rstudio-library repository: file://../rstudio-library - version: 0.1.29 -digest: sha256:ccca30d883d295668402d63328b1d603911ef717b41207f9b3a2e4d1dd3af1a3 -generated: "2024-04-01T12:17:21.579972-04:00" + version: 0.1.30 +digest: sha256:dcf9d679b18cf99da3781b22797d639a2cbeb47b746dff7e7532b3e55261e938 +generated: "2024-05-15T19:57:55.735705-04:00" diff --git a/charts/rstudio-pm/Chart.lock b/charts/rstudio-pm/Chart.lock index 56bdeeeb..82f8ef24 100644 --- a/charts/rstudio-pm/Chart.lock +++ b/charts/rstudio-pm/Chart.lock @@ -1,6 +1,6 @@ dependencies: - name: rstudio-library repository: file://../rstudio-library - version: 0.1.29 -digest: sha256:ccca30d883d295668402d63328b1d603911ef717b41207f9b3a2e4d1dd3af1a3 -generated: "2024-04-01T12:17:57.728915-04:00" + version: 0.1.30 +digest: sha256:dcf9d679b18cf99da3781b22797d639a2cbeb47b746dff7e7532b3e55261e938 +generated: "2024-05-15T19:57:58.863614-04:00" diff --git a/charts/rstudio-workbench/Chart.lock b/charts/rstudio-workbench/Chart.lock index 0c73882b..f139bc12 100644 --- a/charts/rstudio-workbench/Chart.lock +++ b/charts/rstudio-workbench/Chart.lock @@ -1,6 +1,6 @@ dependencies: - name: rstudio-library repository: file://../rstudio-library - version: 0.1.29 -digest: sha256:ccca30d883d295668402d63328b1d603911ef717b41207f9b3a2e4d1dd3af1a3 -generated: "2024-04-01T12:18:00.109138-04:00" + version: 0.1.30 +digest: sha256:dcf9d679b18cf99da3781b22797d639a2cbeb47b746dff7e7532b3e55261e938 +generated: "2024-05-15T19:58:02.13077-04:00" From 55aadc8ad0146c8f534c3cd4ebf28adadc9a9f08 Mon Sep 17 00:00:00 2001 From: edavidaja Date: Fri, 17 May 2024 11:38:26 -0400 Subject: [PATCH 66/67] publish to s3 --- .github/workflows/publish.yml | 38 +++++++++++++++++++++++++++++++++++ Justfile | 14 +++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..6e51b8e5 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,38 @@ +name: Quarto Publish to docs.posit.co + +on: + workflow_dispatch: + push: + branches: main + +permissions: + id-token: write + contents: read + +jobs: + build-deploy: + runs-on: ubuntu-latest + steps: + - name: Configure AWS credentials + id: creds + uses: aws-actions/configure-aws-credentials@master + with: + role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }} + aws-region: ${{ secrets.AWS_REGION }} + + - name: Check out repository + uses: actions/checkout@v4 + + - name: install Just + uses: extractions/setup-just@v2 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + with: + version: pre-release + + - name: Render Quarto Project + uses: quarto-dev/quarto-actions/render@v2 + + - run: just push-docs + diff --git a/Justfile b/Justfile index 3b5fbc64..f8a0268f 100644 --- a/Justfile +++ b/Justfile @@ -101,3 +101,17 @@ test-connect-interpreter-versions: docker run --rm $image /bin/bash -c "command -v $ex" done done + +push-docs: + #!/usr/bin/env bash + set -euxo pipefail + + s3_args=(--dryrun) + if [[ "${GITHUB_REF:-}" == "refs/heads/main" ]] || [[ "${GITHUB_REF:-}" =~ ^refs/tags/v[0-9]{4}\.[0-9]{2}\.[0-9]+$ ]]; then + s3_args=("") + fi + + # The s3 bucket is s3://docs.rstudio.com/, which is available as https://docs.posit.co/ + aws s3 sync ${s3_args[*]:-} \ + _site \ + "s3://docs.rstudio.com/helm/" \ No newline at end of file From 0617f75b94fe8008471d6ed46dd7ba1160f0d693 Mon Sep 17 00:00:00 2001 From: Cole Arendt Date: Fri, 17 May 2024 17:42:15 -0400 Subject: [PATCH 67/67] update prepull-daemonset --- other-charts/prepull-daemonset/Chart.yaml | 2 +- other-charts/prepull-daemonset/NEWS.md | 4 ++++ other-charts/prepull-daemonset/README.md | 6 +++--- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/other-charts/prepull-daemonset/Chart.yaml b/other-charts/prepull-daemonset/Chart.yaml index 97c8fe24..bc72a7e6 100644 --- a/other-charts/prepull-daemonset/Chart.yaml +++ b/other-charts/prepull-daemonset/Chart.yaml @@ -1,6 +1,6 @@ name: prepull-daemonset description: a daemonset to prepull images so they are cached -version: 0.0.3 +version: 0.0.4 apiVersion: v2 icon: https://rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png home: https://www.rstudio.com diff --git a/other-charts/prepull-daemonset/NEWS.md b/other-charts/prepull-daemonset/NEWS.md index c7b0f049..8c4894c5 100644 --- a/other-charts/prepull-daemonset/NEWS.md +++ b/other-charts/prepull-daemonset/NEWS.md @@ -1,5 +1,9 @@ # Changelog +## 0.0.4 + +- Update docs + ## 0.0.3 - Updates to support standalone documentation site diff --git a/other-charts/prepull-daemonset/README.md b/other-charts/prepull-daemonset/README.md index 8358fc42..a8c757e1 100644 --- a/other-charts/prepull-daemonset/README.md +++ b/other-charts/prepull-daemonset/README.md @@ -1,16 +1,16 @@ # prepull-daemonset -![Version: 0.0.3](https://img.shields.io/badge/Version-0.0.3-informational?style=flat-square) +![Version: 0.0.4](https://img.shields.io/badge/Version-0.0.4-informational?style=flat-square) #### _a daemonset to prepull images so they are cached_ ## Installing the Chart -To install the chart with the release name `my-release` at version 0.0.3: +To install the chart with the release name `my-release` at version 0.0.4: ```bash helm repo add rstudio https://helm.rstudio.com -helm install my-release rstudio/prepull-daemonset --version=0.0.3 +helm install my-release rstudio/prepull-daemonset --version=0.0.4 ``` ## Use