From 9746aae728c67f6626367e31702929bc7280f498 Mon Sep 17 00:00:00 2001 From: R-Lawton Date: Fri, 17 Jan 2025 16:42:20 +0000 Subject: [PATCH 1/5] Updating environment setup to new way of installing and also updating to remove the use of guide to tutorial Signed-off-by: R-Lawton --- ...uth-for-app-devs-and-platform-engineers.md | 111 +++++++--- doc/user-guides/dns/gateway-dns.md | 190 ++++++++---------- .../secure-protect-connect.md | 2 +- .../authenticated-rl-for-app-developers.md | 97 +++++++-- ...uthenticated-rl-with-jwt-and-k8s-authnz.md | 134 +++++++++--- .../gateway-rl-for-cluster-operators.md | 9 +- .../multi-auth-rlp-diff-section.md | 8 +- .../multi-auth-rlp-same-section.md | 9 +- .../simple-rl-for-app-developers.md | 7 +- doc/user-guides/tls/gateway-tls.md | 2 +- 10 files changed, 368 insertions(+), 201 deletions(-) diff --git a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md index 8345e933f..ccff9e768 100644 --- a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md +++ b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md @@ -1,6 +1,6 @@ # Enforcing authentication & authorization with Kuadrant AuthPolicy -This guide walks you through the process of setting up a local Kubernetes cluster with Kuadrant where you will protect [Gateway API](https://gateway-api.sigs.k8s.io/) endpoints by declaring Kuadrant AuthPolicy custom resources. +This tutorial walks you through the process of setting up a local Kubernetes cluster with Kuadrant where you will protect [Gateway API](https://gateway-api.sigs.k8s.io/) endpoints by declaring Kuadrant AuthPolicy custom resources. Three AuthPolicies will be declared: @@ -14,7 +14,7 @@ Topology: ``` ┌─────────────────────────┐ │ (Gateway) │ ┌───────────────┐ - │ kuadrant-ingressgateway │◄──│ (AuthPolicy) │ + │ external │◄──│ (AuthPolicy) │ │ │ │ gw-auth │ │ * │ └───────────────┘ └─────────────────────────┘ @@ -35,24 +35,85 @@ Topology: └─────────────────┘ ``` -## Setup the environment +## Prerequisites +- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. -Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make.md) to set up your environment before continuing with this doc. +### Setup environment variables + +Set the following environment variables used for convenience in this guide: + +```bash +export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway +export KUADRANT_GATEWAY_NAME=external # Name for the example Gateway +export KUADRANT_DEVELOPER_NS=toystore # Namespace for an example toystore app + +``` + +### Create an Ingress Gateway + +Create the namespace the Gateway will be deployed in: + +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} +``` + +Create a gateway using toystore as the listener hostname: + +```sh +kubectl apply -f - < +```bash +export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway +export KUADRANT_GATEWAY_NAME=external # Name for the example Gateway +export KUADRANT_DEVELOPER_NS=toystore # Namespace for an example toystore app +export KUADRANT_AWS_ACCESS_KEY_ID=xxxx # AWS Key ID with access to manage the DNS Zone ID below +export KUADRANT_AWS_SECRET_ACCESS_KEY=xxxx # AWS Secret Access Key with access to manage the DNS Zone ID below +export KUADRANT_AWS_DNS_PUBLIC_ZONE_ID=xxxx # AWS Route 53 Zone ID for the Gateway +export KUADRANT_ZONE_ROOT_DOMAIN=example.com # Root domain associated with the Zone ID above ``` -> **Note:** ROOT_DOMAIN should be set to your AWS hosted zone _name_. +Create the namespace the Gateway will be deployed in: -### Create a dns provider secret +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} -Create AWS provider secret. You should limit the permissions of this credential to only the zones you want us to access. -```shell -export AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= +### Create a DNS provider secret +Create AWS provider secret. You should limit the permissions of this credential to only the zones you want us to access. -kubectl -n my-gateways create secret generic aws-credentials \ +```bash +kubectl -n ${KUADRANT_GATEWAY_NS} create secret generic aws-credentials \ --type=kuadrant.io/aws \ - --from-literal=AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \ - --from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY + --from-literal=AWS_ACCESS_KEY_ID=$KUADRANT_AWS_ACCESS_KEY_ID \ + --from-literal=AWS_SECRET_ACCESS_KEY=$KUADRANT_AWS_SECRET_ACCESS_KEY ``` -### Create an ingress gateway +### Create an Ingress Gateway -Create a gateway using your ROOT_DOMAIN as part of a listener hostname: +Create a gateway using your KUADRANT_ZONE_ROOT_DOMAIN as part of a listener hostname: ```sh -kubectl -n my-gateways apply -f - < **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service and accessing over localhost: > > ```sh -> kubectl port-forward -n gateway-system service/kuadrant-ingressgateway-istio 9080:80 >/dev/null 2>&1 & -> export GATEWAY_URL=localhost:9080 +> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/kuadrant-${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & +> export KUADRANT_GATEWAY_URL=localhost:9080 > ``` > > ```sh -> curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +> curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i > # HTTP/1.1 200 OK > ``` @@ -96,6 +151,7 @@ apiVersion: kuadrant.io/v1 kind: AuthPolicy metadata: name: toystore + namespace: ${KUADRANT_DEVELOPER_NS} spec: targetRef: group: gateway.networking.k8s.io @@ -126,7 +182,7 @@ EOF Verify the authentication works by sending a request to the Toy Store API without API key: ```sh -curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 401 Unauthorized # www-authenticate: APIKEY realm="api-key-users" # x-ext-auth-reason: "credential not found" @@ -178,6 +234,7 @@ apiVersion: kuadrant.io/v1 kind: RateLimitPolicy metadata: name: toystore + namespace: ${KUADRANT_DEVELOPER_NS} spec: targetRef: group: gateway.networking.k8s.io @@ -206,17 +263,17 @@ Verify the rate limiting works by sending requests as Alice and Bob. Up to 5 successful (`200 OK`) requests every 10 seconds allowed for Alice, then `429 Too Many Requests`: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMALICE' -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMALICE' -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` Up to 2 successful (`200 OK`) requests every 10 seconds allowed for Bob, then `429 Too Many Requests`: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMBOB' -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMBOB' -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` ## Cleanup ```sh -make local-cleanup +kind delete cluster ``` diff --git a/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md b/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md index f08445928..7e6329616 100644 --- a/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md +++ b/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md @@ -1,6 +1,6 @@ # Authenticated Rate Limiting with JWTs and Kubernetes RBAC -This user guide walks you through an example of how to use Kuadrant to protect an application with policies to enforce: +This tutorial walks you through an example of how to use Kuadrant to protect an application with policies to enforce: - authentication based OpenId Connect (OIDC) ID tokens (signed JWTs), issued by a Keycloak server; - alternative authentication method by Kubernetes Service Account tokens; @@ -23,16 +23,95 @@ Privileges to execute the requested operation (read, create or delete) will be g Each user will be entitled to a maximum of 5rp10s (5 requests every 10 seconds). -### Setup the environment +## Prerequisites +- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. -Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make.md) to set up your environment before continuing with this doc. +### Setup environment variables -### Deploy the Toystore example API: +Set the following environment variables used for convenience in this guide: + +```bash +export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway +export KUADRANT_GATEWAY_NAME=external # Name for the example Gateway +export KUADRANT_DEVELOPER_NS=toystore # Namespace for an example toystore app +``` + +### Create an Ingress Gateway + +Create the namespace the Gateway will be deployed in: + +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} +``` + +Create a gateway using toystore as the listener hostname: ```sh -kubectl apply -f examples/toystore/toystore.yaml +kubectl apply -f - < **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service and accessing over localhost: > > ```sh -> kubectl port-forward -n gateway-system service/kuadrant-ingressgateway-istio 9080:80 >/dev/null 2>&1 & -> export GATEWAY_URL=localhost:9080 +> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/${KUADRANT_GATEWAY_NS}-istio 9080:80 >/dev/null 2>&1 & +> export KUADRANT_GATEWAY_URL=localhost:9080 > ``` > > ```sh -> curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +> curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i > # HTTP/1.1 200 OK > ``` ### Deploy Keycloak -Create the namesapce: +Create the for Keycloak: ```sh kubectl create namespace keycloak @@ -92,6 +171,7 @@ apiVersion: kuadrant.io/v1 kind: AuthPolicy metadata: name: toystore-protection + namespace: ${KUADRANT_DEVELOPER_NS} spec: targetRef: group: gateway.networking.k8s.io @@ -128,7 +208,7 @@ EOF #### Try the API missing authentication ```sh -curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 401 Unauthorized # www-authenticate: Bearer realm="keycloak-users" # www-authenticate: Bearer realm="k8s-service-accounts" @@ -140,13 +220,13 @@ curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i Obtain an access token with the Keycloak server: ```sh -ACCESS_TOKEN=$(kubectl run token --attach --rm --restart=Never -q --image=curlimages/curl -- http://keycloak.keycloak.svc.cluster.local:8080/realms/kuadrant/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=demo' -d 'username=john' -d 'password=p' -d 'scope=openid' | jq -r .access_token) +KUADRANT_ACCESS_TOKEN=$(kubectl run token --attach --rm --restart=Never -q --image=curlimages/curl -- http://keycloak.keycloak.svc.cluster.local:8080/realms/kuadrant/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=demo' -d 'username=john' -d 'password=p' -d 'scope=openid' | jq -r .KUADRANT_ACCESS_TOKEN) ``` Send a request to the API as the Keycloak-authenticated user while still missing permissions: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H "Authorization: Bearer $KUADRANT_ACCESS_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 403 Forbidden ``` @@ -164,13 +244,13 @@ EOF Obtain an access token for the `client-app-1` service account: ```sh -SA_TOKEN=$(kubectl create token client-app-1) +KUADRANT_SA_TOKEN=$(kubectl create token client-app-1) ``` Send a request to the API as the service account while still missing permissions: ```sh -curl -H "Authorization: Bearer $SA_TOKEN" -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H "Authorization: Bearer $KUADRANT_SA_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 403 Forbidden ``` @@ -217,7 +297,7 @@ roleRef: name: toystore-reader subjects: - kind: User - name: $(jq -R -r 'split(".") | .[1] | @base64d | fromjson | .sub' <<< "$ACCESS_TOKEN") + name: $(jq -R -r 'split(".") | .[1] | @base64d | fromjson | .sub' <<< "$KUADRANT_ACCESS_TOKEN") - kind: ServiceAccount name: client-app-1 namespace: default @@ -232,7 +312,7 @@ roleRef: name: toystore-writer subjects: - kind: User - name: $(jq -R -r 'split(".") | .[1] | @base64d | fromjson | .sub' <<< "$ACCESS_TOKEN") + name: $(jq -R -r 'split(".") | .[1] | @base64d | fromjson | .sub' <<< "$KUADRANT_ACCESS_TOKEN") EOF ``` @@ -253,24 +333,24 @@ in the Authorino docs. Send requests to the API as the Keycloak-authenticated user: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H "Authorization: Bearer $KUADRANT_ACCESS_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 200 OK ``` ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Host: api.toystore.com' -X POST http://$GATEWAY_URL/admin/toy -i +curl -H "Authorization: Bearer $KUADRANT_ACCESS_TOKEN" -H 'Host: api.toystore.com' -X POST http://$KUADRANT_GATEWAY_URL/admin/toy -i # HTTP/1.1 200 OK ``` Send requests to the API as the Kubernetes service account: ```sh -curl -H "Authorization: Bearer $SA_TOKEN" -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H "Authorization: Bearer $KUADRANT_SA_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 200 OK ``` ```sh -curl -H "Authorization: Bearer $SA_TOKEN" -H 'Host: api.toystore.com' -X POST http://$GATEWAY_URL/admin/toy -i +curl -H "Authorization: Bearer $KUADRANT_SA_TOKEN" -H 'Host: api.toystore.com' -X POST http://$KUADRANT_GATEWAY_URL/admin/toy -i # HTTP/1.1 403 Forbidden ``` @@ -310,17 +390,17 @@ Each user should be entitled to a maximum of 5 requests every 10 seconds. Send requests as the Keycloak-authenticated user: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H "Authorization: Bearer $KUADRANT_ACCESS_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` Send requests as the Kubernetes service account: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H "Authorization: Bearer $SA_TOKEN" -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H "Authorization: Bearer $KUADRANT_SA_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` ## Cleanup ```sh -make local-cleanup +kind delete cluster ``` diff --git a/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md b/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md index f0c551758..aa15ef498 100644 --- a/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md +++ b/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md @@ -2,11 +2,10 @@ For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) -This user guide walks you through an example of how to configure rate limiting for all routes attached to a specific ingress gateway. +This tutorial walks you through an example of how to configure rate limiting for all routes attached to a specific ingress gateway. -### Setup the environment - -Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make.md) to set up your environment before continuing with this doc. +## Prerequisites +- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. ### Deploy the Toystore example API: @@ -171,5 +170,5 @@ while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Ho ## Cleanup ```sh -make local-cleanup +kind delete cluster ``` diff --git a/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md b/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md index feffc70fc..8c2983c32 100644 --- a/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md +++ b/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md @@ -1,10 +1,10 @@ # Gateway Rate Limiting -This user guide walks you through an example of how to configure multiple rate limit polices for different listeners in an ingress gateway. +This tutorial walks you through an example of how to configure multiple rate limit polices for different listeners in an ingress gateway. -### Setup the environment +## Prerequisites +- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. -Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make.md) to set up your environment before continuing with this doc. ### Deploy the sample API: @@ -138,5 +138,5 @@ while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Ho ## Cleanup ```sh -make local-cleanup +kind delete cluster ``` diff --git a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md index e53712cd1..0e40f1f7e 100644 --- a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md +++ b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md @@ -1,6 +1,6 @@ # Multi authenticated Rate Limiting for an Application -This user guide walks you through an example of how to configure multiple authenticated rate limiting for an application using Kuadrant. +This tutorial walks you through an example of how to configure multiple authenticated rate limiting for an application using Kuadrant. Authenticated rate limiting, rate limits the traffic directed to an application based on attributes of the client user, who is authenticated by some authentication method. A few examples of authenticated rate limiting use cases are: @@ -17,9 +17,8 @@ We will define 2 users of the API, which can send requests to the API at differe | alice | 5rp10s ("5 requests every 10 seconds") | | bob | 2rp10s ("2 requests every 10 seconds") | -### Setup the environment - -Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make.md) to set up your environment before continuing with this doc. +## Prerequisites +- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. ### Deploy the Toy Store API @@ -241,5 +240,5 @@ while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Au ## Cleanup ```sh -make local-cleanup +kind delete cluster ``` diff --git a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md index ce61a9c77..0ce01ec33 100644 --- a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md +++ b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md @@ -8,9 +8,8 @@ In this guide, we will rate limit a sample REST API called **Toy Store**. In rea We will rate limit the `POST /toys` endpoint to a maximum of 5rp10s ("5 requests every 10 seconds"). -### Setup the environment - -Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make.md) to set up your environment before continuing with this doc. +## Prerequisites +- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. ### Deploy the Toy Store API @@ -130,5 +129,5 @@ while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Ho ## Cleanup ```sh -make local-cleanup +kind delete cluster ``` diff --git a/doc/user-guides/tls/gateway-tls.md b/doc/user-guides/tls/gateway-tls.md index e6952f0ce..a5b33583d 100644 --- a/doc/user-guides/tls/gateway-tls.md +++ b/doc/user-guides/tls/gateway-tls.md @@ -1,6 +1,6 @@ # Gateway TLS for Cluster Operators -This user guide walks you through an example of how to configure TLS for all routes attached to an ingress gateway. +This tutorial walks you through an example of how to configure TLS for all routes attached to an ingress gateway. ## Requisites From 98b2ba27919f798482191614d05de25a85b50e42 Mon Sep 17 00:00:00 2001 From: R-Lawton Date: Fri, 17 Jan 2025 17:20:02 +0000 Subject: [PATCH 2/5] Addign additional gatewat Signed-off-by: R-Lawton --- ...uth-for-app-devs-and-platform-engineers.md | 5 -- .../multi-auth-rlp-same-section.md | 71 +++++++++++++++---- 2 files changed, 59 insertions(+), 17 deletions(-) diff --git a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md index ccff9e768..1ce189db7 100644 --- a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md +++ b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md @@ -346,8 +346,3 @@ curl -H 'Host: foo.other-apps.com' http://$KUADRANT_GATEWAY_URL/ -i # } ``` -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md index 0e40f1f7e..4084823ac 100644 --- a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md +++ b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md @@ -20,6 +20,53 @@ We will define 2 users of the API, which can send requests to the API at differe ## Prerequisites - Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. +### Setup environment variables + +Set the following environment variables used for convenience in this guide: + +```bash +export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway +export KUADRANT_GATEWAY_NAME=external # Name for the example Gateway +export KUADRANT_DEVELOPER_NS=toystore # Namespace for an example toystore app +``` + +### Create an Ingress Gateway + +Create the namespace the Gateway will be deployed in: + +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} +``` + +Create a gateway using toystore as the listener hostname: + +```sh +kubectl apply -f - < **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service and accessing over localhost: > > ```sh -> kubectl port-forward -n gateway-system service/kuadrant-ingressgateway-istio 9080:80 >/dev/null 2>&1 & -> export GATEWAY_URL=localhost:9080 +> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/-${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & +> export KUADRANT_GATEWAY_URL=localhost:9080 > ``` > > ```sh -> curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +> curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i > # HTTP/1.1 200 OK > ``` @@ -125,7 +172,7 @@ EOF ### Verify the authentication works by sending a request to the Toy Store API without API key: ```sh -curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy -i +curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i # HTTP/1.1 401 Unauthorized # www-authenticate: APIKEY realm="api-key-users" # x-ext-auth-reason: "credential not found" @@ -228,13 +275,13 @@ Verify the rate limiting works by sending requests as Alice and Bob. Up to 5 successful (`200 OK`) requests every 10 seconds allowed for Alice, then `429 Too Many Requests`: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMALICE' -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMALICE' -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` Up to 2 successful (`200 OK`) requests every 10 seconds allowed for Bob, then `429 Too Many Requests`: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMBOB' -H 'Host: api.toystore.com' http://$GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMBOB' -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` ## Cleanup From 130ada906b5179c7ae9edab0d4656f0155e61a64 Mon Sep 17 00:00:00 2001 From: David Martin Date: Mon, 20 Jan 2025 12:32:24 +0000 Subject: [PATCH 3/5] Update prereqs and remove cleanup Signed-off-by: David Martin --- ...uth-for-app-devs-and-platform-engineers.md | 7 +++-- doc/user-guides/dns/gateway-dns.md | 16 +++------- .../secure-protect-connect.md | 9 ++---- .../authenticated-rl-for-app-developers.md | 16 ++++------ ...uthenticated-rl-with-jwt-and-k8s-authnz.md | 14 ++++----- .../gateway-rl-for-cluster-operators.md | 12 +++----- .../multi-auth-rlp-diff-section.md | 12 +++----- .../multi-auth-rlp-same-section.md | 16 ++++------ .../simple-rl-for-app-developers.md | 16 ++++------ doc/user-guides/tls/gateway-tls.md | 30 +++---------------- 10 files changed, 46 insertions(+), 102 deletions(-) diff --git a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md index 1ce189db7..49f31bc14 100644 --- a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md +++ b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md @@ -36,11 +36,13 @@ Topology: ``` ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Setup environment variables -Set the following environment variables used for convenience in this guide: +Set the following environment variables used for convenience in this tutorial: ```bash export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway @@ -345,4 +347,3 @@ curl -H 'Host: foo.other-apps.com' http://$KUADRANT_GATEWAY_URL/ -i # "message": "Access denied by default by the gateway operator. If you are the administrator of the service, create a specific auth policy for the route." # } ``` - diff --git a/doc/user-guides/dns/gateway-dns.md b/doc/user-guides/dns/gateway-dns.md index cb67d122a..2bf70926d 100644 --- a/doc/user-guides/dns/gateway-dns.md +++ b/doc/user-guides/dns/gateway-dns.md @@ -1,18 +1,16 @@ # Gateway DNS configuration for routes attached to a ingress gateway -This user guide walks you through an example of how to configure DNS for all routes attached to an ingress gateway. +This tutorial walks you through an example of how to configure DNS for all routes attached to an ingress gateway. ## Prerequisites -- kubectl command line tool. +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. - AWS/Azure or GCP with DNS capabilities. -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. - - ### Setup environment variables -Set the following environment variables used for convenience in this guide: +Set the following environment variables used for convenience in this tutorial: ```bash export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway @@ -159,9 +157,3 @@ Verify DNS using curl you should get a status 200: ```shell curl http://api.$KUADRANT_ZONE_ROOT_DOMAIN/cars -i ``` - -## Cleanup - -```shell -kind delete cluster -``` diff --git a/doc/user-guides/full-walkthrough/secure-protect-connect.md b/doc/user-guides/full-walkthrough/secure-protect-connect.md index 5e941e9e0..0935299e2 100644 --- a/doc/user-guides/full-walkthrough/secure-protect-connect.md +++ b/doc/user-guides/full-walkthrough/secure-protect-connect.md @@ -2,18 +2,17 @@ ## Overview -This tutorial walks you through using Kuadrant to secure, protect, and connect an API exposed by a Gateway (Kubernetes Gateway API) from the personas platform engineer and application developer. For more information on the different personas please see the [Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) +This tutorial walks you through using Kuadrant to secure, protect, and connect an API exposed by a Gateway (Kubernetes Gateway API) from the personas platform engineer and application developer. For more information on the different personas please see the [Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. - AWS/Azure or GCP with DNS capabilities. - ### Set the environment variables -Set the following environment variables used for convenience in this guide: +Set the following environment variables used for convenience in this tutorial: ```bash export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway @@ -471,8 +470,6 @@ while :; do curl -k --write-out '%{http_code}\n' --silent --output /dev/null -H ## Next Steps - [mTLS Configuration](../../install/mtls-configuration.md) -To learn more about Kuadrant and see more how to guides, visit Kuadrant [documentation](https://docs.kuadrant.io) - ### Optional diff --git a/doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md b/doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md index c7a3c4efc..1abc212af 100644 --- a/doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md +++ b/doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md @@ -1,8 +1,8 @@ # Authenticated Rate Limiting for Application developers -For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) +For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) -This tutorial guide walks you through an example of how to configure authenticated rate limiting for an application using Kuadrant. +This tutorial walks you through an example of how to configure authenticated rate limiting for an application using Kuadrant. Authenticated rate limiting rate limits the traffic directed to an application based on attributes of the client user, who is authenticated by some authentication method. A few examples of authenticated rate limiting use cases are: @@ -20,11 +20,13 @@ We will define 2 users of the API, which can send requests to the API at differe | bob | 2rp10s ("2 requests every 10 seconds") | ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Setup environment variables -Set the following environment variables used for convenience in this guide: +Set the following environment variables used for convenience in this tutorial: ```bash export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway @@ -271,9 +273,3 @@ Up to 2 successful (`200 OK`) requests every 10 seconds allowed for Bob, then `4 ```sh while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMBOB' -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` - -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md b/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md index 7e6329616..8d8acc6e0 100644 --- a/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md +++ b/doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md @@ -1,6 +1,6 @@ # Authenticated Rate Limiting with JWTs and Kubernetes RBAC -This tutorial walks you through an example of how to use Kuadrant to protect an application with policies to enforce: +This tutorial walks you through an example of how to use Kuadrant to protect an application with policies to enforce: - authentication based OpenId Connect (OIDC) ID tokens (signed JWTs), issued by a Keycloak server; - alternative authentication method by Kubernetes Service Account tokens; @@ -24,11 +24,13 @@ Privileges to execute the requested operation (read, create or delete) will be g Each user will be entitled to a maximum of 5rp10s (5 requests every 10 seconds). ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Setup environment variables -Set the following environment variables used for convenience in this guide: +Set the following environment variables used for convenience in this tutorial: ```bash export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway @@ -398,9 +400,3 @@ Send requests as the Kubernetes service account: ```sh while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H "Authorization: Bearer $KUADRANT_SA_TOKEN" -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` - -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md b/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md index aa15ef498..b6845f02e 100644 --- a/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md +++ b/doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md @@ -1,11 +1,13 @@ # Gateway Rate Limiting for Cluster Operators -For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) +For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) This tutorial walks you through an example of how to configure rate limiting for all routes attached to a specific ingress gateway. ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Deploy the Toystore example API: @@ -166,9 +168,3 @@ Unlimited successful (`200 OK`) through the `internal` ingress gateway (`*.local ```sh while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Host: api.toystore.local' http://localhost:9082 | grep -E --color "\b(429)\b|$"; sleep 1; done ``` - -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md b/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md index 8c2983c32..41b62907d 100644 --- a/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md +++ b/doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md @@ -1,9 +1,11 @@ # Gateway Rate Limiting -This tutorial walks you through an example of how to configure multiple rate limit polices for different listeners in an ingress gateway. +This tutorial walks you through an example of how to configure multiple rate limit polices for different listeners in an ingress gateway. ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Deploy the sample API: @@ -134,9 +136,3 @@ Unlimited successful (`200 OK`) through the `internal` ingress gateway (`*.local ```sh while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Host: api.toystore.local' http://localhost:9081 | grep -E --color "\b(429)\b|$"; sleep 1; done ``` - -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md index 4084823ac..1d05fb07d 100644 --- a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md +++ b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md @@ -1,6 +1,6 @@ # Multi authenticated Rate Limiting for an Application -This tutorial walks you through an example of how to configure multiple authenticated rate limiting for an application using Kuadrant. +This tutorial walks you through an example of how to configure multiple authenticated rate limiting for an application using Kuadrant. Authenticated rate limiting, rate limits the traffic directed to an application based on attributes of the client user, who is authenticated by some authentication method. A few examples of authenticated rate limiting use cases are: @@ -8,7 +8,7 @@ Authenticated rate limiting, rate limits the traffic directed to an application - Each user can send up to 20rpm ("request per minute"). - Admin users (members of the 'admin' group) can send up to 100rps, while regular users (non-admins) can send up to 20rpm and no more than 5rps. -In this guide, we will rate limit a sample REST API called **Toy Store**, an echo service that echoes back to the user whatever attributes it gets in the request. The API exposes an endpoint at `GET http://api.toystore.com/toy`, to mimic an operation of reading toy records. +In this tutorial, we will rate limit a sample REST API called **Toy Store**, an echo service that echoes back to the user whatever attributes it gets in the request. The API exposes an endpoint at `GET http://api.toystore.com/toy`, to mimic an operation of reading toy records. We will define 2 users of the API, which can send requests to the API at different rates, based on their user IDs. The authentication method used is **API key**. @@ -18,11 +18,13 @@ We will define 2 users of the API, which can send requests to the API at differe | bob | 2rp10s ("2 requests every 10 seconds") | ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Setup environment variables -Set the following environment variables used for convenience in this guide: +Set the following environment variables used for convenience in this tutorial: ```bash export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway @@ -283,9 +285,3 @@ Up to 2 successful (`200 OK`) requests every 10 seconds allowed for Bob, then `4 ```sh while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Authorization: APIKEY IAMBOB' -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy | grep -E --color "\b(429)\b|$"; sleep 1; done ``` - -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md index 0ce01ec33..ee58c9ee9 100644 --- a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md +++ b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md @@ -1,15 +1,17 @@ # Simple Rate Limiting for Application developers -For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) +For more info on the different personas see [Gateway API](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) -This user guide walks you through an example of how to configure rate limiting for an endpoint of an application using Kuadrant. +This tutorial 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 operations of reading and writing toy records. +In this tutorial, 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 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"). ## Prerequisites -- Kubernetes cluster with Kuadrant operator installed. See our [getting started](getting-started.md) guide for more information. + +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### Deploy the Toy Store API @@ -125,9 +127,3 @@ Unlimited successful (`200 OK`) to `GET /toys`: ```sh while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Host: api.toystore.com' http://$GATEWAY_URL/toys | grep -E --color "\b(429)\b|$"; sleep 1; done ``` - -## Cleanup - -```sh -kind delete cluster -``` diff --git a/doc/user-guides/tls/gateway-tls.md b/doc/user-guides/tls/gateway-tls.md index a5b33583d..db6cbff10 100644 --- a/doc/user-guides/tls/gateway-tls.md +++ b/doc/user-guides/tls/gateway-tls.md @@ -1,30 +1,14 @@ # Gateway TLS for Cluster Operators -This tutorial walks you through an example of how to configure TLS for all routes attached to an ingress gateway. +This tutorial walks you through an example of how to configure TLS for all routes attached to an ingress gateway. -## Requisites +## Prerequisites -- [Docker](https://docker.io) +- Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. ### 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, CertManager and Kuadrant itself. - -Clone the project: - -```shell -git clone https://github.com/Kuadrant/kuadrant-operator && cd kuadrant-operator -``` - -Setup the environment: - -```shell -make local-setup -``` - -Create a namespace: - ```shell kubectl create namespace my-gateways ``` @@ -269,9 +253,3 @@ x-envoy-upstream-service-time: 1 < * Connection #0 to host api.toystore.local left intact ``` - -## Cleanup - -```shell -make local-cleanup -``` From 8f81327b4bb74615caba55787e496c333a77680d Mon Sep 17 00:00:00 2001 From: David Martin Date: Mon, 20 Jan 2025 12:50:42 +0000 Subject: [PATCH 4/5] Create Gateway in rlp tutorial Signed-off-by: David Martin --- .../simple-rl-for-app-developers.md | 69 ++++++++++++++++--- 1 file changed, 58 insertions(+), 11 deletions(-) diff --git a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md index ee58c9ee9..3a60b67e5 100644 --- a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md +++ b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md @@ -13,6 +13,53 @@ We will rate limit the `POST /toys` endpoint to a maximum of 5rp10s ("5 requests - Kubernetes cluster with Kuadrant operator installed. See our [Getting Started](/getting-started) guide for more information. - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. +### Setup environment variables + +Set the following environment variables used for convenience in this tutorial: + +```bash +export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway +export KUADRANT_GATEWAY_NAME=external # Name for the example Gateway +export KUADRANT_DEVELOPER_NS=toystore # Namespace for an example toystore app +``` + +### Create an Ingress Gateway + +Create the namespace the Gateway will be deployed in: + +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} +``` + +Create a gateway using toystore as the listener hostname: + +```sh +kubectl apply -f - < **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service and accessing over localhost: > > ```sh -> kubectl port-forward -n gateway-system service/kuadrant-ingressgateway-istio 9080:80 >/dev/null 2>&1 & -> export GATEWAY_URL=localhost:9080 +> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/-${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & +> export KUADRANT_GATEWAY_URL=localhost:9080 > ``` > > ```sh -> curl -H 'Host: api.toystore.com' http://$GATEWAY_URL/toys -i +> curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i > # HTTP/1.1 200 OK > ``` @@ -119,11 +166,11 @@ 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}\n' --silent --output /dev/null -H 'Host: api.toystore.com' http://$GATEWAY_URL/toys -X POST | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toys -X POST | grep -E --color "\b(429)\b|$"; sleep 1; done ``` Unlimited successful (`200 OK`) to `GET /toys`: ```sh -while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Host: api.toystore.com' http://$GATEWAY_URL/toys | grep -E --color "\b(429)\b|$"; sleep 1; done +while :; do curl --write-out '%{http_code}\n' --silent --output /dev/null -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toys | grep -E --color "\b(429)\b|$"; sleep 1; done ``` From 1149aa3a861092a786f87300547232d9c5ad9b51 Mon Sep 17 00:00:00 2001 From: David Martin Date: Mon, 20 Jan 2025 13:13:37 +0000 Subject: [PATCH 5/5] Add missing sectionNames to HTTPRoutes Signed-off-by: David Martin --- .../auth/auth-for-app-devs-and-platform-engineers.md | 6 ++++-- .../ratelimiting/multi-auth-rlp-same-section.md | 5 +++-- .../ratelimiting/simple-rl-for-app-developers.md | 8 +++++--- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md index 49f31bc14..54ae81dab 100644 --- a/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md +++ b/doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md @@ -119,7 +119,8 @@ spec: hostnames: - api.toystore.com rules: - - matches: # rule-1 + - name: rule-1 + matches: - method: GET path: type: PathPrefix @@ -131,7 +132,8 @@ spec: backendRefs: - name: toystore port: 80 - - matches: # rule-2 + - name: rule-2 + matches: - path: type: PathPrefix value: "/admin" diff --git a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md index 1d05fb07d..e2aaba4d0 100644 --- a/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md +++ b/doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md @@ -92,7 +92,8 @@ spec: hostnames: - api.toystore.com rules: - - matches: + - name: rule-1 + matches: - path: type: Exact value: "/toy" @@ -125,7 +126,7 @@ curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i > **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service and accessing over localhost: > > ```sh -> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/-${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & +> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & > export KUADRANT_GATEWAY_URL=localhost:9080 > ``` > diff --git a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md index 3a60b67e5..c57f5d86d 100644 --- a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md +++ b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md @@ -85,7 +85,8 @@ spec: hostnames: - api.toystore.com rules: - - matches: + - name: rule-1 + matches: - method: GET path: type: PathPrefix @@ -93,7 +94,8 @@ spec: backendRefs: - name: toystore port: 80 - - matches: # it has to be a separate HTTPRouteRule so we do not rate limit other endpoints + - name: rule-2 + matches: # it has to be a separate HTTPRouteRule so we do not rate limit other endpoints - method: POST path: type: Exact @@ -122,7 +124,7 @@ curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toys -i > **Note**: If the command above fails to hit the Toy Store API on your environment, try forwarding requests to the service and accessing over localhost: > > ```sh -> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/-${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & +> kubectl port-forward -n ${KUADRANT_GATEWAY_NS} service/${KUADRANT_GATEWAY_NAME}-istio 9080:80 >/dev/null 2>&1 & > export KUADRANT_GATEWAY_URL=localhost:9080 > ``` >