sigs.k8s.io/gateway-api@v1.0.0/site-src/guides/tls.md (about)

     1  # TLS Configuration
     2  
     3  Gateway API allow for a variety of ways to configure TLS. This document lays
     4  out various TLS settings and gives general guidelines on how to use them
     5  effectively.
     6  
     7  !!! info "Experimental Channel"
     8  
     9      The `TLSRoute` resource described below is currently only included in the
    10      "Experimental" channel of Gateway API. For more information on release
    11      channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
    12  
    13  ## Client/Server and TLS
    14  
    15  ![overview](/images/tls-overview.svg)
    16  
    17  For Gateways, there are two connections involved:
    18  
    19  - **downstream**: This is the connection between the client and the Gateway.
    20  - **upstream**: This is the connection between the Gateway and backend resources
    21     specified by routes. These backend resources will usually be Services.
    22  
    23  With Gateway API, TLS configuration of downstream and
    24  upstream connections is managed independently.
    25  
    26  Depending on the Listener Protocol, different TLS modes and Route types are supported.
    27  
    28  Listener Protocol | TLS Mode | Route Type Supported
    29  --- | --- | ---
    30  TLS | Passthrough | TLSRoute
    31  TLS | Terminate | TCPRoute
    32  HTTPS | Terminate | HTTPRoute
    33  
    34  Please note that in case of `Passthrough` TLS mode, no TLS settings take
    35  effect as the TLS session from the client is NOT terminated at the Gateway.
    36  The rest of the document assumes that TLS is being terminated at the Gateway,
    37  which is the default setting.
    38  
    39  ## Downstream TLS
    40  
    41  Downstream TLS settings are configured using listeners at the Gateway level.
    42  
    43  ### Listeners and TLS
    44  
    45  Listeners expose the TLS setting on a per domain or sub-domain basis.
    46  TLS settings of a listener are applied to all domains that satisfy the
    47  `hostname` criteria.
    48  
    49  In the following example, the Gateway serves the TLS certificate
    50  defined in the `default-cert` Secret resource for all requests.
    51  Although, the example refers to HTTPS protocol, one can also use the same
    52  feature for TLS-only protocol along with TLSRoutes.
    53  
    54  ```yaml
    55  listeners:
    56  - protocol: HTTPS # Other possible value is `TLS`
    57    port: 443
    58    tls:
    59      mode: Terminate # If protocol is `TLS`, `Passthrough` is a possible mode
    60      certificateRefs:
    61      - kind: Secret
    62        group: ""
    63        name: default-cert
    64  ```
    65  
    66  ### Examples
    67  
    68  #### Listeners with different certificates
    69  
    70  In this example, the Gateway is configured to serve the `foo.example.com` and
    71  `bar.example.com` domains. The certificate for these domains is specified
    72  in the Gateway.
    73  
    74  ```yaml
    75  {% include 'standard/tls-basic.yaml' %}
    76  ```
    77  
    78  #### Wildcard TLS listeners
    79  
    80  In this example, the Gateway is configured with a wildcard certificate for
    81  `*.example.com` and a different certificate for `foo.example.com`.
    82  Since a specific match takes priority, the Gateway will serve
    83  `foo-example-com-cert` for requests to `foo.example.com` and
    84  `wildcard-example-com-cert` for all other requests.
    85  
    86  ```yaml
    87  {% include 'standard/wildcard-tls-gateway.yaml' %}
    88  ```
    89  
    90  #### Cross namespace certificate references
    91  
    92  In this example, the Gateway is configured to reference a certificate in a
    93  different namespace. This is allowed by the ReferenceGrant created in the
    94  target namespace. Without that ReferenceGrant, the cross-namespace reference
    95  would be invalid.
    96  
    97  ```yaml
    98  {% include 'standard/tls-cert-cross-namespace.yaml' %}
    99  ```
   100  
   101  ## Extensions
   102  
   103  Gateway TLS configurations provides an `options` map to add additional TLS
   104  settings for implementation-specific features. Some examples of features that
   105  could go in here would be TLS version restrictions, or ciphers to use.