tree: 977935b84a31a554cf1054c2911417c9e6c31cc6 [path history] [tgz]
  1. ci/
  2. templates/
  3. Chart.yaml
  4. README.md
  5. values.yaml
couchdb/README.md

CouchDB

Apache CouchDB is a database featuring seamless multi-master sync, that scales from big data to mobile, with an intuitive HTTP/JSON API and designed for reliability.

This chart deploys a CouchDB cluster as a StatefulSet. It creates a ClusterIP Service in front of the Deployment for load balancing by default, but can also be configured to deploy other Service types or an Ingress Controller. The default persistence mechanism is simply the ephemeral local filesystem, but production deployments should set persistentVolume.enabled to true to attach storage volumes to each Pod in the Deployment.

TL;DR

$ helm repo add couchdb https://apache.github.io/couchdb-helm
$ helm install couchdb/couchdb \
  --set allowAdminParty=true \
  --set couchdbConfig.couchdb.uuid=$(curl https://www.uuidgenerator.net/api/version4 2>/dev/null | tr -d -)

Prerequisites

  • Kubernetes 1.9+ with Beta APIs enabled
  • Ingress requires Kubernetes 1.14+

Installing the Chart

To install the chart with the release name my-release:

Add the CouchDB Helm repository:

$ helm repo add couchdb https://apache.github.io/couchdb-helm

Afterwards install the chart replacing the UUID decafbaddecafbaddecafbaddecafbad with a custom one:

$ helm install \
  --name my-release \
  --set couchdbConfig.couchdb.uuid=decafbaddecafbaddecafbaddecafbad \
  couchdb/couchdb

This will create a Secret containing the admin credentials for the cluster. Those credentials can be retrieved as follows:

$ kubectl get secret my-release-couchdb -o go-template='{{ .data.adminPassword }}' | base64 --decode

If you prefer to configure the admin credentials directly you can create a Secret containing adminUsername, adminPassword and cookieAuthSecret keys:

$  kubectl create secret generic my-release-couchdb --from-literal=adminUsername=foo --from-literal=adminPassword=bar --from-literal=cookieAuthSecret=baz

and then install the chart while overriding the createAdminSecret setting:

$ helm install \
  --name my-release \
  --set createAdminSecret=false \
  --set couchdbConfig.couchdb.uuid=decafbaddecafbaddecafbaddecafbad \
  couchdb/couchdb

This Helm chart deploys CouchDB on the Kubernetes cluster in a default configuration. The configuration section lists the parameters that can be configured during installation.

Tip: List all releases using helm list

Uninstalling the Chart

To uninstall/delete the my-release Deployment:

$ helm delete my-release

The command removes all the Kubernetes components associated with the chart and deletes the release.

Upgrading an existing Release to a new major version

A major chart version change (like v0.2.3 -> v1.0.0) indicates that there is an incompatible breaking change needing manual actions.

Upgrade to 3.0.0

Since version 3.0.0 setting the CouchDB server instance UUID is mandatory. Therefore you need to generate a UUID and supply it as a value during the upgrade as follows:

$ helm upgrade <release-name> \
  --reuse-values \
  --set couchdbConfig.couchdb.uuid=<UUID> \
  couchdb/couchdb

Migrating from stable/couchdb

This chart replaces the stable/couchdb chart previously hosted by Helm and continues the version semantics. You can upgrade directly from stable/couchdb to this chart using:

$ helm repo add couchdb https://apache.github.io/couchdb-helm
$ helm upgrade my-release couchdb/couchdb

Configuration

The following table lists the most commonly configured parameters of the CouchDB chart and their default values:

ParameterDescriptionDefault
clusterSizeThe initial number of nodes in the CouchDB cluster3
couchdbConfigMap allowing override elements of server .ini configSee below
allowAdminPartyIf enabled, start cluster without admin accountfalse (requires creating a Secret)
createAdminSecretIf enabled, create an admin account and cookie secrettrue
schedulerNameName of the k8s scheduler (other than default)nil
erlangFlagsMap of flags supplied to the underlying Erlang VMname: couchdb, setcookie: monster
persistentVolume.enabledBoolean determining whether to attach a PV to each nodefalse
persistentVolume.sizeIf enabled, the size of the persistent volume to attach10Gi
enableSearchAdds a sidecar for Lucene-powered text searchfalse
telemetry.enabledAdds a sidecar to expose CouchDB metrics to Prometheusfalse

You can set the values of the couchdbConfig map according to the official configuration. The following shows the map's default values and required options to set:

ParameterDescriptionDefault
couchdb.uuidUUID for this CouchDB server instance (Required in a cluster)
chttpd.bind_addresslistens on all interfaces when set to anyany
chttpd.require_valid_userdisables all the anonymous requests to the port 5984 when truefalse

A variety of other parameters are also configurable. See the comments in the values.yaml file for further details:

ParameterDefault
adminUsernameadmin
adminPasswordauto-generated
cookieAuthSecretauto-generated
image.repositorycouchdb
image.tag2.3.1
image.pullPolicyIfNotPresent
searchImage.repositorykocolosk/couchdb-search
searchImage.tag0.1.0
searchImage.pullPolicyIfNotPresent
initImage.repositorybusybox
initImage.taglatest
initImage.pullPolicyAlways
ingress.enabledfalse
ingress.hostschart-example.local
ingress.annotations
ingress.path/
ingress.tls
persistentVolume.accessModesReadWriteOnce
persistentVolume.storageClassDefault for the Kube cluster
podManagementPolicyParallel
affinity
annotations
tolerations
resources
service.annotations
service.enabledtrue
service.typeClusterIP
service.externalPort5984
dns.clusterDomainSuffixcluster.local
networkPolicy.enabledtrue
serviceAccount.enabledtrue
serviceAccount.createtrue
serviceAccount.imagePullSecrets
sidecars{}
livenessProbe.enabledtrue
livenessProbe.failureThreshold3
livenessProbe.initialDelaySeconds0
livenessProbe.periodSeconds10
livenessProbe.successThreshold1
livenessProbe.timeoutSeconds1
readinessProbe.enabledtrue
readinessProbe.failureThreshold3
readinessProbe.initialDelaySeconds0
readinessProbe.periodSeconds10
readinessProbe.successThreshold1
readinessProbe.timeoutSeconds1
telemetry.databases

Telemetry

The chart optionally deploys the CouchDB Prometheus exporter to each CouchDB node. Metrics are exposed on port 9984.

Below is an example Prometheus scrape configuration that can be used to collect per-node CouchDB metrics:

- job_name: couchdb
  scrape_interval: 10s
  kubernetes_sd_configs:
  - role: pod
  relabel_configs:
  - source_labels: [__meta_kubernetes_namespace]
      action: replace
      target_label: k8s_namespace
  - source_labels: [__meta_kubernetes_pod_name]
      action: replace
      target_label: k8s_pod_name
  - source_labels: [__address__]
      action: replace
      regex: ([^:]+)(?::\d+)?
      replacement: ${1}:9984
      target_label: __address__
  - source_labels: [__meta_kubernetes_pod_label_app]
      action: keep
      regex: couchdb

Feedback, Issues, Contributing

General feedback is welcome at our user or developer mailing lists.

Apache CouchDB has a CONTRIBUTING file with details on how to get started with issue reporting or contributing to the upkeep of this project. In short, use GitHub Issues, do not report anything on Docker's website.

Non-Apache CouchDB Development Team Contributors