Docs updates and cleanups

docs/root/start/sandboxes/cors.rst

@@ -37,12 +37,19 @@ Ensure that you have a recent versions of ``docker`` and ``docker-compose``.
 
 A simple way to achieve this is via the `Docker Desktop <https://www.docker.com/products/docker-desktop>`_.
 
-**Step 2: Clone the Envoy repo and start all of our containers**
+**Step 2: Clone the Envoy repo**
 
-If you have not cloned the Envoy repo, clone it with ``git clone git@github.com:envoyproxy/envoy``
-or ``git clone https://github.com/envoyproxy/envoy.git``
+If you have not cloned the Envoy repo, clone it with:
 
-Terminal 1
+``git clone git@github.com:envoyproxy/envoy``
+
+or
+
+``git clone https://github.com/envoyproxy/envoy.git``
+
+**Step 3: Start all of our containers**
+
+Switch to the ``frontend`` directory in the ``cors`` example, and start the containers:
 
 .. code-block:: console
 
@@ -57,12 +64,13 @@ Terminal 1
   frontend_front-envoy_1        /docker-entrypoint.sh /bin ... Up      10000/tcp, 0.0.0.0:8000->8000/tcp, 0.0.0.0:8001->8001/tcp
   frontend_frontend-service_1   /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
 
-Terminal 2
+Now, switch to the ``backend`` directory in the ``cors`` example, and start the containers:
 
 .. code-block:: console
 
   $ pwd
   envoy/examples/cors/backend
+  $ docker-compose pull
   $ docker-compose up --build -d
   $ docker-compose ps
 
@@ -71,12 +79,13 @@ Terminal 2
   backend_backend-service_1   /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
   backend_front-envoy_1       /docker-entrypoint.sh /bin ... Up      10000/tcp, 0.0.0.0:8002->8000/tcp, 0.0.0.0:8003->8001/tcp
 
-**Step 3: Test Envoy's CORS capabilities**
+**Step 4: Test Envoy's CORS capabilities**
 
-You can now open a browser to view your frontend service at ``localhost:8000``.
+You can now open a browser to view your frontend service at http://localhost:8000.
 
 Results of the cross-origin request will be shown on the page under *Request Results*.
-Your browser's CORS enforcement logs can be found in the console.
+
+Your browser's ``CORS`` enforcement logs can be found in the browser console.
 
 For example:
 
@@ -85,13 +94,14 @@ For example:
   Access to XMLHttpRequest at 'http://192.168.99.100:8002/cors/disabled' from origin 'http://192.168.99.101:8000'
   has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
 
-**Step 4: Check stats of backend via admin**
+**Step 5: Check stats of backend via admin**
+
+When Envoy runs, it can listen to ``admin`` requests if a port is configured.
 
-When Envoy runs, it can listen to ``admin`` requests if a port is configured. In the example
-configs, the backend admin is bound to port ``8003``.
+In the example configs, the backend admin is bound to port ``8003``.
 
-If you go to ``localhost:8003/stats`` you will be able to view
-all of the Envoy stats for the backend. You should see the CORS stats for
+If you browse to http://localhost:8003/stats you will be able to view
+all of the Envoy stats for the backend. You should see the ``CORS`` stats for
 invalid and valid origins increment as you make requests from the frontend cluster.
 
 .. code-block:: none

docs/root/start/sandboxes/csrf.rst

@@ -38,12 +38,19 @@ Ensure that you have a recent versions of ``docker`` and ``docker-compose``.
 
 A simple way to achieve this is via the `Docker Desktop <https://www.docker.com/products/docker-desktop>`_.
 
-**Step 2: Clone the Envoy repo and start all of our containers**
+**Step 2: Clone the Envoy repo**
 
-If you have not cloned the Envoy repo, clone it with ``git clone git@github.com:envoyproxy/envoy``
-or ``git clone https://github.com/envoyproxy/envoy.git``
+If you have not cloned the Envoy repo, clone it with:
 
-Terminal 1 (samesite)
+``git clone git@github.com:envoyproxy/envoy``
+
+or
+
+``git clone https://github.com/envoyproxy/envoy.git``
+
+**Step 3: Start all of our containers**
+
+Switch to the ``samesite`` directory in the ``csrf`` example, and start the containers:
 
 .. code-block:: console
 
@@ -58,7 +65,7 @@ Terminal 1 (samesite)
   samesite_front-envoy_1      /docker-entrypoint.sh /bin ... Up      10000/tcp, 0.0.0.0:8000->8000/tcp, 0.0.0.0:8001->8001/tcp
   samesite_service_1          /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
 
-Terminal 2 (crosssite)
+Now, switch to the ``crosssite`` directory in the ``csrf`` example, and start the containers:
 
 .. code-block:: console
 
@@ -72,27 +79,19 @@ Terminal 2 (crosssite)
   crosssite_front-envoy_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 0.0.0.0:8002->8000/tcp, 0.0.0.0:8003->8001/tcp
   crosssite_service_1          /docker-entrypoint.sh /bin ... Up      10000/tcp, 8000/tcp
 
-**Step 3: Test Envoy's CSRF capabilities**
-
-You can now open a browser to view your ``crosssite`` frontend service.
+**Step 4: Test Envoy's CSRF capabilities**
 
-.. code-block:: console
-
-  $ open "http://localhost:8002"
+You can now open a browser at http://localhost:8002 to view your ``crosssite`` frontend service.
 
 Enter the IP of the ``samesite`` machine to demonstrate cross-site requests. Requests
 with the enabled enforcement will fail. By default this field will be populated
 with ``localhost``.
 
-To demonstrate same-site requests open the frontend service for ``samesite`` and enter
-the IP address of the ``samesite`` machine as the destination.
-
-.. code-block:: console
-
-  $ open "http://localhost:8000"
+To demonstrate same-site requests open the frontend service for ``samesite`` at http://localhost:8000
+and enter the IP address of the ``samesite`` machine as the destination.
 
 Results of the cross-site request will be shown on the page under *Request Results*.
-Your browser's CSRF enforcement logs can be found in the console and in the
+Your browser's ``CSRF`` enforcement logs can be found in the browser console and in the
 network tab.
 
 For example:
@@ -102,14 +101,14 @@ For example:
   Failed to load resource: the server responded with a status of 403 (Forbidden)
 
 If you change the destination to be the same as one displaying the website and
-set the CSRF enforcement to enabled the request will go through successfully.
+set the ``CSRF`` enforcement to enabled the request will go through successfully.
 
-**Step 4: Check stats of backend via admin**
+**Step 5: Check stats of backend via admin**
 
 When Envoy runs, it can listen to ``admin`` requests if a port is configured. In
 the example configs, the backend admin is bound to port ``8001``.
 
-If you go to ``localhost:8001/stats`` you will be able to view
+If you browse to http://localhost:8001/stats you will be able to view
 all of the Envoy stats for the backend. You should see the CORS stats for
 invalid and valid origins increment as you make requests from the frontend cluster.
 

docs/root/start/sandboxes/ext_authz.rst

@@ -23,12 +23,21 @@ Ensure that you have a recent versions of ``docker`` and ``docker-compose``.
 
 A simple way to achieve this is via the `Docker Desktop <https://www.docker.com/products/docker-desktop>`_.
 
-**Step 2: Clone the Envoy repository and start all of our containers**
+**Step 2: Clone the Envoy repo**
 
-If you have not cloned the Envoy repository, clone it with ``git clone git@github.com:envoyproxy/envoy``
-or ``git clone https://github.com/envoyproxy/envoy.git``.
+If you have not cloned the Envoy repo, clone it with:
 
-To build this sandbox example and start the example services, run the following commands::
+``git clone git@github.com:envoyproxy/envoy``
+
+or
+
+``git clone https://github.com/envoyproxy/envoy.git``
+
+**Step 3: Start all of our containers**
+
+To build this sandbox example and start the example services, run the following commands:
+
+.. code-block:: console
 
     $ pwd
     envoy/examples/ext_authz
@@ -44,6 +53,7 @@ To build this sandbox example and start the example services, run the following
     ext_authz_upstream-service_1         python3 /app/service/server.py   Up
 
 .. note::
+
     This sandbox has multiple setup controlled by ``FRONT_ENVOY_YAML`` environment variable which
     points to the effective Envoy configuration to be used. The default value of ``FRONT_ENVOY_YAML``
     can be defined in the ``.env`` file or provided inline when running the ``docker-compose up``
@@ -54,7 +64,9 @@ front-envoy with ext_authz HTTP filter with gRPC service ``V3`` (this is specifi
 The possible values of ``FRONT_ENVOY_YAML`` can be found inside the ``envoy/examples/ext_authz/config``
 directory.
 
-For example, to run Envoy with ext_authz HTTP filter with HTTP service will be::
+For example, to run Envoy with ext_authz HTTP filter with HTTP service will be:
+
+.. code-block:: console
 
     $ pwd
     envoy/examples/ext_authz
@@ -64,9 +76,11 @@ For example, to run Envoy with ext_authz HTTP filter with HTTP service will be::
     $ FRONT_ENVOY_YAML=config/http-service.yaml docker-compose up --build -d
     $ # Or you can update the .env file with the above FRONT_ENVOY_YAML value, so you don't have to specify it when running the "up" command.
 
-**Step 3: Access the upstream-service behind the Front Envoy**
+**Step 4: Access the upstream-service behind the Front Envoy**
 
-You can now try to send a request to upstream-service via the front-envoy as follows::
+You can now try to send a request to upstream-service via the front-envoy as follows:
+
+.. code-block:: console
 
     $ curl -v localhost:8000/service
     *   Trying 127.0.0.1...
@@ -87,10 +101,13 @@ filter employed by Envoy rejected the call. To let the request reach the upstrea
 to provide a ``Bearer`` token via the ``Authorization`` header.
 
 .. note::
+
     A complete list of users is defined in ``envoy/examples/ext_authz/auth/users.json`` file. For
     example, the ``token1`` used in the below example is corresponding to ``user1``.
 
-An example of successful requests can be observed as follows::
+An example of successful requests can be observed as follows:
+
+.. code-block:: console
 
     $ curl -v -H "Authorization: Bearer token1" localhost:8000/service
     *   Trying 127.0.0.1...
@@ -114,7 +131,9 @@ An example of successful requests can be observed as follows::
 
 We can also employ `Open Policy Agent <https://www.openpolicyagent.org/>`_ server
 (with `envoy_ext_authz_grpc <https://github.com/open-policy-agent/opa-istio-plugin>`_ plugin enabled)
-as the authorization server. To run this example::
+as the authorization server. To run this example:
+
+.. code-block:: console
 
     $ pwd
     envoy/examples/ext_authz
@@ -123,7 +142,9 @@ as the authorization server. To run this example::
     $ docker-compose down
     $ FRONT_ENVOY_YAML=config/opa-service/v2.yaml docker-compose up --build -d
 
-And sending a request to the upstream service (via the Front Envoy) gives::
+And sending a request to the upstream service (via the Front Envoy) gives:
+
+.. code-block:: console
 
     $ curl localhost:8000/service --verbose
     *   Trying ::1...
@@ -145,7 +166,9 @@ And sending a request to the upstream service (via the Front Envoy) gives::
     Hello OPA from behind Envoy!
 
 From the logs, we can observe the policy decision message from the Open Policy Agent server (for
-the above request against the defined policy in ``config/opa-service/policy.rego``)::
+the above request against the defined policy in ``config/opa-service/policy.rego``):
+
+.. code-block:: console
 
     $ docker-compose logs ext_authz-opa-service | grep decision_id -A 30
     ext_authz-opa-service_1   |   "decision_id": "8143ca68-42d8-43e6-ade6-d1169bf69110",
@@ -180,7 +203,9 @@ the above request against the defined policy in ``config/opa-service/policy.rego
     ext_authz-opa-service_1   |           "method": "GET",
     ext_authz-opa-service_1   |           "path": "/service",
 
-Trying to send a request with method other than ``GET`` gives a rejection::
+Trying to send a request with method other than ``GET`` gives a rejection:
+
+.. code-block:: console
 
     $ curl -X POST localhost:8000/service --verbose
     *   Trying ::1...

docs/root/start/sandboxes/fault_injection.rst

@@ -8,19 +8,25 @@ This simple example demonstrates Envoy's :ref:`fault injection <config_http_filt
 Running the Sandboxes
 ~~~~~~~~~~~~~~~~~~~~~
 
-The following documentation runs through the setup of both services.
+The following documentation runs through the setup of the services.
 
 **Step 1: Install Docker**
 
 Ensure that you have a recent versions of ``docker`` and ``docker-compose``.
 
 A simple way to achieve this is via the `Docker Desktop <https://www.docker.com/products/docker-desktop>`_.
 
-**Step 2: Clone the Envoy repo and start all of our containers**
+**Step 2: Clone the Envoy repo**
 
-If you have not cloned the Envoy repo, clone it with ``git clone git@github.com:envoyproxy/envoy``
-or ``git clone https://github.com/envoyproxy/envoy.git``
+If you have not cloned the Envoy repo, clone it with:
 
+``git clone git@github.com:envoyproxy/envoy``
+
+or
+
+``git clone https://github.com/envoyproxy/envoy.git``
+
+**Step 3: Start all of our containers**
 
 Terminal 1
 
@@ -37,7 +43,7 @@ Terminal 1
   fault-injection_backend_1   gunicorn -b 0.0.0.0:80 htt       Up      0.0.0.0:8080->80/tcp
   fault-injection_envoy_1     /docker-entrypoint.sh /usr       Up      10000/tcp, 0.0.0.0:9211->9211/tcp, 0.0.0.0:9901->9901/tcp
 
-**Step 3: Start sending continuous stream of HTTP requests**
+**Step 4: Start sending continuous stream of HTTP requests**
 
 Terminal 2
 
@@ -50,7 +56,7 @@ Terminal 2
 
 The script above (``send_request.sh``) sends a continuous stream of HTTP requests to Envoy, which in turn forwards the requests to the backend container. Fauilt injection is configured in Envoy but turned off (i.e. affects 0% of requests). Consequently, you should see a continuous sequence of HTTP 200 response codes.
 
-**Step 4: Test Envoy's abort fault injection**
+**Step 5: Test Envoy's abort fault injection**
 
 Turn on *abort* fault injection via the runtime using the commands below.
 
@@ -72,7 +78,7 @@ Terminal 3
 
   $ bash disable_abort_fault_injection.sh
 
-**Step 5: Test Envoy's delay fault injection**
+**Step 6: Test Envoy's delay fault injection**
 
 Turn on *delay* fault injection via the runtime using the commands below.
 
@@ -93,7 +99,7 @@ Terminal 3
 
   $ bash disable_delay_fault_injection.sh
 
-**Step 5: Check the current runtime filesystem**
+**Step 7: Check the current runtime filesystem**
 
 To see the current runtime filesystem overview: