docs: Update start/install section (envoyproxy#13490)

Signed-off-by: Ryan Northey <[email protected]>

Author: phlax

Diff for: docs/redirects.txt

@@ -9,3 +9,11 @@ install/tools/route_table_check_tool.rst      start/install/tools/route_table_ch
 install/tools/schema_validator_check_tool.rst start/install/tools/schema_validator_check_tool.rst
 install/tools/tools.rst       start/install/tools/tools.rst
 install/install.rst	      start/start.rst
+
+start/install/ref_configs.rst	intro/deployment_types/deployment_types.rst
+start/install/sandboxes/local_docker_build.rst start/building/local_docker_build.rst
+
+start/install/tools/tools.rst	operations/tools/tools.rst
+start/install/tools/route_table_check_tool.rst	operations/tools/route_table_check_tool.rst
+start/install/tools/schema_validator_check_tool.rst	operations/tools/schema_validator_check_tool.rst
+start/install/tools/config_load_check_tool.rst	operations/tools/config_load_check_tool.rst

Diff for: docs/root/intro/arch_overview/operations/dynamic_configuration.rst

@@ -12,7 +12,7 @@ collectively known as :ref:`"xDS" <xds_protocol>` (* discovery service). This do
 overview of the options currently available.
 
 * Top level configuration :ref:`reference <config>`.
-* :ref:`Reference configurations <install_ref_configs>`.
+* :ref:`Reference configurations <intro_deployment_types>`.
 * Envoy :ref:`v3 API overview <config_overview>`.
 * :ref:`xDS API endpoints <config_overview_management_server>`.
 

Diff for: docs/root/intro/deployment_types/deployment_types.rst

@@ -1,3 +1,5 @@
+.. _intro_deployment_types:
+
 Deployment types
 ================
 

Diff for: docs/root/intro/deployment_types/double_proxy.rst

@@ -22,4 +22,4 @@ Configuration template
 ^^^^^^^^^^^^^^^^^^^^^^
 
 The source distribution includes an example double proxy configuration. See
-:ref:`here <install_ref_configs>` for more information.
+:ref:`here <intro_deployment_types>` for more information.

Diff for: docs/root/intro/deployment_types/front_proxy.rst

@@ -22,4 +22,4 @@ Configuration template
 ^^^^^^^^^^^^^^^^^^^^^^
 
 The source distribution includes an example front proxy configuration. See
-:ref:`here <install_ref_configs>` for more information.
+:ref:`here <intro_deployment_types>` for more information.

Diff for: docs/root/intro/deployment_types/service_to_service.rst

@@ -64,4 +64,4 @@ load balancing, statistics gathering, etc.
 Configuration template
 ^^^^^^^^^^^^^^^^^^^^^^
 
-The source distribution includes :ref:`an example service-to-service configuration<install_ref_configs>`.
+The source distribution includes :ref:`an example service-to-service configuration<intro_deployment_types>`.

Diff for: docs/root/operations/operations.rst

@@ -15,3 +15,4 @@ Operations and administration
   traffic_tapping
   certificates
   performance
+  tools/tools

Diff for: docs/root/start/install/ref_configs.rst renamed to docs/root/operations/tools/config_generator.rst

@@ -1,18 +1,4 @@
-.. _install_ref_configs:
-
-Reference configurations
-========================
-
-The source distribution includes a set of example configuration templates for each of the three
-major Envoy deployment types:
-
-* :ref:`Service to service <deployment_type_service_to_service>`
-* :ref:`Front proxy <deployment_type_front_proxy>`
-* :ref:`Double proxy <deployment_type_double_proxy>`
-
-The goal of this set of example configurations is to demonstrate the full capabilities of Envoy in
-a complex deployment. All features will not be applicable to all use cases. For full documentation
-see the :ref:`configuration reference <config>`.
+.. _start_tools_configuration_generator:
 
 Configuration generator
 -----------------------

Diff for: docs/root/start/install/tools/config_load_check_tool.rst renamed to docs/root/operations/tools/config_load_check_tool.rst

@@ -1,9 +1,12 @@
+.. _start_tools:
+
 Tools
 =====
 
 .. toctree::
   :maxdepth: 2
 
+  config_generator
   config_load_check_tool
   route_table_check_tool
   schema_validator_check_tool

Diff for: docs/root/start/install/tools/route_table_check_tool.rst renamed to docs/root/operations/tools/route_table_check_tool.rst

@@ -0,0 +1,9 @@
+,,stable,stable,master,master
+Docker image,description,amd64,arm64,amd64,arm64
+`envoyproxy/envoy <https://hub.docker.com/r/envoyproxy/envoy/tags/>`_,Release binary with symbols stripped on top of an Ubuntu Bionic base.,v1.16-latest,v1.16-latest,,
+`envoyproxy/envoy-alpine <https://hub.docker.com/r/envoyproxy/envoy-alpine/tags/>`_,Release binary with symbols stripped on top of a **glibc** alpine base.,v1.16-latest,,,
+`envoyproxy/envoy-debug <https://hub.docker.com/r/envoyproxy/envoy-debug/tags/>`_,Release binary with debug symbols on top of an Ubuntu Bionic base.,v1.16-latest,v1.16-latest,,
+`envoyproxy/envoy-dev <https://hub.docker.com/r/envoyproxy/envoy-dev/tags/>`_,Release binary with symbols stripped on top of an Ubuntu Bionic base.,,,latest,latest
+`envoyproxy/envoy-alpine-dev <https://hub.docker.com/r/envoyproxy/envoy-alpine-dev/tags/>`_,Release binary with symbols stripped on top of a **glibc** alpine base.,,,latest,
+`envoyproxy/envoy-debug-dev <https://hub.docker.com/r/envoyproxy/envoy-debug-dev/tags/>`_,Release binary with debug symbols on top of an Ubuntu Bionic base.,,,latest,latest
+`envoyproxy/envoy-build-ubuntu <https://hub.docker.com/r/envoyproxy/envoy-debug-dev/tags/>`_,Build image which includes tools for building multi-arch Envoy and containers.,,,see dockerhub,see dockerhub

Diff for: docs/root/start/install/tools/schema_validator_check_tool.rst renamed to docs/root/operations/tools/schema_validator_check_tool.rst

@@ -0,0 +1,50 @@
+static_resources:
+
+  listeners:
+    - name: listener_0
+      address:
+        socket_address: { address: 0.0.0.0, port_value: 10000 }
+      filter_chains:
+        - filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                stat_prefix: ingress_http
+                codec_type: AUTO
+                route_config:
+                  name: local_route
+                  virtual_hosts:
+                    - name: local_service
+                      domains: ["*"]
+                      routes:
+                        - match: { prefix: "/" }
+                          route: { host_rewrite_literal: www.google.com, cluster: service_google }
+                http_filters:
+                  - name: envoy.filters.http.router
+
+  clusters:
+    - name: service_google
+      connect_timeout: 0.25s
+      type: LOGICAL_DNS
+      # Comment out the following line to test on v6 networks
+      dns_lookup_family: V4_ONLY
+      lb_policy: ROUND_ROBIN
+      load_assignment:
+        cluster_name: service_google
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: www.google.com
+                      port_value: 443
+      transport_socket:
+        name: envoy.transport_sockets.tls
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
+          sni: www.google.com
+
+admin:
+  access_log_path: /tmp/admin_access.log
+  address:
+    socket_address: { address: 0.0.0.0, port_value: 9901 }

Diff for: docs/root/start/install/tools/tools.rst renamed to docs/root/operations/tools/tools.rst

@@ -4,11 +4,12 @@
 Building
 ========
 
-The Envoy build system uses Bazel. In order to ease initial building and for a quick start, we
-provide an Ubuntu 16 based docker container that has everything needed inside of it to build
-and *statically link* Envoy, see :repo:`ci/README.md`.
+The Envoy build system uses `Bazel <https://bazel.build/>`_.
 
-In order to build manually, follow the instructions at :repo:`bazel/README.md`.
+In order to ease initial building and for a quick start, we provide an Ubuntu 16 based docker container that
+has everything needed inside of it to build and *statically link* Envoy, see :repo:`ci/README.md`.
+
+In order to build without using the Docker container, follow the instructions at :repo:`bazel/README.md`.
 
 .. _install_requirements:
 
@@ -28,62 +29,6 @@ for more information on performing manual builds.
 Please note that for Clang/LLVM 8 and lower, Envoy may need to be built with `--define tcmalloc=gperftools`
 as the new tcmalloc code is not guaranteed to compile with lower versions of Clang.
 
-.. _install_binaries:
-
-Pre-built binaries
-------------------
-
-We build and tag Docker images with release versions when we do official releases. These images can
-be found in the following repositories:
-
-* `envoyproxy/envoy <https://hub.docker.com/r/envoyproxy/envoy/tags/>`_: Release binary with
-  symbols stripped on top of an Ubuntu Bionic base.
-* `envoyproxy/envoy-debug <https://hub.docker.com/r/envoyproxy/envoy-debug/tags/>`_: Release
-  binary with debug symbols on top of an Ubuntu Bionic base.
-* `envoyproxy/envoy-alpine <https://hub.docker.com/r/envoyproxy/envoy-alpine/tags/>`_: Release
-  binary with symbols stripped on top of a **glibc** alpine base.
-
-.. note::
-
-  In the above repositories, we tag a *vX.Y-latest* image for each security/stable release line.
-
-On every master commit we additionally create a set of development Docker images. These images can
-be found in the following repositories:
-
-* `envoyproxy/envoy-dev <https://hub.docker.com/r/envoyproxy/envoy-dev/tags/>`_: Release binary with
-  symbols stripped on top of an Ubuntu Bionic base.
-* `envoyproxy/envoy-debug-dev <https://hub.docker.com/r/envoyproxy/envoy-debug-dev/tags/>`_: Release
-  binary with debug symbols on top of an Ubuntu Bionic base.
-* `envoyproxy/envoy-alpine-dev <https://hub.docker.com/r/envoyproxy/envoy-alpine-dev/tags/>`_: Release
-  binary with symbols stripped on top of a **glibc** alpine base.
-
-In the above *dev* repositories, the *latest* tag points to the last Envoy SHA in master that passed
-tests.
-
-.. note::
-
-  The Envoy project considers master to be release candidate quality at all times, and many
-  organizations track and deploy master in production. We encourage you to do the same so that
-  issues can be reported as early as possible in the development process.
-
-Packaged Envoy pre-built binaries for a variety of platforms are available via
-`GetEnvoy.io <https://www.getenvoy.io/>`_.
-
-We will consider producing additional binary types depending on community interest in helping with
-CI, packaging, etc. Please open an `issue in GetEnvoy <https://github.com/tetratelabs/getenvoy/issues>`_
-for pre-built binaries for different platforms.
-
-.. _arm_binaries:
-
-ARM64 binaries
-^^^^^^^^^^^^^^
-
-`envoyproxy/envoy <https://hub.docker.com/r/envoyproxy/envoy/tags/>`_,
-`envoyproxy/envoy-debug <https://hub.docker.com/r/envoyproxy/envoy-debug/tags/>`_,
-`envoyproxy/envoy-dev <https://hub.docker.com/r/envoyproxy/envoy-dev/tags/>`_ and
-`envoyproxy/envoy-debug-dev <https://hub.docker.com/r/envoyproxy/envoy-debug-dev/tags/>`_ are Docker
-`multi-arch <https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/>`_ images
-and should run transparently on compatible ARM64 hosts.
 
 Modifying Envoy
 ---------------
@@ -95,4 +40,4 @@ Envoy binary, and putting the binary in an Ubuntu container.
 .. toctree::
     :maxdepth: 2
 
-    install/sandboxes/local_docker_build
+    building/local_docker_build

Diff for: docs/root/start/_include/dockerhub-images.csv

@@ -1,3 +1,4 @@
+
 .. _install_sandboxes_local_docker_build:
 
 Building an Envoy Docker image
@@ -19,6 +20,14 @@ That command will take some time to run because it is compiling an Envoy binary
 
 For more information on building and different build targets, please refer to :repo:`ci/README.md`.
 
+.. warning::
+
+   These instructions for building Envoy use
+   `envoyproxy/envoy-build-ubuntu <https://hub.docker.com/r/envoyproxy/envoy-build-ubuntu/tags>`_ image.
+   You will need 4-5GB of disk space to accommodate this image.
+
+   This script runs as effective root on your host system.
+
 **Step 2: Build image with only Envoy binary**
 
 In this step we'll build an image that only has the Envoy binary, and none

Diff for: docs/root/start/_include/envoy-demo.yaml

@@ -0,0 +1,136 @@
+.. _start_docker:
+
+Using the Envoy Docker Image
+============================
+
+The following examples use the :ref:`official Envoy Docker image <start_install_docker>`.
+
+These instructions are known to work for the ``x86_64`` and ``arm64`` architectures.
+
+Running Envoy with docker-compose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you would like to use Envoy with docker-compose you can overwrite the provided configuration file
+by using a volume.
+
+.. substitution-code-block:: yaml
+
+  version: '3'
+  services:
+    envoy:
+      image: envoyproxy/|envoy_docker_image|
+      ports:
+        - "10000:10000"
+      volumes:
+        - ./envoy.yaml:/etc/envoy/envoy.yaml
+
+If you use this method, you will have to ensure that the ``envoy`` user can read the mounted file
+either by ensuring the correct permissions on the file, or making it world-readable, as described
+below.
+
+
+Build and run a Docker image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a simple Dockerfile to execute Envoy.
+
+If you create a custom ``envoy.yaml`` you can create your own Docker image with it using the following
+Dockerfile recipe:
+
+.. substitution-code-block:: dockerfile
+
+  FROM envoyproxy/|envoy_docker_image|
+  COPY envoy.yaml /etc/envoy/envoy.yaml
+  RUN chmod go+r /etc/envoy/envoy.yaml
+
+Build the Docker image using:
+
+.. code-block:: console
+
+   $ docker build -t envoy:v1 .
+
+Assuming Envoy is configured to listen on ports ``9901`` and ``10000``, you can now start it
+with:
+
+.. code-block:: console
+
+   $ docker run -d --name envoy -p 9901:9901 -p 10000:10000 envoy:v1
+
+Permissions for running Docker Envoy containers as a non-root user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Envoy Docker image should be started as ``root``, but switches when run to the ``envoy`` user
+created at build time.
+
+The user is switched in the Docker ``ENTRYPOINT``.
+
+Changing the ``uid`` and/or ``gid`` of the ``envoy`` user
+*********************************************************
+
+The default ``uid`` and ``gid`` for the ``envoy`` user are ``101``.
+
+The ``uid`` and ``gid`` of this user can be set at runtime using the ``ENVOY_UID`` and ``ENVOY_GID``
+environment variables.
+
+This can be done, for example, on the Docker command line:
+
+.. substitution-code-block:: console
+
+  $ docker run -d --name envoy -e ENVOY_UID=777 -e ENVOY_GID=777 envoyproxy/|envoy_docker_image|
+
+This can be useful if you wish to restrict or provide access to ``unix`` sockets inside the container, or
+for controlling access to an Envoy socket from outside of the container.
+
+To run the process inside  the container as the ``root`` user you can set ``ENVOY_UID`` to ``0``,
+but doing so has the potential to weaken the security of your running container.
+
+Logging permissions inside the Envoy container
+**********************************************
+
+The ``envoy`` image sends application logs to ``/dev/stdout`` and ``/dev/stderr`` by default, and these
+can be viewed in the container log.
+
+If you send application, admin or access logs to a file output, the ``envoy`` user will require the
+necessary permissions to write to this file. This can be achieved by setting the ``ENVOY_UID`` and/or
+by making the file writeable by the envoy user.
+
+For example, to mount a log folder from the host and make it writable, you can:
+
+.. substitution-code-block:: console
+
+  $ mkdir logs
+  $ chown 777 logs
+  $ docker run -d --name envoy -v $(pwd)/logs:/var/log -e ENVOY_UID=777 envoyproxy/|envoy_docker_image|
+
+You can then configure ``envoy`` to log to files in ``/var/log``
+
+Configuration and binary file permissions inside the Envoy container
+********************************************************************
+
+The ``envoy`` user also needs to have permission to access any required configuration files mounted
+into the container.
+
+Any binary files specified in the configuration should also be executable by the ``envoy`` user.
+
+If you are running in an environment with a strict ``umask`` setting, you may need to provide ``envoy``
+with access by setting the ownership and/or permissions of the file.
+
+One method of doing this without changing any file permissions is to start the container with the
+host user's ``uid``, for example:
+
+.. substitution-code-block:: console
+
+  $ docker run -d --name envoy -v $(pwd)/envoy.yaml:/etc/envoy/envoy.yaml -e ENVOY_UID=$(id -u) envoyproxy/|envoy_docker_image|
+
+Listen only on ports > 1024 inside the Docker Envoy container
+*************************************************************
+
+Unix-based systems restrict opening ``well-known`` ports (ie. with a port number < ``1024``) to the ``root`` user.
+
+If you need to listen on a ``well-known`` port you can use Docker to do so.
+
+For example, to create an Envoy server listening on port ``8000``, with forwarding from port ``80``:
+
+.. substitution-code-block:: console
+
+  $ docker run -d --name envoy -p 80:8000 envoyproxy/|envoy_docker_image|