配置客户端与网关之间的 mTLS

双向 TLS（mTLS）要求客户端与网关相互验证身份。本指南配置网关信任客户端 CA、出示服务端证书，并拒绝未提供受信任证书的客户端。

前置条件

完成设置 Ingress Controller 和网关。

在网关上启用 SSL

确保你的网关已启用 SSL。

APISIX 网关
API7 网关

下列命令使用 --reuse-values 保留当前 Helm release 的其他值：

helm upgrade apisix apisix/apisix \
  --reuse-values \
  --set "apisix.ssl.enabled=true" \
  --set "apisix.ssl.containerPort=9443"

默认情况下，API7 网关已在容器端口 9443 和 Service 端口 443 上启用 SSL，因此此步骤无需额外配置。

生成证书和密钥

生成证书颁发机构（CA）的密钥和证书：

openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 36500 -sha256 \
  -key ca.key \
  -out ca.crt \
  -subj "/CN=MyTestCA" \
  -extensions v3_ca \
  -config <(printf "[req]\ndistinguished_name=req\n[ v3_ca ]\nbasicConstraints=critical,CA:TRUE\nkeyUsage=critical,keyCertSign,cRLSign\nsubjectKeyIdentifier=hash\nauthorityKeyIdentifier=keyid:always,issuer")

生成服务端密钥和证书签名请求（CSR）：

openssl genrsa -out server.key 2048
openssl req -new -sha256 \
  -key server.key \
  -out server.csr \
  -subj "/CN=test.com"

使用 CA 证书对服务端 CSR 进行签名，生成服务端证书：

openssl x509 -req -days 36500 -sha256 \
  -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt \
  -extensions v3_req \
  -extfile <(printf "[v3_req]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\nsubjectAltName=DNS:test.com")

为客户端生成密钥和证书签名请求（CSR）：

openssl genrsa -out client.key 2048
openssl req -new -sha256 \
  -key client.key \
  -out client.csr \
  -subj "/CN=CLIENT"

使用 CA 证书对客户端 CSR 进行签名，生成客户端证书：

openssl x509 -req -days 36500 -sha256 \
  -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt \
  -extensions v3_req \
  -extfile <(printf "[v3_req]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=clientAuth")

为网关配置 mTLS

Gateway API
APISIX CRD

创建服务端证书 Secret 和包含客户端 CA 证书的 ConfigMap。Gateway API 从 ca.crt 键读取 CA 证书：

kubectl create secret tls test-mtls-secret \
  --cert=server.crt \
  --key=server.key \
  --namespace=aic

kubectl create configmap test-client-ca \
  --from-file=ca.crt=ca.crt \
  --namespace=aic

创建一个要求客户端出示由该 CA 签发证书的 Gateway。spec.tls.frontend.default 会将验证配置应用到所有 HTTPS 监听器，除非监听器端口在 spec.tls.frontend.perPort 下另有配置：

mtls-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: apisix
  namespace: aic
spec:
  gatewayClassName: apisix
  tls:
    frontend:
      default:
        validation:
          caCertificateRefs:
          - group: ""
            kind: ConfigMap
            name: test-client-ca
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: test.com
    tls:
      mode: Terminate
      certificateRefs:
      - group: ""
        kind: Secret
        name: test-mtls-secret
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

应用配置：

kubectl apply -f mtls-gateway.yaml

作为实现特定扩展，Ingress Controller 也接受 caCertificateRefs 中的 Secret。跨命名空间的 CA 引用需要 ReferenceGrant。不支持 AllowInsecureFallback，因为网关不能接受未提供证书或证书验证失败的客户端。

创建两个 Kubernetes Secret：

kubectl create secret tls test-mtls-secret \
  --cert=server.crt \
  --key=server.key \
  --namespace=aic

kubectl create secret generic test-ca-secret \
  --from-file=cert=ca.crt \
  --namespace=aic

创建 Kubernetes manifest 文件，定义 mTLS 配置：

mtls.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixTls
metadata:
  namespace: aic
  name: test-mtls
spec:
  ingressClassName: apisix
  hosts:
    - test.com
  secret:
    name: test-mtls-secret
    namespace: aic
  client:
    caSecret:
      name: test-ca-secret
      namespace: aic
    depth: 1

将配置应用到集群：

kubectl apply -f mtls.yaml

创建路由

Gateway API
APISIX CRD

创建 ExternalName Service 和 HTTPRoute，将 /ip 请求转发到 httpbin.org：

httpbin-route.yaml
apiVersion: v1
kind: Service
metadata:
  name: httpbin-external-domain
  namespace: aic
spec:
  type: ExternalName
  externalName: httpbin.org
  ports:
  - name: http
    port: 80
    appProtocol: http
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-ip
  namespace: aic
spec:
  parentRefs:
  - name: apisix
    sectionName: https
  hostnames:
  - test.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /ip
    backendRefs:
    - name: httpbin-external-domain
      port: 80

应用配置：

kubectl apply -f httpbin-route.yaml

创建一个示例路由，将路径为 /ip 的所有请求转发到上游服务 httpbin.org：

httpbin-route.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: httpbin-ip
spec:
  ingressClassName: apisix
  http:
    - name: httpbin-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain

将配置应用到集群：

kubectl apply -f httpbin-route.yaml

验证

如需验证客户端与网关之间的 mTLS，先将网关的 SSL 端口转发到本地：

kubectl port-forward svc/<your-gateway-svc-name> 9443:443 &

使用客户端证书

由于证书对 test.com 有效，应使用 test.com 作为网关域名。携带客户端证书向路由发送请求：

curl -iv --cacert ca.crt \
  --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" \
  --cert client.crt --key client.key

类似如下的 mTLS 握手过程表示客户端与网关之间的 mTLS 已启用：

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* Connected to test.com (127.0.0.1) port 9443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*  CAfile: ca.crt
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Request CERT (13):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Certificate (11):
* TLSv1.3 (OUT), TLS handshake, CERT verify (15):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
...
>
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* old SSL session ID is stale, removing
* Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
< HTTP/2 200
HTTP/2 200
...

请注意，网关和客户端已在握手期间成功验证彼此的证书并建立连接。

不使用客户端证书

向 https://test.com:9443/ip 发送请求，但不携带客户端证书：

curl -iv --cacert ca.crt \
  --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip"

失败的 mTLS 握手类似如下：

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* Connected to test.com (127.0.0.1) port 9443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*  CAfile: ca.crt
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Request CERT (13):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Certificate (11):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
...
* TLSv1.3 (IN), TLS alert, unknown (628):
* OpenSSL SSL_read: error:1409445C:SSL routines:ssl3_read_bytes:tlsv13 alert certificate required, errno 0
* Failed receiving HTTP2 data
* OpenSSL SSL_write: SSL_ERROR_ZERO_RETURN, errno 0
* Failed sending HTTP2 data
* Connection #0 to host test.com left intact

由于缺少客户端证书，握手失败。

前置条件​

在网关上启用 SSL​

生成证书和密钥​

为网关配置 mTLS​

创建路由​

验证​

使用客户端证书​

不使用客户端证书​