From 5fac1cf7c8d302c630860b7c544fb86f99dc74c6 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 30 May 2024 14:20:32 +0100 Subject: [PATCH] docs/examples: Shift rst files into example folders Signed-off-by: Ryan Northey --- docs/BUILD | 9 +- docs/root/start/sandboxes/index.rst | 42 +-- .../start/sandboxes/win32_front_proxy.rst | 354 ------------------ examples/BUILD | 52 ++- .../brotli.rst => examples/brotli/example.rst | 0 .../cache.rst => examples/cache/example.rst | 0 .../cors.rst => examples/cors/example.rst | 0 .../csrf.rst => examples/csrf/example.rst | 0 .../double-proxy/example.rst | 0 ...sponse-config-active-clusters-updated.json | 0 .../response-config-active-clusters.json | 0 .../_include}/response-config-cluster.json | 0 .../dynamic-config-cp/example.rst | 12 +- ...sponse-config-active-clusters-updated.json | 0 .../response-config-active-clusters.json | 0 .../dynamic-config-fs/example.rst | 10 +- .../ext_authz/example.rst | 0 .../fault-injection/example.rst | 0 .../front-proxy/example.rst | 0 .../golang-http/example.rst | 0 .../golang-network/example.rst | 0 .../grpc-bridge/example.rst | 0 .../gzip.rst => examples/gzip/example.rst | 0 .../jaeger-tracing/example.rst | 0 .../kafka.rst => examples/kafka/example.rst | 0 .../load-reporting-service/example.rst | 0 .../local_ratelimit/example.rst | 0 .../locality-load-balancing/example.rst | 0 .../lua-cluster-specifier/example.rst | 0 .../lua.rst => examples/lua/example.rst | 0 .../mysql.rst => examples/mysql/example.rst | 0 .../opentelemetry/example.rst | 0 .../postgres/example.rst | 0 .../rbac.rst => examples/rbac/example.rst | 0 .../redis.rst => examples/redis/example.rst | 0 .../route-mirror/example.rst | 0 .../single-page-app}/_static/spa-cookies.png | Bin .../_static/spa-github-oauth.png | Bin .../_static/spa-login-github.png | Bin .../single-page-app}/_static/spa-login.png | Bin .../_static/spa-resources.png | Bin .../single-page-app/example.rst | 10 +- .../_static/skywalking-services.png | Bin .../_static/skywalking-topology.png | Bin .../skywalking}/_static/skywalking-trace.png | Bin .../skywalking/example.rst | 6 +- .../tls-inspector/example.rst | 0 .../tls-sni/example.rst | 0 .../tls.rst => examples/tls/example.rst | 0 .../udp.rst => examples/udp/example.rst | 0 examples/wasm-cc/BUILD | 4 +- .../wasm-cc/example.rst | 0 .../websocket/example.rst | 0 .../zipkin}/_static/zipkin-ui-dependency.png | Bin .../zipkin}/_static/zipkin-ui.png | Bin .../zipkin.rst => examples/zipkin/example.rst | 4 +- .../zstd.rst => examples/zstd/example.rst | 0 57 files changed, 77 insertions(+), 426 deletions(-) delete mode 100644 docs/root/start/sandboxes/win32_front_proxy.rst rename docs/root/start/sandboxes/brotli.rst => examples/brotli/example.rst (100%) rename docs/root/start/sandboxes/cache.rst => examples/cache/example.rst (100%) rename docs/root/start/sandboxes/cors.rst => examples/cors/example.rst (100%) rename docs/root/start/sandboxes/csrf.rst => examples/csrf/example.rst (100%) rename docs/root/start/sandboxes/double-proxy.rst => examples/double-proxy/example.rst (100%) rename {docs/root/start/sandboxes/_include/dynamic-config-cp => examples/dynamic-config-cp/_include}/response-config-active-clusters-updated.json (100%) rename {docs/root/start/sandboxes/_include/dynamic-config-cp => examples/dynamic-config-cp/_include}/response-config-active-clusters.json (100%) rename {docs/root/start/sandboxes/_include/dynamic-config-cp => examples/dynamic-config-cp/_include}/response-config-cluster.json (100%) rename docs/root/start/sandboxes/dynamic-configuration-control-plane.rst => examples/dynamic-config-cp/example.rst (92%) rename {docs/root/start/sandboxes/_include/dynamic-config-fs => examples/dynamic-config-fs/_include}/response-config-active-clusters-updated.json (100%) rename {docs/root/start/sandboxes/_include/dynamic-config-fs => examples/dynamic-config-fs/_include}/response-config-active-clusters.json (100%) rename docs/root/start/sandboxes/dynamic-configuration-filesystem.rst => examples/dynamic-config-fs/example.rst (88%) rename docs/root/start/sandboxes/ext_authz.rst => examples/ext_authz/example.rst (100%) rename docs/root/start/sandboxes/fault_injection.rst => examples/fault-injection/example.rst (100%) rename docs/root/start/sandboxes/front_proxy.rst => examples/front-proxy/example.rst (100%) rename docs/root/start/sandboxes/golang-http.rst => examples/golang-http/example.rst (100%) rename docs/root/start/sandboxes/golang-network.rst => examples/golang-network/example.rst (100%) rename docs/root/start/sandboxes/grpc_bridge.rst => examples/grpc-bridge/example.rst (100%) rename docs/root/start/sandboxes/gzip.rst => examples/gzip/example.rst (100%) rename docs/root/start/sandboxes/jaeger_tracing.rst => examples/jaeger-tracing/example.rst (100%) rename docs/root/start/sandboxes/kafka.rst => examples/kafka/example.rst (100%) rename docs/root/start/sandboxes/load_reporting_service.rst => examples/load-reporting-service/example.rst (100%) rename docs/root/start/sandboxes/local_ratelimit.rst => examples/local_ratelimit/example.rst (100%) rename docs/root/start/sandboxes/locality_load_balancing.rst => examples/locality-load-balancing/example.rst (100%) rename docs/root/start/sandboxes/lua-cluster-specifier.rst => examples/lua-cluster-specifier/example.rst (100%) rename docs/root/start/sandboxes/lua.rst => examples/lua/example.rst (100%) rename docs/root/start/sandboxes/mysql.rst => examples/mysql/example.rst (100%) rename docs/root/start/sandboxes/opentelemetry.rst => examples/opentelemetry/example.rst (100%) rename docs/root/start/sandboxes/postgres.rst => examples/postgres/example.rst (100%) rename docs/root/start/sandboxes/rbac.rst => examples/rbac/example.rst (100%) rename docs/root/start/sandboxes/redis.rst => examples/redis/example.rst (100%) rename docs/root/start/sandboxes/route-mirror.rst => examples/route-mirror/example.rst (100%) rename {docs/root/start/sandboxes => examples/single-page-app}/_static/spa-cookies.png (100%) rename {docs/root/start/sandboxes => examples/single-page-app}/_static/spa-github-oauth.png (100%) rename {docs/root/start/sandboxes => examples/single-page-app}/_static/spa-login-github.png (100%) rename {docs/root/start/sandboxes => examples/single-page-app}/_static/spa-login.png (100%) rename {docs/root/start/sandboxes => examples/single-page-app}/_static/spa-resources.png (100%) rename docs/root/start/sandboxes/single-page-app.rst => examples/single-page-app/example.rst (98%) rename {docs/root/start/sandboxes => examples/skywalking}/_static/skywalking-services.png (100%) rename {docs/root/start/sandboxes => examples/skywalking}/_static/skywalking-topology.png (100%) rename {docs/root/start/sandboxes => examples/skywalking}/_static/skywalking-trace.png (100%) rename docs/root/start/sandboxes/skywalking.rst => examples/skywalking/example.rst (95%) rename docs/root/start/sandboxes/tls-inspector.rst => examples/tls-inspector/example.rst (100%) rename docs/root/start/sandboxes/tls-sni.rst => examples/tls-sni/example.rst (100%) rename docs/root/start/sandboxes/tls.rst => examples/tls/example.rst (100%) rename docs/root/start/sandboxes/udp.rst => examples/udp/example.rst (100%) rename docs/root/start/sandboxes/wasm-cc.rst => examples/wasm-cc/example.rst (100%) rename docs/root/start/sandboxes/websocket.rst => examples/websocket/example.rst (100%) rename {docs/root/start/sandboxes => examples/zipkin}/_static/zipkin-ui-dependency.png (100%) rename {docs/root/start/sandboxes => examples/zipkin}/_static/zipkin-ui.png (100%) rename docs/root/start/sandboxes/zipkin.rst => examples/zipkin/example.rst (96%) rename docs/root/start/sandboxes/zstd.rst => examples/zstd/example.rst (100%) diff --git a/docs/BUILD b/docs/BUILD index 5859a9dcbe91..46df13e77e19 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -209,17 +209,9 @@ pkg_files( strip_prefix = "/configs", ) -pkg_files( - name = "examples_rst", - srcs = ["//examples:files"], - prefix = "start/sandboxes/_include", - strip_prefix = "/examples", -) - pkg_filegroup( name = "rst_files", srcs = [ - ":examples_rst", ":repo_configs", ":sphinx_base", ":sphinx_inventories", @@ -244,6 +236,7 @@ pkg_tar( ":extensions_security_rst", ":external_deps_rst", ":version_history_rst", + "//examples:docs", ], ) diff --git a/docs/root/start/sandboxes/index.rst b/docs/root/start/sandboxes/index.rst index 450fd5176fd2..e84bd196d74c 100644 --- a/docs/root/start/sandboxes/index.rst +++ b/docs/root/start/sandboxes/index.rst @@ -42,44 +42,4 @@ Before you begin you will need to install the sandbox environment. The following sandboxes are available: -.. toctree:: - :maxdepth: 1 - - brotli - cache - cors - csrf - double-proxy - dynamic-configuration-filesystem - dynamic-configuration-control-plane - ext_authz - fault_injection - front_proxy - golang-http - golang-network - grpc_bridge - gzip - jaeger_tracing - kafka - load_reporting_service - locality_load_balancing - local_ratelimit - lua-cluster-specifier - lua - mysql - opentelemetry - postgres - rbac - redis - route-mirror - single-page-app - skywalking - tls-inspector - tls-sni - tls - udp - wasm-cc - websocket - win32_front_proxy - zipkin - zstd +.. include:: toctree.rst diff --git a/docs/root/start/sandboxes/win32_front_proxy.rst b/docs/root/start/sandboxes/win32_front_proxy.rst deleted file mode 100644 index 2342bacc7eb3..000000000000 --- a/docs/root/start/sandboxes/win32_front_proxy.rst +++ /dev/null @@ -1,354 +0,0 @@ -Windows based Front proxy -========================= - -.. include:: ../../_include/windows_support_ended.rst - -.. sidebar:: Requirements - - .. include:: _include/docker-env-setup-link.rst - -To get a flavor of what Envoy has to offer on Windows, we are releasing a -`docker compose `_ sandbox that deploys a front Envoy and a -couple of services (simple Flask apps) colocated with a running service Envoy. - -The three containers will be deployed inside a virtual network called ``envoymesh``. - -Below you can see a graphic showing the docker compose deployment: - -.. image:: /_static/docker_compose_front_proxy.svg - :width: 100% - -All incoming requests are routed via the front Envoy, which is acting as a reverse proxy sitting on -the edge of the ``envoymesh`` network. Port ``8080``, ``8443``, and ``8001`` are exposed by docker -compose (see :download:`docker-compose.yaml <_include/front-proxy/docker-compose.yaml>`) to handle -``HTTP``, ``HTTPS`` calls to the services and requests to ``/admin`` respectively. - -Moreover, notice that all traffic routed by the front Envoy to the service containers is actually -routed to the service Envoys (routes setup in :download:`envoy.yaml <_include/front-proxy/envoy.yaml>`). - -In turn the service Envoys route the request to the Flask app via the loopback -address (routes setup in :download:`service-envoy.yaml <_include/front-proxy/service-envoy.yaml>`). This -setup illustrates the advantage of running service Envoys collocated with your services: all -requests are handled by the service Envoy, and efficiently routed to your services. - -Step 1: Start all of our containers -*********************************** - -Change to the ``examples/front-proxy`` directory. - -.. code-block:: console - - PS> $PWD - D:\envoy\examples\win32-front-proxy - PS> docker-compose build --pull - PS> docker-compose up -d - PS> docker-compose ps - Name Command State Ports - ------------------------------------------------------------------------------------------------------------------------------------------------------------ - envoy-front-proxy_front-envoy_1 powershell.exe ./start_env ... Up 10000/tcp, 0.0.0.0:8003->8003/tcp, 0.0.0.0:8080->8080/tcp, 0.0.0.0:8443->8443/tcp - envoy-front-proxy_service1_1 powershell.exe ./start_ser ... Up 10000/tcp - envoy-front-proxy_service2_1 powershell.exe ./start_ser ... Up 10000/tcp - -Step 2: Test Envoy's routing capabilities -***************************************** - -You can now send a request to both services via the ``front-envoy``. - -For ``service1``: - -.. code-block:: console - - PS> curl -v localhost:8080/service/1 - * Trying ::1... - * TCP_NODELAY set - * Trying 127.0.0.1... - * TCP_NODELAY set - * Connected to localhost (127.0.0.1) port 8080 (#0) - > GET /service/1 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.55.1 - > Accept: */* - > - < HTTP/1.1 200 OK - < content-type: text/html; charset=utf-8 - < content-length: 92 - < server: envoy - < date: Wed, 05 May 2021 05:55:55 GMT - < x-envoy-upstream-service-time: 18 - < - Hello from behind Envoy (service 1)! hostname: 8a45bba91d83 resolvedhostname: 172.30.97.237 - * Connection #0 to host localhost left intact - -For ``service2``: - -.. code-block:: console - - PS> curl -v localhost:8080/service/2 - * Trying ::1... - * TCP_NODELAY set - * Trying 127.0.0.1... - * TCP_NODELAY set - * Connected to localhost (127.0.0.1) port 8080 (#0) - > GET /service/2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.55.1 - > Accept: */* - > - < HTTP/1.1 200 OK - < content-type: text/html; charset=utf-8 - < content-length: 93 - < server: envoy - < date: Wed, 05 May 2021 05:57:03 GMT - < x-envoy-upstream-service-time: 14 - < - Hello from behind Envoy (service 2)! hostname: 51e28eb3c8b8 resolvedhostname: 172.30.109.113 - * Connection #0 to host localhost left intact - -Notice that each request, while sent to the front Envoy, was correctly routed to the respective -application. - -We can also use ``HTTPS`` to call services behind the front Envoy. For example, calling ``service1``: - -.. code-block:: console - - PS> curl https://localhost:8443/service/1 -k -v - * Trying ::1... - * TCP_NODELAY set - * Trying 127.0.0.1... - * TCP_NODELAY set - * Connected to localhost (127.0.0.1) port 8443 (#0) - * schannel: SSL/TLS connection with localhost port 8443 (step 1/3) - * schannel: disabled server certificate revocation checks - * schannel: verifyhost setting prevents Schannel from comparing the supplied target name with the subject names in server certificates. - * schannel: sending initial handshake data: sending 171 bytes... - * schannel: sent initial handshake data: sent 171 bytes - * schannel: SSL/TLS connection with localhost port 8443 (step 2/3) - * schannel: failed to receive handshake, need more data - * schannel: SSL/TLS connection with localhost port 8443 (step 2/3) - * schannel: encrypted data got 1081 - * schannel: encrypted data buffer: offset 1081 length 4096 - * schannel: sending next handshake data: sending 93 bytes... - * schannel: SSL/TLS connection with localhost port 8443 (step 2/3) - * schannel: encrypted data got 258 - * schannel: encrypted data buffer: offset 258 length 4096 - * schannel: SSL/TLS handshake complete - * schannel: SSL/TLS connection with localhost port 8443 (step 3/3) - * schannel: stored credential handle in session cache - > GET /service/1 HTTP/1.1 - > Host: localhost:8443 - > User-Agent: curl/7.55.1 - > Accept: */* - > - * schannel: client wants to read 102400 bytes - * schannel: encdata_buffer resized 103424 - * schannel: encrypted data buffer: offset 0 length 103424 - * schannel: encrypted data got 286 - * schannel: encrypted data buffer: offset 286 length 103424 - * schannel: decrypted data length: 257 - * schannel: decrypted data added: 257 - * schannel: decrypted data cached: offset 257 length 102400 - * schannel: encrypted data buffer: offset 0 length 103424 - * schannel: decrypted data buffer: offset 257 length 102400 - * schannel: schannel_recv cleanup - * schannel: decrypted data returned 257 - * schannel: decrypted data buffer: offset 0 length 102400 - < HTTP/1.1 200 OK - < content-type: text/html; charset=utf-8 - < content-length: 92 - < server: envoy - < date: Wed, 05 May 2021 05:57:45 GMT - < x-envoy-upstream-service-time: 3 - < - Hello from behind Envoy (service 1)! hostname: 8a45bba91d83 resolvedhostname: 172.30.97.237 - * Connection #0 to host localhost left intact - -Step 3: Test Envoy's load balancing capabilities -************************************************ - -Now let's scale up our ``service1`` nodes to demonstrate the load balancing abilities of Envoy: - -.. code-block:: console - - PS> docker-compose scale service1=3 - Creating and starting example_service1_2 ... done - Creating and starting example_service1_3 ... done - -Now if we send a request to ``service1`` multiple times, the front Envoy will load balance the -requests by doing a round robin of the three ``service1`` machines: - -.. code-block:: console - - PS> curl -v localhost:8080/service/1 - * Trying ::1... - * TCP_NODELAY set - * Trying 127.0.0.1... - * TCP_NODELAY set - * Connected to localhost (127.0.0.1) port 8080 (#0) - > GET /service/1 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.55.1 - > Accept: */* - > - < HTTP/1.1 200 OK - < content-type: text/html; charset=utf-8 - < content-length: 93 - < server: envoy - < date: Wed, 05 May 2021 05:58:40 GMT - < x-envoy-upstream-service-time: 22 - < - Hello from behind Envoy (service 1)! hostname: 8d2359ee21a8 resolvedhostname: 172.30.101.143 - * Connection #0 to host localhost left intact - PS> curl -v localhost:8080/service/1 - * Trying ::1... - * TCP_NODELAY set - * Trying 127.0.0.1... - * TCP_NODELAY set - * Connected to localhost (127.0.0.1) port 8080 (#0) - > GET /service/1 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.55.1 - > Accept: */* - > - < HTTP/1.1 200 OK - < content-type: text/html; charset=utf-8 - < content-length: 91 - < server: envoy - < date: Wed, 05 May 2021 05:58:43 GMT - < x-envoy-upstream-service-time: 11 - < - Hello from behind Envoy (service 1)! hostname: 41e1141eebf4 resolvedhostname: 172.30.96.11 - * Connection #0 to host localhost left intact - PS> curl -v localhost:8080/service/1 - * Trying ::1... - * TCP_NODELAY set - * Trying 127.0.0.1... - * TCP_NODELAY set - * Connected to localhost (127.0.0.1) port 8080 (#0) - > GET /service/1 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.55.1 - > Accept: */* - > - < HTTP/1.1 200 OK - < content-type: text/html; charset=utf-8 - < content-length: 92 - < server: envoy - < date: Wed, 05 May 2021 05:58:44 GMT - < x-envoy-upstream-service-time: 7 - < - Hello from behind Envoy (service 1)! hostname: 8a45bba91d83 resolvedhostname: 172.30.97.237 - * Connection #0 to host localhost left intact - -Step 4: 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 -can use ``docker-compose exec /bin/bash``. For example we can -enter the ``front-envoy`` container, and ``curl`` for services locally: - -.. code-block:: console - - PS> docker-compose exec front-envoy powershell - PS C:\> (curl -UseBasicParsing http://localhost:8080/service/1).Content - Hello from behind Envoy (service 1)! hostname: 41e1141eebf4 resolvedhostname: 172.30.96.11 - - PS C:\> (curl -UseBasicParsing http://localhost:8080/service/1).Content - Hello from behind Envoy (service 1)! hostname: 8a45bba91d83 resolvedhostname: 172.30.97.237 - - PS C:\> (curl -UseBasicParsing http://localhost:8080/service/1).Content - Hello from behind Envoy (service 1)! hostname: 8d2359ee21a8 resolvedhostname: 172.30.101.143 - - -Step 5: Enter container and curl admin interface -************************************************ - -When Envoy runs it also attaches an ``admin`` to your desired port. - -In the example configs the admin listener is bound to port ``8001``. - -We can ``curl`` it to gain useful information: - -- :ref:`/server_info ` provides information about the Envoy version you are running. -- :ref:`/stats ` provides statistics about the Envoy server. - -In the example we can enter the ``front-envoy`` container to query admin: - -.. code-block:: console - - PS> docker-compose exec front-envoy powershell - PS C:\> (curl http://localhost:8003/server_info -UseBasicParsing).Content - -.. code-block:: json - - { - "version": "093e2ffe046313242144d0431f1bb5cf18d82544/1.15.0-dev/Clean/RELEASE/BoringSSL", - "state": "LIVE", - "hot_restart_version": "11.104", - "command_line_options": { - "base_id": "0", - "use_dynamic_base_id": false, - "base_id_path": "", - "concurrency": 8, - "config_path": "/etc/front-envoy.yaml", - "config_yaml": "", - "allow_unknown_static_fields": false, - "reject_unknown_dynamic_fields": false, - "ignore_unknown_dynamic_fields": false, - "admin_address_path": "", - "local_address_ip_version": "v4", - "log_level": "info", - "component_log_level": "", - "log_format": "[%Y-%m-%d %T.%e][%t][%l][%n] [%g:%#] %v", - "log_format_escaped": false, - "log_path": "", - "service_cluster": "front-proxy", - "service_node": "", - "service_zone": "", - "drain_strategy": "Gradual", - "mode": "Serve", - "disable_hot_restart": false, - "enable_mutex_tracing": false, - "restart_epoch": 0, - "cpuset_threads": false, - "disabled_extensions": [], - "bootstrap_version": 0, - "hidden_envoy_deprecated_max_stats": "0", - "hidden_envoy_deprecated_max_obj_name_len": "0", - "file_flush_interval": "10s", - "drain_time": "600s", - "parent_shutdown_time": "900s" - }, - "uptime_current_epoch": "188s", - "uptime_all_epochs": "188s" - } - -.. code-block:: console - - PS C:\> (curl http://localhost:8003/stats -UseBasicParsing).Content - cluster.service1.external.upstream_rq_200: 7 - ... - cluster.service1.membership_change: 2 - cluster.service1.membership_total: 3 - ... - cluster.service1.upstream_cx_http2_total: 3 - ... - cluster.service1.upstream_rq_total: 7 - ... - cluster.service2.external.upstream_rq_200: 2 - ... - cluster.service2.membership_change: 1 - cluster.service2.membership_total: 1 - ... - cluster.service2.upstream_cx_http2_total: 1 - ... - cluster.service2.upstream_rq_total: 2 - ... - -Notice that we can get the number of members of upstream clusters, number of requests fulfilled by -them, information about http ingress, and a plethora of other useful stats. - -.. seealso:: - - :ref:`Envoy admin quick start guide ` - Quick start guide to the Envoy admin interface. diff --git a/examples/BUILD b/examples/BUILD index 61024d861c46..bcf5f121b8ef 100644 --- a/examples/BUILD +++ b/examples/BUILD @@ -1,3 +1,5 @@ +load("@rules_pkg//pkg:mappings.bzl", "pkg_files") +load("@rules_pkg//pkg:pkg.bzl", "pkg_tar") load( "//bazel:envoy_build_system.bzl", "envoy_package", @@ -51,6 +53,38 @@ filegroup( srcs = glob(["_extra_certs/*.pem"]), ) +filegroup( + name = "docs_rst", + srcs = glob(["**/example.rst"]) + ["//examples/wasm-cc:example.rst"], +) + +pkg_files( + name = "examples_files", + srcs = [":files"], + prefix = "_include", + strip_prefix = "/examples", +) + +genrule( + name = "examples_docs", + srcs = [":docs_rst"], + outs = ["examples_docs.tar.gz"], + cmd = """ + TEMP=$$(mktemp -d) + for location in $(locations :docs_rst); do + example=$$(echo $$location | cut -d/ -f2) + cp -a $$location "$${TEMP}/$${example}.rst" + echo " $${example}" >> "$${TEMP}/_toctree.rst" + done + echo ".. toctree::" > "$${TEMP}/toctree.rst" + echo " :maxdepth: 1" >> "$${TEMP}/toctree.rst" + echo "" >> "$${TEMP}/toctree.rst" + cat "$${TEMP}/_toctree.rst" | sort >> "$${TEMP}/toctree.rst" + rm "$${TEMP}/_toctree.rst" + tar czf $@ -C $${TEMP} . + """, +) + filegroup( name = "lua", srcs = glob(["**/*.lua"]), @@ -58,7 +92,23 @@ filegroup( filegroup( name = "files", - srcs = glob(["**/*"]) + [ + srcs = glob( + [ + "**/*", + ], + exclude = [ + "**/node_modules/**", + "**/*.rst", + ], + ) + [ "//examples/wasm-cc:files", ], ) + +pkg_tar( + name = "docs", + srcs = [":examples_files"], + extension = "tar.gz", + package_dir = "start/sandboxes", + deps = [":examples_docs"], +) diff --git a/docs/root/start/sandboxes/brotli.rst b/examples/brotli/example.rst similarity index 100% rename from docs/root/start/sandboxes/brotli.rst rename to examples/brotli/example.rst diff --git a/docs/root/start/sandboxes/cache.rst b/examples/cache/example.rst similarity index 100% rename from docs/root/start/sandboxes/cache.rst rename to examples/cache/example.rst diff --git a/docs/root/start/sandboxes/cors.rst b/examples/cors/example.rst similarity index 100% rename from docs/root/start/sandboxes/cors.rst rename to examples/cors/example.rst diff --git a/docs/root/start/sandboxes/csrf.rst b/examples/csrf/example.rst similarity index 100% rename from docs/root/start/sandboxes/csrf.rst rename to examples/csrf/example.rst diff --git a/docs/root/start/sandboxes/double-proxy.rst b/examples/double-proxy/example.rst similarity index 100% rename from docs/root/start/sandboxes/double-proxy.rst rename to examples/double-proxy/example.rst diff --git a/docs/root/start/sandboxes/_include/dynamic-config-cp/response-config-active-clusters-updated.json b/examples/dynamic-config-cp/_include/response-config-active-clusters-updated.json similarity index 100% rename from docs/root/start/sandboxes/_include/dynamic-config-cp/response-config-active-clusters-updated.json rename to examples/dynamic-config-cp/_include/response-config-active-clusters-updated.json diff --git a/docs/root/start/sandboxes/_include/dynamic-config-cp/response-config-active-clusters.json b/examples/dynamic-config-cp/_include/response-config-active-clusters.json similarity index 100% rename from docs/root/start/sandboxes/_include/dynamic-config-cp/response-config-active-clusters.json rename to examples/dynamic-config-cp/_include/response-config-active-clusters.json diff --git a/docs/root/start/sandboxes/_include/dynamic-config-cp/response-config-cluster.json b/examples/dynamic-config-cp/_include/response-config-cluster.json similarity index 100% rename from docs/root/start/sandboxes/_include/dynamic-config-cp/response-config-cluster.json rename to examples/dynamic-config-cp/_include/response-config-cluster.json diff --git a/docs/root/start/sandboxes/dynamic-configuration-control-plane.rst b/examples/dynamic-config-cp/example.rst similarity index 92% rename from docs/root/start/sandboxes/dynamic-configuration-control-plane.rst rename to examples/dynamic-config-cp/example.rst index d0c0c908102d..53968bee3c50 100644 --- a/docs/root/start/sandboxes/dynamic-configuration-control-plane.rst +++ b/examples/dynamic-config-cp/example.rst @@ -61,7 +61,7 @@ configuration and you should see the cluster named ``xds_cluster`` configured fo $ curl -s http://localhost:19000/config_dump | jq '.configs[1].static_clusters' -.. literalinclude:: _include/dynamic-config-cp/response-config-cluster.json +.. literalinclude:: /start/sandboxes/_include/dynamic-config-cp/_include/response-config-cluster.json :language: json :emphasize-lines: 10, 18-19 @@ -123,7 +123,7 @@ configuration, you should see it is configured with the ``example_proxy_cluster` $ curl -s http://localhost:19000/config_dump | jq '.configs[1].dynamic_active_clusters' -.. literalinclude:: _include/dynamic-config-cp/response-config-active-clusters.json +.. literalinclude:: /start/sandboxes/_include/dynamic-config-cp/_include/response-config-active-clusters.json :language: json :emphasize-lines: 3, 11, 19-20 @@ -147,7 +147,7 @@ Step 7: Edit ``go`` file and restart the control plane ****************************************************** The example setup starts the ``go-control-plane`` -service with a custom :download:`resource.go <_include/dynamic-config-cp/resource.go>` file which +service with a custom :download:`resource.go ` file which specifies the configuration provided to Envoy. Update this to have Envoy proxy instead to ``service2``. @@ -155,7 +155,7 @@ Update this to have Envoy proxy instead to ``service2``. Edit ``resource.go`` in the dynamic configuration example folder and change the ``UpstreamHost`` from ``service1`` to ``service2``: -.. literalinclude:: _include/dynamic-config-cp/resource.go +.. literalinclude:: /start/sandboxes/_include/dynamic-config-cp/resource.go :language: go :lines: 34-43 :lineno-start: 35 @@ -165,7 +165,7 @@ from ``service1`` to ``service2``: Further down in this file you must also change the configuration snapshot version number from ``"1"`` to ``"2"`` to ensure Envoy sees the configuration as newer: -.. literalinclude:: _include/dynamic-config-cp/resource.go +.. literalinclude:: /start/sandboxes/_include/dynamic-config-cp/resource.go :language: go :lineno-start: 175 :lines: 174-186 @@ -198,7 +198,7 @@ is configured to proxy to ``service2``: $ curl -s http://localhost:19000/config_dump | jq '.configs[1].dynamic_active_clusters' -.. literalinclude:: _include/dynamic-config-cp/response-config-active-clusters-updated.json +.. literalinclude:: /start/sandboxes/_include/dynamic-config-cp/_include/response-config-active-clusters-updated.json :language: json :emphasize-lines: 3, 11, 19-20 diff --git a/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters-updated.json b/examples/dynamic-config-fs/_include/response-config-active-clusters-updated.json similarity index 100% rename from docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters-updated.json rename to examples/dynamic-config-fs/_include/response-config-active-clusters-updated.json diff --git a/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters.json b/examples/dynamic-config-fs/_include/response-config-active-clusters.json similarity index 100% rename from docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters.json rename to examples/dynamic-config-fs/_include/response-config-active-clusters.json diff --git a/docs/root/start/sandboxes/dynamic-configuration-filesystem.rst b/examples/dynamic-config-fs/example.rst similarity index 88% rename from docs/root/start/sandboxes/dynamic-configuration-filesystem.rst rename to examples/dynamic-config-fs/example.rst index 73da55505409..4935cd5bbe6e 100644 --- a/docs/root/start/sandboxes/dynamic-configuration-filesystem.rst +++ b/examples/dynamic-config-fs/example.rst @@ -70,7 +70,7 @@ configuration, you should see it is configured with the ``example_proxy_cluster` $ curl -s http://localhost:19000/config_dump | jq -r '.configs[1].dynamic_active_clusters' -.. literalinclude:: _include/dynamic-config-fs/response-config-active-clusters.json +.. literalinclude:: /start/sandboxes/_include/dynamic-config-fs/_include/response-config-active-clusters.json :language: json :emphasize-lines: 10, 18-19 @@ -79,15 +79,15 @@ Step 4: Replace ``cds.yaml`` inside the container to update upstream cluster The example setup provides Envoy with two dynamic configuration files: -- :download:`configs/cds.yaml <_include/dynamic-config-fs/configs/cds.yaml>` to provide a :ref:`Cluster +- :download:`configs/cds.yaml ` to provide a :ref:`Cluster discovery service (CDS) `. -- :download:`configs/lds.yaml <_include/dynamic-config-fs/configs/lds.yaml>` to provide a :ref:`Listener +- :download:`configs/lds.yaml ` to provide a :ref:`Listener discovery service (LDS) `. Edit ``cds.yaml`` inside the container and change the cluster address from ``service1`` to ``service2``: -.. literalinclude:: _include/dynamic-config-fs/configs/cds.yaml +.. literalinclude:: /start/sandboxes/_include/dynamic-config-fs/configs/cds.yaml :language: yaml :linenos: :lines: 6-13 @@ -121,7 +121,7 @@ the ``example_proxy_cluster`` should now be configured to proxy to ``service2``: $ curl -s http://localhost:19000/config_dump | jq -r '.configs[1].dynamic_active_clusters' -.. literalinclude:: _include/dynamic-config-fs/response-config-active-clusters-updated.json +.. literalinclude:: /start/sandboxes/_include/dynamic-config-fs/_include/response-config-active-clusters-updated.json :language: json :emphasize-lines: 10, 18-19 diff --git a/docs/root/start/sandboxes/ext_authz.rst b/examples/ext_authz/example.rst similarity index 100% rename from docs/root/start/sandboxes/ext_authz.rst rename to examples/ext_authz/example.rst diff --git a/docs/root/start/sandboxes/fault_injection.rst b/examples/fault-injection/example.rst similarity index 100% rename from docs/root/start/sandboxes/fault_injection.rst rename to examples/fault-injection/example.rst diff --git a/docs/root/start/sandboxes/front_proxy.rst b/examples/front-proxy/example.rst similarity index 100% rename from docs/root/start/sandboxes/front_proxy.rst rename to examples/front-proxy/example.rst diff --git a/docs/root/start/sandboxes/golang-http.rst b/examples/golang-http/example.rst similarity index 100% rename from docs/root/start/sandboxes/golang-http.rst rename to examples/golang-http/example.rst diff --git a/docs/root/start/sandboxes/golang-network.rst b/examples/golang-network/example.rst similarity index 100% rename from docs/root/start/sandboxes/golang-network.rst rename to examples/golang-network/example.rst diff --git a/docs/root/start/sandboxes/grpc_bridge.rst b/examples/grpc-bridge/example.rst similarity index 100% rename from docs/root/start/sandboxes/grpc_bridge.rst rename to examples/grpc-bridge/example.rst diff --git a/docs/root/start/sandboxes/gzip.rst b/examples/gzip/example.rst similarity index 100% rename from docs/root/start/sandboxes/gzip.rst rename to examples/gzip/example.rst diff --git a/docs/root/start/sandboxes/jaeger_tracing.rst b/examples/jaeger-tracing/example.rst similarity index 100% rename from docs/root/start/sandboxes/jaeger_tracing.rst rename to examples/jaeger-tracing/example.rst diff --git a/docs/root/start/sandboxes/kafka.rst b/examples/kafka/example.rst similarity index 100% rename from docs/root/start/sandboxes/kafka.rst rename to examples/kafka/example.rst diff --git a/docs/root/start/sandboxes/load_reporting_service.rst b/examples/load-reporting-service/example.rst similarity index 100% rename from docs/root/start/sandboxes/load_reporting_service.rst rename to examples/load-reporting-service/example.rst diff --git a/docs/root/start/sandboxes/local_ratelimit.rst b/examples/local_ratelimit/example.rst similarity index 100% rename from docs/root/start/sandboxes/local_ratelimit.rst rename to examples/local_ratelimit/example.rst diff --git a/docs/root/start/sandboxes/locality_load_balancing.rst b/examples/locality-load-balancing/example.rst similarity index 100% rename from docs/root/start/sandboxes/locality_load_balancing.rst rename to examples/locality-load-balancing/example.rst diff --git a/docs/root/start/sandboxes/lua-cluster-specifier.rst b/examples/lua-cluster-specifier/example.rst similarity index 100% rename from docs/root/start/sandboxes/lua-cluster-specifier.rst rename to examples/lua-cluster-specifier/example.rst diff --git a/docs/root/start/sandboxes/lua.rst b/examples/lua/example.rst similarity index 100% rename from docs/root/start/sandboxes/lua.rst rename to examples/lua/example.rst diff --git a/docs/root/start/sandboxes/mysql.rst b/examples/mysql/example.rst similarity index 100% rename from docs/root/start/sandboxes/mysql.rst rename to examples/mysql/example.rst diff --git a/docs/root/start/sandboxes/opentelemetry.rst b/examples/opentelemetry/example.rst similarity index 100% rename from docs/root/start/sandboxes/opentelemetry.rst rename to examples/opentelemetry/example.rst diff --git a/docs/root/start/sandboxes/postgres.rst b/examples/postgres/example.rst similarity index 100% rename from docs/root/start/sandboxes/postgres.rst rename to examples/postgres/example.rst diff --git a/docs/root/start/sandboxes/rbac.rst b/examples/rbac/example.rst similarity index 100% rename from docs/root/start/sandboxes/rbac.rst rename to examples/rbac/example.rst diff --git a/docs/root/start/sandboxes/redis.rst b/examples/redis/example.rst similarity index 100% rename from docs/root/start/sandboxes/redis.rst rename to examples/redis/example.rst diff --git a/docs/root/start/sandboxes/route-mirror.rst b/examples/route-mirror/example.rst similarity index 100% rename from docs/root/start/sandboxes/route-mirror.rst rename to examples/route-mirror/example.rst diff --git a/docs/root/start/sandboxes/_static/spa-cookies.png b/examples/single-page-app/_static/spa-cookies.png similarity index 100% rename from docs/root/start/sandboxes/_static/spa-cookies.png rename to examples/single-page-app/_static/spa-cookies.png diff --git a/docs/root/start/sandboxes/_static/spa-github-oauth.png b/examples/single-page-app/_static/spa-github-oauth.png similarity index 100% rename from docs/root/start/sandboxes/_static/spa-github-oauth.png rename to examples/single-page-app/_static/spa-github-oauth.png diff --git a/docs/root/start/sandboxes/_static/spa-login-github.png b/examples/single-page-app/_static/spa-login-github.png similarity index 100% rename from docs/root/start/sandboxes/_static/spa-login-github.png rename to examples/single-page-app/_static/spa-login-github.png diff --git a/docs/root/start/sandboxes/_static/spa-login.png b/examples/single-page-app/_static/spa-login.png similarity index 100% rename from docs/root/start/sandboxes/_static/spa-login.png rename to examples/single-page-app/_static/spa-login.png diff --git a/docs/root/start/sandboxes/_static/spa-resources.png b/examples/single-page-app/_static/spa-resources.png similarity index 100% rename from docs/root/start/sandboxes/_static/spa-resources.png rename to examples/single-page-app/_static/spa-resources.png diff --git a/docs/root/start/sandboxes/single-page-app.rst b/examples/single-page-app/example.rst similarity index 98% rename from docs/root/start/sandboxes/single-page-app.rst rename to examples/single-page-app/example.rst index d408748155a7..ea702bda6f5f 100644 --- a/docs/root/start/sandboxes/single-page-app.rst +++ b/examples/single-page-app/example.rst @@ -145,7 +145,7 @@ Step 4: Browse to the dev app and login The development app should now be available at http://localhost:10001 and provide a login button: -.. image:: /start/sandboxes/_static/spa-login.png +.. image:: /start/sandboxes/_include/single-page-app/_static/spa-login.png :align: center .. note:: @@ -212,7 +212,7 @@ Envoy then uses this authorization code with its client secret to confirm author Once logged in, you should be able to make queries to the API using the OAuth credentials: -.. image:: /start/sandboxes/_static/spa-resources.png +.. image:: /start/sandboxes/_include/single-page-app/_static/spa-resources.png :align: center .. warning:: @@ -252,7 +252,7 @@ For the sandbox app, :ref:`forward_bearer_token ` is set, and so Envoy also passes the acquired access token back to the user as a cookie: -.. image:: /start/sandboxes/_static/spa-cookies.png +.. image:: /start/sandboxes/_include/single-page-app/_static/spa-cookies.png :align: center This cookie is then passed through Envoy in any subsequent requests to the proxied Myhub API: @@ -476,7 +476,7 @@ more control and is generally preferable. This can be done either at the `user `_ or organization levels: -.. image:: /start/sandboxes/_static/spa-github-oauth.png +.. image:: /start/sandboxes/_include/single-page-app/_static/spa-github-oauth.png :align: center .. note:: @@ -605,7 +605,7 @@ Browse to the production server https://localhost:10000 You can now log in and use the `Github APIs `__.: -.. image:: /start/sandboxes/_static/spa-login-github.png +.. image:: /start/sandboxes/_include/single-page-app/_static/spa-login-github.png :align: center .. seealso:: diff --git a/docs/root/start/sandboxes/_static/skywalking-services.png b/examples/skywalking/_static/skywalking-services.png similarity index 100% rename from docs/root/start/sandboxes/_static/skywalking-services.png rename to examples/skywalking/_static/skywalking-services.png diff --git a/docs/root/start/sandboxes/_static/skywalking-topology.png b/examples/skywalking/_static/skywalking-topology.png similarity index 100% rename from docs/root/start/sandboxes/_static/skywalking-topology.png rename to examples/skywalking/_static/skywalking-topology.png diff --git a/docs/root/start/sandboxes/_static/skywalking-trace.png b/examples/skywalking/_static/skywalking-trace.png similarity index 100% rename from docs/root/start/sandboxes/_static/skywalking-trace.png rename to examples/skywalking/_static/skywalking-trace.png diff --git a/docs/root/start/sandboxes/skywalking.rst b/examples/skywalking/example.rst similarity index 95% rename from docs/root/start/sandboxes/skywalking.rst rename to examples/skywalking/example.rst index 3b0ffb77151a..d3c8baddc3d7 100644 --- a/docs/root/start/sandboxes/skywalking.rst +++ b/examples/skywalking/example.rst @@ -109,15 +109,15 @@ You should see the Skywalking dashboard. You may need to wait a moment for the traces to be added, but clicking on ``General Service > Services``, you should see the Envoy services listed. -.. image:: /start/sandboxes/_static/skywalking-services.png +.. image:: /start/sandboxes/_include/skywalking/_static/skywalking-services.png From here you can explore the metrics and views that skywalking offers, such as the ``Topology``: -.. image:: /start/sandboxes/_static/skywalking-topology.png +.. image:: /start/sandboxes/_include/skywalking/_static/skywalking-topology.png You can also view tracing information for the requests that you made: -.. image:: /start/sandboxes/_static/skywalking-trace.png +.. image:: /start/sandboxes/_include/skywalking/_static/skywalking-trace.png .. seealso:: diff --git a/docs/root/start/sandboxes/tls-inspector.rst b/examples/tls-inspector/example.rst similarity index 100% rename from docs/root/start/sandboxes/tls-inspector.rst rename to examples/tls-inspector/example.rst diff --git a/docs/root/start/sandboxes/tls-sni.rst b/examples/tls-sni/example.rst similarity index 100% rename from docs/root/start/sandboxes/tls-sni.rst rename to examples/tls-sni/example.rst diff --git a/docs/root/start/sandboxes/tls.rst b/examples/tls/example.rst similarity index 100% rename from docs/root/start/sandboxes/tls.rst rename to examples/tls/example.rst diff --git a/docs/root/start/sandboxes/udp.rst b/examples/udp/example.rst similarity index 100% rename from docs/root/start/sandboxes/udp.rst rename to examples/udp/example.rst diff --git a/examples/wasm-cc/BUILD b/examples/wasm-cc/BUILD index d8a2c77e2c9f..2ea0b7d13906 100644 --- a/examples/wasm-cc/BUILD +++ b/examples/wasm-cc/BUILD @@ -9,6 +9,8 @@ licenses(["notice"]) # Apache 2 envoy_package() +exports_files(["example.rst"]) + selects.config_setting_group( name = "include_wasm_config", match_all = [ @@ -46,5 +48,5 @@ envoy_wasm_cc_binary( filegroup( name = "files", - srcs = glob(["**/*"]), + srcs = glob(["**/*"], exclude = ["example.rst"]), ) diff --git a/docs/root/start/sandboxes/wasm-cc.rst b/examples/wasm-cc/example.rst similarity index 100% rename from docs/root/start/sandboxes/wasm-cc.rst rename to examples/wasm-cc/example.rst diff --git a/docs/root/start/sandboxes/websocket.rst b/examples/websocket/example.rst similarity index 100% rename from docs/root/start/sandboxes/websocket.rst rename to examples/websocket/example.rst diff --git a/docs/root/start/sandboxes/_static/zipkin-ui-dependency.png b/examples/zipkin/_static/zipkin-ui-dependency.png similarity index 100% rename from docs/root/start/sandboxes/_static/zipkin-ui-dependency.png rename to examples/zipkin/_static/zipkin-ui-dependency.png diff --git a/docs/root/start/sandboxes/_static/zipkin-ui.png b/examples/zipkin/_static/zipkin-ui.png similarity index 100% rename from docs/root/start/sandboxes/_static/zipkin-ui.png rename to examples/zipkin/_static/zipkin-ui.png diff --git a/docs/root/start/sandboxes/zipkin.rst b/examples/zipkin/example.rst similarity index 96% rename from docs/root/start/sandboxes/zipkin.rst rename to examples/zipkin/example.rst index 8d402711ae67..34c0f9c82e9e 100644 --- a/docs/root/start/sandboxes/zipkin.rst +++ b/examples/zipkin/example.rst @@ -112,11 +112,11 @@ and other contextual information. Note that Zipkin identifies the Envoy proxies by the name provided in the bootstrap ``node/cluster`` configuration. -.. image:: /start/sandboxes/_static/zipkin-ui.png +.. image:: /start/sandboxes/_include/zipkin/_static/zipkin-ui.png You can also explore the Zipkin dependency UI to view relationships between nodes and the path of traces. -.. image:: /start/sandboxes/_static/zipkin-ui-dependency.png +.. image:: /start/sandboxes/_include/zipkin/_static/zipkin-ui-dependency.png .. seealso:: diff --git a/docs/root/start/sandboxes/zstd.rst b/examples/zstd/example.rst similarity index 100% rename from docs/root/start/sandboxes/zstd.rst rename to examples/zstd/example.rst