Prepare for the upgrade
To run the Sitecore container upgrade process, you must prepare the following requirements:
-
Download and extract the Sitecore Container Deployment package for the relevant version of Sitecore XP.
This package contains the Sitecore upgrade Docker Compose files and Sitecore Kubernetes specification files for each Sitecore topology.
-
Specify the environment variables.
-
Prepare the Sitecore license file.
-
If you are upgrading from Sitecore XP 9.3.0 – 10.0.X:
On the Sitecore instance that you are upgrading from, go to the Sitecore Launchpad, select Control Panel, and in the Database section, select Clean up databases.
The environment variables
The environment variables are the preferred mechanism for passing the configuration settings into the Sitecore upgrade container.
The environment variables in Docker Compose
The environment variables for Docker Compose are stored in the environment variable configuration file – upgrade.env. Docker Compose loads these variables automatically during startup.
Before you deploy the Sitecore upgrade container, you must specify all the environment variables with the required values.
For a complete list of Docker env variables and more information about the individual variables, see Appendix C – The environment variables list.
All the environment variables must fit in the upgrade.env file, in a single 32,767character block. If the total size of the variables exceeds this size, you will be unable to set new values and the databases will not be upgraded successfully.
To reuse environment variables across multiple environments, you should consider setting environment variables on the host Windows OS and removing the corresponding keys from the environment variable configuration file used by Docker Compose.
Kubernetes configuration
The Sitecore upgrade Kubernetes deployment uses secrets to securely store the strings that are used by the container in the Kubernetes cluster.
The secrets are used to store the SQL Server user name and password, the Sitecore license, and so on.
The Kubernetes configuraton also includes ConfigMap values such as the SQL server address and the prefix of the Sitecore databases which are required for the upgrade container.
Before you deploy the Sitecore upgrade container to the Kubernetes cluster, you must update the secrets and ConfigMap values in the configuration text files with the required values.
For a complete list of the secrets and the ConfigMap values see Appendix B – The Kubernetes secrets list.
We provide a Kubectl kustomization.yaml file that deploys all the secrets and the ConfigMap values in a single command.
The Sitecore license file
The Sitecore license file is typically passed to the container instances as an environment variable in encoded string form. The Sitecore license file is very large. You must therefore compress and Base64 encode it to ensure that it conforms with the maximum size allowed by Windows for all the environment variables.
When you have compressed and encoded the license file, copy the string value to the Docker environment variable configuration file or copy the string value to the license secret text file – sitecore-license.txt – depending on which orchestrator you choose for the upgrade container.
Appendix A – License file compression and encoding PowerShell helper function contains a sample PowerShell script that converts a license file into a Base64 compressed string for use in an environment variable.