Free cookie consent management tool by TermsFeed

Installing Appian on Kubernetes

On This Page

Overview

This page walks through how to install Appian on Kubernetes for self-managed customers. The instructions show how to install on a server-based cluster.

This content is aimed at platform engineers with experience with Kubernetes, Helm, and container images. Appian is installed on Kubernetes using a custom resource definition (CRD) and an operator. Before performing the install, you should be familiar with these concepts. To read about them, see What is the Appian Operator?

Note:  This documentation specifically deals with deployment, maintenance, and configuration tasks that are unique to Appian on Kubernetes.

These instructions help you configure a single replica instance of Appian on Kubernetes. Refer to our high availability configuration docs for more information if you would like to setup a multi-replica (HA) deployment of Appian using the Appian operator.

Prerequisites

Before you begin, make sure you meet the following prerequisites and system requirements.

Supported versions

This release of Appian on Kubernetes has been explicitly tested against Kubernetes v1.33-v1.37. To check your server version, run kubectl version in the command line.

Supported platforms

Appian on Kubernetes and the Appian Operator were developed following standard Kubernetes practices. Appian is validated on and supports major platforms including:

Installation Type Platform
Cloud-native
Server-based "plain" or bare metal Kubernetes

While Appian on Kubernetes may work on other conformant Kubernetes distributions, customers are responsible for validating implementations and managing deployment on any unlisted platforms.

Platforms that limit or automate cluster features, such as node-level customizations, may not be capable of running Appian due to such restrictions.

Unsupported platforms

  • Windows: Appian on Kubernetes does not support Kubernetes clusters using Windows Server nodes. The control plane must be on Linux.
  • Serverless: Appian on Kubernetes does not support AWS Fargate, GKE Autopilot, Azure ACI, or similar "serverless" virtualized environments.

Before you begin

Determine your Appian site name

The Appian site name is a unique identifier for your Appian installation. This name will be used to identify the installation in Kubernetes, and you'll be prompted for this name as you install and configure Appian on Kubernetes.

This name must:

  • Contain only lowercase alphanumeric characters, hypens (-), or periods (.).
  • Be between 10 and 15 characters.
  • Not include "appian", "appn", or "apn".
  • Be unique across your organization.

We recommend that the name includes a reference to your organization name. It can also be useful to reference the specific environment such as production versus staging.

For example, company-name or company-name-staging.

Determine your Appian site URL

Whether you have a standalone instance of Appian or a load-balanced configuration with multiple replicas, your end-users should use a single URL to access your Appian installation.

Site URLs must adhere to the same naming limitations as your Appian site name.

For example, https://company-name.com.

Request licenses

Caution:  Starting in November 2026, newly issued Appian licenses will be signed with a new private key and require version v0.205.0 of the Appian operator or newer.

You need to request licenses specifically for Appian on Kubernetes. There are two types of licenses:

  • Temporary license: Valid for 6 days. Request temporary license files when you're setting up a new Appian instance for the first time or a long-term license has expired and you want to renew it.

  • Long-term license: Valid for an extended period of time, and only valid for the site URL for which they were requested. Request long-term license files when you've already obtained temporary license files to set up an Appian instance, or your existing license files are about to expire and you want to proactively request replacements.

Note:  It can take up to 4-5 business days to generate the long-term license files. We recommend that you request temporary license files first, or request both the temporary and long-term licenses at the same time.

To request temporary and long-term licenses:

  1. Go to the Licenses site.

  2. Click REQUEST A NEW LICENSE. The Request an Appian License page displays.

    Request an Appian License page

  3. Click Kubernetes Licenses.
  4. Request a temporary license:

    1. Click Temporary.

      Temporary license fields

    2. For Reason for License, select an appropriate reason. For example, if you're setting up a new server, select Set Up New Server.
    3. Click SEND REQUEST.
  5. Request a long-term license:

    1. Click Long-term.

      Long-term license fields

    2. Complete the following fields:

      Field Action
      Licenses to request. Keep the default selected (k3.lic, k4.lic, and appian.lic).
      Spec URL Enter the URL you intend to use for your Appian site, following the same pattern as above. For example, https://company-name.com.
      Custom Resource Name Enter your Appian site name.
      Reason for License Select an appropriate reason. For example, if you're setting up a new server, select Set Up New Server.

    3. Click SEND REQUEST.

What happens next?

  • If you are your organization's primary point of contact (POC), Appian license administrators will review your request and provide you with the license files or the next steps required to generate the long-term license files.

  • If you are not your organization's primary POC, the request will first go to your organization's POC, who will need to approve the request. If the POC approves the request, the Appian license administrators will then review the request and provide you with the license files or the next steps required to generate the long-term license files.

Decide how you want to provision CA certificates

Before you install the Appian operator Helm chart, you'll need to determine how you want to provision CA certificates. The steps outlined in this page follow our preferred option of using a generated self-signed certificate with cert-manager.

Decide how you want to expose Appian

Appian needs to be exposed outside of Kubernetes to allow access to Apache Web Server (httpd) and webapp components. See Exposing Appian Outside Kubernetes to learn about different ways of exposing Appian.

How you choose to expose Appian will affect properties configured in the Appian CR configuration file.

Set up a relational database for environment metadata

Appian on Kubernetes requires its own relational database to store system metadata, known as the Appian data source. However, Appian on Kubernetes does not install that relational database, so you can select a database consistent with your organization's policies and practices.

This relational database can either run within the Kubernetes cluster or outside of it. If you want to connect directly to a database outside the cluster, ensure that the database is accessible from within the cluster.

Refer to System Requirements to see the relational databases supported for use with Appian.

You must install RDBMS or JDBC drivers in the environment if you want to use Aurora MySQL, MySQL, or IBM Db2 as the Appian data source. Driver installation can also be required if you want to use an older supported version of other relational databases that require different driver versions.

(Optional) Configure Appian RPA database

To use Appian RPA, you must also create and configure multiple databases on the MariaDB server, ensuring the URL, username, and password are correctly set in the configuration files.

Download artifacts

Download the Appian operator Helm chart, pull the Appian operator and Appian container images, and push the images to your organization's registry.

Install Appian on Kubernetes

Once you complete the pre-installation steps, you're ready to install Appian on Kubernetes.

Note:  Services including Kafka and Zookeeper are sensitive to latency reading from and writing to data. Appian recommends keeping the data directories for these two components (services/data/kafka-logs and services/data/zookeeper) on solid state volumes rather than mounting them onto network drives. This recommendation is consistent with industry best practices for these services. The same recommendation about using local disk applies to the search server search-server/data/ and the data service data-server/data/ as well. Object storage is not currently supported for use with these services.

The commands below include placeholders that you'll need to replace with values specific to your environment. For example, you'll want to replace:

  • <APPIAN_OPERATOR_VERSION>
  • <REGISTRY_HOSTNAME>
  • <MY_SITE_NAMESPACE>
  • <PATH TO LICENSE>

1. Install the Appian operator

The following steps will install the Appian operator in the appian-operator namespace from the Appian operator Helm chart you downloaded earlier.

Additionally, these steps follow our preferred option of using a generated self-signed certificate with cert-manager. See additional instructions to configure the caBundle field directly.

  1. Using kubectl, create the appian-operator namespace in the command line:

    1

    kubectl create namespace appian-operator

  2. Install the Appian operator Helm chart using this basic command:

    1
2
3
4

    helm --namespace appian-operator install appian-operator-<APPIAN_OPERATOR_VERSION>.tgz \
--set image.repository=<REGISTRY_HOSTNAME>/appian/appian-operator:<APPIAN_OPERATOR_VERSION> \
... \
--wait

    You may need to specify additional values and annotations in this command, including:

    • If you changed the certificate name or secret name when you created the certificate, use those names here instead of appian-operator-webhooks and appian-operator-webhooks-certificate.
    • For the mutating and validating admission webhooks, add --set webhooks.webhookConfiguration.annotations."cert-manager.io/inject-ca-from:appian-operator/<your certificate name>".
    • To populate the caBundle field from a cert-manager certificate, add --set webhooks.secret=appian-operator-webhooks-certificate:

    Here's an example of the full Helm command that you might run:

    1
2
3
4
5

    helm --namespace appian-operator install appian-operator appian-operator-v0.117.0.tgz \
--set image.repository=registry.example.com/appian/appian-operator \
--set webhooks.secret=appian-operator-webhooks-certificate \
--set webhooks.webhookConfiguration.annotations."cert-manager\.io/inject-ca-from"=appian-operator/appian-operator-webhooks \
--wait

    Note:  If the container registry where your Appian operator image resides is private, create a secret of type docker-registry and provide the name of the secret via the option --set imagePullSecrets={<NAME>} in the command above.

    If you've pushed the operator image with a different tag that doesn't match the version / app version of the chart, you'll want to include the option --set image.tag=<TAG>.

  3. This command may take a minute or two to complete. When complete, use the following command to check that the correct Appian operator deployments, replicasets, and pods were created:

    1

     kubectl -n appian-operator get deployments,replicasets,pods

    The output should be similar to:

    1
2
3
4
5
6
7
8
9
10
11

       NAME                                          READY   UP-TO-DATE   AVAILABLE   AGE
   deployment.apps/appian-operator-controllers   1/1     1            1           90s
   deployment.apps/appian-operator-webhooks      1/1     1            1           90s

   NAME                                                     DESIRED   CURRENT   READY   AGE
   replicaset.apps/appian-operator-controllers-55cfcf74f    1         1         1       90s
   replicaset.apps/appian-operator-webhooks-5bd6588b95      1         1         1       90s

   NAME                                              READY   STATUS    RESTARTS   AGE
   pod/appian-operator-controllers-55cfcf74f-sr4jd   1/1     Running   0          90s
   pod/appian-operator-webhooks-5bd6588b95-7lggk     1/1     Running   0          90s

    For each of the operator's controllers and webhooks, you should see a single deployment, replicaset, and pod. Once the Pods' STATUS are all Running, the READY column should show 1/1 within 1 minute.

  4. Validate that the Appian CRD installed successfully by running this command:

    1

     kubectl get crd appians.crd.k8s.appian.com

    The output should be similar to:

    1
2

     NAME                         CREATED AT
 appians.crd.k8s.appian.com   2022-03-04T12:00:00Z

If you have any trouble installing the operator, see Troubleshooting Appian on Kubernetes.

2. Create the Appian site namespace

If you haven't done so already, create a new namespace in Kubernetes for your Appian site and all of its components. The namespace can have any name; these instructions use <MY_SITE_NAMESPACE> as a placeholder.

1

kubectl create namespace <MY_SITE_NAMESPACE>

3. Load licenses

When you requested your licenses, you received a zip with two files: k3.lic and k4.lic, and a third file called appian.lic. The first two will be installed as secrets on Kubernetes, and appian.lic will be installed as a config map.

  1. Unzip the product license files.

  2. Load the product license files as secrets into Kubernetes. Replace <PATH TO LICENSE> with the location where you unzipped the license files in step 1.

    1

     kubectl -n <MY_SITE_NAMESPACE> create secret generic k3lic --from-file=<PATH TO LICENSE>/k3.lic

    1

     kubectl -n <MY_SITE_NAMESPACE> create secret generic k4lic --from-file=<PATH TO LICENSE>/k4.lic

  3. Create a config map for the appian.lic file, and name the config map as you wish (replacing <MY_SITE_NAMESPACE> in the following command):

    1

     kubectl -n <MY_SITE_NAMESPACE> create configmap appian-lic --from-file=<PATH TO LICENSE>/appian.lic

    When you configure your Appian YAML in the next step, define the name of your license config map with the appianLicConfigMapName property.

4. Configure the Appian CR configuration file

Note:  Migrating from a server-based installation to Appian on Kubernetes? Use the YAML file generated by the migration tool's merge or dry-run command instead of the template.

The Appian CR configuration file stores the spec properties that Kubernetes uses to deploy the Appian custom resource.

To configure this file:

  1. Copy the appian.yaml template file.

  2. At minimum, replace the following template values with your own values:

    Field Template Value Replace With
    .metadata.name appian The Appian site name.
    .spec.appianLicConfigMapName appian-lic The name of the ConfigMap associated with the appian.lic file. This is required for your site to start.
    .spec.url http://myappiansite.com The fully qualified domain name of the Appian site URL including the scheme, host, and, optionally, port. For example: http://www.example.com:8080.
    .spec.webapp.dataSources.primary.driverClassName org.mariadb.jdbc.Driver Driver class name for your RDBMS. For examples of each of the supported databases, see Configuring Data Sources.
    .spec.webapp.dataSources.primary.url jdbc:mariadb://mariadb-appian.<MY_SITE_NAMESPACE>.svc.cluster.local:3306/AppianDS?useOldAliasMetadataBehavior=true Appian data source connection URL of your RDBMS. For URL examples of each of the supported databases, see Configuring Data Sources.
    .spec.webapp.dataSources.primary.username username Plain-text username for your RDBMS connection.

    If you installed a new copy of MariaDB in earlier steps, this will be the username created in that step. For example: username.
    .spec.webapp.dataSources.primary.passwordSecretKeyRef passwordSecretKeyRef Provide your data source password by referencing an existing secret.
    .spec.webapp.dataSources.primary.attributes.validationQuery "SELECT 1" Validation query for your RDBMS connection. For examples of each of the supported databases, see Configuring Data Sources.

    If you installed a new copy of MariaDB in earlier steps, this will be "SELECT 1".
    .spec.[COMPONENT].image.repository
    (Multiple fields - one field per component)    		 registry.example.com/appian/<COMPONENT> Image location on your Docker registry of each Appian component. If you are using a custom registry, change this image for each Appian component. If you did not re-tag your images and push to a custom registry, use the current values that include registry.example.com.
    .spec.[COMPONENT].image.tag
    (Multiple fields - one field per component)    		 Various tag values for each Appian component. The image version number for each Appian component. You can find these tags with the command: docker images <MY DOCKER REGISTRY>/appian/*

    For example: docker images registry.example.com/appian/*

    Note:  We highly recommend you configure application logging to your needs with Log4j.

  3. Change any other custom values in appian.yaml spec. Refer to the Custom Resource Definition to explore supported fields and values, in addition to the customProperties fields.

    Here are some additional configuration settings to consider:

    Configuration Action
    Data sources We are only specifying an Appian data source in the spec, defined in the .spec.webapp.dataSources.business field. To use Data Store Objects, you'll also want to provide at least one business data store. This is just one method of configuring data sources, and can also be completed from the Administration Console.
    High availability The appian.yaml specifies one Pod replica per Appian component. Refer to our high availability docs for setting up multiple replicas in an HA instance of Appian.
    Horizontal pod autoscaling You may want to set up Horizontal Pod Autoscaling on the Apache Web Server (httpd).
    Ingress We expect to use an ingress controller, so we are setting .spec.ingress.enabled to true in the spec. See Exposing Appian Outside Kubernetes for configuration details.
    Init containers Specify init containers if your Appian data source relies on a relational database that required the installation of additional drivers.
    Persistent storage As most Appian components are StatefulSets that rely on persistent storage, the .spec.[STATEFUL_COMPONENT].volumeClaimTemplateSpec fields have suggested values that define this storage. For more on these fields, see PersistentVolumeClaimSpec.
    Resource requests and limits The .spec.[COMPONENT].resources fields in the appian.yaml spec are suggested resource values. For more on tuning these fields, see Resource Requests and Limits.
    Search Server kernel Set the Search Server kernel settings either using an init container in the Appian CR configuration file or using admin commands after the install.
    Web server The Apache Web Server (httpd) component is specified in lines 223-228, though it is optional and can be taken out if you are using another web server or don't require one.

  4. Save the file.

5. Create the Appian site

Note:  Migrating from a server-based installation to Appian on Kubernetes? Run the migration tool's import command instead of creating the Appian custom resource directly.

  1. In the command line, run kubectl create to create the Appian site based on the appian.yaml:

    1

    kubectl create -n <MY_SITE_NAMESPACE> -f <PATH TO APPIAN.YAML>

  2. It will take about 20-30 minutes for the Appian site to fully start. Check progress on the various Appian component pods with the following command.

    1

    kubectl -n <MY_SITE_NAMESPACE> get pods

    The STATUS of the Appian component pods will change from Pending to Running. When the Appian site is ready, you should see all pods have READY of 1/1 and STATUS of Running, similar to the following:

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    NAME                                           READY   STATUS    RESTARTS   AGE
appian-data-server-0                           1/1     Running   0          25m
appian-httpd-8658f7fdb7-k9f6j                  1/1     Running   0          25m
appian-httpd-bf56974d4-crv4g                   1/1     Running   0          25m
appian-kafka-0                                 1/1     Running   0          25m
appian-search-server-0                         1/1     Running   0          25m
appian-service-manager-analytics00-0           1/1     Running   0          25m
appian-service-manager-analytics01-0           1/1     Running   0          25m
appian-service-manager-analytics02-0           1/1     Running   0          25m
appian-service-manager-channels-0              1/1     Running   0          25m
appian-service-manager-content-0               1/1     Running   0          25m
appian-service-manager-download-stats-0        1/1     Running   0          25m
appian-service-manager-execution00-0           1/1     Running   0          25m
appian-service-manager-execution01-0           1/1     Running   0          25m
appian-service-manager-execution02-0           1/1     Running   0          25m
appian-service-manager-forums-0                1/1     Running   0          25m
appian-service-manager-groups-0                1/1     Running   0          25m
appian-service-manager-notifications-0         1/1     Running   0          25m
appian-service-manager-notifications-email-0   1/1     Running   0          25m
appian-service-manager-portal-0                1/1     Running   0          25m
appian-service-manager-process-design-0        1/1     Running   0          25m
appian-webapp-0                                1/1     Running   0          25m
appian-zookeeper-0                             1/1     Running   0          25m

  3. In the command line, get the appians custom resource to check the status of your Appian site (replacing <MY_SITE_NAMESPACE> to match what you named your site):

    1

    kubectl get -n <MY_SITE_NAMESPACE> appians

    The STATUS of a starting site will change from not set to Creating to Starting to Ready. The transition from not set to Creating to Starting should happen within seconds. The transition from Starting to Ready should happen within 20 to 30 minutes.

    Make sure the STATUS is Ready before accessing your site, similar to:

    1
2

    NAME     URL                       STATUS   AGE
appian   http://myappiansite.com   Ready    25m

If you have any trouble with creating the Appian site, see Troubleshooting Appian on Kubernetes.

If you need to edit the Appian CR and restart, see Editing, Stopping, and Restarting).

6. Access your Appian site

Newly created sites are bootstrapped with a system administrator user. This user cannot access the Admin Console. The steps below detail how to login and create a new system administrator user that can access the Admin Console.

  1. In a browser, navigate to <URL>/suite/design/users where <URL> is the value you set in the .spec.url field of the Appian custom resource.
  2. Login as the bootstrap system administrator user with username Administrator and temporary password admin. Change the user's password when prompted.
  3. Click CREATE USER.
  4. Under Security > User Type, select System Administrator.
  5. If you haven't configured your site to send email, make sure to manually assign a temporary password. If you omit a temporary password, Appian will attempt to send an email to the specified email address with a randomly generated temporary password. Since the site has not yet been configured to send email, this will fail and there will be no way to recover the user's password.
  6. Logout and login as the newly created user.

Tip:  To stop the Appian site, see stopping the Appian site.

Feedback