Upgrading Dash Enterprise

Your organization is responsible for performing Dash Enterprise upgrades. We’ll notify you when a new version is available.

To ensure you remain eligible for support, upgrade Dash Enterprise regularly. We recommend keeping your instance as close to the latest version as possible for best results.

Contact us for upgrade help.

Checking the Current Version

helm ls --all-namespaces

Next to the namespace for the Dash Enterprise instance whose version you want to check, look at the CHART or APP VERSION.

Before Upgrading

Before upgrading Dash Enterprise, we strongly recommend:
* Carefully reading the changelog for the version that you want to upgrade to, as well as any intermediate versions.
* Creating a backup that you can restore in the event of an unsuccessful upgrade.

Follow one or many of the upgrade procedures below corresponding to your current and target versions.

6.2.X to 6.3.2

Prerequisites

• kubectl access to the cluster
• Helm v3.14 or later
• If performing the upgrade from an internet-restricted machine, then you have obtained the bundle of Dash Enterprise images for the version that you are upgrading to and you have pushed it to your private container registry.
• Make sure that the following variables are defined in your environment (note that the CHART_VERSION differs from what you set during your installation):

txt export CHART_VERSION=6.3.2 export RELEASE_CHANNEL=standard export CHART_REGISTRY=oci://registry.replicated.com/dash-enterprise export RELEASE_NAME=dash-enterprise export NAMESPACE=<your-namespace> export LICENSE_ID=<license-id> export EMAIL=<email>
If installing from an image bundle that is already pushed to your private container registry, then you also need export SKIP_PUSH=1.

Upgrade Notices

• [6.3.2] If your custom values file defines a private Python package index via global.env.pipExtraIndexUrl, we recommend changing to a more secure way of doing so available in Dash Enterprise 6.3.2 and later.

To change to the recommended way of defining a private Python package index:

1. Create a namespace-scoped secret for the private Python package index URL:
   sh kubectl create secret generic pip-extra-index-url \ --namespace=$NAMESPACE \ --from-literal=url='https://<user>:<token>@pypi.example.com/simple'
   replacing the example private Python package index URL with the correct one. If using an authenticated package index with credentials that contain special characters, don’t forget to URL encode the special characters. For an unauthenticated package index, the URL looks like https://pypi.example.com/simple.

2. After your 6.3.2 upgrade, replace the following lines in your custom values file
   yaml global: env: pipExtraIndexUrl: "https://<user>:<token>@pypi.example.com/simple"

with
yaml global: env: pipExtraIndexUrlSecret: name: pip-extra-index-url key: url # Explicitly unset pipExtraIndexUrl to remove the previously configured value pipExtraIndexUrl: ""
changing the name if you used something different in step 1.

3. Apply the change:
   sh helm upgrade $RELEASE_NAME -f custom-values.yaml \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --reset-then-reuse-values
   changing the name of your custom values file if it is different.

• [6.3.2] Important: Upgrading causes all workspaces to restart.

• [6.3.1] Important: Upgrading causes all workspaces to restart.

• [6.3.0] We recommend updating the values of any environment variables set in the Dash Enterprise App Manager. Contact us if you need assistance.

• [6.3.0] Important: Upgrading causes all apps and workspaces to restart.

Running the Upgrade

To upgrade Dash Enterprise from 6.2.X to 6.3.2:

1. Authenticate to the Replicated registry if you aren’t already:
   sh echo $LICENSE_ID | helm registry login registry.replicated.com \ --username "$EMAIL" \ --password-stdin

2. Use one of the following commands:

• If you don’t need to apply a configuration override:
  sh helm upgrade $RELEASE_NAME \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --reset-then-reuse-values

• If you need to apply a configuration override:
  sh helm upgrade $RELEASE_NAME -f custom-values.yaml \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --reset-then-reuse-values
  changing the name of your custom values file if it is different.

  (the --reset-then-reuse-values flag applies all configuration settings that you applied during the original installation and that are not modified in this command).

6.1.X to 6.2.3

Prerequisites

• kubectl access to the cluster
• Helm v3.14 or later
• If performing the upgrade from an internet-restricted machine, then you have obtained the bundle of Dash Enterprise images for the version that you are upgrading to and you have pushed it to your private container registry.
• Make sure that the following variables are defined in your environment (note that the CHART_VERSION differs from what you set during your installation):
  txt export CHART_VERSION=6.2.3 export RELEASE_CHANNEL=standard export CHART_REGISTRY=oci://registry.replicated.com/dash-enterprise export RELEASE_NAME=dash-enterprise export NAMESPACE=<your-namespace> export LICENSE_ID=<license-id> export EMAIL=<email>
  If installing from an image bundle that is already pushed to your private container registry, then you also need export SKIP_PUSH=1.

Upgrade Notices

Make sure you’re aware of the following when passing through the intermediate versions below:

• [6.2.1] Important: Upgrading causes all apps and workspaces to restart.

• [6.2.0] User-created workloads now use a read-only filesystem by default. If any apps or workspaces need to write to the filesystem (such as for running predeploy or postdeploy scripts), an allowWritableRootFs: true configuration change is needed. The overrides below allow apps and workspaces to use sudo and write to the filesystem:

• For apps:
  yml agents: worker: app: allowPrivilegeEscalation: true allowWritableRootFs: true capabilities: add: - SETUID - SETGID - AUDIT_WRITE

• For workspaces:
  yml agents: worker: workspace: allowPrivilegeEscalation: true allowWritableRootFs: true capabilities: add: - SETUID - SETGID - AUDIT_WRITE

• [6.2.0] Build resource configuration: agents.build.builder.resources is no longer used. Migrate to per-container keys if you were previously using it in your configuration override: agents.build.builder.lifecycle-build.resources, agents.build.builder.lifecycle-export.resources, and agents.build.builder.logging-sidecar.resources.

Running the Upgrade

To upgrade Dash Enterprise from 6.1.X to 6.2.2:

1. Authenticate to the Replicated registry if you aren’t already:
   sh echo $LICENSE_ID | helm registry login registry.replicated.com \ --username "$EMAIL" \ --password-stdin

2. Use one of the following commands:

• If you don’t need to apply a configuration override:
  sh helm upgrade $RELEASE_NAME \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --reset-then-reuse-values

• If you need to apply a configuration override:
  sh helm upgrade $RELEASE_NAME -f custom-values.yaml \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --reset-then-reuse-values
  changing the name of your custom values file if it is different.

  (the --reset-then-reuse-values flag applies all configuration settings that you applied during the original installation and that are not modified in this command).

6.0.X to 6.1.0

Prerequisites

• kubectl access to the cluster
• Helm v3.14 or later
• If performing the upgrade from an internet-restricted machine, then you have obtained the bundle of Dash Enterprise images for the version that you are upgrading to and you have pushed it to your private container registry.
• Make sure that the following variables are defined in your environment (note that the CHART_VERSION differs from what you set during your installation):
  txt export CHART_VERSION=6.1.0 export RELEASE_CHANNEL=standard export CHART_REGISTRY=oci://registry.replicated.com/dash-enterprise export RELEASE_NAME=dash-enterprise export NAMESPACE=<your-namespace> export LICENSE_ID=<license-id> export EMAIL=<email>
  If installing from an image bundle that is already pushed to your private container registry, then you also need export SKIP_PUSH=1.

Upgrade Notices

• auth.keycloak.internalCaSecretName is deprecated in Dash Enterprise 6.1.0. See more information in the changelog.

Running the Upgrade

To upgrade Dash Enterprise from 6.0.X to 6.1.0:

1. Authenticate to the Replicated registry if you aren’t already:
   sh echo $LICENSE_ID | helm registry login registry.replicated.com \ --username "$EMAIL" \ --password-stdin

2. If you are affected by the auth.keycloak.internalCaSecretName deprecation, create a ConfigMap for your self-signed or internal CA certificate:
   sh CA_CONFIGMAP_NAME=keycloak-ca-cert kubectl create configmap $CA_CONFIGMAP_NAME \ --namespace=$NAMESPACE \ --from-file="$KEYCLOAK_CA_CERT" \ --dry-run=client -o yaml | kubectl apply -f -

3. Run one of the following commands:
   * If you are not affected by the auth.keycloak.internalCaSecretName deprecation:
   sh helm upgrade $RELEASE_NAME \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --reset-then-reuse-values
   (the --reset-then-reuse-values flag applies all configuration settings that you applied during the original installation and that are not modified in this command).

• If you are affected by the auth.keycloak.internalCaSecretName deprecation:
  sh helm upgrade $RELEASE_NAME \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --set auth.keycloak.internalCaCertConfigMapName=keycloak-ca-secret \ --reset-then-reuse-values
  (the --reset-then-reuse-values flag applies all configuration settings that you applied during the original installation and that are not modified in this command).