Specialized SaaS deployment scenarios

This page covers specialized SaaS deployment situations: deploying a large amount of data during initial deployments using custom restore and deploying emergency fixes. See Deploy to the SaaS environment for common deployment scenarios.

Deploy a large amount of data during initial deployments

During initial deployments (e.g., when upgrading to Xperience by Kentico), you can use custom restore to deploy a large amount of data without being restricted by the 2 GB deployment package limit.

Custom restore enables you to transfer the database and storage files directly to the selected environment. Custom restore does not provide a way to deploy application libraries, so it needs to be used in combination with a deployment package.

During the process, you first upload the data to automatically created containers in Azure Storage that are separate from your SaaS environments. When you apply the custom restore, all existing data in the target environment’s database and storage is overwritten with the uploaded data, and the target environment is unavailable while the restore itself runs.

The changes introduced by a custom restore are not propagated between environments with the deployment package. Transferring them to other environments requires a custom restore for each environment.

Perform a custom restore

To perform a custom restore:

1. Back up your data.

   1. Create a restore point for the target environment before starting.

2. Create a restore session.

   1. Navigate to Data Management → Custom restore.
   2. Select Create session.

   

3. Get access to restore containers.

   1. Select Get access.

   2. If you want to restrict access to the restore containers, specify an allowlist by entering an IP address or an IP address range and confirm with Get access. Otherwise, select Get access without entering any values.

   3. Copy both SAS URLs for the database and storage containers.

      SAS URLs

      You can’t retrieve the same SAS URLs again. However, you can get new SAS URLs with Get access. The previously existing SAS URLs are still valid. To revoke all current SAS URLs, select Revoke access under Current session.

      Within a session, the SAS URL pairs provide access to the same containers.

4. Upload the database.

   • You can use Azure Storage Explorer to connect to the container:

     1. In Azure Storage Explorer, connect to the restore Azure Storage (select the type Blob container or directory).

     2. Select the connection through Shared access signature URL (SAS).

     3. Enter the SAS URL for the database container and connect to the resource. The display name does not matter.

     4. Upload the database exported as a bacpac file to the database container.

        The file must be named db.bacpac. The database to be restored must have the same version as the one currently in the environment. If these conditions are not met, the restore will not succeed.

5. Upload storage files.

   1. Connect to the storage container using the second SAS URL (as in the previous step).

   2. Upload the files to be stored in Azure Blob Storage.

      • Organize the files according to the Azure Blob Storage configuration of your project. You can obtain this structure by downloading a Storage and files export once you have deployed with this Blob storage configuration.
      • For each container used in your Blob storage mapping, upload a folder with the same name. Within that folder, include the files arranged according to your project’s storage structure.
        • For example, if you’re using the default configuration, the structure would be default/assets/….
      The names of files and folders uploaded to the storage container must be fully in lowercase.
      • Note that the uploaded files count toward the file storage limit, which you can view on the Dashboard.

6. Restore to an environment.

   1. Make sure you have a backup of the target environment. The custom restore process itself cannot be undone, but you can use restore points to revert the changes.
   2. Once you have uploaded both the database and the storage files to be restored, you can select Restore to environment under Current session.
   3. Select the target environment where the data should be restored. The environment will be unavailable during the restore process. The database in the target environment will be replaced with the uploaded one. All storage containers in the environment will be deleted and recreated based on the uploaded data.
   4. Select Create to start the custom restore process.
   Tenant administrator and DevOps roles can restore to any environment. Developers can restore only to non-production environments (QA, UAT).

7. Close the session.

   1. You can see the restore in progress under Active restores. Once finished, it will appear under Last completed restores.
   2. When the restore process is complete and you no longer need to keep the data (for example, to restore it to another environment), Close the session.
   Each session expires after a week. Once a session has expired, you can no longer upload data to the containers, but you can still restore the data you uploaded previously (up to 180 days from the session creation). Only one restore session can be open at a time.

Deploy emergency fixes to the SaaS environment

Emergency deployments allow users in DevOps Engineer or Tenant Administrator roles to bypass the standard deployment flow and push critical fixes or version updates directly to environments other than QA.

The emergency deployment process is suitable for the following situations:

• The Xperience version deployed in your PROD environment is, for example, 30.0.0. In the QA environment, the deployed version is 30.1.0 with some new features you are currently testing. In version 30.2.0, Kentico releases a security advisory and you want to immediately update to this version. However, your QA environment is “blocked” by the tested feature.
• You have recently released a new functionality that contains an issues that impedes the usability of your application. The fix for this issue is simple, but you need to promote it to the PROD environment as soon as possible. However, your QA environment is “blocked” by a new feature that is already tested in this environment.

Deploy emergency fixes from Xperience Portal

1. Create the emergency deployment package. Consider using the -ZeroDowntimeSupportEnabled parameter if your application supports it to minimize deployment downtime.
2. Upload the package from Xperience Portal. In the Deployments application, select the Upload package button under the desired environment.

Deploy emergency fixes using Xperience Portal API

1. Create the emergency deployment package.

2. If you don’t have one already, create a Personal access token with the required permissions for respective environments: Deploy to production environments or Deploy to non-production environments.

3. Upload a package using Xperience Portal API. When sending the POST request to the deployment API endpoint, modify or add the last path segment and set the value to the desired environment (e.g., prod for Production or stg for Staging).

   PS

   Upload to PROD environment

   Copy

   
   
    # Due to a PowerShell issue, we recommended disabling the progress bar to boost the performance significantly.
    # See https://github.com/PowerShell/PowerShell/issues/2138 for more information.
    # Disable the progress bar
    $ProgressPreference = 'SilentlyContinue'
   
    # Upload the deployment package
    $headers = @{ Authorization = "Bearer <PERSONAL_ACCESS_TOKEN_WITH_REQUIRED_PERMISSION>" }
    Invoke-RestMethod -Uri https://xperience-portal.com/api/deployment/upload/<PROJECT_GUID>/prod -Method Post -InFile <FILE_PATH> -ContentType "application/zip" -Headers $headers
   
    # Enable the progress bar
    $ProgressPreference = 'Continue'