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

Link to docs site for any user content #1106

Merged
merged 1 commit into from
Jan 15, 2025
Merged

Link to docs site for any user content #1106

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
155 changes: 5 additions & 150 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,160 +7,15 @@
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9242/badge)](https://www.bestpractices.dev/projects/9242)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FKuadrant%2Fkuadrant-operator.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FKuadrant%2Fkuadrant-operator?ref=badge_shield)

The Operator to install and manage the lifecycle of the [Kuadrant](https://github.com/Kuadrant/) components deployments.

## Overview

Kuadrant is a re-architecture of API Management using Cloud Native concepts and separating the components to be less coupled,
more reusable and leverage the underlying kubernetes platform. It aims to deliver a smooth experience to providers and consumers
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,
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 the [Gateway API](https://gateway-api.sigs.k8s.io/) and one Gateway API provider
being installed on the cluster. Currently only [Istio](https://istio.io/) and
[EnvoyGateway](https://gateway.envoyproxy.io/) are supported
to operate the cluster 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 |
| [DNS Operator](https://github.com/Kuadrant/dns-operator) | A Kubernetes Operator to manage DNS records in external providers |

### Provided APIs

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/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) |
| [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" />

## Getting started

### Pre-requisites

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

#### 1. Install the Kuadrant Operator

The Kuadrant Operator is available in public community operator catalogs, such as the Kubernetes [OperatorHub.io](https://operatorhub.io/operator/kuadrant-operator) and the [Openshift Container Platform and OKD OperatorHub](https://redhat-openshift-ecosystem.github.io/community-operators-prod).

**Kubernetes**

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

# Install the operator by running the following command:

kubectl create -f https://operatorhub.io/install/kuadrant-operator.yaml
```

**Openshift**

The operator is available from the [Openshift Console OperatorHub](https://docs.openshift.com/container-platform/4.11/operators/user/olm-installing-operators-in-namespace.html#olm-installing-from-operatorhub-using-web-console_olm-installing-operators-in-namespace).
Just follow installation steps choosing the "Kuadrant Operator" from the catalog:

![Kuadrant Operator in OperatorHub](https://content.cloud.redhat.com/hs-fs/hubfs/ogFyppY.png?width=449&height=380&name=ogFyppY.png)

#### 2. Request a Kuadrant instance

Create the namespace:

```sh
kubectl create namespace kuadrant
```

Apply the `Kuadrant` custom resource:

```sh
kubectl -n kuadrant apply -f - <<EOF
---
apiVersion: kuadrant.io/v1beta1
kind: Kuadrant
metadata:
name: kuadrant-sample
spec: {}
EOF
```

### Protect your service

#### If you are an _API Provider_

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

- (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/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/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/overviews/rate-limiting.md)
Kuadrant leverages [Gateway API](https://gateway-api.sigs.k8s.io/) and [Policy Attachment](https://gateway-api.sigs.k8s.io/geps/gep-2648/) to enhance gateway providers like [Istio](https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/) and [Envoy Gateway](https://gateway.envoyproxy.io/) with additional features via Policies. Those features include TLS, DNS, application authentication & authorization, and rate limiting.

## Documentation
You can find more information on the different aspects of Kuadrant at the documentation links below:

Docs can be found on the [Kuadrant website](https://kuadrant.io/).
- [Overview](https://docs.kuadrant.io)
- [Getting Started & Installation](https://docs.kuadrant.io/dev/getting-started/)
- [Architecture](https://docs.kuadrant.io/dev/architecture/docs/design/architectural-overview-v1/)

## Contributing

Expand Down
Loading
Loading