Data Planes administration

A Data Plane is a compute location where Domino runs workloads. A Domino Nexus deployment can run several, in different regions or clouds. Manage all of them from the admin portal at Manage resources > Data Planes.

Register a Data Plane

Registration connects a Data Plane cluster that is already installed to your control plane, exchanging configuration data and cryptographic keys between the two. Contact your Domino Admin if you need help with the installation. Before you start, confirm you have admin access to the control plane and kubectl access to the Data Plane cluster.

In the admin portal, go to Manage resources > Data Planes > Register Data Plane, then set these fields:

Field	What it sets
Name	An arbitrary, human-readable name for the Data Plane.
Namespace	The Kubernetes namespace to install the Data Plane into on the Data Plane cluster. This namespace is created if it does not already exist.
Storage Class	The Kubernetes StorageClass name to use for execution volumes in this Data Plane. If blank, it defaults to the control plane’s storage class specified by the `com.cerebro.domino.computegrid.kubernetes.volume.storageClass` configuration record (default: `dominodisk`).
Data Plane Hostname	The subdomain component of the DNS name used for the Data Plane. If the control plane is `example.com` and the Data Plane is `dp.example.com`, enter `dp`. Append `:` and a port number if your Data Plane load balancer runs on a port other than 443. See Enable a Data Plane for Workspaces and Datasets.

Three more fields sit behind Advanced:

Advanced field	What it sets
Disable File Sync	Turns off Domino File System (DFS) file sync in this Data Plane. See Disable file sync.
Enable Istio	Indicates that Istio runs in this Data Plane’s cluster. Data Planes with Istio must have this set; setting the Helm value alone is not sufficient.
Override S3 Endpoint URL	Overrides the default S3 endpoint URL for this Data Plane.

Click Done.

Generate a Data Plane token

When registration is complete, create a bootstrap token:

In the admin portal, go to Manage Resources > Data Planes.
In the Actions column, click Setup for the Data Plane you are registering.
Click Load bootstrap token.
When the token loads, click Copy token.

The token is valid for 10 minutes. If you exceed the 10 minute window, load a new token through the same steps.

Run the bootstrap script

Make sure your default Kubernetes context is the cluster you want to deploy the Data Plane into.

Obtain the Kubernetes context of the Data Plane:

tsh login && tsh kube login <dp-deploy-id>

Download the bootstrap-data-plane.sh script from the Nexus repository on GitHub and save it as an executable file:

curl -Sso bootstrap-data-plane.sh \
  https://raw.githubusercontent.com/dominodatalab/nexus/refs/heads/main/bootstrap-data-plane.sh && \
  chmod +x bootstrap-data-plane.sh

Run the script, replacing <token> with the token you copied:
./bootstrap-data-plane.sh <token>

The script reports that it created a secret and exits. The Data Plane becomes healthy in the admin portal within a couple of minutes.

Verify the registration

In the admin portal, go to Manage resources > Data Planes and confirm the Data Plane reports Healthy. From the Data Plane cluster, confirm every node is Ready and every pod is Running or Completed:

kubectl get nodes
kubectl get pods -n domino-compute

Troubleshoot the registration

The token expired

The bootstrap token is valid for 10 minutes. If more time passed between copying it and running the script, load a new token and run the script again.

The Data Plane stays unhealthy

Read the agent logs, which name the reason the agent has not completed its handshake:

kubectl logs -n domino-compute -l app.kubernetes.io/name=data-plane-agent

The keys expired after a long outage

A Data Plane that stayed offline for more than 4 days can have expired security keys. Force a re-bootstrap:

./bootstrap-data-plane.sh --force <token>

Only use --force when the agent logs report key expiration. If they report waiting..., run the script without it.

Never delete or modify the data-plane-config or data-plane-config-extra ConfigMaps. Recovering a Data Plane after either one is lost is extremely difficult.

Enable a Data Plane for Workspaces and Datasets

Workspaces need a direct connection from the user’s browser to the Data Plane, so a Data Plane that serves interactive workloads needs its own hostname, load balancing, and TLS.

Configure the hostname

Serve the Data Plane from a subdomain of the domain used for the control plane. If users connect to Domino at example.com, then Data Planes must be served from data-plane.example.com.

Configure load balancing

Resolve that hostname to a load balancer that routes traffic to port 8080 on pods with this label selector:

app.kubernetes.io/component: auth-proxy
app.kubernetes.io/instance: auth-proxy
app.kubernetes.io/name: auth-proxy

Use a NodePort service plus a load balancer on-premises, or a LoadBalancer service type in the major cloud providers.

Configure TLS

Users must connect to Data Planes over TLS (HTTPS). If a load balancer routes traffic to the Data Plane, the simplest option is to configure that load balancer to serve valid TLS certificates for the domain. To serve certificates that you provide from the Data Plane itself:

Create a Kubernetes secret containing the certificates:

kubectl create secret tls custom-certs -n <data plane namespace> --cert=<cert file> --key=<key file>

Set this value when you deploy the Data Plane Helm chart:

--set auth-proxy.config.nginx.tlsSecretName=custom-certs

Configure Datasets

Datasets on a remote Data Plane need the volume operator and the filetask operator enabled under release_overrides in the Data Plane’s configuration file. Ask your Domino Admin to apply these if you do not manage that file:

release_overrides:
  data-plane:
    chart_values:
      enable_volume_operator: true
      enable_filetask_operator: true

Edit a registered Data Plane

Go to Manage resources > Data Planes, click the three-dot menu next to the Data Plane, and select Edit. What you can change varies by field:

Field	What changing it means
Name	Change it freely. Tell your users, since they select Data Planes by name.
Namespace	Migrating a Data Plane to a new namespace is technically possible but not generally supported. Contact Domino for support.
Storage Class	Does not affect running executions, but applies to new ones. This can disrupt existing Workspaces.
Hostname	Affects running executions. Re-run the registration setup for the Data Plane, then restart the `auth-proxy` pod in the Data Plane namespace.
Disable File Sync	Change it at any time. It applies to newly launched workloads.
Enable Istio	Enabling or disabling Istio support on an existing Data Plane is possible but not trivial. Contact Domino for support.

Disable file sync

When data must not leave a specific Data Plane, disable file sync on it to prevent anyone pushing data from that Data Plane to the control plane or to another Data Plane. On a Data Plane with file sync disabled:

Users can pull Project files.
Users can pull and push any mounted Git repositories.
Users cannot push changes to the Domino File System (DFS). Domino warns before starting an execution that cannot push to DFS, and the job history records that no artifacts or output files were captured because the execution ran in a restricted Data Plane.

To disable file sync:

In the admin portal, go to Manage resources > Data Planes.
Click the three-dot menu next to the Data Plane and click Edit.
Click Advanced.
Select Disable File Sync, then click Save.

Hardware Tiers for Data Planes

Hardware tiers are how users reach a Data Plane. Every hardware tier is assigned to one Data Plane, so granting a user access to a hardware tier grants them access to run workloads on that Data Plane with the resources the tier defines. Create and restrict those tiers from Manage a hardware tier, which covers the Data Plane field on the tier form, the node labels a Data Plane’s nodes need, and how to limit a tier to specific organizations.

Upgrade a Data Plane

Keep your remote Data Planes in sync with the control plane to maintain compatibility and access new features. A Data Plane upgrade replaces the fleetcommand-agent and Domino services running in the Data Plane cluster. On Domino Cloud, most Data Plane upgrades run from the admin portal. If the UI Upgrade action is unavailable for your Data Plane, Domino Support performs the upgrade for you.

Before you start

The control plane must already be running the target version. Running a Data Plane newer than its control plane is not supported.
Check version compatibility below.
Notify users in the affected regions about a maintenance window. Ongoing executions can typically continue, but stopping them avoids lost work if reconciliation surfaces an issue.

Version compatibility

Starting with Domino 6.1, control planes and Data Planes are compatible across two regular releases. A control plane is compatible with the current and one past regular release of the Data Plane. For instance, control plane 6.2.x is compatible with Data Planes 6.2.x and 6.1.x.

Upgrade the control plane before any Data Plane. Running a Data Plane version newer than the control plane is not supported.

When a Data Plane’s version falls outside that range, the admin portal reports it:

Status	What it means
Degraded	The Data Plane runs an older version. New executions are not permitted until you upgrade it.
Error	Communication between the Data Plane and the control plane is failing.
Disconnected	The Data Plane is not reachable.

Upgrade from the UI

Use the Domino UI when the Upgrade action is available. The action requires both planes to be running Domino 6.1.2 or later, and the Data Plane to have online access to the deployment artifacts.

In the admin portal, go to Manage resources > Data Planes.
Identify the Data Plane that needs an upgrade by looking for a status message indicating “Data Plane is running an older version” or “Data Plane is running a different version”.
Click the three vertical dots next to the Data Plane.
Select Upgrade from the dropdown menu.

The control plane instructs the Data Plane’s operator to reconcile against the target version. Any release_overrides set on the Data Plane’s Domino custom resource are preserved.

When the UI upgrade is unavailable

The Upgrade option is greyed out when the Data Plane already matches the control plane’s version, when it runs 6.1.0 or 6.1.1, or when the upgrade path is not supported from the UI. Contact the Domino Support team. They coordinate the manual upgrade against your Data Plane cluster. Have the following ready when you file the request:

The Data Plane’s current version and the target version.
Whether the Data Plane cluster is air-gapped.
Any release_overrides currently applied to the Data Plane. These live under .spec.config.release_overrides on the Data Plane’s Domino custom resource and are preserved across upgrades, but Support may need to review them for schema changes.

About `release_overrides`

release_overrides live under .spec.config.release_overrides on the Data Plane’s Domino custom resource. They override Helm chart values for the services that the fleetcommand-agent deploys into the Data Plane. A typical shape, adding CPU requests and limits to a service:

spec:
  config:
    release_overrides:
      domino-connect:
        chart_values:
          resources:
            requests:
              cpu: "2"
            limits:
              cpu: "4"

Both the UI Upgrade button and Support-driven upgrades read the existing .spec.config, so overrides remain in place across upgrades. There is no need to re-apply them from scratch.

Starting with the Helm 4 upgrade, chart values are applied to Kubernetes with server-side apply, so any mistyped or invalid field in release_overrides now fails the upgrade instead of being silently ignored. If you want to add or change an override, work with Domino Support to validate the shape before the upgrade runs.

Verify the upgrade

In the admin portal, go to Manage resources > Data Planes and confirm the Data Plane is marked Healthy and its reported version matches the target.
Start a Workspace or run a job pinned to this Data Plane to confirm Workspace connectivity, ingress, and any hardware tiers still behave as expected.
If Domino Support drove the upgrade, confirm with them that no HelmRelease resources landed in a stalled state during reconciliation.

If the Data Plane is unhealthy after the upgrade, read the data-plane-agent logs and, if they report expired keys, re-bootstrap it. See Troubleshoot the registration for both commands.

Monitor a Data Plane

Check a Data Plane’s health, and see which Kubernetes nodes, user executions, and Workspaces are running in it, from the admin portal:

To see	Go to	Where the Data Plane appears
Data Plane health	Manage resources > Data Planes	The status marks a Data Plane Healthy when it is available for use.
Kubernetes nodes across all your clusters	Reports > Infrastructure	The column on the right indicates the Data Plane that each node is in.
All running user executions	Reports > Executions	The rightmost column indicates the Data Plane for the execution.
All durable Workspaces, running and stopped	Reports > Workspaces	The rightmost column indicates the Data Plane for the Workspace.

Data Plane health is a simple check that the Data Plane is contactable. If a Data Plane indicates Error, Disconnected, or Degraded, communication between the Data Plane services and the control plane may have a problem. Contact Domino for help troubleshooting.

Some of the node detail views are not yet implemented for nodes in remote Data Planes.

Archive a Data Plane

Archiving a Data Plane effectively deletes it. An archived Data Plane cannot be un-archived.

Stop all executions in the Data Plane.
Delete all Workspaces in the Data Plane.
Archive all hardware tiers in the Data Plane.
In the admin portal, go to Manage resources > Data Planes.
Click the three-dot menu next to the Data Plane and select Archive.
Click Archive Data Plane.
Use Helm to delete the data-plane release in the Data Plane namespace on the Data Plane Kubernetes cluster.

Architecture & deployment

Identity & access

Infrastructure & compute

Platform configuration

Data administration

Operations, monitoring & cost

Security & compliance

Data Planes administration

Register a Data Plane

Verify the registration

Troubleshoot the registration

Enable a Data Plane for Workspaces and Datasets

Configure the hostname

Configure load balancing

Configure TLS

Configure Datasets

Edit a registered Data Plane

Disable file sync

Hardware Tiers for Data Planes

Upgrade a Data Plane

Before you start

Version compatibility

Upgrade from the UI

When the UI upgrade is unavailable

About `release_overrides`

Verify the upgrade

Monitor a Data Plane

Archive a Data Plane

​Register a Data Plane

​Verify the registration

​Troubleshoot the registration

​Enable a Data Plane for Workspaces and Datasets

​Configure the hostname

​Configure load balancing

​Configure TLS

​Configure Datasets

​Edit a registered Data Plane

​Disable file sync

​Hardware Tiers for Data Planes

​Upgrade a Data Plane

​Before you start

​Version compatibility

​Upgrade from the UI

​When the UI upgrade is unavailable

​About release_overrides

​Verify the upgrade

​Monitor a Data Plane

​Archive a Data Plane

​Related

Register a Data Plane

Verify the registration

Troubleshoot the registration

Enable a Data Plane for Workspaces and Datasets

Configure the hostname

Configure load balancing

Configure TLS

Configure Datasets

Edit a registered Data Plane

Disable file sync

Hardware Tiers for Data Planes

Upgrade a Data Plane

Before you start

Version compatibility

Upgrade from the UI

When the UI upgrade is unavailable

About `release_overrides`

Verify the upgrade

Monitor a Data Plane

Archive a Data Plane

Related