Migration to Kubernetes

These instructions explain how to migrate your existing Posit Connect installation from a provisioned server or virtual machine (VM) to off-host execution on Kubernetes. Connect creates Kubernetes Jobs to build and run your content in isolated pods.

Prerequisites

Use PostgreSQL.

Confirm that your Connect installation uses PostgreSQL before attempting to migrate to Kubernetes. If your installation still uses SQLite, migrate from SQLite to PostgreSQL.
Connect variable data uses a networked filesystem.

Confirm that your Connect installation uses a networked filesystem for its variable data before attempting to migrate to Kubernetes. If your installation still uses the local filesystem, migrate from local storage to NFS.
Upgrade Connect, if necessary.

Confirm that the version of Connect on your current server matches the product version you intend to use on Kubernetes. Separate product upgrades from changes to your infrastructure.
Kubernetes cluster prepared.

Your Kubernetes cluster must be configured and ready. Follow the Kubernetes Cluster Preparation guide to set up your cluster, including PostgreSQL, shared storage, and network connectivity.
Base values.yaml created.

Create your initial Helm chart values file by following Steps 1 and 2 of the Configure your Helm chart values guide.
A Connect API key for an administrator account.

You will use this API key to clear the runtime caches and optionally rebuild content after starting Connect in the new environment.

Workflow

Step 1: Analyze existing content

You will use this information during post-deployment optimization.

Content requirements

Connect executes content in container images that contain R, Python, and Quarto installations. Your images must include versions of these runtimes compatible with your deployed content, along with any system dependencies required by your content’s packages or libraries.

If you are migrating from an existing server, verify that the same R, Python, and Quarto versions available on your current server are present in your content images. The Cookbook has recipes for listing the runtime versions on your server.

For details on image requirements, see Building images for use as execution environments.

Step 2: Identify priority content

After deploying, you can optimize first-time access for important content and verify it runs correctly. Identify the content GUIDs and access paths for these items now, and record them for use in Step 7.

Use rsconnect content search from the rsconnect-python package to identify important content by usage.

For further details on optimizing first-time content access, see the Runtime Cache Workflow.

Step 3: Validate your license

If you plan to use an existing Connect license, confirm that your license allows additional activations. Check your license status using the steps outlined in the Licensing section.

If your existing license lacks additional activations or if you would like a separate evaluation license, speak to your dedicated Posit Customer Success contact or email Posit Sales (sales@posit.co). Mention that you are trialing off-host execution.

Step 4: Migrate configuration

On Kubernetes, Connect configuration lives in the values.yaml file rather than rstudio-connect.gcfg. Move your existing settings from rstudio-connect.gcfg into the config section of values.yaml. See the Helm Chart Reference for how the mapping works.

Step 5: Apply temporary settings

There are a few settings that should be temporarily merged into the values.yaml file to allow the migration cache rebuilding process to occur in an orderly fashion. Be sure to record their original values (if you had them specified at all), so that you can revert them at the end of the migration.

`Scheduler.MinProcessesLimit`

values.yaml

config:
  Scheduler:
    MinProcessesLimit: 0

Setting this value to zero keeps Connect from spinning up processes before the migration is complete. The Posit Connect Admin Guide has additional details about Scheduler.MinProcessesLimit configuration option.

`Applications.ScheduleConcurrency`

values.yaml

config:
  Applications:
    ScheduleConcurrency: 0

Setting this value to zero keeps Connect from starting scheduled jobs before the migration is complete. The Posit Connect Admin Guide has additional details about the Applications.ScheduleConcurrency configuration option.

`Applications.PythonEnvironmentReaping`

values.yaml

config:
  Applications:
    PythonEnvironmentReaping: false

Setting this value to false keeps Connect from reaping unused Python environments until your migration is complete. The Posit Connect Admin Guide has additional details about the Applications.PythonEnvironmentReaping configuration option.

Step 6: Coordinate downtime and deploy

Coordinate with your stakeholders and warn users ahead of the migration with system messages. Your Connect server will be out-of-service during the migration.

The time required depends on the following factors:

Number of content bundles published to your server
The difference of GID / UID assignments between your existing files vs what is present on the runtime images
The amount of content migration optimization that you choose to perform

When you are ready to proceed:

Prohibit access to your Connect servers.
Disable any automatic provisioning or automation which might restart the server.
Stop the rstudio-connect service on the existing server:
```
Terminal
```
```
sudo systemctl stop rstudio-connect
```

Deploy Connect to Kubernetes:

Terminal

helm upgrade --install rstudio-connect-prod rstudio/rstudio-connect \
    --values values.yaml

Check the status of Connect:

Terminal

kubectl get pod -l app.kubernetes.io/name=rstudio-connect

You should see output like the following:

NAME                                       READY   STATUS    RESTARTS   AGE
connect-rstudio-connect-5d45d7b9bc-5wrcn   1/1     Running   0          9m50s

Validate your installation by temporarily enabling port-forwarding:
```
Terminal
```
```
kubectl port-forward svc/rstudio-connect-prod 3939:80
```
Point your browser to http://localhost:3939/, log in, and confirm that Connect is running.

Warning

Manual port-forwarding is appropriate for local testing and validation of the installation. Once you have validated the installation, you need to configure an Ingress and public DNS records for Connect. See Post-deployment for details on configuring external access to your Connect installation.

See the deployment guide for details on how to diagnose and fix problems if your deployment fails to start.

Step 7: Optimize pre-existing content

If your new server uses the same database and the PersistentVolume contains your existing data directory, all previously deployed content bundles are available. The new server rebuilds each content item’s runtime environment on first access, which downloads and installs packages and can be slow.

Rebuild important content ahead of first-user access to avoid this. Administrators and publishers can initiate a rebuild without accessing the content directly.

Using the list of content that you prepared during Step 2, you can use the rsconnect content build tool to rebuild the content.

Note

If you encounter any errors while accessing content on your new server for the first time, your first resolution step should be to initiate a rebuild of the content item. The technique to initiate a rebuild differs depending on the type of content and can range from a simple page reload to a toolbar button available within the Posit Connect dashboard.

Step 8: Revert temporary settings

Now that deployment is complete, revert the temporary configuration changes made in Step 5:

You applied the recommended temporary configuration changes. Revert to the values used before your changes or remove those settings to use the default values.

Remember to review your configuration and revert any deployment-specific changes.

Step 9: Validate important content

Most content needs to be rebuilt when moving from local to off-host execution. In rare cases, the new container environment may not exactly reproduce what accumulated on your original server. Validate important content after migration.

Connect runs in either local mode or Kubernetes mode, not both simultaneously. You can switch between modes by changing the configuration and restarting. Existing content has its environment reconstructed on first execution after the switch.