Walkthrough: Adding the Sitecore Publishing Service module

Abstract

Learn how to add the SPS module that supports publishing in large-scale setups.

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 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

  • Enable the SPS component

  • Apply the application changes

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.

To push the images to the ACR:

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

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.

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:

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

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 execute the overlays:

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

    
    ---
    
    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:

    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: sps
    spec:
      progressDeadlineSeconds: 3600
      template:
        spec:
          containers:
          - name: sitecore-sps
            image: "{{ docker_images.sitecore.sps }}"
    
    
  3. To execute 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.

    - 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
    
    

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.

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:

    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 execute the mssql-init-sps job. Navigate to roles\sitecore-{topology}\tasks\init.yaml and add the following scripts at the end of the file:

    - 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 }}"
    
    
    

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.

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

To apply the application changes to the environment:

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