dsteinkopf/kong-certbot-agent

Kong Certbot Agent

镜像概述和主要用途

Kong Certbot Agent是一个基于cron的Certbot代理，专为与Kong集成设计，用于自动获取Let's Encrypt SSL证书并将其配置到Kong API网关。该工具通过定时任务（每24小时）自动检查证书状态，更新需要续期的证书，简化Kong的SSL证书管理流程。

兼容性

• Kong >= 0.14：使用Kong Certbot Agent 2.x版本
• Kong <= 0.13：使用Kong Certbot Agent 1.x版本

核心功能和特性

• 基于cron的定时任务，自动检查并更新证书（每24小时运行一次）
• 与Let's Encrypt集成，自动获取免费SSL证书
• 支持多域名证书（通过逗号分隔的域名列表）
• 自动将获取的证书配置到Kong
• 提供测试证书功能（使用Let's Encrypt测试环境，避免正式环境请求限制）
• 支持Docker和Kubernetes部署

使用场景和适用范围

适用于需要为Kong API网关管理SSL证书的场景，特别是：

• 需要自动获取和续期Let's Encrypt证书的环境
• 使用Kong作为API网关并需要配置HTTPS的服务
• 希望简化SSL证书管理流程的Docker或Kubernetes环境

使用方法和配置说明

运行容器

必要环境变量

• KONG_ENDPOINT：Kong Admin API的HTTP端点（不含路径），例如 http://kong:8001
• EMAIL：与Let's Encrypt证书关联的***地址（用于证书通知和续期提醒）
• DOMAINS：逗号分隔的域名列表，用于申请证书，例如 example.com,www.example.com

卷挂载要求

• 必须持久化 /etc/letsencrypt 目录（存储Let's Encrypt证书和续期数据）
• 可选持久化 /var/log/kong-certbot-agent 目录（存储日志输出）

部署示例

bash
docker run -d \
  -e KONG_ENDPOINT="http://kong:8001" \
  -e EMAIL="admin@example.com" \
  -e DOMAINS="example.com,www.example.com" \
  -v /path/to/letsencrypt:/etc/letsencrypt \
  -v /path/to/logs:/var/log/kong-certbot-agent \
  phpdockerio/kong-certbot-agent

容器启动后将自动运行更新脚本，每24小时检查并更新需要续期的证书。

Kong配置

为确保Let's Encrypt域名验证正常工作，需在Kong中创建特定API路由，指向该容器的验证路径。

Kong API配置示例

在Kong中创建以下API配置（通过Kong Admin API或配置文件）：

json
{
  "methods": ["GET", "OPTIONS"],
  "uris": ["/.well-known/acme-challenge"],
  "upstream_url": "http://kong-certbot-agent/.well-known/acme-challenge/",
  "strip_uri": true,
  "name": "certbot",
  "http_if_terminated": true,
  "retries": 5,
  "upstream_connect_timeout": 60000,
  "upstream_send_timeout": 60000,
  "upstream_read_timeout": 60000
}

注意：http://kong-certbot-agent 必须正确指向Kong Certbot Agent容器的网络地址。

Kong配置验证

Let's Encrypt验证过程中，会通过HTTP请求域名的 /.well-known/acme-challenge 路径。上述Kong配置确保该请求能正确路由到Kong Certbot Agent容器，完成域名所有权验证。

Kubernetes部署

提供Kubernetes环境下的部署示例，包括Service、Deployment和CronJob配置。

可用配置示例

• Kubernetes Service：用于暴露Kong Certbot Agent服务
• Deployment配置：常规部署（持续运行，依赖内部cron任务）
• CronJob配置：定时任务部署（需Kubernetes 1.4+，支持CronJob资源）

注意事项

• Kubernetes Service在Certbot未运行时会超时，因为仅在Certbot请求Let's Encrypt证书时才监听HTTP端口
• CronJob资源要求Kubernetes 1.4+版本，旧版本需使用Deployment配合内部cron任务

命令行工具

可手动运行命令行工具，自定义证书更新调度逻辑，支持以下操作：

获取正式证书并配置到Kong

bash
docker run -it --rm \
  -v /path/to/letsencrypt:/etc/letsencrypt \
  phpdockerio/kong-certbot-agent \
  ./certbot-agent certs:update \
  http://kong-admin:8001 \
  admin@example.com \
  example.com,www.example.com,api.example.com

获取测试证书（使用Let's Encrypt测试环境）

bash
docker run -it --rm \
  -v /path/to/letsencrypt:/etc/letsencrypt \
  phpdockerio/kong-certbot-agent \
  ./certbot-agent certs:update -t \
  http://kong-admin:8001 \
  admin@example.com \
  example.com,www.example.com,api.example.com

说明：-t 参数指定使用Let's Encrypt测试环境（Staging Environment），避免正式环境因频繁请求触发速率限制。