Skip to content

Commit 6f2acec

Browse files
camilamacedo86camilamacedo86
authored
(doc): Add a doc as a guidance to help users know how to consume the metrics and integrate it with other solutions (#1524)
1 parent a38da78 commit 6f2acec

File tree

1 file changed

+280
-0
lines changed

1 file changed

+280
-0
lines changed

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

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

0 commit comments

Comments
 (0)