Skip to content

Commit

Permalink
Link to docs site for any user content
Browse files Browse the repository at this point in the history 
Signed-off-by: David Martin <[email protected]>
  • Loading branch information
@david-martin
david-martin committed Jan 10, 2025
1 parent 4092c44 commit 5fde08a
Show file tree
Hide file tree
Showing 3 changed files with 6 additions and 1,214 deletions.
155 changes: 5 additions & 150 deletions README.md
View file
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

0 comments on commit 5fde08a

Please sign in to comment.