OverviewCopy link to clipboard
This page walks through how to edit the Appian custom resource (CR) and stop and start Appian on Kubernetes for self-managed customers. It looks at cases for when to do a full restart after updating the custom resource (CR), or when changes can be done on the fly.
Editing and restarting AppianCopy link to clipboard
Typically when a change is made to a running Kubernetes custom resource, the corresponding operator automatically reconciles that change to the Kubernetes resources it manages. See What is the Appian Operator? to understand the relationship between a custom resource and an operator. Due to product constraints, there are many fields in the Appian custom resource that once initially set, cannot be changed without some sort of restart and downtime.
Changes that require a full restartCopy link to clipboard
Configurations that can’t be changed without a restart are documented in the Appian CRD docs as immutable
. They include things like Pod resource configurations, topology configurations for Appian services, and site data sources.
Immutable property changes require Stopping the Appian site, editing your custom resource, and Restarting the Appian site.
Note: In order to prevent users from inadvertently changing a field in the Appian custom resource that would cause a problem with the product, the Appian operator has a validating webhook that prevents immutable
fields from being changed. The validating webhook is only enabled when webhooks.enabled is set to true in the Appian operator’s Helm values.
Changes that can be made to a running siteCopy link to clipboard
Site configurations that can be made without restarts include any properties in the Appian CRD docs not marked as immutable
. For these, you can edit the existing Appian custom resource with the following command.
1
kubectl -n <NAMESPACE> edit appians <APPIAN>
Copy
Once changed, Kubernetes will work to reconcile the change for the Appian custom resource.
Changes to Custom PropertiesCopy link to clipboard
You can change Appian’s custom.properties file by updating the customProperties key-value pairs inside the Appian CRD. The key-value pairs are then injected into the custom.properties
file shared by all components. Note that there are a few Unsupported Custom Properties in Appian on Kubernetes.
Changes to customProperties
can be made without a full restart of Appian. After making the changes to the running site, you can check that the corresponding custom.properties
file on the webapp pod has been fully updated using the following command.
1
kubectl -n <NAMESPACE> exec <WEBAPP POD> -- cat /usr/local/appian/ae/conf/custom.properties
Copy
Some custom.property changes require a restart of the Application Server (webapp component). For custom property changes that require an Application Server restart, you can delete your webapp pod(s) to initiate a restart of just this one component.
1
kubectl -n <NAMESPACE> delete pod <WEBAPP POD>
Copy
After deleting the Webapp pod, the StatefulSet that backs the Webapp pod will automatically recreate it and the Webapp pod will have the configuration updates.
Stopping the Appian siteCopy link to clipboard
The following steps will stop all components of the Appian site.
Note: Because most Appian components are StatefulSets with PersistentVolumesClaims, the component data is persisted when shutting down Appian. The Appian site can then be restarted without data loss.
-
Get the name of your Appian site.
1
kubectl get -n <NAMESPACE> appians
CopyOutput should be similar to:
1 2
NAME URL STATUS AGE appian http://myappiansite.com Ready 25m
Copy -
If you intend to restart the Appian site, make sure you have a copy of the existing Appian custom resource definition somewhere on your computer before shutting down (for example,
appian.yaml
). You will need it to restart the site. You can use the following command to print out the current appian custom resource definition.1
kubectl -n <NAMESPACE> get appian <APPIAN NAME> -oyaml
CopyCopy the output and save as a YAML file.
-
Delete the Appian site.
1
kubectl delete -n <NAMESPACE> appian <APPIAN NAME>
CopyFor example:
1
kubectl delete -n my-site-namespace appian appian
CopyShutdown can take some time and is a synchronous operation, so this command may appear to hang.
-
Confirm the Appian site was deleted with the following commands.
1
kubectl -n <NAMESPACE> get pods
Copy1
kubectl -n <NAMESPACE> get appians
CopyAll Appian component pods should now be deleted. Output from running the
get appians
command should be:1
No resources found in <NAMESPACE> namespace.
Copy
If your site has issues shutting down, follow the steps in Troubleshooting site shutdown to debug.
Restarting the Appian siteCopy link to clipboard
Having stopped the Appian site, you can restart as follows.
-
Make any desired changes to the Appian custom resource YAML file.
-
Run
kubectl apply
to restart the site with the changes:1
kubectl apply -n <NAMESPACE> -f appian.yaml
Copy -
It will take about 20 minutes for the Appian site to fully recover. Check progress on the various Appian component pods with the following command.
1
kubectl -n <NAMESPACE> get pods
CopyThe STATUS of the Appian component pods will transition from
Creating
toStarting
toRunning
. When the Appian site is ready, you should see all pods have READY of1/1
and STATUS ofRunning
, 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
Copy
If you have any trouble with creating the Appian site, see Troubleshooting site startup.
Restarting the webapp componentCopy link to clipboard
You may need to restart the webapp component in the course of updating configurations such as changes to customProperties.
To restart the webapp component, delete its pod(s).
1
kubectl -n <NAMESPACE> delete pod <WEBAPP POD>
Copy
After deleting, Kubernetes will immediately start a new Pod that will take on any configuration changes.
Caution: This type of restart is only safe to do for the webapp component. If you need to change the configuration specific to any other component, we recommend doing a site restart to apply the changes.
Fully deleting the Appian siteCopy link to clipboard
To fully delete the Appian site on Kubernetes, including all data, you will need to delete the PersistentVolumes that are attached to the StatefulSets.
- Follow the steps to Stop Appian.
-
Get the existing PersistentVolumeClaims on the Appian namespace.
1
kubectl -n <NAMESPACE> get persistentvolumeclaim
Copy -
For each Appian component that has a PersistentVolumeClaim (PVC), delete it with the following command.
1
kubectl -n <NAMESPACE> delete persistentvolumeclaim <APPIAN COMPONENT PVC>
Copy -
Depending on how the PVC’s reclaim policy is set up, deleting the PersistentVolumeClaim will in turn delete the PersistentVolume. Check that the Appian component PersistentVolumes were deleted with the following command.
1
kubectl -n <NAMESPACE> get persistentvolume
CopyIf any PersistentVolumes for Appian components still exist, you’ll want to delete each of them with the following command.
1
kubectl -n <NAMESPACE> delete persistentvolume <APPIAN COMPONENT PV>
Copy
Uninstalling the Appian operatorCopy link to clipboard
-
Uninstall the Appian operator via
helm uninstall
:1
helm --namespace appian-operator uninstall appian-operator --wait
Copy -
Delete the
appian-operator
namespace1
kubectl delete namespace appian-operator
Copy -
Delete the Appian custom resource definition (CRD):
1
kubectl delete crd appians.crd.k8s.appian.com
Copy
Starting the Appian operatorCopy link to clipboard
To start the Appian operator, see the instructions to Create the Appian operator.