phpdockerio/kong-certbot-agent

Kong Certbot Agent

镜像概述和主要用途

Kong Certbot Agent是一个基于cron的Certbot代理工具，用于将Let's Encrypt证书集成到Kong中。它能够自动获取指定子域名的Let's Encrypt证书，并将这些证书配置到Kong，特别适合在Kubernetes环境中部署Kong时使用。

兼容性

• Kong Certbot Agent 3.x：兼容Kong 0.14和1.x，Kubernetes示例兼容Kubernetes >= 1.8
• Kong Certbot Agent 2.x：兼容Kong 0.14和1.x，Kubernetes示例兼容Kubernetes <= 1.8
• Kong Certbot Agent 1.x：兼容Kong <= 0.13，Kubernetes示例兼容Kubernetes <= 1.8

核心功能和特性

• 基于cron的自动证书更新机制，默认每24小时运行一次
• 支持指定多个域名，自动获取Let's Encrypt证书
• 自动将获取的证书配置到Kong
• 提供测试证书功能，避免Let's Encrypt的请求限制
• 适合Kubernetes环境部署，提供cronjob示例

使用场景和适用范围

• 需要为Kong管理的域名自动配置Let's Encrypt证书的场景
• Kubernetes环境中部署Kong的HTTPS证书管理
• 需要定期自动更新SSL/TLS证书的Kong部署

使用方法和配置说明

运行容器

容器通过环境变量进行配置，需提供以下环境变量：

• KONG_ENDPOINT：Kong Admin API的HTTP端点（不含路径），例如 http://kong:8001
• EMAIL：与Let's Encrypt证书关联的电子邮件地址
• DOMAINS：逗号分隔的域名列表，用于请求证书

容器会自动每24小时运行一次更新脚本，获取并配置证书。

Kong配置

为使Let's Encrypt的HTTP挑战正常工作，需在Kong中配置指向该容器的服务和路由，且必须对所有请求证书的域名响应。

服务定义示例

json
{
    "host": "kong-certbot-agent",
    "created_at": 1543512083,
    "connect_timeout": 60000,
    "id": "service-id-foo",
    "protocol": "http",
    "name": "KongCertbot",
    "read_timeout": 60000,
    "port": 80,
    "updated_at": 1543513810,
    "retries": 5,
    "write_timeout": 60000
}

假设 http://kong-certbot-agent 正确指向代理容器。

路由定义示例

json
{
    "created_at": 1543512115,
    "strip_path": false,
    "hosts": [
        "your.list",
        "of.domains",
        "for.the",
        "same.certificate"
    ],
    "preserve_host": false,
    "regex_priority": 0,
    "updated_at": 1543513584,
    "paths": [
        "/.well-known/acme-challenge"
    ],
    "service": {
        "id": "service-id-foo"
    },
    "methods": [
        "GET"
    ],
    "protocols": [
        "http"
    ],
    "id": "route-id-foo"
}

Kubernetes部署

提供kubernetes cronjob示例作为部署指南。注意：Kubernetes服务在Certbot运行并请求证书时才会有HTTP监听，其他时间可能会超时。

命令行工具使用

可手动运行命令，自定义调度，示例如下：

获取生产环境证书

bash
docker run -it --rm \
    -e KONG_ENDPOINT=http://kong-admin:8001 \
    -e EMAIL=foo@bar.com \
    -e DOMAINS=bar.com,foo.bar.com,www.bar.com \
    phpdockerio/kong-certbot-agent

获取测试证书（避免请求限制）

bash
docker run -it --rm \
    -e KONG_ENDPOINT=http://kong-admin:8001 \
    -e EMAIL=foo@bar.com \
    -e DOMAINS=bar.com,foo.bar.com,www.bar.com \
    -e TEST_CERT=true \
    phpdockerio/kong-certbot-agent

FAQ

支持多少个域名？

可指定最多100个域名，但会生成一个包含所有域名的证书。建议按逻辑分组设置不同的cronjob。若某个域名的HTTP挑战失败，整个证书获取都会失败。

是否支持通配符证书？

不支持。Certbot的通配符证书需要DNS挑战，而本代理基于HTTP挑战，因此不支持通配符证书。

首次设置注意事项

Let's Encrypt对每个域名每周有50次证书请求限制，首次设置时需注意：

• 初始使用测试证书（设置TEST_CERT=true或命令中添加--test-cert），测试环境限制更宽松
• 确保调度不会重试失败的命令，避免快速超出请求限制（示例cronjob已处理此问题）

证书更新频率？

Let's Encrypt证书有效期为3个月，建议每60天更新一次（示例cronjob按此配置）。无需过于频繁更新，避免浪费资源。