cert-manager 1.13 自动证书管理 + Ingress TLS 自动化

Wed, 15 Jan 2025 00:00:00 +0800

cert-manager 是 K8s 证书管理的"标准答案"

K8s 集群对外暴露 HTTPS 服务的痛点：

证书要申请、签发、安装
90 天过期，要定期续期
多域名、泛域名、通配符场景配置复杂

cert-manager 是 CNCF 沙箱项目，自动从 Let’s Encrypt、HashiCorp Vault 等 CA 申请、签发、自动续期证书，完全 K8s-native——证书本身就是 K8s 的 Secret 资源。

适用版本：cert-manager v1.13.3 / K8s 1.28.5 / quay.io 镜像

1. 架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


 ┌─────────────────┐
 │ Let's Encrypt │
 │ ACME Server │
 └────────┬────────┘
 │ HTTP-01 / DNS-01
 │ challenge
 ┌────────▼────────┐
 │ cert-manager │
 │ - controller │
 │ - webhook │
 │ - cainjector │
 └────────┬────────┘
 │ 创建 / 更新
 ┌────────▼────────┐
 │ K8s Secret │
 │ (tls.crt, │
 │ tls.key) │
 └────────┬────────┘
 │ 引用
 ┌────────▼────────┐
 │ Ingress │
 │ (nginx) │
 └─────────────────┘

三个核心组件：

cert-manager：Controller 监听 Certificate 资源，自动签发 / 续期
webhook：API 校验
cainjector：把 CA 注入到 webhook / apiserver

2. 部署 cert-manager

2.1 安装

1
2
3
4
5


mkdir -p /data/k8scnf/cert-manager && cd /data/k8scnf/cert-manager

# 官方 yaml
curl -L -o cert-manager.yaml \
 https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.yaml

2.2 镜像

quay.io 是红帽的镜像，国内网络直连一般通，不用额外加速：

1
2
3


image: "quay.io/jetstack/cert-manager-cainjector:v1.13.3"
image: "quay.io/jetstack/cert-manager-webhook:v1.13.3"
image: "quay.io/jetstack/cert-manager-controller:v1.13.3"

如果是内网部署，要先 tag 推到私有 harbor：

1
2
3
4


docker pull quay.io/jetstack/cert-manager-controller:v1.13.3
docker tag quay.io/jetstack/cert-manager-controller:v1.13.3 <harbor>/base/jetstack/cert-manager-controller:v1.13.3
docker push <harbor>/base/jetstack/cert-manager-controller:v1.13.3
# cainjector / webhook 同样

2.3 应用

1

kubectl apply -f /data/k8scnf/cert-manager/cert-manager.yaml

2.4 验证

1
2
3
4
5


kubectl get pod -n cert-manager
# NAME READY STATUS RESTARTS AGE
# cert-manager-5c9d8879fd-rtlwb 1/1 Running 0 106s
# cert-manager-cainjector-6cc9b5f678-5fbqk 1/1 Running 0 106s
# cert-manager-webhook-7bb7b75848-7bqzq 1/1 Running 0 106s

3 个 Pod 都 Running，部署成功。

3. ClusterIssuer / Issuer

3.1 概念

Issuer：单一 namespace 内的证书签发者
ClusterIssuer：集群范围（cluster-wide），可被所有 namespace 引用

生产用 ClusterIssuer。

3.2 Let’s Encrypt Staging（测试用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: letsencrypt-staging
spec:
 acme:
 server: https://acme-staging-v02.api.letsencrypt.org/directory
 email: ops@example.com
 privateKeySecretRef:
 name: letsencrypt-staging-account-key
 solvers:
 - http01:
 ingress:
 class: nginx

3.3 Let’s Encrypt Production（生产用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: letsencrypt-prod
spec:
 acme:
 server: https://acme-v02.api.letsencrypt.org/directory
 email: ops@example.com
 privateKeySecretRef:
 name: letsencrypt-prod-account-key
 solvers:
 - http01:
 ingress:
 class: nginx

Staging 配额宽（5 个 / 周 / 域名），适合调试；Production 有速率限制。生产前用 Staging 验证完再切 Production。

应用：

1
2
3
4
5


kubectl apply -f cluster-issuer.yaml

# 看状态
kubectl get clusterissuer
kubectl describe clusterissuer letsencrypt-prod

4. 自动签发证书

4.1 简单域名

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: example-com
 namespace: default
spec:
 secretName: example-com-tls
 issuerRef:
 name: letsencrypt-prod
 kind: ClusterIssuer
 dnsNames:
 - example.com
 - www.example.com

1
2
3
4


kubectl apply -f certificate.yaml
kubectl get certificate
# NAME READY SECRET AGE
# example-com True example-com-tls 30s

4.2 Ingress 自动关联

让 cert-manager 自动从 Ingress 的 spec.tls.hosts 创建证书——加 annotation：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: my-app
 annotations:
 cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - app.example.com
 secretName: app-example-com-tls
 rules:
 - host: app.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: my-app
 port:
 number: 80

cert-manager 会自动创建 Certificate 资源 + 触发 HTTP-01 challenge + 把证书写到 app-example-com-tls Secret。

5. 泛域名（DNS-01）

Let’s Encrypt 对泛域名 *.example.com 只支持 DNS-01 challenge（不是 HTTP-01）。需要 DNS 提供商 API。

5.1 阿里云 DNS 示例

1
2
3
4
5
6


# 创建阿里云 RAM AccessKey（DNS 权限）
# AccessKey ID / Secret 保存到 Secret
kubectl create secret generic alidns-secret \
 --from-literal=access-key={{ALIYUN_ACCESS_KEY}} \
 --from-literal=secret-key={{ALIYUN_SECRET_KEY}} \
 -n cert-manager

实际密钥用占位符 {{ALIYUN_ACCESS_KEY}} {{ALIYUN_SECRET_KEY}} 替代。

5.2 ClusterIssuer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: letsencrypt-prod-dns
spec:
 acme:
 server: https://acme-v02.api.letsencrypt.org/directory
 email: ops@example.com
 privateKeySecretRef:
 name: letsencrypt-prod-account-key
 solvers:
 - dns01:
 rfc2136:
 nameserver: dns17.hichina.com:53
 tsigAlgorithm: HMACSHA1

不同 DNS 提供商插件不同（cert-manager-webhook-*），需要先部署对应插件 Pod。

5.3 申请泛域名证书

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: wildcard-example-com
 namespace: default
spec:
 secretName: wildcard-example-com-tls
 issuerRef:
 name: letsencrypt-prod-dns
 kind: ClusterIssuer
 dnsNames:
 - "*.example.com"
 - example.com

6. 自动续期

cert-manager 在证书 剩余有效期 < 30 天 时自动续期。续期过程对用户完全透明：

1
2
3
4
5
6
7
8


kubectl describe certificate example-com
# Events:
# Type Reason Age From Message
# ---- ------ ---- ---- -------
# Normal OrderCreated 60s cert-manager Created Order resource "example-com-12345"
# Normal OrderComplete 45s cert-manager Order "example-com-12345" completed successfully
# Normal CertIssued 45s cert-manager Certificate issued successfully
# Normal CertRenewed 5d cert-manager Certificate scheduled for renewal in 29 days

7. 与自建 CA 集成（私有场景）

如果内网不连公网 Let’s Encrypt，可以自建 CA（cfssl / step-ca）：

1
2
3
4
5
6
7


apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: internal-ca
spec:
 ca:
 secretName: internal-ca-secret

先创建 CA 根证书 Secret：

1
2
3
4
5


cfssl gencert -initca ca-csr.json | cfssljson -bare ca
kubectl create secret tls internal-ca-secret \
 --cert=ca.pem \
 --key=ca-key.pem \
 -n cert-manager

8. 实战：HTTPS 反代内网应用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# 1. 部署应用（假设已部署 my-app Service 80 端口）
apiVersion: v1
kind: Service
metadata:
 name: my-app
spec:
 selector:
 app: my-app
 ports:
 - port: 80
 targetPort: 8080

---
# 2. Ingress + cert-manager 自动证书
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: my-app
 annotations:
 cert-manager.io/cluster-issuer: "letsencrypt-prod"
 nginx.ingress.kubernetes.io/proxy-body-size: "2048m"
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - app.example.com
 secretName: app-example-com-tls
 rules:
 - host: app.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: my-app
 port:
 number: 80

1
2
3
4
5
6


# 等 60 秒
kubectl get certificate -n default
# READY = True

curl https://app.example.com
# 浏览器看到锁标志 + 证书

9. 排错

9.1 证书 Pending 不签发

1
2
3


kubectl describe certificate my-cert
kubectl describe challenge
# 常见：HTTP-01 challenge 失败，因为 80 端口未暴露

9.2 “rateLimited” 错误

Let’s Encrypt Production 速率限制（同一域名 50 证书 / 周）。换域名或等下周。

9.3 续期失败

1
2


kubectl describe order
# 找原因：DNS / 网络 / CA 配置

9.4 内网环境无外网

Let’s Encrypt 走 HTTP-01 必须公网可达。改：

自建 CA（cfssl + step-ca）
或用 DNS-01（DNS TXT 记录验证，不需要 HTTP）

9.5 Pod 启动失败

1
2


kubectl logs -n cert-manager deploy/cert-manager
# 通常是 webhook 配置问题，看 Events

10. 小结

cert-manager 让 K8s 证书管理"零运维"：

HTTP-01 适合公网 Ingress（最简单）
DNS-01 适合泛域名 + 内网
自建 CA 适合纯内网
cert-manager 自动续期，永远不用手动管理证书
Staging → Production 两步走避免触发速率限制

下一步：Istio 1.20 服务网格：bookinfo + Kiali/Grafana 面板。

Ingress on Liangweidong's blog