xmCloud Deploy Process

In this blog, I describe the xmcloud deployment process based on my understanding and observations and address some of the frequent questions that I saw in the community. Please keep in mind that the actual process may differ from what I described here and these are only my understanding of the process.

Preparing the projects and environments

When you want to start with xmcloud you need to create a project and environment(s) for that project. Each Project may have up to 3 environments. Only one of the environments is allowed to be marked as a Production environment.
Creating a project can be done using xmcloud deploy app web UI or Sitecore cli:

dotnet sitecore cloud project create --name <project-name>

This command will create a project and return it's information. Make a note of the project id.

For the next step you need to create your first environment:

dotnet sitecore cloud environment create --name <name> --project-id <project-id>

After creating for example two environments for development and staging you need to mark the third environment as the production instance:

dotnet sitecore cloud environment create --name <name> --project-id <project-id> --prod 

My guess is, that these steps only create the basic configuration for the Kubernetes cluster and at this time still there is no pod or resource allocation (no PODs). You can see the project and environments using the xmcloud app.

Deploying the application

You can create and start a deployment for a specific environment using this command:

dotnet sitecore cloud deployment create --environment-id <environment-id> --upload

My guess is this will upload all of your source code to the xmcloud build agent.

It will start the following processes:

• Provisioning
• Build
• Deployment
• Post Actions

After the upload is done, the Provisioning process will begin, my guess is, the provisioning process will check for the resource allocation for the environment, if the resources do not exist in the case of the new project, it will allocate the following resources:

• Allocate the SQL server instance and init the Core,Master and Web databases
• Allocate and setup the Experince edge
• Allocate and setup the Solr
• Configure the Auth0 for this environment

After the provisioning step is done, the build process will begin. During the build process following will happen:

• The newest base image for xmcloud will be pulled to the build agent
• The solution will be built using the Docker file configured by sitecore
• The Serialization items will be converted to the IAR package
• The container image will be created and pushed to the sitecore azure kubernetes

• Solution build is based on the "Directory.Build.targets" (you can have multiple) that you have configured for your projects. and of course the whole build and deployment process is configured in the xmcloud.build.json

When the build process is done the newly created container image will be handed over to the deployment process, my guess is the deployment process will start a new Kubernetes pod based on the new solution image. it will add the existing environment variable in the xmcloud app which is configured under Project>Environment>Variables plus the system environment variables, like the connection strings, rendering hosts URLs, and so on.

The deployment process will deploy the xmcloud app and the internal rendering host (editing host) for the Sitecore pages.

After the deployment is done, the current xmcloud pod will be switched with the new pod and the post actions will be started.

The Post actions will be run based on the configurations in the xmcloud.build.json, and it usually includes common tasks like warming up the instance, rebuilding the index, and so on.

Question: I have changed/deleted the default rendering host, how can I find the rendering host URL?

As discussed above, the xmcloud is running on the Kubernetes environment, and the internal URL of the rendering host configured /sitecore/system/Settings/Services/Rendering Hosts/Default may change. The Sitecore will deliver this item as IAR and will update it on the startup:

namespace Sitecore.XmCloud.Common
{
  public class RenderingHostItemInitProcessor
  {
    ....
    public virtual void Process(PipelineArgs args)
    {
        ....
        try
        {
          ...
          foreach (RenderingHost host in renderingHostList)
          {
            if (flag)
            {
              MutableItemData mutableItemData = this.GenerateItem(host, host.Id, host.Name);
              items.Add(mutableItemData);
            }
            else
            {
              Log.Info("Creating Default RH", (object) this);
              MutableItemData mutableItemData = this.GenerateItem(host, "dffee92b-0441-45a4-9207-67810b72bd46", "Default");
              items.Add(mutableItemData);
              flag = true;
            }
          }
          resourceGenerator.GenerateProtobuf((IEnumerable<IItemData>) items, "\\inetpub\\wwwroot\\sitecore modules\\items\\master\\items.master.xmcloudjss.dat");
        }
        catch (Exception ex)
        {
          Log.Error("An Error appeared during Rendering Hosts items creation: ", ex, (object) this);
        }
      }
    }
    ...
}

You should keep in mind that your IAR items will have higher priority than Sitecore IAR items, so if you have this item or its parent which may cause the deletion of the child item(if you have the wrong config), you need to adjust your serialization config and let the Sitecore take care of it.

After adjusting your serialization in a way that it won't affect this item you need to start a new deployment so the IAR items will be updated.

If you have changed the default rendering host URL manually, then you need to delete it and it will be restored from the database.

Environment variables on the xmcloud
As mentioned before the deployment process will add the environment variables to the pod, you can see these environment variables using PowerShell ISE:
gci env: | Format-Table -Wrap -AutoSize

Some of the examples are:

• BuildMetadata__BuildId
• BuildMetadata__DeploymentId
• BuildMetadata__EnvironmentId
• BuildMetadata__Id
• Connection strings
• RENDERING_HOST_INTERNAL_URI
• Kubernetes configs
• ...

I wrote an article for example usage of the xmcloud deploy API, in which I used these environment variables.

Question: What is the Promote functionality in xmcloud?

When you are creating the environments for your project, the best practice is to create three environments:

• Development: This is the lowest environment and used for testing of the single branch for each feature
• Staging: This environment is used for integration testing and approval process by the customer
• Production: Live website

You need always to start the deployment to the lowest environment, in this way the container image will be created and pushed to the kubernetes repository. Later you can use the promote to deploy the same image to the higher environment.
Promote will make sure that the exact same code and same xmcloud base image (same image) will be deployed to the higher environment, and as a side effect will save you some time, because promoting to the higher environment will not need any build process.

Promoting can be done over the Deploy app web ui or using sitecore CLI:

dotnet sitecore cloud environment promote --environment-id ${{ parameters.environmentId }} --source-id ${{ parameters.sourceId }} --json