WIP: 📖 (doc): Add a doc as a guidance to help users know how to consume the metrics and integrate it with other solutions

docs/helpers/consuming-metrics.md

@@ -0,0 +1,281 @@
+# Consuming Metrics
+
+> The information provided here is intended as general guidance and does not constitute a guaranteed or officially supported solution. 
+> Please note that integration with the Prometheus Operator or other third-party tools may have limitations and might not be fully supported.
+
+Operator-Controller and CatalogD are configured to export metrics by default. The metrics are exposed on the `/metrics` endpoint of the respective services.
+
+The metrics are protected by RBAC policies, and you need to have the appropriate permissions to access them. By default, the metrics are exposed over HTTPS, and you need to have the appropriate certificates to access them via other services such as Prometheus.
+
+Below, you will learn how to enable the metrics, validate access, and integrate with [Prometheus Operator][prometheus-operator].
+
+---
+
+## Operator-Controller Metrics
+
+### Step 1: Enable Access
+
+To enable access to the Operator-Controller metrics, create a `ClusterRoleBinding` to allow the Operator-Controller service account to access the metrics.
+
+```shell
+kubectl create clusterrolebinding operator-controller-metrics-binding \
+   --clusterrole=operator-controller-metrics-reader \
+   --serviceaccount=olmv1-system:operator-controller-controller-manager
+```
+
+### Step 2: Validate Access Manually
+
+#### Create a Token and Extract Certificates
+
+Generate a token for the service account and extract the required certificates:
+
+```shell
+TOKEN=$(kubectl create token operator-controller-controller-manager -n olmv1-system)
+echo $TOKEN
+```
+
+#### Deploy a Pod to Consume Metrics
+
+Ensure that the Pod is deployed in a namespace labeled to enforce restricted permissions. Apply the following:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: Pod
+metadata:
+  name: curl-metrics
+  namespace: olmv1-system
+spec:
+  serviceAccountName: operator-controller-controller-manager
+  containers:
+  - name: curl
+    image: curlimages/curl:latest
+    command:
+    - sh
+    - -c
+    - sleep 3600
+    securityContext:
+      runAsNonRoot: true
+      readOnlyRootFilesystem: true
+      runAsUser: 1000
+      runAsGroup: 1000
+      allowPrivilegeEscalation: false
+      capabilities:
+        drop:
+        - ALL
+    volumeMounts:
+    - mountPath: /tmp/cert
+      name: olm-cert
+      readOnly: true
+  volumes:
+  - name: olm-cert
+    secret:
+      secretName: olmv1-cert
+  securityContext:
+    runAsNonRoot: true
+  restartPolicy: Never
+EOF
+```
+
+#### Access the Pod and Test Metrics
+
+Access the pod:
+
+```shell
+kubectl exec -it curl-metrics -n olmv1-system -- sh
+```
+
+From the shell use the `TOKEN` value obtained above to check the metrics:
+
+```shell
+curl -v -k -H "Authorization: Bearer <TOKEN>" \
+https://operator-controller-controller-manager-metrics-service.olmv1-system.svc.cluster.local:8443/metrics
+```
+
+Validate using certificates and token:
+
+```shell
+curl -v --cacert /tmp/cert/ca.crt --cert /tmp/cert/tls.crt --key /tmp/cert/tls.key \
+-H "Authorization: Bearer <TOKEN>" \
+https://operator-controller-controller-manager-metrics-service.olmv1-system.svc.cluster.local:8443/metrics
+```
+
+---
+
+## CatalogD Metrics
+
+### Step 1: Enable Access
+
+To enable access to the CatalogD metrics, create a `ClusterRoleBinding` for the CatalogD service account:
+
+```shell
+kubectl create clusterrolebinding catalogd-metrics-binding \
+   --clusterrole=catalogd-metrics-reader \
+   --serviceaccount=olmv1-system:catalogd-controller-manager
+```
+
+### Step 2: Validate Access Manually
+
+#### Create a Token and Extract Certificates
+
+Generate a token and get the required certificates:
+
+```shell
+TOKEN=$(kubectl create token catalogd-controller-manager -n olmv1-system)
+echo $TOKEN
+```
+
+#### Deploy a Pod to Consume Metrics
+
+From the shell use the `TOKEN` value obtained above to check the metrics:
+
+```shell
+OLM_SECRET=$(kubectl get secret -n olmv1-system -o jsonpath="{.items[?(@.metadata.name | startswith('catalogd-service-cert'))].metadata.name}")
+```
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: Pod
+metadata:
+  name: curl-metrics-catalogd
+  namespace: olmv1-system
+spec:
+  serviceAccountName: catalogd-controller-manager
+  containers:
+  - name: curl
+    image: curlimages/curl:latest
+    command:
+    - sh
+    - -c
+    - sleep 3600
+    securityContext:
+      runAsNonRoot: true
+      readOnlyRootFilesystem: true
+      runAsUser: 1000
+      runAsGroup: 1000
+      allowPrivilegeEscalation: false
+      capabilities:
+        drop:
+        - ALL
+    volumeMounts:
+    - mountPath: /tmp/cert
+      name: catalogd-cert
+      readOnly: true
+  volumes:
+  - name: catalogd-cert
+    secret:
+      secretName: $OLM_SECRET
+  securityContext:
+    runAsNonRoot: true
+  restartPolicy: Never
+EOF
+```
+
+#### Access the Pod and Test Metrics
+
+Access the pod:
+
+```shell
+kubectl exec -it curl-metrics-catalogd -n olmv1-system -- sh
+```
+
+From the shell use the `TOKEN` value obtained above to check the metrics:
+
+```shell
+curl -v -k -H "Authorization: Bearer <TOKEN>" \
+https://catalogd-service.olmv1-system.svc.cluster.local:7443/metrics
+```
+
+Validate using certificates and token:
+
+```shell
+curl -v --cacert /tmp/cert/ca.crt --cert /tmp/cert/tls.crt --key /tmp/cert/tls.key \
+-H "Authorization: Bearer <TOKEN>" \
+https://catalogd-service.olmv1-system.svc.cluster.local:7443/metrics
+```
+
+---
+
+## Enabling Integration with Prometheus
+
+If using [Prometheus Operator][prometheus-operator], create a `ServiceMonitor` to scrape metrics:
+
+### For Operator-Controller
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  labels:
+    control-plane: operator-controller-controller-manager
+  name: controller-manager-metrics-monitor
+  namespace: system
+spec:
+  endpoints:
+    - path: /metrics
+      port: https
+      scheme: https
+      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
+      tlsConfig:
+        insecureSkipVerify: false
+        ca:
+          secret:
+            name: olmv1-cert
+            key: ca.crt
+        cert:
+          secret:
+            name: olmv1-cert
+            key: tls.crt
+        keySecret:
+          name: olmv1-cert
+          key: tls.key
+  selector:
+    matchLabels:
+      control-plane: operator-controller-controller-manager
+EOF
+```
+
+### For CatalogD
+
+
+```shell
+OLM_SECRET=$(kubectl get secret -n olmv1-system -o jsonpath="{.items[?(@.metadata.name | startswith('catalogd-service-cert'))].metadata.name}")
+```
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  labels:
+    control-plane: catalogd-controller-manager
+  name: catalogd-metrics-monitor
+  namespace: system
+spec:
+  endpoints:
+    - path: /metrics
+      port: https
+      scheme: https
+      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
+      tlsConfig:
+        insecureSkipVerify: false
+        ca:
+          secret:
+            name: $OLM_SECRET
+            key: ca.crt
+        cert:
+          secret:
+            name: $OLM_SECRET
+            key: tls.crt
+        keySecret:
+          name: $OLM_SECRET
+          key: tls.key
+  selector:
+    matchLabels:
+      control-plane: catalogd-controller-manager
+EOF
+```
+
+[prometheus-operator]: https://github.com/prometheus-operator/prometheus-operator