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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。