Skip to main content

Migrate From Multi-Container Setup (k8s)

Migrating from a multi-container Kubernetes installation to a single-container Helm deployment can provide several benefits, including easier management and increased efficiency. You can make the transition and migrate your Appsmith deployment from the old stack (multiple pods/containers) Kubernetes to Helm chart(single container). The guide below covers the steps to help you successfully migrate to the Helm chart and works well with the default Kubernetes installation.

The migration works on the default Kubernetes installation with the resources as shown in the image below. Use the kubectl get all command to review the default Kubernetes installation resources.

➜ kubectl get all
pod/appsmith-editor-995c974df-njtdh 1/1 Running 0 3d12h
pod/appsmith-internal-server-dfd68b55b-8p5w8 1/1 Running 1 3d12h
pod/imago-27473940-kwslt 0/1 Completed 0 12m
pod/mongo-statefulset-0 1/1 Running 0 3d12h
pod/redis-statefulset-0 1/1 Running 0 3d12h

service/appsmith-backend-service NodePort <none> 8080:32694/TCP 3d12h
service/appsmith-editor ClusterIP <none> 80/TCP 3d12h
service/kubernetes ClusterIP <none> 443/TCP 3d12h
service/mongo-service NodePort <none> 27017:31766/TCP 3d12h
service/redis-service NodePort <none> 6379:30834/TCP 3d12h

deployment.apps/appsmith-editor 1/1 1 1 3d12h
deployment.apps/appsmith-internal-server 1/1 1 1 3d12h

replicaset.apps/appsmith-editor-995c974df 1 1 1 3d12h
replicaset.apps/appsmith-internal-server-dfd68b55b 1 1 1 3d12h

statefulset.apps/mongo-statefulset 1/1 3d12h
statefulset.apps/redis-statefulset 1/1 3d12h

cronjob.batch/imago 0 * * * * False 0 12m 3d12h

job.batch/imago-27473940 1/1 16s 12m


Before you start the migration process, ensure that the below prerequisites are met.

  1. Install kubectl - kubectl is the command-line interface for Kubernetes. It allows you to run commands against Kubernetes clusters to manage applications and other resources. To install kubectl, follow the instructions for your platform from the official Kubernetes documentation.
  2. Once kubectl is installed, configure it to connect to your cluster. Follow one of the available guides below for your platform:
  3. Install yq package: yq package is needed to format data from the ConfigMap resources into a .yaml file referenced in migration configurations.

Migrate to a single container

Migrating from a multi-container Kubernetes installation to a new cluster involves exporting your data and configuration, setting up the new cluster, and migrating your applications and services to the new environment. Here are the steps to do this:

Export database

Export data from the existing MongoDB pod and download the archive file to your local. Follow the steps below to backup a database:

  1. Create the backup directory in the MongoDB pod.
    kubectl exec mongo-statefulset-0 -- mkdir -pv /data/db/backup
  1. Execute mongodump command to export data from the running MongoDB pod.
   kubectl exec mongo-statefulset-0 o-statefulset-0 -- sh -c 'mongodump --uri="mongodb://$MONGO_INITDB_ROOT_USERNAME:$MONGO_INITDB_ROOT_PASSWORD@localhost/$MONGO_INITDB_DATABASE" --authenticationDatabase admin --archive=/data/db/backup/appsmith-data.archive --gzip'
  1. Copy the archive file from the MongoDB pod to your local.

    kubectl cp mongo-statefulset-0:data/db/backup/appsmith-data.archive appsmith-data.archive
  2. Verify that a local archive file is created that stores the data of the existing MongoDB service in Kubernetes.

    ls | grep appsmith-data.archive


Configure parameters

In the old Kubernetes stack, MongoDB and Redis were deployed as separate resources in the cluster. However, in the new Helm chart, you can configure MongoDB and Redis as internal services or deploy MongoDB and Redis as separate services in the cluster. To ensure that the Helm chart runs with external Redis and MongoDB services, you need to make some changes to the values.yaml file. Follow the steps below to configure external Redis and MongoDB services.

  1. Add Helm repository

    helm repo add appsmith
  2. Update repository

    helm repo update

  3. Pull the latest values from the Appsmith helm chart

      helm show values appsmith/appsmith > values.yml
  4. Modify values.yaml and enable MongoDB and Redis.

    enabled: true
    enabled: false
    replicaCount: 1

    enabled: true
    nameOverride: appsmith-mongodb
    rootUser: root
    rootPassword: password
    replicaCount: 2
    architecture: "replicaset"
    replicaSetName: rs0

Install Helm chart

Follow the below steps to install the Helm chart with the old configuration:

  1. Install Appsmith

    helm install appsmith appsmith/appsmith --values values.yaml
  2. After installation, verify that the pods are running. Use the below command to verify the new pod created by the Helm chart:


Ensure that the APPSMITH_CUSTOM_DOMAIN environment variable is not set in the docker.env file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the Configuring TLS section. :::

    kubectl get pods -n appsmith
appsmith-0 1/1 Running 0 90s
appsmith-mongodb-0 1/1 Running 0 90s
appsmith-mongodb-1 1/1 Pending 0 90s
appsmith-mongodb-arbiter-0 1/1 Running 0 90s
appsmith-redis-master-0 1/1 Running 0 90s
appsmith-redis-replicas-0 1/1 Running 0 90s

Import database

Follow the below steps to import data from the archive file into the new Helm chart:

  1. Create a restore directory in the new pod

kubectl exec appsmith-0 -- mkdir -p /appsmith-stacks/data/restore
  1. Copy the archive file from local to the new pod:

kubectl cp appsmith-data.archive appsmith-0:/appsmith-stacks/data/restore
  1. Run import_db command:

  kubectl exec -it appsmith-0 -- appsmithctl import_db

You see a message - Importing this DB will erase this data. Are you sure you want to proceed, where you can respond with y. It's safe in this situation since the new database in the new setup only contains initial data and should be safe to be overwritten.

  1. Verify that the Helm chart still works after importing and the data from the old Kubernetes stack also shows up in the Helm chart

Migrate SSL certificate

You may want to migrate an existing SSL certificate to the new Helm chart. The Kubernetes cluster uses the cert-manager to provision the SSL certificate, which is an automated certificate manager. However, this change may not be backward compatible if you're migrating from one cert-manager to another.

It's recommended that after migrating to the Helm chart, you follow the document Setup HTTPS to set up a new cert-manager and provision a new certificate for Helm installation.

Test migration

After the chart has been deployed to the Kubernetes cluster, it's important to test that the migration is successful and the Appsmith application is functioning as expected in the new Helm-based deployment. This may involve running a series of integration tests, or simply verifying that the application is accessible and responding to requests as expected.


If any issues are encountered during the migration process or while testing the Appsmith Helm installation, it may be necessary to roll back to the previous multi-container Kubernetes installation. You can start using the old Kubernetes stacks as it's not been removed and is available. If you are still facing any issues, please reach out to or raise it on the Discord Server.