Application Role RLS Health Indicator

Overview

The AppRoleRlsHealthIndicator is a readiness contributor that verifies the status of Row-Level Security (RLS) for the Admin API's database connection pool. Its primary purpose is to ensure that in a multi-tenant SaaS deployment, an application instance does not become ready to serve traffic unless RLS is confirmed to be active.

This component implements a "fail-closed" strategy. If the initial check during startup determines that RLS is not active or if the check fails, the instance reports a DOWN health status. This prevents it from being added to the load balancer's active pool, mitigating the risk of data exposure between tenants.

The health check's behavior is conditional on the platform's operating mode:

• In SaaS mode: The indicator strictly enforces that RLS must be active. A failure results in a DOWN status.
• Outside of SaaS mode: The indicator always reports an UP status to maintain backward compatibility with previous appliance behavior, though it will log a warning if RLS is not active.

The SaaS mode setting is evaluated on every health check, so a change to the platform license that enables SaaS mode will take effect on the next health check.

How It Works

The AppRoleRlsHealthIndicator determines the health status through a sequence of probes and checks, primarily within its health() method, which is called by the Spring Boot Actuator framework.

Initial Probe

Upon application startup (triggered by an ApplicationReadyEvent), the indicator performs an initial database probe via the probe() method. This one-time check determines the RLS status, and the outcome is cached. If this probe has not yet run, any health check request will return UP with a detail of probe: pending.

Health Check Logic

When the health endpoint is invoked, the indicator follows this logic:

flowchart TD
    A[Health Check Request] --> B{Initial probe run?};
    B -- No --> C[Return UP<br/>(detail: probe=pending)];
    B -- Yes --> D{SaaS mode enabled?};
    D -- No --> E[Return UP<br/>(detail: outcome=...)];
    D -- Yes --> F{Last outcome is<br/>PROBE_FAILED?};
    F -- No --> G[Use current outcome];
    F -- Yes --> H{30s elapsed since<br/>last probe?};
    H -- No --> G;
    H -- Yes --> I[Execute new DB probe];
    I --> J[Update last outcome];
    J --> G;
    G --> K{Outcome is<br/>RLS_ACTIVE?};
    K -- Yes --> E;
    K -- No --> L[Return DOWN<br/>(detail: outcome=...)];

1. Check for Initial Probe: If the initial probe result is not yet available, the status is UP with a detail indicating the probe is pending.
2. Check SaaS Mode: The indicator checks if the system is currently in SaaS mode.
3. Non-SaaS Path: If SaaS mode is disabled, the indicator immediately returns UP, regardless of the RLS probe outcome.
4. SaaS Path: If SaaS mode is enabled, the logic proceeds: a. Check for Probe Failure: It checks if the last recorded probe outcome was PROBE_FAILED. b. Retry Mechanism: If the outcome was PROBE_FAILED and at least 30 seconds (RETRY_INTERVAL) have passed since the last attempt, it triggers a new database probe. This allows the instance to recover from transient database issues at startup without requiring a restart. A definite outcome (e.g., RLS_ACTIVE or an owner bypass) is never re-probed. c. Determine Final Status: The final health status is determined based on the probe outcome. If the outcome is anything other than RLS_ACTIVE, the indicator returns DOWN. Otherwise, it returns UP.

Health Endpoint Status

The status of this component is exposed as part of the standard Spring Boot Actuator health endpoint (e.g., /actuator/health) under the name rlsRole.

Response Structure

The JSON response for this indicator includes a status field (UP or DOWN) and a details object containing the outcome of the RLS probe.

{
  "status": "UP",
  "components": {
    "rlsRole": {
      "status": "UP",
      "details": {
        "outcome": "RLS_ACTIVE"
      }
    },
    "...": {}
  }
}

Possible Outcomes

The outcome field in the response details can have several values. The source explicitly defines the following:

Example Responses

SaaS Mode: RLS Active An instance operating correctly in SaaS mode will report UP.

{
  "status": "UP",
  "details": {
    "outcome": "RLS_ACTIVE"
  }
}

SaaS Mode: Probe Failed If the database probe fails in SaaS mode, the instance reports DOWN.

{
  "status": "DOWN",
  "details": {
    "outcome": "PROBE_FAILED"
  }
}

Non-SaaS Mode Outside of SaaS mode, the indicator always reports UP, but includes the actual probe outcome in the details.

{
  "status": "UP",
  "details": {
    "outcome": "PROBE_FAILED"
  }
}

Troubleshooting

Status: DOWN

A DOWN status from the rlsRole health indicator occurs only when the platform is in SaaS mode and the RLS probe could not confirm that RLS is active. Check the outcome field in the health endpoint's response details to diagnose the cause.

• outcome: PROBE_FAILED

  • Meaning: The indicator could not connect to the database to verify the RLS status. This is often a transient issue.
  • Action: No immediate action is required. The indicator will automatically retry the probe after a 30-second interval. If the status persists, investigate for a larger database connectivity or availability problem.

• outcome: (Any value other than RLS_ACTIVE)

  • Meaning: The probe completed successfully but found that RLS is not correctly configured for the application database role. This is a permanent configuration error.
  • Action: This issue cannot be resolved by the automatic retry mechanism. The source indicates that fixing the underlying database configuration and restarting the application instance is required. Consult startup logs for more specific details about the misconfiguration.

Status: UP

• details: { "probe": "pending" }

  • Meaning: The health check was executed before the application's initial RLS probe completed. This is a normal, transient state during service startup. The status will update once the probe finishes.

• In Non-SaaS Mode

  • Meaning: The indicator is configured to always report UP when not in SaaS mode. However, if the outcome is not RLS_ACTIVE, it indicates a potential RLS misconfiguration that is being ignored. A WARN message is logged in this scenario.

Configuration

The component has one internal timing constant that governs its retry behavior.

All SOAP-to-REST docs