Monitoring

Plugwerk Server exposes operational endpoints under /actuator/* for health checks and Prometheus metrics. This page covers the authentication contract for those endpoints and how to configure unattended scraping in production.

Endpoint contract

| Endpoint | Authentication | | ----------------------- | ----------------------------------------------------------- | | /actuator/health | Public (no authentication) | | /actuator/info | Superadmin JWT, or scrape account when configured | | /actuator/prometheus | Superadmin JWT, or scrape account when configured |

/actuator/health is intentionally public so container healthchecks, uptime probes, and orchestrators can poll it without credentials. Any future /actuator/* endpoint is denied by default until it is explicitly opened.

Authentication modes

There are two ways to authenticate against /actuator/info and /actuator/prometheus:

1. Superadmin JWT (default). When no scrape account is configured, only a superadmin Bearer token is accepted. Superadmin tokens have a limited lifetime (see Authentication), which makes this mode unsuitable for unattended Prometheus scraping.
2. Dedicated scrape account (opt-in). A separate HTTP Basic account that grants only the ACTUATOR_SCRAPE authority. This account cannot read namespaces, cannot mint JWTs, and cannot authenticate against any other endpoint — it is scoped exclusively to the actuator chain.

For production Prometheus deployments, configure the scrape account.

Configuring the scrape account

The scrape account is enabled by setting two environment variables together. Half-configured states (one set, the other blank) are rejected at startup.

| Variable | Description | | ----------------------------------------- | --------------------------------------------------------------------------- | | PLUGWERK_AUTH_ACTUATOR_SCRAPE_USERNAME | Username for the HTTP Basic scrape account. | | PLUGWERK_AUTH_ACTUATOR_SCRAPE_PASSWORD | Plaintext password (BCrypt-encoded at startup). Min 16 chars; 32+ recommended. |

Generate a strong password and export both variables:

export PLUGWERK_AUTH_ACTUATOR_SCRAPE_USERNAME=prometheus
export PLUGWERK_AUTH_ACTUATOR_SCRAPE_PASSWORD="$(openssl rand -base64 32)"

Leaving both variables blank keeps the strict default — /actuator/info and /actuator/prometheus then require a superadmin JWT.

Rotation

Rotate the scrape password by updating PLUGWERK_AUTH_ACTUATOR_SCRAPE_PASSWORD and restarting the server. There is no persistent state to migrate.

Prometheus scrape configuration

Use HTTP Basic auth in your Prometheus scrape_configs. Store the password in a file rather than inline:

scrape_configs:
  - job_name: plugwerk
    metrics_path: /actuator/prometheus
    basic_auth:
      username: prometheus
      password_file: /etc/prometheus/plugwerk-scrape-password
    static_configs:
      - targets: ["plugwerk:8080"]

Make sure the password file matches the value of PLUGWERK_AUTH_ACTUATOR_SCRAPE_PASSWORD and is readable only by the Prometheus process.

Kubernetes (ServiceMonitor)

When using the Prometheus Operator, configure HTTP Basic auth via spec.basicAuth and reference a Kubernetes Secret:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: plugwerk
spec:
  selector:
    matchLabels:
      app: plugwerk
  endpoints:
    - port: http
      path: /actuator/prometheus
      basicAuth:
        username:
          name: plugwerk-scrape
          key: username
        password:
          name: plugwerk-scrape
          key: password

The referenced Secret must contain username and password keys matching the values exported on the Plugwerk Server.

Health endpoint

/actuator/health is public and returns a small JSON body indicating overall liveness. Use it for container healthchecks and uptime probes:

curl http://localhost:8080/actuator/health

No credentials are required.