From 846e84305680b676d84b9c9764c8e14999c8ba23 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Wed, 22 Nov 2023 15:40:02 +0000 Subject: [PATCH] Maintenance/docs (#294) * Update development guide for website - Remove TOC * Update Readme - remove TOC - update links * Update jwt and k8s RBAC guide for wedsite - fix list render - add markdown flag to summary blocks - update links * Update Authenticated rate limitinh for application developers guide - remove extra spacing - fix list render for website * Fix merge issue --- README.md | 23 +------------------ doc/development.md | 21 ----------------- .../authenticated-rl-for-app-developers.md | 9 +------- ...uthenticated-rl-with-jwt-and-k8s-authnz.md | 7 +++--- 4 files changed, 5 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index e793a8ef9..1d38af30b 100644 --- a/README.md +++ b/README.md @@ -7,27 +7,6 @@ The Operator to install and manage the lifecycle of the [Kuadrant](https://github.com/Kuadrant/) components deployments. - -- [Overview](#overview) -- [Architecture](#architecture) - - [Kuadrant components](#kuadrant-components) - - [Provided APIs](#provided-apis) -- [Getting started](#getting-started) - - [Pre-requisites](#pre-requisites) - - [Installing Kuadrant](#installing-kuadrant) - - [1. Install the Kuadrant Operator](#1-install-the-kuadrant-operator) - - [2. Request a Kuadrant instance](#2-request-a-kuadrant-instance) - - [Protect your service](#protect-your-service) - - [If you are an *API Provider*](#if-you-are-an-api-provider) - - [If you are a *Cluster Operator*](#if-you-are-a-cluster-operator) -- [User guides](#user-guides) -- [Kuadrant Rate Limiting](#kuadrant-rate-limiting) -- [Documentation](#documentation) -- [Contributing](#contributing) -- [Licensing](#licensing) - - - ## Overview Kuadrant is a re-architecture of API Management using Cloud Native concepts and separating the components to be less coupled, @@ -75,7 +54,7 @@ Additionally, Kuadrant provides the following CRDs |--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | [Kuadrant CRD](https://github.com/Kuadrant/kuadrant-operator/blob/main/api/v1beta1/kuadrant_types.go) | [Kuadrant Operator](https://github.com/Kuadrant/kuadrant-operator) | Represents an instance of kuadrant | [Kuadrant CR](https://github.com/Kuadrant/kuadrant-operator/blob/main/config/samples/kuadrant_v1beta1_kuadrant.yaml) | | [Limitador CRD](https://github.com/Kuadrant/limitador-operator/blob/main/api/v1alpha1/limitador_types.go) | [Limitador Operator](https://github.com/Kuadrant/limitador-operator) | Represents an instance of Limitador | [Limitador CR](https://github.com/Kuadrant/limitador-operator/blob/main/config/samples/limitador_v1alpha1_limitador.yaml) | -| [Authorino CRD](https://github.com/Kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) | [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | Represents an instance of Authorino | [Authorino CR](https://github.com/Kuadrant/authorino-operator/blob/main/config/samples/authorino-operator_v1beta1_authorino.yaml) | +| [Authorino CRD](https://docs.kuadrant.io/authorino-operator/#the-authorino-custom-resource-definition-crd) | [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | Represents an instance of Authorino | [Authorino CR](https://github.com/Kuadrant/authorino-operator/blob/main/config/samples/authorino-operator_v1beta1_authorino.yaml) | Kuadrant Architecture diff --git a/doc/development.md b/doc/development.md index fa0994d7a..acd960afe 100644 --- a/doc/development.md +++ b/doc/development.md @@ -1,26 +1,5 @@ # Development Guide - - * [Technology stack required for development](#technology-stack-required-for-development) - * [Build](#build) - * [Run locally](#run-locally) - * [Deploy the operator in a deployment object](#deploy-the-operator-in-a-deployment-object) - * [Deploy kuadrant operator using OLM](#deploy-kuadrant-operator-using-olm) - * [Build custom OLM catalog](#build-custom-olm-catalog) - * [Build kuadrant operator bundle image](#build-kuadrant-operator-bundle-image) - * [Build custom catalog](#build-custom-catalog) - * [Cleaning up](#cleaning-up) - * [Run tests](#run-tests) - * [Unit tests](#unittests) - * [Integration tests](#integration-tests) - * [All tests](#all-tests) - * [Lint tests](#lint-tests) - * [(Un)Install Kuadrant CRDs](#uninstall-kuadrant-crds) - - - - - ## Technology stack required for development * [operator-sdk] version v1.28.1 diff --git a/doc/user-guides/authenticated-rl-for-app-developers.md b/doc/user-guides/authenticated-rl-for-app-developers.md index dda1c795d..e0e22b83f 100644 --- a/doc/user-guides/authenticated-rl-for-app-developers.md +++ b/doc/user-guides/authenticated-rl-for-app-developers.md @@ -2,15 +2,12 @@ This user guide 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: + - User A can send up to 50rps ("requests per second"), while User B can send up to 100rps. - 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**. In reality, this API is just 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**. @@ -20,8 +17,6 @@ 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") | -
- ## Run the steps ① → ④ ### ① Setup @@ -225,8 +220,6 @@ EOF > **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 as Alice and Bob. Up to 5 successful (`200 OK`) requests every 10 seconds allowed for Alice, then `429 Too Many Requests`: diff --git a/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md b/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md index 1393c822b..c4844c649 100644 --- a/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md +++ b/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md @@ -1,13 +1,12 @@ # 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: + - authentication based OpenId Connect (OIDC) ID tokens (signed JWTs), issued by a Keycloak server; - alternative authentication method by Kubernetes Service Account tokens; - authorization delegated to Kubernetes RBAC system; - rate limiting by user ID. -
- In this example, we will protect 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 hostnames `*.toystore.com`, where it exposes the endpoints `GET /toy*`, `POST /admin/toy` and `DELETE /amind/toy`, respectively, to mimic operations of reading, creating, and deleting toy records. @@ -266,14 +265,14 @@ subjects: EOF ``` -
+
Q: Can I use Roles and RoleBindings instead of ClusterRoles and ClusterRoleBindings? Yes, you can. The example above is for non-resource URL Kubernetes roles. For using `Roles` and `RoleBindings` instead of `ClusterRoles` and `ClusterRoleBindings`, thus more flexible resource-based permissions to protect the API, - see the spec for [Kubernetes SubjectAccessReview authorization](https://github.com/Kuadrant/authorino/blob/v0.5.0/docs/features.md#kubernetes-subjectaccessreview-authorizationkubernetes) + see the spec for [Kubernetes SubjectAccessReview authorization](https://docs.kuadrant.io/authorino/docs/features/#kubernetes-subjectaccessreview-authorizationkubernetessubjectaccessreview) in the Authorino docs.