Skip to content

Commit 39d9585

Browse files
csviricsviri
committed
docs: operations section
Signed-off-by: Attila Mészáros <a_meszaros@apple.com>
1 parent aad20b9 commit 39d9585

File tree

5 files changed

+174
-56
lines changed

5 files changed

+174
-56
lines changed

‎docs/content/en/docs/documentation/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ This section contains detailed documentation for all Java Operator SDK features
1919

2020
- **[Eventing](eventing/)** - Understanding the event-driven model
2121
- **[Accessing Resources in Caches](working-with-es-caches/)** - How to access resources in caches
22-
- **[Operations](operations/)** - Operations-related features including observability
22+
- **[Operations](operations/)** - Helm chart, metrics, and logging
2323
- **[Other Features](features/)** - Additional capabilities and integrations
2424

2525
Each guide includes practical examples and best practices to help you build robust, production-ready operators.

‎docs/content/en/docs/documentation/operations/_index.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,3 @@ weight: 85
44
---
55

66
This section covers operations-related features for running and managing operators in production.
7-
8-
- **[Observability](observability/)** - Monitoring and debugging your operators

‎docs/content/en/docs/documentation/operations/helm-chart.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: Generic Helm Chart
3+
weight: 86
4+
---
5+
6+
A generic, reusable Helm chart for deploying Java operators built with JOSDK is available at
7+
[`helm/generic-helm-chart`](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/helm/generic-helm-chart).
8+
9+
It is intended as a **template for operator developers** — a starting point that covers common deployment
10+
patterns so you don't have to write a chart from scratch. The chart is maintained on a **best-effort basis**.
11+
Contributions are more than welcome.
12+
13+
The chart is used in the
14+
[`metrics-processing` sample operator E2E test](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/sample-operators/metrics-processing/src/test/java/io/javaoperatorsdk/operator/sample/metrics/MetricsHandlingE2E.java)
15+
to deploy the operator to a cluster via Helm.
16+
17+
## What the Chart Provides
18+
19+
- **Deployment** with security defaults (non-root user, read-only filesystem, no privilege escalation)
20+
- **Dynamic RBAC** (ClusterRole, ClusterRoleBinding, ServiceAccount) — permissions are generated automatically
21+
from the primary and secondary resources you declare in `values.yaml`
22+
- **ConfigMap** for operator configuration (`config.yaml`) and logging (`log4j2.xml`), mounted at `/config`
23+
- **Leader election** support (opt-in)
24+
- **Extensibility** via extra containers, init containers, volumes, and environment variables
25+
26+
## Key Configuration
27+
28+
The most important values to set when adapting the chart for your operator:
29+
30+
```yaml
31+
image:
32+
repository: my-operator-image # required
33+
tag: "latest"
34+
35+
# Custom resources your operator reconciles
36+
primaryResources:
37+
- apiGroup: "sample.javaoperatorsdk"
38+
resources:
39+
- myresources
40+
41+
# Kubernetes resources your operator manages
42+
secondaryResources:
43+
- apiGroup: ""
44+
resources:
45+
- configmaps
46+
- services
47+
```
48+
49+
Primary resources get read/watch/patch permissions and status sub-resource access.
50+
Secondary resources get full CRUD permissions. Default verbs can be overridden per resource entry.
51+
52+
### Operator Environment
53+
54+
The chart injects `OPERATOR_NAMESPACE` automatically. You can optionally set `WATCH_NAMESPACE` to
55+
restrict the operator to a single namespace, and add arbitrary environment variables:
56+
57+
```yaml
58+
operator:
59+
watchNamespace: "" # empty = all namespaces
60+
env:
61+
- name: MY_CUSTOM_VAR
62+
value: "some-value"
63+
```
64+
65+
### Resource Defaults
66+
67+
```yaml
68+
resources:
69+
limits:
70+
cpu: 500m
71+
memory: 512Mi
72+
requests:
73+
cpu: 100m
74+
memory: 128Mi
75+
```
76+
77+
See the full
78+
[`values.yaml`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/helm/generic-helm-chart/values.yaml)
79+
for all available options.
80+
81+
## Usage Example
82+
83+
A working example of how to use the chart can be found in the metrics-processing sample operator's
84+
[`helm-values.yaml`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/sample-operators/metrics-processing/src/test/resources/helm-values.yaml):
85+
86+
```yaml
87+
image:
88+
repository: metrics-processing-operator
89+
pullPolicy: Never
90+
tag: "latest"
91+
92+
nameOverride: "metrics-processing-operator"
93+
94+
resources: {}
95+
96+
primaryResources:
97+
- apiGroup: "sample.javaoperatorsdk"
98+
resources:
99+
- metricshandlingcustomresource1s
100+
- metricshandlingcustomresource2s
101+
```
102+
103+
Install with:
104+
105+
```shell
106+
helm install my-operator ./helm/generic-helm-chart -f my-values.yaml --namespace my-ns
107+
```
108+
109+
## Testing the Chart
110+
111+
The chart includes unit tests using the [helm-unittest](https://github.com/helm-unittest/helm-unittest) plugin.
112+
Run them with:
113+
114+
```shell
115+
./helm/run-tests.sh
116+
```

‎docs/content/en/docs/documentation/operations/logging.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Logging
3+
weight: 88
4+
---
5+
6+
## Contextual Info for Logging with MDC
7+
8+
Logging is enhanced with additional contextual information using
9+
[MDC](http://www.slf4j.org/manual.html#mdc). The following attributes are available in most
10+
parts of reconciliation logic and during the execution of the controller:
11+
12+
| MDC Key | Value added from primary resource |
13+
|:---------------------------|:----------------------------------|
14+
| `resource.apiVersion` | `.apiVersion` |
15+
| `resource.kind` | `.kind` |
16+
| `resource.name` | `.metadata.name` |
17+
| `resource.namespace` | `.metadata.namespace` |
18+
| `resource.resourceVersion` | `.metadata.resourceVersion` |
19+
| `resource.generation` | `.metadata.generation` |
20+
| `resource.uid` | `.metadata.uid` |
21+
22+
For more information about MDC see this [link](https://www.baeldung.com/mdc-in-log4j-2-logback).
23+
24+
### MDC entries during event handling
25+
26+
Although, usually users might not require it in their day-to-day workflow, it is worth mentioning that
27+
there are additional MDC entries managed for event handling. Typically, you might be interested in it
28+
in your `SecondaryToPrimaryMapper` related logs.
29+
For `InformerEventSource` and `ControllerEventSource` the following information is present:
30+
31+
| MDC Key | Value from Resource from the Event |
32+
|:-----------------------------------------------|:-------------------------------------------------|
33+
| `eventsource.event.resource.name` | `.metadata.name` |
34+
| `eventsource.event.resource.uid` | `.metadata.uid` |
35+
| `eventsource.event.resource.namespace` | `.metadata.namespace` |
36+
| `eventsource.event.resource.kind` | resource kind |
37+
| `eventsource.event.resource.resourceVersion` | `.metadata.resourceVersion` |
38+
| `eventsource.event.action` | action name (e.g. `ADDED`, `UPDATED`, `DELETED`) |
39+
| `eventsource.name` | name of the event source |
40+
41+
### Note on null values
42+
43+
If a resource doesn't provide values for one of the specified keys, the key will be omitted and not added to the MDC
44+
context. There is, however, one notable exception: the resource's namespace, where, instead of omitting the key, we emit
45+
the `MDCUtils.NO_NAMESPACE` value instead. This allows searching for resources without namespace (notably, clustered
46+
resources) in the logs more easily.
47+
48+
### Disabling MDC support
49+
50+
MDC support is enabled by default. If you want to disable it, you can set the `JAVA_OPERATOR_SDK_USE_MDC` environment
51+
variable to `false` when you start your operator.

docs/content/en/docs/documentation/operations/observability.md renamed to docs/content/en/docs/documentation/operations/metrics.md

Lines changed: 6 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Observability
3-
weight: 55
2+
title: Metrics
3+
weight: 87
44
---
55

66
## Runtime Info
@@ -15,53 +15,6 @@ setting, where this flag usually needs to be set to false, in order to control t
1515
See also an example implementation in the
1616
[WebPage sample](https://github.com/java-operator-sdk/java-operator-sdk/blob/3e2e7c4c834ef1c409d636156b988125744ca911/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageOperator.java#L38-L43)
1717

18-
## Contextual Info for Logging with MDC
19-
20-
Logging is enhanced with additional contextual information using
21-
[MDC](http://www.slf4j.org/manual.html#mdc). The following attributes are available in most
22-
parts of reconciliation logic and during the execution of the controller:
23-
24-
| MDC Key | Value added from primary resource |
25-
|:---------------------------|:----------------------------------|
26-
| `resource.apiVersion` | `.apiVersion` |
27-
| `resource.kind` | `.kind` |
28-
| `resource.name` | `.metadata.name` |
29-
| `resource.namespace` | `.metadata.namespace` |
30-
| `resource.resourceVersion` | `.metadata.resourceVersion` |
31-
| `resource.generation` | `.metadata.generation` |
32-
| `resource.uid` | `.metadata.uid` |
33-
34-
For more information about MDC see this [link](https://www.baeldung.com/mdc-in-log4j-2-logback).
35-
36-
### MDC entries during event handling
37-
38-
Although, usually users might not require it in their day-to-day workflow, it is worth mentioning that
39-
there are additional MDC entries managed for event handling. Typically, you might be interested in it
40-
in your `SecondaryToPrimaryMapper` related logs.
41-
For `InformerEventSource` and `ControllerEventSource` the following information is present:
42-
43-
| MDC Key | Value from Resource from the Event |
44-
|:-----------------------------------------------|:-------------------------------------------------|
45-
| `eventsource.event.resource.name` | `.metadata.name` |
46-
| `eventsource.event.resource.uid` | `.metadata.uid` |
47-
| `eventsource.event.resource.namespace` | `.metadata.namespace` |
48-
| `eventsource.event.resource.kind` | resource kind |
49-
| `eventsource.event.resource.resourceVersion` | `.metadata.resourceVersion` |
50-
| `eventsource.event.action` | action name (e.g. `ADDED`, `UPDATED`, `DELETED`) |
51-
| `eventsource.name` | name of the event source |
52-
53-
### Note on null values
54-
55-
If a resource doesn't provide values for one of the specified keys, the key will be omitted and not added to the MDC
56-
context. There is, however, one notable exception: the resource's namespace, where, instead of omitting the key, we emit
57-
the `MDCUtils.NO_NAMESPACE` value instead. This allows searching for resources without namespace (notably, clustered
58-
resources) in the logs more easily.
59-
60-
### Disabling MDC support
61-
62-
MDC support is enabled by default. If you want to disable it, you can set the `JAVA_OPERATOR_SDK_USE_MDC` environment
63-
variable to `false` when you start your operator.
64-
6518
## Metrics
6619

6720
JOSDK provides built-in support for metrics reporting on what is happening with your reconcilers in the form of
@@ -77,9 +30,9 @@ Metrics metrics; // initialize your metrics implementation
7730
Operator operator = new Operator(client, o -> o.withMetrics(metrics));
7831
```
7932

80-
### MicrometerMetricsV2
33+
### MicrometerMetricsV2
8134

82-
[`MicrometerMetricsV2`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/micrometer-support/src/main/java/io/javaoperatorsdk/operator/monitoring/micrometer/MicrometerMetricsV2.java)
35+
[`MicrometerMetricsV2`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/micrometer-support/src/main/java/io/javaoperatorsdk/operator/monitoring/micrometer/MicrometerMetricsV2.java)
8336
is the recommended micrometer-based implementation. It is designed with low cardinality in mind:
8437
all meters are scoped to the controller, not to individual resources. This avoids unbounded cardinality growth as
8538
resources come and go.
@@ -230,8 +183,8 @@ Metrics loggingMetrics = new LoggingMetrics();
230183

231184
// combine them into a single aggregated instance
232185
Metrics aggregatedMetrics = new AggregatedMetrics(List.of(
233-
micrometerMetrics,
234-
customMetrics,
186+
micrometerMetrics,
187+
customMetrics,
235188
loggingMetrics
236189
));
237190

0 commit comments

Comments
 (0)