lb.services.add

Add a service (listener)

POST /lb/api/load-balancers/{id}/servicesIAM lb:AddServiceChanges state

An https service terminates TLS and needs a certificate: either `domains` (Deutsche Cloud issues it over DNS-01, so every name must be in one of your hosted zones; the service is created at the provider once it is issued, about a minute, and `certificateStatus` goes pending → active) or `certificatePem` + `privateKeyPem` (attached at once). A name outside your hosted zones is refused (400): the certificate authority cannot check it over HTTP, because port 80 goes to your targets.

Request syntax

POST /lb/api/load-balancers/{id}/services
{
  "protocol": "enum",
  "sourcePort": "number",
  "destinationPort": "number",
  "proxyprotocol": "boolean",
  "healthCheckPath": "string",
  "domains": "array of string",
  "certificatePem": "string",
  "privateKeyPem": "string",
  "redirectHttp": "boolean",
  "healthCheckProtocol": "enum",
  "healthCheckInterval": "number",
  "healthCheckTimeout": "number",
  "healthCheckRetries": "number",
  "stickySessions": "boolean",
  "stickyCookieName": "string",
  "stickyCookieLifetime": "number",
  "healthCheckPort": "number",
  "closeOnUnhealthy": "boolean"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • protocolRequired

    enum

    What the load balancer speaks on sourcePort. https terminates TLS and needs a certificate (domains, or certificatePem + privateKeyPem), except on an application load balancer, whose platform name is served by the fleet’s own certificate when neither is given. tcp is refused (400) on application load balancers

    One of: tcp, http, https

  • sourcePortRequired

    number

    Port the load balancer listens on, 1–65535; one service per port (400 when taken, and port 80 is taken by an https service that redirects). application: http on 80 and https on 443 only (400). dedicated: not 22, 9901 or 9902 (400), at most 10 services. The console’s form starts on 80 (443 for https)

    Constraints: integer, 1-65535

  • destinationPortRequired

    number

    Port on the targets traffic is sent to, 1–65535. The console’s form starts on 80

    Constraints: integer, 1-65535

  • proxyprotocolOptional

    boolean

    Prepend the PROXY protocol header to each connection to a target. Default false. Refused (400) on application load balancers, whose targets get X-Forwarded-For and X-Real-IP instead

  • healthCheckPathOptional

    string

    HTTP path probed for health when healthCheckProtocol is http (default `/`). Not checked here; `services update` requires a leading / and at most 256 characters

  • domainsOptional

    array of string

    https only (400 otherwise): names for a certificate Deutsche Cloud issues and renews over DNS-01, at most 50, each up to 253 characters; lower-cased and de-duplicated. Every name (wildcards allowed) must be in one of your Deutsche Cloud hosted zones (400). Not together with certificatePem (400). application: at most 10 names including its platform name, and none another load balancer on the fleet already serves (400)

    Constraints: 1-253 chars

  • certificatePemOptional

    string

    https only, instead of domains: your certificate in PEM, leaf first, then the chain; at most 64 KiB. Must parse and match privateKeyPem (400). Never renewed by the platform

    Constraints: max 65536 chars

  • privateKeyPemOptional

    string

    https, with certificatePem (400 with one but not the other): its unencrypted private key in PEM, at most 16 KiB. lb11/lb21/lb31: handed to the provider and not stored by Deutsche Cloud. application and dedicated: stored sealed under the KMS master key, opened only to configure the fleet

    Constraints: max 16384 chars

  • redirectHttpOptional

    boolean

    https only: answer port 80 with a 301 redirect to https. Port 80 must be free and the service may not itself listen on 80 (400). Default false in the API; the console’s form ticks it

  • healthCheckProtocolOptional

    enum

    http (default): GET the health-check path, 2xx/3xx is healthy. tcp: a connection is enough

    One of: http, tcp

  • healthCheckIntervalOptional

    number

    Seconds between health checks (default 15): 3–60 on lb11/lb21/lb31 (400 below 3), 1–60 on application and dedicated load balancers

    Constraints: integer, 1-60

  • healthCheckTimeoutOptional

    number

    Seconds a health check may take, 1–60 and at most the interval (400 above it; default 10)

    Constraints: integer, 1-60

  • healthCheckRetriesOptional

    number

    Failed checks in a row before a target stops taking traffic (0–5, default 3). A dead target keeps traffic for about interval × (retries + 1)

    Constraints: integer, 0-5

  • stickySessionsOptional

    boolean

    http/https: pin each client to one target with a cookie the load balancer sets (default false; refused with 400 on a tcp service)

  • stickyCookieNameOptional

    string

    Name of the sticky-session cookie (default EWSLB)

    Constraints: /^[A-Za-z0-9_-]{1,64}$/

  • stickyCookieLifetimeOptional

    number

    Seconds the sticky-session cookie lasts (60 s – 7 days, default 300)

    Constraints: integer, 60-604800

  • healthCheckPortOptional

    number

    dedicated type only (400 on the others): the port the health check asks, 1–65535 (default: the target port), e.g. an HTTP health endpoint next to a tcp service

    Constraints: integer, 1-65535

  • closeOnUnhealthyOptional

    boolean

    dedicated tcp only (400 on the other types and protocols): close open connections to a target whose health check answers no (an HTTP status outside 2xx/3xx, retries times in a row); a check that only times out closes nothing. For a database primary endpoint. Default false

Response

201 with the service: id, lbId, protocol, sourcePort, destinationPort, proxyprotocol, the health-check and sticky settings with their defaults filled in, domains, httpRedirectHttp, certificateSource, certificateStatus (`pending` with domains, `active` once an uploaded certificate is attached), certificateNotAfter, … . 409 when an uploaded certificate is sent to an lb11/lb21/lb31 still provisioning; 502 when the provider refuses the uploaded certificate. A load balancer another service owns (a Kubernetes Service, a database endpoint) is refused with 409: change it through its owner.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow lb:AddService on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud lb services add id --protocol tcp --source-port 1 --destination-port 1

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_lb_services_add.