valitvin/certbot

certbot

镜像概述和主要用途

certbot镜像是一个适用于Kubernetes环境的轻量级Certbot工具，旨在简化Ingress资源的SSL证书管理流程。通过与Ingress控制器集成，自动处理Let's Encrypt的ACME验证流程，并将生成的SSL证书存储为Kubernetes Secret，实现Ingress的HTTPS配置自动化。

核心功能和特性

• 自动与Let's Encrypt交互，获取免费SSL/TLS证书
• 通过Ingress路由处理ACME验证流量（/.well-known/acme-challenge路径）
• 证书自动存储为Kubernetes Secret，便于Ingress直接引用
• 支持多域名配置，通过环境变量灵活指定目标域名
• 轻量级设计，适合Kubernetes环境部署

使用场景和适用范围

适用于Kubernetes集群中需要为Ingress资源配置SSL/TLS证书的场景，特别适合以下用户：

• 需要为Ingress启用HTTPS的开发者和运维人员
• 希望自动化管理Let's Encrypt证书生命周期的团队
• 使用Ingress控制器（如NGINX、Traefik等）的Kubernetes环境

使用方法和配置说明

前提条件

• 已部署Kubernetes集群
• 已安装Ingress控制器
• 目标域名已正确解析到Ingress控制器的外部IP

步骤1：配置Ingress规则

创建或修改Ingress资源，将ACME验证路径路由到certbot服务：

yaml
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: <your-ingress-name>
  namespace: <your-namespace>
spec:
  rules:
  - host: <your-host>  # 例如：example.com
    http:
      paths:
      - path: /.well-known/acme-challenge
        pathType: Prefix
        backend:
          service:
            name: certbot
            port:
              number: 80
      - <your-other-paths>  # 其他业务路径配置

步骤2：创建Service

创建Service以接收Ingress转发的验证流量：

yaml
kind: Service
apiVersion: v1
metadata:
  name: certbot
  namespace: <your-namespace>
spec:
  selector:
    run: certbot  # 需与Pod标签匹配
  ports:
  - name: certbot
    port: 80
    targetPort: 80

步骤3：部署certbot Pod

使用kubectl运行certbot镜像，配置必要环境变量：

bash
kubectl run -n <your-namespace> certbot \
  --image=valitvin/certbot \
  -l 'run=certbot' \
  --env="DOMAINS=<domain-list>"  # 逗号分隔的域名列表，如example.com,www.example.com \
  --env="EMAIL=<your-email>"  # Let's Encrypt注册邮箱 \
  --env="KUBE_NAMESPACE=<your-namespace>"  # 目标命名空间 \
  --env="CERTNAME=<secret-name>"  # 存储证书的Secret名称

环境变量说明

RBAC权限说明

若集群启用RBAC，运行certbot的服务账户需具备在KUBE_NAMESPACE命名空间中创建Secret的权限。可通过以下配置实现：

yaml
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: certbot-secret-creator
  namespace: <your-namespace>
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["create", "get", "update"]

---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: certbot-binding
  namespace: <your-namespace>
subjects:
- kind: ServiceAccount
  name: default  # 使用默认服务账户或指定自定义账户
  namespace: <your-namespace>
roleRef:
  kind: Role
  name: certbot-secret-creator
  apiGroup: rbac.authorization.k8s.io

已知问题

• 流量转发延迟：Service和Ingress可能无法立即将流量转发到新创建的certbot Pod，导致ACME验证超时。建议部署后等待1-2分钟，或通过kubectl get endpoints certbot -n <namespace>确认端点是否正常。