docs: client ssl auth filter (#308)

Signed-off-by: Matt Klein <mklein@lyft.com>

api/BUILD

@@ -153,6 +153,7 @@ proto_library(
         "//api/filter/http:lua",
         "//api/filter/http:router",
         "//api/filter/http:transcoder",
+        "//api/filter/network:client_ssl_auth",
         "//api/filter/network:http_connection_manager",
         "//api/filter/network:mongo_proxy",
         "//api/filter/network:redis_proxy",

api/filter/network/client_ssl_auth.proto

@@ -5,24 +5,29 @@ package envoy.api.v2.filter.network;
 import "api/address.proto";
 import "google/protobuf/duration.proto";
 
-// Envoy provides a network filter that performs TLS client authentication
-// via principals fetched from a REST VPN service. This filter matches the
-// presented client certificate hash against the principal list to
-// determine whether the connection should be allowed or not. Optional IP
-// white listing can also be configured. This functionality can be used to
-// build edge proxy VPN support for web infrastructure.
+import "validate/validate.proto";
+
+// [#protodoc-title: Client TLS authentication]
+// Client TLS authentication
+// :ref:`configuration overview <config_network_filters_client_ssl_auth>`.
+
 message ClientSSLAuth {
-  // The cluster manager cluster that runs the authentication service. The
-  // filter will connect to the service every 60s to fetch the list of
-  // principals. The service must support the expected REST API.
-  string auth_api_cluster = 1;
-  // The prefix to use when emitting statistics.
-  string stat_prefix = 2;
+  // The :ref:`cluster manager <arch_overview_cluster_manager>` cluster that runs
+  // the authentication service. The filter will connect to the service every 60s to fetch the list
+  // of principals. The service must support the expected :ref:`REST API
+  // <config_network_filters_client_ssl_auth_rest_api>`.
+  string auth_api_cluster = 1 [(validate.rules).string.min_bytes = 1];
+
+  // The prefix to use when emitting :ref:`statistics
+  // <config_network_filters_client_ssl_auth_stats>`.
+  string stat_prefix = 2 [(validate.rules).string.min_bytes = 1];
+
   // Time in milliseconds between principal refreshes from the
   // authentication service. Default is 60000 (60s). The actual fetch time
   // will be this value plus a random jittered value between
   // 0-refresh_delay_ms milliseconds.
   google.protobuf.Duration refresh_delay = 3;
+
   // An optional list of IP address and subnet masks that should be white
   // listed for access by the filter. If no list is provided, there is no
   // IP white list.

docs/build.sh

@@ -44,6 +44,7 @@ PROTO_RST="
   /api/filter/http/lua/api/filter/http/lua.proto.rst
   /api/filter/http/router/api/filter/http/router.proto.rst
   /api/filter/http/transcoder/api/filter/http/transcoder.proto.rst
+  /api/filter/network/client_ssl_auth/api/filter/network/client_ssl_auth.proto.rst
   /api/filter/network/http_connection_manager/api/filter/network/http_connection_manager.proto.rst
   /api/filter/network/mongo_proxy/api/filter/network/mongo_proxy.proto.rst
   /api/filter/network/redis_proxy/api/filter/network/redis_proxy.proto.rst

docs/root/api-v1/network_filters/client_ssl_auth_filter.rst

@@ -0,0 +1,47 @@
+.. _config_network_filters_client_ssl_auth_v1:
+
+Client TLS authentication
+=========================
+
+Client TLS authentication :ref:`configuration overview <config_network_filters_client_ssl_auth>`.
+
+.. code-block:: json
+
+  {
+    "name": "client_ssl_auth",
+    "config": {
+      "auth_api_cluster": "...",
+      "stat_prefix": "...",
+      "refresh_delay_ms": "...",
+      "ip_white_list": []
+    }
+  }
+
+auth_api_cluster
+  *(required, string)* The :ref:`cluster manager <arch_overview_cluster_manager>` cluster that runs
+  the authentication service. The filter will connect to the service every 60s to fetch the list
+  of principals. The service must support the expected :ref:`REST API
+  <config_network_filters_client_ssl_auth_rest_api>`.
+
+stat_prefix
+  *(required, string)* The prefix to use when emitting :ref:`statistics
+  <config_network_filters_client_ssl_auth_stats>`.
+
+refresh_delay_ms
+  *(optional, integer)* Time in milliseconds between principal refreshes from the authentication
+  service. Default is 60000 (60s). The actual fetch time will be this value plus a random jittered
+  value between 0-refresh_delay_ms milliseconds.
+
+ip_white_list
+  *(optional, array)* An optional list of IP address and subnet masks that should be white listed
+  for access by the filter. If no list is provided, there is no IP white list. The list is
+  specified as in the following example:
+
+  .. code-block:: json
+
+    [
+      "192.168.3.0/24",
+      "50.1.2.3/32",
+      "10.15.0.0/16",
+      "2001:abcd::/64"
+    ]

docs/root/configuration/network_filters/client_ssl_auth_filter.rst

@@ -3,48 +3,9 @@
 Client TLS authentication
 =========================
 
-Client TLS authentication filter :ref:`architecture overview <arch_overview_ssl_auth_filter>`.
-
-.. code-block:: json
-
-  {
-    "name": "client_ssl_auth",
-    "config": {
-      "auth_api_cluster": "...",
-      "stat_prefix": "...",
-      "refresh_delay_ms": "...",
-      "ip_white_list": []
-    }
-  }
-
-auth_api_cluster
-  *(required, string)* The :ref:`cluster manager <arch_overview_cluster_manager>` cluster that runs
-  the authentication service. The filter will connect to the service every 60s to fetch the list
-  of principals. The service must support the expected :ref:`REST API
-  <config_network_filters_client_ssl_auth_rest_api>`.
-
-stat_prefix
-  *(required, string)* The prefix to use when emitting :ref:`statistics
-  <config_network_filters_client_ssl_auth_stats>`.
-
-refresh_delay_ms
-  *(optional, integer)* Time in milliseconds between principal refreshes from the authentication
-  service. Default is 60000 (60s). The actual fetch time will be this value plus a random jittered
-  value between 0-refresh_delay_ms milliseconds.
-
-ip_white_list
-  *(optional, array)* An optional list of IP address and subnet masks that should be white listed
-  for access by the filter. If no list is provided, there is no IP white list. The list is
-  specified as in the following example:
-
-  .. code-block:: json
-
-    [
-      "192.168.3.0/24",
-      "50.1.2.3/32",
-      "10.15.0.0/16",
-      "2001:abcd::/64"
-    ]
+* Client TLS authentication filter :ref:`architecture overview <arch_overview_ssl_auth_filter>`
+* :ref:`v1 API reference <config_network_filters_client_ssl_auth_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.network.ClientSslAuth>`
 
 .. _config_network_filters_client_ssl_auth_stats:
 

docs/root/intro/version_history.rst

@@ -10,7 +10,7 @@ Version history
 * admin: added basic :ref:`Prometheus output <operations_admin_interface_stats>` for stats admin
   endpoint. Histograms are not currently output.
 * config: the :ref:`v2 API <config_overview_v2>` is now considered production ready.
-* config: added ::option:`--v2-config-only` CLI flag.
+* config: added :option:`--v2-config-only` CLI flag.
 * cors: added :ref:`CORS filter <config_http_filters_cors>`.
 * health check: added :ref:`x-envoy-immediate-health-check-fail
   <config_http_filters_router_x-envoy-immediate-health-check-fail>` header support.
@@ -22,7 +22,7 @@ Version history
   <envoy_api_msg_Cluster.RingHashLbConfig>`. This used to be configurable via runtime. The runtime
   configuration was deleted without deprecation as we are fairly certain no one is using it.
 * log: added the ability to optionally log to a file instead of stderr via the
-  ::option:`--log-path` option.
+  :option:`--log-path` option.
 * listeners: added :ref:`drain_type <envoy_api_field_Listener.drain_type>` option.
 * lua: added experimental :ref:`Lua filter <config_http_filters_lua>`.
 * mongo filter: added :ref:`fault injection <config_network_filters_mongo_proxy_fault_injection>`.
@@ -50,7 +50,7 @@ Version history
 * runtime: added :ref:`comment capability <config_runtime_comments>`.
 * server: change default ::`-l` to info level.
 * stats: maximum stat/name sizes and maximum number of stats are now variable via the
-  ::option:`--max-obj-name-len` and ::option:`--max-stats` options.
+  :option:`--max-obj-name-len` and :option:`--max-stats` options.
 * tcp proxy: added :ref:`access logging <envoy_api_field_filter.network.TcpProxy.access_log>`.
 * tcp proxy: added :ref:`configurable connect retries
   <envoy_api_field_filter.network.TcpProxy.max_connect_attempts>`.