xds: define precedence between TLS cert fields (#33749)

Signed-off-by: Mark D. Roth <roth@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 686d7d9d0339e3909e677d8aaee426eec8a30cd5

envoy/extensions/transport_sockets/tls/v3/common.proto

@@ -378,16 +378,13 @@ message CertificateValidationContext {
   // can be treated as trust anchor as well. It allows verification with building valid partial chain instead
   // of a full chain.
   //
-  // Only one of ``trusted_ca`` and ``ca_certificate_provider_instance`` may be specified.
-  //
-  // [#next-major-version: This field and watched_directory below should ideally be moved into a
-  // separate sub-message, since there's no point in specifying the latter field without this one.]
+  // If ``ca_certificate_provider_instance`` is set, it takes precedence over ``trusted_ca``.
   config.core.v3.DataSource trusted_ca = 1
       [(udpa.annotations.field_migrate).oneof_promotion = "ca_cert_source"];
 
   // Certificate provider instance for fetching TLS certificates.
   //
-  // Only one of ``trusted_ca`` and ``ca_certificate_provider_instance`` may be specified.
+  // If set, takes precedence over ``trusted_ca``.
   // [#not-implemented-hide:]
   CertificateProviderPluginInstance ca_certificate_provider_instance = 13
       [(udpa.annotations.field_migrate).oneof_promotion = "ca_cert_source"];

envoy/extensions/transport_sockets/tls/v3/tls.proto

@@ -248,11 +248,8 @@ message CommonTlsContext {
   // :ref:`Multiple TLS certificates <arch_overview_ssl_cert_select>` can be associated with the
   // same context to allow both RSA and ECDSA certificates and support SNI-based selection.
   //
-  // Only one of ``tls_certificates``, ``tls_certificate_sds_secret_configs``,
-  // and ``tls_certificate_provider_instance`` may be used.
-  // [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's
-  // not legal to put a repeated field in a oneof. In the next major version, we should rework
-  // this to avoid this problem.]
+  // If ``tls_certificate_provider_instance`` is set, this field is ignored.
+  // If this field is set, ``tls_certificate_sds_secret_configs`` is ignored.
   repeated TlsCertificate tls_certificates = 2;
 
   // Configs for fetching TLS certificates via SDS API. Note SDS API allows certificates to be
@@ -261,17 +258,14 @@ message CommonTlsContext {
   // The same number and types of certificates as :ref:`tls_certificates <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_certificates>`
   // are valid in the the certificates fetched through this setting.
   //
-  // Only one of ``tls_certificates``, ``tls_certificate_sds_secret_configs``,
-  // and ``tls_certificate_provider_instance`` may be used.
-  // [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's
-  // not legal to put a repeated field in a oneof. In the next major version, we should rework
-  // this to avoid this problem.]
+  // If ``tls_certificates`` or ``tls_certificate_provider_instance`` are set, this field
+  // is ignored.
   repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6;
 
   // Certificate provider instance for fetching TLS certs.
   //
-  // Only one of ``tls_certificates``, ``tls_certificate_sds_secret_configs``,
-  // and ``tls_certificate_provider_instance`` may be used.
+  // If this field is set, ``tls_certificates`` and ``tls_certificate_provider_instance``
+  // are ignored.
   // [#not-implemented-hide:]
   CertificateProviderPluginInstance tls_certificate_provider_instance = 14;