Actuator Read ExecModule

Overview

ActuatorReadModule reads a fresh Spring Boot Actuator health response and up to 24 individual metric responses from one configured service origin. It writes the observed health, metrics, failed endpoints, elapsed duration, and the selected healthy or unhealthy transition to workflow state.

Version 2.0 replaces the module's undocumented, open-ended HTTP behavior with an explicit read contract. Only health and metrics/<name> paths are accepted. Redirects are disabled so credentials cannot be forwarded to another origin, response bodies are capped at 256 KiB, timeouts are capped at 30 seconds, and secrets are accepted only through a bound IntegrationAccount.

Usage

1. Configure the target Spring Boot application to expose only the required Actuator endpoints.
2. Prefer HTTPS whenever the request crosses a host or trust boundary.
3. If the endpoint requires Basic or Bearer authentication, store the credential in an IntegrationAccount and bind it through ExecModuleConfig.authConfig.integrationAccount.
4. Set base_url to the exact Actuator root, such as https://orders.internal.example/actuator.
5. Include health plus any individual metrics/<name> paths in endpoints.
6. Set the healthy and unhealthy workflow transitions, then execute the module under normal generated workflow ACL enforcement.

Every execution performs a fresh read. The module does not serve a cached health result or skip the request because an earlier attempt used the same configuration.

Inputs

Name	Type	Required	Description	Constraints
base_url	string	Yes	Absolute URL of the Actuator root.	HTTP or HTTPS; must contain a host; user info, query strings, fragments, and path traversal are rejected.
endpoints	array of strings	Yes	Actuator paths to read.	1-25 unique items; must include health; remaining items must match metrics/<name>.

The values are stored in normalized ExecModule payload configuration and appear as inputs in Workflow Studio metadata. Arbitrary Actuator paths such as env, configprops, heapdump, logfile, mappings, or shutdown are not supported.

Outputs

Name	Type	Description
actuator.health.status	string	Uppercase status returned by the health endpoint, such as UP, DOWN, OUT_OF_SERVICE, or UNKNOWN.
actuator.metrics	object	Requested metric names mapped to the first numeric measurement value.
actuator.failed_endpoints	array	Endpoint names that failed transport, HTTP, or response validation.
actuator.duration_ms	integer	Total elapsed time for the bounded read.
wf.next	string	next_on_healthy only when health is UP and every requested endpoint succeeds; otherwise next_on_unhealthy.

The runtime ExecModule is marked GOOD only for a complete healthy result. Any missing, malformed, non-200, or failed endpoint marks it ERROR and selects the unhealthy transition.

IntegrationAccount Requirements

Authentication	IntegrationAccount fields	Notes
none	None	Use only when the target safely permits the requested reads without credentials.
basic	username, encrypted password	The account must be READY. A legacy non-secret auth.username fallback is accepted, but the password never comes from payload configuration.
bearer	encrypted apiKey	The account must be READY; apiKey is sent as the Bearer token.

Bind the account through the generated ExecModuleConfig.authConfig.integrationAccount relationship. Do not put passwords, tokens, API keys, bearer values, or credential-bearing URLs in payloadConfig.parameters; the module rejects them before network access.

Configuration

Field	Type	Default	Description
actuatorAccount	IntegrationAccount	None	Workflow Studio account selector for authenticated reads.
auth_type	none, basic, or bearer	none	Authentication strategy.
base_url	URL	None	Exact Actuator root.
endpoints	JSON array	["health"]	Health plus optional individual metric paths.
timeout_sec	integer	10	Per-endpoint connection and read timeout, from 1 through 30 seconds.
next_on_healthy	string	promote	Bounded transition name selected after a complete UP result.
next_on_unhealthy	string	rollback	Bounded transition name selected for every other result.

Illustrative normalized payload parameters:

{
  "base_url": "https://orders.internal.example/actuator",
  "endpoints": ["health", "metrics/process.uptime"],
  "auth_type": "bearer",
  "timeout_sec": 5,
  "next_on_healthy": "promote",
  "next_on_unhealthy": "rollback"
}

The Bearer token is not part of this JSON. It remains in the encrypted apiKey field of the bound account.

Operations

The module performs one bounded operation:

1. Validate the URL, endpoint allowlist, timeout, transition names, and account binding.
2. Read health and each configured metric sequentially from the same origin.
3. Reject redirects and any response larger than 256 KiB.
4. Parse health.status and the first numeric value in each metric's measurements array.
5. Record the complete result and select the healthy or unhealthy transition.

The module does not enumerate metric names, read arbitrary Actuator resources, mutate the target, retry automatically, or follow redirects.

Errors and Failure Modes

Failure	Result	Recovery
Invalid URL or endpoint	No request is sent; module is ERROR.	Correct the URL and use only health or metrics/<name>.
Inline credential	No request is sent; module is ERROR.	Remove the secret and bind a READY IntegrationAccount.
Missing or unusable account	No request is sent; module is ERROR.	Bind an account with the required Basic or Bearer fields.
HTTP redirect	Redirect is not followed; endpoint fails.	Point base_url at the final same-origin Actuator root.
HTTP non-200	Endpoint is added to actuator.failed_endpoints.	Check endpoint exposure, authentication, authorization, proxy, and service state.
Timeout or network error	Endpoint fails with a sanitized EventLog.	Check connectivity and service health, then run a deliberate fresh read.
Oversized or malformed response	Endpoint fails without retaining the response body.	Reduce exposed detail or correct the target's Actuator response contract.
Health not UP or any metric failure	Runtime module is ERROR; next_on_unhealthy is selected.	Inspect service-side diagnostics under separately authorized operational access.

Credentials, response bodies, and transport exception bodies are never written to workflow state or failure events.

Example

Configuration:

{
  "base_url": "https://orders.internal.example/actuator",
  "endpoints": ["health", "metrics/process.uptime"],
  "auth_type": "bearer",
  "timeout_sec": 5
}

Given {"status":"UP"} and a metric response containing {"measurements":[{"value":123.5}]}, the expected result shape is:

{
  "actuator.health.status": "UP",
  "actuator.metrics": {"process.uptime": 123.5},
  "actuator.failed_endpoints": [],
  "actuator.duration_ms": 42,
  "wf.next": "promote"
}

Notes

• Pagination: not applicable. Each configured path is a single bounded Actuator read.
• Limits: at most 25 endpoints, 30 seconds per endpoint, and 256 KiB per response. Reads are sequential to avoid a monitoring burst against a degraded target.
• Idempotency: reads are naturally safe to retry, but health is time-sensitive. The module always performs a fresh request and does not cache or short-circuit repeated configurations.
• API constraints: only the standard health shape and the first numeric value in a standard metric measurements array are normalized. Composite components and metric tags remain service-side details.
• Rate limits: there is no automatic retry. A target or proxy can rate-limit the read; the affected endpoint then fails closed.
• Destructive behavior: none. The module supports GET reads only and never calls write-capable Actuator paths.
• Security: this module intentionally reaches operator-configured internal services. Generated workflow ACLs remain authoritative; the module's URL and path checks reduce, but do not replace, network egress policy and service-side Actuator authorization.
• Observability: EventLogs contain endpoint names, HTTP status codes, and bounded success/failure summaries, never credentials or response bodies.
• Unverified boundary: deterministic tests cover configuration validation, same-origin request construction, account binding, response mapping, fresh repeated reads, metadata serialization, and secret-safe failures. A live authenticated customer Actuator service is not called in repository tests.

See the Spring Boot reference for service-side endpoint exposure, security, and health or metric response configuration.