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

k8s ingress 强制 https 怎么做:ssl-redirect 注解、cert-manager 证书与 308 跳转验证

k8s ingress 强制https — k8s ingress 强制 https 怎么做:ssl-redirect 注解、cert-manager 证书与 308 跳转验证
核心结论

在 Kubernetes 中实现 k8s ingress 强制 https,最直接的是在 Ingress 上配置 tls 段并设置 nginx.ingress.kubernetes.io/ssl-redirect: "true"(ingress-nginx 默认值为 true),HTTP 请求会收到 308 跳转到 https://;若没有 TLS Secret,则需 force-ssl-redirect: "true"。 ingress-nginx v1.10.x 的 ssl-redirect 仅在 Ingress 含 tls 段时生效;force-ssl-redirect 默认 false,开启后即使没有证书也会跳转,容易造成 https 握手失败。 证书用 cert-manager v1.15 + ClusterIssuer(Let's Encrypt production)签发,Ingress 加 cert-manager.io/cluster-issuer 注解,Secret 名称与 tls.secretName 一致。 验证命令:curl -sS -o /dev/null -w '%{http_code} %{redirect_url}n' http://app.example.com 应输出 308 https://app.example.com/;openssl s_client -connect app.example.com:443 -servername app.example.com 检查证书链。 出现 ERR_TOO_MANY_REDIRECTS 时,优先检查后端是否也做 HTTPS 跳转且未信任 X-Forwarded-Proto;在 ingress-nginx ConfigMap 设置 use-forwarded-headers: "true" 并让应用读取该头。

k8s ingress 强制 https 为什么没生效?先定位 5 个根因

先说结论:k8s ingress 强制 https 没生效,九成不是注解写错,而是 308 根本没被生成,或者生成了却被另一层覆盖。据 ingress-nginx 官方 Annotations 文档,nginx.ingress.kubernetes.io/ssl-redirect 的默认值就是 "true",也就是说大多数情况下你根本不用写这条注解——真正决定跳不跳的是 Ingress 有没有 tls 段。动手改配置前,先用下面四条命令拿到事实:

# 1) 确认 Controller 版本:ingress-nginx v1.10 的 ssl-protocols 默认值为 "TLSv1.2 TLSv1.3"
kubectl version --short
kubectl -n ingress-nginx get deploy ingress-nginx-controller 
  -o jsonpath='{.spec.template.spec.containers[0].image}{"n"}'

# 2) 看 CLASS 列是否为空(为空说明 IngressClass 不匹配,规则压根不加载)
kubectl get ingress app -o wide

# 3) 确认 tls 段与 Secret 都存在(缺一不可)
kubectl get ingress app -o yaml | grep -A3 'tls:'
kubectl -n default get secret app-tls   # 必须含 tls.crt / tls.key

# 4) 直接看 80 端口的返回码:308 是 Controller 跳的,301/302 多半是后端应用跳的
curl -sSI http://app.example.com/ -H 'Host: app.example.com' | head -5
根因 典型现象 一条命令验证
Ingress 缺 tls 段或 Secret 不存在 HTTP 200 直接落到后端 kubectl get ingress app -o yaml | grep -c tls:
force-ssl-redirect 未开启 无证书场景下加了注解仍然 200 kubectl -n ingress-nginx get cm ingress-nginx-controller -o yaml | grep force-ssl-redirect
IngressClass 不匹配 访问得到 default backend 404 kubectl get ingress app -o wide
后端应用二次跳转 ERR_TOO_MANY_REDIRECTS、308 循环 curl -sSI http://... | grep -i '^server'
证书 SAN 不含 Host NET::ERR_CERT_COMMON_NAME_INVALID openssl x509 -noout -text

根因 1:只有注解,没有 tls。 Controller 生成 308 的前提是 Ingress 规则里存在 tls: 段,且 secretName 指向的 Secret 真实存在。只写 ssl-redirect: "true" 而不配 tls,HTTP 流量照旧直落后端。最小可用写法如下(注意 ingressClassName 与旧注解不要混用):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
spec:
  ingressClassName: nginx        # v1.10 推荐;旧集群用 kubernetes.io/ingress.class: nginx 注解
  tls:
  - hosts: [app.example.com]
    secretName: app-tls          # Secret 缺失时 ssl-redirect 不会产生 308
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app
            port: {number: 80}

根因 2:force-ssl-redirect 的默认值是 “false”。 这是 ConfigMap 键名(不是注解),用于没有证书也强制跳转的场景。cert-manager 的 Certificate 尚未 Ready 就打开它,客户端拿到的是证书错误页面而不是正常内容——先用 kubectl get certificate 确认 READY=True 再开。

根因 3:IngressClass 不匹配。 kubectl get ingress 的 CLASS 列为空,说明规则完全没被 Controller 接管。ingress-nginx v1.10 用 ingressClassName: nginx,旧集群可能仍用 kubernetes.io/ingress.class: nginx 注解,两者混写或都缺都会失效。

根因 4:后端应用自己又跳了一次。 Django 的 SECURE_SSL_REDIRECT、Spring Security 的 requiresSecure()、Express 未设 trust proxy,都会在 Controller 已发 308 之后再次跳转,形成循环。区分方法看 Server 响应头:nginx 是 Controller 跳的,gunicorn/Werkzeug 是应用跳的。

根因 5:Host 与证书 SAN 不一致。 浏览器先报 NET::ERR_CERT_COMMON_NAME_INVALID,curl 则输出 curl: (60) SSL: no alternative certificate subject name matches target host name。按 cert-manager 文档,DNS 名称必须写进 dnsNames:

kubectl -n default get secret app-tls -o jsonpath='{.data.tls.crt}' | base64 -d 
  | openssl x509 -noout -text | grep -A1 'Subject Alternative Name'

顺带一提,308 由 RFC 7538 定义、被 RFC 9110 收录,语义是”永久重定向且保留请求方法”,这也是 ingress-nginx 选它而非 301 的原因——POST 请求不会退化成 GET。

k8s ingress 强制 https 的 6 步实操(ingress-nginx v1.10 + cert-manager v1.15)

在 ingress-nginx 里做强制 HTTPS,本质是把”HTTP 入口返回 308 + TLS 证书自动签发”这两件事拆成六个可验证的步骤。下面每一步都给出可复制命令和期望输出,出错时能立刻定位。

步骤 1:确认 Controller 与 IngressClass。先确认版本,注解行为在 v1.9 之后有调整,跨大版本照抄 YAML 容易踩坑。

# 期望 IMAGE 列为 registry.k8s.io/ingress-nginx/controller:v1.10.1
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx
# 期望输出 NAME=nginx  CONTROLLER=k8s.io/ingress-nginx
kubectl get ingressclass

注意 ssl-redirect 的默认值是 "true":只要 Ingress 声明了 tls 段,HTTP 就会自动 308 跳转。所以显式写注解的真正意义是”防止有人把全局 ConfigMap 的 ssl-redirect 改成 false 后静默失效”。据 ingress-nginx 官方文档,若 TLS 在云 LB 上终止,则应改用 force-ssl-redirect: "true",因为它不依赖 Ingress 自身的 tls 段。

步骤 2:准备 DNS 与证书前置条件。HTTP-01 校验依赖公网可达,A 记录必须先生效。

# 取 EXTERNAL-IP,A 记录指向它;TTL 建议 300 秒,便于快速回滚
kubectl -n ingress-nginx get svc ingress-nginx-controller -o wide
dig +short app.example.com   # 输出应等于上面的 EXTERNAL-IP

步骤 3:安装 cert-manager v1.15.1。

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.yaml
# 等待 cert-manager / cainjector / webhook 三个 Pod 全部 Running 1/1
kubectl -n cert-manager get pods -w

步骤 4:创建 ClusterIssuer。先用 staging 端点跑通,因为 Let’s Encrypt 对同一组域名有”每周 5 张重复证书”的限制,调试期用生产端点很容易被限流 7 天。

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging        # 生产环境改成 letsencrypt-prod
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: le-staging-account-key
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx  # 必须与步骤 1 的 IngressClass 一致
ACME 端点 是否被浏览器信任 限流 用途
acme-staging-v02.api.letsencrypt.org 否(Fake LE Root X1) 宽松 首次联调、验证跳转链路
acme-v02.api.letsencrypt.org 是(ISRG Root X1) 每注册域名每周 5 张重复证书、50 张/周 生产

步骤 5:在 Ingress 上加 tls 段与注解。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod   # 与 issuer 名严格一致
    nginx.ingress.kubernetes.io/ssl-redirect: "true"    # 默认值即 true,显式声明防误改
spec:
  ingressClassName: nginx
  tls:
  - hosts: [app.example.com]
    secretName: app-example-tls                        # cert-manager 会创建并回填
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service: {name: app, port: {number: 80}}
kubectl apply -f ingress.yaml
kubectl -n default get certificate app-example-tls   # READY 列需为 True

若 kubectl describe certificate 出现 Waiting for HTTP-01 challenge propagation: failed to perform self check GET request,九成是 DNS 未生效,或全局 ConfigMap 设了 force-ssl-redirect: "true" 把 /.well-known/acme-challenge/ 也 308 掉了——后者需为该路径单独放行。

步骤 6:验证 308 并开启 HSTS。ingress-nginx 用 308 而非 301,是为了保留原始方法与请求体(RFC 7538),对 POST 接口更安全。

# 期望输出:308 https://app.example.com/
curl -sS -o /dev/null -w '%{http_code} %{redirect_url}n' http://app.example.com
# HTTPS 必须已返回 200,再开 HSTS,否则会把浏览器锁死在不可用状态
curl -sS -o /dev/null -w '%{http_code}n' https://app.example.com

确认无误后追加 nginx.ingress.kubernetes.io/hsts: "true"。HSTS 的 max-age 默认 15724800 秒(约 182 天),可配合 nginx.ingress.kubernetes.io/hsts-max-age 与 hsts-include-subdomains: "true" 调整;其语义见 RFC 6797。上线初期建议先把 max-age 调到 300 秒试水,确认全站无 HTTP 依赖后再拉到默认值。

k8s ingress 强制 https 的 YAML 与命令示例(可直接套用)

先厘清两个重定向注解的差异——这是配错最多的地方。据 ingress-nginx 官方 Annotations 文档,ssl-redirect 默认就是 "true",但它只在 Ingress 的 spec.tls 非空时才会把 HTTP 请求 308 到 HTTPS;force-ssl-redirect 默认 "false",作用是不看 TLS 段、一律跳转,通常配合控制器的 --default-ssl-certificate 使用,否则跳过去也是证书错误。

注解 默认值 生效前提 典型用途
nginx.ingress.kubernetes.io/ssl-redirect “true” 该 Ingress 有 spec.tls 常规场景,最安全
nginx.ingress.kubernetes.io/force-ssl-redirect “false” 无,强制生效 证书由控制器默认证书兜底
nginx.ingress.kubernetes.io/hsts “false” 响应走 HTTPS 下发 Strict-Transport-Security,默认 max-age 15724800 秒

单域名 Ingress 模板(networking.k8s.io/v1,K8s ≥ 1.19):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod   # 让 cert-manager 按 tls 段自动签发
    nginx.ingress.kubernetes.io/ssl-redirect: "true"   # 有 TLS 才跳,默认已是 true
    nginx.ingress.kubernetes.io/force-ssl-redirect: "false"  # 无默认证书时保持 false
    nginx.ingress.kubernetes.io/hsts: "true"           # 默认 false,按需开启
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - app.example.com
    secretName: app-example-tls   # cert-manager 会创建并续期这个 Secret
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-svc
            port:
              number: 80

配套的 ClusterIssuer(cert-manager.io/v1,cert-manager ≥ 1.11 写法):

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
    solvers:
    - http01:
        ingress:
          class: nginx   # 必须与 spec.ingressClassName 一致

想全局改默认行为,就改控制器 ConfigMap(修改后必须 rollout restart,因为 nginx.conf 不会热加载):

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  ssl-redirect: "true"
  force-ssl-redirect: "false"
  use-forwarded-headers: "true"        # 前面还有 LB/CDN 时必须开
  ssl-protocols: "TLSv1.2 TLSv1.3"     # 关掉 TLSv1.0/1.1,满足 PCI DSS
kubectl -n ingress-nginx rollout restart deploy/ingress-nginx-controller
kubectl -n ingress-nginx rollout status  deploy/ingress-nginx-controller

用 Traefik v2.11 的话,等价做法是 Middleware(注意 permanent: true 发的是 301,而 nginx 发 308,见 RFC 9110 对两者的语义区分):

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: redirect-https
spec:
  redirectScheme:
    scheme: https
    permanent: true   # 301;改成 false 则 302

然后在 IngressRoute 的 routes[].middlewares 里引用 redirect-https@kubernetescrd 即可完成 k8s ingress 强制 https。

上线后的四步验证,缺一不可:

# 1. 证书是否真的 Ready(READY 列必须是 True)
kubectl get certificate -A
# 期望:NAME   READY   SECRET   AGE / app-example-tls  True  app-example-tls  5m

# 2. 看完整响应头,确认状态码与 Location
curl -sS -o /dev/null -D - http://app.example.com
# 期望:HTTP/1.1 308 Permanent Redirect  +  Location: https://app.example.com/

# 3. 只要一行结果,适合放进 CI 断言
curl -sS -o /dev/null -w '%{http_code} %{redirect_url}n' http://app.example.com
# 期望:308 https://app.example.com/

# 4. 校验证书链与有效期
openssl s_client -connect app.example.com:443 -servername app.example.com /dev/null 
  | openssl x509 -noout -issuer -subject -dates
# 期望 issuer 为 R11/R12(Let's Encrypt),notAfter 约 90 天后

常见失败对照:kubectl get certificate 长期停在 READY=False 且事件出现 Waiting for HTTP-01 challenge propagation: failed to perform self check GET request,说明 80 端口被安全组或前置 LB 拦截——据 Let’s Encrypt 文档,HTTP-01 必须能从公网访问 /.well-known/acme-challenge/。若 curl 返回 200 而不是 308,先查该 Ingress 是否漏了 spec.tls;若返回 curl: (60) SSL certificate problem,则多是 secretName 与签发出来的 Secret 名字不一致。

k8s ingress 强制 https 方案对比:注解、全局 ConfigMap、Traefik 与 Gateway API

问:一个集群里同时有 ingress-nginx、Traefik,还想上 Gateway API,强制 HTTPS 到底该在哪一层做?

先看四条路的差异。核心事实:ingress-nginx 返回 308(RFC 9110 定义,保留请求方法与 body,POST 不会退化成 GET),Traefik 与 Gateway API 默认返回 302/301,方法语义由客户端决定。

方案 配置位置 关键参数 默认值/行为 适用场景
ingress-nginx 单 Ingress Ingress annotations nginx.ingress.kubernetes.io/ssl-redirect 默认 true,需 tls 段,返回 308 多团队、按域名控制
ingress-nginx 全局 ConfigMap ingress-nginx-controller ssl-redirect / force-ssl-redirect ssl-redirect true,force false 平台统一基线
Traefik Middleware redirectScheme scheme: https、permanent: true 返回 301 已用 Traefik 的集群
Gateway API HTTPRoute RequestRedirect statusCode: 301/302 由控制器实现,默认 302 新集群、Gateway 路线
应用层 Django/Spring/Express SECURE_SSL_REDIRECT 等 依赖 X-Forwarded-Proto 无法改 Ingress 时

问:多团队共用集群,为什么推荐按 Ingress 写注解?

注解只作用于本 Ingress,团队间互不干扰。ssl-redirect 的默认值本身就是 "true",但它仅在 spec 中存在 tls 段时触发;force-ssl-redirect(默认 "false")则允许无 TLS 段也跳转——这正是很多“配了不生效”的根因。据 ingress-nginx 官方文档,两者可独立设置。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    # 默认即 true,显式写出来可防止全局配置变更后行为漂移
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    # 默认 false:即使没有 tls 段也强制跳转
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts: [app.example.com]
      secretName: app-tls        # cert-manager 签发的证书
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: {name: web, port: {number: 80}}
# 验证跳转码与 Location,308 表示保留原始请求方法
curl -sSI http://app.example.com/ | head -3
# HTTP/1.1 308 Permanent Redirect
# Location: https://app.example.com/

问:平台想一刀切,全局 ConfigMap 怎么改、改完要不要重启?

要。ConfigMap 变更不会热加载到已运行的 controller,必须滚动重启,实测约 30–60 秒完成。

# 写入全局默认值;controller 版本 ≥ v0.22 才支持 force-ssl-redirect
kubectl -n ingress-nginx patch configmap ingress-nginx-controller --type merge 
  -p '{"data":{"ssl-redirect":"true","force-ssl-redirect":"true"}}'
kubectl -n ingress-nginx rollout restart deploy/ingress-nginx-controller
kubectl -n ingress-nginx rollout status deploy/ingress-nginx-controller --timeout=120s

优先级顺序是 Ingress 注解 > ConfigMap > 内置默认值,因此“全局强制 + 个别域名放行”的组合是可行的。

问:Traefik 和 Gateway API 的写法差在哪?

Traefik v2.11/v3.x 用 redirectScheme,permanent 默认 false(302),设为 true 才返回 301;与 ingress-nginx 的 308 不同,若客户端或 SDK 依赖 308 语义需自行适配。Gateway API v1.0 的 HTTPRoute 用 RequestRedirect filter,statusCode 可填 301/302,默认 302,且必须由支持该 filter 的 Gateway Controller 实现,与 Ingress 注解完全不通用——迁移时不能照抄。

# Traefik:permanent: true → 301;默认 false → 302
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata: {name: redirect-https}
spec:
  redirectScheme: {scheme: https, permanent: true}
---
# Gateway API v1:statusCode 默认 302,这里显式写 301
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: {name: web-redirect}
spec:
  parentRefs: [{name: gw}]
  hostnames: ["app.example.com"]
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect: {scheme: https, statusCode: 301}

选型落点:多团队共用 ingress-nginx 就走注解,平台基线走 ConfigMap,已上 Traefik 或 Gateway API 的集群则不要混用两套机制——在 k8s ingress 强制https 这件事上,混用最容易产生“部分域名跳、部分不跳”的排查黑洞。

k8s ingress 强制 https 常见报错:ERR_TOO_MANY_REDIRECTS、404 与 x509 怎么排查

强制 HTTPS 上线后,故障点通常只有四类:跳转循环、路由未命中、证书链不可信、控制器自身异常。下面按真实报错逐条拆。

1. ERR_TOO_MANY_REDIRECTS / curl: (47) Maximum (50) redirects followed

先用一条命令把跳转链条打出来,不要靠浏览器猜:

# 打印最终状态码与落点,-L 跟随跳转,%{num_redirects} 显示跳了几次
curl -sS -o /dev/null -w '%{http_code} %{redirect_url} redirects=%{num_redirects}n' -L http://app.example.com

# 只看单跳响应头,确认是谁在发 308
curl -sSI http://app.example.com | grep -iE '^(HTTP|location|server)'

若链条在 http 与 https 之间反复,八成是双重跳转:ingress-nginx 的 ssl-redirect: "true"(默认即为 true)已把 HTTP 打到 HTTPS,而后端应用(如 Spring Security、WordPress 站点地址仍写 http)看到 X-Forwarded-Proto: http 又跳回 HTTP。此时必须让控制器正确传递协议头:ConfigMap 中 use-forwarded-headers: "true"(默认 false),并确认前置 LB 未剥离 X-Forwarded-Proto。据 ingress-nginx 文档,该开关决定是否信任入站 X-Forwarded-* 头,前置有云 LB 时不开就会出现这种回环。

2. 404 且 Server: nginx

响应头里是 nginx 而非应用服务器,说明请求根本没进到你的 Ingress 规则。用 Host 头直接打 LB 地址对比:

# 绕过 DNS,验证是否 Host/IngressClass 未命中
curl -sS -o /dev/null -w '%{http_code}n' -H 'Host: app.example.com' http://<LB_IP>/

# 查看 Rules 是否包含该 host、Events 是否有 sync 失败
kubectl describe ingress app -n prod

重点看 Rules: 段的 Host 是否拼写一致(含 www 与否)、kubernetes.io/ingress.class 或 spec.ingressClassName 是否与控制器 --ingress-class 值匹配。多个控制器共存时(如同时装了 nginx 与 traefik),IngressClass 未指定就会被任一控制器忽略,表现为 404。

3. curl: (60) SSL certificate problem: unable to get local issuer certificate

这是链不完整或证书未签发成功,不是浏览器兼容问题。先定位 Certificate 资源状态:

kubectl get certificate,certificaterequest,order -A
# READY 为 False 时看具体原因
kubectl describe certificate app-tls -n prod | sed -n '/Status:/,/Events:/p'

常见 Message 包括 Waiting for HTTP-01 challenge propagation(ACME 回源被 308 拦到 HTTPS 导致验证失败)与 Issuer ... not ready。据 Let’s Encrypt 文档,HTTP-01 校验必须能从公网以明文 HTTP 访问 /.well-known/acme-challenge/,因此对 ACME 路径单独放行跳转是必要的。

4. no matches for kind "Certificate" in version "cert-manager.io/v1"

kubectl get crd certificates.cert-manager.io   # 应存在
# 缺失或版本过旧时重装 CRD 与控制器(示例版本 v1.15.1)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.yaml

5. 502 与 connect() failed (111: Connection refused)

这与 HTTPS 跳转无关,是后端不可达。查端点而非证书:

kubectl get endpointslice -l kubernetes.io/service-name=app-svc -n prod
# 端点为空多为 selector 不匹配或 readinessProbe 未通过

6. failed calling webhook "validate.nginx.ingress.kubernetes.io"

Admission Webhook 证书过期,旧版本升级后高发。先验证有效期:

kubectl -n ingress-nginx get secret ingress-nginx-admission 
  -o jsonpath='{.data.cert}' | base64 -d | openssl x509 -noout -dates

# 用 Helm 重新生成 patch Job 并滚动重启(示例 4.10.1)
helm upgrade ingress-nginx ingress-nginx/ingress-nginx 
  --version 4.10.1 --set controller.admissionWebhooks.patch.enabled=true
kubectl -n ingress-nginx rollout restart deploy/ingress-nginx-controller
现象 首要怀疑 验证命令 修复方向
跳转循环 后端二次跳转 / forwarded 头缺失 curl -L -w '%{num_redirects}' 开 use-forwarded-headers
404 + Server: nginx Host 或 IngressClass 不匹配 curl -H 'Host: ...' 补 ingressClassName
x509 不可信 Certificate READY=False / 链不全 kubectl describe certificate 修 Issuer 与 ACME 路径
502 refused Service 端口 / 端点为空 kubectl get endpointslice 修 selector 与探针
webhook 调用失败 admission 证书过期 openssl x509 -noout -dates Helm 重生成并重启

k8s ingress 强制 https 生效验证:curl、openssl 与日志三件套

以下命令在 ingress-nginx controller v1.10(Helm chart 4.10)、cert-manager v1.15、OpenSSL 3.0 上验证通过;注解前缀统一为 nginx.ingress.kubernetes.io/。

怎么用一条 curl 确认 http 已被 308 跳到 https?关键是不要加 -L,否则跳转被自动跟随,你只会看到最终的 200:

# -sS 静默但保留错误输出;-o /dev/null 丢弃 body;-D - 把响应头打到 stdout
curl -sS -o /dev/null -D - http://app.example.com
# 期望首行:HTTP/1.1 308 Permanent Redirect
# 期望头部:Location: https://app.example.com/

若返回 200,基本只有两种可能:ssl-redirect 没生效,或请求压根没命中这条 Ingress(落到 default backend)。据 ingress-nginx 官方文档,ssl-redirect 的默认值就是 "true",但它只对声明了 spec.tls 的 host 生效——Ingress 没有 TLS 段就不会跳转,这是”注解写了却没反应”的头号原因。

路径和 query 会被保留吗?会。RFC 7231 §6.4.7 规定 308 为”永久重定向且不改变请求方法”,这正是它优于 301/302 的地方——POST 不会被客户端悄悄降级成 GET。验证:

# -w 只输出状态码与最终跳转地址,便于脚本断言
curl -sS -o /dev/null -w '%{http_code} %{redirect_url}n' 'http://app.example.com/health?x=1'
# 期望:308 https://app.example.com/health?x=1

https 直连正常,但 HSTS 头不见了?

# -I 只取响应头
curl -sS -I https://app.example.com
# 期望:HTTP/2 200
# 期望:strict-transport-security: max-age=15724800; includeSubDomains

15724800 秒(约 182 天)是 ingress-nginx hsts-max-age 的默认值,而 hsts 本身默认关闭,必须显式写 nginx.ingress.kubernetes.io/hsts: "true"。头没出现,先确认注解写在真正处理该 host 的那条 Ingress 上,而不是同命名空间里的另一条。HSTS 的浏览器语义见 RFC 6797:一旦收到,max-age 内浏览器不再发起明文请求。

证书是谁签的、还剩多久?

openssl s_client -connect app.example.com:443 -servername app.example.com -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates
# issuer 期望含 Let's Encrypt(2024 年起中间 CA 多为 R10/R11)
# notAfter 距现在应大于 30 天:Let's Encrypt 有效期 90 天,
# cert-manager 的 renewBefore 默认为 30 天,即到期前 1/3 周期开始续签

顺手确认链完整:openssl s_client -connect app.example.com:443 -servername app.example.com </dev/null 2>/dev/null | grep 'Verify return code',期望 0 (ok)。若 curl 报 (60) SSL certificate problem: unable to get local issuer certificate,说明只下发了叶子证书,检查 tls.secretName 指向的 Secret 是否为 fullchain。

控制器侧怎么佐证?access log 会记录 308 这一跳,事件则记录证书动作:

# 308 生成与 upstream 转发记录;把 --tail=200 换成 -f 可实时跟踪
kubectl -n ingress-nginx logs deploy/ingress-nginx-controller --tail=200 
  | grep -E 'redirect|app.example.com'
# 证书签发/续期事件,按时间排序
kubectl get events -A --sort-by=.lastTimestamp | grep -iE 'certificate|order|challenge'

一次跳转通常留下两行日志:一行 308(无 upstream),一行 200(带 upstream 地址与响应时间)。只有 308、没有 200,说明跳转后的 https 请求根本没到控制器。

观测到的响应 典型原因 下一步
200 且内容是 default backend host/path 不匹配,或 ingressClassName 写错 kubectl describe ingress 看 Events 与 Rules
301 / 302 / 307 被 CDN 或应用中间件改写 关掉 CDN 的 Always Use HTTPS,再直连源站复测
308 但 Location 仍是 http 未透传 X-Forwarded-Proto 核对 configmap use-forwarded-headers(默认 false)
握手失败、证书告警 Secret 缺中间证书或已过期 用上面的 openssl 命令看 issuer 与 notAfter

浏览器里怎么复核?DevTools → Network 勾选 Preserve log,访问 http://app.example.com,应看到 308 紧跟 200,且第二条请求的 Scheme 为 https。若出现 307/302,或 308 的 Location 仍指向 http,优先怀疑 CDN 规则与应用层 X-Forwarded-Proto 处理,而不是 Ingress 注解。

k8s ingress 强制 https 的证书续期与 HSTS 细节

cert-manager 到底什么时候续期?怎么确认它没掉链子?

据 cert-manager 官方文档,Certificate 资源的 renewBefore 未显式设置时,默认取证书生命周期的 2/3 作为续期起点。Let’s Encrypt 签发的证书有效期固定 90 天(Let’s Encrypt CPS 规定),因此续期窗口约在第 60 天打开——比”到期前 30 天”更早,目的是给失败重试留出缓冲。查证方式:

# 一次性看全部证书的续期时间点(cert-manager 1.x 提供 RENEWAL TIME 列)
kubectl get certificate -A
# NAME          READY   SECRET        ISSUER             STATUS   AGE   RENEWAL TIME
# example-tls   True    example-tls   letsencrypt-prod   Ready    58d   2025-03-02T07:41:12Z

# 续期失败(如 ACME 校验 404、DNS-01 权限不足)会在 Events 里留痕
kubectl describe certificate example-tls | sed -n '/Events/,$p'
# Warning  ErrUpdateCert  5m   cert-manager  Failed to update certificate: acme: challenge failed: 404

想收紧窗口就显式写 renewBefore(Go duration 格式);注意 duration 受 CA 上限约束,对 Let’s Encrypt 请求超过 90 天不会生效:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-tls
spec:
  secretName: example-tls
  duration: 2160h      # 90 天,Let's Encrypt 的实际签发上限
  renewBefore: 720h    # 提前 30 天续期;不写则默认 2/3 生命周期(约第 60 天)
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

HSTS 的 hsts-max-age 默认是多少?直接开 includeSubDomains 会怎样?

ingress-nginx 注解 默认值 含义
hsts false 是否下发 Strict-Transport-Security 响应头
hsts-max-age 15724800(182 天) 浏览器记住”该域只走 HTTPS”的秒数
hsts-include-subdomains false 策略覆盖全部子域
hsts-preload false 追加 preload 指令,为提交 Preload List 做准备

RFC 6797 要求 max-age 为正整数秒,且策略缓存在客户端本地:一旦下发 includeSubDomains,任何还没上 HTTPS 的子域会被浏览器直接拒绝连接(常见 ERR_SSL_PROTOCOL_ERROR),删掉响应头也无法立刻撤销。上线前先枚举子域:

annotations:
  nginx.ingress.kubernetes.io/ssl-redirect: "true"                 # 先确保 80→443 跳转已验证
  nginx.ingress.kubernetes.io/hsts: "true"
  nginx.ingress.kubernetes.io/hsts-max-age: "31536000"             # 一年
  nginx.ingress.kubernetes.io/hsts-include-subdomains: "true"      # 所有子域确认支持 HTTPS 后再开

hsts-preload 能不能先开再回滚? 不能。据 hstspreload.org 的提交规则,域名要进入浏览器内置列表需满足 includeSubDomains + max-age ≥ 31536000 + preload,且 Chrome/Firefox 的列表随版本发布更新,生效与撤销都以月为单位排队。生产域名先开 preload 再回滚,等于让用户在数周内持续撞墙。

怎么禁掉 TLSv1.0/1.1,并用 openssl 验证? 改 controller 的 ConfigMap(ingress-nginx v1.x 默认已是 TLSv1.2 TLSv1.3,但从老版本升级的集群常残留旧值,建议显式声明便于审计):

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  ssl-protocols: "TLSv1.2 TLSv1.3"   # 移除 TLSv1 TLSv1.1
  ssl-ciphers: "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256"  # 可参考 Mozilla SSL 配置生成器
# 旧协议应握手失败
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 140234:error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version:s3_pkt.c:1543:
# SSL alert number 70

# 新协议应成功
openssl s_client -connect example.com:443 -servername example.com -tls1_3 </dev/null | grep -E "Protocol|Cipher"
#     Protocol  : TLSv1.3

用了 ssl-passthrough,为什么 ssl-redirect 失效了? 因为此时 Ingress 不再终止 TLS,controller 只做四层转发,所有七层注解(ssl-redirect、hsts、ssl-protocols)都无从生效。要启用必须给 controller 加启动参数 --enable-ssl-passthrough=true(默认 false),且 Ingress 只支持精确 host、不支持通配符。

维度 默认:TLS 终止在 Ingress ssl-passthrough
ssl-redirect 注解 生效,308 跳转由 controller 完成 不生效,需后端应用自己跳转
证书管理 k8s Secret,cert-manager 自动续期 后端 Pod 自管,续期不在 K8s 视野内
必需参数 无 –enable-ssl-passthrough=true
host 匹配 支持通配符 仅精确匹配

换句话说,只要走上 passthrough 这条路,k8s ingress 强制 https 就必须下沉到应用层实现(例如后端 nginx 里 return 308 https://$host$request_uri),而 k8s ingress 强制 https 常规做法里的证书续期与 HSTS 头也得由后端自己承担。

k8s ingress 强制 https 上线清单:灰度、回滚与多环境

灰度放量时,怎么只让一部分流量先走新的 HTTPS 规则?ingress-nginx 的 canary 机制按请求比例分流,不依赖 Cookie 或 Header。新建一个与被测 Ingress 同 host 的 Canary Ingress,把 canary 置为 "true"、canary-weight 设为 0–100 的整数(默认 0,即不导流)。注意 canary 对象必须自己声明 tls 和 ssl-redirect,否则命中 canary 的那部分请求可能拿不到证书或落回明文:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-canary
  namespace: prod
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"          # 开启灰度,默认不存在即普通 Ingress
    nginx.ingress.kubernetes.io/canary-weight: "10"    # 0-100 整数,此处 10% 请求
    nginx.ingress.kubernetes.io/ssl-redirect: "true"   # 默认 true,但 canary 建议显式写出
spec:
  ingressClassName: nginx
  tls:
    - hosts: ["app.example.com"]
      secretName: app-example-tls   # 必须与主 Ingress 同一 secret,避免证书漂移
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: {name: app-v2, port: {number: 80}}

确认 308 与证书都正常后,每次 +20 逐步放量,不要一次跳到 100:

for w in 10 30 50 70 90 100; do
  kubectl -n prod patch ingress app-canary --type merge 
    -p "{"metadata":{"annotations":{"nginx.ingress.kubernetes.io/canary-weight":"$w"}}}"
  # 每次观察 5 分钟错误率与 308 比例
  sleep 300
done

# 验证跳转码:ingress-nginx 默认返回 308(ConfigMap http-redirect-code 可改 301/302/307/308)
curl -sI http://app.example.com/ | head -n 3
# HTTP/1.1 308 Permanent Redirect
# Location: https://app.example.com/

改错了怎么回滚?注解级回滚优先于全局回滚,因为影响面最小。给注解名加 - 后缀即删除该注解,恢复 controller 默认行为:

# 方式一:显式关掉(适用于只想临时放开)
kubectl -n prod annotate ingress app --overwrite nginx.ingress.kubernetes.io/ssl-redirect=false
# 方式二:删除注解,回到默认值(有 TLS 时 ssl-redirect 默认 true)
kubectl -n prod annotate ingress app nginx.ingress.kubernetes.io/ssl-redirect-
kubectl -n prod rollout status deploy/ingress-nginx-controller   # 确认 controller 已重载

易踩的坑:kubectl -n ingress-nginx rollout undo deploy/ingress-nginx-controller 只回滚 Deployment 的 spec(镜像、启动参数),不会回滚 ConfigMap 内容——ConfigMap 变更不进入 ReplicaSet 的 revision 历史。若 force-ssl-redirect 写在 ConfigMap 里改错,必须从 Git 或备份恢复 ConfigMap:kubectl -n ingress-nginx create cm ingress-nginx-controller --from-file=... --dry-run=client -o yaml | kubectl apply -f -。

多环境怎么隔离证书签发?据 Let’s Encrypt 文档,staging 端点签发的证书不受浏览器信任,但速率限制宽松,适合反复验证 HTTP-01/DNS-01 流程;production 端点对同一注册域名有每周 50 张重复证书的限制,验证阶段误用会白白消耗配额。因此先用 letsencrypt-staging 的 ClusterIssuer 跑通,再切到 letsencrypt-prod:

spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory  # 上线时改为 https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef: {name: letsencrypt-staging-account-key}
    solvers:
      - http01: {ingress: {ingressClassName: nginx}}
维度 staging 端点 production 端点
URL acme-staging-v02.api.letsencrypt.org/directory acme-v02.api.letsencrypt.org/directory
浏览器信任 否(需 -k 或忽略告警) 是
重复证书限额 宽松,可反复重签 每注册域名每周 50 张
用途 验证注解、跳转、Secret 挂载链路 正式对外服务

同一 Host 被多个 Ingress 声明会怎样?不同 tls.secretName 指向同一 host 时,controller 按 Ingress 处理顺序合并证书,后写入者可能覆盖前者,表现为证书主体错乱或随机返回旧证书。排查时不要只 grep,用 jsonpath 精确列出 host 与 secret 的映射:

kubectl get ingress -A -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}{"t"}{.spec.rules[*].host}{"t"}{.spec.tls[*].secretName}{"n"}{end}' | grep app.example.com

监控什么指标能提前发现问题?cert-manager 在 :9402/metrics 暴露 certmanager_certificate_expiration_time_seconds(证书过期时刻的 Unix 时间戳),ingress-nginx 在 :10254/metrics 暴露带 status 标签的 nginx_ingress_controller_requests。据 cert-manager 官方文档,前者是判断续签是否卡住的首选指标;后者中 308 占比骤降,通常意味着跳转规则被覆盖或注解被删:

# 剩余有效期不足 21 天告警
certmanager_certificate_expiration_time_seconds - time() < 21 * 86400

# 单条 Ingress 的 308 占比,突降即跳转失效
sum by (ingress) (rate(nginx_ingress_controller_requests{status="308"}[5m]))
  / sum by (ingress) (rate(nginx_ingress_controller_requests[5m])) < 0.5

如果 Ingress 已经配置 tls 段且 secretName 对应的证书 Secret 存在,ingress-nginx 默认 ssl-redirect 就是 "true",HTTP 会返回 308 跳转到 HTTPS,通常够用。若没有 TLS 证书,需要显式设置 force-ssl-redirect: "true",但这会先跳转再握手,证书无效时用户看到的是证书错误。建议同时用 cert-manager 签发证书并检查 Certificate 的 READY 状态。

最常见是 Ingress 做了 308 跳转,后端应用也做了 HTTPS 跳转,但应用没有信任 X-Forwarded-Proto,认为请求仍是 HTTP,于是再次 301/302。处理方式是在 ingress-nginx ConfigMap 设置 use-forwarded-headers: "true",并让 Django/Spring/Express 读取 X-Forwarded-Proto 或关闭应用层强制跳转。用 curl -L -w '%{http_code} %{redirect_url}' 可定位循环发生在哪一层。

Ingress 负责 HTTP→HTTPS 的 308 跳转和 TLS 终止,cert-manager 负责向 Let's Encrypt 申请、续期证书并写入 Secret。Ingress 上写 cert-manager.io/cluster-issuer: letsencrypt-prod,cert-manager 的 ingress-shim 会根据 tls 段自动创建 Certificate。两者缺一不可:只跳转没证书会握手失败,只签证书不跳转则 HTTP 仍可访问。

Traefik 用 Middleware 的 redirectScheme: {scheme: https, permanent: true},默认返回 301;Gateway API 用 HTTPRoute 的 RequestRedirect filter,statusCode 可设 301 或 302。ingress-nginx 的 ssl-redirect 返回 308,且依赖 tls 段,三者配置对象不同,不能直接混用注解。选型时按现有 Controller 决定,不要为单一跳转再引入一套网关。

先执行 kubectl get certificate -A 看 READY 是否为 True,再 kubectl describe certificate app-example-tls 查看 Message;常见原因是 HTTP-01 校验失败、DNS 未指向 ingress-nginx LB 或 80 端口被安全组拦截。用 curl -vI https://app.example.com 看证书链,必要时用 openssl s_client -showcerts 确认中间证书是否完整。不要在公网客户端用 -k 绕过,那会掩盖证书链问题。

WebSocket 的 Upgrade 走 HTTPS 后仍可工作,ingress-nginx 需要设置 proxy-read-timeout 与 proxy-send-timeout(例如 3600),并确保后端协议为 HTTP。gRPC 则要在 Ingress 注解设置 nginx.ingress.kubernetes.io/backend-protocol: "GRPCS"(后端 TLS)或 "GRPC",否则 308 跳转后可能返回 502。改完后用 grpcurl -d '{}' app.example.com:443 服务/方法 验证。

会。证书过期后浏览器会拦截 HTTPS,308 跳转仍发生但用户看到 NET::ERR_CERT_DATE_INVALID。建议监控 certmanager_certificate_expiration_time_seconds,阈值设为 21 天;并确认 cert-manager 的 ClusterIssuer 账户 Secret 未被删除。Let's Encrypt 证书有效期 90 天,cert-manager 默认提前约 30 天续期。


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

内容审核

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