Load Balancer Health Check Integration

Overview

The Cloud Connector exposes a dedicated round-trip health check endpoint (cc-round-trip-health-status) that enables load balancers to make intelligent, real-time routing decisions based on the actual health of each Cloud Connector instance.

Before v2026.2.0.0 release, load balancers used static IP or host-based routing without checking the health of individual Cloud Connector instances. As a result, traffic could be routed to unhealthy instances, causing failed operations, increased errors, and a degraded user experience, particularly for integrations such as IoT device management and SIGN+.

By integrating this endpoint with your load balancer, traffic will be routed only to healthy Cloud Connector instances, improving reliability and overall system stability.

Health Check Endpoint Reference

Table 1. Health check endpoint properties
Property Value
Endpoint cc-round-trip-health-status
HTTP Method GET
Response SLA ≤ 10,000 ms
Available 2026.2.0.0

Example request:

GET https://<cloud-connector-host>:<port>/cc-round-trip-health-status

How It Works

The health check evaluates two internal communication signals to determine whether a Cloud Connector instance is operational:

  1. Incoming Request Signal - Confirms that the Cloud Connector is actively receiving inbound requests from the SaaS platform.
  2. Outbound Acknowledgement Signal - Confirms that the Cloud Connector is successfully sending responses back to the SaaS platform.

If either signal has not been observed within the configured staleness threshold (default: 5 minutes / 300,000 ms), the instance is classified as unhealthy and the endpoint returns a failure response.

A stale signal is typically caused by worker thread pool saturation, a network disruption, or an internal processing failure. When this occurs, the Cloud Connector automatically logs additional diagnostic information (active threads, pool size, and queue depth) to assist with investigation.

Health Signal Definition

Table 2. HTTP status codes and their meanings
HTTP Status Health State Meaning Load Balancer Action
200 OK UP Instance is healthy and actively communicating with the SaaS platform Include in the active routing pool
503 Service Unavailable DOWN Instance is degraded, disconnected, or has exceeded the signal staleness threshold Exclude from the routing pool immediately

Staleness Threshold Configuration (Optional)

Both signal thresholds are independently configurable via environment variables. The default value for each is 300,000 ms (5 minutes).

Table 3. Environment variables for staleness threshold configuration
Environment Variable Default Value Description 
CC_HEALTH_CHECK
_STATUS_TIMER_MS
 300000 Maximum allowed age (in ms) of the last incoming-request signal before the instance is marked unhealthy 
CC_ACK_HEALTH_CHECK
_STATUS_TIMER_MS
 300000 Maximum allowed age (in ms) of the last outbound-acknowledgement signal before the instance is marked unhealthy

To adjust these thresholds, set the relevant environment variables in the Cloud Connector deployment configuration and restart the service.

Recommended Load Balancer Configuration

Use the following settings when configuring your load balancer health check probe against the Cloud Connector:

Table 4. Recommended load balancer health check settings
Setting Recommended Value
Health Check URL GET /cc-round-trip-health-status
Healthy Threshold 2 consecutive successful (HTTP 200) responses
Unhealthy Threshold 2 – 3 consecutive failed (HTTP 503) responses
Check Interval 30 – 60 seconds
Probe Timeout 10 – 15 seconds

Expected behavior:

  • When the Cloud Connector returns HTTP 200 (UP), the load balancer marks the instance as healthy and includes it in the active routing pool.
  • When the Cloud Connector returns HTTP 503 (DOWN), the load balancer removes the instance from the pool and stops sending new traffic to it.
  • Once the instance recovers and returns HTTP 200 again, the load balancer will automatically re-admit it into active rotation.

Benefits

  • Improved reliability - Traffic is directed only to Cloud Connector instances that are confirmed to be communicating with the SaaS platform.
  • Automatic failover - Degraded instances are excluded from routing without manual intervention, reducing the blast radius of failures.
  • Early detection - Health probe failures surface degraded instances proactively, before they cause widespread user-facing issues.
  • Broad applicability - Especially beneficial for high-traffic integration scenarios such as IoT device management and SIGN workflows.