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
NAME READY STATUS RESTARTS AGE
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
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/appsmith-backend-service NodePort 10.100.247.245 <none> 8080:32694/TCP 3d12h
service/appsmith-editor ClusterIP 10.100.236.17 <none> 80/TCP 3d12h
service/kubernetes ClusterIP 10.100.0.1 <none> 443/TCP 3d12h
service/mongo-service NodePort 10.100.2.162 <none> 27017:31766/TCP 3d12h
service/redis-service NodePort 10.100.7.184 <none> 6379:30834/TCP 3d12h
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/appsmith-editor 1/1 1 1 3d12h
deployment.apps/appsmith-internal-server 1/1 1 1 3d12h
NAME DESIRED CURRENT READY AGE
replicaset.apps/appsmith-editor-995c974df 1 1 1 3d12h
replicaset.apps/appsmith-internal-server-dfd68b55b 1 1 1 3d12h
NAME READY AGE
statefulset.apps/mongo-statefulset 1/1 3d12h
statefulset.apps/redis-statefulset 1/1 3d12h
NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE
cronjob.batch/imago 0 * * * * False 0 12m 3d12h
NAME COMPLETIONS DURATION AGE
job.batch/imago-27473940 1/1 16s 12m
Before you start the migration process, ensure that the below prerequisites are met.
kubectlis 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.
kubectlis installed, configure it to connect to your cluster. Follow one of the available guides below for your platform:
yqpackage: yq package is needed to format data from the
ConfigMapresources into a
.yamlfile 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 data from the existing
MongoDB pod and download the archive file to your local. Follow the steps below to backup a database:
backupdirectory in the
kubectl exec mongo-statefulset-0 -- mkdir -pv /data/db/backup
mongodumpcommand 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'
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
Verify that a local
archivefile is created that stores the data of the existing
MongoDBservice in Kubernetes.
ls | grep appsmith-data.archive
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.
Add Helm repository
helm repo add appsmith https://helm.appsmith.com
helm repo update
Pull the latest values from the Appsmith helm chart
helm show values appsmith/appsmith > values.yml
values.yamland enable MongoDB and Redis.
Install Helm chart
Follow the below steps to install the Helm chart with the old configuration:
helm install appsmith appsmith/appsmith --values values.yaml
After installation, verify that the pods are running. Use the below command to verify the new pod created by the Helm chart:Attention
Ensure that the
APPSMITH_CUSTOM_DOMAINenvironment variable is not set in the
docker.envfile when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the Configuring TLS section.
kubectl get pods -n appsmith
NAME READY STATUS RESTARTS AGE
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
Follow the below steps to import data from the archive file into the new Helm chart:
restoredirectory in the new pod
kubectl exec appsmith-0 -- mkdir -p /appsmith-stacks/data/restore
Copy the archive file from local to the new pod:
kubectl cp appsmith-data.archive appsmith-0:/appsmith-stacks/data/restore
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.
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.
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 email@example.com or raise it on the Discord Server.