docs: health check (#288)

Also cleanup some small inconsistencies with link names.

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

api/BUILD

@@ -148,6 +148,7 @@ proto_library(
         ":rds",
         "//api/filter/accesslog:accesslog",
         "//api/filter/http:buffer",
+        "//api/filter/http:health_check",
         "//api/filter/http:lua",
         "//api/filter/http:router",
         "//api/filter/http:transcoder",

api/filter/http/health_check.proto

@@ -7,16 +7,17 @@ import "google/protobuf/wrappers.proto";
 
 import "validate/validate.proto";
 
-// Note that the filter will automatically fail health checks and set the
-// x-envoy-immediate-health-check-fail header if the /healthcheck/fail
-// admin endpoint has been called. (The /healthcheck/ok admin endpoint
-// reverses this behavior).
+// [#protodoc-title: Health check]
+// Health check :ref:`configuration overview <config_http_filters_health_check>`.
+
 message HealthCheck {
   // Specifies whether the filter operates in pass through mode or not.
   google.protobuf.BoolValue pass_through_mode = 1 [(validate.rules).message.required = true];
+
   // Specifies the incoming HTTP endpoint that should be considered the
-  // health check endpoint. For example /healthcheck.
-  string endpoint = 2 [(validate.rules).message.required = true];
+  // health check endpoint. For example */healthcheck*.
+  string endpoint = 2 [(validate.rules).string.min_len = 1];
+
   // If operating in pass through mode, the amount of time in milliseconds
   // that the filter should cache the upstream response.
   google.protobuf.Duration cache_time = 3;

docs/build.sh

@@ -39,6 +39,7 @@ PROTO_RST="
   /api/filter/accesslog/accesslog/api/filter/accesslog/accesslog.proto.rst
   /api/filter/fault/api/filter/fault.proto.rst
   /api/filter/http/buffer/api/filter/http/buffer.proto.rst
+  /api/filter/http/health_check/api/filter/http/health_check.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

docs/root/api-v1/http_filters/health_check_filter.rst

@@ -0,0 +1,28 @@
+.. _config_http_filters_health_check_v1:
+
+Health check
+============
+
+Health check :ref:`configuration overview <config_http_filters_health_check>`.
+
+.. code-block:: json
+
+  {
+    "name": "health_check",
+    "config": {
+      "pass_through_mode": "...",
+      "endpoint": "...",
+      "cache_time_ms": "..."
+     }
+  }
+
+pass_through_mode
+  *(required, boolean)* Specifies whether the filter operates in pass through mode or not.
+
+endpoint
+  *(required, string)* Specifies the incoming HTTP endpoint that should be considered the
+  health check endpoint. For example */healthcheck*.
+
+cache_time_ms
+  *(optional, integer)* If operating in pass through mode, the amount of time in milliseconds that
+  the filter should cache the upstream response.

docs/root/configuration/http_filters/buffer_filter.rst

@@ -7,8 +7,8 @@ The buffer filter is used to stop filter iteration and wait for a fully buffered
 This is useful in different situations including protecting some applications from having to deal
 with partial requests and high network latency.
 
-* :ref:`v1 configuration <config_http_filters_buffer_v1>`
-* :ref:`v2 configuration <envoy_api_msg_filter.http.Buffer>`
+* :ref:`v1 API reference <config_http_filters_buffer_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.Buffer>`
 
 Statistics
 ----------

docs/root/configuration/http_filters/cors_filter.rst

@@ -8,5 +8,5 @@ For the meaning of the headers please refer to the pages below.
 
 - https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
 - https://www.w3.org/TR/cors/
-- :ref:`V1 API configuration <config_http_filters_cors_v1>`
-- :ref:`V2 API configuration <envoy_api_field_filter.network.HttpFilter.name>`
+- :ref:`v1 API reference <config_http_filters_cors_v1>`
+- :ref:`v2 API reference <envoy_api_field_filter.network.HttpFilter.name>`

docs/root/configuration/http_filters/grpc_json_transcoder_filter.rst

@@ -9,5 +9,5 @@ This is a filter which allows a RESTful JSON API client to send requests to Envo
 and get proxied to a gRPC service. The HTTP mapping for the gRPC service has to be defined by
 `custom options <https://cloud.google.com/service-management/reference/rpc/google.api#http>`_.
 
-* :ref:`v1 configuration <config_http_filters_grpc_json_transcoder_v1>`
-* :ref:`v2 configuration <envoy_api_msg_filter.http.GrpcJsonTranscoder>`
+* :ref:`v1 API reference <config_http_filters_grpc_json_transcoder_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.GrpcJsonTranscoder>`

docs/root/configuration/http_filters/health_check_filter.rst

@@ -3,33 +3,15 @@
 Health check
 ============
 
-Health check filter :ref:`architecture overview <arch_overview_health_checking_filter>`.
-
-.. code-block:: json
-
-  {
-    "name": "health_check",
-    "config": {
-      "pass_through_mode": "...",
-      "endpoint": "...",
-      "cache_time_ms": "...",
-     }
-  }
-
-Note that the filter will automatically fail health checks and set the
-:ref:`x-envoy-immediate-health-check-fail
-<config_http_filters_router_x-envoy-immediate-health-check-fail>` header if the
-:ref:`/healthcheck/fail <operations_admin_interface_healthcheck_fail>` admin endpoint has been
-called. (The :ref:`/healthcheck/ok <operations_admin_interface_healthcheck_ok>` admin endpoint
-reverses this behavior).
-
-pass_through_mode
-  *(required, boolean)* Specifies whether the filter operates in pass through mode or not.
-
-endpoint
-  *(required, string)* Specifies the incoming HTTP endpoint that should be considered the
-  health check endpoint. For example */healthcheck*.
-
-cache_time_ms
-  *(optional, integer)* If operating in pass through mode, the amount of time in milliseconds that
-  the filter should cache the upstream response.
+* Health check filter :ref:`architecture overview <arch_overview_health_checking_filter>`
+* :ref:`v1 API reference <config_http_filters_health_check_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.HealthCheck>`
+
+.. note::
+
+  Note that the filter will automatically fail health checks and set the
+  :ref:`x-envoy-immediate-health-check-fail
+  <config_http_filters_router_x-envoy-immediate-health-check-fail>` header if the
+  :ref:`/healthcheck/fail <operations_admin_interface_healthcheck_fail>` admin endpoint has been
+  called. (The :ref:`/healthcheck/ok <operations_admin_interface_healthcheck_ok>` admin endpoint
+  reverses this behavior).

docs/root/configuration/http_filters/lua_filter.rst

@@ -55,8 +55,8 @@ API.
 Configuration
 -------------
 
-* :ref:`v1 configuration <config_http_filters_lua_v1>`
-* :ref:`v2 configuration <envoy_api_msg_filter.http.Lua>`
+* :ref:`v1 API reference <config_http_filters_lua_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.Lua>`
 
 Script examples
 ---------------

docs/root/configuration/http_filters/router_filter.rst

@@ -8,8 +8,8 @@ that Envoy is deployed for. The filter's main job is to follow the instructions
 configured :ref:`route table <config_http_conn_man_route_table>`. In addition to forwarding and
 redirection, the filter also handles retry, statistics, etc.
 
-* :ref:`V1 API configuration <config_http_filters_router_v1>`.
-* :ref:`V2 API configuration <envoy_api_msg_filter.http.Router>`.
+* :ref:`v1 API reference <config_http_filters_router_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.Router>`
 
 .. _config_http_filters_router_headers:
 

docs/root/configuration/network_filters/mongo_proxy_filter.rst

@@ -3,8 +3,7 @@
 Mongo proxy
 ===========
 
-MongoDB :ref:`architecture overview <arch_overview_mongo>`.
-
+- MongoDB :ref:`architecture overview <arch_overview_mongo>`
 - :ref:`v1 API reference <config_network_filters_mongo_proxy_v1>`
 - :ref:`v2 API reference <envoy_api_msg_filter.network.MongoProxy>`
 

docs/root/configuration/network_filters/redis_proxy_filter.rst

@@ -3,7 +3,7 @@
 Redis proxy
 ===========
 
-Redis :ref:`architecture overview <arch_overview_redis>`.
+Redis :ref:`architecture overview <arch_overview_redis>`
 
 .. code-block:: json