Skip to content

Commit eb14a7c

Browse files
camilamacedo86camilamacedo86
committed
(doc): Add a doc as a guidance to help users know how to consume the metrics and integrate it with other solutions
1 parent 099a6cf commit eb14a7c

File tree

1 file changed

+294
-0
lines changed

1 file changed

+294
-0
lines changed

‎docs/draft/howto/consuming-metrics.md

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
# Consuming Metrics
2+
3+
!!! warning
4+
Metrics endpoints and ports are available as an alpha release and are subject to change in future versions.
5+
The following procedure is provided as an example for testing purposes. Do not depend on alpha features in production clusters.
6+
7+
Operator-Controller and CatalogD are configured to export metrics by default. The metrics are exposed on the `/metrics` endpoint of the respective services.
8+
9+
The metrics are secured by [RBAC policies][rbac-k8s-docs], requiring appropriate permissions for access.
10+
By default, they are exposed over HTTPS, necessitating valid certificates for integration with services like Prometheus.
11+
The following sections cover enabling metrics, validating access, and integrating with the [Prometheus Operator][prometheus-operator].
12+
13+
Below, you will learn how to enable the metrics, validate access, and integrate with [Prometheus Operator][prometheus-operator].
14+
15+
---
16+
17+
## Operator-Controller Metrics
18+
19+
### Step 1: Enable Access
20+
21+
To enable access to the Operator-Controller metrics, create a `ClusterRoleBinding` to
22+
allow the Operator-Controller service account to access the metrics.
23+
24+
```shell
25+
kubectl create clusterrolebinding operator-controller-metrics-binding \
26+
--clusterrole=operator-controller-metrics-reader \
27+
--serviceaccount=olmv1-system:operator-controller-controller-manager
28+
```
29+
30+
### Step 2: Validate Access Manually
31+
32+
#### Create a Token and Extract Certificates
33+
34+
Generate a token for the service account and extract the required certificates:
35+
36+
```shell
37+
TOKEN=$(kubectl create token operator-controller-controller-manager -n olmv1-system)
38+
echo $TOKEN
39+
```
40+
41+
#### Deploy a Pod to Consume Metrics
42+
43+
Ensure that the Pod is deployed in a namespace labeled to enforce restricted permissions. Apply the following:
44+
45+
```shell
46+
kubectl apply -f - <<EOF
47+
apiVersion: v1
48+
kind: Pod
49+
metadata:
50+
name: curl-metrics
51+
namespace: olmv1-system
52+
spec:
53+
serviceAccountName: operator-controller-controller-manager
54+
containers:
55+
- name: curl
56+
image: curlimages/curl:latest
57+
command:
58+
- sh
59+
- -c
60+
- sleep 3600
61+
securityContext:
62+
runAsNonRoot: true
63+
readOnlyRootFilesystem: true
64+
runAsUser: 1000
65+
runAsGroup: 1000
66+
allowPrivilegeEscalation: false
67+
capabilities:
68+
drop:
69+
- ALL
70+
volumeMounts:
71+
- mountPath: /tmp/cert
72+
name: olm-cert
73+
readOnly: true
74+
volumes:
75+
- name: olm-cert
76+
secret:
77+
secretName: olmv1-cert
78+
securityContext:
79+
runAsNonRoot: true
80+
restartPolicy: Never
81+
EOF
82+
```
83+
84+
#### Access the Pod and Test Metrics
85+
86+
Access the pod:
87+
88+
```shell
89+
kubectl exec -it curl-metrics -n olmv1-system -- sh
90+
```
91+
92+
From the shell use the `TOKEN` value obtained above to check the metrics:
93+
94+
```shell
95+
curl -v -k -H "Authorization: Bearer <TOKEN>" \
96+
https://operator-controller-service.olmv1-system.svc.cluster.local:8443/metrics
97+
```
98+
99+
Validate using certificates and token:
100+
101+
```shell
102+
curl -v --cacert /tmp/cert/ca.crt --cert /tmp/cert/tls.crt --key /tmp/cert/tls.key \
103+
-H "Authorization: Bearer <TOKEN>" \
104+
https://operator-controller-service.olmv1-system.svc.cluster.local:8443/metrics
105+
```
106+
107+
---
108+
109+
## CatalogD Metrics
110+
111+
### Step 1: Enable Access
112+
113+
To enable access to the CatalogD metrics, create a `ClusterRoleBinding` for the CatalogD service account:
114+
115+
```shell
116+
kubectl create clusterrolebinding catalogd-metrics-binding \
117+
--clusterrole=catalogd-metrics-reader \
118+
--serviceaccount=olmv1-system:catalogd-controller-manager
119+
```
120+
121+
### Step 2: Validate Access Manually
122+
123+
#### Create a Token and Extract Certificates
124+
125+
Generate a token and get the required certificates:
126+
127+
```shell
128+
TOKEN=$(kubectl create token catalogd-controller-manager -n olmv1-system)
129+
echo $TOKEN
130+
```
131+
132+
#### Deploy a Pod to Consume Metrics
133+
134+
From the shell use the `TOKEN` value obtained above to check the metrics:
135+
136+
```shell
137+
OLM_SECRET=$(kubectl get secret -n olmv1-system -o jsonpath="{.items[*].metadata.name}" | tr ' ' '\n' | grep '^catalogd-service-cert')
138+
echo $OLM_SECRET
139+
```
140+
141+
```shell
142+
kubectl apply -f - <<EOF
143+
apiVersion: v1
144+
kind: Pod
145+
metadata:
146+
name: curl-metrics-catalogd
147+
namespace: olmv1-system
148+
spec:
149+
serviceAccountName: catalogd-controller-manager
150+
containers:
151+
- name: curl
152+
image: curlimages/curl:latest
153+
command:
154+
- sh
155+
- -c
156+
- sleep 3600
157+
securityContext:
158+
runAsNonRoot: true
159+
readOnlyRootFilesystem: true
160+
runAsUser: 1000
161+
runAsGroup: 1000
162+
allowPrivilegeEscalation: false
163+
capabilities:
164+
drop:
165+
- ALL
166+
volumeMounts:
167+
- mountPath: /tmp/cert
168+
name: catalogd-cert
169+
readOnly: true
170+
volumes:
171+
- name: catalogd-cert
172+
secret:
173+
secretName: $OLM_SECRET
174+
securityContext:
175+
runAsNonRoot: true
176+
restartPolicy: Never
177+
EOF
178+
```
179+
180+
#### Access the Pod and Test Metrics
181+
182+
Access the pod:
183+
184+
```shell
185+
kubectl exec -it curl-metrics-catalogd -n olmv1-system -- sh
186+
```
187+
188+
From the shell use the `TOKEN` value obtained above to check the metrics:
189+
190+
```shell
191+
curl -v -k -H "Authorization: Bearer <TOKEN>" \
192+
https://catalogd-service.olmv1-system.svc.cluster.local:7443/metrics
193+
```
194+
195+
Validate using certificates and token:
196+
197+
```shell
198+
curl -v --cacert /tmp/cert/ca.crt --cert /tmp/cert/tls.crt --key /tmp/cert/tls.key \
199+
-H "Authorization: Bearer <TOKEN>" \
200+
https://catalogd-service.olmv1-system.svc.cluster.local:7443/metrics
201+
```
202+
203+
---
204+
205+
## Enabling Integration with Prometheus
206+
207+
If using [Prometheus Operator][prometheus-operator], create a `ServiceMonitor` to scrape metrics:
208+
209+
!!! note
210+
The following manifests are provided as examples. You may need to configure certain settings, such as `serviceMonitorSelector`,
211+
to ensure that metrics are properly scraped. This will depend on how Prometheus is configured and, for example, the namespace
212+
where the `ServiceMonitor` is applied.
213+
214+
### For Operator-Controller
215+
216+
```shell
217+
kubectl apply -f - <<EOF
218+
apiVersion: monitoring.coreos.com/v1
219+
kind: ServiceMonitor
220+
metadata:
221+
labels:
222+
control-plane: operator-controller-controller-manager
223+
name: controller-manager-metrics-monitor
224+
namespace: olmv1-system
225+
spec:
226+
endpoints:
227+
- path: /metrics
228+
port: https
229+
scheme: https
230+
bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
231+
tlsConfig:
232+
insecureSkipVerify: false
233+
serverName: operator-controller-service.olmv1-system.svc
234+
ca:
235+
secret:
236+
name: olmv1-cert
237+
key: ca.crt
238+
cert:
239+
secret:
240+
name: olmv1-cert
241+
key: tls.crt
242+
keySecret:
243+
name: olmv1-cert
244+
key: tls.key
245+
selector:
246+
matchLabels:
247+
control-plane: operator-controller-controller-manager
248+
EOF
249+
```
250+
251+
### For CatalogD
252+
253+
254+
```shell
255+
OLM_SECRET=$(kubectl get secret -n olmv1-system -o jsonpath="{.items[?(@.metadata.name | startswith('catalogd-service-cert'))].metadata.name}")
256+
```
257+
258+
```shell
259+
kubectl apply -f - <<EOF
260+
apiVersion: monitoring.coreos.com/v1
261+
kind: ServiceMonitor
262+
metadata:
263+
labels:
264+
control-plane: catalogd-controller-manager
265+
name: catalogd-metrics-monitor
266+
namespace: olmv1-system
267+
spec:
268+
endpoints:
269+
- path: /metrics
270+
port: https
271+
scheme: https
272+
bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
273+
tlsConfig:
274+
serverName: catalogd-service.olmv1-system.svc
275+
insecureSkipVerify: false
276+
ca:
277+
secret:
278+
name: $OLM_SECRET
279+
key: ca.crt
280+
cert:
281+
secret:
282+
name: $OLM_SECRET
283+
key: tls.crt
284+
keySecret:
285+
name: $OLM_SECRET
286+
key: tls.key
287+
selector:
288+
matchLabels:
289+
control-plane: catalogd-controller-manager
290+
EOF
291+
```
292+
293+
[prometheus-operator]: https://github.com/prometheus-operator/kube-prometheus
294+
[rbac-k8s-docs]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/

0 commit comments

Comments
 (0)