跳到主要内容
基础知识

k8s ingress ssl证书怎么配?Ingress TLS Secret 签发、挂载、轮换与报错排查全流程

k8s ingress ssl证书 — k8s ingress ssl证书怎么配?Ingress TLS Secret 签发、挂载、轮换与报错排查全流程
核心结论

1. k8s ingress ssl证书的本质是:把 PEM 证书与私钥存成同命名空间的 kubernetes.io/tls Secret,再在 Ingress 的 spec.tls[].secretName 引用;ingress-nginx 1.11 会监听该 Secret 变化,通常 5~30 秒内热加载,不需要重启 Pod。 2. 手动方式最小命令:kubectl create secret tls shop-tls --cert=tls.crt --key=tls.key -n prod,Secret 与 Ingress 必须同 namespace,否则 controller 报 secret not found,443 回落到 Fake Certificate。 3. cert-manager v1.16 方案只需在 Ingress 上加注解 cert-manager.io/cluster-issuer: letsencrypt-prod,且 tls.secretName 与 Certificate 的 secretName 完全一致,Certificate READY=True 一般耗时 30~90 秒。 4. 验证一条命令:openssl s_client -connect :443 -servername shop.example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates,重点看 SAN 是否覆盖域名、notAfter 是否大于 30 天。 5. Let's Encrypt 限制为每注册域名每周 50 张、重复证书每周 5 张、验证失败每小时 5 次,调试期先切 staging 端点 https://acme-staging-v02.api.letsencrypt.org/directory。

为什么 k8s ingress ssl证书配完仍然报证书错误?先看这 5 个根因

配完 Ingress TLS 却还是报证书错误,八成不是 controller 的锅,而是下面 5 个根因之一。先记住一个前提:Ingress 对象本身不存证书。据 Kubernetes 官方文档 Ingress 的 TLS 章节,networking.k8s.io/v1 的 Ingress 只有 spec.tls[].hosts 和 spec.tls[].secretName 两个字段,证书实体始终在 Secret 里,Ingress 只是”引用”。搞清这条引用链在哪一环断掉,问题就定位了。

根因 1:Secret 类型或键名不对,controller 直接忽略

Secret 必须是 type: kubernetes.io/tls,且同时含 tls.crt、tls.key 两个键。用 Opaque 存证书时 ingress-nginx 不会报错,只是静默跳过——这是最隐蔽的一种失败。

# 正确创建方式,kubectl 会校验键名与 PEM 格式
kubectl create secret tls shop-tls 
  --cert=fullchain.pem    # 叶证书 + 中间证书,顺序不可颠倒
  --key=privkey.pem       # 必须与证书公钥匹配,否则 create 阶段即失败
  -n shop

# 自检:type 是否为 kubernetes.io/tls,两个键是否都在
kubectl get secret shop-tls -n shop -o jsonpath='{.type}{"n"}{.data}' | head -c 200

根因 2:跨命名空间引用——apply 不报错,日志才报错

Secret 只能被同 namespace 的 Ingress 引用。把 secretName: shop-tls 写进另一个 namespace 的 Ingress,kubectl apply 依然成功(API Server 不做跨对象校验),但 ingress-nginx 日志会出现:

unexpected error obtaining pem ... secret "shop-tls" not found

此时 443 端口回落到 controller 的默认证书。排查命令:

kubectl get ingress shop -n shop -o jsonpath='{.spec.tls[0].secretName}{"n"}'
kubectl get secret shop-tls -n shop          # 换成 Ingress 所在 namespace 再查一次

根因 3:SNI 匹配失败

spec.tls[].hosts 与 spec.rules[].host 不一致,或客户端访问了未列出的域名时,nginx 用 default_server 证书应答。典型报错:

curl: (60) SSL: no alternative certificate subject name matches target host name
# Go 客户端侧表现为
x509: certificate is valid for ingress.local, not shop.example.com

浏览器则提示证书域名不符。修复要点:spec.tls[].hosts 必须覆盖 rules[].host,通配符 *.example.com 仅匹配一级子域。

根因 4:证书链不完整

只上传叶证书、漏掉中间证书时,浏览器与 Go 客户端报 x509: certificate signed by unknown authority。正确顺序是叶证书在前、中间证书在后,根证书不要放(据 Let’s Encrypt 文档,其 fullchain 已含中间证书;把根证书也拼进去会让握手体积变大,且部分客户端的校验路径判断异常)。验证:

openssl s_client -connect shop.example.com:443 -servername shop.example.com -showcerts /dev/null | grep -c "BEGIN CERTIFICATE"   # 期望 ≥2
openssl verify -untrusted chain.pem leaf.pem

根因 5:签发侧失败被 Ingress 掩盖

cert-manager 的 Certificate 处于 False 状态时,Ingress 依然创建成功,kubectl get ingress 看起来一切正常,实际 443 用的是名为 Kubernetes Ingress Controller Fake Certificate 的自签占位证书。必须查 Certificate 资源才能发现:

kubectl get certificate -n shop
# NAME       READY   SECRET     AGE
# shop-tls   False   shop-tls   5m     ← READY 为 False 即签发失败
kubectl describe certificate shop-tls -n shop | tail -20   # 看 Events 里的 ACME 错误

常见后续错误是 ACME HTTP-01 校验不通(Waiting for HTTP-01 challenge propagation),根因往往又回到第 3 条的 host 不一致。五个根因常常连锁出现,按”Secret 类型 → namespace → SNI host → 证书链 → 签发状态”的顺序逐层排除,比直接怀疑 controller 快得多。

k8s ingress ssl证书从零到生效的 6 个操作步骤

问:从零开始,让 shop.example.com 走 HTTPS 最少要几步?答:六步,顺序不能乱。DNS 没生效,HTTP-01 自检必挂;IngressClass 名字差一个字符,Challenge 就永远停在 pending。下面每一步都给出可直接复制的命令,以及“怎么算成功”的判据。

  1. 准备域名解析。先拿到入口地址,再把 A 记录指过去(云上 LoadBalancer 场景也可用 CNAME),TTL 设 300 秒便于回滚。据 ingress-nginx 官方文档,请求打到 controller 但没有匹配规则时返回 404,所以 curl 看到 404 反而是“链路已通”的好消息。

    # 取入口地址:云上看 EXTERNAL-IP,自建裸机看节点 IP + NodePort
    kubectl get svc -n ingress-nginx ingress-nginx-controller -o wide
    
    # DNS 服务商处:shop.example.com A -> 上面的 IP,TTL=300
    dig +short shop.example.com        # 期望返回该 IP
    curl -I http://shop.example.com    # 返回 404 属正常:流量已到 controller,只是暂无匹配 Ingress
    
  2. 安装 ingress-nginx 1.11.x。chart 4.11.3 对应 controller v1.11.x,两者版本号不是一回事,别混用旧 chart。

    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm repo update
    helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx 
      --version 4.11.3 -n ingress-nginx --create-namespace
    kubectl get ingressclass   # 期望 NAME=nginx,CONTROLLER=k8s.io/ingress-nginx
    
  3. 安装 cert-manager v1.16.1。单文件清单包含 CRD、webhook 与 cainjector,必须三个 Pod 全 Running 才继续,否则后面创建 ClusterIssuer 会报 no matches for kind "ClusterIssuer"。

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml
    kubectl get pod -n cert-manager -w   # cert-manager / cainjector / webhook 三个 Pod 均 Running
    
  4. 创建 ClusterIssuer。生产环境 ACME server 填 https://acme-v02.api.letsencrypt.org/directory,调试期换成 https://acme-staging-v02.api.letsencrypt.org/directory(协议遵循 RFC 8555)。solvers.http01.ingress.ingressClassName 必须与步骤 2 里 IngressClass 的名字 逐字一致,否则 challenge 生成的临时 Ingress 不会被 controller 接管,HTTP-01 自检永远 404。

    # clusterissuer.yaml
    apiVersion: cert-manager.io/v1
    kind: ClusterIssuer
    metadata:
      name: letsencrypt-prod
    spec:
      acme:
        server: https://acme-v02.api.letsencrypt.org/directory  # 调试期改 staging 地址
        email: ops@example.com                                  # 到期提醒发这里
        privateKeySecretRef:
          name: letsencrypt-prod-account-key                    # ACME 账户私钥存放的 Secret
        solvers:
        - http01:
            ingress:
              ingressClassName: nginx                           # 必须等于 kubectl get ingressclass 的名字
    
    kubectl apply -f clusterissuer.yaml
    kubectl get clusterissuer          # READY 列应为 True,否则 describe 看 Events
    
  5. 创建带注解的 Ingress。注解 cert-manager.io/cluster-issuer 触发 ingress-shim 自动生成 Certificate CR;若你选择手写 Certificate,则其 spec.secretName 必须与 Ingress 里 spec.tls[].secretName 逐字相同,否则证书签出来了却不被使用。

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: shop
      namespace: prod
      annotations:
        cert-manager.io/cluster-issuer: letsencrypt-prod   # 触发自动签发
    spec:
      ingressClassName: nginx
      tls:
      - hosts: ["shop.example.com"]
        secretName: shop-example-com-tls                   # 签发结果写入此 Secret
      rules:
      - host: shop.example.com
        http:
          paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: shop-svc
                port:
                  number: 80
    
  6. 观察签发链路。按 Order → Challenge → Certificate 的顺序推进,据 cert-manager 文档,DNS 与网络正常时全程 30~90 秒。典型失败事件是 Waiting for HTTP-01 challenge propagation: wrong status code '404', expected '200',九成是 ingressClassName 不匹配或 DNS 尚未生效。

    kubectl get certificate,order,challenge -n prod -w   # 看到 Certificate READY=True 即可 Ctrl+C
    kubectl get secret shop-example-com-tls -n prod      # TYPE=kubernetes.io/tls,DATA=2(tls.crt + tls.key)
    kubectl describe challenge -n prod                   # 卡住时看 Events 定位
    
对比项 生产 acme-v02 预发 acme-staging-v02
浏览器/客户端信任 是 否,链由 Fake LE Root 签发
速率限制 每个注册域名每周 50 张证书,重复证书 5 张/周 限制宽松,适合反复调试
适用阶段 上线 联调、验证 YAML 正确性

补一句常被忽略的点:Secret 里 DATA=2 是硬指标,只有 1 项说明只写入了 tls.crt 而缺私钥,nginx 会报 cannot load certificate ... No such file or directory 或 PEM_read_bio_X509 错误——此时回到步骤 5 检查 Certificate 的 status.conditions,而不是去改 Ingress 注解。

k8s ingress ssl证书的配置与命令示例(ingress-nginx 1.11 + cert-manager 1.16)

Ingress 里 TLS 到底写在哪、写什么?证书本身不进 Ingress,Ingress 只声明“哪个域名用哪个 Secret”。K8s 1.28–1.31 通用的写法如下(networking.k8s.io/v1,pathType 自 1.19 起为必填):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: prod
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod   # 触发 cert-manager 自动签发
    nginx.ingress.kubernetes.io/ssl-redirect: "true"    # 默认即 true,此处显式写出便于 review
spec:
  ingressClassName: nginx
  tls:
  - hosts: ["shop.example.com"]
    secretName: shop-example-com-tls   # 必须与签发/上传的 Secret 同名、同 namespace
  rules:
  - host: shop.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: shop
            port:
              number: 80

让 cert-manager 1.16 自动签发要配什么?一个 ClusterIssuer 即可,HTTP-01 校验会由 cert-manager 自动创建临时 Ingress 完成(协议见 RFC 8555):

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory  # 测试先用 staging 避免触发速率限制
    privateKeySecretRef:
      name: le-prod-account-key   # ACME 账户私钥,集群级复用
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx

已有证书怎么手动塞进去?注意 --cert 传的是“叶证书 + 中间证书”拼接的 fullchain,只传叶证书会让部分客户端报 unable to get local issuer certificate:

# fullchain.pem = 服务器证书 + 中间 CA,顺序不能颠倒
kubectl create secret tls shop-example-com-tls 
  --cert=fullchain.pem --key=privkey.pem -n prod 
  --dry-run=client -o yaml | kubectl apply -f -

# 确认类型,必须输出 kubernetes.io/tls
kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.type}'

ingress-nginx 1.11 中几个高频 annotation 的默认值,务必记牢,都能在 Ingress 上逐条覆盖(据 ingress-nginx 官方 annotation 文档):

Annotation 默认值 说明
ssl-redirect "true" 只要 Ingress 含 tls 段就 301 到 https;设为 false 可保留明文入口
force-ssl-redirect "false" 对“未配 TLS 的 Ingress”也强制跳转,用于全局收口
ssl-protocols "TLSv1.2 TLSv1.3"(1.10 起) 老客户端兼容才加 TLSv1.1,会削弱安全性
proxy-ssl-verify "off" 回源不校验后端证书;开 on 需配 proxy-ssl-secret

怎么确认 controller 真的加载了新证书?直接看渲染后的 nginx.conf,比看 Secret 更可靠:

kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- 
  nginx -T 2>/dev/null | grep -A2 ssl_certificate
# 期望看到 /etc/ingress-controller/ssl/prod-shop-example-com-tls.pem
# 若仍是 default-fake-certificate.pem,说明 Secret 名/namespace 不匹配或 controller 未 reload

自签或内部 CA 怎么做双向 TLS?kubectl create secret tls 只能生成 tls.crt/tls.key 两个键,要带 ca.crt 必须手写 YAML 的三个 base64 字段(type: kubernetes.io/tls)。ingress-nginx 1.11 会把 ca.crt 一并下发给客户端;配合 nginx.ingress.kubernetes.io/auth-tls-verify-client: "on" 与 auth-tls-secret 即可校验客户端证书。密码套件可参考 Mozilla SSL Configuration Generator 的 intermediate 档位填入 ssl-ciphers,避免落到 DEFAULT 的弱套件。

手动 Secret、cert-manager、云托管:k8s ingress ssl证书三种来源怎么选

三种来源没有绝对优劣,选型的核心变量是域名数量、续期自动化的落地成本、以及出问题时你愿意在几个控制台之间跳转。下面这张表按 2025 年常见价格与限制整理,可直接对照团队现状做取舍。

方案 证书存放位置 续期方式 适合规模 关键限制
手动 kubectl create secret tls 自建 kubernetes.io/tls Secret 人工,90 天一次 域名 ≤5 个、内网或自签 易漏续期,无审计记录
cert-manager + Let’s Encrypt Certificate CR 自动生成 Secret 到期前自动,renewBefore 默认 2/3 时长 10~500 个域名 需公网可达做 HTTP-01,每注册域名每周 50 张
云厂商托管(阿里云 CAS、AWS ACM + CLB/NLB) 云侧证书,通过 LB 注解或监听器绑定 云平台自动 已使用云 LB 的集群 Ingress 层看不到 tls.crt,排障要转到云控制台
商业 CA 泛域名(DigiCert、Sectigo OV) 手动 Secret 或 cert-manager 外部签发 1 年有效期,人工续 对外品牌站、合规要求 约 1000~6000 元/年,签发需 1~3 个工作日

域名 20 个以内、团队还没有 CI/CD 流水线,手动 Secret 真的不能用吗?可以用,但必须补一条到期告警,否则”证书过期”会是你在凌晨被叫醒的最常见原因。据 RFC 5280,浏览器只校验 notAfter,一旦过期就是硬失败,没有灰度余地。

# 适用 kubectl ≥ 1.24;fullchain.pem 必须含完整链(服务器证书在前、中间证书在后),
# 顺序写反会让部分客户端报 unable to get local issuer certificate
kubectl create secret tls shop-example-tls 
  --cert=fullchain.pem --key=privkey.pem -n prod

# 校验实际写入 Secret 的到期时间(OpenSSL 1.1.1 / 3.x 通用)
kubectl get secret shop-example-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -subject -enddate
# 纯手动 Secret 场景:用 blackbox_exporter 探针指标兜底,阈值 1209600 秒 = 14 天
groups:
- name: tls-expiry
  rules:
  - alert: IngressTLSCertExpiringSoon
    expr: probe_ssl_earliest_cert_expiry - time() < 1209600
    for: 1h
    labels: {severity: warning}

cert-manager 的额外成本在哪?不在安装,而在 DNS-01 凭证与 RBAC。泛域名 *.example.com 无法用 HTTP-01 验证,必须走 dns01;据 cert-manager 官方文档,renewBefore 默认取证书时长的 2/3,90 天证书即在剩余 30 天时续期。建议单独建一个只具备 DNS 解析权限的 RAM 子账号或 Cloudflare Token,而不是复用主账号 AccessKey。

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata: {name: letsencrypt-dns01}
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef: {name: le-account-key}
    solvers:
    - dns01:
        cloudflare:
          apiTokenSecretRef: {name: cf-api-token, key: api-token}  # 仅 Zone:DNS:Edit
      selector:
        dnsZones: ["example.com"]

为什么云托管证书写不进 Ingress 的 tls.secretName?因为 AWS ACM 不导出私钥,Secret 里没有 tls.key 可放。这类集群按 AWS Load Balancer Controller v2.x 文档,在 Service 上用注解绑定,TLS 在 LB 侧终结:

service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:cn-north-1:123456789012:certificate/abcd
service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
# 副作用:nginx.ingress.kubernetes.io/ssl-redirect 不再生效,需应用侧或 LB 监听器规则做跳转

比较实用的混合策略:对外主域名交给 cert-manager 自动签发,内部服务用 cert-manager 的 CA Issuer 签发 90 天短证书(内部域名本就无法做公网 HTTP-01),两者共用同一套 Ingress 注解与发布流程,避免维护两套 k8s ingress ssl证书 的更新路径。给关键对外域名单独设 renewBefore: 720h(30 天)比默认值更保守,留足 Let’s Encrypt 速率限制触发时的回退时间——据 Let’s Encrypt 速率限制文档,每注册域名每周最多 50 张证书,反复失败的自动重试很容易撞上这条线。

k8s ingress ssl证书常见报错与排查:7 条真实错误信息对照

排查 k8s ingress ssl证书 问题有一条固定路径:先确认 Secret 是否存在,再确认 Secret 里的 PEM 是否合法,最后确认证书 SAN 是否覆盖当前域名。下面按报错原文逐条对照。

报错原文 根因 第一条排查命令
secret "shop-example-com-tls" not found 命名空间或名字不匹配 kubectl get secret -n prod | grep tls
Kubernetes Ingress Controller Fake Certificate controller 未取到有效 PEM kubectl describe ingress
x509: certificate is valid for a.example.com, not b.example.com SAN 不覆盖域名 openssl x509 -text
X509_check_private_key:key values mismatch 证书与私钥不配对 openssl modulus | md5
Waiting for HTTP-01 challenge propagation ... 404 challenge 路径被 rewrite kubectl describe challenge
too many failed authorizations recently Let’s Encrypt 账户级限流 切 staging 端点
x509: certificate has expired or is not yet valid 续期中断 openssl x509 -dates

1. Secret not found:先查命名空间,再查大小写。Ingress 的 spec.tls[].secretName 只在同一个命名空间内解析,跨命名空间引用不会生效,也绝不会回退到 default 命名空间。

# 列出 prod 下所有 TLS 类型 Secret,确认名字与大小写
kubectl get secret -n prod --field-selector type=kubernetes.io/tls
# 打印 Ingress 实际引用的 secretName
kubectl get ingress shop-web -n prod -o jsonpath='{.spec.tls[*].secretName}'
# 打印 cert-manager 实际写入的 secretName,逐字符比对
kubectl get certificate -n prod -o jsonpath='{range .items[*]}{.metadata.name}{"t"}{.spec.secretName}{"n"}{end}'

Ingress 的 tls.secretName 与 Certificate 的 spec.secretName 差一个字符(例如 -tls 写成 -ssl),443 端口就会静默无证书。

2. Fake Certificate:controller 没读到有效 PEM。NGINX Ingress Controller 在没有匹配证书时,会返回内置自签的 Kubernetes Ingress Controller Fake Certificate(可用 --default-ssl-certificate 覆盖)。此时 kubectl describe ingress 的事件里常出现 ingress does not contain a valid TLS certificate。直接验证 Secret 内容:

# 解码 tls.crt 并解析,若报 "unable to load certificate" 说明 Secret 内容本身是坏的
kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -subject -issuer -dates

注意 .data.tls.crt 里的 . 必须转义为 .,否则 jsonpath 会按层级解析而返回空串。

3. SAN 不匹配。现代浏览器只认 SAN,不看 CN。泛域名证书 *.example.com 只覆盖一级子域,a.b.example.com 不在其内(RFC 6125 亦明确通配符仅匹配一个标签)。

openssl x509 -in tls.crt -noout -text | grep -A1 'Subject Alternative Name'

4. key values mismatch。证书与私钥不配对时,NGINX 会打印 SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。用模数哈希比对,两个值必须完全一致:

openssl x509 -noout -modulus -in tls.crt | openssl md5
openssl rsa  -noout -modulus -in tls.key | openssl md5
# ECDSA 证书没有 modulus,改用公钥比对:
# openssl x509 -in tls.crt -noout -pubkey | openssl md5
# openssl pkey -in tls.key -pubout | openssl md5

5. HTTP-01 404。cert-manager 自检 GET http://域名/.well-known/acme-challenge/<token> 返回 404,常见原因是 Ingress 上加了 nginx.ingress.kubernetes.io/rewrite-target 把 challenge 路径改写掉了,或 solver 创建的临时 Ingress 使用了不存在的 ingressClassName。kubectl describe challenge -n prod 的 State 与 Reason 字段会直接指出卡在哪一步。

6. too many failed authorizations recently。据 Let’s Encrypt 速率限制文档,同一账户对同一主机名每小时最多 5 次验证失败,超限后需等待约 1 小时窗口。正确做法是先把 Issuer 的 server 改成 staging 端点(https://acme-staging-v02.api.letsencrypt.org/directory)调通链路,再切回生产,避免消耗生产配额。

7. 证书过期。先看日期,再看 Certificate 状态;notAfter 已过通常意味着续期早已失败:

kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -dates
kubectl describe certificate shop-example-com-tls -n prod   # 看 Status.Conditions 与 Events
kubectl get certificaterequest -n prod                      # 定位失败的 CR

Ready 为 False 且 Reason 为 DoesNotExist/Failed 时,续期链已断,需修复 Issuer 引用或 DNS 解析后手动删除待处理的 CertificateRequest 触发重签。

怎么确认 k8s ingress ssl证书真的生效了?6 条验证命令

Ingress 里写了 tls: 段不代表证书就生效了——Secret 没被挂载、nginx 没 reload、SNI 分流走错、中间证书缺失,每一环都可能静默失败。按下面 6 条命令从资源层往上逐层验证,哪一层先失败就停在哪一层排查。

  1. 资源层:Ingress 引用的 Secret 名与 Certificate 状态

    kubectl get ingress shop -n prod -o jsonpath='{.spec.tls[0].secretName}'; echo
    # 期望输出:shop-example-com-tls(须与 Certificate 生成的 Secret 同名、同 namespace)
    
    kubectl get certificate -n prod
    # NAME               READY   SECRET                 AGE   RENEWAL TIME
    # shop-example-com   True    shop-example-com-tls   9d    79d

    READY 必须为 True,且 AGE 与 RENEWAL TIME 两列要一起看。据 cert-manager 文档,未显式设置 renewBefore 时默认在证书有效期约 2/3 处续期,对 Let’s Encrypt 的 90 天证书即提前约 30 天。只看 AGE 会漏掉“续期已失败但旧证书尚未过期”的危险窗口。

  2. 握手层:证书主体、签发者与到期时间

    openssl s_client -connect shop.example.com:443 -servername shop.example.com -showcerts </dev/null 2>/dev/null 
      | openssl x509 -noout -subject -issuer -dates
    # subject=CN = shop.example.com
    # issuer=C = US, O = Let's Encrypt, CN = R11
    # notAfter=...(距今应大于 30 天)

    issuer 为 R10/R11 说明走的是 Let’s Encrypt 现行中间 CA(2024 年起替代 R3);若 issuer 显示 CN = Kubernetes Ingress Controller Fake Certificate,说明 Secret 根本没被加载,此时浏览器会直接报证书不受信任。

  3. 协议层:确认 TLSv1.0/1.1 已关闭

    echo | openssl s_client -connect shop.example.com:443 -servername shop.example.com -tls1_1 2>&1 
      | grep -E 'Protocol|alert'
    # 期望:alert protocol version,且不出现 Protocol : TLSv1.1

    据 Mozilla Server Side TLS 指南的 intermediate 配置,应只启用 TLSv1.2/1.3,这也符合 RFC 8996 对 TLSv1.0/1.1 的弃用要求(RFC 8996 于 2021 年 3 月将二者标记为 Historic)。

  4. HTTP 层:业务可达与强制跳转

    curl -sSI https://shop.example.com | head -1   # HTTP/2 200 或 301
    curl -sSI http://shop.example.com  | head -3   # 301,Location: https://shop.example.com/

    第二条验证 nginx.ingress.kubernetes.io/ssl-redirect(ingress-nginx 默认值为 true)确实生效,避免 HSTS 与明文入口并存。

  5. 链完整层:客户端能否验证到根

    openssl s_client -connect shop.example.com:443 -servername shop.example.com -verify_return_error </dev/null 2>&1 
      | grep 'Verify return code'
    # 期望:Verify return code: 0 (ok)
    返回码 含义 常见原因
    0 (ok) 链完整、域名匹配 —
    20 (unable to get local issuer certificate) 缺中间证书 Secret 的 tls.crt 只放了叶子证书
    21 (unable to verify the first certificate) 服务端未下发中间证书 未拼接 intermediate 成 fullchain
    10 (certificate has expired) 证书已过期 自动续期失败
    62 (hostname mismatch) SAN 不含该域名 证书与 Ingress host 不一致

    出现 20/21 时先查 Secret 内容而非 Ingress:kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.data.tls.crt}' | base64 -d | grep -c 'BEGIN CERTIFICATE',输出 2 表示叶子+中间证书齐全,1 表示缺中间证书。

  6. 配置层:nginx 是否真的加载并 reload

    # 统计已加载证书数量,应等于所有 Ingress 的 spec.tls 条目总数
    kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- nginx -T 2>/dev/null | grep -c 'ssl_certificate '
    
    # 确认控制器已热加载(无输出说明没感知到变更)
    kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --since=10m | grep -i 'reload'

    数量对不上或没有 reload 日志,最常见原因是 Secret 与 Ingress 不在同一 namespace——Ingress 的 tls.secretName 只能引用同 namespace 内的 Secret,跨 namespace 引用会被静默忽略。

k8s ingress ssl证书轮换:Secret 更新后多久生效、怎么强制续期

Secret 更新后多久生效?ingress-nginx 通过 fsnotify 监听 /etc/ingress-controller/ssl 目录,Secret 的 data.tls.crt/tls.key 变化后,通常 5~30 秒内触发 reload,不需要执行 kubectl rollout restart deploy/ingress-nginx-controller。若 60 秒后仍返回旧证书,再查 controller 日志中的 reload 记录:

# 查看线上实际返回的 notAfter 与 Subject
openssl s_client -connect shop.example.com:443 -servername shop.example.com /dev/null 
  | openssl x509 -noout -dates -subject

# 查看 ingress-nginx 最近 5 分钟的 reload/ssl 日志
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --since=5m | grep -Ei 'reload|ssl'

手动轮换 k8s ingress ssl证书时,推荐声明式 apply,避免先 delete Secret 造成 443 短暂中断。apply 只更新 data 字段,Secret 名称不变,Ingress 无需改动:

# 用新证书原地更新 Secret;--dry-run=client 只生成 YAML,不落盘
kubectl create secret tls shop-example-com-tls 
  --cert=fullchain.pem --key=privkey.pem -n prod 
  --dry-run=client -o yaml | kubectl apply -f -

# 校验 Secret 内证书有效期
kubectl get secret shop-example-com-tls -n prod 
  -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -dates

cert-manager 默认 renewBefore 为证书总时长的 2/3,即 90 天证书在剩余 30 天时自动续期;可在 Certificate 上显式提前,最小粒度到分钟:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: shop-example-com
  namespace: prod
spec:
  secretName: shop-example-com-tls
  renewBefore: 360h          # 15 天;默认约为总时长 2/3,90 天证书即 720h
  dnsNames:
  - shop.example.com
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

需要立即换发时,用 cert-manager v1.16 配套 CLI:cmctl renew shop-example-com-tls -n prod,随后 cmctl status certificate shop-example-com-tls -n prod 观察 Issuing 状态;也可删除关联 Order 触发重建:kubectl delete order -n prod -l cert-manager.io/certificate-name=shop-example-com。据 cert-manager 文档,自动续期还带随机抖动,避免集中请求 ACME。

轮换方式 典型命令 生效时间 风险
手动 apply Secret kubectl create secret tls ... --dry-run=client -o yaml | kubectl apply -f - 通常 5~30 秒 低,推荐
删除后重建 Secret kubectl delete secret ... 取决于重建速度 可能 443 短暂中断
cert-manager 强制续期 cmctl renew ... 数秒至数分钟,取决于 ACME 低

监控建议采集 certmanager_certificate_expiration_timestamp_seconds 与 certmanager_certificate_ready_status,告警阈值设剩余 14 天:certmanager_certificate_expiration_timestamp_seconds - time() < 14*24*3600。据 Let’s Encrypt 公告,其 OCSP 响应服务自 2025 年起逐步停用并改用 CRL,依赖 OCSP stapling 做吊销检查的链路需同步调整。

多域名与泛域名:k8s ingress ssl证书的 SNI 规划与 Gateway API 差异

一个 Ingress 可以写多个 spec.tls 条目,每条带自己的 hosts 与 secretName,ingress-nginx 在 TLS 握手中按客户端 SNI 匹配并下发对应证书。要验证实际下发了哪张证书,不要靠猜,直接用 SNI 探测:

# 适用 ingress-nginx v1.x(Helm chart 4.x),OpenSSL 1.1.1+
# -servername 模拟客户端 SNI,-showcerts 打印完整链
openssl s_client -connect ingress.example.com:443 
  -servername api.example.com 
  -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -ext subjectAltName

一个坑:同一个 host 若同时出现在两个 tls 条目里,以 YAML 中靠前的一条为准。ingress-nginx 按顺序构建 SNI 映射,后者被静默忽略,kubectl apply 不报任何 warning,只有日志里能看到。排查时先看顺序,再看 Secret 是否存在。

泛域名 *.example.com 只能走 DNS-01,据 Let’s Encrypt 文档,HTTP-01 不支持通配符,因为校验必须由 CA 直接发起,无法验证“所有子域”的归属。cert-manager 侧要显式配 solvers.dns01 与服务商 API 凭证(cloudflare、alidns、route53 等):

# cert-manager v1.14+ 验证通过;ClusterIssuer 片段
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns01
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: le-account-key
    solvers:
    - dns01:
        cloudflare:
          apiTokenSecretRef:          # 凭证 Secret 需与 ClusterIssuer 同 ns 或引用
            name: cloudflare-api-token
            key: api-token
      selector:
        dnsZones: ["example.com"]     # 限定生效区域,避免误签其他域

关键点:*.example.com 不覆盖 example.com 本身,必须在 dnsNames 里额外加一条。据 RFC 6125 的通配符匹配规则,通配符只匹配一级标签,*.example.com 也不匹配 a.b.example.com。

Let’s Encrypt 单张证书上限 100 个 SAN(见其速率限制文档)。TLS 握手时整张证书走 Certificate 消息,每个 SAN 约 20~40 字节,域名多会逼近握手包上限并加重首包延迟。超过 30 个域名建议按业务域拆成多张证书,分别挂到不同 Ingress。

维度 Ingress spec.tls[].secretName Gateway API listener.tls.certificateRefs
跨命名空间引用 Secret 不支持(v1 规范至今无此字段) 支持,需配套 ReferenceGrant
多证书(同一 listener) 不支持,一 host 一 Secret 支持 certificateRefs 列表
SNI 匹配位置 controller 内部映射 由 Listener hostname 显式声明
未匹配请求默认证书 controller 启动参数 --default-ssl-certificate 由默认 listener / 实现决定

未匹配任何 SNI 的请求(如客户端用裸 IP 直连、或 SNI 被剥离)会落到默认证书;不指定时暴露的是 ingress-nginx 的 Fake Certificate,部分客户端会直接报 NET::ERR_CERT_AUTHORITY_INVALID。用 controller 启动参数覆盖:

# 适用 ingress-nginx v1.9+;Helm chart 中对应 controller.extraArgs
helm upgrade ingress-nginx ingress-nginx/ingress-nginx 
  --namespace ingress-nginx --reuse-values 
  --set-json 'controller.extraArgs.default-ssl-certificate="ingress-nginx/default-tls"'

默认值为空(即使用内置 Fake Certificate)。同一 Ingress 里多域名规划时,把每个 host 的 Secret 单独命名(如 api-example-tls、wild-example-tls),比塞一张巨型证书更易轮换——这也是后续做 k8s ingress ssl证书 轮换与告警的基础。若已在评估 Gateway API,跨命名空间引用 Secret 是迁移中最直接的收益点:Secret 集中在 infra 命名空间,业务 Ingress 不再需要复制证书。

必须与 Ingress 同命名空间。跨命名空间引用在 kubectl apply 阶段不会报错,但 ingress-nginx 解析不到 PEM,443 会回落到 Kubernetes Ingress Controller Fake Certificate,controller 日志出现 secret not found。多命名空间共用一张证书时,在每个 namespace 各建一份同名 Secret,或改用 Gateway API 的 certificateRefs + ReferenceGrant。

域名超过 10 个、有稳定 CI/CD 流程时选 cert-manager,90 天证书在剩余 30 天自动续期,Secret 原地更新后 ingress-nginx 5~30 秒热加载,几乎零运维。域名少于 5 个或必须用商业 OV/EV 证书时手动 Secret 更直接,但要配到期告警。两者可以共存:主域名走 cert-manager,合规站点用手动 Secret 挂商业证书。

不需要。ingress-nginx 1.11 监听 /etc/ingress-controller/ssl 目录变化,Secret 更新后通常 5~30 秒内自动 reload。若 60 秒后 openssl s_client 仍显示旧 notAfter,检查 controller 日志中的 reload 记录,以及是否误改了 Secret 名称导致 Ingress 引用的还是旧对象。

先执行 kubectl get secret xxx-tls -n 确认存在,再用 kubectl get secret xxx-tls -n prod -o jsonpath='{.type}' 确认类型是 kubernetes.io/tls,最后用 base64 -d 解出 tls.crt 并 openssl x509 -noout -subject 验证内容合法。三步都通过仍报错,就看 kubectl describe ingress 的 Events 与 controller 日志里的 obtaining pem 相关行。

可以,spec.tls 是数组,每个条目包含独立的 hosts 与 secretName,controller 按 SNI 选择证书。泛域名 *.example.com 必须用 DNS-01 验证,cert-manager 需配置 dns01 solver 和服务商 API 凭证;同时记得把裸域 example.com 单独加进 dnsNames,否则主域访问会证书不匹配。

ingress-nginx 从 1.10 起 ssl-protocols 默认值为 "TLSv1.2 TLSv1.3",基于 OpenSSL 3.x 构建的镜像默认启用 TLS 1.3。需要收紧时在 Ingress 上加注解 nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3",需要兼容老旧客户端才临时加回 TLSv1.1,但不建议长期保留,RFC 8996 已将其标记为废弃。

cert-manager 暴露 certmanager_certificate_expiration_timestamp_seconds 指标,用 Prometheus 规则 (certmanager_certificate_expiration_timestamp_seconds – time()) < 14*24*3600 触发告警即可。手动 Secret 场景可用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标,或在 CronJob 里跑 openssl s_client 解析 notAfter 后推送告警。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。