Networking

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Add target to pool

POST
/scopes/{scopeId}/network/load-balancers/{loadBalancerId}/targets

Adds a backend target (member) to one of the load balancer's pools via the "Add target" dialog: target name, destination pool (poolId), IP address and port (defaulting to 8080). The member is created with weight 1 and backupMember=false unless overridden, begins receiving health checks from the pool's monitor, and appears in the Targets tab and the pool's members array. Validation: parent load balancer must exist in the scope (404 NOT_FOUND); poolId must reference an existing pool of this LB — the dialog is disabled when no pools exist, and the backend rejects an unknown pool with 404; name and address non-empty, address a valid IP reachable from the VIP subnet and port an integer 1-65535 (422 VALIDATION_FAILED); the same address:port pair must not already be a member of the target pool (409 CONFLICT); weight a positive integer when supplied (422). Async & state: Asynchronous — returns 202 with the LbMember resource; initial operating state reflects the first health probe (ONLINE once the monitor passes, NO_MONITOR when the pool has no monitor) while the parent LB passes through provisioning=PENDING_UPDATE → ACTIVE. resource.updated SSE frames (kind "network.load_balancer", patch to pools[].members and the healthy-target counters) refresh the UI. Errors: 401 unauthenticated; 403 caller lacks contributor/owner/admin; 404 unknown LB or pool; 409 duplicate address:port in the pool or LB state conflict; 422 invalid name/address/port/weight; 500 backend failure. Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the originally created member instead of registering the target twice.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

loadBalancerId*string

Header Parameters

Idempotency-Key*string

Required: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.

Formatuuid

Request Body

application/json
  1. body

"Add target" dialog payload; weight defaults to 1 and backupMember to false.

name*string

Target name, e.g. web-prod-03.

Match^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$
Length1 <= length <= 255
poolId*string

Id of the destination pool on this load balancer.

address*string

Backend IP address, e.g. 10.0.1.23.

port?integer
Default8080
weight?integer
Default1
backupMember?boolean
Defaultfalse

Response Body

Target registration accepted; member returned while health checks start.

application/json
  1. response

Backend member (target) of a load-balancer pool.

id*string
name*string
address*string

Backend IP address.

port*integer
weight*integer
operating*LbOperating

Operating (health) state of a load balancer or one of its sub-resources.

Value in"ONLINE""DEGRADED""OFFLINE""ERROR""NO_MONITOR"
backupMember*boolean
curl -X POST "https://example.com/scopes/string/network/load-balancers/string/targets" \  -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "poolId": "string",    "address": "string"  }'
{  "id": "string",  "name": "string",  "address": "string",  "port": 0,  "weight": 0,  "operating": "ONLINE",  "backupMember": true}