telephoneorg/couchdb

CouchDB 2.x for Kubernetes w/ manifests

![Build Status]([] ![Size/Layers]([]

维护者

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

镜像概述

这是一个极简的CouchDB 2.x镜像，专为Kubernetes环境设计，包含sidecar容器（couchdiscover）实现自动集群初始化。镜像支持本地开发环境自动完成集群设置，提供couch-helper实用脚本，并基于自定义的极简Debian Linux构建。此外，镜像还集成了来自https://github.com/cabify/couchdb-admin%E7%9A%84couchdb-admin%E5%B7%A5%E5%85%B7%EF%BC%88%E8%AF%A6%E8%A7%81%E8%AF%A5%E9%93%BE%E6%8E%A5%E6%96%87%E6%A1%A3%EF%BC%89%E3%80%82

核心功能

1. 自动集群初始化：通过sidecar容器couchdiscover，在Kubernetes环境中自动完成CouchDB集群的初始化与配置。
2. 本地开发支持：设置COUCHDB_DEV_INIT=true可自动完成本地单节点开发集群的初始化，简化开发流程。
3. 实用工具集成：包含couch-helper脚本用于本地单节点集群管理，集成couchdb-admin工具用于CouchDB的日常管理操作。
4. 灵活配置：通过环境变量可配置CouchDB的日志级别、数据路径、绑定地址等参数，以及集群的分片数、副本数等集群参数。

使用场景

• Kubernetes集群部署：用于在Kubernetes环境中搭建高可用的CouchDB集群，满足生产环境的数据库需求。
• 本地开发测试：快速搭建CouchDB单节点或集群，用于应用的开发、测试和调试。

配置说明

构建环境变量

构建时可通过参数覆盖以下变量，控制镜像构建过程：

• COUCHDB_VERSION：安装的CouchDB版本。
• COUCHDB_RC：发布候选版本号（如适用）。
• COUCHDB_CHECK_RELEASE：是否在make release前执行make check，布尔值。
• 通用变量：APP（couchdb）、USER（couchdb）、HOME（/opt/couchdb）。

运行环境变量

运行时可通过环境变量配置容器行为：

couchdb容器

• ERLANG_THREADS：vm.args中+A参数的值。
• COUCHDB_LOG_LEVEL：local.ini中日志级别（小写）。
• COUCHDB_DATA_PATH：local.ini中数据库和视图索引的存储路径。
• COUCHDB_BIND_ADDR：local.ini中chttpd和httpd的绑定地址。
• COUCHDB_REQUIRE_VALID_USER：local.ini中是否要求有效用户认证。
• COUCHDB_SHARDS：local.ini中集群分片数（q值）。
• COUCHDB_READ_QUORUM：local.ini中读一致性（r值）。
• COUCHDB_WRITE_QUORUM：local.ini中写一致性（w值）。
• COUCHDB_REPLICAS：local.ini中副本数（n值）。
• COUCHDB_DEV_INIT：设为true时，启动前后台执行couchdb-dev脚本（适用于本地单节点开发）。
• COUCHDB_ADMIN_USER/COUCHDB_ADMIN_PASS：集群初始化使用的管理员账号密码。
• ERLANG_COOKIE：Erlang节点通信的cookie值。
• COUCHDB_CLUSTER_SIZE：覆盖Kubernetes StatefulSet的副本数（建议仅必要时使用）。

couchdiscover容器

• LOG_LEVEL：日志输出级别，默认INFO（主要为INFO或WARNING级别）。

部署示例

Docker运行（预构建镜像）

镜像可从以下地址获取：

• [***]
• https://hub.docker.com/r/telephoneorg/couchdb
• 拉取镜像：docker pull telephoneorg/couchdb

运行命令：

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

Docker Compose

拉取镜像：

bash
docker-compose pull

启动服务：

bash
# 前台启动（容器退出时中止）
docker-compose up --abort-on-container-exit

# 后台启动
docker-compose up -d

Kubernetes部署

1. 编辑kubernetes/<environment>下的manifest文件适配你的环境。
2. 创建Erlang cookie secret：

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

3. 创建CouchDB credentials secret：

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

4. 部署CouchDB：

bash
kubectl create -f kubernetes/<environment>

couchdiscover说明

couchdiscover是Kubernetes manifest中的sidecar容器，负责集群初始化：

信息发现方式

1. 通过解析StatefulSet容器主机名获取命名空间、StatefulSet名称、节点索引等信息。
2. 调用Kubernetes API获取StatefulSet和Endpoint对象，解析端点列表、端口、环境变量（含ConfigMaps和Secrets），并获取CouchDB管理员账号密码。
3. 集群大小默认等于StatefulSet副本数，可通过COUCHDB_CLUSTER_SIZE手动覆盖。

核心逻辑

主要逻辑在couchdiscover.manage.ClusterManager的run方法中：

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()

构建CouchDB release candidates

仅构建

bash
docker-compose build \
    --force-rm \
    --build-arg COUCHDB_VERSION=2.1.0 \
    --build-arg COUCHDB_RC=1

构建并执行make check

bash
docker-compose build \
    --force-rm \
    --build-arg COUCHDB_VERSION=2.1.0 \
    --build-arg COUCHDB_RC=1 \
    --build-arg COUCHDB_CHECK_RELEASE=true