Refactor documentation layout and define default ports (#688)

* define ports for each service * Improve and reorganise guide docs to better fit services * Add fix for print.html * Fix agones ports * fix xds port * implement changes from review
googleforgames · Jan 26, 2023 · ed34073 · ed34073
1 parent bf3b43a
commit ed34073
Show file tree

Hide file tree

Showing 51 changed files with 584 additions and 401 deletions.
diff --git a/agones/src/lib.rs b/agones/src/lib.rs
@@ -354,7 +354,7 @@ pub fn quilkin_container(
         liveness_probe: Some(Probe {
             http_get: Some(HTTPGetAction {
                 path: Some("/live".into()),
-                port: IntOrString::Int(9091),
+                port: IntOrString::Int(8000),
                 ..Default::default()
             }),
             initial_delay_seconds: Some(3),
@@ -364,7 +364,7 @@ pub fn quilkin_container(
         readiness_probe: Some(Probe {
             http_get: Some(HTTPGetAction {
                 path: Some("/ready".into()),
-                port: IntOrString::Int(9091),
+                port: IntOrString::Int(8000),
                 ..Default::default()
             }),
             initial_delay_seconds: Some(3),

diff --git a/agones/src/sidecar.rs b/agones/src/sidecar.rs
@@ -90,7 +90,7 @@ clusters:
         let mut gs = game_server();
 
         // reset ports to point at the Quilkin sidecar
-        gs.spec.ports[0].container_port = 7000;
+        gs.spec.ports[0].container_port = 7777;
         gs.spec.ports[0].container = Some("quilkin".into());
 
         // set the gameserver container to the simple-game-server container.

diff --git a/agones/src/xds.rs b/agones/src/xds.rs
@@ -275,7 +275,7 @@ filters:
         .to_vec();
         let mut container = quilkin_container(client, Some(args), None);
         container.ports = Some(vec![ContainerPort {
-            container_port: 7000,
+            container_port: 7777,
             ..Default::default()
         }]);
         let labels = BTreeMap::from([("role".to_string(), "xds".to_string())]);
@@ -318,8 +318,8 @@ filters:
                 selector: Some(labels),
                 ports: Some(vec![ServicePort {
                     protocol: Some("TCP".into()),
-                    port: 80,
-                    target_port: Some(IntOrString::Int(7000)),
+                    port: 7800,
+                    target_port: Some(IntOrString::Int(7800)),
                     ..Default::default()
                 }]),
                 ..Default::default()
@@ -350,7 +350,7 @@ filters:
         let config = r#"
 version: v1alpha1
 management_servers:
-  - address: http://quilkin-manage-agones:80
+  - address: http://quilkin-manage-agones:7800
 "#;
 
         let config_map = config_maps
@@ -362,12 +362,12 @@ management_servers:
             quilkin_container(client, Some(vec!["proxy".into()]), Some(mount_name.into()));
 
         // we'll use a host port, since spinning up a load balancer takes a long time.
-        // we know that port 7000 is open because this is an Agones cluster and it has associated
+        // we know that port 7777 is open because this is an Agones cluster and it has associated
         // firewall rules , and even if we conflict with a GameServer
         // the k8s scheduler will move us to another node.
         let host_port: u16 = 7005;
         container.ports = Some(vec![ContainerPort {
-            container_port: 7000,
+            container_port: 7777,
             host_port: Some(host_port as i32),
             protocol: Some("UDP".into()),
             ..Default::default()

diff --git a/build/Makefile b/build/Makefile
@@ -108,6 +108,7 @@ test-docs:
 			cargo doc --workspace --no-deps && cd docs && mdbook build --dest-dir /tmp/docs/book && \
 			cp -r "$(CARGO_TARGET_DIR)/doc" /tmp/docs/api && \
 			rm /tmp/docs/book/print.html && \
+			echo "<!doctype html>" > /tmp/docs/book/print.html && \
 			htmltest -c /workspace/docs/htmltest.yaml /tmp/docs'
 
 # Build all binaries, images and related artifacts

diff --git a/docs/book.toml b/docs/book.toml
@@ -29,4 +29,7 @@ use_env = true
 
 [preprocessor.variables.variables]
 
+[build]
+create-missing = false
+
 [output.html]
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -1,38 +1,42 @@
-# Summary
+[Introduction](./introduction.md)
+[Installation](./installation.md)
+[FAQ](./faq.md)
 
-- [Introduction](./introduction.md)
-- [Quickstart](./quickstart.md)
-    - [Netcat](./quickstarts/netcat.md)
-    - [Agones + Xonotic (Sidecar)](./quickstarts/agones-xonotic-sidecar.md)
-    - [Agones + Xonotic (xDS)](./quickstarts/agones-xonotic-xds.md)
-- [Usage](./using.md)
-  - [File Configuration](./file-configuration.md)
-- [Integrations](./integrations.md)
-- [Proxy Mode](./proxy-mode.md)
-  - [Concepts](proxy/concepts.md)
-  - [Filters](./filters.md)
-      - [Capture](proxy/filters/capture.md)
-      - [Compress](proxy/filters/compress.md)
-      - [Concatenate Bytes](proxy/filters/concatenate_bytes.md)
-      - [Debug](proxy/filters/debug.md)
-      - [Drop](proxy/filters/drop.md)
-      - [Firewall](proxy/filters/firewall.md)
-      - [Load Balancer](proxy/filters/load_balancer.md)
-      - [Local Rate Limit](proxy/filters/local_rate_limit.md)
-      - [Match](proxy/filters/match.md)
-      - [Pass](proxy/filters/pass.md)
-      - [Timestamp](proxy/filters/timestamp.md)
-      - [Token Router](proxy/filters/token_router.md)
-      - [Writing Custom Filters](proxy/filters/writing_custom_filters.md)
-  - [Metrics](proxy/metrics.md)
-  - [Maxmind](proxy/maxmind.md)
-- [xDS Management API](./xds.md)
-  - [Built-in xDS Providers](./xds/builtin.md)
-    - [Filesytem](./xds/providers/filesystem.md)
-    - [Agones](./xds/providers/agones.md)
-  - [Metrics](./xds/metrics.md)
-- [Administration](./admin.md)
-- [Client SDKs](./sdks.md)
-    - [Unreal Engine](./sdks/unreal-engine.md)
-- [Examples](./examples.md)
-- [FAQ](./faq.md)
+# Quickstart Guides
+- [Netcat](./deployment/quickstarts/netcat.md)
+- [Agones + Xonotic (Sidecar)](./deployment/quickstarts/agones-xonotic-sidecar.md)
+- [Agones + Xonotic (xDS)](./deployment/quickstarts/agones-xonotic-xds.md)
+
+# Services
+- [Proxy](./services/proxy.md)
+    - [Filters](./services/proxy/filters.md)
+        - [Capture](./services/proxy/filters/capture.md)
+        - [Compress](./services/proxy/filters/compress.md)
+        - [Concatenate Bytes](./services/proxy/filters/concatenate_bytes.md)
+        - [Debug](./services/proxy/filters/debug.md)
+        - [Drop](./services/proxy/filters/drop.md)
+        - [Firewall](./services/proxy/filters/firewall.md)
+        - [Load Balancer](./services/proxy/filters/load_balancer.md)
+        - [Local Rate Limit](./services/proxy/filters/local_rate_limit.md)
+        - [Match](./services/proxy/filters/match.md)
+        - [Pass](./services/proxy/filters/pass.md)
+        - [Timestamp](./services/proxy/filters/timestamp.md)
+        - [Token Router](./services/proxy/filters/token_router.md)
+        - [Writing Custom Filters](./services/proxy/filters/writing_custom_filters.md)
+    - [Metrics](./services/proxy/metrics.md)
+
+---
+
+- [Control Plane](./services/xds.md)
+    - [Metrics](./services/xds/metrics.md)
+    - [Providers]()
+        - [Agones](./services/xds/providers/agones.md)
+        - [Filesystem](./services/xds/providers/filesystem.md)
+
+# SDKs
+- [Unreal Engine](./sdks/unreal-engine.md)
+
+# Deployment
+- [Administration](./deployment/admin.md)
+- [Architecture Examples](./deployment/examples.md)
+- [Configuration](./deployment/configuration.md)
diff --git a/docs/src/admin.md → docs/src/deployment/admin.md b/docs/src/admin.md → docs/src/deployment/admin.md
@@ -1,41 +1,56 @@
-# Administration Interface
+# Administration
+
+| services | ports | Protocol |
+|----------|-------|-----------|
+| Administration | 8000 | HTTP (IPv4 OR IPv6) |
+
+## Logging
+By default Quilkin will log `INFO` level events, you can change this by setting
+the `RUST_LOG` environment variable. See [`log` documentation][log-docs] for
+more advanced usage.
+
+> If you are debugging Quilkin set the `RUST_LOG` environemnt variable to `quilkin=trace`, to filter trace level
+> logging to only Quilkin components.
+
+## HTTP API
 
 Quilkin exposes an HTTP interface to query different aspects of the server.
 
 > It is assumed that the administration interface will only ever be able to be accessible on `localhost`.
 
-By default, the administration interface is bound to `[::]:9091`, but it can be configured by the command line flag
-`--admin-address` or through the [proxy configuration file](./file-configuration.md), like so:
+By default, the administration interface is bound to `[::]:8000`, but it can be configured by the command line flag
+`--admin-address` or through the [configuration file](./configuration.md), like so:
 
 ```yaml
 admin:
   address: [::]:9095
 ```
 
+
 ## Endpoints
 
 The admin interface provides the following endpoints:
 
 ### /live
 
-This provides a liveness probe endpoint, most commonly used in 
+This provides a liveness probe endpoint, most commonly used in
 [Kubernetes based systems](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-command).
 
 Will return an HTTP status of 200 when all health checks pass.
 
 ### /ready
 
-This provides a readiness probe endpoint, most commonly used in 
+This provides a readiness probe endpoint, most commonly used in
 [Kubernetes based systems](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes).
 
-Depending on whether Quilkin is run in Proxy mode i.e. `quilkin proxy`, vs an xDS provider mode, such as `quilkin 
-manage agones`, will dictate how readiness is calculated: 
+Depending on whether Quilkin is run in Proxy mode i.e. `quilkin proxy`, vs an xDS provider mode, such as `quilkin
+manage agones`, will dictate how readiness is calculated:
 
 #### Proxy Mode
 
-Will return an HTTP status of 200 when there is at least one endpoint to send data to. This is primarily to ensure 
-that new proxies that have yet to get configuration information from an [xDS server](./xds.md) aren't send data 
-until they are fully populated. 
+Will return an HTTP status of 200 when there is at least one endpoint to send data to. This is primarily to ensure
+that new proxies that have yet to get configuration information from an [xDS server](../services/xds.md) aren't send data
+until they are fully populated.
 
 #### xDS Provider Mode
 
@@ -45,9 +60,9 @@ Will return an HTTP status of 200 when all health checks pass.
 
 Outputs [Prometheus](https://prometheus.io/) formatted metrics for this instance.
 
-See the [Proxy Metrics](proxy/metrics.md) documentation for what proxy metrics are available.
+See the [Proxy Metrics](../services/proxy/metrics.md) documentation for what proxy metrics are available.
 
-See the [xDS Metrics](./xds/metrics.md) documentation for what xDS metrics are available.
+See the [xDS Metrics](../services/xds/metrics.md) documentation for what xDS metrics are available.
 
 ### /config
 

diff --git a/docs/src/file-configuration.md → docs/src/deployment/configuration.md b/docs/src/file-configuration.md → docs/src/deployment/configuration.md
@@ -1,4 +1,4 @@
-# File Configuration
+# Configuration
 
 The following is the schema and reference for a Quilkin configuration
 file. See the [examples] folder for example configuration files.
@@ -11,19 +11,20 @@ environment variable.
 
 ## Static Configuration
 
-Example of a full configuration for `quilkin proxy` that utlisies a static Endpoint configuration:
+Example of a full configuration for `quilkin proxy` that utlisies a static
+endpoint configuration:
 
 ```yaml
-{{#include ../../examples/proxy.yaml:17:100}}
+{{#include ../../../examples/proxy.yaml:17:100}}
 ```
 
 ## Dynamic Configuration
 
-Example of a full configuration for `quilkin proxy` that utlisies a dynamic Endpoint configuration through an 
-[xDS management endpoint](./xds.md):
+Example of a full configuration for `quilkin proxy` that utlisies a dynamic
+Endpoint configuration through an [xDS management endpoint](../services/xds.md):
 
 ```yaml
-{{#include ../../examples/control-plane.yaml:17:100}}
+{{#include ../../../examples/control-plane.yaml:17:100}}
 ```
 
 ## Json Schema

diff --git a/docs/src/integrations.md → docs/src/deployment/examples.md b/docs/src/integrations.md → docs/src/deployment/examples.md
@@ -6,7 +6,10 @@ each providing different capabilities and complexity tradeoffs.
 Below captures several of the most useful and prevalent architectural patterns to give you inspiration
 on how you can use Quilkin in your multiplayer game networking architecture.
 
-## Server Proxy as a Sidecar
+These [examples](https://github.com/googleforgames/quilkin/tree/{{GITHUB_REF_NAME}}/examples)
+as well many others are available on Github repository.
+
+## [Server Proxy as a Sidecar](https://github.com/googleforgames/quilkin/tree/{{GITHUB_REF_NAME}}/examples/agones-xonotic-sidecar)
 
 ```text
                   |
@@ -77,12 +80,12 @@ This example is the same as the above, but puts a Client Proxy between the Game
 advantage of Client Proxy functionality.
 
 * The Client Proxy may be integrated as a standalone binary, directly into the client with communication
-  occurring over a localhost port or it may be possible utlise one of our [client SDKs].
+  occurring over a localhost port or it may be possible utlise one of our client SDKs such as [Unreal Engine][ue].
 * The Client Proxy can now utilise filters, such as compression, without having to change the Game Client.
-* The Game Client will need to communicate to the Client Proxy what IP it should connect to when the Client is 
+* The Game Client will need to communicate to the Client Proxy what IP it should connect to when the Client is
   match-made with a Game Server.
 
-## Client Proxy to Separate Server Proxies Pools
+## [Client Proxy to Separate Server Proxies Pools](https://github.com/googleforgames/quilkin/tree/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds)
 
 ```text
                                        |                             |
@@ -122,32 +125,32 @@ This is the most complex configuration, but enables the most reuse of Quilkin's
 while also providing the most redundancy and security for your dedicated game servers.
 
 * The Game client sends and receives packets from the Quilkin client proxy.
-* The Client Proxy may be integrated as a standalone binary, with communication occurring over a localhost port, or 
-  it could be integrated directly with the game client as a library, or the client could utilise one of our 
+* The Client Proxy may be integrated as a standalone binary, with communication occurring over a localhost port, or
+  it could be integrated directly with the game client as a library, or the client could utilise one of our
   [client SDKs] if Rust integration is not possible.
-* The Client Proxy can utilise the full set of filters, such as concatenation (for routing), compression or load 
+* The Client Proxy can utilise the full set of filters, such as concatenation (for routing), compression or load
   balancing, without having to change the Game Client.
-* A hosted set of Quilkin Server proxies that have public IP addresses, are connected to an 
-  [xDS Control Plane](./xds.md) to coordinate routing and access control to the dedicated game servers, which are 
+* A hosted set of Quilkin Server proxies that have public IP addresses, are connected to an
+  [xDS Control Plane](../services/xds.md) to coordinate routing and access control to the dedicated game servers, which are
   on private IP addresses.
 * The Client Proxy is made aware of one or more Server proxies to connect to, possibly via their Game Client matchmaker
   or another service, with an authentication token to pass to the Server proxies, such that the UDP packets can be
   routed correctly to the dedicated game server they should connect to.
 * Dedicated game servers receive traffic as per normal from the Server Proxies, and send data back to the proxies
   directly.
-* If the dedicated game server always expects traffic from only a single ip/port combination for client connection, 
+* If the dedicated game server always expects traffic from only a single ip/port combination for client connection,
   then traffic will always need to be sent through a single Server Proxy. Otherwise, UDP packets can be load
   balanced via the Client Proxy to multiple Server Proxies for even greater redundancy.
 
 
 ## What Next?
 
-* Have a look at the [example configurations](./examples.md) for configuration and usage examples.
-* Review the [set of filters](./filters.md) that are available.
+* Have a look at the [Administration API](./admin.md).
+* Review the [set of filters](../services/proxy/filters.md) that are available.
 
 ---
 
 Diagrams powered by <a href="http://asciiflow.com/" target="_blank">asciiflow.com</a>
 
 
-[client SDKs]: ./sdks.md
+[ue]: ../sdks/unreal-engine.md
diff --git a/docs/src/quickstarts/_agones.md → docs/src/deployment/quickstarts/_agones.md b/docs/src/quickstarts/_agones.md → docs/src/deployment/quickstarts/_agones.md