Skip to main content
The following guide assumes the Platform Operator and ddlctl command line have already been installed.

​
Before you upgrade

​
Verify cluster health

Before starting a Domino upgrade, run the Domino Admin Toolkit to verify that the Domino instance is healthy. The Admin Toolkit deploys inside the Domino cluster and performs a series of checks to ensure that Domino services are operational. It also checks the cluster for known infrastructure bugs.

​
Back up Domino

Prior to the upgrade, we recommend that you back up your Domino to ensure that no data is lost during the upgrade process. Data loss only occurs in rare, catastrophic update failures. For information on how to run ad hoc backups of Domino, see run a manual Domino backup.

​
Check for drifted Helm releases

If you are upgrading from Domino 6.0.0 or later, check whether any Helm releases have drifted from their desired state prior to an upgrade. 
ddlctl get helmrelease -A --status stalled=true
These out of band changes are not natively supported via the Domino configuration. If for some reason they are required for your upgrade to succeed, make sure to account for them in your upgrade plan so those resources can be appropriately patched post upgrade.

​
Put Domino in maintenance mode

When only upgrading Domino versions, user executions can typically continue to run while the platform upgrades. However, user executions should be stopped to avoid losing work in the following cases:
  • Upgrading Kubernetes.
  • Upgrading from a Domino version earlier than 5.3.0.
Put Domino into maintenance mode to pause all user executions and resume them after upgrading. When upgrading, Domino recommends that you notify your users in advance about a maintenance window when the system will be unavailable.

​
Upgrade your infrastructure

If applicable, first upgrade your infrastructure to match the version of Domino you are upgrading to. This may involve:
  • Upgrading Kubernetes versions (refer to the Kubernetes compatibility table for supported Kubernetes versions).
  • Upgrading the Domino infrastructure.
Consult the documentation for your target cloud provider for instructions on how to upgrade your infrastructure:

​
Upgrade Domino while migrating to the platform operator

For those users who already have a Domino cluster but are upgrading to a version of the platform that uses the Platform Operator, the process is straightforward.

​
Upgrade your existing configuration

Previously this file was known as the domino.yml file, but as part of the transition to an operator-orchestrated deployment, this standalone file has been incorporated into the Domino custom resource definition in the .spec.config field. To prepare your existing configuration for the upgrade, you must feed the existing configuration file into the ddlctl command line so that it can migrate the configuration to the latest schema, populate any defaults, and potentially prompt you for any missing, required values.
Get the $FLEETCOMMAND_AGENT_TAG for your target release from the releases page.
When supplying a path to --from-file, make sure that it is relative to the current working directory. 
ddlctl create config --from-file domino.yml --agent-version $FLEETCOMMAND_AGENT_TAG
The upgraded configuration file will be created in the current directory with the name: 
config-$FLEETCOMMAND_AGENT_TAG.{timestamp}.yaml

​
Create the Domino custom resource

Once you are satisfied with the upgraded configuration file, you can create the Domino custom resource. This will get picked up by the Platform Operator which will then handle installation of all Domino components. 
ddlctl create domino --config config-$FLEETCOMMAND_AGENT_TAG.{timestamp}.yaml --agent-version $FLEETCOMMAND_AGENT_TAG
If you would prefer to just generate the Domino custom resource YAML, you can supply the --export flag and pipe the result to a file. When the upgrade completes successfully, you should see a message that says: 
2019-11-26 21:20:20,214 - INFO - fleetcommand_agent.Application - Deployment complete.
Domino is accessible at $YOUR_FQDN

​
Upgrade Domino when a Domino custom resource already exists

If you are comfortable modifying the upgraded configuration file as part of a single workflow, you can use the dedicated upgrade subcommand of ddlctl to perform an upgrade of Domino that sources the configuration to migrate from an existing Domino custom resource. 
ddlctl upgrade domino --agent-version $FLEETCOMMAND_AGENT_TAG
This will fetch the existing .spec.config from the Domino custom resource in your cluster, upgrade it to the latest schema, and open a text editor for you to review and/or modify the configuration file. Once saved, it will patch the Domino custom resource with the new configuration, agent data, and overall version information. This will transition into a live tail of the logs of the Domino agent as your cluster is upgraded.

​
Upgrade the configuration file by sourcing an existing Domino custom resource

You can upgrade the configuration file as a standalone operation, sourcing an existing Domino custom resource. 
ddlctl create config --from-domino --agent-version $FLEETCOMMAND_AGENT_TAG

​
Dry run an upgrade of Domino

Follow the same steps as above to upgrade your configuration. With an upgraded configuration file in hand, you can generate a Domino custom resource with the --export flag and pipe the result to a file. 
ddlctl create domino --config config-$FLEETCOMMAND_AGENT_TAG.{timestamp}.yaml --agent-version $FLEETCOMMAND_AGENT_TAG --export > domino-cluster.yaml
In the domino-cluster.yaml file, modify the spec.agent.spec to put the operator in a dry run mode. 
spec:
  agent:
    spec:
      dryRunMode: "true"
You can also edit the live domino resource to put it in this mode: 
kubectl edit domino -n domino-operator
Dry running an upgrade of Domino will report on the changes that will be made to the Domino cluster according to what is already represented in the Helm manifests in Helm storage.