sds: improve watched directory documentation.

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

@@ -155,7 +155,8 @@ message TlsCertificate {
   // default the parent directories of the filesystem paths in
   // *certificate_chain* and *private_key* are watched if this field is not
   // specified. This only applies when a *TlsCertificate* is delivered by SDS
-  // with references to filesystem paths.
+  // with references to filesystem paths. See the :ref:`SDS key rotation
+  // <sds_key_rotation>` documentation for further details.
   config.core.v3.WatchedDirectory watched_directory = 7;
 
   // BoringSSL private key method provider. This is an alternative to :ref:`private_key
@@ -265,7 +266,8 @@ message CertificateValidationContext {
   // default the parent directory of the filesystem path in *trusted_ca* is
   // watched if this field is not specified. This only applies when a
   // *CertificateValidationContext* is delivered by SDS with references to
-  // filesystem paths.
+  // filesystem paths. See the :ref:`SDS key rotation <sds_key_rotation>`
+  // documentation for further details.
   config.core.v3.WatchedDirectory watched_directory = 11;
 
   // An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the

docs/root/configuration/security/secret.rst

@@ -45,11 +45,15 @@ refer to filesystem paths. This currently is supported for the following secret
 * :ref:`TlsCertificate <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.TlsCertificate>`
 * :ref:`CertificateValidationContext <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.CertificateValidationContext>`
 
-By default, directories containing secrets are watched for filesystem move events. Explicit control over
-the watched directory is possible by specifying a *watched_directory* path in :ref:`TlsCertificate
+By default, directories containing secrets are watched for filesystem move events. For example, a
+key or trusted CA certificates at ``/foo/bar/baz/cert.pem`` will be watched at `/foo/bar/baz`.
+Explicit control over the watched directory is possible by specifying a *watched_directory* path in
+:ref:`TlsCertificate
 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.watched_directory>` and
 :ref:`CertificateValidationContext
 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.watched_directory>`.
+This allows watches to be established at path predecessors, e.g. ``/foo/bar``; this capability is
+useful when implementing common key rotation schemes.
 
 An example of key rotation is provided :ref:`below <xds_certificate_rotation>`.