|
Important
| The following guide assumes the Platform Operator and ddlctl command line have already been installed. |
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=trueThese 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:
-
AWS: Follow the instructions in the AWS documentation.
-
GCP: Follow the instructions in the GCP documentation.
-
Azure: Follow the instructions in the Azure documentation.
-
Tanzu: Follow the instructions in the Tanzu documentation.
-
OpenShift: Follow the instructions in the OpenShift documentation.
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.
|
Note
|
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_TAGThe upgraded configuration file will be created in the current directory with the name:
config-$FLEETCOMMAND_AGENT_TAG.{timestamp}.yamlCreate 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_TAGIf 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_FQDNIf 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_TAGThis 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.
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_TAGFollow 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.yamlIn 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-operatorDry 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.