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..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 @@ -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,28 +35,92 @@ Topology: └─────────────────┘ ``` -## Setup the environment +## Prerequisites -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. +- 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 - < -``` +Create the namespace the Gateway will be deployed in: -> **Note:** ROOT_DOMAIN should be set to your AWS hosted zone _name_. +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} -### Create a dns provider secret +### 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. -```shell -export AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= - -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 +153,7 @@ apiVersion: kuadrant.io/v1 kind: AuthPolicy metadata: name: toystore + namespace: ${KUADRANT_DEVELOPER_NS} spec: targetRef: group: gateway.networking.k8s.io @@ -126,7 +184,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 +236,7 @@ apiVersion: kuadrant.io/v1 kind: RateLimitPolicy metadata: name: toystore + namespace: ${KUADRANT_DEVELOPER_NS} spec: targetRef: group: gateway.networking.k8s.io @@ -206,17 +265,11 @@ 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 -``` - -## Cleanup - -```sh -make local-cleanup +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 ``` 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..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 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,97 @@ 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 -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. +- 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: +### 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 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 +173,7 @@ apiVersion: kuadrant.io/v1 kind: AuthPolicy metadata: name: toystore-protection + namespace: ${KUADRANT_DEVELOPER_NS} spec: targetRef: group: gateway.networking.k8s.io @@ -128,7 +210,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 +222,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 +246,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 +299,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 +314,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 +335,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 +392,11 @@ 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 -``` - -## Cleanup - -```sh -make local-cleanup +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 ``` 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..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,12 +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 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 +## Prerequisites -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. +- 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: @@ -167,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 -make local-cleanup -``` 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..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,10 +1,12 @@ # 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) guide for more information. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. -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: @@ -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 -make local-cleanup -``` 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..e2aaba4d0 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: @@ -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**. @@ -17,9 +17,57 @@ 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 +## Prerequisites -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. +- 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/toy -i +> curl -H 'Host: api.toystore.com' http://$KUADRANT_GATEWAY_URL/toy -i > # HTTP/1.1 200 OK > ``` @@ -126,7 +175,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" @@ -229,17 +278,11 @@ 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 -``` - -## Cleanup - -```sh -make local-cleanup +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 ``` 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..c57f5d86d 100644 --- a/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md +++ b/doc/user-guides/ratelimiting/simple-rl-for-app-developers.md @@ -1,16 +1,64 @@ # 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"). -### Setup the environment +## Prerequisites -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. +- 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 > ``` @@ -118,17 +168,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 -``` - -## Cleanup - -```sh -make local-cleanup +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 ``` diff --git a/doc/user-guides/tls/gateway-tls.md b/doc/user-guides/tls/gateway-tls.md index e6952f0ce..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 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 +## 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 -```