Skip to content

Commit b98b57b

Browse files
maximilianbraunmaximilianbraun
committed
chore: Readme and kubebuilder
Signed-off-by: Maximilian Braun (SAP) <[email protected]>
1 parent c6b8379 commit b98b57b

File tree

2 files changed

+364
-5
lines changed

2 files changed

+364
-5
lines changed

‎PROJECT‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Code generated by tool. DO NOT EDIT.
2+
# This file is used to track the info used to scaffold your project
3+
# and allow the plugins properly work.
4+
# More info: https://book.kubebuilder.io/reference/project-config.html
5+
domain: cloud.sap
6+
layout:
7+
- go.kubebuilder.io/v4
8+
projectName: co-metrics-operator
9+
repo: github.com/SAP/metrics-operator
10+
resources:
11+
- api:
12+
crdVersion: v1
13+
namespaced: true
14+
controller: true
15+
domain: cloud.sap
16+
group: metrics
17+
kind: Metric
18+
path: github.com/SAP/metrics-operator/api/v1alpha1
19+
version: v1alpha1
20+
- api:
21+
crdVersion: v1
22+
namespaced: true
23+
controller: true
24+
domain: cloud.sap
25+
group: metrics
26+
kind: ManagedMetric
27+
path: github.com/SAP/metrics-operator/api/v1alpha1
28+
version: v1alpha1
29+
- api:
30+
crdVersion: v1
31+
namespaced: true
32+
domain: cloud.sap
33+
group: metrics
34+
kind: RemoteClusterAccess
35+
path: github.com/SAP/metrics-operator/api/v1alpha1
36+
version: v1alpha1
37+
- api:
38+
crdVersion: v1
39+
namespaced: true
40+
controller: true
41+
domain: cloud.sap
42+
group: metrics
43+
kind: SingleMetric
44+
path: github.com/SAP/metrics-operator/api/v1beta1
45+
version: v1beta1
46+
- api:
47+
crdVersion: v1
48+
namespaced: true
49+
controller: true
50+
domain: cloud.sap
51+
group: metrics
52+
kind: CompoundMetric
53+
path: github.com/SAP/metrics-operator/api/v1beta1
54+
version: v1beta1
55+
- api:
56+
crdVersion: v1
57+
namespaced: true
58+
controller: true
59+
domain: cloud.sap
60+
group: metrics
61+
kind: FederatedMetric
62+
path: github.com/SAP/metrics-operator/api/v1beta1
63+
version: v1beta1
64+
- api:
65+
crdVersion: v1
66+
namespaced: true
67+
controller: true
68+
domain: cloud.sap
69+
group: metrics
70+
kind: ClusterAccess
71+
path: github.com/SAP/metrics-operator/api/v1beta1
72+
version: v1beta1
73+
- api:
74+
crdVersion: v1
75+
namespaced: true
76+
domain: cloud.sap
77+
group: metrics
78+
kind: FederatedClusterAccess
79+
path: github.com/SAP/metrics-operator/api/v1beta1
80+
version: v1beta1
81+
- api:
82+
crdVersion: v1
83+
namespaced: true
84+
controller: true
85+
domain: cloud.sap
86+
group: metrics
87+
kind: FederatedManagedMetric
88+
path: github.com/SAP/metrics-operator/api/v1beta1
89+
version: v1beta1
90+
version: "3"

‎README.md‎

Lines changed: 274 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,283 @@
11
[![REUSE status](https://api.reuse.software/badge/github.com/SAP/metrics-operator)](https://api.reuse.software/info/github.com/SAP/metrics-operator)
22

3-
# metrics-operator
3+
# Metrics Operator
44

5-
## About this project
5+
The Metrics Operator is a powerful tool designed to monitor and provide insights into the state, usage, patterns, and trends of distributed systems and their associated components.
66

7-
This project enables insights into the state, usage, patterns and trends of distributed systems with particular focus on the k8s clusters (one or many) and their associated components.
7+
## Table of Contents
88

9-
## Requirements and Setup
9+
- [Key Features](#key-features)
10+
- [Installation](#installation)
11+
- [Usage](#usage)
12+
- [RBAC Configuration](#rbac-configuration)
13+
- [Remote Cluster Access](#remote-cluster-access)
14+
- [Data Sink Integration](#data-sink-integration)
1015

11-
*Insert a short description what is required to get your project running...*
16+
## Key Features
17+
18+
- **Comprehensive Resource Tracking**: Quantifies and catalogs various resource types, providing a holistic view of resource distribution and utilization.
19+
- **Multi-dimensional Analysis**: Examines specific attributes and dimensions of resources, generating nuanced metrics for deeper understanding of system behavior.
20+
- **Comparative Analytics**: Enables side-by-side analysis of different resource configurations, highlighting patterns and potential imbalances in resource allocation.
21+
- **Custom Component Focus**: Tailored to monitor and analyze complex, custom-defined resources across your infrastructure.
22+
- **Predictive Insights**: Aggregates data over time to identify emerging trends, supporting data-driven decision making for future system enhancements.
23+
- **Strategic Decision Support**: Offers data-backed insights to guide product evolution.
24+
- **Customizable Alerting System**: Allows defining alerts based on specific metric thresholds, enabling proactive response to potential issues or significant changes in system state.
25+
26+
## Installation
27+
28+
### Prerequisites
29+
30+
1. Create a namespace for the Metrics Operator.
31+
2. Create a secret containing the credentials for the artifactory (read-only) in the operator's namespace.
32+
3. Create a secret containing the data sink credentials in the operator's namespace.
33+
34+
### Deployment
35+
36+
Deploy the Metrics Operator using the Helm chart:
37+
38+
```bash
39+
helm upgrade --install co-metrics-operator deploy-releases-hyperspace-helm/co-metrics-operator \
40+
--namespace <operator-namespace> \
41+
--create-namespace \
42+
--set imagePullSecrets[0].name=<artifactory-secret-name> \
43+
--version=<version>
44+
```
45+
46+
Replace `<operator-namespace>`, `<artifactory-secret-name>`, and `<version>` with appropriate values.
47+
48+
## Usage
49+
50+
51+
### Single Metric
52+
To create a basic metric, deploy a `SingleMetric` resource in your desired namespace. The Metrics Operator will pick up the resource and start monitoring it, periodically sending data points to the configured data sink.
53+
54+
Example `SingleMetric` resource:
55+
56+
```yaml
57+
apiVersion: metrics.cloud.sap/v1beta1
58+
kind: SingleMetric
59+
metadata:
60+
name: single-pod
61+
spec:
62+
name: single-metric-pods
63+
description: Pods
64+
target:
65+
kind: Pod
66+
group: ""
67+
version: v1
68+
frequency: 1 # in minutes
69+
---
70+
```
71+
72+
Apply the metric:
73+
74+
```bash
75+
kubectl apply -f singlemetric.yaml
76+
```
77+
78+
### Compound Metric
79+
80+
Compound metrics have additional capabilities, such as projections. Projections allow you to extract specific fields from the target resource and include them in the metric data.
81+
This can be useful for tracking additional dimensions of the resource, such as fields, labels or annotations. It uses the dot notation to access nested fields.
82+
The projections are then translated to dimensions in the metric.
83+
84+
```yaml
85+
apiVersion: metrics.cloud.sap/v1beta1
86+
kind: CompoundMetric
87+
metadata:
88+
name: comp-pod
89+
spec:
90+
name: comp-metric-pods
91+
description: Pods
92+
target:
93+
resource: pods
94+
group: ""
95+
version: v1
96+
frequency: 1 # in minutes
97+
projections:
98+
- name: pod-namespace
99+
fieldPath: "metadata.namespace"
100+
---
101+
```
102+
103+
### Federated Metric
104+
Federated metrics deal with resources that are spread across multiple clusters. To monitor these resources, you need to define a `FederatedMetric` resource.
105+
They offer capabilities to aggregate data as well as filtering down to a specific cluster or field using projections.
106+
```yaml
107+
apiVersion: metrics.cloud.sap/v1beta1
108+
kind: FederatedMetric
109+
metadata:
110+
name: xfed-prov
111+
spec:
112+
name: xfed-prov
113+
description: crossplane providers
114+
target:
115+
group: pkg.crossplane.io
116+
resource: providers
117+
version: v1
118+
frequency: 1 # in minutes
119+
projections:
120+
- name: package
121+
fieldPath: "spec.package"
122+
federateCaRef:
123+
name: federate-ca-sample
124+
namespace: default
125+
---
126+
127+
```
128+
129+
### Federated Managed Metric
130+
This is a special use case metric, it is looking at all the crossplane managed resource across all clusters.
131+
The pre-condition here is that if a resource comes from a crossplane provider, its CRD should have categories "crossplane" and "managed".
132+
133+
134+
```yaml
135+
apiVersion: metrics.cloud.sap/v1beta1
136+
kind: FederatedManagedMetric
137+
metadata:
138+
name: xfed-managed
139+
spec:
140+
name: xfed-managed
141+
description: crossplane managed resources
142+
frequency: 1 # in minutes
143+
federateCaRef:
144+
name: federate-ca-sample
145+
namespace: default
146+
---
147+
```
148+
149+
## Remote Cluster Access
150+
151+
152+
### Cluster Access
153+
The Metrics Operator can monitor both the cluster it's deployed in and remote clusters. To monitor a remote cluster, define a `ClusterAccess` resource:
154+
155+
This cluster access resource can be used by `SingleMetric` and `CompoundMetric` resources to monitor resources in the remote cluster.
156+
157+
```yaml
158+
apiVersion: metrics.cloud.sap/v1beta1
159+
kind: ClusterAccess
160+
metadata:
161+
name: remote-cluster
162+
namespace: <monitoring-namespace>
163+
spec:
164+
remoteClusterConfig:
165+
clusterSecretRef:
166+
name: remote-cluster-secret
167+
namespace: <secret-namespace>
168+
serviceAccountName: <service-account-name>
169+
serviceAccountNamespace: <service-account-namespace>
170+
```
171+
172+
173+
### Federated Cluster Access
174+
175+
To monitor resources across multiple clusters, define a `FederatedClusterAccess` resource:
176+
177+
```yaml
178+
apiVersion: metrics.cloud.sap/v1beta1
179+
kind: FederatedClusterAccess
180+
metadata:
181+
name: federate-ca-sample
182+
namespace: default
183+
spec:
184+
target:
185+
group: core.orchestrate.cloud.sap
186+
resource: controlplanes #plural always, lowecase only
187+
version: v1beta1
188+
kubeConfigPath: spec.target.kubeconfig #case sensitive
189+
```
190+
191+
192+
## RBAC Configuration
193+
194+
The Metrics Operator requires appropriate permissions to monitor the resources you specify. You need to configure RBAC (Role-Based Access Control) to grant these permissions. Here's an example of how to create a ClusterRole and ClusterRoleBinding for the Metrics Operator:
195+
196+
```yaml
197+
---
198+
apiVersion: rbac.authorization.k8s.io/v1
199+
kind: ClusterRole
200+
metadata:
201+
name: metrics-operator-role
202+
rules:
203+
- apiGroups:
204+
- "example.group"
205+
resources:
206+
- "exampleresources"
207+
verbs:
208+
- get
209+
- list
210+
- watch
211+
---
212+
apiVersion: rbac.authorization.k8s.io/v1
213+
kind: ClusterRoleBinding
214+
metadata:
215+
name: metrics-operator-rolebinding
216+
subjects:
217+
- kind: ServiceAccount
218+
name: metrics-operator-sa
219+
namespace: <operator-namespace>
220+
roleRef:
221+
kind: ClusterRole
222+
name: metrics-operator-role
223+
apiGroup: rbac.authorization.k8s.io
224+
```
225+
226+
Replace `<operator-namespace>` with the namespace where the Metrics Operator is deployed. Adjust the `apiGroups` and `resources` fields to match the resources you want to monitor.
227+
228+
Apply the RBAC configuration:
229+
230+
```bash
231+
kubectl apply -f rbac-config.yaml
232+
```
233+
234+
Remember to update this RBAC configuration whenever you add new resource types to monitor.
235+
236+
237+
## Data Sink Integration
238+
239+
The Metrics Operator sends collected data to a configured data sink for storage and analysis. The data sink (e.g., Dynatrace) provides tools for data aggregation, filtering, and visualization.
240+
241+
To make the most of your metrics:
242+
243+
1. Configure your data sink according to its documentation.
244+
2. Use the data sink's query language or UI to create custom views of your metrics.
245+
3. Set up alerts based on metric thresholds or patterns.
246+
4. Leverage the data sink's analysis tools to gain insights into your system's behavior and performance.
247+
248+
For specific instructions on using your data sink's features, refer to its documentation. For example, if using Dynatrace, consult the Dynatrace documentation for information on creating custom charts, setting up alerts, and performing advanced analytics on your metric data.
249+
250+
251+
## Getting Started
252+
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
253+
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
254+
255+
### Running on the cluster
256+
1. Install Instances of Custom Resources:
257+
258+
```sh
259+
make dev-local-all
260+
```
261+
262+
2. Run the controller:
263+
264+
```sh
265+
make dev-run
266+
```
267+
Or run it from your IDE.
268+
269+
### Delete Kind Cluster
270+
Delete Kind cluster
271+
```sh
272+
make dev-clean
273+
```
274+
275+
### Modifying the API definitions
276+
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
277+
278+
```sh
279+
make manifests generate
280+
```
12281

13282
## Support, Feedback, Contributing
14283

0 commit comments

Comments
 (0)