使用 MongoDB Kubernetes Operator 在 Helm 中安装 Appsmith：从快速启动到生产高可用配置全指南

使用 MongoDB Kubernetes Operator 在 Helm 中安装 Appsmith从快速启动到生产高可用配置全指南【免费下载链接】appsmithPlatform to build admin panels, internal tools, and dashboards. Integrates with 25 databases and any API.项目地址: https://gitcode.com/GitHub_Trending/ap/appsmith适用版本Appsmith Helm chart 3.7.0 起提供该能力的预览支持。本文以仓库中的官方安装指南 deploy/helm/docs/install-mongodb-operator.md 为主体结合 deploy/helm/values.yaml、deploy/helm/templates/mongodb-community.yaml 等模板源码完整讲解如何用 MongoDB Kubernetes Operator 取代默认的 Bitnami MongoDB 子 chart 来托管 Appsmith 的数据库。导读Appsmith 官方的 Kubernetes/Helm 部署默认依赖 Bitnami 的mongodb子 chart。当 MongoDB 官方推出专属的 MongoDB Community Kubernetes Operator下文简称Operator之后Appsmith Helm chart 增加了全新的部署路径通过MongoDBCommunity自定义资源CR让 Operator 直接管理副本集。本文从安装动机讲起逐步覆盖快速启动、验证安装、密码获取与自管、生产级资源配置、ArgoCD 集成、卸载清理以及典型故障排查并在每一节结合仓库模板源码解释底层机制让读者既能照着命令直接落地又能理解每一步为什么会这样工作。为什么选择 Operator 托管 MongoDB把 MongoDB 交给 Operator 而非 Bitnami 子 chart核心收益有三点专用控制器接管运维MongoDB 副本集成员关系、TLS/SCRAM 凭据生命周期、版本升级都由 Operator 这个专用控制器统一编排而不是依赖普通 Deployment/StatefulSet 的通用逻辑连接串免手工拼装Operator 会自动创建并维护 Appsmith 需要读取的 connection-string Secret无需自行拼接mongodb://user:passhost:port/db形式的地址镜像更可持续Operator 运行在 MongoDB 官方持续维护的社区版镜像上而 Bitnami 的mongodb镜像已由其发行方标记弃用长期可维护性更优。前置条件与组件交互关系文档列出的安装前提为Kubernetes 1.28Helm 3.14官方安装页已为目标集群配置好kubectl集群存在默认StorageClass或显式通过--set global.storageClassname指定。文档明确说明无需单独预装 Operator因为 chart 可以通过子 chart 把它一并带上见下节。从模板源码看新增能力由三个开关协同控制开关默认值作用mongodb.enabledtrue是否部署默认的 Bitnami MongoDB 子 chartmongodbCommunity.enabledfalse是否渲染MongoDBCommunityCR 交给 Operator 调和mongodbOperator.enabledfalse是否把上游mongodb-kuberneteschart 作为子 chart 一起安装含 Operator Pod 与所需 CRD三者之间的关系可以在 deploy/helm/values.yaml 中看到注释并在 deploy/helm/templates/_helpers.tpl 的appsmith.useOperatorMongo模板中得到印证只有当mongodbCommunity.enabledtrue且mongodb.enabledfalse同时没有显式传入APPSMITH_DB_URL/APPSMITH_MONGODB_URI/ 外部 Secret 时Appsmith 工作负载才会真正把连接串指向 Operator 托管的 MongoDB。在 deploy/helm/Chart.yaml 中可以看到该子 chart 的声明mongodb-kubernetes别名mongodbOperator版本1.8.0仓库https://mongodb.github.io/helm-charts与redis、mongodb、postgresql、prometheus等子 chart 并列。快速启动捆绑 Operator 的全新安装这是官方推荐的全新安装路径命令如下helm repo add appsmith https://helm.appsmith.com helm repo update kubectl create namespace appsmith helm install appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ --set mongodb.enabledfalse \ --set mongodbCommunity.enabledtrue \ --set mongodbOperator.enabledtrue三个开关的语义对应如下表格Flag用途mongodb.enabledfalse不部署默认的 Bitnami MongoDB 子 chartmongodbCommunity.enabledtrue部署一个MongoDBCommunityCR交由 Operator 调和为副本集mongodbOperator.enabledtrue在同命名空间安装上游 MongoDB Kubernetes Operator 子 chart这条命令背后发生了什么当上述开关打开后chart 实际渲染出三类关键资源均可在仓库模板中一一对应MongoDBCommunityCR由 deploy/helm/templates/mongodb-community.yaml 渲染。它声明副本数、type: ReplicaSet、MongoDB 版本、SCRAM 认证用户及角色readWriteclusterMonitor、statefulSet.spec下的调度/资源参数以及两块volumeClaimTemplatesdata-volume与固定 2Gi 的logs-volume。密码初始化 Helm hook Job由 deploy/helm/templates/hooks/mongodb-community.yaml 渲染。当mongodbCommunity.auth.passwordSecretName为空时一个pre-install,pre-upgrade的幂等 Job 会生成 24 位随机密码tr -dc A-Za-z0-9 /dev/urandom | head -c 24写入名为MongoDBCommunity名字-password的 Secret。模板注释说明这样设计是为了保持密码在 Helm 升级与 ArgoCD 反复 sync 之间保持稳定——若用模板内lookuprandAlphaNumArgoCD 每次 sync 都会看到 diff从而覆盖密码。生成的 Secret 不带 release 标签与 ownerReferenceArgoCD 不会追踪或 diff 它。Appsmith 工作负载与连接串 Secret 的接线当appsmith.useOperatorMongo判定为真时deploy/helm/templates/deployment.yaml 会把APPSMITH_DB_URL通过secretKeyRef指向 Operator 维护的 Secret 中connectionString.standardSrv键同时 init 容器会先对 Operator 的 headless Service 执行mongoshping 探活见同文件 L106-L110。验证安装kubectl get pods -n appsmith kubectl get mongodbcommunity -n appsmith预期输出节选NAME READY STATUS appsmith-0 1/1 Running appsmith-mongo-0 2/2 Running appsmith-postgresql-0 1/1 Running appsmith-redis-master-0 1/1 Running mongodb-kubernetes-operator-... 1/1 Running NAME PHASE VERSION appsmith-mongo Running 8.0.20注意两个细节一是 Operator Pod 就绪后MongoDBCommunity才会进入Running二是这里默认的 MongoDB 版本为8.0.20定义于 deploy/helm/values.yaml与 deploy/helm/Chart.yaml 中 chart 的appVersion没有直接绑定关系。访问 UIkubectl port-forward -n appsmith svc/appsmith 8080:80随后浏览器打开 http://localhost:8080。生产环境请改用 Ingress 对外暴露参见 Appsmith 官方文档 Publishing Appsmith onlinekubernetes 安装指南下的页面。获取生成的 MongoDB 密码与连接串MongoDB 用户密码存放在名为mongodbCommunity.name-password的 Secret 中。release 名为appsmith且使用默认命名时即为appsmith-mongo-password命名规则见 deploy/helm/templates/_helpers.tpl 的appsmith.mongoCommunityName默认取release-fullname-mongo刻意使用-mongo而非 Bitnami 的-mongodb后缀以避免命名冲突kubectl get secret appsmith-mongo-password -n appsmith \ -o jsonpath{.data.password} | base64 -dAppsmith 自身读取的是 Operator 维护的连接串 Secret命名规则为MongoDBCommunity名字-database-username见 deploy/helm/templates/_helpers.tpl 的appsmith.mongoOperatorSecretName默认即appsmith-mongo-appsmith-appsmithkubectl get secret appsmith-mongo-appsmith-appsmith -n appsmith \ -o jsonpath{.data.connectionString\.standardSrv} | base64 -d常用配置自带 MongoDB 密码 Secret如果密码由 Vault、SOPS、ExternalSecrets 等外部工具托管可以先自行创建 Secret再用mongodbCommunity.auth.passwordSecretName指向它。Secret 内必须包含唯一键password值为明文密码——下面的kubectl create secret只是为了演示所需格式实际生产可沿用你已有的任意工具产出同样结构kubectl create secret generic my-mongodb-secret \ -n appsmith \ --from-literalpasswordyour-password helm install appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ --set mongodb.enabledfalse \ --set mongodbCommunity.enabledtrue \ --set mongodbOperator.enabledtrue \ --set mongodbCommunity.auth.passwordSecretNamemy-mongodb-secret一旦设置mongodbCommunity.auth.passwordSecretNamechart 就会跳过密码初始化 Job对应 deploy/helm/templates/hooks/mongodb-community.yaml 的渲染条件并假定该 Secret 已被正确填充。相关参数默认值见 deploy/helm/values.yaml默认用户名appsmith、认证库appsmith同时用作连接路径passwordSecretName默认留空。资源规格与高可用HAchart 默认针对评估与开发环境调优单成员副本集、适度存储默认storageSize: 10Gi。此模式下 MongoDB 功能完整但没有故障转移能力。生产环境建议扩到三个成员、固定资源请求与上限并显式指定StorageClassmongodbCommunity: enabled: true members: 3 # replica set size (odd number recommended) persistent: storageSize: 100Gi storageClass: gp3 # or omit to use cluster default resources: requests: cpu: 500m memory: 2Gi limits: memory: 4Gi与这些字段对应的 CR 渲染逻辑都集中在 deploy/helm/templates/mongodb-community.yamlmembers直接映射到 CR 的spec.membersvalues.yaml中minimum: 1默认值为 1persistent.storageSize/persistent.storageClass进入volumeClaimTemplates其中storageClass会优先取mongodbCommunity.persistent.storageClass否则回退到global.storageClass仍为空则省略该字段、交由集群默认类决定resources被注入到statefulSet.spec.template.spec.containers中名为mongod的容器此外nodeSelector、affinity、tolerations同样可透传到 Pod 模板。从 1 扩到 3 不需要重建这只是 upgrade 时的取值变化Operator 会在线把新成员加入副本集、无需停机。values.yaml中对此有明确说明The operator handles scaling between these online — its just a value change on upgrade。一个值得注意的镜像细节来自 deploy/helm/values.yaml 的注释私有镜像仓库若只同步-ubi8后缀的 tag可把mongodbCommunity.version直接设为8.0.20-ubi8——Operator 会原样消费 CR 的spec.version而 Appsmith 侧 init 容器镜像构造模板会先裁掉重复后缀再拼镜像名因此无需再覆盖 init 容器镜像。官方 registry 上则保持裸版本号8.0.20由 Operator 自动追加-ubi8。通过 ArgoCD 部署捆绑 Operator 的路径与 ArgoCD 天然兼容因为 CRD 位于上游 chart 的crds/目录Helm以及 ArgoCD会在校验任何模板之前先安装 CRD从而避免CRD 尚未就绪的竞态问题。示例ApplicationapiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: appsmith namespace: argocd spec: project: default source: repoURL: https://helm.appsmith.com chart: appsmith targetRevision: chart-version helm: valuesObject: mongodb: enabled: false mongodbCommunity: enabled: true mongodbOperator: enabled: true destination: server: https://kubernetes.default.svc namespace: appsmith syncPolicy: automated: {} syncOptions: - CreateNamespacetrue关于 GitOps 场景hook Job 模板的注释还特意解释了为何采用Job 检测再创建的方式相比于在模板里渲染随机密码的做法前者在 ArgoCD 反复 sync 下不会产生无谓 diff也不会覆盖既有密码见 deploy/helm/templates/hooks/mongodb-community.yaml。若你选择完全自带密码 Secret则连这个 Job 都会被跳过ArgoCD 视图更干净。卸载与清理卸载顺序有讲究先删MongoDBCommunityCR再卸载 release。因为 CR 上带有 Operator 负责清理的 finalizer先删 CR 可以保证 Operator 仍在运行时处理完收尾# 1. Delete the CR and wait for the operator to clear its finalizer kubectl delete mongodbcommunity -n appsmith --all --waittrue # 2. Uninstall Appsmith (and the bundled operator, if enabled) helm uninstall appsmith -n appsmith # 3. Remove the namespace kubectl delete namespace appsmith跳过第 1 步可能导致MongoDBCommunity资源在 Operator Deployment 已消失后仍带着无法解除的 finalizer从而阻塞命名空间删除——若已发生见下文故障排查小节的处理方法。这一流程会移除 Appsmith、捆绑的 Operator若经本 chart 安装以及与该MongoDBCommunityCR 绑定的全部由 Operator 调和出的资源。但需要注意子 chart 安装的 MongoDB CRD 在卸载后依然保留Helm 从不删除crds/中的资源。要彻底清理需手动删除 CRDkubectl delete crd mongodbcommunity.mongodbcommunity.mongodb.com # The mongodb-kubernetes chart also installs CRDs for its enterprise features: kubectl delete crd mongodb.mongodb.com kubectl delete crd mongodbusers.mongodb.com # (and any others from the chart you want to remove)警告删除这些 CRD 会移除集群中所有匹配的资源——只有确认没有其他工作负载依赖该 Operator 时才可执行。故障排查MongoDBCommunityCR 一直处于Pending先看 Operator 日志kubectl logs -n appsmith -l app.kubernetes.io/namemongodb-kubernetes-operator --tail50常见原因密码 Secret 不存在。若设置了mongodbCommunity.auth.passwordSecretName请确认 Secret 存在且包含password键MongoDB 镜像拉取失败。用kubectl describe pod mongodbCommunity.name-0查看镜像拉取错误。helm uninstall后命名空间删除卡住症状kubectl delete namespace appsmith永不完成MongoDBCommunity资源仍被列出且带有deletionTimestamp。原因MongoDBCommunityCR 的 finalizer 由 Operator 负责移除。当mongodbOperator.enabledtrue时Helm 可能在 Operator 处理完 CR 删除前就先拆掉了 Operator Deploymentfinalizer 因此永远残留。修复手工清空 finalizer随后命名空间删除即可继续kubectl patch mongodbcommunity -n appsmith mongodbCommunity.name \ --typemerge -p {metadata:{finalizers:[]}}Appsmith Pod 卡在Init原因Appsmith 的 init 容器会持续等待 MongoDB 可达。若 MongoDB 未就绪该容器会一直重试对应 deploy/helm/templates/deployment.yaml 中until mongosh --host ... --eval db.runCommand({ping:1})的循环逻辑。修复先检查 MongoDB 本身kubectl get mongodbcommunity -n appsmith。如果 phase 已是Running但 Appsmith 仍不前进再查看 init 容器日志kubectl logs -n appsmith appsmith-0 -c mongo-init-container密码初始化 Job 因镜像拉取失败症状mongodbCommunity.name-password-initJob 的 Pod 因alpine/kubectl镜像进入ImagePullBackOff。原因集群无法拉取docker.io/alpine/kubectl——要么处于离线/受限网络air-gapped环境要么策略禁止从 Docker Hub 拉取。修复把镜像覆盖指向你的私有镜像仓库--set mongodbCommunity.passwordInit.image.registrymy-registry.example.com --set mongodbCommunity.passwordInit.image.repositorymy/kubectl --set mongodbCommunity.passwordInit.image.tag1.34.2这一组参数在 deploy/helm/values.yaml 中有完整定义与注释默认registry: docker.io、repository: alpine/kubectltag 默认使用浮动的latest因为上游alpine/kubectl仓库会定期淘汰旧补丁 tag若需要字节级可复现性建议固定具体版本号。结语从单条helm install命令到生产级三成员副本集再到 GitOps 化的 ArgoCD ApplicationAppsmith 通过mongodbCommunitymongodbOperator两个开关把 MongoDB Kubernetes Operator 完整接入官方 Helm chart。理解 deploy/helm/templates/mongodb-community.yaml、deploy/helm/templates/hooks/mongodb-community.yaml 与 deploy/helm/templates/deployment.yaml 三份模板的协作关系你就能清楚地预判谁在生成密码、谁在维护连接串、谁在探活、谁负责卸载时的最终清理。需要强调的是该能力仍处于预览期自 chart 3.7.0本文给出的安装路径适用于全新安装若你已用 Bitnami 支撑的生产数据跑着老 release请等待官方另行发布的迁移文档不要在含生产数据的 release 上直接改动mongodbCommunity.enabled。【免费下载链接】appsmithPlatform to build admin panels, internal tools, and dashboards. Integrates with 25 databases and any API.项目地址: https://gitcode.com/GitHub_Trending/ap/appsmith创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考