Skip to main content

Configure TLS on Kubernetes

This page provides steps to configure TLS for your Appsmith deployment using a free Let's Encrypt certificate.

Prerequisites​

Before configuring SSL for your custom domain, ensure you have the following:

  1. A self-hosted Appsmith instance installed. If not already installed, refer to the installation guides. This guide assumes you are working with an existing installation.
  2. A custom domain purchased from a domain provider, such as:
  3. Ports 80 and 443 must be open and accessible. If using custom ports, ensure they are also open and accessible.
  4. Exposed your Kubernetes deployment to the internet. If not exposed, see theExpose K8s to Internet guide.

Configure TLS (HTTPS) with Let's Encrypt​

tip

If you see permission errors when running these commands on Google Kubernetes Engine (GKE), refer to the official cert-manager documentation on how to elevate your permissions.

Follow these steps to configure TLS:

  1. Get the LoadBalancer hostname with:
kubectl get svc --namespace ingress-nginx ingress-nginx-controller  -o jsonpath="{.status.loadBalancer.ingress[0].hostname}"

  1. Confirm that you can access your Appsmith instance by browsing the hostname.

  2. Create a CNAME record for the LoadBalancer hostname in your DNS configuration.

  3. Add the repository with:

helm repo add jetstack https://charts.jetstack.io
  1. Create a namespace for cert-manager with:
kubectl create namespace cert-manager
  1. Create custom resource definitions with:
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.3/cert-manager.crds.yaml
  1. Create a ClusterIssuer resource for Let's Encrypt certificates. Create a file with the below content. Replace the <EMAIL_ADDRESS> placeholder with a valid email address. Save the file as letsencrypt-appsmith.yaml.
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
  1. Apply the changes to the cluster with:
kubectl apply -f letsencrypt-appsmith.yaml
  1. Install cert-manager and set up Let's Encrypt as the default Certificate Authority (CA) with:
helm install cert-manager --namespace cert-manager jetstack/cert-manager --version v1.5.3
  1. Install Appsmith with integration to Ingress and cert-manager.

You can use the helm upgrade command in one of the two ways:

  • Use the below command to update Helm parameters. Replace <DOMAIN> with your domain name.
  helm upgrade appsmith appsmith-ee/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

  • Or use the values.yaml file to update parameters. Follow these steps to update:

    1. Open the values.yaml file, and make changes to the parameters as shown below:
    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"
    1. Run the below command once the parameter values are updated:
    helm upgrade -i appsmith -f values.yaml appsmith appsmith-ee/appsmith

You can now access Appsmith via a secure TLS connection with a valid Let's Encrypt certificate. Verify this by opening the site in a browser.

Troubleshooting​

You may face SSL/TLS certificate error while configuring SSL, follow the below guide to troubleshoot:

If you continue to face issues, contact the support team using the chat widget at the bottom right of this page.

See also​