docs: enhance custom certificate validator documentation (#15306)

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

Mirrored from https://github.com/envoyproxy/envoy @ 7e7b527d5347cfdbfd9c3b0d94192c4a59b3b1da

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

@@ -377,11 +377,6 @@ message CertificateValidationContext {
   // If specified, all validation is done by the specified validator,
   // and the behavior of all other validation settings is defined by the specified validator (and may be entirely ignored, unused, and unvalidated).
   // Refer to the documentation for the specified validator. If you do not want a custom validation algorithm, do not set this field.
-  // The following names are available here:
-  //
-  // .. _extension_envoy.tls.cert_validator.spiffe:
-  //
-  // **envoy.tls.cert_validator.spiffe**: `SPIFFE <https://github.com/spiffe/spiffe>`_ certificate validator.
-  // Please refer to :ref:`envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig>` for more information.
+  // [#extension-category: envoy.tls.cert_validator]
   config.core.v3.TypedExtensionConfig custom_validator_config = 12;
 }

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

@@ -4,9 +4,7 @@ package envoy.extensions.transport_sockets.tls.v3;
 
 import "envoy/config/core/v3/base.proto";
 
-import "udpa/annotations/sensitive.proto";
 import "udpa/annotations/status.proto";
-import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.transport_sockets.tls.v3";
@@ -15,25 +13,26 @@ option java_multiple_files = true;
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: SPIFFE Certificate Validator]
+// [#extension: envoy.tls.cert_validator.spiffe]
 
-// Configuration specific to the SPIFFE certificate validator provided at
-// :ref:`envoy.extensions.transport_sockets.tls.v3.CertificateValidationContext.custom_validator_config<envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.custom_validator_config>`.
+// Configuration specific to the `SPIFFE <https://github.com/spiffe/spiffe>`_ certificate validator.
 //
 // Example:
 //
-// .. code-block:: yaml
+// .. validated-code-block:: yaml
+//   :type-name: envoy.extensions.transport_sockets.tls.v3.CertificateValidationContext
 //
-//  custom_validator_config:
-//    name: envoy.tls.cert_validator.spiffe
-//    typed_config:
-//      "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig
-//      trust_domains:
-//      - name: foo.com
-//        trust_bundle:
-//          filename: "foo.pem"
-//      - name: envoy.com
-//        trust_bundle:
-//          filename: "envoy.pem"
+//   custom_validator_config:
+//     name: envoy.tls.cert_validator.spiffe
+//     typed_config:
+//       "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig
+//       trust_domains:
+//       - name: foo.com
+//         trust_bundle:
+//           filename: "foo.pem"
+//       - name: envoy.com
+//         trust_bundle:
+//           filename: "envoy.pem"
 //
 // In this example, a presented peer certificate whose SAN matches `spiffe//foo.com/**` is validated against
 // the "foo.pem" x.509 certificate. All the trust bundles are isolated from each other, so no trust domain can mint

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

@@ -379,11 +379,6 @@ message CertificateValidationContext {
   // If specified, all validation is done by the specified validator,
   // and the behavior of all other validation settings is defined by the specified validator (and may be entirely ignored, unused, and unvalidated).
   // Refer to the documentation for the specified validator. If you do not want a custom validation algorithm, do not set this field.
-  // The following names are available here:
-  //
-  // .. _extension_envoy.tls.cert_validator.spiffe:
-  //
-  // **envoy.tls.cert_validator.spiffe**: `SPIFFE <https://github.com/spiffe/spiffe>`_ certificate validator.
-  // Please refer to :ref:`envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig>` for more information.
+  // [#extension-category: envoy.tls.cert_validator]
   config.core.v4alpha.TypedExtensionConfig custom_validator_config = 12;
 }

envoy/extensions/transport_sockets/tls/v4alpha/tls_spiffe_validator_config.proto

@@ -4,7 +4,6 @@ package envoy.extensions.transport_sockets.tls.v4alpha;
 
 import "envoy/config/core/v4alpha/base.proto";
 
-import "udpa/annotations/sensitive.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -15,25 +14,26 @@ option java_multiple_files = true;
 option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
 
 // [#protodoc-title: SPIFFE Certificate Validator]
+// [#extension: envoy.tls.cert_validator.spiffe]
 
-// Configuration specific to the SPIFFE certificate validator provided at
-// :ref:`envoy.extensions.transport_sockets.tls.v3.CertificateValidationContext.custom_validator_config<envoy_api_field_extensions.transport_sockets.tls.v4alpha.CertificateValidationContext.custom_validator_config>`.
+// Configuration specific to the `SPIFFE <https://github.com/spiffe/spiffe>`_ certificate validator.
 //
 // Example:
 //
-// .. code-block:: yaml
+// .. validated-code-block:: yaml
+//   :type-name: envoy.extensions.transport_sockets.tls.v3.CertificateValidationContext
 //
-//  custom_validator_config:
-//    name: envoy.tls.cert_validator.spiffe
-//    typed_config:
-//      "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig
-//      trust_domains:
-//      - name: foo.com
-//        trust_bundle:
-//          filename: "foo.pem"
-//      - name: envoy.com
-//        trust_bundle:
-//          filename: "envoy.pem"
+//   custom_validator_config:
+//     name: envoy.tls.cert_validator.spiffe
+//     typed_config:
+//       "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig
+//       trust_domains:
+//       - name: foo.com
+//         trust_bundle:
+//           filename: "foo.pem"
+//       - name: envoy.com
+//         trust_bundle:
+//           filename: "envoy.pem"
 //
 // In this example, a presented peer certificate whose SAN matches `spiffe//foo.com/**` is validated against
 // the "foo.pem" x.509 certificate. All the trust bundles are isolated from each other, so no trust domain can mint