企业官网建设流程全解析

• 文档
• 教程
• 云原生

本文基于 Knative 官方文档docs/versioned/serving/encryption/system-internal-tls.md，讲解如何为 Knative Serving 开启system-internal-tls，使 Ingress-Controller、Activator 与 Queue-Proxy 等系统内部组件之间的流量全部走 TLS 加密。读者完成本文后，能够独立完成 cert-manager 集成配置、通过config-networkConfigMap 启用该特性、验证证书轮询与 TLS 服务启动日志，并理解 Knative 系统组件的信任链分发机制（trust-bundle）与 CA 轮换流程。

需要特别说明：Knative Serving 的加密特性cluster-local-domain-tls与system-internal-tls目前均处于实验状态（见文档内嵌的 encryption-notice 警告片段），生产使用前需谨慎评估。另外，system-internal-tls目前仅支持与 Kourier 作为网络层配合使用。

一、Knative Serving 加密的三大组成部分

要理解system-internal-tls的定位，先需要看 加密总览（docs/versioned/serving/encryption/encryption-overview.md）。Knative Serving 的加密被划分为相互独立的三部分，每部分可以使用不同的 CA 签发证书：

1. 集群外部入口 HTTPS：面向集群外域名（如myapp-<namespace>.example.com）的入口加密，证书通过 SNI 由 ingress-controller 的外部端点托管，见 外部域名加密配置；
2. 集群本地域名入口 HTTPS：面向集群内域名（如myapp.<namespace>.svc.cluster.local）的入口加密，证书同样由 ingress-controller 的集群内端点通过 SNI 托管，见 集群本地域名加密配置；
3. Knative 系统内部加密（即本文主题）：开启后，Knative 系统内部组件（Ingress-Controller、Activator、Queue-Proxy）会各自托管 TLS 端点，组件间连接使用 TLS 加密并基于特定的 SAN 集做身份校验。

总览文档同时指出一个边界：当前所有控制面流量（包括 Kubernetes PreStopHooks 与 metrics 等元数据）是不加密的，本文的加密范围仅覆盖数据面组件间的通信。

二、前置条件与 cert-manager 集成配置

2.1 前提要求

启用system-internal-tls需要满足以下条件：

• 已安装 Knative Serving，具体步骤参考 Knative 安装指南（docs/versioned/install/yaml-install/serving/install-serving-with-yaml.md）；
• 网络层使用 Kourier；
• 已安装并配置cert-manager（版本1.0.0及以上）及 Knative 的 cert-manager 集成，详见 cert-manager 安装文档（docs/versioned/install/installing-cert-manager.md）与 Knative cert-manager 集成配置（docs/versioned/serving/encryption/configure-certmanager-integration.md）。

集成文档中特别警告：必须确认 cert-manager 已安装，否则 Serving controller 无法正确启动。

2.2 三个 Issuer 引用

Knative 的 cert-manager 桥接组件定义了三个 issuer 引用，分别对应上述三种加密特性：

• issuerRef：为外部域名入口证书签发所用；
• clusterLocalIssuerRef：为集群本地域名入口证书签发所用；
• systemInternalIssuerRef：为 system-internal-tls 组件间证书签发所用。

system-internal-tls需要签发的 SAN 集合是固定的：

• kn-routing
• kn-user-<namespace>（<namespace>为每个存在/将创建 Knative Service 的命名空间）
• data-plane.knative.dev

由于这些 SAN 不是真实可解析的域名，ACME 协议（DNS01/HTTP01）无法完成验证，因此systemInternalIssuerRef必须指向一个能够直接签发这些证书的 issuer（例如基于 CA 的 issuer），而不能指向 ACME issuer。

2.3 示例：自签名 ClusterIssuer 配置

集成文档给出了一个自签名ClusterIssuer的完整示例（文档明确提示：自签名 issuer 不应直接用于生产环境，生产环境需为各用途规划不同的 CA 与信任分发方案）：

# 该 issuer 供 cert-manager 签发证书使用 apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: cluster-selfsigned-issuer spec: selfSigned: {} --- # 该 issuer 专供 Knative 使用，使用下方 Certificate 创建的 Secret 中存储的 CA apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: knative-selfsigned-issuer spec: ca: secretName: knative-selfsigned-ca --- # 该 Certificate 由 cluster-selfsigned-issuer 签发，CA 证书存储在 secret knative-selfsigned-ca 中 apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: knative-selfsigned-ca namespace: cert-manager # 若要用作 ClusterIssuer，secret 必须位于 cert-manager 命名空间 spec: secretName: knative-selfsigned-ca commonName: knative.dev usages: - server auth isCA: true issuerRef: kind: ClusterIssuer name: cluster-selfsigned-issuer

应用后确认可用性：

kubectl get clusterissuer cluster-selfsigned-issuer -o yaml kubectl get clusterissuer knative-selfsigned-issuer -o yaml

预期结果：两个 issuer 的Status.Conditions中应包含Ready=True。

随后在config-certmanagerConfigMap 中引用这些 issuer：

kubectl edit configmap config-certmanager -n knative-serving

在data段中添加如下字段：

apiVersion: v1 kind: ConfigMap metadata: name: config-certmanager namespace: knative-serving labels: networking.knative.dev/certificate-provider: cert-manager data: issuerRef: | kind: ClusterIssuer name: knative-selfsigned-issuer clusterLocalIssuerRef: | kind: ClusterIssuer name: knative-selfsigned-issuer systemInternalIssuerRef: | kind: ClusterIssuer name: knative-selfsigned-issuer

验证写入结果：

kubectl get configmap config-certmanager -n knative-serving -o yaml

三、启用 system-internal-tls

完成 cert-manager 集成后，通过在knative-serving命名空间的config-networkConfigMap 中设置system-internal-tls: Enabled来开启该特性。

1. 执行以下命令编辑config-networkConfigMap：

   kubectl edit configmap config-network -n knative-serving

2. 在data段下添加system-internal-tls: Enabled属性：

   apiVersion: v1 kind: ConfigMap metadata: name: config-network namespace: knative-serving data: ... system-internal-tls: Enabled ...

3. 重启 Knative 的 activator 与 controller 组件，使 Knative 的 cert-manager 集成开始工作：

   kubectl rollout restart deploy/activator -n knative-serving kubectl rollout restart deploy/controller -n knative-serving

配置完成后，Knative 在 Ingress-Controller、Activator 与 Queue-Proxy 之间将使用 TLS 通信。

四、验证加密是否生效

原文档给出的验证流程包含三步：

1. 部署一个 Knative Service；

2. 检查证书是否已创建并就绪，在目标 Service 所在命名空间执行：

   kubectl get kcert -n <your-knative-service-namespace>

3. 检查 Queue-Proxy 容器是否在启动时读取了证书：

   kubectl logs your-pod -n your-knative-service-namespace -c queue-proxy | grep -E 'certDir|Certificate|tls'

   预期日志形如以下四行（来自原文档的真实输出样例）：

   {"severity":"INFO","timestamp":"2024-01-03T07:07:32.892810888Z","logger":"queueproxy","caller":"certificate/watcher.go:62","message":"Starting to watch the following directories for changes{certDir 15 0 /var/lib/knative/certs <nil>} {keyDir 15 0 /var/lib/knative/certs <nil>}","commit":"86420f2-dirty","knative.dev/key":"first/helloworld-00001","knative.dev/pod":"helloworld-00001-deployment-75fbb7d488-qgmxx"} {"severity":"INFO","timestamp":"2024-01-03T07:07:32.89397512Z","logger":"queueproxy","caller":"certificate/watcher.go:131","message":"Certificate and/or key have changed on disk and were reloaded.","commit":"86420f2-dirty","knative.dev/key":"first/helloworld-00001","knative.dev/pod":"helloworld-00001-deployment-75fbb7d488-qgmxx"} {"severity":"INFO","timestamp":"2024-01-03T07:07:32.894232939Z","logger":"queueproxy","caller":"sharedmain/main.go:282","message":"Starting tls server admin:8022","commit":"86420f2-dirty","knative.dev/key":"first/helloworld-00001","knative.dev/pod":"helloworld-00001-deployment-75fbb7d488-qgmxx"} {"severity":"INFO","timestamp":"2024-01-03T07:07:32.894268548Z","logger":"queueproxy","caller":"sharedmain/main.go:282","message":"Starting tls server main:8112","commit":"86420f2-dirty","knative.dev/key":"first/helloworld-00001","knative.dev/pod":"helloworld-00001-deployment-75fbb7d488-qgmxx"}

   从这四行日志可以读出 system-internal-tls 在 Queue-Proxy 侧的实际行为：

   • Queue-Proxy 启动一个证书监控进程（对应 knative/serving 仓库中的pkg/queue/certificate/watcher.go），持续监视/var/lib/knative/certs目录下的证书（certDir）与密钥（keyDir）；
   • 检测到磁盘上证书或密钥发生变化后会重新加载（Certificate and/or key have changed on disk and were reloaded.），这意味着 cert-manager 轮换证书后 Queue-Proxy 无需重启即可热更新；
   • 最终在admin:8022与main:8112两个端口上分别启动 TLS 服务（对应 knative/serving 仓库中的sharedmain/main.go逻辑）。

五、信任（Trust）：Knative 组件如何信任签发 CA

这是本文最容易被忽略、但对系统长期稳定运行最关键的部分。

5.1 自动信任机制与官方建议

原文档给出的警告（原文逐字继承其要点）：Knative会自动信任签发证书所用的 CA——前提是 cert-manager 的 issuer 允许把 CA 直接放入证书Secret的ca.crt字段中。但无论该自动机制是否可用，集群管理员都应当始终显式提供 trust-bundle，具体做法见 cert-manager 集成的信任管理章节。这也是 cert-manager 官方文档强烈建议的做法，可避免证书轮换时出现问题。

5.2 通过 trust-bundle ConfigMap 显式分发信任

Knative 系统组件可以配置为一个或多个来自ConfigMap的 CA bundle 提供信任。组件会在其所在命名空间查找带标签networking.knative.dev/trust-bundle: "true"的 ConfigMap，并读取其中所有data键（键名不限），一个键可包含一个或多个 CA/中间证书；校验通过后它们会被加入 Knative 组件的信任存储。

需要放置 trust-bundle 的命名空间包括：

• knative-serving
• istio-system（使用 net-istio 时）
• kourier-system（使用 net-kourier 时，本特性当前即限定 Kourier）
• 每个运行 Knative Service 的命名空间

trust-bundle ConfigMap 示例（来自集成文档）：

apiVersion: v1 data: cacerts.pem: | -----BEGIN CERTIFICATE----- MIIDDTCCAfWgAwIBAgIQMQuip05h7NLQq2TB+j9ZmTANBgkqhkiG9w0BAQsFADAW MRQwEgYDVQQDEwtrbmF0aXZlLmRldjAeFw0yMzExMjIwOTAwNDhaFw0yNDAyMjAw OTAwNDhaMBYxFDASBgNVBAMTC2tuYXRpdmUuZGV2MIIBIjANBgkqhkiG9w0BAQEF AAOCAQ8AMIIBCgKCAQEA3clC3CV7sy0TpUKNuTku6QmP9z8JUCbLCPCLACCUc1zG FEokqOva6TakgvAntXLkB3TEsbdCJlNm6qFbbko6DBfX6rEggqZs40x3/T+KH66u 4PvMT3fzEtaMJDK/KQOBIvVHrKmPkvccUYK/qWY7rgBjVjjLVSJrCn4dKaEZ2JNr Fd0KNnaaW/dP9/FvviLqVJvHnTMHH5qyRRr1kUGTrc8njRKwpHcnUdauiDoWRKxo Zlyy+MhQfdbbyapX984WsDjCvrDXzkdGgbRNAf+erl6yUm6pHpQhyFFo/zndx6Uq QXA7jYvM2M3qCnXmaFowidoLDsDyhwoxD7WT8zur/QIDAQABo1cwVTAOBgNVHQ8B Af8EBAMCAgQwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDwYDVR0TAQH/BAUwAwEB/zAd BgNVHQ4EFgQU7p4VuECNOcnrP9ulOjc4J37Q2VUwDQYJKoZIhvcNAQELBQADggEB AAv26Vnk+ptQrppouF7yHV8fZbfnehpm07HIZkmnXO2vAP+MZJDNrHjy8JAVzXjt +OlzqAL0cRQLsUptB0btoJuw23eq8RXgJo05OLOPQ2iGNbAATQh2kLwBWd/CMg+V KJ4EIEpF4dmwOohsNR6xa/JoArIYH0D7gh2CwjrdGZr/tq1eMSL+uZcuX5OiE44A 2oXF9/jsqerOcH7QUMejSnB8N7X0LmUvH4jAesQgr7jo1JTOBs7GF6wb+U76NzFa 8ms2iAWhoplQ+EHR52wffWb0k6trXspq4O6v/J+nq9Ky3vC36so+G1ZFkMhCdTVJ ZmrBsSMWeT2l07qeei2UFRU= -----END CERTIFICATE----- kind: ConfigMap metadata: labels: networking.knative.dev/trust-bundle: "true" name: knative-bundle namespace: knative-serving

如果手动向所有命名空间分发 bundle 过于繁琐，可以使用 cert-manager 生态中的trust-manager自动分发 CA bundle。

5.3 CA 轮换期间保持零停机

轮换 CA 或中间证书期间，客户端需要同时信任新旧 CA/证书链，直到轮换完成。集成文档给出的完整轮换步骤如下：

1. 确认现有配置已正常运行；
2. 确认所有 Knative Service 持有相关证书且未过期；
3. 确认 CA（及完整链）未过期；
4. 将现有 CA和新 CA（及完整链）都加入 trust bundle（手动或通过 trust-manager）；
5. 重新配置 cert-manager 的ClusterIssuer或Issuer指向新 CA；
6. 等待所有旧证书过期并由 cert-manager 续期；
7. 此后所有证书均由新 CA 签发；
8. 预留一段宽限时间，确保所有组件都已拾取变更；
9. 从 trust bundle 中移除旧 CA。

六、相关文档索引

最后重申适用前提与限制：本流程要求Kourier 网络层、cert-manager ≥ 1.0.0，且system-internal-tls属于实验特性；控制面流量（PreStopHooks、metrics 等）不在加密范围内。

• 文档
• 教程
• 云原生