1. Configure Managed Cloud

Walkthrough: Adding the Sitecore Publishing Service module

Version:

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:

    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:

    
---

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

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

    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:

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

    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:

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

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

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.

If you have suggestions for improving this article, let us know!