callforamerica/couchdb

CouchDB 2.0 for Kubernetes（带清单）

维护者

Joe Black | <***> | https://github.com/joeblackwaslike

镜像概述

这是一个最小化的CouchDB 2.0镜像，包含用于自动集群初始化的sidecar容器，支持本地开发环境自动完成集群配置，并提供couch-helper工具脚本。镜像基于自定义的Debian Linux（Jessie版本）构建，压缩后大小约22MB。

核心功能

• 自动集群初始化：通过sidecar容器couchdiscover实现Kubernetes环境下的集群自动初始化
• 本地开发支持：设置LOCAL_DEV_CLUSTER=true可快速完成单节点开发集群配置
• 灵活配置：通过环境变量自定义日志级别、数据路径、绑定地址、集群分片数等参数
• 轻量高效：基于自定义Debian镜像，资源占用低，压缩后仅约22MB

使用场景

• Kubernetes集群中的CouchDB分布式部署
• 本地开发环境的单节点CouchDB快速搭建
• 需要自动集群初始化的容器化CouchDB应用场景

配置说明

构建环境变量

构建时可通过参数覆盖以下变量：

• ERLANG_VERSION：Erlang版本
• COUCHDB_VERSION：CouchDB版本
• APP：应用名称（默认couchdb）
• USER：运行用户（默认couchdb）
• HOME：应用目录（默认/opt/couchdb）

运行环境变量

CouchDB容器

• ERLANG_THREADS：Erlang线程数，默认25
• COUCHDB_LOG_LEVEL：日志级别，默认info
• COUCHDB_DATA_PATH：数据存储路径，默认/data/couchdb
• COUCHDB_BIND_ADDR：绑定地址，默认0.0.0.0
• COUCHDB_REQUIRE_VALID_USER：是否需要有效用户认证，默认false
• COUCHDB_SHARDS：集群分片数，默认4
• COUCHDB_READ_QUORUM：读法定人数，默认1
• COUCHDB_WRITE_QUORUM：写法定人数，默认1
• COUCHDB_REPLICAS：副本数，默认1
• LOCAL_DEV_CLUSTER：是否为本地开发集群，默认false
• COUCHDB_ADMIN_USER/COUCHDB_ADMIN_PASS：管理员账号密码，用于集群初始化
• ERLANG_COOKIE：Erlang节点通信cookie
• COUCHDB_CLUSTER_SIZE：集群大小（覆盖StatefulSet副本数，不建议随意修改）

couchdiscover容器

• LOG_LEVEL：日志级别，默认INFO

部署示例

Docker部署

bash
docker run -d \
    --name couchdb \
    -h couchdb.local \
    -e "LOCAL_DEV_CLUSTER=true" \
    -e "COUCHDB_ADMIN_USER=admin" \
    -e "COUCHDB_ADMIN_PASS=secret" \
    -e "ERLANG_COOKIE=test-cookie" \
    docker.xuanyuan.run/callforamerica/couchdb

Docker Compose部署

拉取镜像：

bash
docker-compose pull

前台启动：

bash
docker-compose up --abort-on-container-exit

后台启动：

bash
docker-compose up -d

Kubernetes部署

1. 创建Erlang Cookie Secret：

bash
kubectl create secret generic erlang-cookie --from-literal=erlang.cookie=$(LC_ALL=C tr -cd '[:alnum:]' < /dev/urandom | head -c 64)

2. 创建CouchDB凭据Secret：

bash
kubectl create secret generic couchdb-creds --from-literal=couchdb.user=$(sed $(perl -e "print int rand(99999)")"q;d" /usr/share/dict/words) --from-literal=couchdb.pass=$(LC_ALL=C tr -cd '[:alnum:]' < /dev/urandom | head -c 32)

3. 部署CouchDB：

bash
kubectl create -f kubernetes/<environment>

couchdiscover说明

couchdiscover是Kubernetes清单中的sidecar容器，负责集群初始化。其工作原理如下：

信息发现方式

1. 通过解析StatefulSet容器主机名获取命名空间、StatefulSet名称、无头服务名称等信息
2. 通过Kubernetes API获取StatefulSet和Endpoint对象，解析主机列表、端口及环境变量（含ConfigMaps和Secrets）
3. 从CouchDB容器环境变量中获取管理员账号密码，集群大小默认取StatefulSet副本数（可通过COUCHDB_CLUSTER_SIZE覆盖）

核心逻辑

python
# couchdiscover.manage.ClusterManager
def run(self):
    """Main logic here, this is where we begin once all environment
    information has been retrieved."""
    log.info('Starting couchdiscover: %s', self.couch)
    if self.couch.disabled:
        log.info('Cluster disabled, enabling')
        self.couch.enable()
    elif self.couch.finished:
        log.info('Cluster already finished')
        self.sleep_forever()

    if self.env.first_node:
        log.info("Looks like I'm the first node")
        if self.env.single_node_cluster:
            log.info('Single node cluster detected')
            self.couch.finish()
    else:
        log.info("Looks like I'm not the first node")
        self.couch.add_to_master()
        if self.env.last_node:
            log.info("Looks like I'm the last node")
            self.couch.finish()
        else:
            log.info("Looks like I'm not the last node")
    self.sleep_forever()