如何使用 Cert Manager 对 Kubernetes 流量进行加密：让我们一起来实现加密功能，并使用内部 TLS 协议来保障数据安全

检查发行者是否已准备就绪：

kubectl get cluster issuer pebble

名称     是否准备就绪   创建时间
pebble   是        5秒前

如果“是否准备就绪”的状态仍为“否”，那么最常见的原因可能是caBundle文件格式不正确（请确认它是一条完整的Base64编码字符串，且没有换行符），或者从cert-manager命名空间无法访问Pebble。要检查是否可以访问Pebble，请执行以下命令：

kubectl run test-curl --rm -it --restart=Never \
  --image=curlimages/curl:latest \
  --namespace cert-manager -- \
  curl -k https://pebble.pebble.svc.cluster.local/dir

如果该命令返回JSON格式的数据，说明Pebble是可以访问的。

步骤5：部署一个示例应用程序

# echo-app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
        - name: echo
          image: ealen/echo-server:latest
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: echo
  namespace: default
spec:
  selector:
    app: echo
  ports:
    - port: 80
      targetPort: 80

kubectl apply -f echo-app.yaml

检查这些资源是否已经创建成功：

kubectl get deploy,pod,svc -n default

名称                   是否准备就绪   创建时间   是否可用   创建时间
deployment.apps/echo   1/1     1            1           32秒前

名称                        是否准备就绪   运行状态    重启次数   创建时间
pod/echo-5665fbcfdd-mbgxj   1/1     正在运行   0          36秒前

名称                 类型        集群内部IP      外部IP         端口        创建时间
service/echo         ClusterIP   10.96.103.114           80/TCP    40秒前
service/kubernetes   ClusterIP   10.96.0.1               443/TCP   32分钟前

步骤6：创建一个使用TLS协议的Ingress

cert-manager.io/cluster-issuer: pebble这一注释会告诉cert-manager自动为这个Ingress创建一个Certificate资源，并且会使用我们刚刚创建的发行者。主机名echo.pebble.local不需要在外部进行解析——因为在步骤3中我们已经让所有的DNS解析器都知道了这个主机的存在。

# echo-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: pebble
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - echo.pebble.local
      secretName: echo-tls     # cert-manager会创建这个Secret文件
  rules:
    - host: echo.pebble.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: echo
                port:
                  number: 80

kubectl apply -f echo-ingress.yaml

步骤7：观察证书的颁发过程

# 查看证书资源状态（当“READY”为True时，使用Ctrl-C暂停操作）
kubectl get certificate echo-tls -n default -w

NAME       READY   SECRET     AGE
echo-tls   False   echo-tls   5s
echo-tls   True    echo-tls   28s

当“READY”状态变为“True”时，证书就已经被颁发并存储在“echo-tls”这个Secret中。在一个运行正常的集群中，从CertificateRequest到Order、Challenge、solver pod，再最终生成Secret这一整个流程，完成时间通常不到一分钟：

kubectl get certificate,certificaterequest,order,challenge -n default

NAME                                   READY   SECRET     AGE
certificate.cert-manager.io/echo-tls   True    echo-tls   81s

NAME                                            APPROVED   DENIED   READY   ISSUER   AGE
certificaterequest.cert-manager.io/echo-tls-1   True                True    pebble   81s

NAME                                               STATE   AGE
order.acme_cert-manager.io/echo-tls-1-1824732543   valid   81s

一旦Order流程完成，相关的Challenge会自动被删除，因此此时执行kubectl get challenge -n default通常会显示没有结果——这说明操作成功了，并非出现了故障。

如果“READY”状态超过一分钟仍然为“False”，请参考本节末尾提供的故障排除建议。

检查所颁发的证书，以确认它确实是由Pebble签发的：

kubectl get secret echo-tls -n default -o jsonpath '{.data.tls\.crt}' | \
  base64 -d | openssl x509 -noout -issuer -subject -dates

issuer=CN=Pebble Intermediate CA 05478c
subject=
notBefore=May 17 19:09:22 2026 GMT
notAfter=Aug 15 19:09:21 2026 GMT

发行证书的机构是Pebble的中间CA，这一事实证明了整个ACME流程是顺利完成的。该证书的有效期为90天，cert-manager会在第60天自动为其更新。

在集群内部通过HTTPS访问echo服务器，以确认所有配置都已经正确连接起来：

kubectl run curltest --rm -it --restart=Never --image=curlimages/curl -- \
  curl -sk https://echo.pebble.local/

echo服务器应该会返回一个JSON数据，注意其中"x-forwarded-proto":"https"这一字段，它证明了请求是通过TLS协议、经由nginx传递过来的。

如果证书状态始终无法变为“READY”，可以尝试以下故障排除方法：

• kubectl describe order -n default——检查事件日志中是否出现了“DNS问题”或“连接失败”之类的信息。

• kubectl logs -n pebble deploy/pebble --tail=50——Pebble会在验证过程中记录它尝试访问的具体URL以及出现的任何错误。

• 如果Order状态一直处于“pending”状态且没有任何事件记录，说明cert-manager尚未完成相关处理，请等待30秒后再试。

• 如果Order被标记为invalid，很可能是因为第3步中的DNS配置有误。请重新执行两次nslookup检查。

• 如果应用Ingress配置时出现了与x509相关的错误，可能是因为你忽略了第一步中执行的kubectl delete validatingwebhookconfiguration ingress-nginx-admission这一操作。

步骤8：切换到Let’s Encrypt的测试环境配置（适用于真实公共域名）

Pebble已经证明了这种配置在本地环境中是可行的。现在，你需要将域名指向一个可公开访问的集群。步骤3中进行的DNS相关设置不再需要了——因为这个域名是真实存在的，所以任何解析器都能自动找到它。

首先使用Let’s Encrypt的测试环境配置。它使用的ACME协议与生产环境中的相同，但会设置较为宽松的请求速率限制，因此测试过程中出现的失败尝试不会导致你无法继续使用该服务：

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

kubectl apply -f cluster issuer-staging.yaml

# 将Ingress配置指向测试环境地址及真实的域名，然后强制重新生成证书
kubectl annotate ingress echo \
  cert-manager.io/cluster-issuer=letsencrypt-staging --overwrite -n default
kubectl delete secret echo-tls -n default

新生成的证书的发行者信息将会显示为(STAGING) Let’s Encrypt。

步骤9：切换到Let’s Encrypt的生产环境配置

当测试环境配置成功后，再使用生产环境的ClusterIssuer配置进行同样的操作。唯一的区别在于server地址的不同：

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

kubectl apply -f cluster issuer-prod.yaml
kubectl annotate ingress echo \
  cert-manager.io/cluster-issuer=letsencrypt-prod --overwrite -n default
kubectl delete secret echo-tls -n default

cert-manager会检测到缺失的Secret文件，并立即向Let’s Encrypt的生产环境请求一份受浏览器信任的证书。

cert-manager会在检测到Secret文件缺失时，自动使用生产环境的配置来重新申请证书。

如何通过DNS-01获取通配符证书

对于那些具有公共访问入口的单一域名来说，HTTP-01验证机制效果很好。但在以下两种情况下，你需要使用DNS-01：首先，当你的集群无法被公众访问时（例如内部集群、处于隔离环境中的集群，或者通过VPN连接的测试环境）；其次，当你需要一份能够覆盖该域名下所有子域名的通配符证书时。

DNS-01要求cert-manager能够在你的DNS服务提供商处创建和删除TXT记录。cert-manager内置了对Route53、Cloud DNS、Cloudflare、Azure DNS等众多服务的支持。

以下是使用AWS Route53的DNS-01配置示例：

# clusterIssuer-dns01.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns01
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-dns01-account-key
    solvers:
      - dns01:
          route53:
            region: us-east-1
            # 在生产环境中应使用IRSA（服务账户的IAM角色）而非静态凭证
            # hostedZoneID: 请替换为你的主机区域ID

使用上述发证机构生成的通配符证书配置如下：

# wildcard-cert.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example-com
  namespace: default
spec:
  secretName: wildcard-example-com-tls
  issuerRef:
    name: letsencrypt-dns01
    kind: ClusterIssuer
  commonName: "*.example.com"
  dnsNames:
    - "*.example.com"
    - "example.com"        # 也覆盖顶级域名
  duration: 2160h           # 90天
  renewBefore: 720h         # 在证书到期前30天自动续订

名称为wildcard-example-com-tls的秘密文件可以被default命名空间中的任何Ingress服务引用。所有子域名——如api.example.com、dashboard.example.com、staging.example.com——都由这张会自动更新的证书覆盖。

如果使用Cloudflare而非Route53，solvers部分的配置如下：

    solvers:
      - dns01:
          cloudflare:
            email: your-email@example.com
            apiTokenSecretRef:
              name: cloudflare-api-token
              key: api-token

演示2——为服务间TLS通信设置内部CA

Let’s Encrypt证书非常适合用于公开服务的认证需求，但对于内部服务来说——比如一个gRPC微服务调用另一个微服务，或者一个Web应用与它的数据库进行交互——并不需要公众信任。此时你需要的是一个被集群所信任的CA机构，并且这个机构能够为那些在公共DNS系统中并不存在的服务名称颁发证书。

cert-manager提供的CA发证机制可以解决这个问题。你只需创建一个根CA证书，然后告知cert-manager这一信息，之后就可以使用该根CA为内部服务颁发证书了。任何信任这个根CA的服务，都会信任它所颁发的所有证书。

步骤1：创建自签名的ClusterIssuer

自签名的发证机构生成的证书是由该机构自身签署的——也就是说，它本身就是自己的CA。你可以利用这一机制作为第一步，来生成根CA证书。

# selfsigned-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned
spec:
  selfSigned: {}

kubectl apply -f self-signed-issuer.yaml

步骤 2：创建根CA证书

使用自签发的发证机构来创建一个CA证书。isCA: true这一字段告诉cert-manager，该证书可以用于为其他证书签名：

# internal-ca.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: internal-ca
  namespace: cert-manager    # 存储在cert-manager命名空间中
spec:
  isCA: true
  commonName: internal-ca
  secretName: internal-ca-secret
  duration: 87600h           # 10年——这是一个根CA证书
  renewBefore: 720h
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer

kubectl apply -f internal-ca.yaml
kubectl get certificate internal-ca -n cert-manager

NAME          READY   SECRET               AGE
internal-ca   True    internal-ca-secret   8s

步骤 3：创建一个由根CA证书支持的CA ClusterIssuer

现在创建一个使用刚才创建的根CA密钥的ClusterIssuer。这个发证机构将负责为你的内部服务生成证书：

# internal-ca-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: internal-ca
spec:
  ca:
    secretName: internal-ca-secret   # 引用cert-manager命名空间中的密钥

kubectl apply -f internal-ca-issuer.yaml
kubectl get cluster issuer internal-ca

NAME          READY   AGE
internal-ca   True    5s

步骤 4：为内部服务生成证书

现在为某个内部的gRPC服务生成一份证书。dnsNames字段使用了Kubernetes的内部DNS命名格式——..svc.cluster.local：

# payments-cert.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: payments-tls
  namespace: production
spec:
  secretName: payments-tls-secret
  issuerRef:
    name: internal-ca
    kind: ClusterIssuer
  commonName: payments.production.svc.cluster.local
  dnsNames:
    - payments.production.svc.cluster.local
    - payments.production.svc
    - payments
  duration: 2160h     # 90天
  renewBefore: 360h   # 在证书到期前15天进行续期

kubectl create namespace production
kubectl apply -f payments-cert.yaml
kubectl get certificate payments-tls -n production

名称           是否已准备就绪  密钥              使用时长
payments-tls   是    payments-tls-secret   6秒

密钥 payments-tls-secret 现在包含了文件 tls.crt、tls.key 和 ca.crt。请将这个密钥配置到您的应用程序容器中：

# 在您的 Deployment 配置文件中添加以下内容：
volumes:
  - 名称: tls
    密钥:
      名称: payments-tls-secret
containers:
  - 名称: payments
    卷挂配置:
      - 名称: tls
        挂载路径: /etc/tls
        只读属性: 是

您的应用程序会读取 /etc/tls/tls.crt 和 /etc/tls/tls.key 文件来配置 TLS 连接；其他需要信任这些证书的服务则会读取 /etc/tls/ca.crt 文件。

步骤 5：使用 trust-manager 分发 CA 证书包

使用自定义 CA 证书的一个问题是，所有服务都需要知道这个 CA 证书的存在。cert-manager 的辅助工具 trust-manager 通过将 CA 证书包作为 ConfigMap 分发到所有命名空间中，从而解决了这个问题：

helm upgrade trust-manager oci://quay.io/jetstack/charts/trust-manager \
  --install \
  --namespace cert-manager \
  --wait

创建一个 Bundle 资源，该资源会从 internal-ca-secret 中获取 CA 证书，并将其分发到整个集群中：

# ca-bundle.yaml 文件内容：
apiVersion: trust.cert-manager.io/v1alpha1
kind: Bundle
metadata:
  名称: internal-ca-bundle
spec:
  来源:
    - 密钥:
        名称: internal-ca-secret
        内容: ca.crt
  目标:
    configMap:
      名称: ca-bundle.crt
    命名空间筛选条件:
      匹配标签:
        # 将证书分发到所有带有此标签的命名空间中
        kubernetes.io/metadata.name: production

kubectl apply -f ca-bundle.yaml

几秒钟后，所有符合条件的命名空间都会拥有一个名为 internal-ca-bundle 的 ConfigMap，其中包含了 CA 证书。应用程序只需挂载这个 ConfigMap，就可以信任由集群内部生成的证书了，而无需为每个服务单独进行配置。

步骤 6：验证证书链的有效性

# 提取 CA 证书和服务证书
kubectl get secret payments-tls-secret -n production \
  -o jsonpath '{.data.ca\.crt}' | base64 -d > ca.crt

kubectl get secret payments-tls-secret -n production \
  -o jsonpath '{.data.tls\.crt}' | base64 -d > payments.crt

# 验证证书是否由 CA 机构签名
openssl verify -CAfile ca.crt payments.crt

验证结果：payments.crt: OK

证书轮换的原理

证书轮换是证书管理中最为常见的问题之一。cert-manager 会自动处理这一过程，但了解其工作原理有助于您对其进行优化或在出现问题时进行调试。

cert-manager会监控它所管理的所有Certificate资源，并检查存储在Secret中的证书是否即将过期。当证书的剩余有效期限低于renewBefore设定的阈值时，cert-manager会自动触发更新流程。默认情况下，renewBefore的值是证书总有效期的1/3——因此，有效期为90天的证书会在第60天开始进入更新阶段。

更新过程会生成一个新的CertificateRequest，然后完成整个颁发流程，并最终更新Secret中的证书信息。新的证书会原子性地替换原有的证书。那些通过文件挂载来监控证书变化的应用程序（大多数现代Web服务器和gRPC框架都属于这类应用）能够在不重启的情况下获取到新证书。

# 查看当前的证书轮换状态
kubectl describe certificate echo-tls -n default

在输出结果中寻找以下字段：

Status:
  Not After:   2024-06-18T10:00:00Z
  Not Before:  2024-03-20T10:00:00Z
  Renewal Time: 2024-05-18T10:00:00Z   # cert-manager将在这个时间开始更新证书
  Conditions:
    Type:    Ready
    Status:  True
    Message:  证书是有效的，且尚未过期

如果更新过程失败——例如因为无法完成HTTP-01验证请求——cert-manager会采用指数退避策略重新尝试。现有的证书会继续正常使用，直到其真正过期为止，这样你就有足够的时间来排查问题。

kubectl get events -n default --field-selector reason=Issued
kubectl get events -n default --field-selector reason=Failed

正确设置renewBefore的值非常重要：对于面向公众的服务来说，将renewBefore设置为证书有效期限的30天之前是一个合理的缓冲时间；而对于那些有效期仅为24小时的内部证书而言，应将renewBefore设置为8小时，这样即使第一次尝试失败，证书也能在到期前被及时更新。需要注意的是，千万不要将renewBefore设置得超过证书有效期限的一半——否则cert-manager会立即尝试更新刚刚颁发的证书。

清理操作

# 删除示例资源
kubectl delete ingress echo -n default
kubectl delete service echo -n default
kubectl delete deployment echo -n default
kubectl delete secret echo-tls -n default
kubectl delete certificate payments-tls -n production
kubectl delete namespace production

# 卸载cert-manager和trust-manager
helm uninstall trust-manager -n cert-manager
helm uninstall cert-manager -n cert-manager
kubectl delete namespace cert-manager

# 删除ClusterIssuers配置
kubectl delete clusterIssuer letsencrypt-staging letsencrypt-prod \
  internal-ca selfsigned 2>/dev/null

总结

Kubernetes将TLS配置的完全权限交给了用户。在本文中，我们详细了解了与TLS配置相关的各项任务，包括那些面向公众的服务以及内部系统中的配置管理流程。

在公共环境中，您使用了当前的OCI Helm图表来安装cert-manager，创建了一个由Let’s Encrypt支持的ClusterIssuer，并观察了cert-manager如何完成整个ACME HTTP-01认证流程——从生成临时解决方案Pod到将有效的证书存储在Kubernetes的Secret中。您也了解到，将环境从测试环境切换到生产环境只需要修改一行配置注释，而且cert-manager会自动在证书过期之前为其进行续期。

在内部环境中，您利用cert-manager自签发的证书创建了一个私有的CA，以此为基础生成了ClusterIssuer，并为那些仅存在于集群内部的内部服务名称颁发了证书。您还使用了trust-manager在整个集群范围内分发这些CA证书包，这样各服务就可以无需进行单独配置就能互相信任彼此的证书。此外，您也学会了如何使用openssl工具来验证证书链，从而确保在将系统部署到生产环境之前一切正常。

了解证书更新机制是区分那些能够熟练管理TLS协议的团队与那些因为证书过期而在凌晨3点被惊醒的团队的关键。cert-manager会自动完成证书续期工作，但renewBefore字段为您提供了额外的安全保障——请确保正确设置这一参数，并掌握查看证书续期状态的方法。

本文中提到的所有YAML配置文件及Helm参数值，都可以在DevOps-Cloud-Projects的GitHub仓库中找到。