docs: admin (#14)

docs/configuration/cluster_manager/cluster_hc.rst

@@ -74,7 +74,8 @@ interval_jitter_ms
 .. _config_cluster_manager_cluster_hc_service_name:
 
 service_name
-  *(optional, string)* An optional service name parameter which is used to validate health checked cluster
-  against this value. Upstream health checked cluster is taken from x-envoy-upstream-healthchecked-cluster
-  response header, :ref:`see details here <arch_overview_health_checking_filter>`.
-  If upstream health checked cluster differs from expected, HC will fail.
+  *(optional, string)* An optional service name parameter which is used to validate the health
+  checked cluster against this value. The upstream health checked cluster is taken from the
+  *x-envoy-upstream-healthchecked-cluster* response header, :ref:`see details here
+  <arch_overview_health_checking_filter>`. It is compared against the :option:`--service-cluster`
+  command line option. If the upstream health checked cluster differs from expected, HC will fail.

docs/configuration/cluster_manager/sds_api.rst

@@ -44,6 +44,8 @@ ip_address
 port
   *(required, integer)* The port of the upstream host.
 
+.. _config_cluster_manager_sds_api_host_az:
+
 az
   *(optional, string)* The optional zone of the upstream host. Envoy uses the zone for various
   statistics and load balancing tasks documented elsewhere.

docs/configuration/overview/overview.rst

@@ -33,6 +33,8 @@ miscellaneous configuration.
   *(required, object)* Configuration for the :ref:`cluster manager <arch_overview_cluster_manager>`
   which owns all upstream clusters within the server.
 
+.. _config_overview_flags_path:
+
 flags_path
   *(optional, string)* The file system path to search for :ref:`startup flag files
   <operations_file_system_flags>`.

docs/configuration/overview/runtime.rst

@@ -26,6 +26,8 @@ subdirectory
   if multiple systems share the same delivery mechanism. Envoy configuration elements can be
   contained in a dedicated subdirectory.
 
+.. _config_runtime_override_subdirectory:
+
 override_subdirectory
   *(optional, string)* Specifies an optional subdirectory to load within the root directory. If
   specified and the directory exists, configuration values within this directory will override those

docs/intro/arch_overview/hot_restart.rst

@@ -1,3 +1,5 @@
+.. _arch_overview_hot_restart:
+
 Hot restart
 ===========
 
@@ -12,7 +14,7 @@ hot restart functionality has has the following general architecture:
   protocol.
 * The new process fully initializes itself (loads the configuration, does an initial service
   discovery and health checking phase, etc.) before it asks for copies of the listen sockets from
-  the old process. The new process starts listening and then tells the old process to start 
+  the old process. The new process starts listening and then tells the old process to start
   draining.
 * During the draining phase, the old process attempts to gracefully close existing connections. How
   this is done depends on the configured filters. The drain time is configurable and as more time

docs/intro/arch_overview/threading_model.rst

@@ -1,3 +1,5 @@
+.. _arch_overview_threading:
+
 Threading model
 ===============
 

docs/operations/admin.rst

@@ -2,3 +2,94 @@
 
 Administration interface
 ========================
+
+Envoy exposes a :ref:`local administration interface <config_admin>` that can be used to query and
+modify different aspects of the server.
+
+.. http:get:: /
+
+  Print a menu of all available options.
+
+.. http:get:: /certs
+
+  List out all loaded SSL certificates, including file name, serial number, and days until
+  expiration.
+
+.. http:get:: /clusters
+
+  List out all configured :ref:`cluster manager <arch_overview_cluster_manager>` clusters. This
+  information includes all discovered upstream hosts in each cluster along with per host statistics.
+  This is useful for debugging service discovery issues. The per host statistics include:
+
+  .. csv-table::
+    :header: Name, Type, Description
+    :widths: 1, 1, 2
+
+    cx_total, Counter, FIXFIX
+    cx_active, Gauge, FIXFIX
+    cx_connect_fail, Counter, FIXFIX
+    rq_total, Counter, FIXFIX
+    rq_active, Gauge, FIXFIX
+    healthy, Boolean, FIXFIX
+    weight, Integer, FIXFIX
+    zone, String, FIXFIX
+    canary, Boolean, FIXFIX
+
+.. http:get:: /cpuprofiler
+
+  Enable or disable the CPU profiler. Requires compiling with gperftools.
+
+.. http:get:: /healthcheck/fail
+
+  Fail inbound health checks. This requires the use of the HTTP :ref:`health check filter
+  <config_http_filters_health_check>`. This is useful for draining a server prior to shutting it
+  down or doing a full restart. Invoking this command will universally fail health check requests
+  regardless of how the filter is configured (pass through, etc.).
+
+.. http:get:: /healthcheck/ok
+
+  Negate the effect of :http:get:`/healthcheck/fail`. This requires the use of the HTTP
+  :ref:`health check filter <config_http_filters_health_check>`.
+
+.. http:get:: /hot_restart_version
+
+  See :option:`--hot-restart-version`.
+
+.. http:get:: /logging
+
+  Enable/disable different logging levels on different subcomponents. Generally only used during
+  development.
+
+.. http:get:: /quitquitquit
+
+  Cleanly exit the server.
+
+.. http:get:: /reset_counters
+
+  Reset all counters to zero. This is useful along with :http:get:`/stats` during debugging. Note
+  that this does not drop any data sent to statsd. It just effects local output of the
+  :http:get:`/stats` command.
+
+.. http:get:: /server_info
+
+  Outputs information about the running server. Sample output looks like:
+
+.. code-block:: none
+
+  envoy 267724/RELEASE live 1571 1571 0
+
+The fields are:
+
+* Process name
+* Compiled SHA and build type
+* Health check state (live or draining)
+* Current hot restart epoch uptime in seconds
+* Total uptime in seconds (across all hot restarts)
+* Current hot restart epoch
+
+.. http:get:: /stats
+
+  Outputs all statistics on demand. This includes only counters and gauges. Timers are not output as
+  Envoy currently has no built in histogram support and relies on statsd for timer aggregation. This
+  command is very useful for local debugging. See :ref:`here <operations_stats>` for more
+  information.

docs/operations/cli.rst

@@ -1,38 +1,62 @@
 Command line options
 ====================
 
+Envoy is driven both by a JSON configuration file as well as a set of command line options. The
+following are the command line options that Envoy supports.
+
 .. option:: -c <path string>, --config-path <path string>
 
-  FIXFIX
+  *(required)* The path to the :ref:`JSON configuration file <config>`.
 
 .. option:: --base-id <integer>
 
-  FIXFIX
+  *(optional)* The base ID to use when allocating shared memory regions. Envoy uses shared memory
+  regions during :ref:`hot restart <arch_overview_hot_restart>`. Most users will never have to
+  set this option. However, if Envoy needs to be run multiple times on the same machine, each
+  running Envoy will need a unique base ID so that the shared memory regions do not conflict.
 
 .. option:: --concurrency <integer>
 
-  FIXFIX
+  *(optional)* The number of :ref:`worker threads <arch_overview_threading>` to run. If not
+  specified defaults to the number of hardware threads on the machine.
 
 .. option:: -l <integer>, --log-level <integer>
 
-  FIXFIX
+  *(optional)* The logging level. Defaults to *NOTICE*. Non developers should never set this option.
 
 .. option:: --restart-epoch <integer>
 
-  FIXFIX
+  *(optional)* The :ref:`hot restart <arch_overview_hot_restart>` epoch. (The number of times
+  Envoy has been hot restarted instead of a fresh start). Defaults to 0 for the first start. This
+  option tells Envoy whether to attempt to create the shared memory region needed for hot restart,
+  or whether to open an existing one. It should be incremented every time a hot restart takes place.
+  The :ref:`hot restart wrapper <operations_hot_restarter>` sets the *RESTART_EPOCH* environment
+  variable which should be passed to this option in most cases.
 
 .. option:: --hot-restart-version
 
-  FIXFIX
+  *(optional)* Outputs an opaque hot restart compatibility version for the binary. This can be
+  matched against the output of the :http:get:`/hot_restart_version` admin endpoint to determine
+  whether the new binary and the running binary are hot restart compatible.
 
 .. option:: --service-cluster <string>
 
-  FIXFIX
+  *(optional)* Defines the local service cluster name where Envoy is running. Though optional,
+  it should be set if any of the following features are used: :ref:`statsd
+  <arch_overview_statistics>`, :ref:`health check cluster verification
+  <config_cluster_manager_cluster_hc_service_name>`, :ref:`runtime override directory
+  <config_runtime_override_subdirectory>`, :ref:`user agent addition
+  <config_http_conn_man_add_user_agent>`, :ref:`HTTP global rate limiting
+  <config_http_filters_rate_limit>`, and :ref:`HTTP tracing <arch_overview_tracing>`.
 
 .. option:: --service-node <string>
 
-  FIXFIX
+  *(optional)* Defines the local service node name where Envoy is running. Though optional,
+  it should be set if any of the following features are used: :ref:`statsd
+  <arch_overview_statistics>`, and :ref:`HTTP tracing <arch_overview_tracing>`.
 
 .. option:: --service-zone <string>
 
-  FIXFIX
+  *(optional)* Defines the local service zone where Envoy is running. Though optional, it should
+  be set if discovery service routing is used and the discovery service exposes :ref:`zone data
+  <config_cluster_manager_sds_api_host_az>`.

docs/operations/fs_flags.rst

@@ -2,3 +2,12 @@
 
 File system flags
 =================
+
+Envoy supports file system "flags" that alter state at startup. This is used to persist changes
+between restarts if necessary. The flag files should be placed in the directory specified in the
+:ref:`flags_path <config_overview_flags_path>` configuration option. The currently supported
+flag files are:
+
+drain
+  If this file exists, Envoy will start in HC failing mode, similar to after the
+  :http:get:`/healthcheck/fail` command has been executed.

docs/operations/hot_restarter.rst

@@ -2,3 +2,36 @@
 
 Hot restart Python wrapper
 ==========================
+
+Typically, Envoy will be :ref:`hot restarted <arch_overview_hot_restart>` for config changes and
+binary updates. However, in many cases, users will wish to use a standard process manager such as
+monit, runit, etc. We provide :repo:`/restarter/hot-restarter.py` to make this straightforward.
+
+The restarter is invoked like so:
+
+.. code-block:: console
+
+  hot-restarter.py start_envoy.sh
+
+`start_envoy.sh` might be defined like so (using salt/jinja like syntax):
+
+.. code-block:: jinja
+
+  #!/bin/bash
+
+  ulimit -n {{ pillar.get('envoy_max_open_files', '102400') }}
+  exec /usr/sbin/envoy -c /etc/envoy/envoy.cfg --restart-epoch $RESTART_EPOCH --service-cluster {{ grains['cluster_name'] }} --service-node {{ grains['service_node'] }} --service-zone {{ grains.get('ec2_availability-zone', 'unknown') }}
+
+The *RESTART_EPOCH* environment variable is set by the restarter on each restart and can be passed
+to the :option:`--restart-epoch` option.
+
+The restarter handles the following signals:
+
+* **SIGTERM**: Will cleanly terminate all children and exit.
+* **SIGHUP**: Will hot restart by re-invoking whatever is passed as the first argument to the
+  hot restart script.
+* **SIGCHLD**: If any of the child processes shut down unexpectedly, the restart script will shut
+  everything down and exit to avoid being in an unexpected state. The controlling process manager
+  should then restart the restarter script to start Envoy again.
+* **SIGUSR1**: Will be forwarded to Envoy as a signal to reopen all access logs. This is used for
+  atomic move and reopen log rotation.

docs/operations/runtime.rst

@@ -2,3 +2,7 @@
 
 Runtime
 =======
+
+:ref:`Runtime configuration <arch_overview_runtime>` can be used to modify various server settings
+without restarting Envoy. The runtime settings that are available depend on how the server is
+configured. They are documented in the relevant sections of the :ref:`configuration guide <config>`.

docs/operations/stats_overview.rst

@@ -1,2 +1,13 @@
+.. _operations_stats:
+
 Statistics overview
 ===================
+
+Envoy outputs numerous statistics which depend on how the server is configured. They can be seen
+locally via the :http:get:`/stats` command and are typically sent to a :ref:`statsd cluster
+<arch_overview_statistics>`. The statistics that are output are documented in the relevant
+sections of the :ref:`configuration guide <config>`. Some of the more important statistics that will
+almost always be used can be found in the following sections:
+
+* :ref:`HTTP connection manager <config_http_conn_man_stats>`
+* :ref:`Upstream cluster <config_cluster_manager_cluster_stats>`