Dash Enterprise 6 Installation

This guide can help you install Dash Enterprise on your Kubernetes cluster.

Dash Enterprise runs in a single namespace. It operates safely in Kubernetes clusters running applications other than Dash Enterprise, as well as other instances of Dash Enterprise.

Installing Dash Enterprise involves using a Plotly-provided Helm chart.

Prerequisites

Infrastructure

Here are the infrastructure pieces that you’ll need before you can install Dash Enterprise.

Similarly, if any Dash apps depend on APT packages, you’ll need to prepare a custom APT repository.

This private Python package index and/or custom APT repository must have a TLS/SSL certificate from a globally trusted certificate authority.

Required Tools and Permissions

In addition to the above, you must also have the following ready before the installation.

txt -----BEGIN CERTIFICATE----- <Your> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <Your> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <Your> -----END CERTIFICATE-----

(Unless you are using a self-signed certificate, in which case the certificate chain is a single certificate).

The root certificate can be issued by an external/globally-trusted CA or by a CA that is internal to your organization. If using a root certificate issued by an internal CA, you’ll need the root certificate (must be a .crt file) in addition to the full chain.

If you obtained your certificate chain as multiple files, you need to combine them into a single .pem file. You can do this with cat server.pem intermediate.pem trustedroot.pem > fullchain.pem, replacing the file names if yours are different. Using multiple certificates is not supported.

The full certificate chain and unencrypted private key will be used to terminate TLS/SSL.

Installing Dash Enterprise

Defining Variables for the Installation

In this step, you’ll define variables that will be used for the installation in a later step.

On the machine from which you’re performing the installation, use this command to create an install-env.sh file containing these variables. Replace and add values where applicable for your installation.

The first four variables are predefined by Plotly for a Dash Enterprise installation.

cat > install-env.sh << 'EOF'
#!/bin/bash

export CHART_VERSION=6.0.0
export RELEASE_CHANNEL=standard
export CHART_REGISTRY=oci://registry.replicated.com/dash-enterprise
export RELEASE_NAME=dash-enterprise

export LICENSE_ID=&lt;license-id&gt;
export EMAIL=&lt;email&gt; # email address associated with your Dash Enterprise license

export NAMESPACE=&lt;your-namespace&gt; # must be unique for the cluster
export HOSTNAME=&lt;your-hostname&gt;
export CERT_PATH=&lt;your-TLS-certificate-path&gt;
export KEY_PATH=&lt;your-TLS-key-path&gt;

# If planning to integrate Dash Enterprise with an identity provider (IdP) that uses a
# self-signed or internal CA signed certificate, define a certificate that will establish
# trust with the IdP server. The Common Name (Server Name) in the certificate must be
# set to the fully qualified domain name (FQDN) that Dash Enterprise's auth service,
# Keycloak, will use to reach the IdP server.

export CA_CERT=&lt;your-internal-ca-certificate-path&gt;

# AIRGAP CONFIGURATION

export PYTHON_PACKAGE_INDEX_URL=&lt;python-package-index-url&gt;

# Leave REGISTRY_PREFIX empty if the images do not need to be
# pushed to a specific subpath in the registry. Note that
# REGISTRY_PREFIX cannot start nor end with slashes but can
# contain them.

export REGISTRY=&lt;your-registry&gt;
export REGISTRY_PULL_SECRET=&lt;your-registry-pull-secret&gt;
export REGISTRY_PREFIX=""

EOF

If the Dash Enterprise images are already present in your private container registry, add

export SKIP_PUSH=1

to the command (before EOF). Note that SKIP_PUSH will disable image pushes regardless of its
value when it is set. If accidentally set, unset it with unset SKIP_PUSH.

Then apply the file contents to your environment:

source install-env.sh

Setting Up the Dash Enterprise Namespace

In this step, you’ll create the namespace for Dash Enterprise in the cluster and define required secrets.

To set up the Dash Enterprise namespace:

  1. Create the namespace:
    sh kubectl create namespace $NAMESPACE

  2. Create a namespace-scoped Kubernetes secret for your TLS certificate:
    sh kubectl create secret tls de-tls \ --namespace=$NAMESPACE \ --cert=$CERT_PATH \ --key=$KEY_PATH

  3. If you defined a CA_CERT, create the corresponding namespace-scoped Kubernetes secret:
    sh kubectl create secret generic keycloak-ca-secret \ --namespace=$NAMESPACE \ --from-literal=customer.crt.b64="$CA_CERT" \ --dry-run=client -o yaml | kubectl apply -f -

(Optional) Preparing the Private Container Registry

This step is only required if installing from images in a private container registry. Skip to Configuration if installing directly from the Helm chart registry.

Configuration

In this step, you’ll review some Dash Enterprise default parameters and decide whether they are appropriate for your environment.

Good to know: You can continue to make configuration changes after Dash Enterprise is installed.

To apply changes to the defaults below, you’ll add the required flags to your helm install command in the following step. For now, make a note of which ones you’ll need for your desired configuration.

Note about Ingress controllers: Some Ingress controllers do not support TCP proxying. Using these Ingress controllers in the cluster means that app developers will be unable to deploy apps from their workstations over SSH unless additional configuration is performed on port 22.

To apply changes to the defaults below, you’ll need to override values in the Helm chart’s values.yaml file. Extract the values.yaml file if you haven’t already and create a copy such as values-custom.yaml. Make any changes in the custom values file only (you’ll pass it to the helm install command in the next step).

Running the Installation

  1. Assemble your installation command. We recommend working in a code editor.

  2. Start with
    sh helm install $RELEASE_NAME \ $CHART_REGISTRY/$RELEASE_CHANNEL/dash-enterprise \ --version "$CHART_VERSION" \ --namespace $NAMESPACE \ --set global.hostname="$HOSTNAME"

    1. If using a private container registry, pass the file that was generated during the registry preparation step by adding:
      sh --values values-private-registry.yaml \

    2. If installing Dash Enterprise in an airgapped (internet-restricted cluster), add
      sh --set global.env.airgapEnabled=true \ --set replicated.isAirgap=true

    3. If using a private Python package index, add
      sh --set global.env.pipExtraIndexUrl="$PYTHON_PACKAGE_INDEX_URL"

    4. If you defined a CA_CERT in your install-env.sh file, add
      sh --set auth.keycloak.internalCaCertSecretName=keycloak-ca-secret

    5. Dash Enterprise exposes the registry on node port 30100 by default. If this node port is already taken by another tenant on the cluster, add
      sh --set registry.internal.service.nodePort=&lt;port&gt;
      replacing &lt;port&gt; with a node port that is unique for the cluster. The port must be within the 30000-32767 range (reference).

    6. Add any additional flags for your desired configuration.

    7. Finally, if your desired configuration involves using custom values, pass your custom values file:
      sh -f values-custom.yaml
      changing the file name if your custom values file is named something else.

  3. Run the assembled command.

Note: The TLS secret that you created is provided automatically (--set global.tls.secretName="de-tls" is used internally).

  1. Run
    sh watch -- kubectl get pod -n $NAMESPACE

and wait until the output shows all the pods in Running or Completed state.

Creating DNS Entries

  1. Get the load balancer IP address using one of the following commands:
  1. Create DNS entries as follows:
Name Type Value
&lt;base-domain&gt; A Record &lt;load-balancer-ip&gt;
api-&lt;base-domain&gt; CNAME &lt;base-domain&gt;
auth-&lt;base-domain&gt; CNAME &lt;base-domain&gt;

where &lt;load-balancer-ip&gt; is the IP address that you retrieved in step 1.

Accessing Dash Enterprise

Dash Enterprise uses Keycloak for identity and access management. During the installation, an initial Keycloak admin user was created to allow you to access the Keycloak Administration Console. As part of Keycloak security best practices, you’ll create a second Keycloak admin user. With this new Keycloak admin user, you’ll create the Dash Enterprise account that you’ll use to log in to https://&lt;your-dash-enterprise-server&gt;.

Creating the Keycloak Admin User

In this step, you’ll retrieve the password for the initial Keycloak admin user and use it to create a new admin user.

To create the new Keycloak admin user:

  1. Retrieve the password for the initial Keycloak admin user (this displays the password in plain text):
    sh kubectl get secret keycloak-admin-password -n $NAMESPACE -o jsonpath='{.data.password}' | base64 -d && echo

  2. Copy the password.

  3. Go to https://auth-&lt;your-dash-enterprise-server&gt;
  4. Enter the username admin and the password that you retrieved in step 1; then select Sign In.

<img>

A warning message is displayed that recommends you create a new admin user and delete the existing one. Important: Do not delete nor edit the initial Keycloak admin user. This user is managed by Dash Enterprise.

  1. Make sure that Keycloak (master) is selected in the realm list in the top left corner.
  2. Select Users > Add User.
  3. In Username, enter the username that you want for the Keycloak admin user.
  4. Select Create. Additional settings become available.
  5. Go to Credentials.
  6. Select Set password.
  7. In Password and Password confirmation, enter the password you want to use.
  8. Select Save; then Save password to confirm.
  9. (Recommended) Add the username and password to your organization’s password manager or other secure storage. You can share these credentials with other members in your organization who need to access Keycloak.
  10. Assign the Keycloak admin role:
    1. Go to Role mapping.
    2. Select Assign role.
    3. Change the filter to Filter by realm roles.
    4. Find and select the role called “admin”.
    5. Select Assign.

Use this user from now on when logging in to Keycloak.

You can rotate the password for this user in Keycloak by going back to the Keycloak (master) realm, editing the user, and changing the Password that is set. Note that managing this user is the only reason to go to the Keycloak (master) realm. All Dash Enterprise user management is done in a different realm.

Creating Your Dash Enterprise User

In this step, you’ll log in to Keycloak using the newly created admin user and create a Dash Enterprise user that has admin permissions at the Dash Enterprise level. Dash Enterprise administrators have access to the Admin section of the Dash Enterprise App Manager, which you’ll use to configure system limits in a later step. Learn more about Dash Enterprise permissions.

To create your Dash Enterprise user:

  1. If you’re still logged in to Keycloak with the initial admin user, log out and back in with the new admin user.

  2. Go to the realm responsible for Dash Enterprise users by selecting dash from the realm list in the top left corner.

    Dash realm

  3. Select Users > Add User.

  4. In Username, enter the username that you want to use when logging in to Dash Enterprise.
  5. Select Create. Additional settings become available.
  6. Go to Credentials.
  7. Select Set password.
  8. In Password and Password confirmation, enter the password you want to use.
  9. Select Save; then Save password to confirm.
  10. Assign the Dash Enterprise admin role:
    1. Go to Role mapping.
    2. Select Assign role.
    3. Change the filter to Filter by clients.
    4. Find and select the role called “dash admin”. Note that if you intend on deploying apps, you’ll also need the “dash licensed_user” role, and assigning this role consumes a license seat.
    5. Select Assign.

You can now log in to https://&lt;your-dash-enterprise-server&gt; using the credentials for the newly created Dash Enterprise user. Dash Enterprise opens to the Portal. Go to the App Manager by selecting Apps > App Manager.