Kubernetes cluster preparation

Note

Before continuing with the steps below, please ensure that your Kubernetes cluster is configured according to your cloud provider’s instructions. For example, your Kubernetes cluster might need to have Container Storage Interface (CSI) drivers and virtual networks configured.

Managing secrets in Kubernetes deployments

When deploying Posit Connect on Kubernetes using Helm charts, you should use Kubernetes Secrets to manage sensitive configuration values like database passwords, rather than Connect’s encrypted configuration values.

Why use Kubernetes secrets instead of encrypted config values

Connect’s encrypted configuration values rely on a secret key that is generated automatically when Connect first starts. This creates a chicken-and-egg problem for Helm deployments: you need the encryption key to encrypt values, but the key doesn’t exist until Connect runs for the first time.

Using Kubernetes Secrets avoids this issue entirely and provides several advantages:

  • No encryption key dependency: Secrets work independently of Connect’s internal encryption key.
  • Kubernetes-native: Integrates with Kubernetes role-based access control (RBAC) and audit logging.
  • External secret manager support: Compatible with tools like HashiCorp Vault, AWS Secrets Manager, and Azure Key Vault through operators like External Secrets Operator.
  • Separation of concerns: Security teams can manage secrets independently from application configuration.
Note

While Kubernetes secrets are base64-encoded by default (not encrypted), you can enable encryption at rest for secrets in your cluster or use an external secrets manager for additional security.

Supported secret types

The Connect Helm chart supports injecting secrets for:

  • Database passwords: PostgreSQL connection credentials
  • License files: Connect license files
  • Other sensitive configuration: Any value that can be passed as an environment variable

The following sections show how to create these secrets.

Create a namespace for Posit Connect

You need a Kubernetes namespace for Posit Connect. We recommend creating a new one called posit-connect or having a cluster administrator create one on your behalf.

Use the following commands to create and switch to the namespace:

Terminal
# Create the new namespace
kubectl create namespace posit-connect

# Switch to the new namespace in your current context
kubectl config set-context --current --namespace=posit-connect

Create a secret containing a PostgreSQL database password

Store the PostgreSQL database password as a Kubernetes Secret and make it available to the container as an environment variable, as shown in the values.yaml in the next section.

Create the secret imperatively:

Terminal
kubectl create secret generic posit-connect-database --from-literal=password=YOURPASSWORDHERE

Or declaratively with YAML:

Terminal
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: posit-connect-database
  namespace: posit-connect
type: Opaque
stringData:
  password: YOURPASSWORDHERE
EOF
Note

For production deployments, consider using an external secrets manager like HashiCorp Vault or AWS Secrets Manager with the External Secrets Operator to automatically sync secrets into your Kubernetes cluster.

Create a StorageClass with ReadWriteMany access

Your cluster must have a StorageClass backed by POSIX-compliant PersistentVolume storage that supports symlinks and ReadWriteMany access. A Persistent Volume Claim (PVC) uses this storage class to either dynamically provision a Persistent Volume (PV) or use a static PV for the Connect data directory.

Alternatively, if you already have an NFS instance that you wish to use, you can skip this section. The External Storage appendix describes how to configure an external NFS instance for use by the Posit Connect Helm chart.

Create a secret containing a license file

Store a license file as a Kubernetes Secret and set the license.file.secret and license.file.secretKey values accordingly as shown in the values.yaml in the next section.

Create the secret imperatively:

Terminal
kubectl create secret generic posit-connect-license --from-file=licenses/posit-connect.lic