Merge pull request #367 from Kuadrant/docs/observability

[docs] Observability and CLI

docs/architecture.md

@@ -154,7 +154,7 @@ More concrete examples of `AuthConfig`s for specific use-cases can be found in t
 
 The instances of the Authorino authorization service workload, following the [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator), watch events related to the `AuthConfig` custom resources, to build and reconcile an in-memory index of configs. Whenever a replica receives traffic for authorization request, it [looks up in the index](#host-lookup) of `AuthConfig`s and then [triggers the "Auth Pipeline"](#the-auth-pipeline-aka-enforcing-protection-in-request-time), i.e. enforces the associated auth spec onto the request.
 
-An instance can be a single authorization service workload or a set of replicas. All replicas watch and reconcile the same set of resources that match the `AUTH_CONFIG_LABEL_SELECTOR` and `SECRET_LABEL_SELECTOR` configuration options. (See both [Cluster-wide vs. Namespaced instances](#cluster-wide-vs-namespaced-instances) and [Sharding](#sharding), for details about defining the reconciliation space of Authorino instances.)
+An instance can be a single authorization service workload or a set of replicas. All replicas watch and reconcile the same set of resources that match the `--auth-config-label-selector` and `--secret-label-selector` configuration options. (See both [Cluster-wide vs. Namespaced instances](#cluster-wide-vs-namespaced-instances) and [Sharding](#sharding), for details about defining the reconciliation space of Authorino instances.)
 
 The above means that all replicas of an Authorino instance should be able to receive traffic for authorization requests.
 
@@ -164,7 +164,7 @@ The status of an `AuthConfig` tells whether the resource is "ready" (i.e. indexe
 
 Apart from watching events related to `AuthConfig` custom resources, Authorino also watches events related to Kubernetes `Secret`s, as part of Authorino's [API key authentication](./features.md#api-key-identityapikey) feature. `Secret` resources that store API keys are linked to their corresponding `AuthConfig`s in the index. Whenever the Authorino instance detects a change in the set of API key `Secret`s linked to an `AuthConfig`s, the instance reconciles the index.
 
-Authorino only watches events related to `Secret`s whose `metadata.labels` match the label selector `SECRET_LABEL_SELECTOR` of the Authorino instance. The default values of the label selector for Kubernetes `Secret`s representing Authorino API keys is `authorino.kuadrant.io/managed-by=authorino`.
+Authorino only watches events related to `Secret`s whose `metadata.labels` match the label selector `--secret-label-selector` of the Authorino instance. The default values of the label selector for Kubernetes `Secret`s representing Authorino API keys is `authorino.kuadrant.io/managed-by=authorino`.
 
 ## The "Auth Pipeline" (_aka:_ enforcing protection in request-time)
 
@@ -349,16 +349,16 @@ 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.
 
-Authorino's custom controllers filter the `AuthConfig`-related events to be reconciled using [Kubernetes label selectors](https://pkg.go.dev/k8s.io/apimachinery/pkg/labels#Parse), defined for the Authorino instance via `AUTH_CONFIG_LABEL_SELECTOR` environment variable. By default, `AUTH_CONFIG_LABEL_SELECTOR` is empty, meaning all `AuthConfig`s in the space are watched; this variable can be set to any value parseable as a valid label selector, causing Authorino to then watch only events of `AuthConfig`s whose `metadata.labels` match the selector.
+Authorino's custom controllers filter the `AuthConfig`-related events to be reconciled using [Kubernetes label selectors](https://pkg.go.dev/k8s.io/apimachinery/pkg/labels#Parse), defined for the Authorino instance via `--auth-config-label-selector` command-line flag. By default, `--auth-config-label-selector` is empty, meaning all `AuthConfig`s in the space are watched; this variable can be set to any value parseable as a valid label selector, causing Authorino to then watch only events of `AuthConfig`s whose `metadata.labels` match the selector.
 
 The following are all valid examples of `AuthConfig` label selector filters:
 
 ```
-AUTH_CONFIG_LABEL_SELECTOR="authorino.kuadrant.io/managed-by=authorino"
-AUTH_CONFIG_LABEL_SELECTOR="authorino.kuadrant.io/managed-by=authorino,other-label=other-value"
-AUTH_CONFIG_LABEL_SELECTOR="authorino.kuadrant.io/managed-by in (authorino,kuadrant)"
-AUTH_CONFIG_LABEL_SELECTOR="authorino.kuadrant.io/managed-by!=authorino-v0.4"
-AUTH_CONFIG_LABEL_SELECTOR="!disabled"
+--auth-config-label-selector="authorino.kuadrant.io/managed-by=authorino"
+--auth-config-label-selector="authorino.kuadrant.io/managed-by=authorino,other-label=other-value"
+--auth-config-label-selector="authorino.kuadrant.io/managed-by in (authorino,kuadrant)"
+--auth-config-label-selector="authorino.kuadrant.io/managed-by!=authorino-v0.4"
+--auth-config-label-selector="!disabled"
 ```
 
 ## RBAC
@@ -379,4 +379,4 @@ The table below describes the roles and role bindings defined by the Authorino s
 
 ## Observability
 
-Please refer to the respective user guides for info about [Metrics & Observability](./user-guides/metrics.md) and [Logging & Tracing](./user-guides/logging.md).
+Please refer to the [Observability](./user-guides/observability.md) user guide for info on Prometheus metrics exported by Authorino, readiness probe, logging, tracing, etc.

docs/contributing.md

@@ -244,7 +244,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/logging.md) architecture and policy regarding log levels, log modes, tracing IDs, etc.
+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.
 

docs/features.md

@@ -118,7 +118,7 @@ API key secrets must be created in the same namespace of the `AuthConfig` (defau
 
 API key secrets must be labeled with the labels that match the selectors specified in `spec.identity.apiKey.selector` in the `AuthConfig`.
 
-Whenever an `AuthConfig` is indexed, Authorino will also index all matching API key secrets. In order for Authorino to also watch events related to API key secrets individually (e.g. new `Secret` created, updates, deletion/revocation), `Secret`s must also include a label that matches Authorino's bootstrap configuration `SECRET_LABEL_SELECTOR` (default: `authorino.kuadrant.io/managed-by=authorino`). This label may or may not be present to `spec.identity.apiKey.selector` in the `AuthConfig` without implications for the caching of the API keys when triggered by the reconciliation of the `AuthConfig`; however, if not present, individual changes related to the API key secret (i.e. without touching the `AuthConfig`) will be ignored by the reconciler.
+Whenever an `AuthConfig` is indexed, Authorino will also index all matching API key secrets. In order for Authorino to also watch events related to API key secrets individually (e.g. new `Secret` created, updates, deletion/revocation), `Secret`s must also include a label that matches Authorino's bootstrap configuration `--secret-label-selector` (default: `authorino.kuadrant.io/managed-by=authorino`). This label may or may not be present to `spec.identity.apiKey.selector` in the `AuthConfig` without implications for the caching of the API keys when triggered by the reconciliation of the `AuthConfig`; however, if not present, individual changes related to the API key secret (i.e. without touching the `AuthConfig`) will be ignored by the reconciler.
 
 **Example.** For the following `AuthConfig`:
 
@@ -946,7 +946,7 @@ As for the 'complex-policy' authorization policy, the cache key is a string comp
 
 **Notes on evaluator caching**
 
-_Capacity_ - By default, each cache namespace is limited to 1 mb. Entries will be evicted following First-In-First-Out (FIFO) policy to release space. The individual capacity of cache namespaces is set at the level of the Authorino instance (via `EVALUATOR_CACHE_SIZE` environment variable or `spec.evaluatorCacheSize` field of the `Authorino` CR).
+_Capacity_ - By default, each cache namespace is limited to 1 mb. Entries will be evicted following First-In-First-Out (FIFO) policy to release space. The individual capacity of cache namespaces is set at the level of the Authorino instance (via `--evaluator-cache-size` command-line flag or `spec.evaluatorCacheSize` field of the `Authorino` CR).
 
 _Usage_ - Avoid caching objects whose evaluation is considered to be relatively cheap. Examples of operations associated to Authorino auth features that are usually NOT worth caching: validation of JSON Web Tokens (JWT), Kubernetes TokenReviews and SubjectAccessReviews, API key validation, simple JSON pattern-matching authorization rules, simple OPA policies. Examples of operations where caching may be desired: OAuth2 token introspection, fetching of metadata from external sources (via HTTP request), complex OPA policies.
 
@@ -993,6 +993,6 @@ The same pattern works for other types of evaluators. Find below the list of all
 | `response.json`            | RESPONSE_JSON                   |
 | `response.wristband`       | RESPONSE_WRISTBAND              |
 
-Metrics at the level of the evaluators can also be enforced to an entire Authorino instance, by setting the <code>DEEP_METRICS_ENABLED=true</code> environment variable. In this case, regardless of the value of the field `spec.(identity|metadata|authorization|response).metrics` in the AuthConfigs, individual metrics for all evaluators of all AuthConfigs will be exported.
+Metrics at the level of the evaluators can also be enforced to an entire Authorino instance, by setting the <code>--deep-metrics-enabled</code> command-line flag. In this case, regardless of the value of the field `spec.(identity|metadata|authorization|response).metrics` in the AuthConfigs, individual metrics for all evaluators of all AuthConfigs will be exported.
 
-For more information about observability metrics in Authorino, see the user guide [Observability](./user-guides/metrics.md).
+For more information about metrics exported by Authorino, see [Observability](./user-guides/observability.md#metrics).

docs/user-guides.md

@@ -81,11 +81,5 @@ Have multiple instances of Authorino running in the same space (Kubernetes names
 - **[Caching](./user-guides/caching.md)**<br/>
 Cache auth objects resolved at runtime for any configuration bit of an AuthConfig, for easy access in subsequent requests whenever an arbitrary cache key repeats, until the cache entry expires.
 
-- **[Observability](./user-guides/metrics.md)**<br/>
-Prometheus metrics exported by Authorino.
-
-- **[Logging](./user-guides/logging.md)**<br/>
-Parse Authorino's structured JSON log messages; activate debug log level and get more user-friendly outputs in dev environment.
-
-- **[Tracing](./user-guides/logging.md#3-tracing-id)**<br/>
-Trace authorization requests deep across the stack.
+- **[Observability](./user-guides/observability.md)**<br/>
+Prometheus metrics exported by Authorino, readiness probe, logging, tracing, etc.