diff --git a/docs/draft/howto/consuming-metrics.md b/docs/draft/howto/consuming-metrics.md new file mode 100644 index 000000000..d896d8081 --- /dev/null +++ b/docs/draft/howto/consuming-metrics.md @@ -0,0 +1,280 @@ +# Consuming Metrics + +!!! warning +Metrics endpoints and ports are available as an alpha release and are subject to change in future versions. +The following procedure is provided as an example for testing purposes. Do not depend on alpha features in production clusters. + +In OLM v1, you can use the provided metrics with tools such as the [Prometheus Operator][prometheus-operator]. By default, Operator Controller and catalogd export metrics to the `/metrics` endpoint of each service. + +You must grant the necessary permissions to access the metrics by using [role-based access control (RBAC) polices][rbac-k8s-docs]. +Because the metrics are exposed over HTTPS by default, you need valid certificates to use the metrics with services such as Prometheus. +The following sections cover enabling metrics, validating access, and provide a reference of a `ServiceMonitor` +to illustrate how you might integrate the metrics with the [Prometheus Operator][prometheus-operator] or other third-part solutions. + +--- + +## Enabling metrics for the Operator Controller + +1. To enable access to the Operator controller metrics, create a `ClusterRoleBinding` resource by running the following command: + +```shell +kubectl create clusterrolebinding operator-controller-metrics-binding \ + --clusterrole=operator-controller-metrics-reader \ + --serviceaccount=olmv1-system:operator-controller-controller-manager +``` + +### Validating Access Manually + +1. 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 +``` + +2. Apply the following YAML to deploy a pod in a namespace to consume the metrics: + +```shell +kubectl apply -f - <" \ +https://operator-controller-service.olmv1-system.svc.cluster.local:8443/metrics +``` + +5. Run the following command to validate the certificates and token: + +```shell +curl -v --cacert /tmp/cert/ca.crt --cert /tmp/cert/tls.crt --key /tmp/cert/tls.key \ +-H "Authorization: Bearer " \ +https://operator-controller-service.olmv1-system.svc.cluster.local:8443/metrics +``` + +--- + +## Enabling metrics for the Operator CatalogD + +1. 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 +``` + +### Validating Access Manually + +1. Generate a token and get the required certificates: + +```shell +TOKEN=$(kubectl create token catalogd-controller-manager -n olmv1-system) +echo $TOKEN +``` + +2. Run the following command to obtain the name of the secret which store the certificates: + +```shell +OLM_SECRET=$(kubectl get secret -n olmv1-system -o jsonpath="{.items[*].metadata.name}" | tr ' ' '\n' | grep '^catalogd-service-cert') +echo $OLM_SECRET +``` + +3. Apply the following YAML to deploy a pod in a namespace to consume the metrics: + +```shell +kubectl apply -f - <" \ +https://catalogd-service.olmv1-system.svc.cluster.local:7443/metrics +``` + +6. Run the following command to validate the certificates and token: +```shell +curl -v --cacert /tmp/cert/ca.crt --cert /tmp/cert/tls.crt --key /tmp/cert/tls.key \ +-H "Authorization: Bearer " \ +https://catalogd-service.olmv1-system.svc.cluster.local:7443/metrics +``` + +--- + +## Integrating the metrics endpoints with third-party solutions + +In many cases, you must provide the certificates and the `ServiceName` resources to integrate metrics endpoints with third-party solutions. +The following example illustrates how to create a `ServiceMonitor` resource to scrape metrics for the [Prometheus Operator][prometheus-operator] in OLM v1. + +!!! note +The following manifests are provided as a reference mainly to let you know how to configure the certificates. +The following procedure is not a complete guide to configuring the Prometheus Operator or how to integrate within. +To integrate with [Prometheus Operator][prometheus-operator] you might need to adjust your +configuration settings, such as the `serviceMonitorSelector` resource, and the namespace +where you apply the `ServiceMonitor` resource to ensure that metrics are properly scraped. + +**Example for Operator-Controller** + +```shell +kubectl apply -f - <