1.1. Overview — What OPENMARU APM Operator Is
Overview
OPENMARU APM Operator automates applying the APM agent and scaling on load in a Kubernetes or OpenShift cluster. This chapter explains the problem the Operator solves, the role of its two components, and the overall flow.
1. Why It Is Needed
Monitoring an application with OPENMARU APM used to mean doing the following by hand.
- Rebuilding the container image to include the agent (a jar)
- Setting the
-javaagentJVM option and the APM connection details (OMAPM_*) one workload at a time - Rebuilding and redeploying every image whenever the agent version changed
Once pods number in the dozens or hundreds this is tedious, and it is easy to miss one or configure it wrongly. There is also the problem that CPU and memory alone do not reflect the real load (the request volume) in time when traffic surges, so scaling happens late or overshoots.
OPENMARU APM Operator automates both of these -- applying instrumentation and scaling on load -- at the Kubernetes / OpenShift level.
2. What Gets Better
| Area | Before the Operator | After the Operator |
|---|---|---|
| Applying the agent | Rebuild the image and set JVM options by hand | One label and it is injected automatically (the image is untouched) |
| New and scaled-out pods | Repeat by hand for every pod that comes up | Applied automatically wherever the label is (less operational burden) |
| Changing the agent version | Rebuild and redeploy the image | Change the version in the label |
| Configuration mistakes | Omissions and typos are common | Standardised automatic injection means fewer mistakes |
| Autoscaling basis | CPU and memory only | Can scale on TPS (the real request volume) -- a more accurate response to traffic |
| The original application | Code and image affected | Untouched (injected separately by an init container) |
The main benefits in one line each:
- Simpler operation -- one label finishes the instrumentation, and the image is not touched.
- Accurate autoscaling -- pods grow and shrink on the load users actually feel (TPS), reducing response delay and overscaling.
- Consistency -- connection details and JVM options are injected in a standard way, unifying settings that used to differ per environment.
3. The Two Components
The Operator runs as two pods (components).
3.1 APM Agent — Auto-Instrumentation
A Kubernetes mutating admission webhook. It intercepts the moment a pod is created and, if the
target workload carries the label openmaru.io/was-agent: 'true', inserts the following
automatically.
- A shared volume (
khan-data, emptyDir) - An init container (
khan-agent-init) -- unpacks the agent files into the shared volume -javaagentand the APM connection environment variables (OMAPM_*) in the application container
The result is that the agent is applied without modifying the original image. For how to use it, see 301 Auto-Instrumentation.
3.2 APM HPA — a Custom Autoscaler
An adapter that implements the Kubernetes External Metrics API
(external.metrics.k8s.io/v1beta1). It answers the external metrics a HorizontalPodAutoscaler (HPA)
asks for by querying the OPENMARU APM server.
- Metric provided today:
tps(the application group's requests handled per second) - The HPA reads that value and adjusts the pod count automatically
For how to use it, see 302 Autoscaling.
4. How It Works
4.1 Auto-Instrumentation
4.2 Autoscaling
5. Where It Applies and What It Assumes
- A Kubernetes or OpenShift (OCP) cluster
- An OPENMARU APM server running and reachable over the network from the Operator pods
- The instrumentation targets are Java (WAS) workloads
In an OPENMARU COP environment the Operator is configured automatically. On COP (the cloud operations platform, based on Kubernetes/OpenShift) this Operator is included by default and is deployed and configured automatically with no separate installation. COP users can therefore start straight from 301 Auto-Instrumentation. For installing on a cluster you built yourself, see 201 Installation.
6. Terms
| Term | Description |
|---|---|
| Auto-instrumentation | Attaching the agent automatically with no code or image change |
| Webhook (mutating) | The Kubernetes feature that intercepts a pod creation request and alters the spec |
| khan-agent | The OPENMARU WAS agent (a jar). Loaded with -javaagent |
| Application group (groupName) | The unit that groups instances in OPENMARU APM. The key for looking up an HPA metric |
| apmAlias | The alias that distinguishes several APM servers. It decides which server the HPA asks |