[zh] sync secure-ingress and kubernetes-ingress (#13345)

* [zh] sync /traffic-management/ingress/secure-ingress/ * make lint happy
2023-06-12 10:34:51 +08:00 · 2023-06-12 10:34:51 +08:00 · a036568852
parent 21a7019554
commit a036568852
2 changed files with 74 additions and 40 deletions
--- a/content/zh/docs/tasks/traffic-management/ingress/kubernetes-ingress/index.md
+++ b/content/zh/docs/tasks/traffic-management/ingress/kubernetes-ingress/index.md
@ -7,19 +7,24 @@ owner: istio/wg-networking-maintainers
 test: yes
 ---

-此任务描述如何使用 [Kubernetes Ingress](https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/) 为 Istio 配置入口网关以暴露服务网格集群内的服务。
+此任务描述如何使用 [Kubernetes Ingress](https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/)
+为 Istio 配置入口网关以暴露服务网格集群内的服务。

 {{< tip >}}
-建议使用 [Gateway](/zh/docs/tasks/traffic-management/ingress/ingress-control/) 而不是 Ingress 来利用 Istio 提供的完整功能集，例如丰富的流量管理和安全功能。
+建议使用 [Gateway](/zh/docs/tasks/traffic-management/ingress/ingress-control/)
+而不是 Ingress 来利用 Istio 提供的完整功能集，例如丰富的流量管理和安全功能。
 {{< /tip >}}

 ## 准备工作{#before-you-begin}

-请按照[入口网关任务](/zh/docs/tasks/traffic-management/ingress/ingress-control/)中的[准备工作](/zh/docs/tasks/traffic-management/ingress/ingress-control/#before-you-begin)、[确定 Ingress IP 和端口](/zh/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)的说明进行操作。
+请按照[入口网关任务](/zh/docs/tasks/traffic-management/ingress/ingress-control/)中的
+[准备工作](/zh/docs/tasks/traffic-management/ingress/ingress-control/#before-you-begin)、
+[确定 Ingress IP 和端口](/zh/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)的说明进行操作。

 ## 使用 Ingress 资源配置入口网关 {#configuring-ingress-using-an-ingress-resource}

-[Kubernetes Ingress](https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/) 公开了从集群外到集群内服务的 HTTP 和 HTTPS 路由。
+[Kubernetes Ingress](https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/)
+公开了从集群外到集群内服务的 HTTP 和 HTTPS 路由。

 让我们看看如何在端口 80 上配置 `Ingress` 以实现 HTTP 流量。

@ -50,7 +55,7 @@ test: yes

    需要使用 `kubernetes.io/ingress.class` 注解来告知 Istio 网关控制器它应该处理此 `Ingress`，否则它将被忽略。

-1.  使用 _curl_ 访问 _httpbin_ 服务：
+1.  使用 **curl** 访问 **httpbin** 服务：

    {{< text bash >}}
    $ curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST:$INGRESS_PORT/status/200"
@ -59,7 +64,8 @@ test: yes
    ...
    {{< /text >}}

-    注意，您需要使用 `-H` 标志将 _Host_ 的 HTTP header 设置为 "httpbin.example.com"，因为 `Ingress` 中已经配置为处理访问 "httpbin.example.com" 的请求，但是在测试环境中，该 host 并没有相应的 DNS 绑定。
+    注意，您需要使用 `-H` 标志将 **Host** 的 HTTP 头设置为 "httpbin.example.com"，
+    因为 `Ingress` 中已经配置为处理访问 "httpbin.example.com" 的请求，但是在测试环境中，该 host 并没有相应的 DNS 绑定。

 1.  访问未显式公开的其他 URL 时，将返回 HTTP 404 错误：

@ -73,7 +79,9 @@ test: yes

 ### TLS {#TLS}

-`Ingress` 支持[指定 TLS 设置](https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/#tls)。Istio 支持此功能，但是引用的 `Secret` 必须存在于 `istio-ingressgateway` 部署的命名空间（通常是 `istio-system`）中。[cert-manager](/zh/docs/ops/integrations/certmanager/) 可用于生成这些证书。
+`Ingress` 支持[指定 TLS 设置](https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/#tls)。
+Istio 支持此功能，但是引用的 `Secret` 必须存在于 `istio-ingressgateway` 部署的命名空间（通常是 `istio-system`）中。
+[cert-manager](/zh/docs/ops/integrations/certmanager/) 可用于生成这些证书。

 ### 指定路径类型{#specifying-path-type}

@ -83,7 +91,8 @@ Istio 默认路径类型为精确匹配，除非路径以 `/*` 或 `.*` 结尾

 ### 指定 `IngressClass` {#specifying-ingress-class}

-在 Kubernetes 1.18 中，添加了新资源 `IngressClass`，以替换 Ingress 资源上的 `kubernetes.io/ingress.class` 注解。如果使用此资源，则需要将 `controller` 字段设置为 `istio.io/ingress-controller`。例如：
+在 Kubernetes 1.18 中，添加了新资源 `IngressClass`，以替换 Ingress 资源上的 `kubernetes.io/ingress.class` 注解。
+如果使用此资源，则需要将 `controller` 字段设置为 `istio.io/ingress-controller`。例如：

 {{< text yaml >}}
 apiVersion: networking.k8s.io/v1
--- a/content/zh/docs/tasks/traffic-management/ingress/secure-ingress/index.md
+++ b/content/zh/docs/tasks/traffic-management/ingress/secure-ingress/index.md
@ -10,7 +10,8 @@ owner: istio/wg-networking-maintainers
 test: yes
 ---

-[Ingress 流量控制任务](/zh/docs/tasks/traffic-management/ingress/ingress-control)描述了如何配置入口网关以向外部公开 HTTP 服务。此任务描述如何使用 TLS 或 mTLS 公开安全的 HTTPS 服务。
+[Ingress 流量控制任务](/zh/docs/tasks/traffic-management/ingress/ingress-control)描述了如何配置入口网关以向外部公开
+HTTP 服务。此任务描述如何使用 TLS 或 mTLS 公开安全的 HTTPS 服务。

 {{< boilerplate gateway-api-support >}}

@ -31,11 +32,13 @@ test: yes
    curl 7.54.0 (x86_64-apple-darwin17.0) libcurl/7.54.0 LibreSSL/2.0.20 zlib/1.2.11 nghttp2/1.24.0
    {{< /text >}}

-    如果上述命令输出的是如图所示的 LibreSSL 版本，则 `curl` 命令应按照此任务中的说明正确运行。否则，请尝试使用 `curl` 的其他实现，例如在 Linux 机器上。
+    如果上述命令输出的是如图所示的 LibreSSL 版本，则 `curl` 命令应按照此任务中的说明正确运行。
+    否则，请尝试使用 `curl` 的其他实现，例如在 Linux 机器上。

 ## 生成客户端和服务器证书和密钥{#generate-client-and-server-certificates-and-keys}

-对于此任务，您可以使用自己喜欢的工具来生成证书和密钥。下面的命令使用 [openssl](https://man.openbsd.org/openssl.1)。
+对于此任务，您可以使用自己喜欢的工具来生成证书和密钥。
+下面的命令使用 [openssl](https://man.openbsd.org/openssl.1)。

 1.  创建用于服务签名的根证书和私钥：

@ -94,7 +97,7 @@ example.com.key         httpbin.example.com.csr

 ### 配置单机 TLS 入口网关 {#configure-a-tls-ingress-gateway-for-a-single-host}

-1.  为 Ingress Gateway 创建 Secret:
+1.  为入口网关创建 Secret:

    {{< text bash >}}
    $ kubectl create -n istio-system secret tls httpbin-credential \
@ -108,7 +111,8 @@ example.com.key         httpbin.example.com.csr

 {{< tab name="Istio classic" category-value="istio-classic" >}}

-首先，使用 `servers:` 为 443 端口定义一个网关，并将 `credentialName` 的值设置为 `httpbin-credential`。该值与 Secret 的名称相同。TLS 模式的值应为 `SIMPLE`。
+首先，使用 `servers:` 为 443 端口定义一个网关，并将 `credentialName` 的值设置为 `httpbin-credential`。
+该值与 Secret 的名称相同。TLS 模式的值应为 `SIMPLE`。

 {{< text bash >}}
 $ cat <<EOF | kubectl apply -f -
@ -159,7 +163,8 @@ spec:
 EOF
 {{< /text >}}

-最后，按照[这些说明](/zh/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)设置访问网关的 `INGRESS_HOST` 和 `SECURE_INGRESS_PORT` 变量。
+最后，按照[这些说明](/zh/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)
+设置访问网关的 `INGRESS_HOST` 和 `SECURE_INGRESS_PORT` 变量。

 {{< /tab >}}

@ -186,7 +191,7 @@ spec:
      certificateRefs:
      - name: httpbin-credential
    allowedRoutes:
-        namespaces:
+      namespaces:
        from: Selector
        selector:
          matchLabels:
@ -206,8 +211,8 @@ spec:
  parentRefs:
  - name: mygateway
    namespace: istio-system
-    hostnames: ["httpbin.example.com"]
-    rules:
+  hostnames: ["httpbin.example.com"]
+  rules:
  - matches:
    - path:
        type: PathPrefix
@ -215,7 +220,7 @@ spec:
    - path:
        type: PathPrefix
        value: /delay
-        backendRefs:
+    backendRefs:
    - name: httpbin
      port: 8000
 EOF
@ -297,7 +302,8 @@ $ export SECURE_INGRESS_PORT=$(kubectl get gtw mygateway -n istio-system -o json

 ### 为多个主机配置 TLS 入口网关 {#configure-a-TLS-ingress-gateway-for-multiple-hosts}

-您可以为多个主机（例如 `httpbin.example.com` 和 `helloworld-v1.example.com`）配置入口网关。入口网关配置有与每个主机相对应的唯一凭据。
+您可以为多个主机（例如 `httpbin.example.com` 和 `helloworld-v1.example.com`）配置入口网关。
+入口网关配置有与每个主机相对应的唯一凭据。

 1.  通过删除并使用原始证书和密钥重新创建 Secret 来恢复上一个示例中的 `httpbin` 凭据：

@ -327,7 +333,8 @@ $ export SECURE_INGRESS_PORT=$(kubectl get gtw mygateway -n istio-system -o json

 {{< tab name="Istio classic" category-value="istio-classic" >}}

-为 443 端口定义一个具有两个服务器部分的网关。将每个端口上的 `credentialName` 值分别设置为 `httpbin-credential` 和 `helloworld-credential`。将 TLS 模式设置为 `SIMPLE`。
+为 443 端口定义一个具有两个服务器部分的网关。将每个端口上的 `credentialName`
+值分别设置为 `httpbin-credential` 和 `helloworld-credential`。将 TLS 模式设置为 `SIMPLE`。

 {{< text bash >}}
 $ cat <<EOF | kubectl apply -f -
@ -339,7 +346,6 @@ spec:
  selector:
    istio: ingressgateway # use istio default ingress gateway
  servers:
-
  - port:
      number: 443
      name: https-httpbin
@ -390,7 +396,8 @@ EOF

 {{< tab name="Gateway API" category-value="gateway-api" >}}

-在 443 端口上配置具有两个监听器的 `Gateway`。将每个端口的监听器的 `certificateRefs` 的名字分别设置为 `httpbin-credential` 和 `helloworld-credential`。
+在 443 端口上配置具有两个监听器的 `Gateway`。将每个端口的监听器的 `certificateRefs`
+的名字分别设置为 `httpbin-credential` 和 `helloworld-credential`。

 {{< text bash >}}
 $ cat <<EOF | kubectl apply -f -
@ -402,7 +409,6 @@ metadata:
 spec:
  gatewayClassName: istio
  listeners:
-
  - name: https-httpbin
    hostname: "httpbin.example.com"
    port: 443
@ -411,8 +417,8 @@ spec:
      mode: Terminate
      certificateRefs:
      - name: httpbin-credential
-        allowedRoutes:
-        namespaces:
+    allowedRoutes:
+      namespaces:
        from: Selector
        selector:
          matchLabels:
@ -426,7 +432,7 @@ spec:
      certificateRefs:
      - name: helloworld-credential
    allowedRoutes:
-        namespaces:
+      namespaces:
        from: Selector
        selector:
          matchLabels:
@ -446,13 +452,13 @@ spec:
  parentRefs:
  - name: mygateway
    namespace: istio-system
-    hostnames: ["helloworld.example.com"]
-    rules:
+  hostnames: ["helloworld.example.com"]
+  rules:
  - matches:
    - path:
        type: Exact
        value: /hello
-        backendRefs:
+    backendRefs:
    - name: helloworld
      port: 5000
 EOF
@ -493,7 +499,8 @@ EOF

 您可以扩展网关的定义以支持[双向 TLS](https://en.wikipedia.org/wiki/Mutual_authentication)。

-1. 通过删除其 Secret 并创建一个新的来更改入口网关的凭据。服务器使用 CA 证书来验证其客户端，我们必须使用名称 `cacert` 来持有 CA 证书。
+1. 通过删除其 Secret 并创建一个新的来更改入口网关的凭据。服务器使用 CA
+   证书来验证其客户端，我们必须使用名称 `cacert` 来持有 CA 证书。

    {{< text bash >}}
    $ kubectl -n istio-system delete secret httpbin-credential
@ -503,6 +510,16 @@ EOF
      --from-file=ca.crt=example_certs1/example.com.crt
    {{< /text >}}

+    {{< tip >}}
+
+    {{< boilerplate crl-tip >}}
+
+    凭据也可以包括 [OCSP Staple](https://datatracker.ietf.org/doc/html/rfc6961)
+    使用参数 `--from-file=tls.ocsp-staple=/some/path/to/your-ocsp-staple.pem` 指定的
+    `tls.ocsp-staple` 作为键名。
+
+    {{< /tip >}}
+
 1. 配置入口网关：

 {{< tabset category-name="config-api" >}}
@ -537,7 +554,8 @@ EOF

 {{< tab name="Gateway API" category-value="gateway-api" >}}

-因为 Kubernetes Gateway API 目前不支持 [Gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.Gateway) 中的双向 TLS 终止，所以我们使用 Istio 特定的选项 `gateway.istio.io/tls-terminate-mode: MUTUAL` 来配置它：
+因为 Kubernetes Gateway API 目前不支持 [Gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.Gateway)
+中的双向 TLS 终止，所以我们使用 Istio 特定的选项 `gateway.istio.io/tls-terminate-mode: MUTUAL` 来配置它：

 {{< text bash >}}
 $ cat <<EOF | kubectl apply -f -
@ -549,7 +567,6 @@ metadata:
 spec:
  gatewayClassName: istio
  listeners:
-
  - name: https
    hostname: "httpbin.example.com"
    port: 443
@ -558,10 +575,10 @@ spec:
      mode: Terminate
      certificateRefs:
      - name: httpbin-credential
-        options:
+      options:
        gateway.istio.io/tls-terminate-mode: MUTUAL
-        allowedRoutes:
-        namespaces:
+    allowedRoutes:
+      namespaces:
        from: Selector
        selector:
          matchLabels:
@ -618,12 +635,15 @@ Istio 支持读取几种不同的 Secret 格式，以支持与各种工具的集

 * 带有 `tls.key` 和 `tls.crt` 的 TLS Secret，如上所述。对于双向 TLS，`ca.crt` 可以作为密钥。
 * 带有 `key` 和 `cert` 键的通用 Secret。对于双向 TLS，`cacert` 可以作为密钥。
-* 带有 `key` 和 `cert` 键的通用 Secret。对于双向 TLS，名为 `<secret>-cacert` 的带有 `cacert` 键的通用 Secret。例如，`httpbin-credential` 有 `key` 和 `cert`，`httpbin-credential-cacert` 有 `cacert`。
+* 带有 `key` 和 `cert` 键的通用 Secret。对于双向 TLS，名为 `<secret>-cacert` 的带有 `cacert` 键的通用 Secret。
+  例如，`httpbin-credential` 有 `key` 和 `cert`，`httpbin-credential-cacert` 有 `cacert`。
 * `cacert` 键值可以是一个 CA 捆绑包，由串联的各个 CA 证书组成。

 ### SNI 路由 {#sni-routing}

-HTTPS `Gateway` 将在转发请求之前对其配置的主机执行 [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) 匹配，这可能会导致某些请求失败。有关详细信息，请参阅[配置 SNI 路由](/zh/docs/ops/common-problems/network-issues/#configuring-sni-routing-when-not-sending-sni)。
+HTTPS `Gateway` 将在转发请求之前对其配置的主机执行 [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication)
+匹配，这可能会导致某些请求失败。有关详细信息，
+请参阅[配置 SNI 路由](/zh/docs/ops/common-problems/network-issues/#configuring-sni-routing-when-not-sending-sni)。

 ## 问题排查 {#troubleshooting}

@ -648,7 +668,8 @@ HTTPS `Gateway` 将在转发请求之前对其配置的主机执行 [SNI](https:
    $ kubectl logs -n istio-system <gateway-service-pod>
    {{< /text >}}

-*   如果使用 macOS，请验证您使用的是使用 [LibreSSL](http://www.libressl.org/) `curl` 库编译的，如[准备工作](#before-you-begin)部分中所述。
+*   如果使用 macOS，请验证您使用的是使用 [LibreSSL](http://www.libressl.org/) `curl`
+    库编译的，如[准备工作](#before-you-begin)部分中所述。

 *   验证已在 `istio-system` 命名空间中成功创建 Secret：

@ -656,7 +677,7 @@ HTTPS `Gateway` 将在转发请求之前对其配置的主机执行 [SNI](https:
    $ kubectl -n istio-system get secrets
    {{< /text >}}

-    `httpbin-credential` 和 `helloworld-credential`  应当显示在 Secret 列表中。
+    `httpbin-credential` 和 `helloworld-credential` 应当显示在 Secret 列表中。

 *   检查日志以验证入口网关代理已将密钥/证书对推送到入口网关：

@ -664,7 +685,11 @@ HTTPS `Gateway` 将在转发请求之前对其配置的主机执行 [SNI](https:
    $ kubectl logs -n istio-system <gateway-service-pod>
    {{< /text >}}

-    日志应显示 `httpbin-credential`  Secret 已添加。如果使用双向  TLS，那么 `httpbin-credential-cacert`  Secret 也应该出现。验证日志显示网关代理接收到来自入口网关的 SDS 请求，资源的名称是 `httpbin-credential`，并且入口网关获得了密钥/证书对。如果使用双向 TLS，日志应显示密钥/证书已发送到入口网关，网关代理收到带有 `httpbin-credential-cacert` 资源名称的 SDS 请求，并且入口网关获得了根证书。
+    日志应显示 `httpbin-credential` Secret 已添加。如果使用双向 TLS，
+    那么 `httpbin-credential-cacert` Secret 也应该出现。
+    验证日志显示网关代理接收到来自入口网关的 SDS 请求，资源的名称是 `httpbin-credential`，
+    并且入口网关获得了密钥/证书对。如果使用双向 TLS，日志应显示密钥/证书已发送到入口网关，
+    网关代理收到带有 `httpbin-credential-cacert` 资源名称的 SDS 请求，并且入口网关获得了根证书。

 ## 清理 {#cleanup}