sigs.k8s.io/gateway-api@v1.0.0/geps/gep-851.md (about)

     1  # GEP-851: Allow Multiple Certificate Refs per Gateway Listener
     2  
     3  * Issue: [#851](https://github.com/kubernetes-sigs/gateway-api/issues/851)
     4  * Status: Standard
     5  
     6  ## TLDR
     7  
     8  Replace `CertificateRef` field with a `CertificateRefs` field in Gateway
     9  Listeners.
    10  
    11  ## Goals
    12  
    13  Provide a path for implementations to support:
    14  
    15  * RSA and ECDSA certs on the same Listener.
    16  * Referencing certificates for different hostnames from the same Listener (maybe
    17    as part of a self-service TLS approach).
    18  * Including new and old certificates as part of renewal process.
    19  * Certificate pinning: enable implementations that require certain certificates
    20    for legacy clients while exposing a "normal" certificate to non-legacy
    21    clients.
    22  
    23  ## Non-Goals
    24  
    25  * Define how implementations should support these features. Many implementations
    26    have limited control as far as how certs are handled. Some implementations
    27    just pass certs directly to the dataplane and rely on that implementation
    28    specific behavior to determine which certs are used for a given request. That
    29    makes it difficult to define any truly portable handling of multiple
    30    certificates.
    31  
    32  ## Introduction
    33  
    34  As described above, there are a number of potential use cases for attaching
    35  multiple certificates to a Gateway Listener. The most straightforward reason for
    36  that involves attaching RSA and ECDSA certs. Although this is not a very common
    37  use case, it is a clearly understood and broadly supported example of why this
    38  change would be helpful. This change will enable implementations to support
    39  these more advanced use cases while still providing a portable core.
    40  
    41  ## API
    42  
    43  The `CertificateRef` field in `GatewayTLSConfig` would be replaced with the
    44  following `CertificateRefs` field:
    45  
    46  ```go
    47      // CertificateRefs contains a series of references to Kubernetes objects that
    48      // contains TLS certificates and private keys. These certificates are used to
    49      // establish a TLS handshake for requests that match the hostname of the
    50      // associated listener.
    51      //
    52      // A single CertificateRef to a Kubernetes Secret has "Core" support.
    53      // Implementations MAY choose to support attaching multiple certificates to
    54      // a Listener, but this behavior is implementation-specific.
    55      //
    56      // References to a resource in different namespace are invalid UNLESS there
    57      // is a ReferenceGrant in the target namespace that allows the certificate
    58      // to be attached. If a ReferenceGrant does not allow this reference, the
    59      // "ResolvedRefs" condition MUST be set to False for this listener with the
    60      // "InvalidCertificateRef" reason.
    61      //
    62      // This field is required to have at least one element when the mode is set
    63      // to "Terminate" (default) and is optional otherwise.
    64      //
    65      // CertificateRefs can reference to standard Kubernetes resources, i.e.
    66      // Secret, or implementation-specific custom resources.
    67      //
    68      // Support: Core - A single reference to a Kubernetes Secret
    69      //
    70      // Support: Implementation-specific (More than one reference or other resource types)
    71      //
    72      // +optional
    73      // +kubebuilder:validation:MaxItems=64
    74      CertificateRefs []*SecretObjectReference `json:"certificateRefs,omitempty"`
    75  ```
    76  
    77  ## Alternatives
    78  
    79  N/A