Skip to content
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.

Sign up for GitHub

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

Adding/updating RLP use cases to docs #964

Merged
merged 1 commit into from
Dec 2, 2024
Merged

Adding/updating RLP use cases to docs #964

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 32 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ instead it will opt to connect with what’s there and what’s being developed

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
- 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

Expand All @@ -35,7 +35,7 @@ to operate the cluster ingress gateway to provide API management with **authenti
### Kuadrant components

| CRD | Description |
|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not know you could do this. Certainly is working (I can see in https://github.com/R-Lawton/kuadrant-operator/tree/doc-updates)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I cant take credit was my linter 😁

| 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) |
Expand All @@ -48,19 +48,19 @@ to operate the cluster ingress gateway to provide API management with **authenti

The kuadrant control plane owns the following [Custom Resource Definitions, CRDs](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/):

| CRD | Description | Example |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| AuthPolicy CRD [\[doc\]](doc/auth.md) [[reference]](doc/reference/authpolicy.md) | Enable AuthN and AuthZ based access control on workloads | [AuthPolicy CR](https://github.com/Kuadrant/kuadrant-operator/blob/main/examples/toystore/authpolicy.yaml) |
| RateLimitPolicy CRD [\[doc\]](doc/rate-limiting.md) [[reference]](doc/reference/ratelimitpolicy.md) | Enable access control on workloads based on HTTP rate limiting | [RateLimitPolicy CR](https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/examples/toystore/ratelimitpolicy_httproute.yaml) |
| DNSPolicy CRD [\[doc\]](doc/dns.md) [[reference]](doc/reference/dnspolicy.md) | Enable DNS management | [DNSPolicy CR](config/samples/kuadrant_v1_dnspolicy.yaml) |
| TLSPolicy CRD [\[doc\]](doc/tls.md) [[reference]](doc/reference/tlspolicy.md) | Enable TLS management | [TLSPolicy CR](config/samples/kuadrant_v1_tlspolicy.yaml) |
| CRD | Description | Example |
| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| AuthPolicy CRD [\[doc\]](doc/overviews/auth.md) [[reference]](doc/reference/authpolicy.md) | Enable AuthN and AuthZ based access control on workloads | [AuthPolicy CR](https://github.com/Kuadrant/kuadrant-operator/blob/main/examples/toystore/authpolicy.yaml) |
| RateLimitPolicy CRD [\[doc\]](doc/overviews/rate-limiting.md) [[reference]](doc/reference/ratelimitpolicy.md) | Enable access control on workloads based on HTTP rate limiting | [RateLimitPolicy CR](https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/examples/toystore/ratelimitpolicy_httproute.yaml) |
| DNSPolicy CRD [\[doc\]](doc/overviews/dns.md) [[reference]](doc/reference/dnspolicy.md) | Enable DNS management | [DNSPolicy CR](config/samples/kuadrant_v1_dnspolicy.yaml) |
| TLSPolicy CRD [\[doc\]](doc/overviews/tls.md) [[reference]](doc/reference/tlspolicy.md) | Enable TLS management | [TLSPolicy CR](config/samples/kuadrant_v1_tlspolicy.yaml) |

Additionally, Kuadrant provides the following CRDs

| CRD | Owner | Description | Example |
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| [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) |
| CRD | Owner | Description | Example |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [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://docs.kuadrant.io/latest/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) |

<img alt="Kuadrant Architecture" src="doc/images/kuadrant-architecture.svg" />
Expand All @@ -69,17 +69,17 @@ Additionally, Kuadrant provides the following CRDs

### Pre-requisites

* Istio or Envoy Gateway is installed in the cluster. Otherwise, refer to the
- Istio or Envoy Gateway is installed in the cluster. Otherwise, refer to the
[Istio getting started guide](https://istio.io/latest/docs/setup/getting-started/)
or [EnvoyGateway getting started guide](https://gateway.envoyproxy.io/docs/).
* Kubernetes Gateway API is installed in the cluster.
* cert-manager is installed in the cluster. Otherwise, refer to the
- Kubernetes Gateway API is installed in the cluster.
- cert-manager is installed in the cluster. Otherwise, refer to the
[cert-manager installation guide](https://cert-manager.io/docs/installation/).

### Installing Kuadrant

Installing Kuadrant is a two-step procedure. Firstly, install the Kuadrant Operator and secondly,
request a Kuadrant instance by creating a *Kuadrant* custom resource.
request a Kuadrant instance by creating a _Kuadrant_ custom resource.

#### 1. Install the Kuadrant Operator

Expand Down Expand Up @@ -130,41 +130,41 @@ EOF

### Protect your service

#### If you are an *API Provider*
#### If you are an _API Provider_

* Deploy the service/API to be protected ("Upstream")
* Expose the service/API using the kubernetes Gateway API, ie
- 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/reference/spec/#gateway.networking.k8s.io/v1.HTTPRoute) object.
* Write and apply the Kuadrant's [RateLimitPolicy](doc/rate-limiting.md) and/or
[AuthPolicy](doc/auth.md) custom resources targeting the HTTPRoute resource
- Write and apply the Kuadrant's [RateLimitPolicy](doc/overviews/rate-limiting.md) and/or
[AuthPolicy](doc/overviews/auth.md) custom resources targeting the HTTPRoute resource
to have your API protected.

#### If you are a *Cluster Operator*
#### If you are a _Cluster Operator_

* (Optionally) deploy ingress gateway using the
- (Optionally) deploy ingress gateway using the
[Gateway](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway) resource.
* Write and apply the Kuadrant's [RateLimitPolicy](doc/rate-limiting.md) and/or
[AuthPolicy](doc/auth.md) custom resources targeting the Gateway resource
- Write and apply the Kuadrant's [RateLimitPolicy](doc/overviews/rate-limiting.md) and/or
[AuthPolicy](doc/overviews/auth.md) custom resources targeting the Gateway resource
to have your gateway traffic protected.

## User guides

The user guides section of the docs gathers several use-cases as well as the instructions to implement them using kuadrant.

* [Simple Rate Limiting for Application Developers](doc/user-guides/simple-rl-for-app-developers.md)
* [Authenticated Rate Limiting for Application Developers](doc/user-guides/authenticated-rl-for-app-developers.md)
* [Gateway Rate Limiting for Cluster Operators](doc/user-guides/gateway-rl-for-cluster-operators.md)
* [Authenticated Rate Limiting with JWTs and Kubernetes RBAC](doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md)
- [Simple Rate Limiting for Application Developers](doc/user-guides/ratelimiting/simple-rl-for-app-developers.md)
- [Authenticated Rate Limiting for Application Developers](doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md)
- [Gateway Rate Limiting for Cluster Operators](doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md)
- [Authenticated Rate Limiting with JWTs and Kubernetes RBAC](doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md)

## [Kuadrant Rate Limiting](doc/rate-limiting.md)
## [Kuadrant Rate Limiting](doc/overviews/rate-limiting.md)

## Documentation

Docs can be found on the [Kuadrant website](https://kuadrant.io/).

## Contributing

The [Development guide](doc/development.md) describes how to build the kuadrant operator and
The [Development guide](doc/overviews/development.md) describes how to build the kuadrant operator and
how to test your changes before submitting a patch or opening a PR.

Join us on the [#kuadrant](https://kubernetes.slack.com/archives/C05J0D0V525) channel in the Kubernetes Slack workspace,
Expand All @@ -176,5 +176,4 @@ This software is licensed under the [Apache 2.0 license](https://www.apache.org/

See the LICENSE and NOTICE files that should have been provided along with this software for details.


[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FKuadrant%2Fkuadrant-operator.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FKuadrant%2Fkuadrant-operator?ref=badge_large)
16 changes: 8 additions & 8 deletions config/install/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
- Accessible Redis instance, for persistent storage for your rate limit counters. (Optional)


> Note: By default the following guide will install the "latest" or "main" version of Kuadrant. To pick a specific version, change the image in the `config/deploy/install/standard/kustomization.yaml`. All versions available can be found on the Kuadrant operator [release page](https://github.com/Kuadrant/kuadrant-operator/releases)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this directory doesnt exist

> Note: By default the following guide will install the "latest" or "main" version of Kuadrant. To pick a specific version, change the image in the `config/install/standard/kuadrant-version.yaml`. All versions available can be found on the Kuadrant operator [release page](https://github.com/Kuadrant/kuadrant-operator/releases)

> Note: for multiple clusters, it would make sense to do the installation via a tool like [argocd](https://argo-cd.readthedocs.io/en/stable/). For other methods of addressing multiple clusters take a look at the [kubectl docs](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)

Expand All @@ -19,19 +19,19 @@
> Note this uses the community operatorhub catalog. If you are installing on OpenShift and want to use the redhat provided catalog use the second command.


```
```bash
# community catalog
kubectl apply -k config/install/standard
```

```
```bash
# redhat catalog
kubectl apply -k config/install/openshift
```

Verify both Kuadrant and sail operators are installed. Note, that this can take a while. You can also take a look at the subscription and installplan resource to help with debugging but the end state should be as below:

```
```bash
kubectl get deployments -n kuadrant-system


Expand All @@ -45,7 +45,7 @@ kubectl get deployments -n kuadrant-system



```
```bash
kubectl get deployments -n gateway-system


Expand All @@ -71,7 +71,7 @@ This will configure Kuadrant and Sail to install their components, set the crede

Validate Kuadrant is ready via the kuadrant resource status condition

```
```bash
kubectl get kuadrant kuadrant -n kuadrant-system -o=yaml
```

Expand All @@ -81,7 +81,7 @@ At this point Kuadrant is ready to use. Below are some additional configuration

create a `redis-credential.env` in the `config/install/configure/redis-storage` dir

```
```bash
kubectl apply -k config/install/configure/redis-storage
```

Expand All @@ -91,7 +91,7 @@ This will setup limitador to use provided redis connection URL as a backend stor

Validate Kuadrant is in a ready state as before:

```
```bash
kubectl get kuadrant kuadrant -n kuadrant-system -o=yaml
```

Expand Down
2 changes: 1 addition & 1 deletion config/install/standard/kuadrant-version.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@ kind: CatalogSource
metadata:
name: kuadrant-operator-catalog
spec:
image: quay.io/kuadrant/kuadrant-operator-catalog:v1.0.0-rc6 #change this to the version you want to install
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

default should be latest

image: quay.io/kuadrant/kuadrant-operator-catalog:latest #change this to the version you want to install
13 changes: 3 additions & 10 deletions doc/install/install-kubernetes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# Install Kuadrant on a Kubernetes cluster

!!! note

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does this render ok with mkdocs (checkout a branch locally, update mkdocs.yaml to point to this branch for the kuadrant-operator component) ? could be wrong by I vaguely recall that maybe these newlines were needed - worth a quick check

Copy link
Contributor Author

@R-Lawton R-Lawton Nov 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no i havent checked good shout ill double check

You must perform these steps on each Kubernetes cluster where you want to use Kuadrant.

!!! warning
Expand Down Expand Up @@ -31,7 +30,6 @@ kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/downloa
### Install [OLM](https://olm.operatorframework.io/)

!!! note

Currently, we recommend installing our operator via OLM. We plan to support Helm soon.

```bash
Expand All @@ -41,12 +39,10 @@ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releas
### (Optional) Install Istio as a Gateway API provider

!!! note

Skip this step if planing to use [Envoy Gateway](https://gateway.envoyproxy.io/) as Gateway API provider

!!! note

There are several ways to install Istio (via `istioctl`, Helm chart or Operator) - this is just an example for starting from a bare Kubernetes cluster.
There are several ways to install Istio (via `istioctl`, Helm chart or Operator) - this is just an example for starting from a bare Kubernetes cluster.

```bash
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.5 sh -
Expand All @@ -58,12 +54,9 @@ kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/ma
### (Optional) Install Envoy Gateway as a Gateway API provider

!!! note

Skip this step if planing to use [Istio](https://istio.io/) as Gateway API provider

!!! note

There are several ways to install Envoy Gateway (via `egctl`, Helm chart or Kubernetes yaml) - this is just an example for starting from a bare Kubernetes cluster.
There are several ways to install Envoy Gateway (via `egctl`, Helm chart or Kubernetes yaml) - this is just an example for starting from a bare Kubernetes cluster.

```bash
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.1.0 -n envoy-gateway-system --create-namespace
Expand Down Expand Up @@ -213,4 +206,4 @@ If you are using a local kind cluster, we recommend using [metallb](https://meta

## Next Steps

- [Secure, protect, and connect APIs with Kuadrant on Kubernetes](../user-guides/secure-protect-connect.md)
- [Secure, protect, and connect APIs with Kuadrant on Kubernetes](../user-guides/full-walkthrough/secure-protect-connect-k8s.md)
Loading
Loading