Maintained by imos64. A public deployment package with pinned sources, native Kubernetes manifests, Helm, Terraform and OpenTofu, architecture documentation, and recovery runbooks. It follows the structure of prometheus-kubernetes.
Three CouchDB nodes form one cluster with n=3 replicas and q=8 shards for newly created databases. Hard anti-affinity places members on different hosts; the setup Job joins the cluster.
flowchart LR
Client --> Service[CouchDB Service]
Service --> Node1
Service --> Node2
Service --> Node3
Node1 <-->|Erlang distribution| Node2
Node2 <-->|Erlang distribution| Node3
Node1 --> PVC1
Node2 --> PVC2
Node3 --> PVC3
A three-replica database typically uses majority read/write quorums, but CouchDB is not a strict serializable consensus database. Client conflict handling remains necessary. Existing databases keep their shard/replica layout when defaults change; validate membership and _shards explicitly.
| Path | Purpose |
|---|---|
charts/couchdb |
Local Helm chart and base/production values |
k8s/base, k8s/production |
Reproducible rendered manifests with Kustomize entry points |
terraform, opentofu |
Alternative Helm release owners on an existing Kubernetes cluster |
scripts |
Rendering, schema validation, secret-reference and topology checks |
docs |
Architecture, configuration, operations, validation and source provenance |
examples |
Deployment-specific integration and recovery examples |
Use one delivery path per release. These modules deploy applications to an existing cluster; they do not provision cloud networks, worker nodes, DNS, object storage or a CSI driver. Base is smaller for evaluation, while production increases storage/resources and supported replicas. Neither profile configures your organization's backup destination or proves an availability SLO.
- Kubernetes 1.34-compatible APIs, Helm 3, and a working default RWO StorageClass for stateful workloads. Plan storage expansion and volume reattachment; node-local storage cannot survive permanent node loss.
- For three-member clusters, three schedulable workers in appropriate fault domains. Set node/zone placement and storage topology for your environment.
- A CNI that enforces NetworkPolicy. Workload ingress permits this namespace and namespaces explicitly labeled
platform-access=true; egress is not restricted by the supplied policy. Internal HTTP services need TLS/authentication at your approved access boundary. - An explicit kubeconfig/context and namespace access. Operator installation additionally requires cluster-scoped CRD/RBAC privileges.
- Existing credentials delivered by your secret manager. No real passwords, certificates, state files or private project configurations are committed.
Use the same auth and Erlang cookie secrets for all three nodes. The committed UUID is a non-secret example cluster identifier: replace app.couchdbConfig.couchdb.uuid with your own stable 32-character hex UUID before initial installation and render the native manifests again.
git clone https://github.com/imos64/couchdb-kubernetes.git
cd couchdb-kubernetes
export KUBECONFIG=/absolute/path/to/your/kubeconfig
kubectl config current-context
kubectl create namespace couchdbReview configuration and credentials before installation. scripts/bootstrap-demo-secrets.py generates fresh credentials directly in the selected cluster for a disposable evaluation; it refuses to overwrite an existing secret and never prints generated passwords. For production, provision the same keys using your secret-management workflow.
python3 scripts/bootstrap-demo-secrets.py --context YOUR_CONTEXThelm upgrade --install couchdb ./charts/couchdb -n couchdb \
-f charts/couchdb/values-production.yaml --wait --timeout 15mAdd -f /secure/path/site-values.yaml last for your storage class, sizing and integrations. Helm's release wait does not prove database quorum or custom-resource readiness; run the acceptance checks below.
kubectl apply --server-side -k k8s/productionFor customized native manifests, edit chart values then run make render and review the diff. The rendered namespace/release defaults are couchdb; re-render intentionally if you change that contract. Helm hook Jobs become ordinary Jobs under kubectl, so check their completion and delete only completed setup Jobs before rerunning changed hooks.
Both modules use the same pinned local Helm source. They require the namespace and secrets to exist first. Keep state in an encrypted remote backend with locking; state and plans can contain sensitive information.
terraform -chdir=terraform init
terraform -chdir=terraform plan -var='kube_context=YOUR_CONTEXT' -out=deployment.tfplan
terraform -chdir=terraform apply deployment.tfplan
# OR
tofu -chdir=opentofu init
tofu -chdir=opentofu plan -var='kube_context=YOUR_CONTEXT' -out=deployment.tfplan
tofu -chdir=opentofu apply deployment.tfplanUse kubeconfig_path and values_files to supply your environment. See deployment.tfvars.example. Never manage the same release from Terraform and OpenTofu simultaneously.
Internal endpoint: couchdb-svc-app.couchdb.svc.cluster.local:5984 (verify rendered Service name with kubectl get svc -n couchdb).
Wait for the setup Job, query authenticated /_membership and require three all_nodes and cluster_nodes. Create a database with n=3, write a marker, inspect its shards, restart one member, then read the marker and confirm cluster membership returns to three.
Continuously replicate important databases to a separately administered cluster and retain point-in-time backups so accidental deletions do not destroy every copy. Back up shard files and configuration with CouchDB-compatible procedures. Include security objects and design documents in recovery checks.
See operations for backup, restore, upgrade and failure checks. HA replication is not a backup. Retained PVCs do not protect against storage-system failure, accidental deletion or site loss.
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
python3 scripts/install-tools.py
export PATH="$PWD/.tools:$PATH"
make render
make validateCI checks deterministic rendering, strict Helm lint, Kubernetes and custom-resource schemas, topology/secret contracts, Terraform/OpenTofu validation and secret scanning. Runtime acceptance and disaster-recovery steps are documented separately in validation evidence; configuration validation is not proof of production readiness.
This repository owns the integration/deployment code, not the upstream application. Upstream project · Official documentation. See provenance for pinned versions and SHA-256 chart checksums. Deployment code is Apache-2.0; bundled upstream charts, schemas and container images retain their original licenses. Review application licensing for your use case, especially Nexus, SonarQube, Redis and MongoDB-derived distributions.