diff --git a/docs/preprocessor.sh b/docs/preprocessor.sh index e3190927bf..fd55562c32 100755 --- a/docs/preprocessor.sh +++ b/docs/preprocessor.sh @@ -23,6 +23,7 @@ cargo run -q --manifest-path ../Cargo.toml &> ../target/quilkin.commands || true cargo run -q --manifest-path ../Cargo.toml -- proxy --help &> ../target/quilkin.proxy.commands || true cargo run -q --manifest-path ../Cargo.toml -- manage --help &> ../target/quilkin.manage.commands || true cargo run -q --manifest-path ../Cargo.toml -- relay --help &> ../target/quilkin.relay.commands || true +cargo run -q --manifest-path ../Cargo.toml -- agent --help &> ../target/quilkin.agent.commands || true # Credit: https://github.com/rust-lang/mdBook/issues/1462#issuecomment-778650045 jq -M -c .[1] <&0 diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index f41253666e..ffee596de6 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -7,6 +7,7 @@ - [Netcat](./deployment/quickstarts/netcat.md) - [Agones + Xonotic (Sidecar)](./deployment/quickstarts/agones-xonotic-sidecar.md) - [Agones + Xonotic (xDS)](./deployment/quickstarts/agones-xonotic-xds.md) +- [Agones + Xonotic (Relay)](./deployment/quickstarts/agones-xonotic-relay.md) # Services @@ -41,7 +42,7 @@ - [Relay](./services/relay.md) - [Metrics]() - - [Providers]() + - [Agents](./services/agent.md) # SDKs diff --git a/docs/src/deployment/quickstarts/agones-xonotic-relay.md b/docs/src/deployment/quickstarts/agones-xonotic-relay.md index 6447a7d776..1f4451d474 100644 --- a/docs/src/deployment/quickstarts/agones-xonotic-relay.md +++ b/docs/src/deployment/quickstarts/agones-xonotic-relay.md @@ -1,4 +1,4 @@ -# Quickstart: Quilkin with Agones and Xonotic (xDS) +# Quickstart: Quilkin with Agones and Xonotic (Relay) {{#include _agones.md}} * A local copy of the [Quilkin Binary](https://github.com/googleforgames/quilkin/releases). @@ -8,28 +8,26 @@ In this quickstart, we'll be setting up an example multi-cluster [Xonotic](https://xonotic.org/) [Agones](https://agones.dev/) Fleet, that will only be accessible through Quilkin, via utilising the [TokenRouter] Filter to -provide routing and access control to the Allocated `GameServer` instances. +provide routing and access control to the Allocated `GameServer` instances. To do this, we'll take advantage of the Quilkin [Relay](../../services/relay.md) to provide -an out-of-the-box multi-cluster control plane, and the [Agones Agent](../../services/agent.md) +an out-of-the-box multi-cluster xDS control plane, and the [Agones Agent](../../services/agent.md) to send information from the cluster(s) to the relay, which can be used as a -management server for the load balancers. +management server for each of the Quilkin [Proxy](../../services/proxy.md) instances. +> While the application of `quilkin relay` is to ultimately provide a solution where multiple clusters feed +> configuration information into a single relay endpoint via a `quilkin agent`, in this example we'll +> use a single cluster for demonstrative purposes. -## 2. Install Quilkin Agones Relay +## 2. Install Quilkin Relay and Agones Agent -To install Quilkin as an Agones integrated xDS control plane, we can create a deployment of Quilkin running as -`quilkin manage agones`, with the appropriate permissions. - -## 2. Install Quilkin Agones xDS Provider - -To install Quilkin as an Agones integrated xDS control plane, we can create a deployment of Quilkin running as -`quilkin manage agones`, with the appropriate permissions. +To install Quilkin as an Agones integrated relay control plane, we can create a deployment of Quilkin running as +`quilkin relay` with a corresponding Agones agent, `quilkin agent agones`, with the appropriate permissions. Run the following: ```shell -kubectl apply -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/xds-control-plane.yaml +kubectl apply -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/relay-control-plane.yaml ``` This applies several resources to your cluster: @@ -37,10 +35,10 @@ This applies several resources to your cluster: 1. A [ConfigMap] with a [Capture] and [TokenRouter] Filter set up to route packets to Endpoints, to be the base configuration for all the Quilkin proxies. 2. Appropriate [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) permissions for the - `quilkin manage agones` process to inspect Agones resources. -3. A matching [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) that runs the - `quilkin relay` process, a deployment for the `quilkin agent` process and a - [Service](https://kubernetes.io/docs/concepts/services-networking/service/) that the Quilkin proxies can connect to, + `quilkin agent agones` process to inspect Agones resources. +3. A [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) that runs the + `quilkin relay` process, a matching Deployment for the `quilkin agent` process and a + [Service](https://kubernetes.io/docs/concepts/services-networking/service/) that the Quilkin agents can send configuration information to, and the Proxies can connect to, to get their Filter and Endpoint configuration from. Now we can run `kubectl get pods` until we see that the Pod for the Deployment is up and running. @@ -48,62 +46,91 @@ Now we can run `kubectl get pods` until we see that the Pod for the Deployment i ```shell $ kubectl get pods NAME READY STATUS RESTARTS AGE -quilkin-manage-agones-54b787654-9dbvp 1/1 Running 0 76s +quilkin-agones-agent-9dd6699bd-qh7cq 1/1 Running 0 6s +quilkin-relay-agones-55fbd69f5d-cdh9k 1/1 Running 0 6s ``` -We can now run `kubectl get service quilkin-manage-agones` and see the -service that is generated in front of the above Deployment for our Quilkin proxies to connect to and receive their -configuration information from. +We can now run `kubectl get service quilkin-relay-agones` and see the +service that is generated in front of the above Quilkin Relay Deployment for our Quilkin Proxies to connect to and +receive their configuration information from. ```shell -$ kubectl get service quilkin-manage-agones -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -quilkin-manage-agones ClusterIP 10.104.2.72 80/TCP 1m23s +$ kubectl get service quilkin-relay-agones +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +quilkin-relay-agones ClusterIP 10.103.243.246 7800/TCP,7900/TCP 57s ``` ## 3. Install Quilkin Proxy Pool -To install the Quilkin Proxy pool which connects to the above xDS provider, we can create a Deployment of Quilkin +To install the Quilkin Proxy pool which connects to the above Relay xDS provider, we can create a Deployment of Quilkin proxy instances that point to the aforementioned Service, like so: ```shell -kubectl apply -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/proxy-pool.yaml +kubectl apply -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/proxy-pool.yaml ``` -This will set up three instances of Quilkin running as `quilkin proxy --management-server http://quilkin-manage-agones:80` -all connected to the `quilkin-manage-agones` service. +This will set up three instances of Quilkin running as `quilkin proxy --management-server +http://quilkin-relay-agones:7900` all of which are connected to the `quilkin-relay-agones` service. Now we can run `kubectl get pods` until we see that the Pods for the proxy Deployment is up and running. ```shell -$ kubectl get pods +$ kubectl get pods NAME READY STATUS RESTARTS AGE -quilkin-manage-agones-54b787654-9dbvp 1/1 Running 0 5m7s -quilkin-proxies-78965c446d-dqvjg 1/1 Running 0 6s -quilkin-proxies-78965c446d-fr6zs 1/1 Running 0 6s -quilkin-proxies-78965c446d-m4rr7 1/1 Running 0 6s +quilkin-agones-agent-9dd6699bd-5brzf 1/1 Running 0 18s +quilkin-proxies-7d9bbbccdf-5mz4l 1/1 Running 0 7s +quilkin-proxies-7d9bbbccdf-9vd59 1/1 Running 0 7s +quilkin-proxies-7d9bbbccdf-vwn2f 1/1 Running 0 7s +quilkin-relay-agones-55fbd69f5d-k2n7b 1/1 Running 0 18s ``` Let's take this one step further, and check the configuration of the proxies that should have come from the `quilkin -manage agones` instance. +agent agones` instance and passed through the `quilkin relay instance` into each of the proxies. In another terminal, run: `kubectl port-forward deployments/quilkin-proxies 8000`, to port forward the -[admin endpoint](../admin.md) locally, which we can then query. +[admin endpoint](../admin.md) locally to port 8001, which we can then query. -Go back to your original terminal and run `curl -s http://localhost:8000/config` +Go back to your original terminal and run `curl -s http://localhost:8001/config` -> If you have [jq](https://stedolan.github.io/jq/) installed, run `curl -s http://localhost:8000/config | jq` for a +> If you have [jq](https://stedolan.github.io/jq/) installed, run `curl -s http://localhost:8001/config | jq` for a > nicely formatted JSON output. ```shell -$ curl -s http://localhost:8000/config -{"admin":{"address":"0.0.0.0:8000"},"clusters":{},"filters":[{"name":"quilkin.filters.capture.v1alpha1.Capture","config":{"metadataKey":"quilkin.dev/capture","suffix":{"size":3,"remove":true}}},{"name":"quilkin.filters.token_router.v1alpha1.TokenRouter","config":null}],"id":"quilkin-proxies-78965c446d-dqvjg","management_servers":[{"address":"http://quilkin-manage-agones:80"}],"port":7000,"version":"v1alpha1","maxmind_db":null}% +$ curl -s http://localhost:8001/config | jq +{ + "clusters": [ + { + "endpoints": [], + "locality": null + } + ], + "filters": [ + { + "name": "quilkin.filters.capture.v1alpha1.Capture", + "label": null, + "config": { + "metadataKey": "quilkin.dev/capture", + "suffix": { + "size": 3, + "remove": true + } + } + }, + { + "name": "quilkin.filters.token_router.v1alpha1.TokenRouter", + "label": null, + "config": null + } + ], + "id": "quilkin-proxies-7d9bbbccdf-9vd59", + "version": "v1alpha1" +} ``` -This shows us the current configuration of the proxies coming from the xDS server created via `quilkin manage +This shows us the current configuration of the proxies coming from the xDS server created via `quilkin agent agones`. The most interesting part that we see here, is that we have a matching set of [Filters](../../services/proxy/filters.md) that are found in the `ConfigMap` in the -[xds-control-plane.yaml](https://github.com/googleforgames/quilkin/blob/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/xds-control-plane.yaml) +[relay-control-plane.yaml](https://github.com/googleforgames/quilkin/blob/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/relay-control-plane.yaml) we installed earlier. ## 4. Create the Agones Fleet @@ -112,25 +139,25 @@ Now we will create an [Agones Fleet](https://agones.dev/site/docs/reference/flee game servers. Thankfully, Agones Fleets require no specific configuration to work with Quilkin proxies, so this yaml is a -[standard Agones Fleet configuration](https://github.com/googleforgames/quilkin/blob/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/fleet.yaml) +[standard Agones Fleet configuration](https://github.com/googleforgames/quilkin/blob/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/fleet.yaml) ```shell -kubectl apply -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/fleet.yaml +kubectl apply -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/fleet.yaml ``` Run `kubectl get gameservers` until all the `GameServer` records show that they are `Ready` and able to take players. ```shell -$ kubectl get gameservers -NAME STATE ADDRESS PORT NODE AGE -xonotic-d7rfx-55j7q Ready 34.168.170.51 7226 gke-agones-default-534a3f8d-ifpc 34s -xonotic-d7rfx-nx7xr Ready 34.168.170.51 7984 gke-agones-default-534a3f8d-ifpc 34s -xonotic-d7rfx-sn5d6 Ready 34.168.170.51 7036 gke-agones-default-534a3f8d-ifpc 34s +$ kubectl get gs +NAME STATE ADDRESS PORT NODE AGE +xonotic-8ns7b-2lk5d Ready 39.168.219.72 7015 gke-agones-default-ad8cd7e5-3b12 1m +xonotic-8ns7b-hrc8j Ready 39.168.219.72 7298 gke-agones-default-ad8cd7e5-3b12 1m +xonotic-8ns7b-mldg6 Ready 39.168.219.72 7558 gke-agones-default-ad8cd7e5-3b12 1m ``` ## 5. Allocate a `GameServer` -To let the Quilkin xDS provider know what token will route to which `GameServer` we need to apply the +To let the Quilkin Agones Agent know what token will route to which `GameServer` we need to apply the `quilkin.dev/tokens` annotation to an allocated `GameServer`, with the token content as its value. > This token would normally get generated by some kind of player authentication service and passed to the client @@ -142,7 +169,7 @@ Since you can add annotations to `GameServers` at and apply the annotation at the same time! ```shell -kubectl create -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/gameserverallocation.yaml +kubectl create -f https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/gameserverallocation.yaml ``` If we check our `GameServers` now, we should see that one of them has moved to the `Allocated` state, marking it as @@ -151,9 +178,9 @@ having players playing on it, and therefore it is protected by Agones until the ```shell $ kubectl get gs NAME STATE ADDRESS PORT NODE AGE -xonotic-d7rfx-55j7q Allocated 34.168.170.51 7226 gke-agones-default-534a3f8d-ifpc 23m -xonotic-d7rfx-nx7xr Ready 34.168.170.51 7984 gke-agones-default-534a3f8d-ifpc 23m -xonotic-d7rfx-sn5d6 Ready 34.168.170.51 7036 gke-agones-default-534a3f8d-ifpc 23m +xonotic-8ns7b-2lk5d Allocated 39.168.219.72 7015 gke-agones-default-ad8cd7e5-3b12 17m +xonotic-8ns7b-hrc8j Ready 39.168.219.72 7298 gke-agones-default-ad8cd7e5-3b12 17m +xonotic-8ns7b-mldg6 Ready 39.168.219.72 7558 gke-agones-default-ad8cd7e5-3b12 17m ``` > Don't do this more than once, as then multiple allocated `GameServers` will have the same routing token! @@ -162,14 +189,14 @@ If we `kubectl describe gameserver ` and have a look at th should see something similar to this: ```shell -$ kubectl describe gameserver xonotic-d7rfx-55j7q -Name: xonotic-d7rfx-55j7q +❯ kubectl describe gs xonotic-8ns7b-2lk5d +Name: xonotic-8ns7b-2lk5d Namespace: default Labels: agones.dev/fleet=xonotic - agones.dev/gameserverset=xonotic-h5cfn -Annotations: agones.dev/last-allocated: 2022-12-19T22:59:22.099818298Z - agones.dev/ready-container-id: containerd://7b3d9e9dbda6f2e0381df7669f6117bf3e54171469cfacbce2670605a61ce4b8 - agones.dev/sdk-version: 1.24.0 + agones.dev/gameserverset=xonotic-8ns7b +Annotations: agones.dev/last-allocated: 2023-10-04T19:47:04.047026419Z + agones.dev/ready-container-id: containerd://b39d30965becdbc40336fd9aa642fe776421553615f642dd599e1b0d88c505b6 + agones.dev/sdk-version: 1.33.0 quilkin.dev/tokens: NDU2 API Version: agones.dev/v1 Kind: GameServer @@ -181,18 +208,57 @@ our authentication and routing token ("NDU2"). > You should use something more cryptographically random than `456` in your application. -Let's run `curl -s http://localhost:8000/config` again, so we can see what has changed! +Let's run `curl -s http://localhost:8001/config` again, so we can see what has changed! ```shell -$ curl -s http://localhost:8000/config -{"admin":{"address":"0.0.0.0:8000"},"clusters":{"default":{"localities":[{"locality":null,"endpoints":[{"address":"34.168.170.51:7226","metadata":{"quilkin.dev":{"tokens":["NDU2"]}}}]}]}},"filters":[{"name":"quilkin.filters.capture.v1alpha1.Capture","config":{"metadataKey":"quilkin.dev/capture","suffix":{"size":3,"remove":true}}},{"name":"quilkin.filters.token_router.v1alpha1.TokenRouter","config":null}],"id":"quilkin-proxies-78965c446d-tfgsj","management_servers":[{"address":"http://quilkin-manage-agones:80"}],"port":7000,"version":"v1alpha1","maxmind_db":null}% +❯ curl -s http://localhost:8001/config | jq +{ + "clusters": [ + { + "endpoints": [ + { + "address": "39.168.219.72:7015", + "metadata": { + "quilkin.dev": { + "tokens": [ + "NDU2" + ] + }, + "name": "xonotic-8ns7b-2lk5d" + } + } + ], + "locality": null + } + ], + "filters": [ + { + "name": "quilkin.filters.capture.v1alpha1.Capture", + "label": null, + "config": { + "metadataKey": "quilkin.dev/capture", + "suffix": { + "size": 3, + "remove": true + } + } + }, + { + "name": "quilkin.filters.token_router.v1alpha1.TokenRouter", + "label": null, + "config": null + } + ], + "id": "quilkin-proxies-7d9bbbccdf-9vd59", + "version": "v1alpha1" +} ``` -Looking under `clusters` > `localities` > `endpoints` we can see an address and token that matches up with the +Looking under `clusters` > `endpoints` we can see an address and token that matches up with the `GameServer` record we created above! -The xDS process saw that allocated `GameServer`, turned it into a Quilkin `Endpoint` and applied the set routing -token appropriately -- without you having to write a line of xDS compliant code! +The Agones agent process saw that allocated `GameServer`, turned it into a Quilkin `Endpoint` and applied the set +routing token appropriately -- without you having to write a line of xDS compliant code! ## Connecting Client Side @@ -208,7 +274,7 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) quilkin-proxies LoadBalancer 10.109.0.12 35.246.94.14 7000:30174/UDP 3h22m ``` -We have a [Quilkin config yaml](https://github.com/googleforgames/quilkin/blob/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/client-token.yaml) +We have a [Quilkin config yaml](https://github.com/googleforgames/quilkin/blob/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/client-token.yaml) file all ready for you, that is configured to append the routing token `456` to each packet that passes through it, via the power of a [ConcatenateBytes](../../services/proxy/filters/concatenate_bytes.md) Filter. @@ -216,7 +282,7 @@ packet that passes through it, via the power of a Download `client-token.yaml` locally, so you can edit it: ```shell -curl https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-xds/client-token.yaml --output client-token.yaml +curl https://raw.githubusercontent.com/googleforgames/quilkin/{{GITHUB_REF_NAME}}/examples/agones-xonotic-relay/client-token.yaml --output client-token.yaml ``` We then take the EXTERNAL-IP and port from the `quilkin-proxies` service, and replace the`${LOADBALANCER_IP}` @@ -225,18 +291,19 @@ with it in `client-token.yaml`. Run this edited configuration locally with your quilkin binary as `quilkin -c ./client-token.yaml proxy`: ```shell -$ quilkin -c ./client-token.yaml proxy -{"timestamp":"2022-10-07T22:10:47.257635Z","level":"INFO","fields":{"message":"Starting Quilkin","version":"0.4.0-dev","commit":"c77260a2526542c564829a2c66935c60f00adcd2"},"target":"quilkin::cli"} -{"timestamp":"2022-10-07T22:10:47.258273Z","level":"INFO","fields":{"message":"Starting","port":7000,"proxy_id":"markmandel45"},"target":"quilkin::proxy"} -{"timestamp":"2022-10-07T22:10:47.258321Z","level":"INFO","fields":{"message":"Starting admin endpoint","address":"[::]:9092"},"target":"quilkin::admin"} -{"timestamp":"2022-10-07T22:10:47.258812Z","level":"INFO","fields":{"message":"Quilkin is ready"},"target":"quilkin::proxy"} +$ ./quilkin --config ./client-token.yaml proxy +2023-10-04T20:09:07.320780Z INFO quilkin::cli: src/cli.rs: Starting Quilkin version="0.7.0-dev" commit="d42db7e14c2e0e758e9a6eb655ccf4184941066c" +2023-10-04T20:09:07.321711Z INFO quilkin::admin: src/admin.rs: Starting admin endpoint address=[::]:8000 +2023-10-04T20:09:07.322089Z INFO quilkin::cli::proxy: src/cli/proxy.rs: Starting port=7777 proxy_id="markmandel45" +2023-10-04T20:09:07.322576Z INFO quilkin::cli::proxy: src/cli/proxy.rs: Quilkin is ready +2023-10-04T20:09:07.322692Z INFO qcmp_task{v4_addr=0.0.0.0:7600 v6_addr=[::]:7600}: quilkin::protocol: src/protocol.rs: awaiting qcmp packets v4_addr=0.0.0.0:7600 v6_addr=[::]:7600 ``` -Now connect to the local client proxy on "127.0.0.1:7000" via the "Multiplayer > Address" field in the +Now connect to the local client proxy on "[::1]:7777" via the "Multiplayer > Address" field in the Xonotic client, and Quilkin will take care of appending the routing token to all your UDP packets, which the Quilkin proxies will route to the Allocated GameServer, and you can play a gamee! -![xonotic-address.png](xonotic-address.png) +![xonotic-address-v6.png](xonotic-address-v6.png) ...And you didn't have to change the client or the dedicated game server 🤸 diff --git a/docs/src/deployment/quickstarts/xonotic-address-v6.png b/docs/src/deployment/quickstarts/xonotic-address-v6.png new file mode 100644 index 0000000000..00519cc4e3 Binary files /dev/null and b/docs/src/deployment/quickstarts/xonotic-address-v6.png differ diff --git a/docs/src/services/agent.md b/docs/src/services/agent.md index cc6a266621..841d3c1524 100644 --- a/docs/src/services/agent.md +++ b/docs/src/services/agent.md @@ -1,8 +1,8 @@ -# Control Plane Relay +# Control Plane Agents -| services | ports | Protocol | -|----------|-------|-----------| -| QCMP | 7600 | UDP(IPv4 OR IPv6) | +| services | ports | Protocol | +|----------|-------|-------------------| +| QCMP | 7600 | UDP(IPv4 OR IPv6) | > **Note:** This service is currently in active experimentation and development so there may be bugs which cause it to be unusable for production, as always @@ -12,6 +12,9 @@ For multi-cluster integration, Quilkin provides a `agent` service, that can be deployed to a cluster to act as a beacon for QCMP pings and forward cluster configuration information to a `relay` service +Agent configuration and functionality matches that of Control Plane Providers, such as +[Filesystem](./xds/providers/filesystem.md) and [Agones](./xds/providers/agones.md). + To view all options for the `agent` subcommand, run: ```shell diff --git a/docs/src/services/relay.md b/docs/src/services/relay.md index 5ebeabff92..2ae2216c18 100644 --- a/docs/src/services/relay.md +++ b/docs/src/services/relay.md @@ -1,9 +1,9 @@ # Control Plane Relay -| services | ports | Protocol | -|----------|-------|-----------| -| ADS | 7800 | gRPC(IPv4) | -| CPDS | 7900 | gRPC(IPv4) | +| services | ports | Protocol | +|----------|-------|--------------------| +| ADS | 7800 | gRPC(IPv4 OR IPv6) | +| CPDS | 7900 | gRPC(IPv4 OR IPv6) | > **Note:** This service is currently in active experimentation and development so there may be bugs which cause it to be unusable for production, as always diff --git a/examples/agones-xonotic-relay/README.md b/examples/agones-xonotic-relay/README.md index 42b1569a56..e2f50ba206 100644 --- a/examples/agones-xonotic-relay/README.md +++ b/examples/agones-xonotic-relay/README.md @@ -1,111 +1,3 @@ -# Agones & Xonotic Example +# Agones & Xonotic via Relay Example -An example of running [Xonotic](https://xonotic.org/) with Quilkin on an [Agones](https://agones.dev/) cluster, -utlising the Quilkin xDS Agones provider, with a TokenRouter to provide routing and access control to the -allocated `GameServer` instance. - -To interact with the demo, you will need to download the Xonotic client and an existing Agones Kubernetes cluster. - -## Installation on the Cluster - -To install Quilkin as an Agones integrated xDS control plane, we can create a deployment of Quilkin running in -`manage agones` mode, with the appropriate permissions. - -```shell -$ kubectl apply -f ./xds-control-plane.yaml -configmap/quilkin-xds-filter-config created -serviceaccount/quilkin-agones created -clusterrole.rbac.authorization.k8s.io/quilkin-agones created -rolebinding.rbac.authorization.k8s.io/quilkin-agones created -deployment.apps/quilkin-manage-agones created -service/quilkin-manage-agones created -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -quilkin-manage-agones-68b47457d4-42fxl 1/1 Running 0 3s -``` - -This also creates an internal `Service` endpoint for our Quilkin proxy instances to connect to named -`quilkin-manage-agones`. - -To install the Quilkin Proxy pool which connects to the above xDS provider, we can split up a Deployment of Quilkin -instances that point to the aforementioned Service, like so: - -```shell -$ kubectl apply -f ./proxy-pool.yaml -deployment.apps/quilkin-proxies created -service/quilkin-proxies created -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -quilkin-manage-agones-68b47457d4-42fxl 1/1 Running 0 20m -quilkin-proxies-7448987cfb-6kbsz 1/1 Running 0 3s -quilkin-proxies-7448987cfb-p6krc 1/1 Running 0 3s -quilkin-proxies-7448987cfb-s9gxz 1/1 Running 0 3s -``` - -We can now see that we have 3 proxies running alongside and connected to our xDS provider. - -## Create the `Fleet` - -Next, create the `Fleet` of Xonotic `GameServer` instances: - -```shell -$ kubectl apply -f ./fleet.yaml -fleet.agones.dev/xonotic created -$ kubectl get gameservers # run until they are Ready -NAME STATE ADDRESS PORT NODE AGE -xonotic-d7rfx-55j7q Ready 34.168.170.51 7226 gke-agones-default-534a3f8d-ifpc 34s -xonotic-d7rfx-nx7xr Ready 34.168.170.51 7984 gke-agones-default-534a3f8d-ifpc 34s -xonotic-d7rfx-sn5d6 Ready 34.168.170.51 7036 gke-agones-default-534a3f8d-ifpc 34s -``` - -To let the Quilkin xDS provider know what token will route to which `GameServer` we need to apply the -`quilkin.dev/tokens` annotation to an allocated `GameServer`, with the token content as its value - so let's create -an allocation, and apply the annotation all in one go! - -```shell -$ kubectl create -f ./gameserverallocation.yaml -gameserverallocation.allocation.agones.dev/xonotic-d7rfx-nx7xr created -$ kubectl get gs -NAME STATE ADDRESS PORT NODE AGE -xonotic-d7rfx-55j7q Allocated 34.168.170.51 7226 gke-agones-default-534a3f8d-ifpc 23m -xonotic-d7rfx-nx7xr Ready 34.168.170.51 7984 gke-agones-default-534a3f8d-ifpc 23m -xonotic-d7rfx-sn5d6 Ready 34.168.170.51 7036 gke-agones-default-534a3f8d-ifpc 23m -``` - -> Don't do this more than once, as then multiple allocated `GameServers` will have the same routing token! - -## Connecting Client Side - -Instead of connecting to Xonotic or an Agones `GameServer` directly, we'll want to grab the IP and exposed port of -the `Service` that fronts all our Quilkin proxies: - -```shell -$ kubectl get service quilkin-proxies -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -quilkin-proxies LoadBalancer 10.109.0.12 35.246.94.14 7000:30174/UDP 3h22m -``` - -We then take the EXTERNAL-IP and port from the `quilkin-proxies` service, and replace the`${LOADBALANCER_IP}` -with it in `client-token.yaml`. - -Run this configuration locally as: - -```shell -$ quilkin -c ./client-token.yaml proxy -{"timestamp":"2022-10-07T22:10:47.257635Z","level":"INFO","fields":{"message":"Starting Quilkin","version":"0.4.0-dev","commit":"c77260a2526542c564829a2c66935c60f00adcd2"},"target":"quilkin::cli"} -{"timestamp":"2022-10-07T22:10:47.258273Z","level":"INFO","fields":{"message":"Starting","port":7000,"proxy_id":"markmandel45"},"target":"quilkin::proxy"} -{"timestamp":"2022-10-07T22:10:47.258321Z","level":"INFO","fields":{"message":"Starting admin endpoint","address":"[::]:9092"},"target":"quilkin::admin"} -{"timestamp":"2022-10-07T22:10:47.258812Z","level":"INFO","fields":{"message":"Quilkin is ready"},"target":"quilkin::proxy"} -``` - -Now connect to the local client proxy on "127.0.0.1:7000" via the "Multiplayer > Address" field in the -Xonotic client, and Quilkin will take care of appending the routing token to all your UDP packets, which the Quilkin -proxies will route to the Allocated GameServer, and you can play a gamee! - -...And you didn't have to change the client or the dedicated game server 🤸 - -## Metrics - -The Quilkin instances are also annotated with the -[appropriate Prometheus annotations](https://github.com/prometheus-community/helm-charts/tree/main/charts/prometheus#scraping-pod-metrics-via-annotations) -to inform Prometheus on how to scrape the Quilkin proxies for metrics. +This is the code example for the "Quickstart: Quilkin with Agones and Xonotic (Relay)" Guide, linked via the homepage. diff --git a/examples/agones-xonotic-relay/client-token.yaml b/examples/agones-xonotic-relay/client-token.yaml index abf1b9ab30..37942a6b3e 100644 --- a/examples/agones-xonotic-relay/client-token.yaml +++ b/examples/agones-xonotic-relay/client-token.yaml @@ -1,5 +1,5 @@ # -# Copyright 2022 Google LLC +# Copyright 2023 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -22,7 +22,5 @@ filters: on_write: DO_NOTHING bytes: NDU2 # 456 clusters: - default: - localities: - - endpoints: - - address: ${LOADBALANCER_IP}:7777 + - endpoints: + - address: ${LOADBALANCER_IP}:7777 diff --git a/examples/agones-xonotic-relay/fleet.yaml b/examples/agones-xonotic-relay/fleet.yaml index 75a90db8ba..4be622a6d7 100644 --- a/examples/agones-xonotic-relay/fleet.yaml +++ b/examples/agones-xonotic-relay/fleet.yaml @@ -1,4 +1,4 @@ -# Copyright 2022 Google LLC All Rights Reserved. +# Copyright 2023 Google LLC All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -21,16 +21,18 @@ metadata: name: xonotic spec: replicas: 3 + strategy: + type: Recreate template: spec: ports: - - name: default - containerPort: 26000 + - name: default + containerPort: 26000 health: initialDelaySeconds: 30 periodSeconds: 60 template: spec: containers: - - name: xonotic - image: gcr.io/agones-images/xonotic-example:0.8 + - name: xonotic + image: us-docker.pkg.dev/agones-images/examples/xonotic-example:1.2 diff --git a/examples/agones-xonotic-relay/gameserverallocation.yaml b/examples/agones-xonotic-relay/gameserverallocation.yaml index 6a7f1e24ab..920fbf657f 100644 --- a/examples/agones-xonotic-relay/gameserverallocation.yaml +++ b/examples/agones-xonotic-relay/gameserverallocation.yaml @@ -1,4 +1,4 @@ -# Copyright 2022 Google LLC All Rights Reserved. +# Copyright 2023 Google LLC All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/examples/agones-xonotic-relay/proxy-pool.yaml b/examples/agones-xonotic-relay/proxy-pool.yaml index 4a92a76809..ab674c3de4 100644 --- a/examples/agones-xonotic-relay/proxy-pool.yaml +++ b/examples/agones-xonotic-relay/proxy-pool.yaml @@ -1,5 +1,5 @@ # -# Copyright 2022 Google LLC +# Copyright 2023 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -16,7 +16,7 @@ # # Pool of Quilkin proxies, tied to the -# xDS control plane in xds-control-plane.yaml +# Quilkin relay control plane in relay-control-plane.yaml # --- @@ -42,7 +42,7 @@ spec: spec: containers: - name: quilkin - image: us-docker.pkg.dev/quilkin/release/quilkin:0.6.0 + image: us-docker.pkg.dev/quilkin-mark-dev/release/quilkin:0.7.0 args: ["proxy", "--management-server", "http://quilkin-relay-agones:7800"] env: - name: RUST_LOG diff --git a/examples/agones-xonotic-relay/xds-control-plane.yaml b/examples/agones-xonotic-relay/relay-control-plane.yaml similarity index 89% rename from examples/agones-xonotic-relay/xds-control-plane.yaml rename to examples/agones-xonotic-relay/relay-control-plane.yaml index 963758c2bb..6abf33b46a 100644 --- a/examples/agones-xonotic-relay/xds-control-plane.yaml +++ b/examples/agones-xonotic-relay/relay-control-plane.yaml @@ -1,5 +1,5 @@ # -# Copyright 2022 Google LLC +# Copyright 2023 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -15,7 +15,7 @@ # # -# Everything to setup the xDS Agones integrated control plane +# Everything to setup the relay and agent Agones control plane # --- @@ -23,7 +23,7 @@ apiVersion: v1 kind: ConfigMap metadata: - name: quilkin-xds-filter-config + name: quilkin-relay-filter-config labels: quilkin.dev/configmap: "true" data: @@ -40,7 +40,7 @@ data: --- -# RBAC Setup for Agones xDS Control Plane +# RBAC Setup for Agones Relay Control Plane apiVersion: v1 kind: ServiceAccount @@ -113,7 +113,7 @@ spec: env: - name: RUST_LOG value: info - image: us-docker.pkg.dev/quilkin/release/quilkin:0.6.0 + image: us-docker.pkg.dev/quilkin-mark-dev/release/quilkin:0.7.0 livenessProbe: failureThreshold: 3 httpGet: @@ -152,12 +152,13 @@ spec: - name: quilkin args: - agent + - --relay - http://quilkin-relay-agones:7900 - agones env: - name: RUST_LOG value: info - image: us-docker.pkg.dev/quilkin/release/quilkin:0.6.0 + image: us-docker.pkg.dev/quilkin-mark-dev/release/quilkin:0.7.0 livenessProbe: failureThreshold: 3 httpGet: @@ -172,10 +173,12 @@ metadata: name: quilkin-relay-agones spec: ports: - - port: 7800 + - name: ads + port: 7800 protocol: TCP targetPort: 7800 - - port: 7900 + - name: cpds + port: 7900 protocol: TCP targetPort: 7900 selector: