Skip to main content

Kubernetes

Kubernetes (K8s) is an open source platform for managing, scaling, and automating the deployment of containerized applications. It's one of the most popular container orchestration tools. This guide helps you to install Appsmith on a Kubernetes cluster using the Helm package manager.

Prerequisites​

Before you install Appsmith, ensure the following are installed:

  1. Helm Package Manager - This is a package manager for Kubernetes clusters. It allows you to install and manage applications on Kubernetes clusters. To install Helm, follow the instructions for your platform from the official Helm documentation.

  2. kubectl - This is the command-line interface to manage resources on Kubernetes clusters. To install kubectl, follow the instructions for your platform from the official Kubernetes documentation.

Configure Kubernetes cluster​

Follow one of the available guidelines below to configure the Kubernetes cluster.

  1. Set up the Kubernetes cluster by creating a kubeconfig for Amazon EKS.
  2. Ensure that you have a default storage class running. If not, create default storage class
  3. The NGINX Ingress Controller is enabled by default. If not, install NGINX Controller for AWS EKS. Ensure that you enable the correct version for your cluster.

Install Appsmith​

You've installed and configured the Kubernetes cluster. Great, now go ahead and install Appsmith using Helm.

Follow the steps below to install Appsmith on your Kubernetes cluster:

  1. Download the values.yaml file, and place it into the Appsmith installation folder. Or, run the following cURL command:

      curl -L https://bit.ly/3ETEgPT -o "$PWD/values.yml"

  2. Add the Appsmith chart repository with:

    helm repo add appsmith https://helm.appsmith.com

  3. Load the Appsmith chart repository with:

    helm repo update

  4. Install Appsmith on your Kubernetes cluster using the Helm chart. Replace <your-namespace> with the namespace you want to install Appsmith in:

    helm install appsmith appsmith/appsmith --namespace <your-namespace>

When installing Appsmith using Helm, it automatically creates all the necessary Kubernetes objects to run the app on your clusters, such as pods, services, and ingresses with the default configuration. For more information on customizing the configuration, checkout the Configure Appsmith section.

  1. Verify the status of the Appsmith installation by running the following command:

    kubectl -n <your-namespace> rollout status deployment <release-name>-appsmith

    When the deployment is ready, a message that indicates the deployment of "appsmith" has been successfully rolled out is displayed.

  2. Access Appsmith by visiting the URL that was output by the Helm installation command. Use the kubectl command to get the URL. The URL has a hostname and port of the Appsmith ingress to access Appsmith using a web browser.

    kubectl -n <your-namespace> get ingress <release-name>-appsmith

Congratulations, you have successfully installed Appsmith on your Kubernetes cluster using Helm. For more detailed instructions and options for configuring the Appsmith Helm chart, see the Configure Appsmith section below.

Configure Appsmith​

The Appsmith installation works with the default configuration, but you also have the option to customize it to fit your specific needs. To configure the installation parameters, it's recommended to use the values.yaml file. This file allows you to specify the settings and options you want to use for your Appsmith installation, allowing you to tailor the installation to your needs. The following is a comprehensive list of available parameters.

Parameters​

Customize Appsmith by using either Helm parameters or Appsmith-specific parameters. The table below provides details on the various Helm and Appsmith parameters that are available for configuration.

Global​
NameDescriptionValue
global.namespaceOverrideOverride the namespace for resource deployed by the chart""
global.storageClassGlobal StorageClass for Persistent Volume""
Common​
NameDescriptionValue
fullnameOverrideString to fully override appsmith.name template""
containerNameSpecify container's name running in the pods"appsmith"
commonLabelsLabels to add to all deployed objects{}
commonAnnotationsAnnotations to add to all deployed objects{}
Appsmith image​
NameDescriptionValue
image.registryAppsmith image registryindex.docker.io
image.repositoryAppsmith image repositoryappsmith/appsmith-editor
image.tagAppsmith image taglatest
image.pullPolicyAppsmith image pull policyIfNotPresent
Appsmith deployment​
NameDescriptionValue
strategyTypeAppsmith deployment strategy typeRollingUpdate
schedulerNameAlternate scheduler""
podAnnotationsAnnotations for Appsmith pods{}
podSecurityContextAppsmith pods security context{}
securityContextSet security context{}
resources.limitsThe resources limits for the Appsmith container{}
resources.requestsThe requested resources for the Appsmith container{}
nodeSelectorNode labels for pod assignment{}
tolerationsTolerations for pod assignment[]
affinityAffinity fod pod assignment{}
Appsmith namespace​
NameDescriptionValue
namespace.createEnable creation of Namespacetrue
Appsmith service account​
NameDescriptionValue
serviceAccount.createEnable creation of ServiceAccount for Appsmith podstrue
serviceAccount.nameName of the created ServiceAccount . If not set, a name is generated using the appsmith.fullname template""
serviceAccount.annotationsAdditional service account annotations{}
Traffic exposure​
NameDescriptionValue
service.typeAppsmith service typeClusterIP
service.portAppsmith service port80
service.portNameAppsmith service port nameappsmith
service.nodePortAppsmith service node port to expose to expose8000
service.clusterIPAppsmith service Cluster""
service.loadBalancerIPAppsmith service Load Balancer IP""
service.loadBalancerSourceRangesAppsmith service Load Balancer sources[]
service.annotationsAdditional custom annotations for Appsmith service{}
ingress.enabledEnable ingress record generation for Appsmithfalse
ingress.hostsAn array of hosts to be covered with the ingress record[]
ingress.tlsEnable TLS configuration for the hosts defined at ingress.hosts parameterfalse
ingress.secretsCustom TLS certificates as secrets[]
ingress.certManagerEnable ingress to use TLS certificates provided by Cert Managerfalse
ingress.certManagerTlsSpecify TLS secret resources created by Cert Manager[]
ingress.classNameConfigure Ingress class that being used in ingress resource""
Persistence​
NameDescriptionValue
persistence.enabledEnable persistence using Persistent Volume Claimstrue
persistence.storageClassPersistent Volume storage class""
persistence.annotationsAdditional custom annotations for the PVC{}
persistence.localStorageEnable persistent volume using local storagefalse
persistence.storagePathLocal storage Path/tmp/hostpath_pv
persistence.localClusterLocal running cluster to provide storage space[minikube]
persistence.accessModesPersistent Volume access modes[ReadWriteOnce]
persistence.sizePersistent Volume size10Gi
storageClass.enabledEnable Storage Class configurationfalse
storageClass.defaultClassCreate default Storage Classfalse
storageClass.bindingModeBinding mode for Persistent Volume Claims using Storage ClassImmediate
storageClass.allowVolumeExpansionAllow expansion of Persistent Volume Claims using Storage Classtrue
storageClass.reclaimPolicyConfigure the retention of the dynamically created Persistent VolumeDelete
storageClass.provisionerStorage Class provisioner""
storageClass.annotationsAdditional storage class annotations{}
storageClass.mountOptionsMount options used by Persistent Volumes{}
storageClass.parametersStorage Class parameters{}
Auto update image​
NameDescriptionValue
autoupdate.enabledEnable auto update Helm chart's imagetrue
autoupdate.schedulerSchedule time to run cron job to update image"0 * * * *"
Set parameters​

When using command, specify each parameter using --set key=value[,key=value] argument to helm install. For example, the below command deploys Appsmith and configures it to use the storage class name appsmith-pv. 

helm install \
--set persistence.storageClass=appsmith-pv \
  appsmith appsmith/appsmith

Similarly, run the below command if you wish to change the encryption salt configuration.

helm install \
--set applicationConfig.APPSMITH_ENCRYPTION_SALT=123 \
  appsmith appsmith/appsmith

Alternatively, use a values.yaml file. You can specify the parameter values needed for installing the chart. To change configurations specific to Appsmith update the values.yaml file. Listed below are available configurations for Appsmith.

NameValue
applicationConfig.APPSMITH_OAUTH2_GOOGLE_CLIENT_ID""
applicationConfig.APPSMITH_OAUTH2_GOOGLE_CLIENT_SECRET""
applicationConfig.APPSMITH_OAUTH2_GITHUB_CLIENT_ID""
applicationConfig.APPSMITH_OAUTH2_GITHUB_CLIENT_SECRET""
applicationConfig.APPSMITH_CLIENT_LOG_LEVEL""
applicationConfig.APPSMITH_GOOGLE_MAPS_API_KEY""
applicationConfig.APPSMITH_MAIL_ENABLED""
applicationConfig.APPSMITH_MAIL_HOST""
applicationConfig.APPSMITH_MAIL_PORT""
applicationConfig.APPSMITH_MAIL_USERNAME""
applicationConfig.APPSMITH_MAIL_PASSWORD""
applicationConfig.APPSMITH_MAIL_FROM""
applicationConfig.APPSMITH_REPLY_TO""
applicationConfig.APPSMITH_MAIL_SMTP_AUTH""
applicationConfig.APPSMITH_MAIL_SMTP_TLS_ENABLED""
applicationConfig.APPSMITH_DISABLE_TELEMETRY""
applicationConfig.APPSMITH_RECAPTCHA_SITE_KEY""
applicationConfig.APPSMITH_RECAPTCHA_SECRET_KEY""
applicationConfig.APPSMITH_RECAPTCHA_ENABLED""
applicationConfig.APPSMITH_MONGODB_URI""
applicationConfig.APPSMITH_REDIS_URL""
applicationConfig.APPSMITH_ENCRYPTION_PASSWORD""
applicationConfig.APPSMITH_ENCRYPTION_SALT""
applicationConfig.APPSMITH_CUSTOM_DOMAIN""

Once you have made changes to the values file, run the below command.

helm install appsmith appsmith/appsmith -f values.yaml

Update Appsmith​

Appsmith installation can be updated manually or by enabling auto update.

Auto update​

The default Appsmith helm installation disables auto update (recommended). You have an option to enable auto update by either setting it in values file or using a command.

  • Values file: Ensure that the parameters are configured to enable auto update. For more information, see Auto update image. Once the set up is in place, run the below command.

      helm upgrade --values values.yaml appsmith appsmith/appsmith

  • Command: Pass an argument using the --set keyword (--set autoupdate.enabled=true) to the command.

      helm install appsmith/appsmith appsmith \
        --set autoupdate.enabled=true
Manual update​

To manually update the Appsmith container image to the latest release, run the command: 

kubectl rollout restart statefulset appsmith

Publish Appsmith​

To make your Appsmith installation accessible on the internet, you need an Ingress controller set up. For more information on Ingress controllers, see the Configure Kubernetes Cluster section. If you haven't yet installed the Helm chart, you can run the following command to install the chart, enable the ingress controller, and publish Appsmith.

To install the Nginx ingress controller on AWS-EKS, GCE-GKE, or Azure, run the following command if it hasn't already been installed:

 helm install ingress-nginx ingress-nginx/ingress-nginx
Enable the ingress controller through command or by modifying the `values.yaml` file.
Follow the steps below to configure using command
Run the below command to enable ingress controller:
helm upgrade appsmith/appsmith \
    --set ingress.enabled=true \
    --set ingress.className=nginx \
    --set service.type=ClusterIP \
Follow the steps below to configure using `values.yaml`

Open the values.yaml file and update the parameter values as below:

ingress:
  ## @param ingress.enabled Enable ingress record generation for Ghost
  ##
  enabled: true
  ## @param ingress.annotations Additional custom annotations for the ingress record
  ## NOTE: If `ingress.certManager=true`, annotation `kubernetes.io/tls-acme: "true"` will automatically be added
  ##
  className: nginx
  hosts: []
    # - host: appsmith-domain.me
service:
  ## @param service.type Kubernetes Service type
  ##
  type: ClusterIP

Once the parameter values are modified, run the below command:

helm upgrade --values values.yaml appsmith appsmith/appsmith

  • It takes a few minutes for the ingress to get a public IP assigned. Once it has been assigned, you should see an IPv4 address or a domain name in the ADDRESS column. Run the below command to get this address:

    kubectl get ingress

    The command generates the output as shown below:

    NAME       CLASS   HOSTS   ADDRESS                                                                    PORTS   AGE
    appsmith   nginx   *       a918d94876c27453ea78d2883539bb36-1165345706.ap-south-1.elb.amazonaws.com   80      25h

Configure TLS​

To ensure the security of your Appsmith application, it's recommended to use TLS certificates. One way to do this is by using Cert Manager. Cert Manager secures HTTP traffic with TLS and SSL certificates. The Appsmith Helm chart comes with built-in support for Ingress routes and certificate management through cert-manager. This makes it easy to configure TLS support using certificates from a variety of certificate providers, including Let's Encrypt.

The steps below explain how to use Ingress routes and cert-manager to configure TLS for your Appsmith deployment using a free Let's Encrypt certificate:

tip

When executing these commands on Google Kubernetes Engine (GKE), you may encounter permission errors. Refer to the official cert-manager documentation for notes on how to elevate your permissions.*

  1. Obtain the LoadBalancer host name using the command below. Note this host name as you need it to configure DNS in a later step.

    kubectl get svc --namespace ingress-nginx ingress-nginx-controller  -o jsonpath="{.status.loadBalancer.ingress[0].hostname}"

  2. Browse to the host name and confirm that you can access your Appsmith instance. This indicates that the NGINX Ingress controller is working.

  3. Configure the DNS for your domain name by adding a CNAME record pointing to the public host name obtained in the previous steps.

  4. To use cert-manager, add the repository, create a namespace, and create CRDs. i. Add the repository by running below command:

    helm repo add jetstack https://charts.jetstack.io

    ii. Create a namespace by running below command:

    kubectl create namespace cert-manager

    iii. Create CRDs by running below command:

    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.3/cert-manager.crds.yaml

  5. To create a ClusterIssuer resource for Let's Encrypt certificates, create a file named letsencrypt-appsmith.yaml with the following content, replacing the <EMAIL_ADDRESS> placeholder with a valid email address: 

    apiVersion: cert-manager.io/v1
    kind: ClusterIssuer
    metadata:
      name: letsencrypt-appsmith
    spec:
      acme:
        email: <EMAIL_ADDRESS>
        server: https://acme-v02.api.letsencrypt.org/directory
        privateKeySecretRef:
          name: letsencrypt-appsmith
        solvers:
        - http01:
            ingress:
              class: nginx

  6. Apply the changes to the cluster:

    kubectl apply -f letsencrypt-appsmith.yaml

  7. Use Helm to install cert-manager and set up Let's Encrypt as the default Certificate Authority (CA).

    helm install cert-manager --namespace cert-manager jetstack/cert-manager --version v1.5.3

  8. Install Appsmith with integration to Ingress and cert-manager.

You can either use a command or add additional parameters to the `values.yaml` file.
Follow the below steps to configure using a command
You can use the Helm chart with the following additional parameters. Replace the DOMAIN placeholder with your specific domain name in the below command and run it:
  ```bash
    helm upgrade appsmith appsmith/appsmith \
      --set service.type=ClusterIP \
      --set ingress.enabled=true \
      --set ingress.tls=true \
      --set ingress.certManager=true \
      --set ingress.annotations."cert-manager\.io/cluster-issuer"=letsencrypt-appsmith \
      --set ingress.hosts[0].host=<DOMAIN> \
      --set ingress.certManagerTls[0].hosts[0]=<DOMAIN> \
      --set ingress.certManagerTls[0].secretName=letsencrypt-appsmith
      --set ingress.className=nginx
  ```
Follow the below steps to configure using a `values.yaml` file
Open the `values.yaml` file, and update the parameters as shown below: Run the below command once the parameter values are updated:
  ```bash
  ingress:
      enabled: true
      annotations:
        cert-manager.io/cluster-issuer: "letsencrypt-appsmith"
      hosts:
        - host: example.appsmith.com
      tls: true
      secrets: []
      certManager: true
      certManagerTls:
        - hosts:
            - example.appsmith.com
          secretName: letsencrypt-appsmith
      className: "nginx"
  ```
  Run the below command once the parameter values are updated:

  ```bash
  helm upgrade --values values.yaml appsmith appsmith/appsmith
  ```

Once the deployment is finished, check the domain in a browser to verify that the Appsmith site is accessible over a secure TLS connection with a valid Let's Encrypt certificate.

Enable data compression for Ingress controller​

The default installation doesn't have data compression configured for Nginx ingress controller. Follow the below steps to enable it.

  1. Edit the configMap for ingress-nginx-controller by using the below command.

    kubectl edit configmap -n ingress-nginx ingress-nginx-controller

  2. Add the following to the data section.

    # Add the data section if not already present
    data: 
      use-gzip: "true" # ENABLE GZIP COMPRESSION
      gzip-types: "*" # SPECIFY MIME TYPES TO COMPRESS ("*" FOR ALL)

The Nginx controller automatically updates once you save (:wq!) the changes.

Uninstall Appsmith​

The following command uninstalls Appsmith and removes all Kubernetes resources associated with the chart:

  1. List the releases by running below command:
helm list

The command generates the output as shown below:

NAME                       NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
#highlight-next-line
appsmith-1631069261        default         1               2021-09-09 11:24:40.152766 +0700 +07    deployed        appsmith-1.3.0  1.16.0
  1. Pick the release name appsmith-1631069261 and run the below command to uninstall Appsmith:
helm uninstall appsmith-1631069261
  1. Run the command to verify the release status for appsmith-1631069261
helm status <RELEASE_NAME>

Troubleshooting​

If you’re having issues with the deployment, please see the debugging deployment errors troubleshooting guide. If you continue to have problems reach out on Discord Server or send an email to support or ask questions on the community forum.

Further reading​