Traefik配置ingress.kubernetes.io/pass-tls-cert含义及证书传递失败咨询

1. 配置项的核心含义 #

ingress.kubernetes.io/pass-tls-cert 是Traefik针对Kubernetes Ingress的专属注解，作用是控制Traefik是否将接收到的TLS客户端证书信息转发给后端服务。当设置为true时，Traefik会把证书内容通过特定HTTP请求头传递到后端，让后端应用能够获取并使用这份证书的相关数据（比如验证用户身份、提取用户标识等）。

2. "Client"的定义与证书传递失败排查 #

这里的"Client"指终端用户 #

文档里提到的TLS 'Client'证书，绝对是指发起请求的终端用户（或客户端设备）提供的证书，而非Traefik自身的服务端证书。Traefik作为反向代理，在与客户端完成TLS握手时会接收客户端证书，开启这个配置后，就应该把这份用户证书转发给后端。

为什么设置true后还是传不了证书？试试这些排查步骤 #

如果已经开启注解但后端拿不到用户证书，大概率是配置环节有遗漏，你可以按顺序检查：

• 确认Traefik要求客户端提供证书
  首先，Traefik必须在TLS握手阶段主动要求客户端出示证书，否则根本没有证书可以转发。你需要在Ingress的TLS配置中开启客户端认证：

  spec:
    tls:
    - secretName: your-server-tls-secret
      options:
        name: client-auth-config
  

  对应的Traefik TLS options配置（动态配置）要设置clientAuth为RequireAndVerifyClientCert，并指定信任的CA证书：

  apiVersion: traefik.containo.us/v1alpha1
  kind: TLSOption
  metadata:
    name: client-auth-config
  spec:
    clientAuth:
      clientAuthType: RequireAndVerifyClientCert
      secretNames:
        - your-trusted-ca-secret
  

• 检查注解前缀是否匹配Traefik版本
  如果你用的是Traefik v2.x及以上版本，旧的ingress.kubernetes.io/前缀已经被弃用，需要改用traefik.ingress.kubernetes.io/前缀。比如：

  metadata:
    annotations:
      traefik.ingress.kubernetes.io/pass-tls-cert: "true"
  

  用错前缀的话，Traefik根本不会识别这个配置。

• 验证请求头是否到达后端
  开启配置后，Traefik会添加X-Forwarded-Tls-Client-Cert请求头，后端可以读取这个头获取证书的Base64编码PEM内容。你可以在后端打印所有请求头，确认这个字段是否存在。如果不存在，检查Traefik的日志，看是否有相关错误提示。

• 排查中间件是否拦截请求头
  如果Traefik配置了请求头过滤、修改类的中间件，可能会把X-Forwarded-Tls-Client-Cert头移除。检查你的Traefik中间件配置，确保没有针对这个头的拦截逻辑。

• 确认后端正确解析证书
  即使请求头存在，后端服务也需要正确解码证书内容（因为证书是Base64编码的PEM格式）。比如在Python中可以这样解析：

  import base64
  from cryptography import x509
  from cryptography.hazmat.backends import default_backend
  
  cert_header = request.headers.get('X-Forwarded-Tls-Client-Cert')
  if cert_header:
      # 解码Base64
      cert_pem = base64.b64decode(cert_header)
      # 解析X509证书
      cert = x509.load_pem_x509_certificate(cert_pem, default_backend())
      # 获取证书信息
      subject = cert.subject
  

内容的提问来源于stack exchange，提问作者kuramal