Free cookie consent management tool by TermsFeed Using the Appian on Kubernetes Migration Tool [Appian on Kubernetes v0.140.1]
Appian Operator
Using the Appian on Kubernetes Migration Tool


This page outlines the steps and information needed for using the Appian on Kubernetes Migration Tool for self-managed customers.

The Migration Tool makes it easier to transition an existing machine-based Appian deployment to an Appian on Kubernetes deployment by packaging up your data and configurations.

Before Starting

Shut Appian down and make a full backup of your original Appian deployment and associated databases before proceeding. You can find instructions here.

  • You will need to download the Migration Tool executable specific to the operating systems of your Appian site, as well as any machine(s) that will be used to execute the migration. The Migration tool will need to be installed on all the physical server(s) that run your Appian deployment(s). For HA and distributed topologies you will need to ensure that it is on every server.

  • Set up the Appian operator on the destination Kubernetes cluster per the Installation Guide.

    • Set up registries with the Appian product images. The Appian images need to be the same version as their current deployment.
    • Import K Licenses.
    • Install the Appian operator Helm chart.
    • Don't create the Appian Custom Resource or go any further, as the Migration Tool will handle those tasks.

If you are on an older version of Appian, you will need to upgrade your original deployment to a version of Appian compatible (22.1+) with the Appian operator before running the Migration Tool.

  • Your database connection should be accessible for your destination Kubernetes cluster.

We do not support database migrations as part of this tool.

The Migration Tool commands each have -h flags that explain supporting flags and which parameters are required or optional. You can see the full list of commands available by running migrate --help or migrate -h.

Step 1: Exporting your Appian data

To begin your migration, you will use the export command, pointing to your Appian installation directory and defining a directory for output.

The tool will package your Appian data into a ZIP, including shared data for HA or distributed Appian deployments, and prepare it to be deployed in Kubernetes.

Before proceeding, first ensure you have enough room available for the generated ZIP. You'll need free space representing at least 70% of your Appian data total. You can use the du command on a Linux system on your Appian directory and prepare an estimate based on that.

As an example, if your Appian installation is located at C:\appian-prod\appian on a Windows server and you have created a new directory on that server C:\appian-migration for storing the exported data, your command would look like this:

.\migrate.exe export -i C:\appian-prod\appian -o C:\appian-migration

For Unix/Linux systems the command would look similar to this:

./migrate export -i /usr/local/appian -o /appian-migration

If you have a HA/distributed deployment, you will need to run the export command on each server. Follow through all the prompts to ensure that your site and its data is exported properly.

Step 2: Preparing and merging your Appian data

Once all your site data has been exported the merge command is needed to generate a Kubernetes Custom Resource from your data and configurations. This command must be executed regardless if you have a single, HA, or distributed topology.

The merge command must have access to all the export ZIPs to properly execute. If you have an HA/distributed site you will need to ensure that all the zips are accessible; it is recommended that you try to collocated the ZIPs on the same machine if possible.

Here is an example of executing the merge command for a Unix/Linux system of a distributed site:

./migrate merge -z -z -z -o .

As before, be certain that you have enough room for the generated merged ZIP file. This is especially true if you are merging from multiple server sources, since the merged data will represent the sum of those ZIP files.

The merge action will package your data and configurations into a single ZIP ( and a base Appian operator Custom Resource (appian.yaml) for your Kubernetes deployment. These files will both be used for the import action.

Do not manually attempt to unzip the migration artifacts created by the tool.

Step 3: Importing your Appian data into Kubernetes

The import will need to be executed on an environment that has direct access to your Kubernetes cluster. If you need to move the appian.yaml and to a different machine to perform the import make sure you have downloaded the appropriate Migration tool for that machine's OS.

import will help validate your data, create PVCs (Kubernetes Persistent Volume Claims), and copy the zipped data from merge into those PVCs.

Before running the import command, you will need to update the appian.yaml Custom Resource file based on your cluster requirements. Below are fields which will need to be modified at a minimum:

Any HA or multi-replica definitions of Webapp or Service Manager will also require the haExistingClaim to be defined for those services. See High Availability for this set up.

It is strongly recommended to update the Resource limits for the Appian services based on your sites's needs. Refer to Resource Requests and Limits for guidelines on resource updates based on your cluster and site's needs.

Here is an example of executing the import command for a Unix/Linux system of a distributed site:

./migrate import -z -a appian.yaml -n <site namespace>

Do not change the Appian versions or the number of replicas for services from your site's current setup at this time during migration. The import action will fail if it detects any of those changes. You can perform upgrades of Appian afer you have confirmed that the migration of your data has been successful.

Once this process is completed, the tool will start up your new Appian deployment. If you have not setup how to expose Appian the front end will not be accessible. However you should check that all the Appian services were able to come up and verify that the number of pods match your site's defined replica count. At this point, you may want to visit the Tasks, Configuration, and Reference sections of the Appian on Kubernetes documentation for instructions on upkeep, upgrading, and additional configurations.

Open in Github Built: Fri, Feb 23, 2024 (09:13:35 PM)

Using the Appian on Kubernetes Migration Tool