From 2972fad73c57f8d5438dfae758c16dbab29eae98 Mon Sep 17 00:00:00 2001 From: Jason Madigan Date: Tue, 26 Sep 2023 11:02:21 +0100 Subject: [PATCH 1/5] Making GW listener wildcard, copying initial guides --- .../multicluster-gateways-walkthrough.md | 2 +- docs/how-to/ratelimitpolicy-walkthrough.md | 157 ++++++++++++++++++ 2 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 docs/how-to/ratelimitpolicy-walkthrough.md diff --git a/docs/how-to/multicluster-gateways-walkthrough.md b/docs/how-to/multicluster-gateways-walkthrough.md index 8e35e7fec..3b17ec4fc 100644 --- a/docs/how-to/multicluster-gateways-walkthrough.md +++ b/docs/how-to/multicluster-gateways-walkthrough.md @@ -56,7 +56,7 @@ You are now ready to begin creating a gateway! :tada: namespaces: from: All name: api - hostname: $MGC_SUB_DOMAIN + hostname: "$MGC_ZONE_ROOT_DOMAIN" port: 443 protocol: HTTPS tls: diff --git a/docs/how-to/ratelimitpolicy-walkthrough.md b/docs/how-to/ratelimitpolicy-walkthrough.md new file mode 100644 index 000000000..64e41da6e --- /dev/null +++ b/docs/how-to/ratelimitpolicy-walkthrough.md @@ -0,0 +1,157 @@ +# Simple Rate Limiting for Application Developers + +This user guide walks you through an example of how to configure rate limiting for an endpoint of an application using Kuadrant. + +
+ +In this guide, we will rate limit a sample REST API called **Toy Store**. In reality, this API is just an echo service that echoes back to the user whatever attributes it gets in the request. The API listens to requests at the hostname `api.toystore.com`, where it exposes the endpoints `GET /toys*` and `POST /toys`, respectively, to mimic a operations of reading and writing toy records. + +We will rate limit the `POST /toys` endpoint to a maximum of 5rp10s ("5 requests every 10 seconds"). + +
+ +## Run the steps ① → ③ + +### ① Setup + +This step uses tooling from the Kuadrant Operator component to create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io), +where it installs Istio, Kubernetes Gateway API and Kuadrant itself. + +> **Note:** In production environment, these steps are usually performed by a cluster operator with administrator privileges over the Kubernetes cluster. + +Clone the project: + +```sh +git clone https://github.com/Kuadrant/kuadrant-operator && cd kuadrant-operator +``` + +Setup the environment: + +```sh +make local-setup +``` + +Request an instance of Kuadrant: + +```sh +kubectl -n kuadrant-system apply -f - < **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service: +> +> ```sh +> kubectl port-forward -n istio-system service/istio-ingressgateway 9080:80 2>&1 >/dev/null & +> ``` + +### ③ Enforce rate limiting on requests to the Toy Store API + +Create a Kuadrant `RateLimitPolicy` to configure rate limiting: + +![](https://i.imgur.com/2A9sXXs.png) + +```sh +kubectl apply -f - < **Note:** It may take a couple of minutes for the RateLimitPolicy to be applied depending on your cluster. + +
+ +Verify the rate limiting works by sending requests in a loop. + +Up to 5 successful (`200 OK`) requests every 10 seconds to `POST /toys`, then `429 Too Many Requests`: + +```sh +while :; do curl --write-out '%{http_code}' --silent --output /dev/null -H 'Host: api.toystore.com' http://localhost:9080/toys -X POST | egrep --color "\b(429)\b|$"; sleep 1; done +``` + +Unlimited successful (`200 OK`) to `GET /toys`: + +```sh +while :; do curl --write-out '%{http_code}' --silent --output /dev/null -H 'Host: api.toystore.com' http://localhost:9080/toys | egrep --color "\b(429)\b|$"; sleep 1; done +``` + +## Cleanup + +```sh +make local-cleanup +``` From 760290e0cca59238a2b014d30da4b074f55fe4c3 Mon Sep 17 00:00:00 2001 From: Jason Madigan Date: Wed, 27 Sep 2023 10:58:56 +0100 Subject: [PATCH 2/5] remove usage of the MGC_SUB_DOMAIN env var entirely. --- .../multicluster-gateways-walkthrough.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/docs/how-to/multicluster-gateways-walkthrough.md b/docs/how-to/multicluster-gateways-walkthrough.md index 3b17ec4fc..a4e2a1c4c 100644 --- a/docs/how-to/multicluster-gateways-walkthrough.md +++ b/docs/how-to/multicluster-gateways-walkthrough.md @@ -13,13 +13,7 @@ We will start with a single cluster and move to multiple clusters to illustrate ## Initial Setup -In this walkthrough, we'll deploy test echo services across multiple clusters. Before starting, set up a `MGC_SUB_DOMAIN` variable to simplify templating. This variable will represent the host for each service. - -If you followed the [Getting Started Guide](https://docs.kuadrant.io/getting-started/), you would have already set up a `MGC_ZONE_ROOT_DOMAIN` environment variable when creating a `ManagedZone`. For this tutorial, we'll derive a host from this domain. - -```bash -export MGC_SUB_DOMAIN=myapp.$MGC_ZONE_ROOT_DOMAIN -``` +In this walkthrough, we'll deploy test echo services across multiple clusters. If you followed the [Getting Started Guide](https://docs.kuadrant.io/getting-started/), you would have already set up a `MGC_ZONE_ROOT_DOMAIN` environment variable when creating a `ManagedZone`. For this tutorial, we'll derive a host from this domain for these echo services. ### Create a gateway @@ -174,7 +168,7 @@ So what about DNS how do we bring traffic to these gateways? name: prod-web namespace: kuadrant-multi-cluster-gateways hostnames: - - "$MGC_SUB_DOMAIN" + - "echo.$MGC_ZONE_ROOT_DOMAIN" rules: - backendRefs: - name: echo @@ -257,12 +251,12 @@ So what about DNS how do we bring traffic to these gateways? 4. Give DNS a minute or two to update. You should then be able to execute the following and get back the correct A record. ```bash - dig $MGC_SUB_DOMAIN + dig echo.$MGC_ZONE_ROOT_DOMAIN ``` 5. You should also be able to curl that endpoint ```bash - curl -k https://$MGC_SUB_DOMAIN + curl -k https://echo.$MGC_ZONE_ROOT_DOMAIN # Request served by echo-XXX-XXX ``` @@ -297,7 +291,6 @@ So now we have a working gateway with DNS and TLS configured. Let place this gat So now we have second ingress cluster configured with the same Gateway. 4. Let's create the HTTPRoute in the second gateway cluster: - ```bash kubectl --context kind-mgc-workload-1 apply -f - < Date: Wed, 27 Sep 2023 11:07:32 +0100 Subject: [PATCH 3/5] Wildcard listener for MGW --- docs/how-to/multicluster-gateways-walkthrough.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/multicluster-gateways-walkthrough.md b/docs/how-to/multicluster-gateways-walkthrough.md index a4e2a1c4c..77dd30653 100644 --- a/docs/how-to/multicluster-gateways-walkthrough.md +++ b/docs/how-to/multicluster-gateways-walkthrough.md @@ -50,7 +50,7 @@ You are now ready to begin creating a gateway! :tada: namespaces: from: All name: api - hostname: "$MGC_ZONE_ROOT_DOMAIN" + hostname: "*.$MGC_ZONE_ROOT_DOMAIN" port: 443 protocol: HTTPS tls: From bdcf227b32b0e4e94c309e74d54c303f4e19e280 Mon Sep 17 00:00:00 2001 From: Jason Madigan Date: Wed, 27 Sep 2023 11:08:10 +0100 Subject: [PATCH 4/5] Updated Simple RateLimiting + AuthPolicy for Application Developers connected to the MG walkthrough mend --- .../multicluster-gateways-walkthrough.md | 4 +- docs/how-to/ratelimitpolicy-walkthrough.md | 157 ------------- .../simple-authpolicy-for-app-developers.md | 222 ++++++++++++++++++ ...mple-ratelimitpolicy-for-app-developers.md | 166 +++++++++++++ 4 files changed, 391 insertions(+), 158 deletions(-) delete mode 100644 docs/how-to/ratelimitpolicy-walkthrough.md create mode 100644 docs/how-to/simple-authpolicy-for-app-developers.md create mode 100644 docs/how-to/simple-ratelimitpolicy-for-app-developers.md diff --git a/docs/how-to/multicluster-gateways-walkthrough.md b/docs/how-to/multicluster-gateways-walkthrough.md index 77dd30653..bb1c65935 100644 --- a/docs/how-to/multicluster-gateways-walkthrough.md +++ b/docs/how-to/multicluster-gateways-walkthrough.md @@ -357,6 +357,8 @@ So now we have a working gateway with DNS and TLS configured. Let place this gat If you want you can use ```watch dig echo.$MGC_ZONE_ROOT_DOMAIN``` to see the DNS switching between the two addresses ## Follow-on Walkthroughs -Some good follow-on walkthroughs that build on this walkthrough +Here are some good, follow-on guides that build on this walkthrough: +* [Simple RateLimitPolicy for App Developers](./simple-ratelimitpolicy-for-app-developers.md) +* [Simple AuthPolicy for App Developers](./simple-authpolicy-for-app-developers.md) * [Deploying/Configuring Metrics.](../how-to/metrics-walkthrough.md) \ No newline at end of file diff --git a/docs/how-to/ratelimitpolicy-walkthrough.md b/docs/how-to/ratelimitpolicy-walkthrough.md deleted file mode 100644 index 64e41da6e..000000000 --- a/docs/how-to/ratelimitpolicy-walkthrough.md +++ /dev/null @@ -1,157 +0,0 @@ -# Simple Rate Limiting for Application Developers - -This user guide walks you through an example of how to configure rate limiting for an endpoint of an application using Kuadrant. - -
- -In this guide, we will rate limit a sample REST API called **Toy Store**. In reality, this API is just an echo service that echoes back to the user whatever attributes it gets in the request. The API listens to requests at the hostname `api.toystore.com`, where it exposes the endpoints `GET /toys*` and `POST /toys`, respectively, to mimic a operations of reading and writing toy records. - -We will rate limit the `POST /toys` endpoint to a maximum of 5rp10s ("5 requests every 10 seconds"). - -
- -## Run the steps ① → ③ - -### ① Setup - -This step uses tooling from the Kuadrant Operator component to create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io), -where it installs Istio, Kubernetes Gateway API and Kuadrant itself. - -> **Note:** In production environment, these steps are usually performed by a cluster operator with administrator privileges over the Kubernetes cluster. - -Clone the project: - -```sh -git clone https://github.com/Kuadrant/kuadrant-operator && cd kuadrant-operator -``` - -Setup the environment: - -```sh -make local-setup -``` - -Request an instance of Kuadrant: - -```sh -kubectl -n kuadrant-system apply -f - < **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service: -> -> ```sh -> kubectl port-forward -n istio-system service/istio-ingressgateway 9080:80 2>&1 >/dev/null & -> ``` - -### ③ Enforce rate limiting on requests to the Toy Store API - -Create a Kuadrant `RateLimitPolicy` to configure rate limiting: - -![](https://i.imgur.com/2A9sXXs.png) - -```sh -kubectl apply -f - < **Note:** It may take a couple of minutes for the RateLimitPolicy to be applied depending on your cluster. - -
- -Verify the rate limiting works by sending requests in a loop. - -Up to 5 successful (`200 OK`) requests every 10 seconds to `POST /toys`, then `429 Too Many Requests`: - -```sh -while :; do curl --write-out '%{http_code}' --silent --output /dev/null -H 'Host: api.toystore.com' http://localhost:9080/toys -X POST | egrep --color "\b(429)\b|$"; sleep 1; done -``` - -Unlimited successful (`200 OK`) to `GET /toys`: - -```sh -while :; do curl --write-out '%{http_code}' --silent --output /dev/null -H 'Host: api.toystore.com' http://localhost:9080/toys | egrep --color "\b(429)\b|$"; sleep 1; done -``` - -## Cleanup - -```sh -make local-cleanup -``` diff --git a/docs/how-to/simple-authpolicy-for-app-developers.md b/docs/how-to/simple-authpolicy-for-app-developers.md new file mode 100644 index 000000000..66fd6f412 --- /dev/null +++ b/docs/how-to/simple-authpolicy-for-app-developers.md @@ -0,0 +1,222 @@ +# Authenticated API for Application Developers + +This user guide walks you how to configure and protect Gateway API endpoints by declaring Kuadrant `AuthPolicy` custom resources. + +## Requirements + +- Complete the [Multicluster Gateways Walkthrough](./multicluster-gateways-walkthrough.md), and you'll have an environment configured with a Gateway that we'll use in this guide. + +## Setup + +### ① Deploy the Toy Store API + +#### Create the Deployment + +> **Note:** You can skip this step and proceed to [Create the HTTPRoute](#create-the-httproute) if you've already deployed the Toy Store API as part of [the RateLimitPolicy for App Developers guide](./simple-ratelimitpolicy-for-app-developers.md#-deploy-the-toy-store-api). + +Create the deployments for both clusters (`kind-mgc-control-plane` & `kind-mgc-workload-1`) we've created previously in the [Multicluster Gateways Walkthrough](./multicluster-gateways-walkthrough.md): + +```sh +for context in kind-mgc-control-plane kind-mgc-workload-1; do kubectl --context $context apply -f - < + (Optional) Verify internal custom resources reconciled by Kuadrant +
+ + Verify the Authorino AuthConfig created in association with the policy: + + ```sh + kubectl get authconfig/ap-default-toystore -o yaml + ``` + + + +Create the API key: + +```sh +for context in kind-mgc-control-plane kind-mgc-workload-1; do kubectl --context $context apply -f - < **Note:** It may take a couple of minutes for the RateLimitPolicy to be applied depending on your cluster. + +
+ +Verify the rate limiting works by sending requests in a loop. + +Up to 5 successful (`200 OK`) requests every 10 seconds to `POST /toys`, then `429 Too Many Requests`: + +```sh +while :; do curl --write-out '%{http_code}' --silent -k --output /dev/null https://toystore.$MGC_ZONE_ROOT_DOMAIN/toys -X POST | egrep --color "\b(429)\b|$"; sleep 1; done +``` + +Unlimited successful (`200 OK`) to `GET /toys`: + +```sh +while :; do curl --write-out '%{http_code}' --silent -k --output /dev/null https://toystore.$MGC_ZONE_ROOT_DOMAIN/toys | egrep --color "\b(429)\b|$"; sleep 1; done +``` + +## Next Steps + +Here are some good, follow-on guides that build on this walkthrough: + +* [Simple AuthPolicy for App Developers](./simple-authpolicy-for-app-developers.md) +* [Deploying/Configuring Metrics.](../how-to/metrics-walkthrough.md) \ No newline at end of file From d1380f239962441d44af693c26a7948dfbb58619 Mon Sep 17 00:00:00 2001 From: Jason Madigan Date: Tue, 3 Oct 2023 16:08:02 +0100 Subject: [PATCH 5/5] Update docs/how-to/multicluster-gateways-walkthrough.md Co-authored-by: Laura Fitzgerald --- .../multicluster-gateways-walkthrough.md | 3 +- .../simple-authpolicy-for-app-developers.md | 222 ------------------ ...mple-ratelimitpolicy-for-app-developers.md | 4 + 3 files changed, 5 insertions(+), 224 deletions(-) delete mode 100644 docs/how-to/simple-authpolicy-for-app-developers.md diff --git a/docs/how-to/multicluster-gateways-walkthrough.md b/docs/how-to/multicluster-gateways-walkthrough.md index bb1c65935..d44d85051 100644 --- a/docs/how-to/multicluster-gateways-walkthrough.md +++ b/docs/how-to/multicluster-gateways-walkthrough.md @@ -13,7 +13,7 @@ We will start with a single cluster and move to multiple clusters to illustrate ## Initial Setup -In this walkthrough, we'll deploy test echo services across multiple clusters. If you followed the [Getting Started Guide](https://docs.kuadrant.io/getting-started/), you would have already set up a `MGC_ZONE_ROOT_DOMAIN` environment variable when creating a `ManagedZone`. For this tutorial, we'll derive a host from this domain for these echo services. +In this walkthrough, we'll deploy test echo services across multiple clusters. If you followed the [Getting Started Guide](https://docs.kuadrant.io/getting-started/), you would have already set up a `MGC_ZONE_ROOT_DOMAIN` environment variable. For this tutorial, we'll derive a host from this domain for these echo services. ### Create a gateway @@ -360,5 +360,4 @@ If you want you can use ```watch dig echo.$MGC_ZONE_ROOT_DOMAIN``` to see the DN Here are some good, follow-on guides that build on this walkthrough: * [Simple RateLimitPolicy for App Developers](./simple-ratelimitpolicy-for-app-developers.md) -* [Simple AuthPolicy for App Developers](./simple-authpolicy-for-app-developers.md) * [Deploying/Configuring Metrics.](../how-to/metrics-walkthrough.md) \ No newline at end of file diff --git a/docs/how-to/simple-authpolicy-for-app-developers.md b/docs/how-to/simple-authpolicy-for-app-developers.md deleted file mode 100644 index 66fd6f412..000000000 --- a/docs/how-to/simple-authpolicy-for-app-developers.md +++ /dev/null @@ -1,222 +0,0 @@ -# Authenticated API for Application Developers - -This user guide walks you how to configure and protect Gateway API endpoints by declaring Kuadrant `AuthPolicy` custom resources. - -## Requirements - -- Complete the [Multicluster Gateways Walkthrough](./multicluster-gateways-walkthrough.md), and you'll have an environment configured with a Gateway that we'll use in this guide. - -## Setup - -### ① Deploy the Toy Store API - -#### Create the Deployment - -> **Note:** You can skip this step and proceed to [Create the HTTPRoute](#create-the-httproute) if you've already deployed the Toy Store API as part of [the RateLimitPolicy for App Developers guide](./simple-ratelimitpolicy-for-app-developers.md#-deploy-the-toy-store-api). - -Create the deployments for both clusters (`kind-mgc-control-plane` & `kind-mgc-workload-1`) we've created previously in the [Multicluster Gateways Walkthrough](./multicluster-gateways-walkthrough.md): - -```sh -for context in kind-mgc-control-plane kind-mgc-workload-1; do kubectl --context $context apply -f - < - (Optional) Verify internal custom resources reconciled by Kuadrant -
- - Verify the Authorino AuthConfig created in association with the policy: - - ```sh - kubectl get authconfig/ap-default-toystore -o yaml - ``` - - - -Create the API key: - -```sh -for context in kind-mgc-control-plane kind-mgc-workload-1; do kubectl --context $context apply -f - < **Note:** You can skip this step and proceed to [Create the HTTPRoute](#create-the-httproute) if you've already deployed the Toy Store API as part of [the AuthPolicy for App Developers guide](./simple-authpolicy-for-app-developers.md#-deploy-the-toy-store-api). + Create the deployments for both clusters we've created previously (`kind-mgc-control-plane` & `kind-mgc-workload-1`): ```bash