fixup! fixup! fixup! docs: add kube-rbac-proxy

content/Projects/Observability/kube-rbac-proxy.md

@@ -1,16 +1,20 @@
 # kube-rbac-proxy
 
-`kube-rbac-proxy`, as the name suggests, is a proxy that sits in front of a workload and performs authentication and authorization on its behalf, to make sure the requests passing through are the ones that it expects to.
+`kube-rbac-proxy`, as the name suggests, is an HTTP proxy that sits in front of a workload and performs authentication and authorization of incoming requests using the `TokenReview` and `SubjectAccessReview` resources of the Kubernetes API.
 
 ## Workflow
 
-The purpose of `kube-rbac-proxy` is to distinguish between calls made by same or different user(s) (or service account(s)) to endpoint(s) and protect them from unauthorized resource access based on their trusted identity (e.g. tokens, TLS certificates, etc.) or the RBACs they hold, respectively.
+The purpose of `kube-rbac-proxy` is to distinguish between calls made by same or different user(s) (or service account(s)) to endpoint(s) and protect them from unauthorized resource access based on their trusted identity (e.g. tokens, TLS certificates, etc.) or the RBACs they hold, respectively. Once the request is authenticated and/or authorized, the proxy forwards the response from the server to the client unmodified.
 
-- [**Authentication**](https://github.com/brancz/kube-rbac-proxy/blob/74181c75b8b6fbcde7eff1ca5fae353faac5cfae/pkg/authn/config.go#L33-L39): Both [OIDC JWT](https://github.com/brancz/kube-rbac-proxy/blob/52e49fbdb75e009db4d02e3986e51fdba0526378/pkg/authn/oidc.go#L45-L63) and [delegated (header-based)](https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/authenticatorfactory/delegating.go#L102-L112) authentication rely on Bearer tokens to authenticate the requests. The tokens are validated against the OIDC provider or the Kubernetes API server, respectively. Monitoring components use [mTLS](#downstream-usage) for client-server authentication, which provides a secure way to establish trust based on each other's digital certificates. The proxy can also possibly be configured to [skip the authentication step](https://github.com/brancz/kube-rbac-proxy/blob/4c4a18fa7dd5d8069c0aa3a55028e06631621a52/pkg/authn/delegating.go#L53) altogether, in which case it will not validate the tokens and will assume that the requests are authenticated, which is not recommended. This token represents the identity of the user or service account that is making the request. A [`TokenReview` request is created](https://github.com/kubernetes/apiserver/blob/21bbcb57c672531fe8c431e1035405f9a4b061de/plugin/pkg/authenticator/token/webhook/webhook.go#L51-L53), and includes the bearer token that the client provided, which is then sent to the API server. The API server verifies the authenticity of the token and responds with the details of the authenticated party, if the operation was successful.
+### [**Authentication**](https://github.com/brancz/kube-rbac-proxy/blob/74181c75b8b6fbcde7eff1ca5fae353faac5cfae/pkg/authn/config.go#L33-L39)
 
-- [**Authorization**](https://github.com/brancz/kube-rbac-proxy/blob/1c7f88b5e951d25a493a175e93515068f5c77f3b/pkg/authz/auth.go#L31C1-L37): Once authentication is done, `kube-rbac-proxy` must then decide whether to allow the user's request to go through or not. A [`SubjectAccessReview` request is created](https://github.com/kubernetes/apiserver/blob/21bbcb57c672531fe8c431e1035405f9a4b061de/plugin/pkg/authorizer/webhook/webhook.go#L57-L59) for the API server, which allows for the review of the subject's access to a particular resource. Essentially, it checks whether the authenticated user or service account or has sufficient permissions to perform the desired action on the requested resource, based on the RBAC permissions granted to it. If so, the request is forwarded to the endpoint, otherwise it is rejected. Its worth mentioning that the HTTP verbs are internally mapped to their [corresponding RBAC verbs](https://github.com/brancz/kube-rbac-proxy/blob/ccd5bc7fec36f9db0747033c2d698cc75a0e314c/pkg/proxy/proxy.go#L49-L60). Note that static authorization (as described in the [downstream usage](#downstream-usage) section) without SubjectAccessReview is also possible.
+Both [OIDC JWT](https://github.com/brancz/kube-rbac-proxy/blob/52e49fbdb75e009db4d02e3986e51fdba0526378/pkg/authn/oidc.go#L45-L63) and [delegated (header-based)](https://github.com/kubernetes/apiserver/blob/8ad2e288d62d02276033ea11ee1efd94bb627836/pkg/authentication/authenticatorfactory/delegating.go#L102-L112) authentication rely on Bearer tokens to authenticate the requests. The tokens are validated against the OIDC provider or the Kubernetes API server, respectively. Monitoring components use [mTLS](#downstream-usage) for client-server authentication, which provides a secure way to establish trust based on each other's digital certificates. This token represents the identity of the user or service account that is making the request. A [`TokenReview` request is created](https://github.com/kubernetes/apiserver/blob/21bbcb57c672531fe8c431e1035405f9a4b061de/plugin/pkg/authenticator/token/webhook/webhook.go#L51-L53), and includes the bearer token that the client provided, which is then sent to the API server. The API server verifies the authenticity of the token and responds with the details of the authenticated party, if the operation was successful.
 
-- **Request/response forwarding and error handling**: Once the request is authenticated and authorized, it is forwarded to the endpoint. The response from the endpoint is then forwarded back to the client. If the request fails at any point, the proxy returns an error response to the client. In the case of a failed authentication, an [HTTP `401 Unauthorized` status code](https://github.com/brancz/kube-rbac-proxy/blob/9efde2a776fd516cfa082cc5f2c35c7f9e0e2689/pkg/filters/auth_test.go#L290) is returned (note the distinction between *authentication* and *unauthorized* here). If the authorization step fails, i.e., the client doesn't have the required permissions to access the requested resource, `kube-rbac-proxy` returns an [HTTP `403 Forbidden` status code](https://github.com/brancz/kube-rbac-proxy/blob/9efde2a776fd516cfa082cc5f2c35c7f9e0e2689/pkg/filters/auth_test.go#L300) to the client and does not forward the request to the endpoint.
+### [**Authorization**](https://github.com/brancz/kube-rbac-proxy/blob/1c7f88b5e951d25a493a175e93515068f5c77f3b/pkg/authz/auth.go#L31C1-L37)
+
+Once authentication is done, `kube-rbac-proxy` must then decide whether to allow the user's request to go through or not. A [`SubjectAccessReview` request is created](https://github.com/kubernetes/apiserver/blob/21bbcb57c672531fe8c431e1035405f9a4b061de/plugin/pkg/authorizer/webhook/webhook.go#L57-L59) for the API server, which allows for the review of the subject's access to a particular resource. Essentially, it checks whether the authenticated user or service account has sufficient permissions to perform the desired action on the requested resource, based on the RBAC permissions granted to it. If so, the request is forwarded to the endpoint, otherwise it is rejected. It is worth mentioning that the HTTP verbs are internally mapped to their [corresponding RBAC verbs](https://github.com/brancz/kube-rbac-proxy/blob/ccd5bc7fec36f9db0747033c2d698cc75a0e314c/pkg/proxy/proxy.go#L49-L60). Note that static authorization (as described in the [downstream usage](#downstream-usage) section) without SubjectAccessReview is also possible.
+
+Once the request is authenticated and authorized, it is forwarded to the endpoint. The response from the endpoint is then forwarded back to the client. If the request fails at any point, the proxy returns an error response to the client. In the case of a failed authentication, an [HTTP `401 Unauthorized` status code](https://github.com/brancz/kube-rbac-proxy/blob/9efde2a776fd516cfa082cc5f2c35c7f9e0e2689/pkg/filters/auth_test.go#L290) is returned (note the distinction between *authentication* and *unauthorized* here). If the authorization step fails, i.e., the client doesn't have the required permissions to access the requested resource, `kube-rbac-proxy` returns an [HTTP `403 Forbidden` status code](https://github.com/brancz/kube-rbac-proxy/blob/9efde2a776fd516cfa082cc5f2c35c7f9e0e2689/pkg/filters/auth_test.go#L300) to the client and does not forward the request to the endpoint.
 
 ## Downstream usage
 
@@ -90,10 +94,12 @@ The following components use the same method in their `kube-rbac-proxy` configur
 * `kube-rbac-proxy-metrics` (`prometheus-user-workload`)
 * `telemeter-client-kube-rbac-proxy-config` (`telemeter-client`)
 * `thanos-querier-kube-rbac-proxy-metrics` (`thanos-querier`)
-*  `thanos-ruler-kube-rbac-proxy-metrics` (`thanos-ruler`)
+* `thanos-ruler-kube-rbac-proxy-metrics` (`thanos-ruler`)
 
 For more details, refer to the `kube-rbac-proxy`'s [static authorization](https://github.com/brancz/kube-rbac-proxy/blob/4a44b610cd12c4cfe076a2b306283d0598c1bb7a/examples/static-auth/README.md#L169) example.
 
+For more information on collecting metrics in such cases, refer to the [metrics collection](https://rhobs-handbook.netlify.app/products/openshiftmonitoring/collecting_metrics.md/#kube-rbac-proxy-sidecar) section of the handbook.
+
 On the other hand, the example below depicts restricted access to a resource, i.e., `monitoring.coreos.com/prometheusrules` in the `openshift-monitoring` namespace.
 
 ```yaml
@@ -109,7 +115,7 @@ stringData:
     "authorization":
       "resourceAttributes":
         "apiGroup": "monitoring.coreos.com"
-        "namespace": "openshift-monitoring"
+        "namespace": "{{ .Value }}"
         "resource": "prometheusrules"
       "rewrites":
         "byQueryParameter":
@@ -132,5 +138,5 @@ Details on configuring `kube-rbac-proxy` under different scenarios can be found
 ## Debugging
 
 In addition to enabling debug logs or compiling a custom binary with debugging capabilities (`-gcflags="all=-N -l"`), users can:
-* enable a higher verbose level using `-v=12` (or higher) (requires CMO to be put into the unmanaged state), or,
+* [put the CMO into unmanaged state](https://github.com/openshift/cluster-monitoring-operator/blob/e1803adfa64f9ef424cd6e10790791adbed25eb4/hack/local-cmo.sh#L68-L103) to enable a higher verbose level using `-v=12` (or higher), or,
 * grep [the audit logs](https://docs.openshift.com/container-platform/4.13/security/audit-log-view.html) for more information about requests or responses concerning `kube-rbac-proxy`.