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
8Replace `CertificateRef` field with a `CertificateRefs` field in Gateway
9Listeners.
10
11## Goals
12
13Provide 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
34As described above, there are a number of potential use cases for attaching
35multiple certificates to a Gateway Listener. The most straightforward reason for
36that involves attaching RSA and ECDSA certs. Although this is not a very common
37use case, it is a clearly understood and broadly supported example of why this
38change would be helpful. This change will enable implementations to support
39these more advanced use cases while still providing a portable core.
40
41## API
42
43The `CertificateRef` field in `GatewayTLSConfig` would be replaced with the
44following `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
79N/A
View as plain text