Run Update images pipeline

Abstract

Update images pipeline to deploy new and update existing Managed Cloud Premium container images.

In the Update images pipeline, you can update image references for Sitecore application services, such as CM, CD, ID, and PRC, and additional application services depending on the selected topology or as provided by customer service.

To update your Sitecore images, or your other service image references:

  1. Check that the image you are updating is already located in the Azure Container Registry (ACR).

  2. In Azure DevOps go to Pipelines section in the left-hand nav, click the All tab, and select update images link from the available list of pipelines.

  3. If this is your first time running the pipeline, click Run pipeline. This opens the Run pipeline dialog.

  4. In the Run pipeline dialog check that the Branch/tag field is set to main.

  5. Go to your container registry and copy the path from the Login server parameter field in the Essentials section.

    • To update the Sitecore application reference:

      In the update images Run pipeline dialog, add the new path in the related field for each Sitecore application image reference you are updating. For example, for CM, update the path in the Sitecore CM Image Path field.

    • Enter NA for those Sitecore application references that are not being updated.

  6. For your service image references other than sitecore images:

    a. Add the image name beside the Name parameter that matches an existing image reference that you want to update, or a new one that you want to deploy.

    b. Enter a path in the Path parameter that references the image in the ACR with the appropriate tag.

    Example with one custom service image showing the name and path parameters in the Other Service Images field.

    c. You can continue to add multiple image references in the Other Service Images field following the schema:

    • Name: <image name>

    • Path: <image ACR path>

    Example with several custom service images showing several name and path parameters in the Other Service Images field.
  7. Click Run.

When the Update images pipeline is run a series of steps are executed. 

As it goes through each step of the pipeline, the output verifies that it is successful or provides error information to help you troubleshooting the issue.

To run and validate the pipeline:

  1. Use the output from the Update docker images configuration and complete pull request step to check for issues with the new path, and to get a confirmation that the image references path will be updated.

    In the following example, the pipeline correctly recognizes that the [cortexprocessingworker] image was not found in the ACR and an error is thrown.

    Pipeline code example.

    To resolve the issue:

    1. Verify the path and ensure that the image is uploaded to the ACR with the correct tag.

    2. When you have verified, run the pipeline again.

  2. The output from the Update docker images configuration and complete pull request step verifies that there are no issues with the image references update and proceed to the 020 Update docker images configuration and complete pull request step. When the image references are updated successfully, the pipeline creates and completes the pull request (PR) for the changes. 

    The step output below shows that the image references update is confirmed and the pipeline has created and completed the PR.

    Pipeline code example.
  3. After the update images pipeline completes the run and completes the PR, the continuous integration (CI) run is triggered automatically for the application pipeline to run and deploy images to Kubernetes. 

    The following image shows that the CI run is triggered for the application pipeline after the PR completes, as part of the update images pipeline run.

    THe CI run.

The Image updates pipeline enables you to promote changes between environments. For example when you make changes to your Pre-PROD environment and have tested them, you can push the modifications into PROD.

To promote changes between environments:

  1. Push image to the ACR.

    ACR is shared and used between various deployments sharing the same agreement.

  2. In your preproduction environment, run the Update images pipeline, as outlined in the previous steps to update the Docker configuration and to deploy a container application service in your Azure Kubernetes Service (AKS).

  3. Validate the changes and ensure that everything is working as expected in the preproduction environment.

  4. Run the Update images pipeline in the production environment.

    Because ACR is shared, there is no need to push images again to apply the same changes for production. The container application services are deployed into your AKS.

You can also integrate your CI/CD workflows and trigger Update Images pipeline as part of it, automatically. This procedure describes how to trigger the pipeline and provides the required parameters via an API call.

As a prerequisite, you must have obtained the following information from the Sitecore Managed Cloud support team:

  • Update Images pipeline ID for your environment

  • Access token to interface with the DevOps environment

To trigger the update images pipeline using an API:

  1. Use the POST method and a URL that is configured with the your parameters. These include organization name, your project name, and the pipeline ID of the Update images pipeline:

    https://dev.azure.com/{customer organization}/{customer project}/_apis/pipelines/{pipeline ID}/runs?api-version=6.0-preview.1

  2. You must configure the authorization using the access token provided by the Managed Cloud support team.

  3. The body of the API call must contain parameters with the path for the images to update. Use the following templates, named Example 1 and Example 2, to build the API call body in JSON format.

    The images that do not require updating can be set as NA.

    Multiple images can be provided in the formatted string for otherServiceImages parameter field.

Example 1: the following example shows the setting of a single image to be updated for the otherServiceImages otherServiceImages parameter.

{
     "templateParameters": {
           "sitecoreCmImagePath" : "NA",
           "sitecoreCdImagePath" : “NA”,
           "sitecoreIdImagePath" : “NA”,
           "sitecorePrcImagePath" : “NA”,
           "otherServiceImages" :  "- Name: <image name>\n  Path: <ACR FQDN>/<image name>:<image tag>"
            }
}                   

Example 2: the following example shows the setting of multiple images to be updated for the otherServiceImages parameter.

{    "templateParameters": {
            "sitecoreCmImagePath" : "NA",
            “sitecoreCdImagePath” : “NA”,
            “sitecoreIdImagePath” : “NA”,
            “sitecorePrcImagePath” : “NA”,
            "otherServiceImages" :  "- Name: <image name>\n  Path: <ACR FQDN>/<image name>:<image tag>\n- Name: <image name>\n  Path: <ACR FQDN>/<image name>:<image tag>"
            }
}