Configure origins and health checks

You create an upstream group, add an origin and configure active HTTP probes. Passive checks use observed backend failures.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• A reachable origin domain and a probe path that accepts the configured method. Use example.com as the origin placeholder. An existing probe client certificate, exported as MTLS_CLIENT_CERTIFICATE_ID, for the active-check request below.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
MTLS_CLIENT_CERTIFICATE_ID	Returned resource identifier, or your selected scope identifier.
UPSTREAM_GROUP_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'MTLS_CLIENT_CERTIFICATE_ID: ' MTLS_CLIENT_CERTIFICATE_ID
export MTLS_CLIENT_CERTIFICATE_ID

Steps

1. Create the upstream group.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/upstream-groups" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"name":"web_origins","connectTimeoutMilliseconds":5000}'

   API reference: Creates a new upstream group (backend pool)

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "upstreamGroupId": 1
     }
   }

   Set UPSTREAM_GROUP_ID to the returned upstreamGroupId.

2. Add your origin. Replace example.com with your origin domain.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/upstream-groups/$UPSTREAM_GROUP_ID/upstreams" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"targetType":"domain","domain":"example.com"}'

   API reference: Adds a backend target to an upstream group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "upstreamId": 1
     }
   }

3. Enable active HTTP checks and passive checks.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request PATCH \
     --url "https://<your-api-host>/upstream-groups/$UPSTREAM_GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'healthCheck': {'active': {'enabled': True, 'type': 'http', 'domain': 'example.com', 'path': '/health', 'port': 80, 'intervalSeconds': 180, 'triesPerCheck': 3, 'timeoutMilliseconds': 15000, 'mtlsClientCertificateId': int(os.environ['MTLS_CLIENT_CERTIFICATE_ID'])}, 'passive': {'enabled': True}}}))
   PYBODY

   API reference: Update an upstream group configuration

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "upstreamGroupId": 1
     }
   }

4. Read back the group and its origins.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/upstream-groups/$UPSTREAM_GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get an upstream group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "upstreamGroupId": 1
     }
   }

Verify

Confirm the probe path returns an allowed status, then send an application request through your HTTP group. A successful probe does not establish that every application request succeeds. Ask support for endpoint health observations if selection differs from your expectations.

Use your configured site domain in this traffic check:

curl --silent --show-error --include "https://example.com/"

Expected: the site behavior described above. The application response body and status depend on your origin and selected policies.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

TODO(verify): Whether mtlsClientCertificateId can be omitted for an HTTP probe. The available active-check schema marks it required, so this example supplies an existing certificate identifier.

Troubleshooting

Symptom	Cause	Fix
Origin requests fail	Port, reachability or TLS identity differs from the origin	Check origin port, network access and TLS identity.
Probe fails but the site works	Probe Host, path or authentication differs	Use a reachable probe path and the intended Host.
One failed request appears to change health	Active probes and passive observations are separate	Compare both settings and ask support for endpoint observations.

Limits and defaults

Setting	Limit or default
Connection timeout	Default 5000 ms; 1 to 120000 ms
Active interval	Default 180 seconds; 10 to 3600
Attempts per check	Default 3; 1 to 10
Probe timeout	Default 15000 ms; 1000 to 60000
Probe method	Default GET; GET or HEAD
Allowed HTTP statuses	Default 2xx
Active checks	Disabled by default
Passive checks	Enabled by default

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
412	Inspect the returned error details.

Related API operations

• DELETE /upstream-groups/{upstreamGroupId}
• DELETE /upstream-groups/{upstreamGroupId}/upstreams/{upstreamId}
• GET /upstream-groups
• GET /upstream-groups/{upstreamGroupId}
• GET /upstream-groups/{upstreamGroupId}/upstreams
• GET /upstream-groups/{upstreamGroupId}/upstreams/{upstreamId}
• GET /upstream-groups/{upstreamGroupId}/upstreams/{upstreamId}/health-events
• GET /upstream-groups/{upstreamGroupId}/upstreams/{upstreamId}/performance
• GET /upstream-groups/{upstreamGroupId}/upstreams/{upstreamId}/status
• PATCH /upstream-groups/{upstreamGroupId}
• PATCH /upstream-groups/{upstreamGroupId}/upstreams/{upstreamId}
• POST /upstream-groups
• POST /upstream-groups/{upstreamGroupId}/upstreams

API reference

• Delete an upstream group

• Remove a backend server from an upstream group

• List upstream groups associated with your account

• Get an upstream group

• List upstreams (backend servers) in an upstream group

• Get details of a single upstream

• Returns the health check event history for an upstream

• Returns aggregated performance report data for an upstream

• Returns the per-location health check status for an upstream

• Update an upstream group configuration

• Update an upstream's name, health check address, or disabled state

• Creates a new upstream group (backend pool)

• Adds a backend target to an upstream group

• Upstream Groups

Need Help?

Contact your account manager or use the Balancer portal.