跳到主要内容
安装配置教程

k8s ingress ssl证书安装全流程:Secret 创建、Ingress TLS 配置与报错排查

k8s ingress ssl证书安装 — k8s ingress ssl证书安装全流程:Secret 创建、Ingress TLS 配置与报错排查
核心结论

k8s ingress ssl证书安装本质只有两步:把 fullchain 证书与私钥放进与 Ingress 同 namespace 的 kubernetes.io/tls Secret,再在 spec.tls[].secretName 引用它,Ingress 本身不解析证书文件。 secretName 拼错或跨 namespace 引用时不会报硬错误,ingress-nginx 会回落内置自签证书,浏览器显示签发者为 kubernetes ingress controller fake certificate。 证书必须是 PEM 且含中间 CA:cat cert.crt chain.crt > fullchain.pem,否则 Android 7+ 与 Java 客户端报 unable to get local issuer certificate。 Let's Encrypt 证书有效期 90 天,建议用 cert-manager v1.14+ 的 Certificate CRD,renewBefore 设 720h,避免每 3 个月手工执行一次 kubectl create secret tls。 验证命令:openssl s_client -connect 1.2.3.4:443 -servername example.com -showcerts /dev/null | openssl x509 -noout -issuer -dates,看到 Verify return code: 0 (ok) 才算 k8s ingress ssl证书安装成功。

k8s ingress ssl证书安装为什么经常“装完不生效”:三个断点与根本原因

很多人执行完 kubectl create secret tls、在 Ingress 里加了两行 tls:,浏览器却依然报证书错误。原因几乎都能归到下面三个断点,外加两个容易被忽略的”静默覆盖”机制。

断点一:Secret 和 Ingress 不在同一个 namespace

Ingress 的 spec.tls[].secretName 只在同 namespace 内解析。据 Kubernetes 官方 API 参考,IngressTLS.secretName 的语义就是”同一 namespace 中的 Secret 名称”,至今没有跨 namespace 引用字段;跨 namespace 的引用授权直到 Gateway API 才通过 ReferenceGrant 解决。所以 prod 的 Ingress 引用 dev 的 Secret 会静默失败——kubectl describe ingress 的 Events 里通常只有一行:

# 定位:Secret 与 Ingress 的 namespace 必须一致
kubectl get ingress my-app -n prod -o jsonpath='{.spec.tls[0].secretName}{"n"}'
kubectl get secret my-app-tls -n prod          # 若报 NotFound,就是断点一
# 正确做法:在目标 namespace 重建同名 Secret(或用 external-secrets 等同步过去)
kubectl create secret tls my-app-tls -n prod --cert=fullchain.pem --key=privkey.pem
# describe 中典型事件:secret "my-app-tls" not found

断点二:证书不是合法 PEM

kubectl create secret tls 只做 PEM 解析,不做证书链完整性和私钥匹配校验。上传 .pfx/.p12/.der 会直接失败:

error: failed to load key pair: tls: failed to find any PEM data in certificate input

先转换再上传(OpenSSL 1.1.1 / 3.x 均适用):

# pfx → 证书(-clcerts 只导叶子证书,-nokeys 不导私钥)
openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -nodes -out privkey.pem
# 上传前自检:Subject 与 SAN 是否正确、私钥是否匹配
openssl x509 -in cert.pem -noout -subject -ext subjectAltName
openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem | openssl md5   # 两行 md5 必须一致

断点三:host 与证书 SAN 不逐字匹配

spec.rules[].host 必须与 SAN 里的 DNS 名逐字相同(含 www. 前缀)。通配符 *.example.com 按 RFC 6125 只覆盖一级子域,a.b.example.com 不在覆盖范围内,浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID。可在本地验证:

openssl x509 -in cert.pem -noout -checkhost www.example.com   # 输出 Hostname ... does match/does NOT match

为什么”装了却没生效”:默认证书与 API 版本两个静默陷阱

ingress-nginx 有启动参数 --default-ssl-certificate,默认值为空。当 SNI 未匹配到任何 Ingress 的 tls 段时,控制器回落到内置自签证书,CN 为 kubernetes ingress controller fake certificate、有效期 3650 天——这正是”配置写了但浏览器还是报假证书”的高频原因。检查方式:

kubectl -n ingress-nginx get deploy ingress-nginx-controller 
  -o jsonpath='{.spec.template.spec.containers[0].args}' | tr ',' 'n' | grep default-ssl

另一个陷阱是 API 版本:networking.k8s.io/v1 自 Kubernetes 1.19 GA,1.22 起移除 extensions/v1beta1/v1beta1。在 1.22+ 集群 apply 旧清单会直接失败,tls 段自然不会下发到 nginx.conf:

error: resource mapping not found ... no matches for kind "Ingress" in version "extensions/v1beta1"
断点 典型现象 一条命令定位
Secret 跨 namespace Events: secret “xxx-tls” not found kubectl get secret xxx-tls -n <ingress 所在 ns>
非 PEM 格式 failed to find any PEM data openssl x509 -in cert.pem -noout -subject
host 与 SAN 不符 NET::ERR_CERT_COMMON_NAME_INVALID openssl x509 -in cert.pem -noout -checkhost <host>
回落到默认自签证书 CN = fake certificate,3650 天 检查 --default-ssl-certificate 与 SNI 匹配
API 版本过旧 no matches for kind “Ingress” kubectl api-resources | grep ingress

k8s ingress ssl证书安装的完整实操步骤(8 步,可直接照做)

在开始之前先说清楚一个前提:k8s ingress ssl证书安装能否一次成功,八成取决于前面两步的“体检”,而不是 YAML 写得多漂亮。据 Kubernetes 官方文档,networking.k8s.io/v1 自 1.19 起 GA,extensions/v1beta1 已在 1.22 移除;如果你在旧清单上照抄,报错会非常隐蔽。

步骤 1:确认集群版本与控制器版本。先看 Server Version(建议 1.24+,1.24 起 ServiceAccount 不再自动生成长期 Token,很多老清单会连带出问题),再反查 ingress-nginx 控制器镜像版本。

# Server Version 建议 ≥ 1.24
kubectl version --short
# 输出示例:Server Version: v1.28.6
# 注:kubectl 1.28 起 --short 被标记弃用,若提示 unknown flag,直接执行 kubectl version 看 Server Version 一行

# 查看控制器镜像,命名空间按实际安装调整(官方清单默认 ingress-nginx)
kubectl -n ingress-nginx get deploy ingress-nginx-controller 
  -o jsonpath='{.spec.template.spec.containers[0].image}{"n"}'
# 典型输出:registry.k8s.io/ingress-nginx/controller:v1.10.1

镜像地址能反推清单新旧:k8s.gcr.io/ingress-nginx/controller 是 v1.6 及更早的老仓库,v1.7 之后官方迁移到 registry.k8s.io(据 ingress-nginx 官方发布说明)。仓库还是旧的,说明你的控制器已经落后好几个小版本。

步骤 2:确认 Ingress API 版本存在。

kubectl api-resources | grep -i ingress
# 期望包含这一行(SHORTNAMES 列可能为空):
# ingresses   ing   networking.k8s.io/v1   true   Ingress

如果只看到 networking.k8s.io/v1beta1 或 extensions/v1beta1,本节后面的 YAML 一律不适用,请先升级集群。

步骤 3:整理 fullchain 与无口令私钥。证书顺序必须是“站点证书在前、中间证书在后”,反了会出现 curl: (60) unable to get local issuer certificate。私钥若带 passphrase,kubelet 无法交互输入,Secret 里必须是明文私钥。

# 拼接完整链:站点证书 + 中间证书
cat example.com.crt intermediate.crt > fullchain.pem

# 私钥去口令(OpenSSL 3.x 推荐 pkey,会提示输入原口令,输出为不加密私钥)
openssl pkey -in example.com.key -out privkey.pem
# 旧写法(OpenSSL 1.1.1 亦可):openssl rsa -in example.com.key -out privkey.pem

chmod 600 fullchain.pem privkey.pem   # 避免私钥进镜像层或 Git 历史
文件 内容 对应参数 常见错误
fullchain.pem 站点证书 + 中间证书 --cert 只放站点证书 → 链不完整
privkey.pem 无口令私钥(RSA/ECDSA) --key 带 passphrase → 加载失败
example.com.crt 仅站点证书 不直接用 浏览器报“证书链不完整”

步骤 4:校验私钥与证书是否配对。这一步能省掉后面 90% 的排查时间。

openssl x509 -noout -pubkey -in fullchain.pem | openssl sha256
openssl pkey -pubout -in privkey.pem | openssl sha256
# 两行 sha256 必须完全一致

不一致时,下一步会直接报:error: tls: private key does not match public key。顺便可用 openssl pkey -in privkey.pem -noout -check 确认私钥本身没损坏。

步骤 5:创建 Secret。这就是 k8s ingress ssl证书安装 里最容易被 GitOps 卡住的一环。

kubectl create secret tls example-tls --cert=fullchain.pem --key=privkey.pem -n prod

# 走 GitOps 时先导出 YAML 再提交(注意 base64 私钥会进仓库,建议配 SealedSecret/External Secrets)
kubectl create secret tls example-tls --cert=fullchain.pem --key=privkey.pem -n prod 
  --dry-run=client -o yaml > secret.yaml

据 Kubernetes 文档,单个 Secret/ConfigMap 对象总大小上限为 1MiB;RSA 4096 + 完整中间链通常在 4–6KB,容量上不必担心。

步骤 6:在 Ingress 中写入 tls 段。关键约束:spec.tls[0].hosts 与 spec.rules[].host 必须逐字符一致(含是否带 www.),secretName 指向刚建的 example-tls。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
  namespace: prod
  annotations:
    # ingress-nginx 中该项默认即为 "true",此处显式声明只为可读性
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx        # 1.18+ 用它替代 kubernetes.io/ingress.class 注解
  tls:
    - hosts:
        - example.com            # 必须与下方 rules[].host 完全一致
      secretName: example-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix     # v1 中必填,漏写报 spec.rules[0].http.paths[0].pathType: Required value
            backend:
              service:
                name: web
                port:
                  number: 80

步骤 7:应用清单。

kubectl apply -f ingress.yaml
# 期望输出:ingress.networking.k8s.io/example created

步骤 8:基础核对。先看 describe 的 TLS 段,再用证书本身反查有效期,最后用 --resolve 绕过 DNS 直接验证 SNI 握手(SNI 定义见 RFC 6066)。

kubectl describe ingress example -n prod
# 期望看到:
# TLS:
#   example-tls terminates example.com

kubectl get secret example-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -subject -dates
# 确认 subject 与 notAfter 符合预期

curl -vI https://example.com --resolve example.com:443:<ingress-ip> 2>&1 | grep -E 'SSL|subject|issuer'

若 describe 里 TLS 段为空,先查 kubectl get ingress example -n prod -o yaml 确认 spec.tls 真的被提交;若 TLS 段正常但浏览器报错,问题通常已转移到控制器日志与证书链本身,属于下一节的排查范围。

配置与命令示例:Secret、Ingress、cert-manager 三份可套用清单(含版本与参数)

只想快速套用,最少要写几份 YAML?三份:一份 kubernetes.io/tls 类型的 Secret(或交给 cert-manager 自动生成)、一份 networking.k8s.io/v1 的 Ingress、以及一份 cert-manager 的 Issuer/Certificate(如果走自动签发)。下面三份清单可直接改域名套用。

第一份是 Secret。type 必须是 kubernetes.io/tls,data 下的键名固定为 tls.crt 与 tls.key,值均为 base64。注意 tls.crt 要放 fullchain(站点证书 + 中间证书,至少两段 -----BEGIN CERTIFICATE-----),否则部分客户端会报 unable to get local issuer certificate。

# 适用:所有 Kubernetes 1.9+ 版本;命名空间按需替换
apiVersion: v1
kind: Secret
metadata:
  name: example-tls
  namespace: prod
type: kubernetes.io/tls
data:
  # fullchain.pem 的 base64:必须含 2 段及以上 BEGIN CERTIFICATE
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
  # 私钥的 base64:PEM 格式且不能带 passphrase,否则 ingress-nginx 加载失败
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...

---
# 更省事的写法:直接用文件生成,避免手工 base64
# kubectl create secret tls example-tls -n prod --cert=fullchain.pem --key=tls.key --dry-run=client -o yaml

用 stringData 写明文确实可以,apiserver 会自动编码进 data,但明文会残留在 kubectl.kubernetes.io/last-applied-configuration 注解里,任何有 get secret 权限的人都能读回——生产环境建议始终用 data 或 kubectl create secret tls。

第二份是 Ingress。据 ingress-nginx 文档,proxy-body-size 默认值仅为 1m,上传稍大的文件就会返回 413 Request Entity Too Large;ssl-protocols 在较新版本默认已是 TLSv1.2 TLSv1.3,显式写出便于审计。

# 适用:Kubernetes 1.19+(networking.k8s.io/v1 GA)、ingress-nginx v1.9+
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: prod
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "20m"                 # 默认 1m
    nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"      # 对齐 Mozilla intermediate
    cert-manager.io/cluster-issuer: letsencrypt-prod                  # 触发自动签发/续期
spec:
  ingressClassName: nginx
  tls:
    - hosts: ["example.com"]
      secretName: example-tls        # spec.tls 是数组,可写多组 hosts+secretName 挂多张证书
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

第三份是 cert-manager(v1.14+,CRD 为 cert-manager.io/v1)。duration 默认 2160h(90 天,也是 Let’s Encrypt 的上限),renewBefore 默认到期前 720h 续期。据 Let’s Encrypt 文档,ACME 目录必须用 acme-v02,v1 端点已于 2021 年下线。

apiVersion: cert-manager.io/v1          # 需 cert-manager v1.14 及以上
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:
            ingressClassName: nginx    # v1.14 用 ingressClassName;更早版本字段名为 class
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-tls
  namespace: prod
spec:
  secretName: example-tls
  duration: 2160h        # 90 天
  renewBefore: 720h      # 提前 30 天续期
  dnsNames:
    - example.com
    - "*.example.com"
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

仅在测试环境用自签证书时,注意 -addext 需要 OpenSSL 1.1.1 及以上;1.0.2 需改用 -extfile:

# OpenSSL 1.1.1+;1.0.2 请改用 -extfile <(printf "subjectAltName=DNS:example.com,DNS:*.example.com")
openssl req -x509 -newkey rsa:2048 -nodes -keyout tls.key -out tls.crt -days 365 
  -subj "/CN=example.com" 
  -addext "subjectAltName=DNS:example.com,DNS:*.example.com"

kubectl create secret tls example-tls -n prod --cert=tls.crt --key=tls.key

怎么确认装进去的证书是对的?解出 Secret 里的证书直接看主题、签发者与有效期:

kubectl get secret example-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -subject -issuer -dates
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R3   (2024 年后新签发多为 E5/E6/R10/R11,以实际为准)
# notBefore=Mar 14 08:00:00 2025 GMT
# notAfter=Jun 12 08:00:00 2025 GMT

控制器侧还能在 ConfigMap 里统一覆盖:ssl-ciphers(默认对齐 Mozilla intermediate)、ssl-protocols、ssl-session-cache(默认 shared:SSL:10m)。若集群前面还有云 SLB 的 TCP 四层监听,TLS 仍在 Ingress 层终止,不要在 LB 上再上传同一张证书,否则会形成两层 TLS 并引发 SNI 错配。

证书来源 有效期/续期 适用场景 主要风险
手工 Secret(kubernetes.io/tls) 由 CA 决定,需人工轮换 已有商业证书、内网域名 忘记续期导致 certificate has expired
cert-manager + Let’s Encrypt 2160h,提前 720h 自动续 公网可解析域名 http01 需 80 端口可达;有速率限制
openssl 自签 -days 指定,如 365 仅 staging/联调 浏览器报 NET::ERR_CERT_AUTHORITY_INVALID

k8s ingress ssl证书安装的 5 种方案对比与选型建议

问:k8s ingress ssl证书安装到底有几种做法,我该选哪一种?

答:主流是五种,差别不在”能不能用”,而在私钥存放位置和续期由谁负责。先看对比表,再按三个问题做决策。

方案 证书来源 / 续期方式 典型有效期 典型失败表现 适用规模
A 手动 Secret(kubectl create secret tls) 商业 CA 或自签,人工续期 365 天 忘记更新后 notAfter 过期,浏览器 NET::ERR_CERT_DATE_INVALID <5 张证书、变更走审批的小集群
B cert-manager + Let’s Encrypt ACME(RFC 8555)自动签发与续期 90 天,提前 1/3 续期 ACME challenge 长时间 pending 域名多、要求自动化的生产集群
C 云厂商 LB 托管证书 控制台上传,云平台推送续期 随购买周期 监听器未绑定证书、443 未放行 私钥不允许进集群的合规场景
D ingress-nginx 默认证书 一张泛域名兜底 自定 SNI 未命中时回落到 fake 证书,NET::ERR_CERT_AUTHORITY_INVALID 内部测试域名、兜底
E Istio Gateway SDS Secret 或 istiod 下发 自定 Secret 命名空间不对,网关起不来 已上 Service Mesh、需 mTLS

方案 A 的最小完整命令(适用于 kubectl 1.20+):

# 1) 创建 tls 类型 Secret;--cert 必须是包含中间证书的 fullchain,顺序不能反
kubectl create secret tls shop-tls 
  --cert=fullchain.pem 
  --key=privkey.pem 
  -n prod

# 2) 核对有效期:notAfter 即到期时间(定义见 RFC 5280)
kubectl get secret shop-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -subject -dates

方案 B 的核心是 Certificate 资源。据 cert-manager 官方文档,renewBefore 不填时默认为证书有效期的 1/3,90 天证书即约 720h:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: shop-tls
  namespace: prod
spec:
  secretName: shop-tls          # cert-manager 自动写入同名 Secret
  duration: 2160h               # 90 天
  renewBefore: 720h             # 提前 30 天续期
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - shop.example.com

challenge 卡住的常见原文是 Waiting for HTTP-01 challenge propagation: failed to perform self check GET request,多半是 Service 未暴露 /.well-known/acme-challenge 或 80 端口被安全组拦截。

方案 D 只需给 ingress-nginx Controller 加一个启动参数(默认值为空,即不启用):

# ingress-nginx v1.x,写在 Controller Deployment 的 args 里
- --default-ssl-certificate=ingress-nginx/fallback-tls

方案 E 在 Istio 1.20+ 的 Gateway 中通过 SDS 引用 Secret,注意 Secret 必须与网关同一命名空间:

servers:
- port: {number: 443, name: https, protocol: HTTPS}
  tls:
    mode: SIMPLE
    credentialName: shop-tls   # 与 Gateway 同命名空间
  hosts: ["shop.example.com"]

选型判断一:域名数量与续期频率。3 个域名以内、每年集中更换一次,手动 Secret 的运维成本可接受;超过 10 个域名或含大量二级子域,cert-manager 的自动化收益明显,单集群每年可省 20–40 次人工操作。

选型判断二:私钥能否出集群。金融与等保场景常要求私钥不落地到业务集群,此时优先方案 C,把 TLS 终止放在云 LB,Ingress 只处理 HTTP 并透传 X-Forwarded-Proto。

选型判断三:是否需要 OCSP Stapling 与 HTTP/2。ingress-nginx v1.x 支持 OCSP Stapling(前提是证书链完整,可参考 Mozilla Server Side TLS 的链配置建议),且默认开启 HTTP/2;云 LB 的 OCSP 支持依厂商而定,采购前需确认。

成本区间参考:Let’s Encrypt 免费;DV 单域名商业证书约 100–600 元/年,OV 约 800–3000 元/年,通配符 OV 常见 3000–8000 元/年;cert-manager 本身免费,但需要额外的监控与告警投入(例如对 certmanager_certificate_expiration_timestamp_seconds 做 21 天告警)。

如果你的集群同时存在对外主域名和内部测试域名,实践中常见的是 B + D 组合:主域名走 cert-manager 自动续期,内部域名交给 --default-ssl-certificate 兜底,既避免 SNI 未命中时的证书告警,又不用为测试环境单独采购证书。

k8s ingress ssl证书安装常见报错与排查路径(附真实报错信息)

把报错先分类,排查能省一半时间。k8s ingress ssl证书安装 的失败几乎都落在下面六类,先用一条命令定位再动手改:

现象 / 报错原文 根因 一条命令定位
unable to get local issuer certificate / x509: certificate signed by unknown authority 证书链缺中间 CA openssl s_client -showcerts 数证书条数
tls: private key does not match public key 私钥与证书不配对 modulus / 公钥指纹比对
NET::ERR_CERT_COMMON_NAME_INVALID host 不在 SAN 里 openssl x509 -text 看 SAN
显示 kubernetes ingress controller fake certificate secretName 拼错或 namespace 不一致 kubectl describe ingress 看 Events
Order invalid / Certificate is not valid for the requested domain HTTP-01 挑战路径不可达 kubectl describe challenge
SSL_do_handshake() failed (SSL: error:0A00018A:SSL routines::dh key too small) DH 参数低于 2048 位 换 ECDSA 证书或显式指定 dh-param

为什么浏览器/客户端说“证书签发者未知”?因为 Secret 里只放了叶证书,没带中间 CA。据 Let’s Encrypt 文档,fullchain.pem 必须是“叶证书在前、中间证书在后”的拼接,顺序颠倒同样握手失败。先验证服务端实际下发的条数,返回 1 就是缺链:

# 数服务端下发的证书条数;1 = 只有叶证书,缺中间 CA,应为 2 或以上
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -c "BEGIN CERTIFICATE"

# 修复:把 intermediate.crt 追加到 fullchain.pem 末尾,再重建 Secret
cat fullchain.pem intermediate.crt > fullchain-new.pem
kubectl create secret tls example-tls -n prod 
  --cert=fullchain-new.pem --key=privkey.pem 
  --dry-run=client -o yaml | kubectl apply -f -
# 说明:type 固定为 kubernetes.io/tls,--dry-run=client 便于幂等更新

报 tls: private key does not match public key 怎么办?多半是 CSR 重签后旧私钥没换。RSA 证书比对 modulus 的 MD5;ECDSA 证书没有 modulus 字段,必须改比公钥指纹,这是最容易踩空的一步:

# RSA 证书
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem    | openssl md5
# 两值不同即确认不配对

# ECDSA 证书(P-256 等)用公钥指纹比对
openssl x509 -in fullchain.pem -noout -pubkey | openssl sha256
openssl pkey -in privkey.pem -pubout          | openssl sha256

NET::ERR_CERT_COMMON_NAME_INVALID 一定是证书错了吗?不是,是 Ingress 里写的 host 没落在证书 SAN 列表中。CA/Browser Forum 基线要求自 2017 年起 CN 被忽略、只认 SAN,所以别去看 Subject 的 CN:

# macOS 上 base64 -d 换成 base64 -D 或 base64 --decode
kubectl get secret example-tls -n prod -o jsonpath='{.data.tls.crt}' | base64 -d 
  | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

为什么浏览器显示的是 fake certificate?说明 Ingress 根本没引用到你的 Secret,nginx-ingress 回落到内置自签证书。名字拼错、Secret 建在 default 而 Ingress 在 prod,都会这样:

kubectl describe ingress example -n prod | sed -n '/Events/,$p'
# 典型输出:Error: secret "example-tls" not found
kubectl get secret -n prod | grep tls   # 核对名称与 namespace

cert-manager 的 Order 卡在 invalid 呢?按 ingress-nginx 文档,HTTP-01 需要 /.well-known/acme-challenge/ 走明文 80;若 Ingress 开了 nginx.ingress.kubernetes.io/ssl-redirect: "true",挑战会被 301 到 443 而失败,需为该路径单独放行 HTTP,同时确认 ingressClassName 与 controller 一致:

kubectl get certificate,order,challenge -n prod
kubectl describe challenge -n prod <challenge-name> | tail -20

dh key too small 从哪来?旧环境迁移的 DH 参数常为 1024 位,OpenSSL 3.x(RFC 7919 推荐的 FFDHE 为 2048 位起)直接拒绝。最省事的做法是换 ECDSA P-256 证书;必须用 RSA 时,在 ConfigMap 中显式指定 ssl-dh-param 指向 ≥2048 位文件并重载 controller:

# 生成 2048 位 DH 参数(耗时数十秒)
openssl dhparam -out /etc/ingress-controller/ssl/dhparam.pem 2048
kubectl -n ingress-nginx edit configmap ingress-nginx-controller
# data:
#   ssl-dh-param: ingress-nginx/dhparam

证书装上去了不等于生效。Secret 类型对了、Ingress 也引用了,仍可能因为缺 SNI、证书链顺序错、controller 没热加载而让浏览器报警。按下面 5 层由外到内逐层验证,每一层都有可判定的通过信号。

第一层:openssl 直连,验证 TLS 握手本身。绕过 DNS 打入口 IP,用 -servername 显式携带 SNI——这一步不能省,否则 nginx-ingress 会回落到 default 证书,验证就变成假阳性。

openssl s_client -connect 1.2.3.4:443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -E 'Protocol|Cipher|Verify return code'
# 期望输出:
# Protocol  : TLSv1.3
# Cipher    : TLS_AES_128_GCM_SHA256
# Verify return code: 0 (ok)

据 OpenSSL 文档,-showcerts 会打印服务端下发的完整证书链;TLS 1.3 的 AEAD 套件命名规则见 RFC 8446 附录 B.4。若 Protocol 显示 TLSv1.2 而期望 1.3,先查 Ingress 的 ssl-protocols 注解与 controller 版本(ingress-nginx 1.9+ 默认已含 TLSv1.3)。

第二层:curl 带 SNI 解析,验证应用层与重定向。

curl -vI https://example.com --resolve example.com:443:1.2.3.4 2>&1 
  | grep -E 'SSL certificate verify|subjectAltName|HTTP/'
# 期望:SSL certificate verify ok.
#       subjectAltName: host "example.com" matched cert's "example.com"
#       HTTP/2 200
# 若得到 HTTP/1.1 301 且 Location: https://...,说明 ssl-redirect 生效
# (ingress-nginx 该注解默认值为 false,需显式开启)

--resolve 不污染 DNS,适合在切流量前灰度验证新入口。subjectAltName 列表必须覆盖实际访问的域名,Let’s Encrypt 签发的证书不再使用 CN 匹配,仅看 subjectAltName。

第三层:查集群对象状态,排除”证书没问题但对象没挂上”。

kubectl get ingress example -n prod
# ADDRESS 列应为 LB IP/域名,空白说明 controller 未 watch 到该 IngressClass
kubectl describe ingress example -n prod | sed -n '/TLS:/,/Rules:/p'
# 期望:TLS:  example-tls  Hosts:  example.com
kubectl get secret example-tls -n prod -o jsonpath='{.type}{"n"}'
# 期望:kubernetes.io/tls;且 tls.crt、tls.key 两个 key 缺一不可

第四层:证书链完整性。本地 openssl verify 与 SSL Labs 报告互相印证:

openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
# 期望:fullchain.pem: OK
awk '/BEGIN CERTIFICATE/{c++} END{print c" certs"}' fullchain.pem
# 期望:2~3 certs(叶子证书 + 中间证书,根证书可省略)

SSL Labs 报告中 Chain issues 应为 None;出现 “Incomplete chain” 或 “Contains anchor” 说明中间证书缺失或顺序颠倒。只发叶子证书是 502 与”证书不受信任”的高发原因。

第五层:续期与到期监控。

kubectl get certificate -n prod
# NAME          READY   SECRET        AGE
# example-tls   True    example-tls   30d
kubectl get certificate example-tls -n prod -o jsonpath='{.status.renewalTime}{"n"}'
# cert-manager 未设 renewBefore 时默认取证书时长的 2/3,且不早于到期前 30 天
# 外部监控:blackbox_exporter 的 probe_ssl_earliest_cert_expiry 返回 Unix 时间戳
# 告警阈值建议:(probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
层级 关键命令 通过判据 典型失败信号
1 TLS 握手 openssl s_client -servername Verify return code: 0 返回 default 证书、CN 不符
2 应用层 curl -vI –resolve HTTP/2 200 + verify ok 421/SSL_ERROR_BAD_CERT_DOMAIN
3 对象状态 kubectl get/describe ADDRESS 有值、TLS 段有 secretName ADDRESS 空白、Secret 类型为 Opaque
4 链完整性 openssl verify -CAfile fullchain.pem: OK unable to get local issuer certificate
5 续期 kubectl get certificate READY=True、renewalTime 合理 READY=False,Events 报 ACME 校验失败

把 5 层做成一个上线检查脚本,每次 k8s ingress ssl证书安装 后跑一遍,能挡掉绝大多数”看起来装好了但用户报错”的返工。

很多人把k8s ingress ssl证书安装当成一次性动作——Secret 建好、Ingress 挂上、浏览器出现小锁,任务就结束了。真正的问题在 60 天后:证书过期,用户看到 NET::ERR_CERT_DATE_INVALID,而你还在翻当时的操作记录。这一节讲清楚两条轮换路线(cert-manager 自动、手动换名切流)、怎么监控剩余天数、以及参数该填多少。

cert-manager 场景:续签为什么不需要重启 Pod?

据 cert-manager 官方文档,Certificate 资源的 renewBefore 默认取 duration 的 1/3;duration 默认 2160h(90 天),因此默认就是到期前 720h(30 天)触发续签。签发成功后,cert-manager 会原地覆盖同名 Secret。ingress-nginx 通过 informer 监听 Secret 变更,证书走动态加载路径,controller 不需要重启,nginx 也不做整体 reload,已有连接不中断——这是很多人误以为“必须滚动重启”的地方。

# cert-manager v1.14+ 验证:duration/renewBefore 是否生效
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-tls
  namespace: prod
spec:
  secretName: example-tls      # 续签后写回这个同名 Secret
  duration: 2160h              # 默认 90 天,Let's Encrypt 上限也是 90 天
  renewBefore: 720h            # 到期前 30 天续签,默认值即 duration 的 1/3
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - www.example.com
---
# 检查续签时间点与状态
kubectl -n prod describe certificate example-tls | grep -E 'Renewal Time|Not After|Status'
# Status: True / Renewal Time: ... / Not After: ...

注意:把 duration 设成大于 90 天对 Let’s Encrypt 无效,CA 返回什么就用什么;商业证书 365 天有效期时,renewBefore 建议改成 1080h(45 天),给审批和采购留出余量。

手动场景:为什么推荐“换名再切流”而不是直接覆盖?

直接覆盖同名 Secret 技术上可行,但一旦新证书链拼错(漏了中间证书)或私钥不匹配,旧证书已经被冲掉,你只能重新申请。换名切流把“发布”和“清理”拆成两步,回滚就是把 Ingress 的 secretName 改回去。

# 1) 新证书先落到新名字
kubectl -n prod create secret tls example-tls-v2 --cert=fullchain.pem --key=privkey.pem
# 2) 只改 Ingress 的 tls 引用
kubectl -n prod patch ingress web --type=json 
  -p='[{"op":"replace","path":"/spec/tls/0/secretName","value":"example-tls-v2"}]'
# 3) 观察 5-10 分钟:证书主题、到期时间、是否出现 5xx
curl -svI https://www.example.com 2>&1 | grep -E 'subject:|expire date:'
# 4) 有异常立刻回滚
kubectl -n prod patch ingress web --type=json 
  -p='[{"op":"replace","path":"/spec/tls/0/secretName","value":"example-tls"}]'
# 5) 确认稳定后删除旧 Secret
kubectl -n prod delete secret example-tls
轮换方式 回滚成本 是否重启工作负载 适用场景
cert-manager 自动续签(覆盖同名 Secret) 低,重签即可 否 ACME 证书、域名固定
手动换名再切流 极低,改回 secretName 否 商业证书、需人工审批
手动直接覆盖同名 Secret 高,旧私钥丢失 否 仅应急修补

过期监控的最小实现是什么?

不需要一上来就上完整可观测平台,一条命令就能验证券书剩余天数;openssl x509 -checkend 在证书于指定秒数内过期时返回 1,非常适合做探针。

# 打印到期时间
kubectl -n prod get secret example-tls -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -enddate -subject
# 剩余不足 21 天(1814400 秒)时返回 1,可作为告警判定
kubectl -n prod get secret example-tls -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -checkend 1814400 || echo "TLS 证书将在 21 天内过期"

集群内更推荐 blackbox_exporter 的 probe_ssl_earliest_cert_expiry(Unix 时间戳),每 6 小时采集一次,告警规则写成 (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21 即可覆盖所有 Ingress 域名。

非 Ingress 终止 TLS 的场景要不要 reloader?

如果 TLS 在 Ingress 终止,上面的热加载已足够,不需要额外组件。但应用自己读取挂载的 Secret 文件(例如 Go 服务只在启动时加载证书),文件更新后进程仍用旧证书。此时可用 stakater/reloader v1.x,在 Deployment 上加注解 reloader.stakater.com/auto: "true",它监听同命名空间 Secret 变更并触发滚动重启。代价是重启会中断连接,因此务必配合 maxUnavailable: 0 的滚动策略。

判断标准很简单:Secret 的生命周期由人管,就必须有人盯到期时间;交给 cert-manager,就把它当成不可变基础设施,只在告警里留一条兜底规则。

不需要。证书以 kubernetes.io/tls 类型的 Secret 存在 etcd 中,ingress-nginx 通过 API Server 监听并加载,节点本地不落地文件。只有当你使用 hostPath 挂载或自建 nginx 不用 Ingress 时,才需要关心节点上的证书路径。

说明传入的不是 PEM 文本。先用 file cert.pfx 确认格式,若为 PKCS#12 执行 openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert.pem 转换;若为 DER 执行 openssl x509 -inform der -in cert.der -out cert.pem,并确认文件首行是 —–BEGIN CERTIFICATE—–。

不是必须。cert-manager 解决的是签发与续期自动化,ingress-nginx 只负责终止 TLS 并引用 Secret。若使用商业证书或云 LB 托管证书,完全可以只做 kubectl create secret tls,只是每 90 天到 1 年需要人工更换一次。

看私钥合规要求与运维边界。Ingress 方案证书随代码走 GitOps、灰度方便,适合域名多且团队自己管集群;云 LB 托管方案私钥不进集群、续期由平台推送,适合等保要求私钥不出云控制台的场景。两者不要在同一链路重复终止 TLS。

可以。spec.tls 是数组,每项包含 hosts 与 secretName,nginx 按 SNI 选择证书。泛域名 *.example.com 写进 Certificate 的 dnsNames 后,Ingress 的 host 只能填一级子域如 api.example.com,a.b.example.com 需要单独签发。

先确认 Secret 内容确实变了:kubectl get secret example-tls -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -serial。若 Secret 已更新但浏览器仍旧,多为前面还有 CDN 或四层 LB 缓存了旧证书,或本地 DNS 解析到了未更新的节点。

检查 Ingress 注解 nginx.ingress.kubernetes.io/ssl-redirect 是否被显式设为 “false”,以及是否配置了 force-ssl-redirect。若前面有云 LB 做四层转发,跳转发生在 Ingress 层,需要确认 80 端口确实转发到了 controller 的 80 端口而非直接丢弃。


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

内容审核

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