Walkthrough: Adding the Sitecore Publishing Service module

Current version: 10.1

The Sitecore Publishing Service (SPS) module provides integration with the opt-in Publishing Service, supporting high-performance publishing in large-scale Sitecore setups. To deploy SPS as a container in a cloud-based solution, you must deploy both the module and the service on top of your Sitecore solution.

This walkthrough describes how to deploy the SPS module on top of an already deployed managed cloud containers environment. It describes how to:

  • Prepare the Docker images

  • Push the images to the Azure Container Registry (ACR)

  • Download the Kubernetes specification files

  • Copy the base SPS Kubernetes configuration files

  • Define an SPS configuration overlay

  • Change the images in the Application repository

  • Run the mssql_init_sps container:

    • Without disaster recovery.

    • With disaster recovery.

  • Enable the SPS component

  • Apply the application changes

Prepare the Docker images

To prepare the Docker images:

  • You must prepare the Sitecore CM, CD, and MSSQL-INIT custom images to include all the resources (files, databases, and so on) from the SPS asset images. The asset images are:

    • sxp/modules/sitecore-sps-integration-xm1-assets

    • sxp/modules/sitecore-sps-integration-xp1-assets

You must use the asset image for the topology you are deploying. For more information about how to apply the asset images, refer to: Add Sitecore modules and the Sitecore module reference.

Refer to the Sitecore Publishing Service Container Deployment Guide document for instructions on how to build corresponding custom images.

Push the images to the Azure Container Registry (ACR)

To push the images to the ACR:

  • In PowerShell, run the docker push command. You must push all SPS custom images (CM, CD, and MSSQL-INIT) to the preprovisioned ACR: {infrastructure_id}acr.

Download the Kubernetes specification files

In the GitHub Sitecore containers deployment repository, locate and download the following file:

  • SitecorePublishingServiceContainerDeployment.10.1.0.{latest available build number}.zip

This file contains the Sitecore Publishing Service Kubernetes configuration files for Sitecore XP 10.1.0. Unzip the package locally.

Copy the base SPS Kubernetes configuration files

To copy the base SPS Kubernetes files:

  1. Navigate to the Application repository folder and create an sps folder: roles\sitecore-{topology}\bases\components\sps

  2. Copy the following sps base configuration files into the folder:

    • \k8s\ltsc2019\sps\patch-sps.yaml

    • \k8s\ltsc2019\sps\sps.yaml

    • \k8s\ltsc2019\overrides\{topology}\patch-cm.sps.yaml

  3. In the sps folder you created earlier, create a kustomization.yaml file with the following content:

    RequestResponse
    apiVersion: kustomize.config.k8s.io/v1alpha1
    kind: Component
    
    resources:
    - sps.yaml
    
    patchesStrategicMerge:
    - patch-sps.yaml
    - patch-cm.sps.yaml

Define an SPS configuration overlay

To integrate the SPS module configuration with the Managed Cloud Containers environment, you must define an overlay layer on top of the SPS base configuration. This abstraction simplifies the upgrade process of the SPS base configuration during an SPS module upgrade for future releases.

To define and run the overlays:

  1. Create a roles\sitecore-{topology}\overlays\components\sps\kustomization.yaml file with the following content:

    RequestResponse
    
    ---
    
    apiVersion: kustomize.config.k8s.io/v1beta1
    
    kind: Kustomization
    
    
    resources:
    
    - sitecore-roles.yaml
    
    
    patchesStrategicMerge:
    
    - sps.yaml
    
  2. Create a roles\sitecore-{topology}\overlays\components\sps\sps.yaml file with the following content:

    RequestResponse
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: sps
    spec:
      progressDeadlineSeconds: 3600
      template:
        spec:
          containers:
          - name: sitecore-sps
            image: "{{ docker_images.sitecore.sps }}"
    
  3. To run the overlays, navigate to: roles\sitecore-{topology}\tasks\main.yaml and add the tasks next to the Run Kustomization for {topology} task.

    The following example describes XP topology. For XM, you must replace sitecore-xp with sitecore-xm.

    RequestResponse
    - name: Copy Sitecore roles configuration into SPS overlay
      template:
        src: roles/sitecore-xp/templates/sitecore-roles.yaml
        dest: roles/sitecore-xp/overlays/components/sps/sitecore-roles.yaml
    
    - name: Run Kustomization for SPS integration
      shell: |
          kustomize build roles/sitecore-xp/overlays/components/sps > roles/sitecore-xp/templates/sitecore-roles.yaml
    

Change the images in the Application repository

Now you can add the SPS-specific image and the two new properties to the Application repository.

To change the images in the Application repository:

  • Navigate to the Application repository config/docker-images and edit the docker-images.json file and make the following changes:

    • Replace the cm image with cm-sps.

    • Replace the cd image with cd-sps.

    • Add the mssql_init_sps property.

    • Add the sps property, and point it to the SPS service public image that corresponds to your Sitecore version.

Run the mssql_init_sps container without disaster recovery

To run the mssql-init-sps container:

  1. Navigate to roles\sitecore-{topology}\templates\ and add the mssql-init-sps.yaml jobs file with the following content:

    RequestResponse
    apiVersion: batch/v1
    kind: Job
    metadata:
     name: sps-mssql-init
    spec:
      template:
        spec:
          nodeSelector:
            kubernetes.io/os: windows
          imagePullSecrets:
            - name: sitecore-docker-registry
          containers:
          - name: mssql-init-sps
            image: "{{ docker_images.sitecore.mssql_init_sps }}"
            env:
            - name: sitecore_admin_password
              valueFrom:
                secretKeyRef:
                  name: sitecore-admin
                  key: sitecore-adminpassword.txt
            - name: SQL_ADMIN_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-databasepassword.txt
            - name: SQL_ADMIN_LOGIN
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-databaseusername.txt
            - name: SQL_SERVER
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-databaseservername.txt
            - name: SQL_ELASTIC_POOL_NAME
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-database-elastic-pool-name.txt
            - name: DATABASES_TO_DEPLOY
              value: sps
          restartPolicy: Never
      backoffLimit: 5
  2. Add the Ansible tasks to run the mssql-init-sps job. Navigate to roles\sitecore-{topology}\tasks\init.yaml and add the following scripts at the end of the file:

    RequestResponse
    - name: Execute SPS mssql-init jobs
      k8s:
        apply: true
        namespace: "{{ solution_id }}"
        state: present
        definition: "{{ lookup('template', 'mssql-init-sps.yaml') }}"
    
    - name: 'Wait - SPS Mssql-init job'
      k8s_info:
        kind: Job
        name: sps-mssql-init
        namespace: "{{ solution_id }}"
      register: sps_mssql_init_result
      un-til: (sps_mssql_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
      retries: 60
      delay: 60
    
    - name: Get all SPS Mssql completed pods
      k8s_info:
        kind: Pod
        namespace: "{{ solution_id }}"
        label_selectors:
          - job-name = sps-mssql-init
      no_log: true
      register: sps_mssql_pod_list
    
    - name: Remove SPS Mssql job's pods
      k8s:
        kind: Pod
        name: "{{ item.metadata.name }}"
        namespace: "{{ solution_id }}"
        state: absent
      no_log: true
      with_items: "{{ sps_mssql_pod_list.resources }}"
    
    
  3. Run the application pipeline.

Run the mssql_init_sps container with disaster recovery

To run the mssql-init-sps container:

  1. Navigate to roles\sitecore-{topology}\templates\ and add the mssql-init-sps.yaml jobs file with the following content:

    RequestResponse
    apiVersion: batch/v1
    kind: Job
    metadata:
     name: sps-mssql-init
    spec:
      template:
        spec:
          nodeSelector:
            kubernetes.io/os: windows
          imagePullSecrets:
            - name: sitecore-docker-registry
          containers:
          - name: mssql-init-sps
            image: "{{ docker_images.sitecore.mssql_init_sps }}"
            env:
            - name: sitecore_admin_password
              valueFrom:
                secretKeyRef:
                  name: sitecore-admin
                  key: sitecore-adminpassword.txt
            - name: SQL_ADMIN_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-databasepassword.txt
            - name: SQL_ADMIN_LOGIN
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-databaseusername.txt
            - name: SQL_SERVER
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-databaseservername.txt
            - name: SQL_ELASTIC_POOL_NAME
              valueFrom:
                secretKeyRef:
                  name: sitecore-database
                  key: sitecore-database-elastic-pool-name.txt
            - name: DATABASES_TO_DEPLOY
              value: sps
          restartPolicy: Never
      backoffLimit: 5
  2. Create a custom init.yaml file, for example, custom-init.yaml, and put it under the /roles/sitecore-{topology}/tasks folder.

  3. To add the mssql-init-sps job to the file, add the following code:

    RequestResponse
    - name: Execute SPS mssql-init jobs
      k8s:
        apply: true
        namespace: "{{ solution_id }}"
        state: present
        definition: "{{ lookup('template', 'mssql-init-sps.yaml') }}"
    
    - name: 'Wait - SPS Mssql-init job'
      k8s_info:
        kind: Job
        name: sps-mssql-init
        namespace: "{{ solution_id }}"
      register: sps_mssql_init_result
      un-til: (sps_mssql_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
      retries: 60
      delay: 60
    
    - name: Get all SPS Mssql completed pods
      k8s_info:
        kind: Pod
        namespace: "{{ solution_id }}"
        label_selectors:
          - job-name = sps-mssql-init
      no_log: true
      register: sps_mssql_pod_list
    
    - name: Remove SPS Mssql job's pods
      k8s:
        kind: Pod
        name: "{{ item.metadata.name }}"
        namespace: "{{ solution_id }}"
        state: absent
      no_log: true
      with_items: "{{ sps_mssql_pod_list.resources }}"
  4. To call the custom init.yaml file, go to /roles/sitecore-{topology}/tasks/main.yaml and add the following role at the end of the file:

    RequestResponse
    - name: Execute custom init jobs 
      include_tasks: custom-init.yaml
    In the main.yaml file, call the init.yaml file.
  5. Run the application pipeline.

  6. If the custom job has been successfully created, comment out the Execute custom init jobs role.

Enable the SPS component

To enable the SPS component:

  • In the Application repository, navigate to the roles\sitecore-{topology}\overlays\platform\kustomization.yaml file and enable SPS by using the components element, pointing to the sps module configuration scripts folder.

RequestResponse
components:
-  ../../bases/components/sps

Apply the application changes

To apply the application changes to the environment:

  • Create and complete a pull request to the Application repository.

Do you have some feedback for us?

If you have suggestions for improving this article,