-
Notifications
You must be signed in to change notification settings - Fork 32
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: minor improvements #217
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -18,7 +18,7 @@ The Operator to install and manage the lifecycle of the [Kuadrant](https://githu | |
* [If you are an <em>API Provider</em>](#if-you-are-an-api-provider) | ||
* [If you are a <em>Cluster Operator</em>](#if-you-are-a-cluster-operator) | ||
* [User guides](#user-guides) | ||
* [<a href="/doc/rate-limiting.md">Kuadrant Rate Limiting</a>](#kuadrant-rate-limiting) | ||
* [<a href="doc/rate-limiting.md">Kuadrant Rate Limiting</a>](#kuadrant-rate-limiting) | ||
* [Documentation](#documentation) | ||
* [Contributing](#contributing) | ||
* [Licensing](#licensing) | ||
|
@@ -32,29 +32,30 @@ more reusable and leverage the underlying kubernetes platform. It aims to delive | |
of applications & services when it comes to rate limiting, authentication, authorization, discoverability, change management, usage contracts, insights, etc. | ||
|
||
Kuadrant aims to produce a set of loosely coupled functionalities built directly on top of Kubernetes. | ||
Furthermore it only strives to provide what Kubernetes doesn’t offer out of the box, i.e. Kuadrant won’t be designing a new Gateway/proxy, | ||
Furthermore, it only strives to provide what Kubernetes doesn’t offer out of the box, i.e. Kuadrant won’t be designing a new Gateway/proxy, | ||
instead it will opt to connect with what’s there and what’s being developed (think Envoy, Istio, GatewayAPI). | ||
|
||
Kuadrant is a system of cloud-native k8s components that grows as users’ needs grow. | ||
|
||
* From simple protection of a Service (via **AuthN**) that is used by teammates working on the same cluster, or “sibling” services, up to **AuthZ** of users using OIDC plus custom policies. | ||
* From no rate-limiting to rate-limiting for global service protection on to rate-limiting by users/plans | ||
|
||
## Architecture | ||
|
||
Kuadrant relies on [Istio](https://istio.io/) and the [Gateway API](https://gateway-api.sigs.k8s.io/) | ||
to operate the cluster (istio's) ingress gateway to provide API management with **authentication** (authN), | ||
to operate the cluster (Istio's) ingress gateway to provide API management with **authentication** (authN), | ||
**authorization** (authZ) and **rate limiting** capabilities. | ||
|
||
### Kuadrant components | ||
|
||
| CRD | Description | | ||
| --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| Control Plane | The control plane takes the customer desired configuration (declaratively as kubernetes custom resources) as input and ensures all components are configured to obey customer's desired behavior.<br> This repository contains the source code of the kuadrant control plane | | ||
| [Kuadrant Operator](https://github.com/Kuadrant/kuadrant-operator) | A Kubernetes Operator to manage the lifecycle of the kuadrant deployment | | ||
| [Authorino](https://github.com/Kuadrant/authorino) | The AuthN/AuthZ enforcer. As the [external istio authorizer](https://istio.io/latest/docs/tasks/security/authorization/authz-custom/) ([envoy external authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter) serving gRPC service) | | ||
| [Limitador](https://github.com/Kuadrant/limitador) | The external rate limiting service. It exposes a gRPC service implementing the [Envoy Rate Limit protocol (v3)](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/ratelimit/v3/rls.proto) | | ||
| [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | A Kubernetes Operator to manage Authorino instances | | ||
| [Limitador Operator](https://github.com/Kuadrant/limitador-operator) | A Kubernetes Operator to manage Limitador instances | | ||
| CRD | Description | | ||
|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| Control Plane | The control plane takes the customer desired configuration (declaratively as kubernetes custom resources) as input and ensures all components are configured to obey customer's desired behavior.<br> This repository contains the source code of the kuadrant control plane | | ||
| [Kuadrant Operator](https://github.com/Kuadrant/kuadrant-operator) | A Kubernetes Operator to manage the lifecycle of the kuadrant deployment | | ||
| [Authorino](https://github.com/Kuadrant/authorino) | The AuthN/AuthZ enforcer. As the [external istio authorizer](https://istio.io/latest/docs/tasks/security/authorization/authz-custom/) ([envoy external authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter) serving gRPC service) | | ||
| [Limitador](https://github.com/Kuadrant/limitador) | The external rate limiting service. It exposes a gRPC service implementing the [Envoy Rate Limit protocol (v3)](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/ratelimit/v3/rls.proto) | | ||
| [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | A Kubernetes Operator to manage Authorino instances | | ||
| [Limitador Operator](https://github.com/Kuadrant/limitador-operator) | A Kubernetes Operator to manage Limitador instances | | ||
|
||
### Provided APIs | ||
|
||
|
@@ -86,7 +87,7 @@ Additionally, Kuadrant provides the following CRDs | |
|
||
### Installing Kuadrant | ||
|
||
Installing Kuadrant is a two-step procedure. Firstly, install the Kuadrant Operator and seconly, | ||
Installing Kuadrant is a two-step procedure. Firstly, install the Kuadrant Operator and secondly, | ||
request a Kuadrant instance by creating a *Kuadrant* custom resource. | ||
|
||
#### 1. Install the Kuadrant Operator | ||
|
@@ -98,14 +99,14 @@ The Kuadrant Operator is available in public community operator catalogs, such a | |
The operator is available from [OperatorHub.io](https://operatorhub.io/operator/kuadrant-operator). | ||
Just go to the linked page and follow installation steps (or just run these two commands): | ||
|
||
``` | ||
```sh | ||
# Install Operator Lifecycle Manager (OLM), a tool to help manage the operators running on your cluster. | ||
|
||
$ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.23.1/install.sh | bash -s v0.23.1 | ||
curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.23.1/install.sh | bash -s v0.23.1 | ||
|
||
# Install the operator by running the following command: | ||
|
||
$ kubectl create -f https://operatorhub.io/install/kuadrant-operator.yaml | ||
kubectl create -f https://operatorhub.io/install/kuadrant-operator.yaml | ||
``` | ||
|
||
**Openshift** | ||
|
@@ -125,12 +126,13 @@ kubectl create namespace kuadrant | |
|
||
Apply the `Kuadrant` custom resource: | ||
|
||
```yaml | ||
kubectl apply -n kuadrant -f -<<EOF | ||
```sh | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nitpick: technically it is a shell script, but I would be highlighting the yaml content There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Plus, if you keep it as There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah, this is a hard one 🤔 TBH previously, we are not consistent in this use for code blocks. In some places, we use While highlighting for yaml is nice, I've went with There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. take my money |
||
kubectl -n kuadrant apply -f - <<EOF | ||
--- | ||
apiVersion: kuadrant.io/v1beta1 | ||
kind: Kuadrant | ||
metadata: | ||
name: kuadrant | ||
name: kuadrant-sample | ||
spec: {} | ||
EOF | ||
``` | ||
|
@@ -142,16 +144,16 @@ EOF | |
* Deploy the service/API to be protected ("Upstream") | ||
* Expose the service/API using the kubernetes Gateway API, ie | ||
[HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute) object. | ||
* Write and apply the Kuadrant's [RateLimitPolicy](/doc/rate-limiting.md) and/or | ||
[AuthPolicy](apis/apim/v1alpha1/authpolicy_types.go) custom resources targeting the HTTPRoute resource | ||
* Write and apply the Kuadrant's [RateLimitPolicy](doc/rate-limiting.md) and/or | ||
[AuthPolicy](api/v1beta1/authpolicy_types.go) custom resources targeting the HTTPRoute resource | ||
to have your API protected. | ||
|
||
#### If you are a *Cluster Operator* | ||
|
||
* (Optionally) deploy istio ingress gateway using the | ||
[Gateway](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1beta1.Gateway) resource. | ||
* Write and apply the Kuadrant's [RateLimitPolicy](/doc/rate-limiting.md) and/or | ||
[AuthPolicy](apis/apim/v1alpha1/authpolicy_types.go) custom resources targeting the Gateway resource | ||
* Write and apply the Kuadrant's [RateLimitPolicy](doc/rate-limiting.md) and/or | ||
[AuthPolicy](api/v1beta1/authpolicy_types.go) custom resources targeting the Gateway resource | ||
to have your gateway traffic protected. | ||
|
||
## User guides | ||
|
@@ -163,7 +165,7 @@ The user guides section of the docs gathers several use-cases as well as the ins | |
* [Gateway rate limiting for cluster operators](doc/user-guides/gateway-rl-for-cluster-operators.md) | ||
* [Authenticated rate limiting with JWTs and Kubernetes authnz](doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md) | ||
|
||
## [Kuadrant Rate Limiting](/doc/rate-limiting.md) | ||
## [Kuadrant Rate Limiting](doc/rate-limiting.md) | ||
|
||
## Documentation | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just for curiosity, is
/doc/rate-limiting.md
wrong? the link seems to be working (on Linux/Firefox)There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The leading slash breaks it in https://docs.kuadrant.io/kuadrant-operator/. Not sure if using the simple relative path will solve it tho.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It works but it is broken in the website for the above in the table of contents ^^ . I am also not sure will this change fix it since it links to https://docs.kuadrant.io/doc/rate-limiting.md vs https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/ which seems to be the correct url instead 🤷
Though this change is also to give consitency to references to other docs in the repo. In most other links, we use
docs/x
instead of/docs/x
🤔