Description

The end of life of Azure Kubernetes Service (AKS) 1.24 is July 2023. Sitecore Managed Cloud Containers solutions based on AKS 1.24 must be updated to a newer version that uses AKS 1.25. For more details on AKS's end of life and the consequences of deprecation, refer to Microsoft's FAQ.

The following article contains upgrade instructions for the Sitecore Managed Cloud Containers solution to the version that uses AKS 1.25.

Important:

• Upgrade your solution only if its product version (revision number) is earlier than those of the update packages listed in the Upgrade Instructions sections below.
  For example, the update package revision: mcc.xp.upgrade.10.1.1-r.0.1.309915.nupkg.
  To locate the version and revision number of your solution, view the solution.json file in the infrastructure repository of your Sitecore Managed Cloud Containers Azure DevOps project.
• If your environment is still running on AKS 1.23, it is recommended to first upgrade to AKS 1.24 and then follow the steps in this article.

Breaking Changes

Upgrading the AKS version from 1.24 to 1.25 introduces some breaking changes:

• The Azure public IP should be recreated, due to an update in terraform syntax for the Azure public IP module. To accomplish this, the IP should be temporarily unbound from the Azure Front Door (AFD).
• For Windows node pools on Sitecore v. 10.2 and v. 10.3, the node OS by default uses GA Windows Server 2022 OS image. As a result of the upgrade process for Sitecore 10.2 and 10.3 environments, the node pools are switched from Windows 2019 to Windows 2022.
• If custom images for containers are being used, ensure these images are updated and rebuilt for support running on Windows Server 2022 node pool.
• If v. 10.1.0 – v. 10.1.2 are being used, Windows Server 2019 is retained. This is because older versions remain supported for use on Windows Server 2019 node pools for the next AKS version until Microsoft deprecates the Windows 2019 node pool image. These versions are not supposed to be updated to support the new Microsoft Windows 2022 GA image. Therefore, before Microsoft completely deprecates Windows 2019, it is highly recommended that customers upgrade to the latest Sitecore version.

Note: For Sitecore v. 10.1 – v. 10.3, downtime might occur during the upgrade process.

Upgrade Instructions for Sitecore v. 10.1.0 – v. 10.1.2

The following charts depict the various branches that should be created and the pipelines that should be run during the upgrade process.

No disaster recovery / basic cold disaster recovery

With managed hot disaster recovery

 

To perform the upgrade:

1. Download an upgrade package for the required topology and version from the storage. This is a list of available upgrade packages:
   
   • Sitecore 10.1.0 solution versions:
     • mcc.xp.upgrade.10.1.0-r.0.1.321601.nupkg
     • mcc.xm.upgrade.10.1.0-r.0.1.321601.nupkg
   • Sitecore 10.1.1 solution versions:
     • mcc.xp.upgrade.10.1.1-r.0.1.321602.nupkg
     • mcc.xm.upgrade.10.1.1-r.0.1.321602.nupkg
   • Sitecore 10.1.2 solution versions:
     • mcc.xp.upgrade.10.1.2-r.0.1.321603.nupkg
     • mcc.xm.upgrade.10.1.2-r.0.1.321603.nupkg
2. Download the AKS-125-upgrade-preparation.zip package from the storage.
3. Create a new temporary branch of the Infrastructure master branch. This branch is referred to as the upgrade-preparation branch in subsequent steps.
   Note: This branch must be created from the existing master branch without the upgrade package applied.
4. Copy the contents of the Infrastructure folder from AKS-125-upgrade-preparation.zip to the upgrade-preparation branch.
5. Commit the changes to the temporary branch but do not merge.
6. Create a new upgrade-preparation pipeline in your organization using the upgrade-preparation branch (the Infrastructure repository) and the \pipelines\prepare-mcc-upgrade.yaml file.
7. Run the upgrade-preparation pipeline using the upgrade-preparation branch.
8. The temporary upgrade-preparation pipeline and branch can now be deleted.
9. Install the upgrade package to the Infrastructure repository only, according to the guidelines for Sitecore 10.2.
10. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • Download the AKS-125-upgrade-for-env-with-DR-Managed-Hot.zip package from the storage.
    • Extract and copy the file from the downloaded package to the Infrastructure repository (pipelines folder).
11. Merge updates into the Infrastructure repository via Pull Request (PR) and ensure that the Infrastructure pipeline runs successfully.
12. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • In the Azure Portal, navigate to the Secondary Resource Group (<infraID>draks) and get the Secondary IP address (<infraID>driip).
    • In the Infrastructure repository, navigate to infrastructure\frontdoor\backend-config.json. Using the Secondary IP address, update all backends with priority 2 and commit the changes.
13. Run the Frontdoor pipeline.
14. Create a new temporary branch of Application repository for the upgrade-preparation pipeline.
    Note: This branch should be created from the existing master branch without the upgrade package applied.
15. Copy the contents of the application/v10-10.1/* folder from the AKS-125-upgrade-preparation.zip package downloaded earlier, to the root of the Application repository.
16. Commit the changes to the temporary branch but do not merge.
17. Create a new upgrade-preparation pipeline in your organization using the temporary branch and the application\pipelines\application-upgrade-preparation.yaml file.
18. Run the upgrade-preparation pipeline, as follows:
    Use the sitecore_role_pattern_match parameter to ensure the pipeline selects the correct role. The default pattern is sitecore-*.
    
    Note: The upgrade preparation depends on the Sitecore ansible role. Modification of the folder structure for that role might cause a failure.
19. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • Create a new dr-upgrade-preparation pipeline in your organization using the temporary branch and the application\pipelines\dr-application-upgrade-preparation.yaml file.
    • Run the dr-upgrade-preparation pipeline, as follows:
      Use the sitecore_role_pattern_match parameter to ensure the pipeline selects the correct role. The default pattern is sitecore-*.
      
      Note: The upgrade preparation depends on the Sitecore ansible role. Modification of the folder structure for that role might cause a failure.
20. The temporary upgrade-preparation pipeline and branch can now be deleted.
21. Install the upgrade package to the Application repository, according to the guidelines for Sitecore 10.2.
    
    • The upgrade can be merged immediately.
    • The Application pipeline should be triggered automatically.
22. Run the check cluster upgrades pipeline.
23. Run the cluster version upgrade pipeline. Select the latest available patch version received from the check cluster upgrades pipeline (Kubernetes_version 1.25.*).
24. If the environment uses DR Managed Hot, run the dr cluster version upgrade pipeline. Select the latest available patch version received from the check cluster upgrades pipeline (Kubernetes_version 1.25.*).

Upgrade Instructions for Sitecore v. 10.2 and v. 10.3

The following charts depict the various branches that should be created and the pipelines that should be run during the upgrade process.

No disaster recovery / basic cold disaster recovery

With managed hot disaster recovery

 

Important:

• If any custom Windows images are being used in the deployment, they must be rebuilt using ltsc2022 as the OS version.

To perform the upgrade:

1. Download an upgrade package for the required topology and version from the storage. This is a list of available upgrade packages:
   
   • Sitecore 10.2.0 solution versions:
     • mcc.xp.upgrade.10.2.0-r.0.1.321604.nupkg
     • mcc.xm.upgrade.10.2.0-r.0.1.321604.nupkg
   • Sitecore 10.3.0 solution versions:
     • mcc.xp.upgrade.10.3.0-r.0.1.321605.nupkg
     • mcc.xm.upgrade.10.3.0-r.0.1.321605.nupkg
2. Download the AKS-125-upgrade-preparation.zip package from the storage.
3. Create a new temporary branch of the Infrastructure master branch. This branch is referred to as the upgrade-preparation branch in subsequent steps.
   Note: This branch must be created from the existing master branch without the upgrade package applied.
4. Copy the contents of the Infrastructure folder from AKS-125-upgrade-preparation.zip to the upgrade-preparation branch.
5. Commit the changes to the temporary branch but do not merge.
6. Create a new upgrade-preparation pipeline in your organization using the upgrade-preparation branch (the Infrastructure repository) and the \pipelines\prepare-mcc-upgrade.yaml file.
7. Run the upgrade-preparation pipeline using the upgrade-preparation branch.
8. The temporary upgrade-preparation pipeline and branch can now be deleted.
9. Install the upgrade package to the Infrastructure repository only, according to the guidelines for Sitecore 10.2, but do not merge to master.
10. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • Download the AKS-125-upgrade-for-env-with-DR-Managed-Hot.zip package from the storage.
    • Extract and copy the file from the downloaded package to the Infrastructure repository (pipelines folder).
11. Merge updates into the Infrastructure master branch via Pull Request (PR) and ensure that the Infrastructure pipeline runs successfully.
    Note: The Infrastructure pipeline should be triggered automatically.
12. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • In the Azure Portal, navigate to the Secondary Resource Group (<infraID>draks) and get the Secondary IP address (<infraID>driip).
    • In the Infrastructure repository, navigate to infrastructure\frontdoor\backend-config.json.
    • Using the Secondary IP address, update all backends with priority 2, and commit the changes.
13. Run the Frontdoor pipeline.
14. Run the check cluster upgrades pipeline.
15. Perform the following steps:
    
    • Run the cluster version upgrade pipeline. Select the latest available patch version received from the check cluster upgrades pipeline (Kubernetes_version 1.25.*).
    • Clear the check box next to Disable Step to Create Temporary Nodepools.
      
16. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • Run the dr cluster version upgrade pipeline. Select the latest available patch version received from the check cluster upgrades pipeline (Kubernetes_version 1.25.*).
    • Clear the check box next to Disable Step to Create Temporary Nodepools.
      
17. Re-run the Infrastructure pipeline, which recreates correct nodepools with correct OS versions.
18. Create a new branch of the Application master branch. This branch is referred to as the upgrade branch in subsequent steps.
    Install the upgrade package for the Application repository, according to the guidelines for Sitecore 10.2, but do not merge to the master.
19. Change container image versions in the upgrade branch, as follows:
    
    • Update the config/docker-images/docker-images.json file:
      
      • For any default Sitecore images, replace ltsc2019 with ltsc2022.
      • For the windowsservercore image, replace 1809 with ltsc2022.
      • For custom images, use the tag ltsc2022.
    • Update solr-init and mssql-init images to ltsc2022 under the path roles/sitecore-[your_topology]/overlays/init.
      
    • In case of using XP topology, check the following files for powershell:lts-nanoserver-1809 and replace it with powershell:lts-nanoserver-ltsc2022.
      
      • platform-artifacts\kustomization.yaml
      • platform-artifacts\cd.yaml
      • platform-artifacts\cm.yaml
      • platform-artifacts\cortexprocessingworker.yaml
      • platform-artifacts\prc.yaml
      • platform-artifacts\xdbautomation.yaml
      • platform-artifacts\xdbautomationworker.yaml
20. Create a new temporary branch of the upgrade for the upgrade-preparation pipeline. This branch is referred to as the upgrade-preparation in subsequent steps.
21. Copy the content of the application/v10.2-10.3/* folder from the AKS-125-upgrade-preparation.zip package downloaded earlier, to the upgrade-preparation branch.
22. Commit the changes to the upgrade-preparation branch but do not merge.
23. Create a new upgrade-preparation pipeline in your organization using the upgrade-preparation branch (Application repository) and the \pipelines\application-upgrade-preparation.yaml file.
24. Run the upgrade-preparation pipeline, using the upgrade-preparation branch:
    Use the sitecore_role_pattern_match parameter to ensure the pipeline selects the correct role. The default pattern is sitecore-*.
    
    Note: The upgrade preparation depends on the Sitecore ansible role. Modification of the folder structure for that role might cause a failure.
25. If the environment uses DR Managed Hot, complete the following additional steps. Otherwise, proceed to the next numbered step.
    
    • Create a new dr-upgrade-preparation pipeline in your organization using the upgrade-preparation branch and the application\pipelines\dr-application-upgrade-preparation.yaml file.
    • Run the dr-upgrade-preparation pipeline, as follows:
      Use the sitecore_role_pattern_match parameter to ensure the pipeline selects the correct role. The default pattern is sitecore-*.
      
      Note: The upgrade preparation depends on the Sitecore ansible role. The modification of the folder structure for that role might cause a failure.
26. The temporary pipeline and branch can now be deleted.
27. Merge the upgrade branch to the master. The Application pipeline should be triggered automatically.

Troubleshooting

If the cluster version upgrade pipeline fails due to timeout, a restart will enable it to complete successfully.