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.
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.
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.
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
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.
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.
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 export.site-node-1.zip -z export.site-node-2.zip -z export.site-node-3.zip -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.
merge action will package your data and configurations into a single ZIP (merge.zip) and a base Appian operator Custom Resource (appian.yaml) for your Kubernetes deployment. These files will both be used for the
Do not manually attempt to unzip the migration artifacts created by the tool.
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 merge.zip 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 merge.zip -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.
Using the Appian on Kubernetes Migration Tool