docs: Use structured headings for examples steps (#13292)

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

docs/root/start/sandboxes/_include/docker-env-setup.rst

@@ -1,12 +1,14 @@
 The following documentation runs through the setup of Envoy described above.
 
-**Step 1: Install Docker**
+Step 1: Install Docker
+**********************
 
 Ensure that you have a recent versions of ``docker`` and ``docker-compose`` installed.
 
 A simple way to achieve this is via the `Docker Desktop <https://www.docker.com/products/docker-desktop>`_.
 
-**Step 2: Clone the Envoy repo**
+Step 2: Clone the Envoy repo
+****************************
 
 If you have not cloned the Envoy repo, clone it with:
 

docs/root/start/sandboxes/cache.rst

@@ -27,7 +27,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Start all of our containers**
+Step 3: Start all of our containers
+***********************************
 
 .. code-block:: console
 
@@ -43,7 +44,8 @@ Running the Sandbox
     cache_service1_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
     cache_service2_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
 
-**Step 4: Test Envoy's HTTP caching capabilities**
+Step 4: Test Envoy's HTTP caching capabilities
+**********************************************
 
 You can now send a request to both services via the ``front-envoy``. Note that since the two services have different routes,
 identical requests to different services have different cache entries (i.e. a request sent to service 2 will not be served by a cached

docs/root/start/sandboxes/cors.rst

@@ -31,7 +31,8 @@ Running the Sandboxes
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Start all of our containers**
+Step 3: Start all of our containers
+***********************************
 
 Switch to the ``frontend`` directory in the ``cors`` example, and start the containers:
 
@@ -63,7 +64,8 @@ Now, switch to the ``backend`` directory in the ``cors`` example, and start the
   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 4: Test Envoy's CORS capabilities**
+Step 4: Test Envoy's CORS capabilities
+**************************************
 
 You can now open a browser to view your frontend service at http://localhost:8000.
 
@@ -78,7 +80,8 @@ 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 5: 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.
 

docs/root/start/sandboxes/csrf.rst

@@ -32,7 +32,8 @@ Running the Sandboxes
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Start all of our containers**
+Step 3: Start all of our containers
+***********************************
 
 Switch to the ``samesite`` directory in the ``csrf`` example, and start the containers:
 
@@ -63,7 +64,8 @@ Now, switch to the ``crosssite`` directory in the ``csrf`` example, and start th
   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 4: Test Envoy's CSRF capabilities**
+Step 4: Test Envoy's CSRF capabilities
+**************************************
 
 You can now open a browser at http://localhost:8002 to view your ``crosssite`` frontend service.
 
@@ -87,7 +89,8 @@ For example:
 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.
 
-**Step 5: 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``.

docs/root/start/sandboxes/ext_authz.rst

@@ -19,7 +19,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Start all of our containers**
+Step 3: Start all of our containers
+***********************************
 
 To build this sandbox example and start the example services, run the following commands:
 
@@ -62,7 +63,8 @@ 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 4: 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:
 

docs/root/start/sandboxes/fault_injection.rst

@@ -10,7 +10,8 @@ Running the Sandboxes
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Start all of our containers**
+Step 3: Start all of our containers
+***********************************
 
 Terminal 1
 
@@ -27,7 +28,8 @@ 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 4: Start sending continuous stream of HTTP requests**
+Step 4: Start sending continuous stream of HTTP requests
+********************************************************
 
 Terminal 2
 
@@ -40,7 +42,8 @@ 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 5: 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.
 
@@ -62,7 +65,8 @@ Terminal 3
 
   $ bash disable_abort_fault_injection.sh
 
-**Step 6: 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.
 
@@ -83,7 +87,8 @@ Terminal 3
 
   $ bash disable_delay_fault_injection.sh
 
-**Step 7: Check the current runtime filesystem**
+Step 7: Check the current runtime filesystem
+********************************************
 
 To see the current runtime filesystem overview:
 

docs/root/start/sandboxes/front_proxy.rst

@@ -31,7 +31,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Start all of our containers**
+Step 3: Start all of our containers
+***********************************
 
 .. code-block:: console
 
@@ -47,7 +48,8 @@ Running the Sandbox
     front-proxy_service1_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
     front-proxy_service2_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
 
-**Step 4: Test Envoy's routing capabilities**
+Step 4: Test Envoy's routing capabilities
+*****************************************
 
 You can now send a request to both services via the ``front-envoy``.
 
@@ -143,7 +145,8 @@ We can also use ``HTTPS`` to call services behind the front Envoy. For example,
     <
     Hello from behind Envoy (service 1)! hostname: 36418bc3c824 resolvedhostname: 192.168.160.4
 
-**Step 5: Test Envoy's load balancing capabilities**
+Step 5: Test Envoy's load balancing capabilities
+************************************************
 
 Now let's scale up our ``service1`` nodes to demonstrate the load balancing abilities of Envoy:
 
@@ -211,7 +214,8 @@ requests by doing a round robin of the three ``service1`` machines:
     <
     Hello from behind Envoy (service 1)! hostname: 36418bc3c824 resolvedhostname: 192.168.160.4
 
-**Step 6: enter containers and curl services**
+Step 6: enter containers and curl services
+******************************************
 
 In addition of using ``curl`` from your host machine, you can also enter the
 containers themselves and ``curl`` from inside them. To enter a container you
@@ -230,7 +234,8 @@ enter the ``front-envoy`` container, and ``curl`` for services locally:
     root@81288499f9d7:/# curl localhost:8080/service/2
     Hello from behind Envoy (service 2)! hostname: 92f4a3737bbc resolvedhostname: 172.19.0.2
 
-**Step 7: enter container and curl admin**
+Step 7: enter container and curl admin
+**************************************
 
 When Envoy runs it also attaches an ``admin`` to your desired port.
 

docs/root/start/sandboxes/grpc_bridge.rst

@@ -25,7 +25,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Generate the protocol stubs**
+Step 3: Generate the protocol stubs
+***********************************
 
 A docker-compose file is provided that generates the stubs for both ``client`` and ``server`` from the
 specification in the ``protos`` directory.
@@ -65,7 +66,8 @@ respective directories:
 
 These generated ``python`` and ``go`` stubs can be included as external modules.
 
-**Step 4: Start all of our containers**
+Step 4: Start all of our containers
+***********************************
 
 To build this sandbox example and start the example services, run the following commands:
 

docs/root/start/sandboxes/jaeger_native_tracing.rst

@@ -49,7 +49,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Build the sandbox**
+Step 3: Build the sandbox
+*************************
 
 To build this sandbox example, and start the example apps run the following commands:
 
@@ -68,7 +69,8 @@ To build this sandbox example, and start the example apps run the following comm
     jaeger-native-tracing_service1_1      /start-service.sh              Up      10000/tcp, 8000/tcp
     jaeger-native-tracing_service2_1      /start-service.sh              Up      10000/tcp, 8000/tcp
 
-**Step 4: Generate some load**
+Step 4: Generate some load
+**************************
 
 You can now send a request to service1 via the front-envoy as follows:
 
@@ -92,7 +94,8 @@ You can now send a request to service1 via the front-envoy as follows:
     Hello from behind Envoy (service 1)! hostname: f26027f1ce28 resolvedhostname: 172.19.0.6
     * Connection #0 to host 192.168.99.100 left intact
 
-**Step 5: View the traces in Jaeger UI**
+Step 5: View the traces in Jaeger UI
+************************************
 
 Point your browser to http://localhost:16686 . You should see the Jaeger dashboard.
 Set the service to "front-proxy" and hit 'Find Traces'. You should see traces from the front-proxy.

docs/root/start/sandboxes/jaeger_tracing.rst

@@ -35,7 +35,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Build the sandbox**
+Step 3: Build the sandbox
+*************************
 
 To build this sandbox example, and start the example apps run the following commands:
 
@@ -54,7 +55,8 @@ To build this sandbox example, and start the example apps run the following comm
     jaeger-tracing_service1_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
     jaeger-tracing_service2_1      /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 8000/tcp
 
-**Step 4: Generate some load**
+Step 4: Generate some load
+**************************
 
 You can now send a request to service1 via the front-envoy as follows:
 
@@ -78,7 +80,8 @@ You can now send a request to service1 via the front-envoy as follows:
     Hello from behind Envoy (service 1)! hostname: f26027f1ce28 resolvedhostname: 172.19.0.6
     * Connection #0 to host 192.168.99.100 left intact
 
-**Step 5: View the traces in Jaeger UI**
+Step 5: View the traces in Jaeger UI
+************************************
 
 Point your browser to http://localhost:16686 . You should see the Jaeger dashboard.
 Set the service to "front-proxy" and hit 'Find Traces'. You should see traces from the front-proxy.

docs/root/start/sandboxes/load_reporting_service.rst

@@ -20,7 +20,8 @@ Running the Sandbox
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Build the sandbox**
+Step 3: Build the sandbox
+*************************
 
 Terminal 1 ::
 
@@ -42,7 +43,8 @@ Terminal 2 ::
     load-reporting-service_http_service_2   /bin/sh -c /usr/local/bin/ ... Up      10000/tcp, 0.0.0.0:81->80/tcp, 0.0.0.0:8082->8081/tcp
     load-reporting-service_lrs_server_1     go run main.go                   Up      0.0.0.0:18000->18000/tcp
 
-**Step 4: Start sending stream of HTTP requests**
+Step 4: Start sending stream of HTTP requests
+*********************************************
 
 Terminal 2 ::
 
@@ -52,7 +54,8 @@ Terminal 2 ::
 
 The script above (``send_requests.sh``) sends requests randomly to each Envoy, which in turn forwards the requests to the backend service.
 
-**Step 5: See Envoy Stats**
+Step 5: See Envoy Stats
+***********************
 
 You should see
 

docs/root/start/sandboxes/lua.rst

@@ -14,7 +14,8 @@ Running the Sandboxes
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Build the sandbox**
+Step 3: Build the sandbox
+*************************
 
 .. code-block:: console
 
@@ -29,7 +30,8 @@ Running the Sandboxes
   lua_proxy_1         /docker-entrypoint.sh /bin       Up      10000/tcp, 0.0.0.0:8000->8000/tcp, 0.0.0.0:8001->8001/tcp
   lua_web_service_1   node ./index.js                  Up      0.0.0.0:8080->80/tcp
 
-**Step 4: Send a request to the service**
+Step 4: Send a request to the service
+*************************************
 
 The output from the ``curl`` command below should include the headers ``foo``.
 

docs/root/start/sandboxes/mysql.rst

@@ -12,7 +12,8 @@ Running the Sandboxes
 
 .. include:: _include/docker-env-setup.rst
 
-**Step 3: Build the sandbox**
+Step 3: Build the sandbox
+*************************
 
 Terminal 1
 
@@ -30,7 +31,8 @@ Terminal 1
   mysql_proxy_1   /docker-entrypoint.sh /bin       Up      10000/tcp, 0.0.0.0:1999->1999/tcp, 0.0.0.0:8001->8001/tcp
 
 
-**Step 4: Issue commands using mysql**
+Step 4: Issue commands using mysql
+**********************************
 
 Use ``mysql`` to issue some commands and verify they are routed via Envoy. Note
 that the current implementation of the protocol filter was tested with MySQL
@@ -74,7 +76,8 @@ Terminal 1
   mysql> exit
   Bye
 
-**Step 5: Check egress stats**
+Step 5: Check egress stats
+**************************
 
 Check egress stats were updated.
 
@@ -93,7 +96,8 @@ Terminal 1
   mysql.egress_mysql.sessions: 1
   mysql.egress_mysql.upgraded_to_ssl: 0
 
-**Step 6: Check TCP stats**
+Step 6: Check TCP stats
+***********************
 
 Check TCP stats were updated.