Route traffic with groups and routes

You create an HTTP load balancer, connect a group to your origins, attach a domain and add a route.

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.
• An upstream group, control of the site domain and a certificate for HTTPS. Set UPSTREAM_GROUP_ID to your upstream group identifier.

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
GROUP_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_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 'GROUP_ID: ' GROUP_ID
export GROUP_ID

Steps

1. Create the load balancer.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"name":"web"}'

   API reference: Creates a new HTTP load balancer

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

   {
     "code": 200,
     "result": "success",
     "data": {
       "httpLbId": 1
     }
   }

   Set HTTP_LB_ID to the returned httpLbId.

2. Create a group for your origins.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'upstreamGroupId': int(os.environ['UPSTREAM_GROUP_ID']), 'backendPort': 80}))
   PYBODY

   API reference: Creates a new application group within an HTTP load balancer

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

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

   Set GROUP_ID to the returned groupId.

3. Attach your domain.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/domains" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"domain":"example.com"}'

   API reference: Adds a domain to an HTTP 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,
     "result": "success",
     "data": {
       "domainId": 1
     }
   }

4. Add a route for paths beginning with /api/. Lower priority numbers run first.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/routes" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"priority":10,"name":"api","requestExpression":"starts_with(http.request.uri.path, \"/api/\")","requestTimeoutMilliseconds":15000}'

   API reference: Creates a new route for an HTTP 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,
     "result": "success"
   }

5. Read the saved routes.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/routes" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: List routes for an HTTP 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,
     "result": "success"
   }

Verify

Send requests to /api/ and a path outside /api/ with the intended Host and TLS name. Compare the response and origin observations with each route. API success confirms saved configuration; it does not establish live route matching.

Use your configured site domain in this traffic check:

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

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.

Troubleshooting

Symptom	Cause	Fix
Wrong route handles a request	Priority or expression differs from the request	Check Host, method, path, scheme and route order.
HTTPS fails	Domain or certificate is not ready	Check domain assignment and the certificate presented by the site.
Saved configuration differs from traffic	Changes have not reached the serving location	Read back assignments and repeat a controlled request.

Limits and defaults

Setting	Limit or default
Route priority	Required; 1 to 100000000; lower first
Route expression	Maximum 8192 characters
Backend port	1 to 65535
Group algorithm	Default round-robin
Group request timeout	Default 15000 ms; 0 to 3600000
HTTP/2	Enabled by default
HTTP/3	Disabled 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.
409	Resource state conflicts with the operation.
500	The request encounters a server error.
503	The operation is temporarily unavailable.

Related API operations

• DELETE /http-loadbalancers/{httpLbId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/domains/{domainId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/origin-analysis-rules/{originAnalysisRuleId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/basic-auth-users/{userId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/jwt-auth-providers/{providerId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/upstream-bindings/{bindingId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/session-label-rules/{sessionLabelRuleId}
• GET /edges
• GET /http-loadbalancers
• GET /http-loadbalancers/{httpLbId}
• GET /http-loadbalancers/{httpLbId}/groups
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/domains
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/domains/{domainId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/origin-analysis-rules
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/origin-analysis-rules/{originAnalysisRuleId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/basic-auth-users
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/jwt-auth-providers
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/jwt-auth-providers/{providerId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/upstream-bindings
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/session-label-rules
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/session-label-rules/{sessionLabelRuleId}
• PATCH /http-loadbalancers/{httpLbId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/domains/{domainId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/origin-analysis-rules/{originAnalysisRuleId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/jwt-auth-providers/{providerId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/upstream-bindings/{bindingId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/session-label-rules/{sessionLabelRuleId}
• POST /http-loadbalancers
• POST /http-loadbalancers/{httpLbId}/groups
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/domains
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/domains/{domainId}/move
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/origin-analysis-rules
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/basic-auth-users
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/jwt-auth-providers
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/upstream-bindings
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/session-label-rules

API reference

• Delete an HTTP load balancer

• Delete an HTTP LB group

• Remove a domain from an HTTP LB group

• Delete an origin analysis rule for an HTTP group

• Delete a route

• Delete a basic auth user from a route

• Remove a JWT auth provider from a route

• Remove a route upstream binding

• Delete a session label rule from an HTTP group

• List edge targets available to your account

• List HTTP load balancers associated with your account

• Get HTTP load balancer

• List HTTP groups

• Get HTTP group

• List domains for an HTTP group

• Get HTTP group domain

• List origin analysis rules for an HTTP group

• Get origin analysis rule for an HTTP group

• List routes for an HTTP group

• Get HTTP group route

• List basic auth users for a route

• List JWT auth providers for a route

• Get JWT auth provider for a route

• List upstream bindings for a route

• List session label rules for an HTTP group

• Get session label rule for an HTTP group

• Update HTTP load balancer settings

• Update an HTTP group configuration

• Update an HTTP group domain configuration

• Update an origin analysis rule for an HTTP group

• Update an HTTP group route configuration

• Update a JWT auth provider configuration

• Update a route upstream binding

• Update a session label rule for an HTTP group

• Creates a new HTTP load balancer

• Creates a new application group within an HTTP load balancer

• Adds a domain to an HTTP group

• Move an HTTP domain to another group in the same account

• Create an origin analysis rule for an HTTP group

• Creates a new route for an HTTP group

• Adds a basic auth user to a route

• Creates a JWT auth provider on a route

• Adds an upstream binding to a route for per-route traffic splitting

• Create a session label rule for an HTTP group

• HTTP Load Balancers

• Groups and Routes

• Edges

Need Help?

Contact your account manager or use the Balancer portal.