From a80d26f980ce53f9d8f26b98d08ee36f408cd6b6 Mon Sep 17 00:00:00 2001 From: Goutham Pratapa Date: Mon, 18 Aug 2025 14:04:21 +0530 Subject: [PATCH 1/3] chore: update documentation for appsmith on azure HA --- .../azure/aks-high-availability.mdx | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx diff --git a/website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx b/website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx new file mode 100644 index 0000000000..9b1f812590 --- /dev/null +++ b/website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx @@ -0,0 +1,215 @@ +--- +description: Deploy Appsmith with High Availability on Azure Kubernetes Service (AKS) +title: Azure AKS High Availability +hide_title: true +sidebar_position: 2 +toc_max_heading_level: 2 +--- + + + +
+

High Availability on Azure AKS

+ + + +
+ + + +This guide explains how to deploy Appsmith on an Azure Kubernetes Service (AKS) cluster with High Availability. High availability ensures that your Appsmith instance remains accessible without interruption, even during system disruptions. + +## Prerequisites + +Before setting up high availability for Appsmith on Azure AKS, ensure the following requirements are met: + +- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure) installed and logged in +- [Helm](https://helm.sh/docs/intro/install/) installed and configured +- Access to the Appsmith Helm repository +- An active [Azure subscription](https://azure.com/free) +- At least 2 GB of free storage available for backup and update tasks + +## Configure variables + +Update the following values starting with 'my' where necessary, and enter them in your shell/terminal: + +```bash +RESOURCE_GROUP="myResourceGroup" +LOCATION="centralindia" +STORAGE_ACCOUNT_NAME="mystorageaccount$RANDOM" +SHARE_NAME="myFileShareName" +AKS_NAME="myAppsmithAKS" +``` + +## 1. Create Resource Group + +Create a resource group to organize your Azure resources: + +```bash +az group create --name $RESOURCE_GROUP --location $LOCATION +``` + +## 2. Create Azure File System + +Create an Azure Storage Account and File Share for persistent storage: + +```bash +# Create storage account +az storage account create \ + --resource-group $RESOURCE_GROUP \ + --name $STORAGE_ACCOUNT_NAME \ + --location $LOCATION \ + --sku Standard_LRS + +# Create file share +az storage share-rm create \ + --storage-account $STORAGE_ACCOUNT_NAME \ + --name $SHARE_NAME \ + --quota 100 +``` + +## 3. Create AKS Cluster + +Create an AKS cluster with the necessary configuration for high availability: + +```bash +az aks create \ + --resource-group $RESOURCE_GROUP \ + --name $AKS_NAME \ + --node-count 1 \ + --node-vm-size Standard_B4ms \ + --generate-ssh-keys \ + --location $LOCATION +``` + +:::note +For production environments, consider using multiple nodes and larger VM sizes for better performance and availability. +::: + +## 4. Create Persistent Volume Claim (PVC) + +Create a file named `pvc-azurefile-csi.yaml`: + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: pvc-azurefile +spec: + accessModes: + - ReadWriteMany + resources: + requests: + storage: 100Gi + storageClassName: azurefile-csi +``` + +Apply the PVC to your cluster: + +```bash +kubectl apply -f pvc-azurefile-csi.yaml +``` + +## 5. Get PVC and PV Information + +Retrieve the Persistent Volume information: + +```bash +kubectl get pvc pvc-azurefile +kubectl describe pvc pvc-azurefile | grep VolumeName +``` + +Note the VolumeName from the output - you'll need this for the next step. + +## 6. Get Appsmith Helm Values + +Download the default Helm values for Appsmith: + +```bash +helm show values appsmith-ee/appsmith > values.yaml +``` + +Update the `values.yaml` file with the obtained PVC and PV values: + +```yaml +existingClaim: + enabled: true + name: + claimName: pvc-azurefile +``` + +Replace `` with the actual VolumeName you obtained in step 5. + +## 7. Install Appsmith with Helm + +Install Appsmith using Helm with the configured values: + +```bash +helm upgrade -i appsmith appsmith-ee/appsmith \ + -n appsmith-ee \ + --create-namespace \ + -f values.yaml +``` + +## Verification + +Verify that Appsmith is running correctly: + +```bash +kubectl get pods -n appsmith-ee +kubectl get svc -n appsmith-ee +``` + +Appsmith should now be running in HA mode on your AKS cluster. + +## Post-installation configuration + +Once you have completed the installation process, consider performing the tasks below to configure and manage your Appsmith instance, enhancing its security and performance, specifically if it's intended for production use. + +
+
+ +
+
+ Configure Single Sign-on (SSO) +
+
+
+ Set up authentication with your identity provider for secure access to Appsmith. +
+ + +
+
+ Configure Custom Domain +
+
+
+ Set up a custom domain for your Appsmith instance to improve branding and user experience. +
+ + +
+
+ Configure Email +
+
+
+ Configure email settings to enable user invitations and notifications. +
+ +
+ +## Troubleshooting + +If you encounter issues during installation, refer to the [troubleshooting guide](/help-and-support/troubleshooting-guide) for common solutions and error resolutions. + +## Related + +- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes) +- [High Availability on AWS EKS](/getting-started/setup/installation-guides/kubernetes/configure-high-availability) +- [Azure Container Instance](/getting-started/setup/installation-guides/azure-aci) From c8c727ce2a4890eabe8397950b07c9d0df8a973e Mon Sep 17 00:00:00 2001 From: Goutham Pratapa Date: Mon, 18 Aug 2025 14:18:53 +0530 Subject: [PATCH 2/3] feat(installation-guides): add Azure AKS deployment guide and update README --- .../setup/installation-guides/README.md | 13 + .../setup/installation-guides/azure-aks.md | 258 ++++++++++++++++++ .../azure/aks-high-availability.mdx | 215 --------------- 3 files changed, 271 insertions(+), 215 deletions(-) create mode 100644 website/docs/getting-started/setup/installation-guides/azure-aks.md delete mode 100644 website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx diff --git a/website/docs/getting-started/setup/installation-guides/README.md b/website/docs/getting-started/setup/installation-guides/README.md index d4f8bce9b9..fa988750b4 100644 --- a/website/docs/getting-started/setup/installation-guides/README.md +++ b/website/docs/getting-started/setup/installation-guides/README.md @@ -96,6 +96,19 @@ Choose from the following guides to deploy Appsmith according to your business n Deploy Appsmith on Azure Container Instances (ACI) for a simplified container setup with minimal operational overhead. + + +
+ Azure Kubernetes Service logo +
+ Azure Kubernetes Service (AKS) +
+
+
+
+ Deploy Appsmith on Azure Kubernetes Service (AKS) for scalable, managed Kubernetes deployments with enterprise-grade features. +
+
diff --git a/website/docs/getting-started/setup/installation-guides/azure-aks.md b/website/docs/getting-started/setup/installation-guides/azure-aks.md new file mode 100644 index 0000000000..b4fe98e78e --- /dev/null +++ b/website/docs/getting-started/setup/installation-guides/azure-aks.md @@ -0,0 +1,258 @@ +--- +description: Deploy Appsmith on Azure Kubernetes Service (AKS) +sidebar_position: 5 +toc_max_heading_level: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Azure Kubernetes Service + +Azure Kubernetes Service (AKS) is a managed Kubernetes service that simplifies deploying, managing, and scaling containerized applications. This document guides you through deploying Appsmith on AKS using Helm charts. The data persists in Azure Storage Account File Share. + +:::note +Azure only supports CIFS file shares and doesn't support NFS file shares. +::: + +## Prerequisites​ + +Before deploying Appsmith on AKS, you need to have an Azure subscription and the necessary tools installed on your machine. + +- [Azure Subscription](https://azure.com/free) - If you don't have an Azure subscription, you can sign up for a free trial. +- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure). +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) - Kubernetes command-line tool. +- [Helm](https://helm.sh/docs/intro/install/) - Kubernetes package manager. +- Whitelist `cs.appsmith.com` in your firewall settings to allow outbound HTTPS traffic. If using Azure Firewall, add these domains under Application Rules. + +## Configure variables + +Update the following values starting with 'my' where necessary, and enter them in your shell/terminal. + +```bash +resourceGroupName="myResourceGroup" +aksName="myAppsmithAKS" +storageAccountName="mystorageaccount$RANDOM" +aksLocation="southindia" +fileShareName="myFileShareName" +``` + +### Create a resource group (optional) + +You can skip this step if you want to use an existing resource group. + +```bash +az group create --name $resourceGroupName --location $aksLocation +``` + +### Create a storage account (optional) + +You can skip this step if you want to use an existing storage account. + +```bash +az storage account create --resource-group $resourceGroupName --name $storageAccountName --location $aksLocation --sku Standard_LRS +``` + +### Create a file share + +```bash +az storage share-rm create --storage-account $storageAccountName --name $fileShareName --quota 100 +``` + +### Create AKS cluster + +```bash +az aks create \ + --resource-group $resourceGroupName \ + --name $aksName \ + --node-count 1 \ + --node-vm-size Standard_B4ms \ + --generate-ssh-keys \ + --location $aksLocation +``` + +### Get credentials for your cluster + +```bash +az aks get-credentials --resource-group $resourceGroupName --name $aksName +``` + +## Install Appsmith + +### Create Persistent Volume Claim (PVC) + +Create a file named `pvc-azurefile-csi.yaml`: + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: pvc-azurefile +spec: + accessModes: + - ReadWriteMany + resources: + requests: + storage: 100Gi + storageClassName: azurefile-csi +``` + +Apply the PVC to your cluster: + +```bash +kubectl apply -f pvc-azurefile-csi.yaml +``` + +### Get PVC and PV Information + +Retrieve the Persistent Volume information: + +```bash +kubectl get pvc pvc-azurefile +kubectl describe pvc pvc-azurefile | grep VolumeName +``` + +Note the VolumeName from the output - you'll need this for the next step. + +### Get Appsmith Helm Values + +Download the default Helm values for Appsmith: + +```bash +helm show values appsmith-ee/appsmith > values.yaml +``` + +Update the `values.yaml` file with the obtained PVC and PV values: + +```yaml +existingClaim: + enabled: true + name: + claimName: pvc-azurefile +``` + +Replace `` with the actual VolumeName you obtained in the previous step. + +### Install Appsmith with Helm + +Install Appsmith using Helm with the configured values: + +```bash +helm upgrade -i appsmith appsmith-ee/appsmith \ + -n appsmith-ee \ + --create-namespace \ + -f values.yaml +``` + +## Install Appsmith Community + +To install the Appsmith open source edition (Appsmith Community), replace `appsmith-ee` with `appsmith-ce` in the Helm installation command: + +```bash +helm upgrade -i appsmith appsmith-ce/appsmith \ + -n appsmith-ce \ + --create-namespace \ + -f values.yaml +``` + +## Post-installation configuration + +Once you have completed the installation process, consider performing the tasks below to configure and manage your Appsmith instance, enhancing its security and performance, specifically if it's intended for production use. +
+ + + + +## Best Practices & Things Not to Do When Deploying Appsmith on Azure AKS + +When deploying **Appsmith** on **Azure Kubernetes Service (AKS)**, it's crucial to avoid certain architectural decisions that can lead to performance issues, data inconsistency, or outright application failure. The following anti-patterns are particularly relevant when using Azure Files or network-mounted file systems. + +### Avoid Using Azure Files (or Any Network-Mounted File System) for Appsmith Storage + +While Azure Files offers a convenient way to persist data, it is **not suitable** for hosting Appsmith's core components such as MongoDB, Redis, or internal file storage. + +#### Common Mistakes + +1. **Running internal MongoDB, Redis, or file storage on Azure Files** + - Appsmith is not designed to work efficiently with network-mounted volumes as primary persistent stores. + - Issues observed: + - Sluggish performance. + - Data corruption. + - Intermittent failures and inconsistencies. + - App crashes on startup or under load. + +2. **Using Azure Files to store runtime data for internal services** + - These services (MongoDB, Redis) are latency-sensitive and require fast local or SSD-backed storage to function properly. + +#### Recommended Approach + +To ensure a **stateless, reliable, and production-grade deployment**, follow these best practices: + +- **Run Appsmith container on AKS using Azure Files only for minimal required mounts** (e.g., config files, if needed). +- **Use external managed services** for critical components: + - [**MongoDB**](/getting-started/setup/instance-configuration/custom-mongodb-redis): Use a cloud-managed MongoDB (e.g., MongoDB Atlas) hosted in Azure or nearby region. + - [**Redis**](/getting-started/setup/instance-configuration/external-redis): Use **Azure Cache for Redis** or provision your own Redis cluster. + - [**PostgreSQL**](/getting-started/setup/instance-configuration/external-postgresql-rds): Use **Azure Database for PostgreSQL** to support advanced features like **Workflows** and **SAML SSO**. + +This approach ensures your Appsmith instance is: + +- **Stateless** +- **Easy to scale and recover** +- **Less prone to I/O bottlenecks and crashes** + +## Troubleshooting + +If you are facing issues during deployment, refer to the guide on [troubleshooting deployment errors](/help-and-support/troubleshooting-guide/deployment-errors). If you continue to face issues, contact the support team using the chat widget at the bottom right of this page. + +### See also + +- [Manage Installation](/getting-started/setup/instance-configuration): Learn how to manage your Appsmith instance. +- [Upgrade Installation Guides](/getting-started/setup/instance-management/): Learn how to upgrade your Appsmith installation. \ No newline at end of file diff --git a/website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx b/website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx deleted file mode 100644 index 9b1f812590..0000000000 --- a/website/docs/getting-started/setup/installation-guides/azure/aks-high-availability.mdx +++ /dev/null @@ -1,215 +0,0 @@ ---- -description: Deploy Appsmith with High Availability on Azure Kubernetes Service (AKS) -title: Azure AKS High Availability -hide_title: true -sidebar_position: 2 -toc_max_heading_level: 2 ---- - - - -
-

High Availability on Azure AKS

- - - -
- - - -This guide explains how to deploy Appsmith on an Azure Kubernetes Service (AKS) cluster with High Availability. High availability ensures that your Appsmith instance remains accessible without interruption, even during system disruptions. - -## Prerequisites - -Before setting up high availability for Appsmith on Azure AKS, ensure the following requirements are met: - -- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure) installed and logged in -- [Helm](https://helm.sh/docs/intro/install/) installed and configured -- Access to the Appsmith Helm repository -- An active [Azure subscription](https://azure.com/free) -- At least 2 GB of free storage available for backup and update tasks - -## Configure variables - -Update the following values starting with 'my' where necessary, and enter them in your shell/terminal: - -```bash -RESOURCE_GROUP="myResourceGroup" -LOCATION="centralindia" -STORAGE_ACCOUNT_NAME="mystorageaccount$RANDOM" -SHARE_NAME="myFileShareName" -AKS_NAME="myAppsmithAKS" -``` - -## 1. Create Resource Group - -Create a resource group to organize your Azure resources: - -```bash -az group create --name $RESOURCE_GROUP --location $LOCATION -``` - -## 2. Create Azure File System - -Create an Azure Storage Account and File Share for persistent storage: - -```bash -# Create storage account -az storage account create \ - --resource-group $RESOURCE_GROUP \ - --name $STORAGE_ACCOUNT_NAME \ - --location $LOCATION \ - --sku Standard_LRS - -# Create file share -az storage share-rm create \ - --storage-account $STORAGE_ACCOUNT_NAME \ - --name $SHARE_NAME \ - --quota 100 -``` - -## 3. Create AKS Cluster - -Create an AKS cluster with the necessary configuration for high availability: - -```bash -az aks create \ - --resource-group $RESOURCE_GROUP \ - --name $AKS_NAME \ - --node-count 1 \ - --node-vm-size Standard_B4ms \ - --generate-ssh-keys \ - --location $LOCATION -``` - -:::note -For production environments, consider using multiple nodes and larger VM sizes for better performance and availability. -::: - -## 4. Create Persistent Volume Claim (PVC) - -Create a file named `pvc-azurefile-csi.yaml`: - -```yaml -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: pvc-azurefile -spec: - accessModes: - - ReadWriteMany - resources: - requests: - storage: 100Gi - storageClassName: azurefile-csi -``` - -Apply the PVC to your cluster: - -```bash -kubectl apply -f pvc-azurefile-csi.yaml -``` - -## 5. Get PVC and PV Information - -Retrieve the Persistent Volume information: - -```bash -kubectl get pvc pvc-azurefile -kubectl describe pvc pvc-azurefile | grep VolumeName -``` - -Note the VolumeName from the output - you'll need this for the next step. - -## 6. Get Appsmith Helm Values - -Download the default Helm values for Appsmith: - -```bash -helm show values appsmith-ee/appsmith > values.yaml -``` - -Update the `values.yaml` file with the obtained PVC and PV values: - -```yaml -existingClaim: - enabled: true - name: - claimName: pvc-azurefile -``` - -Replace `` with the actual VolumeName you obtained in step 5. - -## 7. Install Appsmith with Helm - -Install Appsmith using Helm with the configured values: - -```bash -helm upgrade -i appsmith appsmith-ee/appsmith \ - -n appsmith-ee \ - --create-namespace \ - -f values.yaml -``` - -## Verification - -Verify that Appsmith is running correctly: - -```bash -kubectl get pods -n appsmith-ee -kubectl get svc -n appsmith-ee -``` - -Appsmith should now be running in HA mode on your AKS cluster. - -## Post-installation configuration - -Once you have completed the installation process, consider performing the tasks below to configure and manage your Appsmith instance, enhancing its security and performance, specifically if it's intended for production use. - -
- - -## Troubleshooting - -If you encounter issues during installation, refer to the [troubleshooting guide](/help-and-support/troubleshooting-guide) for common solutions and error resolutions. - -## Related - -- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes) -- [High Availability on AWS EKS](/getting-started/setup/installation-guides/kubernetes/configure-high-availability) -- [Azure Container Instance](/getting-started/setup/installation-guides/azure-aci) From 01316dffbdc88bf66eda89ebebdc1d52f057677e Mon Sep 17 00:00:00 2001 From: Goutham Pratapa Date: Mon, 18 Aug 2025 14:29:11 +0530 Subject: [PATCH 3/3] feat(installation-guides): add Azure AKS deployment guide and update README for new guide --- .../setup/installation-guides/README.md | 28 +++++++++---------- .../{azure-aks.md => azure-aks.mdx} | 0 2 files changed, 14 insertions(+), 14 deletions(-) rename website/docs/getting-started/setup/installation-guides/{azure-aks.md => azure-aks.mdx} (100%) diff --git a/website/docs/getting-started/setup/installation-guides/README.md b/website/docs/getting-started/setup/installation-guides/README.md index fa988750b4..b2f5e405b5 100644 --- a/website/docs/getting-started/setup/installation-guides/README.md +++ b/website/docs/getting-started/setup/installation-guides/README.md @@ -68,45 +68,45 @@ Choose from the following guides to deploy Appsmith according to your business n Deploy Appsmith using AWS Elastic Container Service (ECS) on EC2 instances for reliable and flexible container management.
- -
- +
- AWS Fargate logo + Azure Kubernetes Service logo
- AWS ECS - Fargate + Azure Kubernetes Service (AKS)
- Run Appsmith on AWS ECS with Fargate for a serverless container experience without managing the underlying infrastructure. + Deploy Appsmith on Azure Kubernetes Service (AKS) for scalable, managed Kubernetes deployments with enterprise-grade features.
+
- +
+
- Azure Container Instances logo + AWS Fargate logo
- Azure Container Instance (ACI) + AWS ECS - Fargate
- Deploy Appsmith on Azure Container Instances (ACI) for a simplified container setup with minimal operational overhead. + Run Appsmith on AWS ECS with Fargate for a serverless container experience without managing the underlying infrastructure.
- +
- Azure Kubernetes Service logo + Azure Container Instances logo
- Azure Kubernetes Service (AKS) + Azure Container Instance (ACI)
- Deploy Appsmith on Azure Kubernetes Service (AKS) for scalable, managed Kubernetes deployments with enterprise-grade features. + Deploy Appsmith on Azure Container Instances (ACI) for a simplified container setup with minimal operational overhead.
diff --git a/website/docs/getting-started/setup/installation-guides/azure-aks.md b/website/docs/getting-started/setup/installation-guides/azure-aks.mdx similarity index 100% rename from website/docs/getting-started/setup/installation-guides/azure-aks.md rename to website/docs/getting-started/setup/installation-guides/azure-aks.mdx