Merge pull request #446 from Boomatang/maintenance/docs

Maintenance/docs

README.md

@@ -11,17 +11,6 @@ Authorino is not about inventing anything new. It's about making the best things
 [![End-to-end Tests](https://github.com/Kuadrant/authorino/actions/workflows/e2e-test.yaml/badge.svg)](https://github.com/Kuadrant/authorino/actions/workflows/e2e-test.yaml)
 [![Smoke Tests](https://github.com/Kuadrant/authorino/actions/workflows/integration-test.yaml/badge.svg)](https://github.com/Kuadrant/authorino/actions/workflows/integration-test.yaml)
 
-## Table of contents
-
-- [Getting started](#getting-started)
-- [Use-cases](#use-cases)
-- [How it works](#how-it-works)
-- [List of features](#list-of-features)
-- [Documentation](./docs/README.md)
-- [FAQ](#faq)
-- [Benchmarks](#benchmarks)
-- [Contributing](#contributing)
-
 ## Getting started
 
 1. Deploy with the [Authorino Operator](https://github.com/kuadrant/authorino-operator)
@@ -240,7 +229,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 
   The only attribute of the authorization request that is strictly required is the host name. (See [Host lookup](./docs/architecture.md#host-lookup) for more information.) The other attributes, such as method, path, headers, etc, might as well be required, depending on each `AuthConfig`. In the case of the gRPC [`CheckRequest`](https://pkg.go.dev/github.com/envoyproxy/go-control-plane/envoy/service/auth/v3?utm_source=gopls#CheckRequest) method, the host is supplied in `Attributes.Request.Http.Host` and alternatively in `Attributes.ContextExtensions["host"]`. For raw HTTP authorization requests, the host must be supplied in `Host` HTTP header.
 
-  Check out [Kuadrant](https://github.com/kuadrant/kuadrant-controller) for easy-to-use Envoy and Authorino deployment & configuration for API management use-cases, using Kubernetes Custom Resources.
+  Check out [Kuadrant](https://docs.kuadrant.io/kuadrant-operator) for easy-to-use Envoy and Authorino deployment & configuration for API management use-cases, using Kubernetes Custom Resources.
 </details>
 
 <details markdown="1">
@@ -303,7 +292,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 
   There are lots of similarities, but also complementarity between Authorino and Istio and [Istio Authorization](https://istio.io/latest/docs/concepts/security/#authorization) in special.
 
-  Istio provides a simple way to enable features that are, in many cases, features of Envoy, such as authorization based on JWTs, authorization based on attributes of the request, and activation of external authorization services, without having to deal with complex Envoy config files. See [Kuadrant](https://github.com/kuadrant/kuadrant-controller) for a similar approach, nonetheless leveraging features of Istio as well.
+  Istio provides a simple way to enable features that are, in many cases, features of Envoy, such as authorization based on JWTs, authorization based on attributes of the request, and activation of external authorization services, without having to deal with complex Envoy config files. See [Kuadrant](https://doc.kuadrant.io/kuadrant-operator) for a similar approach, nonetheless leveraging features of Istio as well.
 
   Authorino is an Envoy-compatible external authorization service. One can use Authorino with or without Istio.
 
@@ -312,6 +301,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   Authorino also provides built-in OPA authorization, several other methods of authentication and identity verification (e.g. Kubernetes token validation, API key-based authentication, OAuth token introspection, OIDC-discoverable JWT verification, etc), and features like fetching of external metadata (HTTP services, OIDC userinfo, UMA resource data), token normalization, wristband tokens and dynamic responses. These all can be used independently or combined, in a simple and straightforward Kubernetes-native fashion.
 
   In summary, one might value Authorino when looking for a policy enforcer that offers:
+
   1. multiple supported methods and protocols for rather hybrid authentication, encompassing future and legacy auth needs;
   2. broader expressiveness and more functionalities for the authorization rules;
   3. authentication and authorization in one single declarative manifest;
@@ -362,7 +352,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 <details markdown="1">
   <summary><strong>Do I have to be admin of the cluster to install Authorino?</strong></summary>
 
-  To install the Authorino Custom Resource Definition (CRD) and to define cluster roles required by the Authorino service, admin privilege to the Kubernetes cluster is required. This step happens only once per cluster and is usually equivalent to installing the [Authorino Operator](https://github.com/kuadrant/authorino-operator).
+  To install the Authorino Custom Resource Definition (CRD) and to define cluster roles required by the Authorino service, admin privilege to the Kubernetes cluster is required. This step happens only once per cluster and is usually equivalent to installing the [Authorino Operator](https://docs.kuadrant.io/authorino-operator).
 
   Thereafter, deploying instances of the Authorino service and applying `AuthConfig` custom resources to a namespace depend on the permissions set by the cluster administrator – either directly by editing the bindings in the cluster's RBAC, or via options of the operator. In most cases, developers will be granted permissions to create and manage `AuthConfig`s, and sometimes to deploy their own instances of Authorino.
 </details>
@@ -390,6 +380,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 ## Benchmarks
 
 **Configuration of the tests (Authorino features):**
+
 | Performance test           | Identity  | Metadata      | Authorization                                          | Response |
 |----------------------------|:---------:|:-------------:|:------------------------------------------------------:|:--------:|
 | `ReconcileAuthConfig`      | OIDC/JWT  | UserInfo, UMA | OPA<br/><sup>(inline Rego)</sup>                       | -        |

docs/architecture.md

@@ -1,27 +1,4 @@
 # Architecture
-- [Overview](#overview)
-- [Topologies](#topologies)
-  - [Centralized gateway](#centralized-gateway)
-  - [Centralized authorization service](#centralized-authorization-service)
-  - [Sidecars](#sidecars)
-- [Cluster-wide vs. Namespaced instances](#cluster-wide-vs-namespaced-instances)
-- [The Authorino `AuthConfig` Custom Resource Definition (CRD)](#the-authorino-authconfig-custom-resource-definition-crd)
-- [Resource reconciliation and status update](#resource-reconciliation-and-status-update)
-- [The "Auth Pipeline" (_aka:_ enforcing protection in request-time)](#the-auth-pipeline-aka-enforcing-protection-in-request-time)
-- [Host lookup](#host-lookup)
-  - [Avoiding host name collision](#avoiding-host-name-collision)
-- [The Authorization JSON](#the-authorization-json)
-- [Raw HTTP Authorization interface](#raw-http-authorization-interface)
-- [Caching](#caching)
-  - [OpenID Connect and User-Managed Access configs](#openid-connect-and-user-managed-access-configs)
-  - [JSON Web Keys (JWKs) and JSON Web Key Sets (JWKS)](#json-web-keys-jwks-and-json-web-key-sets-jwks)
-  - [Revoked access tokens](#revoked-access-tokens)
-  - [External metadata](#external-metadata)
-  - [Compiled Rego policies](#compiled-rego-policies)
-  - [Repeated requests](#repeated-requests)
-- [Sharding](#sharding)
-- [RBAC](#rbac)
-- [Observability](#observability)
 
 ## Overview
 
@@ -48,6 +25,7 @@ On every request, Authorino's "working memory" is called [**Authorization JSON**
 Typically, upstream APIs are deployed to the same Kubernetes cluster and namespace where the Envoy proxy and Authorino is running (although not necessarily). Whatever is the case, Envoy must be proxying to the upstream API (see Envoy's [HTTP route components](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto) and virtual hosts) and pointing to Authorino in the external authorization filter.
 
 This can be achieved with different topologies:
+
 - Envoy can be a [centralized gateway](#centralized-gateway) with one dedicated instance of Authorino, proxying to one or more upstream services
 - Envoy can be deployed as a sidecar of each protected service, but still contacting from a [centralized Authorino authorization service](#centralized-authorization-service)
 - Both Envoy and Authorino deployed as [sidecars](#sidecars) of the protected service, restricting all communication between them to localhost
@@ -78,7 +56,7 @@ Apart from that, protected service should only listen on `localhost` and all tra
 
 Authorino instances can run in either **cluster-wide** or **namespaced** mode.
 
-Namespace-scoped instances only watch resources (`AuthConfig`s and `Secret`s) created in a given namespace. This deployment mode does not require admin privileges over the Kubernetes cluster to deploy the instance of the service (given Authorino's CRDs have been installed beforehand, such as when Authorino is installed using the [Authorino Operator](https://github.com/kuadrant-authorino-operator)).
+Namespace-scoped instances only watch resources (`AuthConfig`s and `Secret`s) created in a given namespace. This deployment mode does not require admin privileges over the Kubernetes cluster to deploy the instance of the service (given Authorino's CRDs have been installed beforehand, such as when Authorino is installed using the [Authorino Operator](https://github.com/kuadrant/authorino-operator)).
 
 Cluster-wide deployment mode, in contraposition, deploys instances of Authorino that watch resources across the entire cluster, consolidating all resources into a multi-namespace index of auth configs. Admin privileges over the Kubernetes cluster is required to deploy Authorino in cluster-wide mode.
 
@@ -221,6 +199,7 @@ When more than one host name is specified in the `AuthConfig`, all of them can b
 ![Domain tree](http://www.plantuml.com/plantuml/png/RP71ReCm38RlVWhKuoGcjN2U-YPLb6MTDS0e9E-_v8zgNC4fyVU5nFo-Ryd5bEU9Ol39BSyfT9VFI-UsBeeaijZB355MYzUGDl2wiU93wQE-OfNpSu2jcpUnil97AOxtmU0-wrWWMOuVi1oUNtY5Agl5oKr_8VQl7bg9BiXpzEWlfrylomy_-oiELN0zqpVLjpCzg1xEzAXw92g1TtrU-pQI6YXA3AB6iLSQTaEOo2lAXX2uPcWOiPX7M8ndePAKxlTSW90Y4O80-DB8yVUDsJGjrev1XqPr_82ZXJXw3yjtdgT_)
 
 The domain tree above induces the following relation:
+
 - `foo.nip.io` → `authconfig-1` (matches `*.io`)
 - `talker-api.nip.io` → `authconfig-2` (matches `talker-api.nip.io`)
 - `dogs.pets.com` → `authconfig-2` (matches `*.pets.com`)
@@ -312,6 +291,7 @@ For information about reading and fetching data from the Authorization JSON (syn
 ## Raw HTTP Authorization interface
 
 Besides providing the gRPC authorization interface – that implements the Envoy gRPC authorization server –, Authorino also provides another interface for **raw HTTP authorization**. This second interface responds to `GET` and `POST` HTTP requests sent to `:5001/check`, and is suitable for other forms of integration, such as:
+
 - using Authorino as Kubernetes ValidatingWebhook service ([example](./user-guides/validating-webhook.md));
 - other HTTP proxies and API gateways;
 - old versions of Envoy incompatible with the latest version of gRPC external authorization protocol (Authorino is based on v3.19.1 of Envoy external authorization API)
@@ -373,6 +353,7 @@ By default, Authorino instances will watch `AuthConfig` CRs in the entire space
 The benefits of limiting the space of reconciliation of an Authorino instance include avoiding unnecessary caching and workload in instances that do not receive corresponding traffic (according to your routing settings) and preventing leaders of multiple instances (sets of replicas) to compete on resource status updates (see [Resource reconciliation and status update](#resource-reconciliation-and-status-update) for details).
 
 Use-cases for sharding of `AuthConfig`s:
+
 - Horizontal load balancing of traffic of authorization requests
 - Supporting for managed centralized instances of Authorino to API owners who create and maintain their own `AuthConfig`s within their own user namespaces.
 

docs/contributing.md

@@ -1,24 +1,9 @@
 # Developer's Guide
 
-- [Technology stack for developers](#technology-stack-for-developers)
-- [Workflow](#workflow)
-  - [Check the issues](#check-the-issues)
-  - [Clone the repo and setup the local environment](#clone-the-repo-and-setup-the-local-environment)
-  - [Make your changes](#make-your-changes)
-  - [Run the tests](#run-the-tests)
-  - [Try locally](#try-locally)
-    - [Build, deploy and try Authorino in a local cluster](#build-deploy-and-try-authorino-in-a-local-cluster)
-    - [Additional tools (for specific use-cases)](#additional-tools-for-specific-use-cases)
-    - [Re-build and rollout latest](#re-build-and-rollout-latest)
-    - [Clean-up](#clean-up)
-  - [Sign your commits](#sign-your-commits)
-- [Logging policy](#logging-policy)
-- [Additional resources](#additional-resources)
-- [Reach out](#reach-out)
-
 ## Technology stack for developers
 
 Minimum requirements to contribute to Authorino are:
+
 - [Golang v1.20+](https://golang.org)
 - [Docker](https://docker.com)
 
@@ -27,17 +12,17 @@ Authorino's code was originally bundled using the [Operator SDK](https://sdk.ope
 The following tools can be installed as part of the development workflow:
 
 - _Installed with `go install` to the `$PROJECT_DIR/bin` directory:_
-  - [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html): for building custom types and manifests
-  - [Kustomize](https://kustomize.io/): for assembling flavoured manifests and installing/deploying
-  - [setup-envtest](https://v0-19-x.sdk.operatorframework.io/docs/golang/references/env-test-setup): for running the tests – extra tools installed to `./testbin`
-  - [benchstat](https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports
-  - [mockgen](https://github.com/golang/mock/mockgen): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go`
-  - [Kind](https://kind.sigs.k8s.io): for deploying a containerized Kubernetes cluster for integration testing purposes
+    - [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html): for building custom types and manifests
+    - [Kustomize](https://kustomize.io/): for assembling flavoured manifests and installing/deploying
+    - [setup-envtest](https://book.kubebuilder.io/reference/envtest.html): for running the tests – extra tools installed to `./testbin`
+    - [benchstat](https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports
+    - [mockgen](https://github.com/golang/mock): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go`
+    - [Kind](https://kind.sigs.k8s.io): for deploying a containerized Kubernetes cluster for integration testing purposes
 
 - _Other recommended tools to have installed:_
-  - [jq](https://stedolan.github.io/jq/)
-  - [yq](http://mikefarah.github.io/yq/)
-  - [gnu-sed](https://www.gnu.org/software/sed/)
+    - [jq](https://stedolan.github.io/jq/)
+    - [yq](https://mikefarah.github.io/yq/)
+    - [gnu-sed](https://www.gnu.org/software/sed/)
 
 ## Workflow
 
@@ -71,6 +56,7 @@ make help
 ### Make your changes
 
 Good changes...
+
 - follow the [Golang conventions](https://golang.org/doc/effective_go)
 - have proper test coverage
 - address corresponding updates to the [docs](./)
@@ -89,6 +75,7 @@ make test
 #### Build, deploy and try Authorino in a local cluster
 
 The following command will:
+
 - Start a local Kubernetes cluster (using Kind)
 - Install [cert-manager](https://github.com/jetstack/cert-manager) in the cluster
 - Install the [Authorino Operator](https://github.com/kuadrant/authorino-operator) and Authorino CRDs
@@ -140,7 +127,7 @@ kubectl port-forward deployment/envoy 8000:8000 &
 
   Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup:
 
-  - Admin console: http://localhost:8080/auth/admin (admin/p)
+  - Admin console: [http://localhost:8080/admin](http://localhost:8080/admin)  (admin/p)
   - Preloaded realm: **kuadrant**
   - Preloaded clients:
     - **demo**: to which API consumers delegate access and therefore the one which access tokens are issued to
@@ -247,6 +234,7 @@ All commits to be accepted to Authorino's code are required to be signed. Refer
 ## Logging policy
 
 A few guidelines for adding logging messages in your code:
+
 1. Make sure you understand Authorino's [Logging](./user-guides/observability.md#logging) architecture and policy regarding log levels, log modes, tracing IDs, etc.
 2. Respect controller-runtime's [Logging Guidelines](https://github.com/kubernetes-sigs/controller-runtime/blob/master/TMP-LOGGING.md).
 3. Do not add sensitive data to your `info` log messages; instead, redact all sensitive data in your log messages or use `debug` log level by mutating the logger with `V(1)` before outputting the message.