Skip to content

Commit 76b5ab5

Browse files
n3rdc4ptnn3rdc4ptn
committed
docs: add MCPUsage and Metering Operator documentation
1 parent 8252c07 commit 76b5ab5

File tree

3 files changed

+125
-0
lines changed

3 files changed

+125
-0
lines changed

‎docs/mcpusage.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# MCPUsage Resource
2+
3+
The `MCPUsage` resource is created automatically by the usage-operator based on the MCPs located on the onboarding cluster.
4+
The resources get a UUID as there name, but also contain the project, workspace and mcp-name. This is also visible in the display columns, when running `kubectl get mcpusage`.
5+
6+
The resource is structured like so:
7+
8+
```yaml
9+
apiVersion: usage.openmcp.cloud/v1
10+
kind: MCPUsage
11+
metadata:
12+
name: 0fde12fa-c822-5d51-a2c2-aa11be641f0d
13+
spec:
14+
project: test
15+
workspace: test
16+
mcp: test-bug
17+
charging_target: missing
18+
charging_target_type: ""
19+
daily_usage:
20+
- date: "2025-07-22T00:00:00Z"
21+
usage: 14h57m21.929782431s
22+
- date: "2025-07-23T00:00:00Z"
23+
usage: 24h0m0s
24+
- date: "2025-07-24T00:00:00Z"
25+
usage: 24h0m0s
26+
- date: "2025-07-25T00:00:00Z"
27+
usage: 24h0m0s
28+
- date: "2025-07-26T00:00:00Z"
29+
usage: 24h0m0s
30+
- date: "2025-07-27T00:00:00Z"
31+
usage: 24h0m0s
32+
- date: "2025-07-28T00:00:00Z"
33+
usage: 6h0m4.499363869s
34+
last_usage_captured: "2025-07-28T06:52:32Z"
35+
mcp_created_at: "2025-07-22T09:07:12Z"
36+
message: no charging target specified
37+
```
38+
39+
This is what the resource looks like, when the usage-operator creates and manages it, the status is untouched, as this is the responsibility of a `metering-operator` (see [Metering Operator](metering-operator.md))
40+
41+
## Garbage Collection
42+
43+
The `usage-operator` enforces a strict garbage collection policy for the `daily_usage` field, retaining usage data for the most recent **32** days only. This allows you to review usage status for up to one month. The garbage collection operates on a rolling basis, automatically removing the oldest entry each day to maintain the 32-day window.
44+
45+
There are plans to make the **32**-day retention window configurable in future releases of the `usage-operator`.

‎docs/metering-operator.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Metering Operators
2+
3+
As metering the usage of your platform to your customers is highly dependend on your environment, we created a system which decouples usage collection from the actual metering. The [MCPUsage](mcpusage.md) resource is the connection point.
4+
This resource just reports the usage of your platform. The metering itself needs a custom operator, you need to provide yourself.
5+
6+
A metering operator needs to reconcile the `MCPUsage` resource and extracts the usage information from the `spec`. To report status back, it can edit the `status` of the respective `MCPUsage` resource.
7+
One example is the following resource:
8+
9+
```yaml
10+
apiVersion: usage.openmcp.cloud/v1
11+
kind: MCPUsage
12+
metadata:
13+
name: 0fde12fa-c822-5d51-a2c2-aa11be641f0d
14+
spec:
15+
project: test
16+
workspace: test
17+
mcp: test-bug
18+
charging_target: missing
19+
charging_target_type: ""
20+
daily_usage:
21+
- date: "2025-07-22T00:00:00Z"
22+
usage: 14h57m21.929782431s
23+
- date: "2025-07-23T00:00:00Z"
24+
usage: 24h0m0s
25+
- date: "2025-07-24T00:00:00Z"
26+
usage: 24h0m0s
27+
- date: "2025-07-25T00:00:00Z"
28+
usage: 24h0m0s
29+
- date: "2025-07-26T00:00:00Z"
30+
usage: 24h0m0s
31+
- date: "2025-07-27T00:00:00Z"
32+
usage: 24h0m0s
33+
- date: "2025-07-28T00:00:00Z"
34+
usage: 6h0m4.499363869s
35+
last_usage_captured: "2025-07-28T06:52:32Z"
36+
mcp_created_at: "2025-07-22T09:07:12Z"
37+
message: no charging target specified
38+
status:
39+
daily_usage_report:
40+
- date: "2025-07-22T00:00:00Z"
41+
message: charging target missing
42+
status: Failed
43+
- date: "2025-07-23T00:00:00Z"
44+
message: charging target missing
45+
status: Failed
46+
- date: "2025-07-24T00:00:00Z"
47+
message: charging target missing
48+
status: Failed
49+
- date: "2025-07-25T00:00:00Z"
50+
message: charging target missing
51+
status: Failed
52+
- date: "2025-07-26T00:00:00Z"
53+
message: charging target missing
54+
status: Failed
55+
- date: "2025-07-27T00:00:00Z"
56+
message: charging target missing
57+
status: Failed
58+
```
59+
60+
As you can see, the metering operator can report a list of `daily_usage_report` back, to provide information for every day the usage is collected.
61+
It can provice a short status and a message. In the example, the responsible metering operator reports, that the charging target is missing.
62+
63+
As the status is not used for anything in the usage-operator, you can decide what messages you want to display there. This can be used for your metering operator to check, which usage entry it already reported, and what maybe needs to be reported again. Keep in mind, that the status of the resource is not permanently stored and can be lost, due to kubernetes own guidelines. So your operator should not depend on the status being saved indefinitely.

‎docs/setup.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Setup
2+
3+
To install the usage-operator into your MCP landscape, you need to register it as a new PlatformService.
4+
This can be done using the `PlatformService` Resource.
5+
6+
```yaml
7+
apiVersion: openmcp.cloud/v1alpha1
8+
kind: PlatformService
9+
metadata:
10+
name: usage-operator
11+
spec:
12+
image: "ghcr.io/openmcp-project/images/usage-operator:v0.0.11"
13+
imagePullSecrets: []
14+
```
15+
16+
The usage-operator will then automatically be installed by the mcp platform and requests its permissions for the onboarding cluster.
17+
Inside the onboarding cluster a new CRD will then be installed called `MCPUsage`. This resource is completely managed by the `usage-operator` and there is no need to create resource manually.

0 commit comments

Comments
 (0)