Description

Sitecore Managed Cloud Containers solutions that use NGINX as the ingress controller can be migrated to Traefik as part of the MCC 2.13.0 upgrade.

This article describes how to migrate an existing Sitecore Managed Cloud Containers environment from NGINX to Traefik while minimizing downtime during the transition.

Upgrade Instructions

Follow these steps to migrate an existing Sitecore Managed Cloud Containers environment from NGINX to Traefik:

1. In the mcc-upgrades container of the mccsharedupgradestorage storage account, locate the upgrade package that matches the environment.
2. Download the applicable .nupkg package containing the Traefik upgrade.
3. Extract the package by running the following command:

   tar -zxvf mcc.{topology}.upgrade.{version}-{package-number}.nupkg

4. Clone the infrastructure and application repositories into separate folders.
5. Merge the contents of the extracted infrastructure and application folders into the corresponding cloned repositories.
   For example:

   cp -r {package/infrastructure/} {environment-infrastructure}

6. If Disaster Recovery is not enabled, push the changes to the infrastructure and application repositories. Otherwise, follow the applicable Cold or Hot Disaster Recovery instructions provided later in this procedure.
7. After pushing the changes from the package, manually apply the following updates and complete the corresponding pull requests:
   1. In infrastructure repository add these updates and run the infrastructure pipeline if not started automatically:
      
      Code to be added:

      resource "azurerm_key_vault_secret" "frontdoor_name" {
        name         = "frontdoor-name"
        value        = local.frontdoor_name
        key_vault_id = data.azurerm_key_vault.this.id
      }
      resource "azurerm_key_vault_secret" "frontdoor_id" {
        name         = "frontdoor-id"
        value        = azurerm_cdn_frontdoor_profile.this.resource_guid
        key_vault_id = data.azurerm_key_vault.this.id
      }

   2. After the infrastructure pipeline runs, run the frontdoor pipeline so that the values of the frontdoor secrets are updated in the infrastructure repository.

      If the pipeline fails, the failure might be related to a Microsoft change affecting how Front Door retrieves secrets from Key Vault. Apply the following changes:

      1. Enable Frontdoor System Assigned Identity:
         
      2. Add the required change to the frontdoor/standard/main.tf file in the infrastructure repository:
         
   3. In the application repository, add the applicable update as below.
      
      The application pipeline starts automatically and is expected to fail while Traefik remains in the pending state.
   4. If the environment serves multiple hostnames for the same role, update the collection reference in requirements.yaml as follows:

      collections:
        - name: sitecore/managedcloud/sitecore-managedcloud-0.0.660805.tar.gz

      Then, follow the steps in the Configure additional hostnames for Traefik to register the environment’s existing hostnames so that the hostnames continue working with Traefik.

      Note: This step applies only when additional domains have been added in Front Door and additional managed websites have been configured in the Sitecore.config file.

8. If Cold Disaster Recovery is enabled, revert the changes that remove the hadr and dr configuration:
   1. In the infrastructure repository, revert the applicable changes in solution.json file, merge the pull request, and run the infrastructure pipeline if the pipeline does not start automatically.
      
   2. In the application repository, revert the applicable changes and merge the pull request:
      
      
9. If Hot Disaster Recovery is enabled, revert the changes that remove the Disaster Recovery configuration:
   1. In the infrastructure repository, revert the applicable changes in solution.json file, merge the pull request, and run the infrastructure pipeline if the pipeline does not start automatically:
      
   2. In the application repository, revert the changes that remove the Disaster Recovery configuration in:
      • pipelines/templates/application.yaml
      • pipelines/application.yaml
10. In the Azure portal, navigate to the environment’s resource group and open the Kubernetes service. Under Settings, select Security configuration.
11. Under Authentication and Authorization, edit the chosen groups and add a group that includes the current user as a member. Tick the Kubernetes local accounts check box, and then click Apply. This provides access to edit the Kubernetes Namespaces required in the following steps.
    
12. Wait for the application pipeline to fail. During this stage, nginx_ingress and traefik exist simultaneously. Because nginx is trying to get the same public IP address, traefik remains in the Pending state.
13. To resolve this issue:
    1. Navigate to the {resource-group-id}aks resource group.
    2. Create a new Public IP Address resource.
    3. Associate the new public IP address with the AKS resource type Kubernetes, selecting the *aks resource group id.
    4. Return to the services and select nginx-ingress.
    5. Edit the nginx-ingress YAML file. In the loadBalancerIP setting, replace the existing public IP address with the newly created public IP address.
    6. Run the application pipeline again.
    After the application pipeline runs:
    • Traefik uses the original nginx public IP address.
    • NGINX uses the newly created public IP address.
    The expected downtime during this transition is approximately less than 30 seconds.
    Note: For an environment that uses Hot Disaster Recovery, perform these actions in both the primary and Disaster Recovery resource groups.
14. Verify that all Sitecore sites are running by accessing the following URL: https://{resource-group-id}-{topology}.sitecoretest.com
15. Verify that all custom sites route traffic through Traefik and no longer use NGINX. NGINX namespace need to be deleted completely if it needed to be removed.

The migration is complete when all standard and custom sites are running and traffic passes through Traefik.

Configure Additional Hostnames for Traefik

Under NGINX, multiple public hostnames can share the same Content Delivery or Content Management role without additional configuration. NGINX dynamically forwards the original request hostname to the back end.

Traefik requires each additional hostname to be registered explicitly. Otherwise, Traefik cannot forward a runtime hostname to the back end if the hostname has not been preconfigured.

For hostnames that were previously configured and working with NGINX, the following configuration should already be available and does not need to be recreated:

• A Front Door custom domain for each hostname, associated with the applicable role route.
• A DNS record that points each hostname to the Front Door endpoint.
• A matching <site hostName="..."> definition in the Sitecore configuration included in the CM or CD image.

To configure the existing additional hostnames for Traefik:

1. In the application repository, register each existing additional hostname in the environment-specific config/ingress/additional-hostnames.yamlfile.
2. Run or rerun the application pipeline.

   The ingress-configuration Ansible role reads the file automatically and creates the corresponding Traefik Middleware/Rule for each hostname. No manual kubectl changes are required.

   If the configuration is added while completing step 7 of the Upgrade Instructions, a separate application pipeline run is not required.

3. Access each registered hostname and verify that the correct Sitecore site is resolved.

Rollback Instructions

If an issue occurs during the migration, perform these steps:

1. Open the application repository pull request that introduced the Traefik changes.
   
2. Revert the pull request.
3. Complete the new pull request.
4. The application pipeline runs and restores the NGINX namespace and its services. The pipeline also removes Traefik and returns the environment to its previous state.
5. Repeat the rollback steps for the infrastructure repository.
6. After approximately three minutes, verify that the Sitecore sites are running correctly through NGINX.

The rollback is complete when the Sitecore sites are accessible and the environment is operating through NGINX.