17. Managed Load Balancer
A Managed load balancer works as the network level frontend of customer application by directing connections to the backend servers.
The Managed load balancer API allows customer to manage their services. Managed load balancers are available in every UpCloud zone. The API requests and responses payload are in JSON format only.
API follows JSON Merge Patch semantics. Note when modifying nested structures payload should contain entire array, which in a sense is PUT within PATCH for them.
JSON Merge Patch uses null to explicitly indicate property deletion while absent properties are ignored, i.e. not modified.
It is recommended to use the hostnames of your load balancer when directing your domain to it. This ensures utilization of all addresses that the load balancer might possess.
For the subdomains of your domain, use CNAME. For the primary domain, you might need to use ALIAS, or whatever is supported by your DNS provider.
List plans
Returns a list of available load balancer plans.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
Normal response
[
{
"name": "development",
"per_server_max_sessions": 10000,
"server_number": 1
},
{
"name": "production",
"per_server_max_sessions": 50000,
"server_number": 2
}
]
Get plan details
Returns load balancer plan details by given {name}.
Request
Normal response
Create service
Creates a new load balancer service.
Request
{
"name": "example-service",
"plan": "development",
"zone": "fi-hel1",
"configured_status": "started",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"networks": [
{
"name": "example-network-1",
"type": "public",
"family": "IPv4"
},
{
"name": "example-network-2",
"type": "private",
"family": "IPv4",
"uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
}
],
"frontends": [
{
"name": "example-frontend",
"mode": "http",
"port": 443,
"default_backend": "example-backend-1",
"networks": [
{
"name": "example-network-1"
}
],
"rules": [
{
"name": "example-rule-1",
"priority": 100,
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
]
}
],
"tls_configs": [
{
"name": "example-tls-config",
"certificate_bundle_uuid": "0a73c569-a2d1-481a-917f-b0fdafd78136"
}
],
"properties": {
"timeout_client": 5,
"inbound_proxy_protocol": false
}
}
],
"backends": [
{
"name": "example-backend-1",
"members": [
{
"name": "example-member-1",
"ip": "172.16.1.4",
"port": 8000,
"type": "static",
"weight": 100,
"max_sessions": 1000,
"enabled": true
},
{
"name": "example-member-2",
"ip": "172.16.1.6",
"port": 8080,
"type": "static",
"weight": 50,
"max_sessions": 500,
"enabled": true,
"backup": false
}
],
"properties": {
"timeout_server": 10,
"timeout_tunnel": 3600,
"outbound_proxy_protocol": "",
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_interval": 10,
"health_check_fall": 5,
"health_check_rise": 5,
"health_check_url": "http://somehost/health",
"health_check_expected_status": 200,
"sticky_session_cookie_name": "x-session",
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
}
},
{
"name": "example-backend-2",
"resolver": "example-resolver",
"tls_configs": [],
"members": [
{
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"max_sessions": 1000,
"weight": 100,
"enabled": true
}
]
}
],
"resolvers": [
{
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"cache_valid": 180,
"cache_invalid": 10
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the service must be unique within customer account. |
| plan | A valid plan identifier, e.g. development |
yes | Plan which the service will have, see plans. |
| zone | A valid zone identifier, e.g. fi-hel1 |
yes | Zone in which the service will be hosted, e.g. fi-hel1. |
| configured_status | started / stopped |
yes | Service status managed by the customer. |
| networks | An array of 1-8 network objects | yes | Attached Networks from where traffic consumed and routed. Private networks must reside in loadbalancer zone. |
| frontends | An array of 0-100 frontend objects | no | Frontends receive the traffic before dispatching it to the backends. |
| backends | An array of 0-100 backend objects | no | Backends are groups of customer servers whose traffic should be balanced. |
| resolvers | An array of 0-100 resolver objects | no | Domain Name Resolvers must be configured in case of customer uses dynamic type members |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
| maintenance_dow | A valid day of the week in lowercase monday/tuesday/wednesday/thursday/friday/saturday/sunday |
no | The day of the week on which maintenance will be performed. If not provided, we will randomly select a weekend day. |
| maintenance_time | A valid time format in UTC HH:MM:SSZ |
no | The time at which the maintenance will begin in UTC. A 2-hour timeframe has been allocated for maintenance. During this period, the multi-node production plans will not experience any downtime, while the one-node plans will have a downtime of 1-2 minutes. If not provided, we will randomly select an off-peak time. |
| network_uuid | A valid network identifier in UUID format | no | (Deprecated) Private network UUID where traffic will be routed. Must reside in loadbalancer zone. The field will be deprecated soon, please consider using networks field instead. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List services
Returns a list of load balancer services.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
| label | String representation of a label. | no | Filter by label. See labels usage. |
Normal response
[
{
"backends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"backup": false,
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
},
{
"backup": false,
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.6",
"max_sessions": 500,
"name": "example-member-2",
"port": 8080,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 50
}
],
"name": "example-backend-1",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 5,
"health_check_interval": 10,
"health_check_rise": 5,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/health",
"sticky_session_cookie_name": "x-session",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"backup": false,
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "",
"max_sessions": 1000,
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
}
],
"name": "example-backend-2",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "tcp",
"health_check_on_down": "",
"health_check_url": "/",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"resolver": "example-resolver",
"tls_configs": [],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"configured_status": "started",
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"frontends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"default_backend": "example-backend-1",
"mode": "http",
"name": "example-frontend",
"networks": [
{
"name": "example-network-1"
}
],
"port": 443,
"properties": {
"timeout_client": 5
},
"rules": [
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2022-10-04T16:11:14.569638Z",
"matchers": [
{
"type": "path",
"inverse": false,
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"tls_configs": [
{
"certificate_bundle_uuid": "0a73c569-a2d1-481a-917f-b0fdafd78136",
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-tls-config",
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
],
"name": "example-service",
"networks": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"family": "IPv4",
"name": "example-network-1",
"type": "public",
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-2.upcloudlb.com",
"family": "IPv4",
"name": "example-network-2",
"type": "private",
"updated_at": "2022-10-04T16:11:14.569638Z",
"uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
}
],
"nodes": [
{
"networks": [
{
"ip_addresses": [
{
"address": "100.127.5.146",
"listen": true
}
],
"name": "example-network-1",
"type": "public"
},
{
"ip_addresses": [
{
"address": "172.16.1.44",
"listen": false
},
{
"address": "172.16.1.45",
"listen": true
}
],
"name": "example-network-2",
"type": "private"
}
],
"operational_state": "running"
}
],
"operational_state": "pending",
"plan": "development",
"resolvers": [
{
"cache_invalid": 10,
"cache_valid": 180,
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:36:09.933249Z",
"uuid": "0a498284-629e-4629-a55d-0415a6e89dda",
"zone": "fi-hel1"
}
]
Notes:
- Please see service configured statuses and operational states description.
Get service details
Returns load balancer service details by given {service_uuid}.
Request
Normal response
{
"backends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"backup": false,
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
},
{
"backup": false,
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.6",
"max_sessions": 500,
"name": "example-member-2",
"port": 8080,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 50
}
],
"name": "example-backend-1",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 5,
"health_check_interval": 10,
"health_check_rise": 5,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/health",
"sticky_session_cookie_name": "x-session",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"backup": false,
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "",
"max_sessions": 1000,
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
}
],
"name": "example-backend-2",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "tcp",
"health_check_on_down": "",
"health_check_url": "//:8080",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"resolver": "example-resolver",
"tls_configs": [],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"configured_status": "started",
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"frontends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"default_backend": "example-backend-1",
"mode": "http",
"name": "example-frontend",
"networks": [
{
"name": "example-network-1"
}
],
"port": 443,
"properties": {
"timeout_client": 5
},
"rules": [
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2022-10-04T16:11:14.569638Z",
"matchers": [
{
"type": "path",
"inverse": false,
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"tls_configs": [
{
"certificate_bundle_uuid": "0a73c569-a2d1-481a-917f-b0fdafd78136",
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-tls-config",
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
],
"name": "example-service",
"networks": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"family": "IPv4",
"name": "example-network-1",
"type": "public",
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-2.upcloudlb.com",
"family": "IPv4",
"name": "example-network-2",
"type": "private",
"updated_at": "2022-10-04T16:11:14.569638Z",
"uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
}
],
"nodes": [
{
"networks": [
{
"ip_addresses": [
{
"address": "100.127.5.146",
"listen": true
}
],
"name": "example-network-1",
"type": "public"
},
{
"ip_addresses": [
{
"address": "172.16.1.44",
"listen": false
},
{
"address": "172.16.1.45",
"listen": true
}
],
"name": "example-network-2",
"type": "private"
}
],
"operational_state": "running"
}
],
"operational_state": "pending",
"plan": "development",
"resolvers": [
{
"cache_invalid": 10,
"cache_valid": 180,
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:36:09.933249Z",
"uuid": "0a498284-629e-4629-a55d-0415a6e89dda",
"zone": "fi-hel1"
}
Notes:
- Please see service configured statuses and operational states description.
Replace service
Replaces existing load balancer service by given {service_uuid}.
Request
{
"name": "example-service",
"plan": "development",
"configured_status": "started",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"frontends": [
{
"name": "example-frontend",
"mode": "http",
"port": 443,
"default_backend": "example-backend-1",
"networks": [
{
"name": "example-network-1"
}
],
"rules": [
{
"name": "example-rule-1",
"priority": 100,
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
]
}
],
"tls_configs": [
{
"name": "example-tls-config",
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2"
}
],
"properties": {
"timeout_client": 15,
"inbound_proxy_protocol": true
}
}
],
"backends": [
{
"name": "example-backend-1",
"members": [
{
"name": "example-member-1",
"ip": "172.16.1.4",
"port": 8000,
"type": "static",
"weight": 100,
"max_sessions": 1000,
"enabled": true
},
{
"name": "example-member-2",
"ip": "172.16.1.5",
"port": 8080,
"type": "static",
"weight": 50,
"max_sessions": 500,
"enabled": true,
"backup": true
}
],
"properties": {
"timeout_server": 30,
"timeout_tunnel": 3600,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_interval": 20,
"health_check_fall": 3,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_url": "/",
"health_check_expected_status": 200,
"sticky_session_cookie_name": "",
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
}
},
{
"name": "example-backend-2",
"resolver": "example-resolver",
"tls_configs": [],
"members": [
{
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"max_sessions": 1000,
"weight": 100,
"enabled": true
}
]
}
],
"resolvers": [
{
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"cache_valid": 180,
"cache_invalid": 10
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the service must be unique within customer account. |
| plan | A valid plan identifier, e.g. development |
yes | Plan which the service will have, see plans. |
| configured_status | started / stopped |
yes | Service status managed by the customer. |
| maintenance_dow | A valid day of the week in lowercase monday/tuesday/wednesday/thursday/friday/saturday/sunday |
no | The day of the week on which maintenance will be performed. If not provided, we will randomly select a weekend day. |
| maintenance_time | A valid time format in UTC HH:MM:SSZ |
no | The time at which the maintenance will begin in UTC. A 2-hour timeframe has been allocated for maintenance. During this period, the multi-node production plans will not experience any downtime, while the one-node plans will have a downtime of 1-2 minutes. If not provided, we will randomly select an off-peak time. |
| frontends | An array of 0-100 frontend objects | no | Frontends receive the traffic before dispatching it to the backends. |
| backends | An array of 0-100 backend objects | no | Backends are groups of customer servers whose traffic should be balanced. |
| resolvers | An array of 0-100 resolver objects | no | Domain Name Resolvers must be configured in case of customer uses dynamic type members |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Service with provided UUID not found. |
Modify service
Modifies existing load balancer service by given {service_uuid}.
Request
{
"name": "example-service",
"plan": "development",
"configured_status": "started",
"resolvers": [
{
"name": "example-resolver",
"nameservers": [
"172.16.4.12:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 25,
"cache_valid": 360,
"cache_invalid": 10
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the service must be unique within customer account. |
| plan | A valid plan identifier, e.g. development |
no | Plan which the service will have, see plans. |
| configured_status | started / stopped |
no | Service status managed by the customer. |
| maintenance_dow | A valid day of the week in lowercase monday/tuesday/wednesday/thursday/friday/saturday/sunday |
no | The day of the week on which maintenance will be performed. |
| maintenance_time | A valid time format in UTC HH:MM:SSZ |
no | The time at which the maintenance will begin in UTC. A 2-hour timeframe has been allocated for maintenance. During this period, the multi-node production plans will not experience any downtime, while the one-node plans will have a downtime of 1-2 minutes. |
| frontends | An array of 0-100 frontend objects / null |
no | Frontends receive the traffic before dispatching it to the backends. |
| backends | An array of 0-100 backend objects / null |
no | Backends are groups of customer servers whose traffic should be balanced. |
| resolvers | An array of 0-100 resolver objects / null |
no | Domain Name Resolvers must be configured in case of customer uses dynamic type members |
| labels | An array of 0-255 labels objects / null |
no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Service with provided UUID not found. |
Delete service
Deletes existing load balancer service by given {service_uuid}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Service with provided UUID not found. |
Networks
List of network objects should be provided on service creation and cannot be changed later. Loadbalancer could route
traffic to any of the attached networks and listen on networks specified in networks field on a frontend level.
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the network must be unique within the service. |
| type | public / private |
yes | The type of the network. Only one public network can be attached and at least one private network must be attached. |
| family | IPv4 |
yes | Currently only IPv4 network family is supported. |
| uuid | A valid network identifier in UUID format | no | Required for private networks and must reside in loadbalancer zone. For public network the field should be omitted. |
Modify network
Modifies existing service network by given {service_uuid} and {network_name}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the network must be unique within the service. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create frontend
Creates a new service frontend by given {service_uuid}.
Request
{
"name": "example-frontend",
"mode": "http",
"port": 443,
"default_backend": "example-backend",
"networks": [
{
"name": "example-network-1"
}
],
"rules": [
{
"name": "example-rule-1",
"priority": 100,
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
]
}
],
"tls_configs": [
{
"name": "example-tls-config",
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2"
}
],
"properties": {
"timeout_client": 5,
"inbound_proxy_protocol": true
}
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the frontend must be unique within the service. |
| mode | tcp / http |
yes | When load balancer operating in tcp mode it acts as a layer 4 proxy. In http mode it acts as a layer 7 proxy. |
| port | 1-65535 | yes | Port to listen incoming requests |
| default_backend | A valid backend identifier, e.g. example-backend |
yes | The name of the default backend where traffic will be routed. Note, default backend can be overwritten in frontend rules. |
| networks | An array of network objects | yes | Network object contains the name of attached networks on which frontend will be listening. |
| rules | An array of 0-100 rules objects | no | Set of frontend rules |
| tls_configs | An array of 0-1000 TLS configs | no | Set of TLS configs. Only TLS configs with the certificate bundle of type manual/dynamic can be attached to the frontend. |
| properties | Properties object | no | Embedded Frontend properties. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List frontends
Returns a list of available service frontends by given {service_uuid}.
Request
Normal response
[
{
"created_at": "2021-12-07T13:58:30.817272Z",
"default_backend": "example-backend-1",
"mode": "http",
"name": "example-frontend",
"networks": [
{
"name": "example-network-1"
}
],
"port": 443,
"properties": {
"timeout_client": 10
},
"rules": [
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2021-12-07T13:58:30.817272Z",
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-02-11T17:33:08.490581Z"
}
],
"tls_configs": [
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"created_at": "2022-02-11T17:33:08.490581Z",
"name": "example-tls-config",
"updated_at": "2022-02-11T17:33:08.490581Z"
}
],
"updated_at": "2022-02-11T17:33:08.490581Z"
}
]
Get frontend details
Returns service frontend details by given {service_uuid} and {frontend_name}.
Request
Normal response
{
"created_at": "2021-12-07T13:58:30.817272Z",
"default_backend": "example-backend-1",
"mode": "http",
"name": "example-frontend",
"networks": [
{
"name": "example-network-1"
}
],
"port": 443,
"properties": {
"timeout_client": 10
},
"rules": [
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2021-12-07T13:58:30.817272Z",
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-02-11T17:33:08.490581Z"
}
],
"tls_configs": [
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"created_at": "2022-02-11T17:33:08.490581Z",
"name": "example-tls-config",
"updated_at": "2022-02-11T17:33:08.490581Z"
}
],
"updated_at": "2022-02-11T17:33:08.490581Z"
}
Modify frontend
Modifies existing service frontend by given {service_uuid} and {frontend_name}.
Request
{
"name": "example-frontend",
"mode": "http",
"port": 443,
"default_backend": "example-backend",
"properties": {
"timeout_client": 10,
"inbound_proxy_protocol": false
},
"networks": [
{
"name": "example-network-2"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the frontend must be unique within the service. |
| mode | tcp / http |
no | When load balancer operating in tcp mode it acts as a layer 4 proxy. In http mode it acts as a layer 7 proxy. |
| port | 1-65535 | no | Port to listen incoming requests |
| default_backend | A valid backend identifier, e.g. example-backend |
no | The name of the default backend where traffic will be routed. Note, default backend can be overwritten in frontend rules. |
| networks | An array of network objects | no | Network object contains the name of attached networks on which frontend will be listening. |
| rules | An array of 0-100 rules objects / null |
no | Set of frontend rules |
| tls_configs | An array of 0-1000 TLS configs / null |
no | Set of TLS configs. Only TLS configs with the certificate bundle of type manual/dynamic can be attached to the frontend. |
| properties | Properties object | no | Embedded Frontend properties. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Delete frontend
Deletes existing frontend by given {service_uuid} and {frontend_name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create Frontend TLS config
Creates a new TLS config by given {service_uuid} and {frontend_name}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the TLS config must be unique within service frontend. |
| certificate_bundle_uuid | A valid certificate bundle identifier in UUID format | yes | Reference to certificate bundle. Certificate bundles of type manual or dynamic can be attached to frontend tls config. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List Frontend TLS configs
Returns a list of available frontend TLS Config by given {service_uuid} and {frontend_name}.
Request
Normal response
[
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"created_at": "2022-02-11T17:33:08.490581Z",
"name": "example-tls-config-1",
"updated_at": "2022-02-11T17:33:08.490581Z"
},
{
"certificate_bundle_uuid": "c136c429-d18f-4192-b55e-e7b5079dee40",
"created_at": "2021-11-11T11:21:51.121789Z",
"name": "example-tls-config-2",
"updated_at": "2021-11-11T11:21:51.121789Z"
}
]
Get Frontend TLS config details
Returns frontend TLS config details by given {service_uuid}, {frontend_name} and {tls_config_name}.
Request
GET /1.3/load-balancer/{service_uuid}/frontends/{frontend_name}/tls-configs/{tls_config_name} HTTP/1.1
Normal response
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"created_at": "2022-02-11T17:33:08.490581Z",
"name": "example-tls-config",
"updated_at": "2022-02-11T17:33:08.490581Z"
}
Modify Frontend TLS config
Modifies existing TLS config by given {service_uuid}, {frontend_name} and {tls_config_name}.
Request
PATCH /1.3/load-balancer/{service_uuid}/frontends/{frontend_name}/tls-configs/{tls_config_name} HTTP/1.1
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the TLS config must be unique within service frontend. |
| certificate_bundle_uuid | A valid certificate bundle identifier in UUID format | no | Reference to certificate bundle. Certificate bundles of type manual or dynamic can be attached to frontend tls config. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Delete Frontend TLS config
Deletes existing TLS config by given {service_uuid}, {frontend_name} and {tls_config_name}.
Request
DELETE /1.3/load-balancer/{service_uuid}/frontends/{frontend_name}/tls-configs/{tls_config_name} HTTP/1.1
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create rule
Creates a new rule by given {service_uuid} and {frontend_name}.
{
"name": "example-rule-1",
"priority": 100,
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the rule must be unique within customer service. |
| priority | 0-100 | yes | Rule with the higher priority goes first. Rules with the same priority processed in alphabetical order. |
| matching_condition | and / or |
no | Evaluate multiple matchers using this boolean operator. Defaults to and. |
| matchers | An array of 0-40 matcher objects | yes | Set of rule matchers. |
| actions | An array of 1-40 action objects | yes | Set of rule actions. |
Notes:
- if rule has empty
matchersarray, then action applies to all incoming requests.
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List rules
Returns a list of available frontend rules by given {service_uuid} and {frontend_name}.
Request
Normal response
[
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2021-12-07T13:58:30.817272Z",
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-02-11T17:33:08.490581Z"
}
]
Get rule details
Returns frontend rule details by given {service_uuid}, {frontend_name} and {rule_name}.
Request
Normal response
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2021-12-07T13:58:30.817272Z",
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-02-11T17:33:08.490581Z"
}
Replace rule
Replaces existing rule by given {service_uuid}, {frontend_name} and {rule_name}.
{
"name": "example-rule-1",
"priority": 100,
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the rule must be unique within customer service. |
| priority | 0-100 | yes | Rule with the higher priority goes first. Rules with the same priority processed in alphabetical order. |
| matchers | An array of 0-40 matcher objects | yes | Set of rule matchers. |
| actions | An array of 1-40 action objects | yes | Set of rule actions. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Modify rule
Modifies existing rule by given {service_uuid}, {frontend_name} and {rule_name}.
Request
{
"name": "example-rule-1",
"priority": 100,
"matching_condition": "and",
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/new-path"
}
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the rule must be unique within customer service. |
| priority | 0-100 | no | Rule with the higher priority goes first. Rules with the same priority processed in alphabetical order. |
| matching_condition | and / or |
no | Evaluate multiple matchers using this boolean operator. |
| matchers | An array of 0-40 matcher objects / null |
no | Set of rule matchers. |
| actions | An array of 1-40 action objects / null |
no | Set of rule actions. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Delete rule
Deletes existing rule by given {service_uuid}, {frontend_name} and {rule_name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create backend
Creates a new backend by given {service_uuid}.
{
"name": "example-backend-2",
"resolver": "example-resolver",
"members": [
{
"name": "member1.example.com",
"port": 8000,
"type": "dynamic",
"max_sessions": 1000,
"weight": 100,
"enabled": true
},
{
"name": "member2.example.com",
"port": 8000,
"type": "dynamic",
"max_sessions": 1000,
"weight": 100,
"enabled": true
}
],
"properties": {
"timeout_server": 30,
"timeout_tunnel": 3600,
"health_check_type": "tcp",
"health_check_on_down": "",
"health_check_interval": 20,
"health_check_fall": 3,
"health_check_rise": 3,
"sticky_session_cookie_name": "SERVERID",
"outbound_proxy_protocol": "v2",
"tls_enabled": true,
"tls_verify": true,
"tls_use_system_ca": false
},
"tls_configs": [
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"name": "example-tls-config"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the backend must be unique within the service. |
| resolver | A valid resolver identifier, e.g. example-resolver |
no | Domain Name Resolver used with dynamic type members. |
| members | An array of 0-100 member objects | yes | Group of target servers in the customer private network. |
| properties | Properties object | no | Embedded Backend properties. |
| tls_configs | An array of 0-100 TLS configs / null |
no | Set of TLS configs. Only TLS configs with the certificate bundle of type authority/manual can be attached to the backend. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List backends
Returns a list of available service backends by given {service_uuid}.
Request
Normal response
[
{
"created_at": "2021-12-07T13:58:30.817272Z",
"members": [
{
"backup": false,
"created_at": "2022-02-11T16:39:55.321306Z",
"enabled": true,
"ip": "",
"max_sessions": 1000,
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"updated_at": "2022-02-11T17:33:08.490581Z",
"weight": 100
}
],
"name": "example-backend-2",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": true,
"tls_verify": false,
"tls_use_system_ca": true
},
"resolver": "dns",
"tls_configs": [],
"updated_at": "2022-02-11T17:33:08.490581Z"
},
{
"created_at": "2021-12-07T13:58:30.817272Z",
"members": [
{
"backup": false,
"created_at": "2021-12-07T13:58:30.817272Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-02-11T17:33:08.490581Z",
"weight": 100
}
],
"name": "example-backend-1",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"resolver": "",
"tls_configs": [],
"updated_at": "2022-02-11T17:33:08.490581Z"
}
]
Get backend details
Returns service backend details by given {service_uuid} and {backend_name}.
Request
Normal response
{
"created_at": "2021-12-07T13:58:30.817272Z",
"members": [
{
"backup": false,
"created_at": "2021-12-07T13:58:30.817272Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-02-11T17:33:08.490581Z",
"weight": 100
}
],
"name": "example-backend-1",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/health",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"resolver": "dns",
"tls_configs": [
{
"certificate_bundle_uuid": "0a98ddbf-29e3-408c-b081-278a67101f76",
"created_at": "2023-07-28T08:01:11.729382Z",
"name": "ca",
"updated_at": "2023-07-28T08:26:30.436412Z"
}
],
"updated_at": "2022-02-11T17:33:08.490581Z"
}
Modify backend
Modifies existing backend by given {service_uuid} and {backend_name}.
Request
{
"name": "example-backend-2",
"resolver": "example-resolver",
"tls_configs": [],
"properties": {
"timeout_server": 30,
"timeout_tunnel": 3600,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_interval": 20,
"health_check_fall": 3,
"health_check_rise": 2,
"health_check_tls_verify": false,
"health_check_url": "/health",
"health_check_expected_status": 200,
"sticky_session_cookie_name": "SERVERID",
"outbound_proxy_protocol": "v1",
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
}
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the backend must be unique within the service. |
| resolver | A valid resolver identifier, e.g. example-resolver / null |
no | Domain Name Resolver used with dynamic type members. |
| members | An array of 0-100 member objects / null |
no | Group of target servers in the customer private network. |
| properties | Properties object | no | Embedded Backend properties. |
| tls_configs | An array of 0-100 TLS configs / null |
no | Set of TLS configs. Only TLS configs with the certificate bundle of type authority/manual can be attached to the backend. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Delete backend
Deletes existing backend by given {service_uuid} and {backend_name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create static member
Creates a new member by given {service_uuid} and {backend_name}.
{
"name": "example-member-1",
"ip": "172.16.1.4",
"port": 8000,
"type": "static",
"weight": 100,
"max_sessions": 1000,
"enabled": true,
"backup": false
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-254 characters | yes | The name of the member must be unique within the backend. |
| type | static |
yes | Member type. |
| ip | IPv4 / IPv6 address | yes | Server IP address in the customer private network. Note that load balancer members can reside in private networks directly attached to the load balancer or networks reachable via an SDN Virtual Router in those networks. |
| port | 1-65535 | yes | Server port. |
| weight | 0-100 | yes | Used to adjust the member's weight relative to other members. All members will receive a load proportional to their weight relative to the sum of all weights, so the higher the weight, the higher the load. A value of 0 means the member will not participate in load balancing but will still accept persistent connections. |
| max_sessions | 0-500000 | yes | Maximum number of sessions before queueing. |
| enabled | true / false |
yes | Indicates if the member is enabled. Disabled members are excluded from load balancing. |
| backup | true / false |
no | The member is only used in loadbalancing when all other non-backup members are unavailable. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Create dynamic member
Creates a new member by given {service_uuid} and {backend_name}.
{
"name": "member1.example.com",
"type": "dynamic",
"weight": 100,
"max_sessions": 1000,
"enabled": true,
"backup": false
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-254 characters | yes | Fully qualified domain name of the member must be unique within backend. Note that load balancer members can reside in private networks directly attached to the load balancer or networks reachable via an SDN Virtual Router in those networks. |
| type | dynamic |
yes | Member type. |
| ip | IPv4 / IPv6 address | no | Optional fallback IP address in case of failure on DNS resolving. |
| port | 1-65535 | no | Port is optional and can be specified in DNS SRV record. |
| weight | 0-100 | yes | Used to adjust the member's weight relative to other members. All members will receive a load proportional to their weight relative to the sum of all weights, so the higher the weight, the higher the load. A value of 0 means the member will not participate in load balancing but will still accept persistent connections. |
| max_sessions | 0-500000 | yes | Maximum number of sessions before queueing. |
| enabled | true / false |
yes | Indicates if the member is enabled. Disabled members are excluded from load balancing. |
| backup | true / false |
no | The member is only used in loadbalancing when all other non-backup members are unavailable. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List members
Returns a list of available backend members by given {service_uuid} and {backend_name}.
Request
Normal response
[
{
"backup": false,
"created_at": "2022-02-11T16:39:55.321306Z",
"enabled": true,
"ip": "",
"max_sessions": 1000,
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"updated_at": "2022-02-11T17:33:08.490581Z",
"weight": 100
},
{
"backup": false,
"created_at": "2021-12-07T13:58:30.817272Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-02-11T17:33:08.490581Z",
"weight": 100
}
]
Get member details
Returns backend member details by given {service_uuid}, {backend_name} and {member_name}.
Request
Normal response
{
"backup": false,
"created_at": "2021-12-07T13:58:30.817272Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-02-11T17:33:08.490581Z",
"weight": 100
}
Modify static member
Modifies existing member by given {service_uuid}, {backend_name} and {member_name}.
Request
{
"name": "example-member-1",
"ip": "172.16.1.4",
"port": 8000,
"type": "static",
"weight": 100,
"max_sessions": 1000,
"enabled": true,
"backup": true
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-254 characters | no | The name of the member must be unique within backend. |
| type | static |
no | Member type. |
| ip | IPv4 / IPv6 address | no | Server IP address in the customer private network. Note that load balancer members can reside in private networks directly attached to the load balancer or networks reachable via an SDN Virtual Router in those networks. |
| port | 1-65535 | no | Server port. |
| weight | 0-100 | no | Used to adjust the server's weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights, so the higher the weight, the higher the load. A value of 0 means the server will not participate in load balancing but will still accept persistent connections. |
| max_sessions | 0-500000 | no | Maximum number of sessions before queueing. |
| enabled | true / false |
no | Indicates if the member is enabled. Disabled members are excluded from load balancing. |
| backup | true / false |
no | The member is only used in loadbalancing when all other non-backup members are unavailable. |
Normal response
Modify dynamic member
Modifies existing member by given {service_uuid}, {backend_name} and {member_name}.
Request
{
"name": "member1.example.com",
"type": "dynamic",
"weight": 100,
"max_sessions": 1000,
"enabled": true,
"backup": false
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-254 characters | no | Fully qualified domain name of the member must be unique within backend. Note that load balancer members can reside in private networks directly attached to the load balancer or networks reachable via an SDN Virtual Router in those networks. |
| type | dynamic |
no | Member type. |
| ip | IPv4 / IPv6 address | no | Optional fallback IP address in case of failure on DNS resolving. |
| port | 1-65535 | no | Port is optional and can be specified in DNS SRV record. |
| weight | 0-100 | no | Used to adjust the server's weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights, so the higher the weight, the higher the load. A value of 0 means the server will not participate in load balancing but will still accept persistent connections. |
| max_sessions | 0-500000 | no | Maximum number of sessions before queueing. |
| enabled | true / false |
no | Indicates if the member is enabled. Disabled members are excluded from load balancing. |
| backup | true / false |
no | The member is only used in loadbalancing when all other non-backup members are unavailable. |
Normal response
Delete member
Deletes existing member by given {service_uuid}, {backend_name} and {member_name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create Backend TLS config
Creates a new TLS config by given {service_uuid} and {backend_name}.
Request
Notes:
- TLS config with certificate bundle of type
authorityused for backend member verification. - Only one TLS config with certificate bundle of type
manualcan be attached to the backend. It used for client authentication on a backend member server.
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the TLS config must be unique within service backend. |
| certificate_bundle_uuid | A valid certificate bundle identifier in UUID format | yes | Reference to certificate bundle. Certificate bundles of types authotity or manual can be attached to backend tls config. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List Backend TLS configs
Returns a list of available backend TLS Config by given {service_uuid} and {backend_name}.
Request
Normal response
[
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"created_at": "2022-02-11T17:33:08.490581Z",
"name": "example-tls-config-1",
"updated_at": "2022-02-11T17:33:08.490581Z"
},
{
"certificate_bundle_uuid": "c136c429-d18f-4192-b55e-e7b5079dee40",
"created_at": "2021-11-11T11:21:51.121789Z",
"name": "example-tls-config-2",
"updated_at": "2021-11-11T11:21:51.121789Z"
}
]
Get Backend TLS config details
Returns backend TLS config details by given {service_uuid}, {backend_name} and {tls_config_name}.
Request
GET /1.3/load-balancer/{service_uuid}/backends/{backend_name}/tls-configs/{tls_config_name} HTTP/1.1
Normal response
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"created_at": "2022-02-11T17:33:08.490581Z",
"name": "example-tls-config",
"updated_at": "2022-02-11T17:33:08.490581Z"
}
Modify Backend TLS config
Modifies existing TLS config by given {service_uuid}, {backend_name} and {tls_config_name}.
Request
PATCH /1.3/load-balancer/{service_uuid}/backends/{backend_name}/tls-configs/{tls_config_name} HTTP/1.1
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the TLS config must be unique within service backend. |
| certificate_bundle_uuid | A valid certificate bundle identifier in UUID format | no | Reference to certificate bundle. Certificate bundles of type manual or authority can be attached to backend tls config. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Delete Backend TLS config
Deletes existing TLS config by given {service_uuid}, {backend_name} and {tls_config_name}.
Request
DELETE /1.3/load-balancer/{service_uuid}/backends/{backend_name}/tls-configs/{tls_config_name} HTTP/1.1
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create resolver
Creates a new resolver by given {service_uuid}.
Resolver is a DNS server usually residing in a user's private network. It's used to resolve IPs for backend members of
type dynamic.
{
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"cache_valid": 180,
"cache_invalid": 10
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the resolver must be unique within the service. |
| nameservers | An array of 1-10 nameserver IP addresses, e.g. ["172.16.1.4:53", ...] |
yes | Nameserver can reside in public internet or in customer private network. Port is optional, if missing then default 53 will be used. |
| retries | 1-10 | yes | Number of retries on failure. |
| timeout | 1-60 | yes | Timeout for the query in seconds. |
| timeout_retry | 1-60 | yes | Timeout for the query retries in seconds. |
| cache_valid | 1-86400 | yes | Time in seconds to cache valid results. |
| cache_invalid | 1-86400 | yes | Time in seconds to cache invalid results. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List resolvers
Returns a list of available service domain name resolvers by given {service_uuid}.
Request
Normal response
[
{
"cache_invalid": 30,
"cache_valid": 180,
"created_at": "2022-02-11T16:39:55.321306Z",
"name": "example-resolver",
"nameservers": [
"172.16.1.250"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"updated_at": "2022-02-11T17:33:08.490581Z"
}
]
Get resolver details
Returns backend resolver details by given {service_uuid} and {resolver_name}.
Request
Normal response
{
"cache_invalid": 30,
"cache_valid": 180,
"created_at": "2022-02-11T16:39:55.321306Z",
"name": "example-resolver",
"nameservers": [
"172.16.1.250"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"updated_at": "2022-02-11T17:33:08.490581Z"
}
Modify resolver
Modifies existing resolver by given {service_uuid} and {resolver_name}.
Request
{
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"cache_valid": 180,
"cache_invalid": 10
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the resolver must be unique within the service. |
| nameservers | An array of 1-10 nameserver IP addresses, e.g. ["172.16.1.4:53", ...] |
no | Nameserver can reside in public internet or in customer private network. Port is optional, if missing then default 53 will be used. |
| retries | 1-10 | no | Number of retries on failure. |
| timeout | 1-60 | no | Timeout for the query in seconds. |
| timeout_retry | 1-60 | no | Timeout for the query retries in seconds. |
| cache_valid | 1-86400 | no | Time in seconds to cache valid results. |
| cache_invalid | 1-86400 | no | Time in seconds to cache invalid results. |
Normal response
Delete resolver
Deletes existing resolver by given {service_uuid} and {resolver_name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create service label
Creates a new label by given {service_uuid}.
Labels used for service filtering.
Service labels usage examples
Below are some examples of what certain GET requests might look like.
- exact match:
GET /1.3/load-balancer?label=env%3Dstaging - existence:
GET /1.3/load-balancer?label=env - multiple:
GET /1.3/load-balancer?label=env&label=foo%3Dbar
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| key | 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ |
yes | Represents the label identifier. The key is unique within a service. |
| value | 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z |
yes | Represents the label value. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List service labels
Returns a list of available service labels by given {service_uuid}.
Request
Normal response
Get service label details
Returns label details by given {service_uuid} and {key}.
Request
Normal response
Modify service label
Modifies existing label by given {service_uuid} and {key}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| key | 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ |
no | Represents the label identifier. The key is unique within a service. |
| value | 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z / null |
no | Represents the label value. |
Normal response
Delete service label
Deletes existing label by given {service_uuid} and {key}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Get metrics
Returns metrics by given {service_uuid}.
Request
Normal response
{
"backends": [
{
"avg_connection_time_ms": 2,
"avg_queue_time_ms": 0,
"avg_server_response_time_ms": 71,
"avg_total_time_ms": 71,
"connections_waiting": 0,
"created_at": "2022-06-17T14:18:02.846435Z",
"current_sessions": 115,
"members": [
{
"avg_connection_time_ms": 1,
"avg_queue_time_ms": 0,
"avg_server_response_time_ms": 70,
"avg_total_time_ms": 70,
"check_http_code": 200,
"check_status": "http_ok",
"connections_waiting": 0,
"created_at": "2022-06-17T14:18:02.857216Z",
"current_sessions": 65,
"name": "example-member-1",
"session_rate": 51,
"status": "up",
"total_client_aborted": 0,
"total_failed_checks": 0,
"total_failed_checks_transitions": 0,
"total_failed_connections": 0,
"total_http_responses_1xx": 0,
"total_http_responses_2xx": 29471,
"total_http_responses_3xx": 0,
"total_http_responses_4xx": 0,
"total_http_responses_5xx": 0,
"total_http_responses_other": 0,
"total_invalid_responses": 0,
"total_request_bytes": 2505205,
"total_response_bytes": 4951464,
"total_server_aborted": 0,
"total_server_connection_retries": 0,
"total_sessions": 29471,
"updated_at": "2022-06-29T12:26:34.884371Z"
},
{
"avg_connection_time_ms": 2,
"avg_queue_time_ms": 0,
"avg_server_response_time_ms": 72,
"avg_total_time_ms": 73,
"check_http_code": 200,
"check_status": "http_ok",
"connections_waiting": 0,
"created_at": "2022-06-17T14:18:02.857243Z",
"current_sessions": 50,
"name": "example-member-2",
"session_rate": 49,
"status": "up",
"total_client_aborted": 0,
"total_failed_checks": 0,
"total_failed_checks_transitions": 0,
"total_failed_connections": 0,
"total_http_responses_1xx": 0,
"total_http_responses_2xx": 29473,
"total_http_responses_3xx": 0,
"total_http_responses_4xx": 1,
"total_http_responses_5xx": 5,
"total_http_responses_other": 0,
"total_invalid_responses": 0,
"total_request_bytes": 2505715,
"total_response_bytes": 4952978,
"total_server_aborted": 0,
"total_server_connection_retries": 0,
"total_sessions": 29479,
"updated_at": "2022-06-29T12:26:34.884361Z"
}
],
"name": "example-backend-1",
"session_rate": 98,
"total_client_aborted": 0,
"total_failed_checks_transitions": 0,
"total_failed_connections": 0,
"total_http_responses_1xx": 0,
"total_http_responses_2xx": 58942,
"total_http_responses_3xx": 0,
"total_http_responses_4xx": 1,
"total_http_responses_5xx": 7,
"total_http_responses_other": 0,
"total_invalid_responses": 0,
"total_request_bytes": 5010750,
"total_response_bytes": 9904106,
"total_server_aborted": 0,
"total_server_connection_retries": 0,
"total_sessions": 58951,
"updated_at": "2022-06-29T12:26:34.886954Z"
}
],
"frontends": [
{
"created_at": "2022-06-17T14:18:02.824071Z",
"current_sessions": 115,
"name": "example-frontend-1",
"request_rate": 322,
"session_rate": 98,
"total_denied_requests": 16,
"total_http_requests": 58963,
"total_http_responses_1xx": 0,
"total_http_responses_2xx": 58942,
"total_http_responses_3xx": 0,
"total_http_responses_4xx": 3,
"total_http_responses_5xx": 7,
"total_http_responses_other": 10,
"total_invalid_requests": 0,
"total_request_bytes": 5012102,
"total_response_bytes": 9904500,
"total_sessions": 58967,
"updated_at": "2022-06-29T12:26:34.867576Z"
}
]
}
Attributes
| Attribute | Value | Object | Description |
|---|---|---|---|
| name | 1-64 characters | frontend / backend / member | The Name of the object. |
| avg_connection_time_ms | >= 0 | backend / member | The average connect time in ms over the 1024 last requests. |
| avg_queue_time_ms | >= 0 | backend / member | The average queue time in ms over the 1024 last requests. |
| avg_server_response_time_ms | >= 0 | backend / member | The average response time in ms over the 1024 last requests. |
| avg_total_time_ms | >= 0 | backend / member | Total request+response time in ms, averaged over the 1024 last requests. |
| status | up / down / maintenance |
member | Current member state. |
| check_http_code | 100-599 | member | HTTP Status Code of last health check of type http (see backend properties). |
| check_status | unknown / initializing / socket_error / tcp_ok / tcp_timeout / tcp_connection_error / tls_ok / tls_timeout / tls_protocol_error / http_ok / http_timeout / http_protocol_error / http_response_error |
member | Status of last health check. |
| connections_waiting | >= 0 | backend / member | Current number of connections waiting in the queue. |
| current_sessions | >= 0 | frontend / backend / member | Current number of sessions on the frontend, backend or member. |
| request_rate | >= 0 | frontend | HTTP requests per second over last elapsed second. |
| session_rate | >= 0 | frontend / backend / member | Total number of sessions per second over last elapsed second. |
| total_client_aborted | >= 0 | backend / member | Total number of requests or connections aborted by the client. |
| total_failed_checks | >= 0 | member | Total number of failed health checks. |
| total_failed_checks_transitions | >= 0 | backend / member | Total number of failed health checks causing up to down member transitions. |
| total_failed_connections | >= 0 | backend / member | Total number of failed connections to member. |
| total_http_responses_1xx | >= 0 | frontend / backend / member | Total number of HTTP responses with status 100-199. |
| total_http_responses_2xx | >= 0 | frontend / backend / member | Total number of HTTP responses with status 200-299. |
| total_http_responses_3xx | >= 0 | frontend / backend / member | Total number of HTTP responses with status 300-399. |
| total_http_responses_4xx | >= 0 | frontend / backend / member | Total number of HTTP responses with status 400-499. |
| total_http_responses_5xx | >= 0 | frontend / backend / member | Total number of HTTP responses with status 500-599. |
| total_http_responses_other | >= 0 | frontend / backend / member | Total number of HTTP responses with status <100, >599. |
| total_invalid_requests | >= 0 | frontend | Total number of invalid requests. |
| total_invalid_responses | >= 0 | backend / member | Total number of invalid responses. |
| total_request_bytes | >= 0 | frontend / backend / member | Total number of request bytes. |
| total_response_bytes | >= 0 | frontend / backend / member | Total number of response bytes. |
| total_server_aborted | >= 0 | backend / member | Total number of requests or connections aborted by the server. |
| total_server_connection_retries | >= 0 | backend / member | Total number of server connection retries. |
| total_sessions | >= 0 | frontend / backend / member | Total number of sessions. |
| total_http_requests | >= 0 | frontend | Total number of HTTP requests. |
| total_denied_requests | >= 0 | frontend | Total number of denied requests. |
| created_at | datetime | frontend / backend / member | Date and time when first metrics sample collected. |
| updated_at | datetime | frontend / backend / member | Date and time when latest metrics sample collected. |
Get frontend metric series
Returns the frontend metric series via the given {service_uuid}, and {frontend_name}.
Request
Query Parameters
| Attribute | Accepted Values | Constraints | Default Value | Required | Description |
|---|---|---|---|---|---|
| interval | Time formats: m, h, mh. Examples: 5m, 1h, 1h10m. |
Min: 1min, Max: 24hr, and rounded to the nearest minute. |
10m |
no | Metrics aggregation interval. |
| to | Example: 2024-02-07T07:20:00Z, Format: (ISO 8601) |
Must be greater than from |
current time | no | End of the time range for which to return metrics. |
| from | Example: 2024-02-06T07:20:00Z, Format: (ISO 8601) |
Must be less than to |
24 hours ago | no | Beginning of the time range for which to return metrics. |
| sort | start_at, or -start_at |
Must only be: start_at, or -start_at |
start_at |
no | Metric sort order. |
Error response
| Http status | Accepted Values | Default Value |
|---|---|---|
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Normal response
[
{
"denied_connections": 0,
"denied_requests": 0,
"denied_responses": 0,
"denied_sessions": 0,
"end_at": "2024-02-06T15:00:00Z",
"frontends": [
"my-frontend-1"
],
"http_requests": 0,
"http_responses_1xx": 0,
"http_responses_2xx": 0,
"http_responses_3xx": 0,
"http_responses_4xx": 0,
"http_responses_5xx": 0,
"http_responses_other": 0,
"intercepted_requests": 0,
"invalid_requests": 0,
"request_bytes": 0,
"response_bytes": 0,
"sessions": 0,
"start_at": "2024-02-06T14:50:00Z"
}
]
Attributes
| Attribute | Value | Description |
|---|---|---|
| denied_connections | >= 0 | Total number of denied connections. |
| denied_requests | >= 0 | Total number of denied requests. |
| denied_responses | >= 0 | Total number of denied responses. |
| denied_sessions | >= 0 | Total number of denied sessions. |
| end_at | datetime | Date and time when the last metrics sample was collected. |
| frontends | An array of 0-100 frontend objects | List of frontend names. |
| http_requests | >= 0 | Total number of HTTP requests. |
| http_responses_1xx | >= 0 | Total number of HTTP 1XX responses. |
| http_responses_2xx | >= 0 | Total number of HTTP 2XX responses. |
| http_responses_3xx | >= 0 | Total number of HTTP 3XX responses. |
| http_responses_4xx | >= 0 | Total number of HTTP 4XX responses. |
| http_responses_5xx | >= 0 | Total number of HTTP 5XX responses. |
| http_responses_other | >= 0 | Total number of other HTTP responses. |
| intercepted_requests | >= 0 | Total number of intercepted requests. |
| invalid_requests | >= 0 | Total number of invalid requests. |
| request_bytes | >= 0 | Total number of request bytes. |
| response_bytes | >= 0 | Total number of response bytes. |
| sessions | >= 0 | Total number of sessions. |
| start_at | datetime | Date and time when the first metrics sample was collected, formatted as RFC 3339 timestamp. |
Get combined frontend metric series
Returns the combined frontend metric series by the given {service_uuid}.
Request
Query Parameters
| Attribute | Accepted Values | Constraints | Default Value | Required | Description |
|---|---|---|---|---|---|
| interval | Time formats: m, h, mh. Examples: 5m, 1h, 1h10m. |
Min: 1min, Max: 24hr, and rounded to the nearest minute. |
10m |
no | Metrics aggregation interval. |
| to | Example: 2024-02-07T07:20:00Z, Format: (ISO 8601) |
Must be greater than from |
current time | no | End of the time range for which to return metrics. |
| from | Example: 2024-02-06T07:20:00Z, Format: (ISO 8601) |
Must be less than to |
24 hours ago | no | Beginning of the time range for which to return metrics. |
| sort | start_at, or -start_at |
Must only be: start_at, or -start_at |
start_at |
no | Metric sort order. |
Error response
| Http status | Accepted Values | Default Value |
|---|---|---|
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Normal response
[
{
"denied_connections": 0,
"denied_requests": 0,
"denied_responses": 0,
"denied_sessions": 0,
"end_at": "2024-02-06T15:00:00Z",
"frontends": [
"my-frontend-1"
],
"http_requests": 0,
"http_responses_1xx": 0,
"http_responses_2xx": 0,
"http_responses_3xx": 0,
"http_responses_4xx": 0,
"http_responses_5xx": 0,
"http_responses_other": 0,
"intercepted_requests": 0,
"invalid_requests": 0,
"request_bytes": 0,
"response_bytes": 0,
"sessions": 0,
"start_at": "2024-02-06T14:50:00Z"
}
]
Attributes
| Attribute | Value | Description |
|---|---|---|
| denied_connections | >= 0 | Total number of denied connections. |
| denied_requests | >= 0 | Total number of denied requests. |
| denied_responses | >= 0 | Total number of denied responses. |
| denied_sessions | >= 0 | Total number of denied sessions. |
| end_at | datetime | Date and time when the last metrics sample was collected. |
| frontends | An array of 0-100 frontend objects | List of frontend names. |
| http_requests | >= 0 | Total number of HTTP requests. |
| http_responses_1xx | >= 0 | Total number of HTTP 1XX responses. |
| http_responses_2xx | >= 0 | Total number of HTTP 2XX responses. |
| http_responses_3xx | >= 0 | Total number of HTTP 3XX responses. |
| http_responses_4xx | >= 0 | Total number of HTTP 4XX responses. |
| http_responses_5xx | >= 0 | Total number of HTTP 5XX responses. |
| http_responses_other | >= 0 | Total number of other HTTP responses. |
| intercepted_requests | >= 0 | Total number of intercepted requests. |
| invalid_requests | >= 0 | Total number of invalid requests. |
| request_bytes | >= 0 | Total number of request bytes. |
| response_bytes | >= 0 | Total number of response bytes. |
| sessions | >= 0 | Total number of sessions. |
| start_at | datetime | Date and time when the first metrics sample was collected, formatted as RFC 3339 timestamp. |
Get backend metric series
Returns the backend metric series via the given {service_uuid}, and {backend_name}.
Request
Query Parameters
| Attribute | Accepted Values | Constraints | Default Value | Required | Description |
|---|---|---|---|---|---|
| interval | Time formats: m, h, mh. Examples: 5m, 1h, 1h10m. |
Min: 1min, Max: 24hr, and rounded to the nearest minute. |
10m |
no | Metrics aggregation interval. |
| to | Example: 2024-02-07T07:20:00Z, Format: (ISO 8601) |
Must be greater than from |
current time | no | End of the time range for which to return metrics. |
| from | Example: 2024-02-06T07:20:00Z, Format: (ISO 8601) |
Must be less than to |
24 hours ago | no | Beginning of the time range for which to return metrics. |
| sort | start_at, or -start_at |
Must only be: start_at, or -start_at |
start_at |
no | Metric sort order. |
Error response
| Http status | Accepted Values | Default Value |
|---|---|---|
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Normal response
[
{
"backends": [
"my-backend-1"
],
"client_aborted": 0,
"denied_responses": 0,
"downtime_s": 0,
"end_at": "2024-02-07T07:20:00Z",
"failed_checks_transitions": 0,
"failed_connections": 0,
"http_responses_1xx": 0,
"http_responses_2xx": 2,
"http_responses_3xx": 0,
"http_responses_4xx": 2,
"http_responses_5xx": 0,
"http_responses_other": 0,
"invalid_responses": 0,
"request_bytes": 0,
"response_bytes": 0,
"routed_requests": 0,
"server_aborted": 0,
"server_connection_retries": 0,
"server_redispatches": 0,
"sessions": 0,
"start_at": "2024-02-07T07:10:00Z"
}
]
Attributes
| Attribute | Value | Description |
|---|---|---|
| backends | An array of 0-100 backend objects | List of backend names. |
| client_aborted | >= 0 | Total number of client-aborted connections. |
| denied_responses | >= 0 | Total number of denied responses. |
| downtime_s | >= 0 | Total downtime in seconds. |
| end_at | datetime | Date and time when the last metrics sample was collected. |
| failed_checks_transitions | >= 0 | Total number of failed checks transitions. |
| failed_connections | >= 0 | Total number of failed connections. |
| http_responses_1xx | >= 0 | Total number of HTTP 1XX responses. |
| http_responses_2xx | >= 0 | Total number of HTTP 2XX responses. |
| http_responses_3xx | >= 0 | Total number of HTTP 3XX responses. |
| http_responses_4xx | >= 0 | Total number of HTTP 4XX responses. |
| http_responses_5xx | >= 0 | Total number of HTTP 5XX responses. |
| http_responses_other | >= 0 | Total number of other HTTP responses. |
| invalid_responses | >= 0 | Total number of invalid responses. |
| request_bytes | >= 0 | Total number of request bytes. |
| response_bytes | >= 0 | Total number of response bytes. |
| routed_requests | >= 0 | Total number of routed requests. |
| server_aborted | >= 0 | Total number of server-aborted connections. |
| server_connection_retries | >= 0 | Total number of server connection retries. |
| server_redispatches | >= 0 | Total number of server redispatches. |
| sessions | >= 0 | Total number of sessions. |
| start_at | datetime | Date and time when the first metrics sample was collected, formatted as RFC 3339 timestamp. |
Get combined backend metric series
Returns the combined backend metric series by the given {service_uuid}.
Request
Query Parameters
| Attribute | Accepted Values | Constraints | Default Value | Required | Description |
|---|---|---|---|---|---|
| interval | Time formats: m, h, mh. Examples: 5m, 1h, 1h10m. |
Min: 1min, Max: 24hr, and rounded to the nearest minute. |
10m |
no | Metrics aggregation interval. |
| to | Example: 2024-02-07T07:20:00Z, Format: (ISO 8601) |
Must be greater than from |
current time | no | End of the time range for which to return metrics. |
| from | Example: 2024-02-06T07:20:00Z, Format: (ISO 8601) |
Must be less than to |
24 hours ago | no | Beginning of the time range for which to return metrics. |
| sort | start_at, or -start_at |
Must only be: start_at, or -start_at |
start_at |
no | Metric sort order. |
Error response
| Http status | Accepted Values | Default Value |
|---|---|---|
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Normal response
[
{
"backends": [
"my-backend-1"
],
"client_aborted": 0,
"denied_responses": 0,
"downtime_s": 0,
"end_at": "2024-02-07T07:20:00Z",
"failed_checks_transitions": 0,
"failed_connections": 0,
"http_responses_1xx": 0,
"http_responses_2xx": 2,
"http_responses_3xx": 0,
"http_responses_4xx": 2,
"http_responses_5xx": 0,
"http_responses_other": 0,
"invalid_responses": 0,
"request_bytes": 0,
"response_bytes": 0,
"routed_requests": 0,
"server_aborted": 0,
"server_connection_retries": 0,
"server_redispatches": 0,
"sessions": 0,
"start_at": "2024-02-07T07:10:00Z"
}
]
Attributes
| Attribute | Value | Description |
|---|---|---|
| backends | An array of 0-100 backend objects | List of backend names. |
| client_aborted | >= 0 | Total number of client-aborted connections. |
| denied_responses | >= 0 | Total number of denied responses. |
| downtime_s | >= 0 | Total downtime in seconds. |
| end_at | datetime | Date and time when the last metrics sample was collected. |
| failed_checks_transitions | >= 0 | Total number of failed checks transitions. |
| failed_connections | >= 0 | Total number of failed connections. |
| http_responses_1xx | >= 0 | Total number of HTTP 1XX responses. |
| http_responses_2xx | >= 0 | Total number of HTTP 2XX responses. |
| http_responses_3xx | >= 0 | Total number of HTTP 3XX responses. |
| http_responses_4xx | >= 0 | Total number of HTTP 4XX responses. |
| http_responses_5xx | >= 0 | Total number of HTTP 5XX responses. |
| http_responses_other | >= 0 | Total number of other HTTP responses. |
| invalid_responses | >= 0 | Total number of invalid responses. |
| request_bytes | >= 0 | Total number of request bytes. |
| response_bytes | >= 0 | Total number of response bytes. |
| routed_requests | >= 0 | Total number of routed requests. |
| server_aborted | >= 0 | Total number of server-aborted connections. |
| server_connection_retries | >= 0 | Total number of server connection retries. |
| server_redispatches | >= 0 | Total number of server redispatches. |
| sessions | >= 0 | Total number of sessions. |
| start_at | datetime | Date and time when the first metrics sample was collected, formatted as RFC 3339 timestamp. |
Get backend member metric series
Returns the backend members metric series via the given {service_uuid}, {backend_name}, and {member_name}.
Request
GET /1.3/load-balancer/{service_uuid}/metrics/series/backends/{backend_name}/members/{member_name} HTTP/1.1
Query Parameters
| Attribute | Accepted Values | Constraints | Default Value | Required | Description |
|---|---|---|---|---|---|
| interval | Time formats: m, h, mh. Examples: 5m, 1h, 1h10m. |
Min: 1min, Max: 24hr, and rounded to the nearest minute. |
10m |
no | Metrics aggregation interval. |
| to | Example: 2024-02-07T07:20:00Z, Format: (ISO 8601) |
Must be greater than from |
current time | no | End of the time range for which to return metrics. |
| from | Example: 2024-02-06T07:20:00Z, Format: (ISO 8601) |
Must be less than to |
24 hours ago | no | Beginning of the time range for which to return metrics. |
| sort | start_at, or -start_at |
Must only be: start_at, or -start_at |
start_at |
no | Metric sort order. |
Error response
| Http status | Accepted Values | Default Value |
|---|---|---|
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Normal response
[
{
"client_aborted": 0,
"denied_responses": 0,
"end_at": "2024-02-13T14:30:00Z",
"failed_checks": 0,
"failed_checks_transitions": 0,
"failed_connections": 0,
"http_responses_1xx": 0,
"http_responses_2xx": 0,
"http_responses_3xx": 0,
"http_responses_4xx": 0,
"http_responses_5xx": 0,
"http_responses_other": 0,
"invalid_responses": 0,
"members": [
"terraformtest"
],
"request_bytes": 0,
"response_bytes": 0,
"routed_requests": 0,
"server_aborted": 0,
"server_connection_retries": 0,
"server_redispatches": 0,
"sessions": 0,
"start_at": "2024-02-13T14:20:00Z"
}
]
Attributes
| Attribute | Value | Description |
|---|---|---|
| client_aborted | >= 0 | Total number of client-aborted connections. |
| denied_responses | >= 0 | Total number of denied responses. |
| downtime_s | >= 0 | Total downtime in seconds. |
| end_at | datetime | Date and time when the last metrics sample was collected. |
| failed_checks_transitions | >= 0 | Total number of failed checks transitions. |
| failed_connections | >= 0 | Total number of failed connections. |
| http_responses_1xx | >= 0 | Total number of HTTP 1XX responses. |
| http_responses_2xx | >= 0 | Total number of HTTP 2XX responses. |
| http_responses_3xx | >= 0 | Total number of HTTP 3XX responses. |
| http_responses_4xx | >= 0 | Total number of HTTP 4XX responses. |
| http_responses_5xx | >= 0 | Total number of HTTP 5XX responses. |
| http_responses_other | >= 0 | Total number of other HTTP responses. |
| invalid_responses | >= 0 | Total number of invalid responses. |
| members | An array of member names | List of member names. |
| request_bytes | >= 0 | Total number of request bytes. |
| response_bytes | >= 0 | Total number of response bytes. |
| routed_requests | >= 0 | Total number of routed requests. |
| server_aborted | >= 0 | Total number of server-aborted connections. |
| server_connection_retries | >= 0 | Total number of server connection retries. |
| server_redispatches | >= 0 | Total number of server redispatches. |
| sessions | >= 0 | Total number of sessions. |
| start_at | datetime | Date and time when the first metrics sample was collected, formatted as RFC 3339 timestamp. |
Get combined backend members metric series
Returns the combined backend members metric series via the given {service_uuid}, and {backend_name}.
Request
Query Parameters
| Attribute | Accepted Values | Constraints | Default Value | Required | Description |
|---|---|---|---|---|---|
| interval | Time formats: m, h, mh. Examples: 5m, 1h, 1h10m. |
Min: 1min, Max: 24hr, and rounded to the nearest minute. |
10m |
no | Metrics aggregation interval. |
| to | Example: 2024-02-07T07:20:00Z, Format: (ISO 8601) |
Must be greater than from |
current time | no | End of the time range for which to return metrics. |
| from | Example: 2024-02-06T07:20:00Z, Format: (ISO 8601) |
Must be less than to |
24 hours ago | no | Beginning of the time range for which to return metrics. |
| sort | start_at, or -start_at |
Must only be: start_at, or -start_at |
start_at |
no | Metric sort order. |
Error response
| Http status | Accepted Values | Default Value |
|---|---|---|
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Normal response
[
{
"backends": [
"my-backend-1"
],
"client_aborted": 0,
"denied_responses": 0,
"downtime_s": 0,
"end_at": "2024-02-07T07:20:00Z",
"failed_checks_transitions": 0,
"failed_connections": 0,
"http_responses_1xx": 0,
"http_responses_2xx": 2,
"http_responses_3xx": 0,
"http_responses_4xx": 2,
"http_responses_5xx": 0,
"http_responses_other": 0,
"invalid_responses": 0,
"request_bytes": 0,
"response_bytes": 0,
"routed_requests": 0,
"server_aborted": 0,
"server_connection_retries": 0,
"server_redispatches": 0,
"sessions": 0,
"start_at": "2024-02-07T07:10:00Z"
}
]
Attributes
| Attribute | Value | Description |
|---|---|---|
| client_aborted | >= 0 | Total number of client-aborted connections. |
| denied_responses | >= 0 | Total number of denied responses. |
| downtime_s | >= 0 | Total downtime in seconds. |
| end_at | datetime | Date and time when the last metrics sample was collected. |
| failed_checks_transitions | >= 0 | Total number of failed checks transitions. |
| failed_connections | >= 0 | Total number of failed connections. |
| http_responses_1xx | >= 0 | Total number of HTTP 1XX responses. |
| http_responses_2xx | >= 0 | Total number of HTTP 2XX responses. |
| http_responses_3xx | >= 0 | Total number of HTTP 3XX responses. |
| http_responses_4xx | >= 0 | Total number of HTTP 4XX responses. |
| http_responses_5xx | >= 0 | Total number of HTTP 5XX responses. |
| http_responses_other | >= 0 | Total number of other HTTP responses. |
| invalid_responses | >= 0 | Total number of invalid responses. |
| members | An array of member names | List of member names. |
| request_bytes | >= 0 | Total number of request bytes. |
| response_bytes | >= 0 | Total number of response bytes. |
| routed_requests | >= 0 | Total number of routed requests. |
| server_aborted | >= 0 | Total number of server-aborted connections. |
| server_connection_retries | >= 0 | Total number of server connection retries. |
| server_redispatches | >= 0 | Total number of server redispatches. |
| sessions | >= 0 | Total number of sessions. |
| start_at | datetime | Date and time when the first metrics sample was collected, formatted as RFC 3339 timestamp. |
Create manual certificate bundle
Creates a new certificate bundle of manual type.
Can be used:
- to establish TLS connection when attached to the Frontend
- for client authentication on a backend member server when attached to the Backend
{
"name": "example-manual-certificate",
"type": "manual",
"certificate": "LS0LS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNIVENDQWNPZ0F3SUJBZ0lVSWlNbzg1cGd0b25kUmVESU1McVR4YjhncHI0d0NnWUlLb1pJemowRUF3SXcKWkRFTE1Ba0dBMVVFQmhNQ1FWVXhFekFSQmdOVkJBZ01DbE52YldVdFUzUmhkR1V4SVRBZkJnTlZCQW9NR0VsdQpkR1Z5Ym1WMElGZHBaR2RwZEhNZ1VIUjVJRXgwWkRFZE1Cc0dBMVVFQXd3VVpHVjJMblZ3YkdJdWRYQmpiRzkxClpDNWpiMjB3SGhjTk1qRXhNREl5TVRJeE1ETTJXaGNOTXpFeE1ESXdNVEl4TURNMldqQmtNUXN3Q1FZRFZRUUcKRXdKQlZURVRNQkVHQTFVRUNBd0tVMjl0WlMxVGRHRjBaVEVoTUI4R0ExVUVDZ3dZU1c1MFpYSnVaWFFnVjJsawpaMmwwY3lCUWRIa2dUSFJrTVIwd0d3WURWUVFEREJSa1pYWXVkWEJzWWk1MWNHTnNiM1ZrTG1OdmJUQlpNQk1HCkJ5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEEwSUFCQmpVcUgyaVNuMFV2ZkU3UDdkT0QrSDBoKytxUWpnTG9OeWQKSTFwMmkvdlJPZmhMa0hCUjIxZ2JCSUdENjllYU1WWnZ4RWNxVWlKVWYwcmxLU3FzKzIralV6QlJNQjBHQTFVZApEZ1FXQkJTYTFaU3V1NkxJczMrc2lSSUJ5MHRXL3RnamZEQWZCZ05WSFNNRUdEQVdnQlNhMVpTdXU2TElzMytzCmlSSUJ5MHRXL3RnamZEQVBCZ05WSFJNQkFmOEVCVEFEQVFIL01Bb0dDQ3FHU000OUJBTUNBMGdBTUVVQ0lRQ3IKWXA5dHc2TmVXTHZGOGwrWm9rSE9QUzUzaGc2SDM0OHNMSjEvNit4YXN3SWdWVmN6WkFDc3JyUWt3TnVBZEVCeQo5TkxJR1VrWlhqeWgwdVFCS2x4Si9Wdz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=",
"intermediates": "LS0tLS1CRdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJ0VENDQVZ1Z0F4SUJBZ0lSQU5wSDZzV0ZtQzErWkdnUzFMWllVZGN3Q2dZSUtvWkl6ajBFQXdJd0pERU0KTUFvR0ExVUVDaE1EWkdWMk1SUXdFZ1lEVlFRREV3dGtaWFlnVW05dmRDQkRRVEFlRncweU1URXlNRGt4TXpVMwpNREZhRncwek1URXlNRGN4TXpVM01ERmFNQ3d4RERBS0JnTlZCQW9UQTJSbGRqRWNNQm9HQTFVRUF4TVRaR1YyCklFbHVkR1Z5YldWa2FXRjBaU0JEUVRCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkswbGMzNmcKN01TaDJTaXd3MUdDUjkvL3lSODR6S1VuNml6SmdCUkpFTlBxbmNXcjQzTi8rNktJR1EraERaazhRWHZ6RmExYQp2dFloc3JEVGtnRm9EV0tqWmpCa01BNEdBMVVkRHdFQi93UUVBd0lCQmpBU0JnTlZIUk1CQWY4RUNEQUdBUUgvCkFnRUFNQjBHQTFVZERnUVdCQlRWcG44d3hraHZhYVhvajF6c0Rkcmk4eGJuSnpBZkJnTlZIU01FR0RBV2dCU2oKckgwV0pubDdUSUJtc3NESGVveENFTVZyRmpBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlBa3NhUXdPMkFESGhBLwppRVR1SVY1dTlNV3hFTU5BVGlVODFIZjc0cGVhWlFJaEFLMnJDRmhVVnQxbFlzR1o3dFdjWGFHVDhyU1k2cU1YClBmK3dnUXFnNXUyVAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"private_key": "LS0tL1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JR0hBZ0VBTUJNR0J5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEJHMHdhd0lCQVFRZ3NQMzI2RlIxcmNwL0xybmcKNFBCT3BLRjIzSUNaM01GdGNrZFJuWkFESnRlaFJBTkNBQVFZMUtoOW9rcDlGTDN4T3orM1RnL2g5SWZ2cWtJNApDNkRjblNOYWRvdjcwVG40UzVCd1VkdFlHd1NCZyt2WG1qRldiOFJIS2xJaVZIOUs1U2txclB0dgotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg==",
"labels": [
{
"key": "foo",
"value": "bar"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the bundle must be unique within customer account. |
| type | manual |
yes | Certificate bundle type. |
| certificate | Base64 encoded string | yes | Certificate within base64 string must be in PEM format. |
| intermediates | Base64 encoded string | no | Intermediate certificates within base64 string must be in PEM format. |
| private_key | Base64 encoded string | yes | Private key within base64 string must be in PEM format. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Create dynamic certificate bundle
Creates a new certificate bundle of dynamic type.
{
"name": "example-dynamic-certificate",
"type": "dynamic",
"hostnames": [
"example.com",
"app.example.com"
],
"key_type": "rsa",
"labels": [
{
"key": "foo",
"value": "bar"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the bundle must be unique within customer account. |
| type | dynamic |
yes | Certificate bundle type. |
| hostnames | An array of 1-100 hostnames | yes | Certificate hostnames. |
| key_type | rsa / ecdsa |
yes | Private key type. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
Create authority certificate bundle
Creates a new certificate bundle of authority type. Used to verify and authenticate the identity of backend servers when backend TLS enabled (see Backend properties).
{
"name": "example-authority-certificate",
"type": "authority",
"certificate": "LS0LS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNIVENDQWNPZ0F3SUJBZ0lVSWlNbzg1cGd0b25kUmVESU1McVR4YjhncHI0d0NnWUlLb1pJemowRUF3SXcKWkRFTE1Ba0dBMVVFQmhNQ1FWVXhFekFSQmdOVkJBZ01DbE52YldVdFUzUmhkR1V4SVRBZkJnTlZCQW9NR0VsdQpkR1Z5Ym1WMElGZHBaR2RwZEhNZ1VIUjVJRXgwWkRFZE1Cc0dBMVVFQXd3VVpHVjJMblZ3YkdJdWRYQmpiRzkxClpDNWpiMjB3SGhjTk1qRXhNREl5TVRJeE1ETTJXaGNOTXpFeE1ESXdNVEl4TURNMldqQmtNUXN3Q1FZRFZRUUcKRXdKQlZURVRNQkVHQTFVRUNBd0tVMjl0WlMxVGRHRjBaVEVoTUI4R0ExVUVDZ3dZU1c1MFpYSnVaWFFnVjJsawpaMmwwY3lCUWRIa2dUSFJrTVIwd0d3WURWUVFEREJSa1pYWXVkWEJzWWk1MWNHTnNiM1ZrTG1OdmJUQlpNQk1HCkJ5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEEwSUFCQmpVcUgyaVNuMFV2ZkU3UDdkT0QrSDBoKytxUWpnTG9OeWQKSTFwMmkvdlJPZmhMa0hCUjIxZ2JCSUdENjllYU1WWnZ4RWNxVWlKVWYwcmxLU3FzKzIralV6QlJNQjBHQTFVZApEZ1FXQkJTYTFaU3V1NkxJczMrc2lSSUJ5MHRXL3RnamZEQWZCZ05WSFNNRUdEQVdnQlNhMVpTdXU2TElzMytzCmlSSUJ5MHRXL3RnamZEQVBCZ05WSFJNQkFmOEVCVEFEQVFIL01Bb0dDQ3FHU000OUJBTUNBMGdBTUVVQ0lRQ3IKWXA5dHc2TmVXTHZGOGwrWm9rSE9QUzUzaGc2SDM0OHNMSjEvNit4YXN3SWdWVmN6WkFDc3JyUWt3TnVBZEVCeQo5TkxJR1VrWlhqeWgwdVFCS2x4Si9Wdz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=",
"labels": [
{
"key": "foo",
"value": "bar"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the bundle must be unique within customer account. |
| type | manual |
yes | Certificate bundle type. |
| certificate | Base64 encoded string | yes | Certificate within base64 string must be in PEM format. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List certificate bundles
Returns a list of available certificate bundles.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
| filter_service_uuid | String with a valid service UUID | no | Only return certificates used by the service with the specified UUID. | |
| filter_name_or_hostname | String | no | Only return certificates with names or one of the hostnames matching the specified string. | |
| filter_type | manual / dynamic / authority |
no | Only return certificates of specified type. Can be provided multiple times to get certificates of more than one type. |
Normal response
[
{
"certificate": "LS0LS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNIVENDQWNPZ0F3SUJBZ0lVSWlNbzg1cGd0b25kUmVESU1McVR4YjhncHI0d0NnWUlLb1pJemowRUF3SXcKWkRFTE1Ba0dBMVVFQmhNQ1FWVXhFekFSQmdOVkJBZ01DbE52YldVdFUzUmhkR1V4SVRBZkJnTlZCQW9NR0VsdQpkR1Z5Ym1WMElGZHBaR2RwZEhNZ1VIUjVJRXgwWkRFZE1Cc0dBMVVFQXd3VVpHVjJMblZ3YkdJdWRYQmpiRzkxClpDNWpiMjB3SGhjTk1qRXhNREl5TVRJeE1ETTJXaGNOTXpFeE1ESXdNVEl4TURNMldqQmtNUXN3Q1FZRFZRUUcKRXdKQlZURVRNQkVHQTFVRUNBd0tVMjl0WlMxVGRHRjBaVEVoTUI4R0ExVUVDZ3dZU1c1MFpYSnVaWFFnVjJsawpaMmwwY3lCUWRIa2dUSFJrTVIwd0d3WURWUVFEREJSa1pYWXVkWEJzWWk1MWNHTnNiM1ZrTG1OdmJUQlpNQk1HCkJ5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEEwSUFCQmpVcUgyaVNuMFV2ZkU3UDdkT0QrSDBoKytxUWpnTG9OeWQKSTFwMmkvdlJPZmhMa0hCUjIxZ2JCSUdENjllYU1WWnZ4RWNxVWlKVWYwcmxLU3FzKzIralV6QlJNQjBHQTFVZApEZ1FXQkJTYTFaU3V1NkxJczMrc2lSSUJ5MHRXL3RnamZEQWZCZ05WSFNNRUdEQVdnQlNhMVpTdXU2TElzMytzCmlSSUJ5MHRXL3RnamZEQVBCZ05WSFJNQkFmOEVCVEFEQVFIL01Bb0dDQ3FHU000OUJBTUNBMGdBTUVVQ0lRQ3IKWXA5dHc2TmVXTHZGOGwrWm9rSE9QUzUzaGc2SDM0OHNMSjEvNit4YXN3SWdWVmN6WkFDc3JyUWt3TnVBZEVCeQo5TkxJR1VrWlhqeWgwdVFCS2x4Si9Wdz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=",
"created_at": "2021-11-09T08:07:39.749472Z",
"hostnames": [
"application.example.com"
],
"labels": [
{
"key": "env",
"value": "staging"
}
],
"key_type": "ecdsa",
"name": "example-manual-certificate",
"not_after": "2031-10-20T12:10:36Z",
"not_before": "2021-10-22T12:10:36Z",
"operational_state": "idle",
"type": "manual",
"updated_at": "2021-11-09T08:07:39.749472Z",
"uuid": "bf571589-7378-41f8-879e-5505613b070d"
},
{
"certificate": "LStLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN3ekNDQW1tZ0F3SUJBZ0lRS0oxNWtaSFVtb1llUUN2ZGE2YVRzVEFLQmdncWhrak9QUVFEQWpBc01Rd3cKQ2dZRFZRUUtFd05rWlhZeEhEQWFCZ05WQkFNVEUyUmxkaUJKYm5SbGNtMWxaR2xoZEdVZ1EwRXdIaGNOTWpJdwpNakV5TURVek1qUXpXaGNOTWpJd01qRXpNRFV6TXpReldqQUFNSUlCSWpBTkJna3Foa2lHOXcwQkFRRUZBQU9DCkFROEFNSUlCQ2dLQ0FRRUExTlhmUzhIdEhVbURncjB1VkptbTl0SWRZTHpYS0NrSklGejFJNDI1WVZGTlB5cGYKZkJ5MDdxMUpYejIyQSs5WFdrZEVLY21yZ3N3QU50YVZkbHFDRzU5SzVQbXhCTVRLREFTYXc5REtZcGVTNUNlMwpWVG1PRnB3T3lMbUluMFJTZmdzdU5DOWRTR1BvemdhR0VLNXVVS29SRU4rNzRzNGNkcmVVME5pM0lQTUpzeHpmClMvVXJQRTcydzU5eG5jaEs4dVNUL0pzRzBsQUt4TkRsMHRqRkw3K25zNmYvNzQxRE9YSVVRZERMekhVYktheEsKWVNKTlQ2dGNlVlJqM01RNEtaaDRlQ3pNRmJlc0V2M1UxRVRRL1ZYYkNhQXBBOTB6UWdJQURqbGNNZTV0UTFZcwplNDIvWTkrWGVYZ25ISXFvR2RzdlF3VlNXYkdlWmdsZ1orZlNCd0lEQVFBQm80SE5NSUhLTUE0R0ExVWREd0VCCi93UUVBd0lGb0RBZEJnTlZIU1VFRmpBVUJnZ3JCZ0VGQlFjREFRWUlLd1lCQlFVSEF3SXdIUVlEVlIwT0JCWUUKRkh1NVVOZGlkb0VyN0FrTTR4Um1NQzR4NUdxTU1COEdBMVVkSXdRWU1CYUFGTldtZnpER1NHOXBwZWlQWE93TgoydUx6RnVjbk1Eb0dBMVVkRVFFQi93UXdNQzZDTEd4aUxUQmhabVkyWkdGak1UUXpZelF6TURBNVlqTXpaV1V5Ck56VTJaalkxT1RKa0xtRndjR3hsWW1WbE1CMEdEQ3NHQVFRQmdxUmt4aWhBQVFRTk1Bc0NBUVlFQkdGamJXVUUKQURBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlFQTBUcXhjNlVVejREVlh1OFJwSFhxS2R3VHVoSkNkSGxOMVA1agpNekkvMTFjQ0lEb2ZoelkwSFcxUHlMbEgrckVydW90cC9FYm5IMElLaDEzQTM4dndTQnM2Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K",
"created_at": "2022-02-11T17:31:38.202398Z",
"hostnames": [
"web.example.com"
],
"intermediates": "LS0tS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJ0VENDQVZ1Z0F3SUJBZ0lSQU5wSDZzV0ZtQzErWkdnUzFMWllVZGN3Q2dZSUtvWkl6ajBFQXdJd0pERU0KTUFvR0ExVUVDaE1EWkdWMk1SUXdFZ1lEVlFRREV3dGtaWFlnVW05dmRDQkRRVEFlRncweU1URXlNRGt4TXpVMwpNREZhRncwek1URXlNRGN4TXpVM01ERmFNQ3d4RERBS0JnTlZCQW9UQTJSbGRqRWNNQm9HQTFVRUF4TVRaR1YyCklFbHVkR1Z5YldWa2FXRjBaU0JEUVRCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkswbGMzNmcKN01TaDJTaXd3MUdDUjkvL3lSODR6S1VuNml6SmdCUkpFTlBxbmNXcjQzTi8rNktJR1EraERaazhRWHZ6RmExYQp2dFloc3JEVGtnRm9EV0tqWmpCa01BNEdBMVVkRHdFQi93UUVBd0lCQmpBU0JnTlZIUk1CQWY4RUNEQUdBUUgvCkFnRUFNQjBHQTFVZERnUVdCQlRWcG44d3hraHZhYVhvajF6c0Rkcmk4eGJuSnpBZkJnTlZIU01FR0RBV2dCU2oKckgwV0pubDdUSUJtc3NESGVveENFTVZyRmpBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlBa3NhUXdPMkFESGhBLwppRVR1SVY1dTlNV3hFTU5BVGlVODFIZjc0cGVhWlFJaEFLMnJDRmhVVnQxbFlzR1o3dFdjWGFHVDhyU1k2cU1YClBmK3dnUXFnNXUyVAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"key_type": "rsa",
"labels": [
{
"key": "foo",
"value": "bar"
}
],
"name": "example-dynamic-certificate",
"not_after": "2022-02-13T05:33:43Z",
"not_before": "2022-02-12T05:32:43Z",
"operational_state": "idle",
"type": "dynamic",
"updated_at": "2022-02-12T08:13:47.877562Z",
"uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2"
}
]
Notes:
- Please see dynamic certificate bundle operational states description.
Get certificate bundle details
Returns certificate bundle details by given {certificate_bundle_uuid}.
Request
Normal response
{
"certificate": "LStLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN3ekNDQW1tZ0F3SUJBZ0lRS0oxNWtaSFVtb1llUUN2ZGE2YVRzVEFLQmdncWhrak9QUVFEQWpBc01Rd3cKQ2dZRFZRUUtFd05rWlhZeEhEQWFCZ05WQkFNVEUyUmxkaUJKYm5SbGNtMWxaR2xoZEdVZ1EwRXdIaGNOTWpJdwpNakV5TURVek1qUXpXaGNOTWpJd01qRXpNRFV6TXpReldqQUFNSUlCSWpBTkJna3Foa2lHOXcwQkFRRUZBQU9DCkFROEFNSUlCQ2dLQ0FRRUExTlhmUzhIdEhVbURncjB1VkptbTl0SWRZTHpYS0NrSklGejFJNDI1WVZGTlB5cGYKZkJ5MDdxMUpYejIyQSs5WFdrZEVLY21yZ3N3QU50YVZkbHFDRzU5SzVQbXhCTVRLREFTYXc5REtZcGVTNUNlMwpWVG1PRnB3T3lMbUluMFJTZmdzdU5DOWRTR1BvemdhR0VLNXVVS29SRU4rNzRzNGNkcmVVME5pM0lQTUpzeHpmClMvVXJQRTcydzU5eG5jaEs4dVNUL0pzRzBsQUt4TkRsMHRqRkw3K25zNmYvNzQxRE9YSVVRZERMekhVYktheEsKWVNKTlQ2dGNlVlJqM01RNEtaaDRlQ3pNRmJlc0V2M1UxRVRRL1ZYYkNhQXBBOTB6UWdJQURqbGNNZTV0UTFZcwplNDIvWTkrWGVYZ25ISXFvR2RzdlF3VlNXYkdlWmdsZ1orZlNCd0lEQVFBQm80SE5NSUhLTUE0R0ExVWREd0VCCi93UUVBd0lGb0RBZEJnTlZIU1VFRmpBVUJnZ3JCZ0VGQlFjREFRWUlLd1lCQlFVSEF3SXdIUVlEVlIwT0JCWUUKRkh1NVVOZGlkb0VyN0FrTTR4Um1NQzR4NUdxTU1COEdBMVVkSXdRWU1CYUFGTldtZnpER1NHOXBwZWlQWE93TgoydUx6RnVjbk1Eb0dBMVVkRVFFQi93UXdNQzZDTEd4aUxUQmhabVkyWkdGak1UUXpZelF6TURBNVlqTXpaV1V5Ck56VTJaalkxT1RKa0xtRndjR3hsWW1WbE1CMEdEQ3NHQVFRQmdxUmt4aWhBQVFRTk1Bc0NBUVlFQkdGamJXVUUKQURBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlFQTBUcXhjNlVVejREVlh1OFJwSFhxS2R3VHVoSkNkSGxOMVA1agpNekkvMTFjQ0lEb2ZoelkwSFcxUHlMbEgrckVydW90cC9FYm5IMElLaDEzQTM4dndTQnM2Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K",
"created_at": "2022-02-11T17:31:38.202398Z",
"hostnames": [
"web.example.com"
],
"intermediates": "LS0tS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJ0VENDQVZ1Z0F3SUJBZ0lSQU5wSDZzV0ZtQzErWkdnUzFMWllVZGN3Q2dZSUtvWkl6ajBFQXdJd0pERU0KTUFvR0ExVUVDaE1EWkdWMk1SUXdFZ1lEVlFRREV3dGtaWFlnVW05dmRDQkRRVEFlRncweU1URXlNRGt4TXpVMwpNREZhRncwek1URXlNRGN4TXpVM01ERmFNQ3d4RERBS0JnTlZCQW9UQTJSbGRqRWNNQm9HQTFVRUF4TVRaR1YyCklFbHVkR1Z5YldWa2FXRjBaU0JEUVRCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkswbGMzNmcKN01TaDJTaXd3MUdDUjkvL3lSODR6S1VuNml6SmdCUkpFTlBxbmNXcjQzTi8rNktJR1EraERaazhRWHZ6RmExYQp2dFloc3JEVGtnRm9EV0tqWmpCa01BNEdBMVVkRHdFQi93UUVBd0lCQmpBU0JnTlZIUk1CQWY4RUNEQUdBUUgvCkFnRUFNQjBHQTFVZERnUVdCQlRWcG44d3hraHZhYVhvajF6c0Rkcmk4eGJuSnpBZkJnTlZIU01FR0RBV2dCU2oKckgwV0pubDdUSUJtc3NESGVveENFTVZyRmpBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlBa3NhUXdPMkFESGhBLwppRVR1SVY1dTlNV3hFTU5BVGlVODFIZjc0cGVhWlFJaEFLMnJDRmhVVnQxbFlzR1o3dFdjWGFHVDhyU1k2cU1YClBmK3dnUXFnNXUyVAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"key_type": "rsa",
"labels": [
{
"key": "foo",
"value": "bar"
}
],
"name": "example-dynamic-certificate",
"not_after": "2022-02-13T05:33:43Z",
"not_before": "2022-02-12T05:32:43Z",
"operational_state": "idle",
"services": [
{
"backends": [
{
"name": "example-backend",
"tls_configs": [
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"name": "auth"
}
]
}
],
"frontends": [],
"name": "example-service-1",
"uuid": "0a98ddbf-29e3-408c-b081-278a67101f76"
},
{
"frontends": [
{
"name": "example-frontend",
"tls_configs": [
{
"certificate_bundle_uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2",
"name": "example-tls-config"
}
]
}
],
"name": "example-service-2",
"uuid": "0a2f6730-5cbb-4676-a731-67acd3323ac4"
}
],
"type": "dynamic",
"updated_at": "2022-02-12T08:13:47.877562Z",
"uuid": "0aded5c1-c7a3-498a-b9c8-a871611c47a2"
}
Notes:
- Please see dynamic certificate bundle operational states description.
Modify manual certificate bundle
Modifies existing manual certificate bundle by given {certificate_bundle_uuid}.
Request
{
"name": "example-manual-certificate",
"certificate": "LS0LS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNIVENDQWNPZ0F3SUJBZ0lVSWlNbzg1cGd0b25kUmVESU1McVR4YjhncHI0d0NnWUlLb1pJemowRUF3SXcKWkRFTE1Ba0dBMVVFQmhNQ1FWVXhFekFSQmdOVkJBZ01DbE52YldVdFUzUmhkR1V4SVRBZkJnTlZCQW9NR0VsdQpkR1Z5Ym1WMElGZHBaR2RwZEhNZ1VIUjVJRXgwWkRFZE1Cc0dBMVVFQXd3VVpHVjJMblZ3YkdJdWRYQmpiRzkxClpDNWpiMjB3SGhjTk1qRXhNREl5TVRJeE1ETTJXaGNOTXpFeE1ESXdNVEl4TURNMldqQmtNUXN3Q1FZRFZRUUcKRXdKQlZURVRNQkVHQTFVRUNBd0tVMjl0WlMxVGRHRjBaVEVoTUI4R0ExVUVDZ3dZU1c1MFpYSnVaWFFnVjJsawpaMmwwY3lCUWRIa2dUSFJrTVIwd0d3WURWUVFEREJSa1pYWXVkWEJzWWk1MWNHTnNiM1ZrTG1OdmJUQlpNQk1HCkJ5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEEwSUFCQmpVcUgyaVNuMFV2ZkU3UDdkT0QrSDBoKytxUWpnTG9OeWQKSTFwMmkvdlJPZmhMa0hCUjIxZ2JCSUdENjllYU1WWnZ4RWNxVWlKVWYwcmxLU3FzKzIralV6QlJNQjBHQTFVZApEZ1FXQkJTYTFaU3V1NkxJczMrc2lSSUJ5MHRXL3RnamZEQWZCZ05WSFNNRUdEQVdnQlNhMVpTdXU2TElzMytzCmlSSUJ5MHRXL3RnamZEQVBCZ05WSFJNQkFmOEVCVEFEQVFIL01Bb0dDQ3FHU000OUJBTUNBMGdBTUVVQ0lRQ3IKWXA5dHc2TmVXTHZGOGwrWm9rSE9QUzUzaGc2SDM0OHNMSjEvNit4YXN3SWdWVmN6WkFDc3JyUWt3TnVBZEVCeQo5TkxJR1VrWlhqeWgwdVFCS2x4Si9Wdz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=",
"intermediates": "LS0tLS1CRdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJ0VENDQVZ1Z0F4SUJBZ0lSQU5wSDZzV0ZtQzErWkdnUzFMWllVZGN3Q2dZSUtvWkl6ajBFQXdJd0pERU0KTUFvR0ExVUVDaE1EWkdWMk1SUXdFZ1lEVlFRREV3dGtaWFlnVW05dmRDQkRRVEFlRncweU1URXlNRGt4TXpVMwpNREZhRncwek1URXlNRGN4TXpVM01ERmFNQ3d4RERBS0JnTlZCQW9UQTJSbGRqRWNNQm9HQTFVRUF4TVRaR1YyCklFbHVkR1Z5YldWa2FXRjBaU0JEUVRCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkswbGMzNmcKN01TaDJTaXd3MUdDUjkvL3lSODR6S1VuNml6SmdCUkpFTlBxbmNXcjQzTi8rNktJR1EraERaazhRWHZ6RmExYQp2dFloc3JEVGtnRm9EV0tqWmpCa01BNEdBMVVkRHdFQi93UUVBd0lCQmpBU0JnTlZIUk1CQWY4RUNEQUdBUUgvCkFnRUFNQjBHQTFVZERnUVdCQlRWcG44d3hraHZhYVhvajF6c0Rkcmk4eGJuSnpBZkJnTlZIU01FR0RBV2dCU2oKckgwV0pubDdUSUJtc3NESGVveENFTVZyRmpBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlBa3NhUXdPMkFESGhBLwppRVR1SVY1dTlNV3hFTU5BVGlVODFIZjc0cGVhWlFJaEFLMnJDRmhVVnQxbFlzR1o3dFdjWGFHVDhyU1k2cU1YClBmK3dnUXFnNXUyVAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"private_key": "LS0tL1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JR0hBZ0VBTUJNR0J5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEJHMHdhd0lCQVFRZ3NQMzI2RlIxcmNwL0xybmcKNFBCT3BLRjIzSUNaM01GdGNrZFJuWkFESnRlaFJBTkNBQVFZMUtoOW9rcDlGTDN4T3orM1RnL2g5SWZ2cWtJNApDNkRjblNOYWRvdjcwVG40UzVCd1VkdFlHd1NCZyt2WG1qRldiOFJIS2xJaVZIOUs1U2txclB0dgotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg=="
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the bundle must be unique within customer account. |
| certificate | Base64 encoded string | no | Certificate within base64 string must be in PEM format. |
| intermediates | Base64 encoded string | no | Intermediate certificates within base64 string must be in PEM format. |
| private_key | Base64 encoded string | no | Private key within base64 string must be in PEM format. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Modify dynamic certificate bundle
Modifies existing dynamic certificate bundle by given {certificate_bundle_uuid}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the bundle must be unique within customer account. |
| hostnames | An array of 1-100 hostnames | no | Certificate hostnames. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Modify authority certificate bundle
Modifies existing authority certificate bundle by given {certificate_bundle_uuid}.
Request
{
"name": "example-authority-certificate",
"certificate": "LS0LS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNIVENDQWNPZ0F3SUJBZ0lVSWlNbzg1cGd0b25kUmVESU1McVR4YjhncHI0d0NnWUlLb1pJemowRUF3SXcKWkRFTE1Ba0dBMVVFQmhNQ1FWVXhFekFSQmdOVkJBZ01DbE52YldVdFUzUmhkR1V4SVRBZkJnTlZCQW9NR0VsdQpkR1Z5Ym1WMElGZHBaR2RwZEhNZ1VIUjVJRXgwWkRFZE1Cc0dBMVVFQXd3VVpHVjJMblZ3YkdJdWRYQmpiRzkxClpDNWpiMjB3SGhjTk1qRXhNREl5TVRJeE1ETTJXaGNOTXpFeE1ESXdNVEl4TURNMldqQmtNUXN3Q1FZRFZRUUcKRXdKQlZURVRNQkVHQTFVRUNBd0tVMjl0WlMxVGRHRjBaVEVoTUI4R0ExVUVDZ3dZU1c1MFpYSnVaWFFnVjJsawpaMmwwY3lCUWRIa2dUSFJrTVIwd0d3WURWUVFEREJSa1pYWXVkWEJzWWk1MWNHTnNiM1ZrTG1OdmJUQlpNQk1HCkJ5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEEwSUFCQmpVcUgyaVNuMFV2ZkU3UDdkT0QrSDBoKytxUWpnTG9OeWQKSTFwMmkvdlJPZmhMa0hCUjIxZ2JCSUdENjllYU1WWnZ4RWNxVWlKVWYwcmxLU3FzKzIralV6QlJNQjBHQTFVZApEZ1FXQkJTYTFaU3V1NkxJczMrc2lSSUJ5MHRXL3RnamZEQWZCZ05WSFNNRUdEQVdnQlNhMVpTdXU2TElzMytzCmlSSUJ5MHRXL3RnamZEQVBCZ05WSFJNQkFmOEVCVEFEQVFIL01Bb0dDQ3FHU000OUJBTUNBMGdBTUVVQ0lRQ3IKWXA5dHc2TmVXTHZGOGwrWm9rSE9QUzUzaGc2SDM0OHNMSjEvNit4YXN3SWdWVmN6WkFDc3JyUWt3TnVBZEVCeQo5TkxJR1VrWlhqeWgwdVFCS2x4Si9Wdz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo="
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the bundle must be unique within customer account. |
| certificate | Base64 encoded string | no | Certificate within base64 string must be in PEM format. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Delete certificate bundle
Deletes existing certificate bundle by given {certificate_bundle_uuid}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
| 409 Conflict | INVALID_REQUEST | Certificate bundle is in use. |
Create certificate bundle label
Creates a new label by given {certificate_bundle_uuid}.
Labels used for certificate bundles filtering.
Certificate bundle labels usage examples
Below are some examples of what certain GET requests might look like.
- exact match:
GET /1.3/load-balancer/certificate-bundles?label=env%3Dstaging - existence:
GET /1.3/load-balancer/certificate-bundles?label=env - multiple:
GET /1.3/load-balancer/certificate-bundles?label=env&label=foo%3Dbar
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| key | 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ |
yes | Represents the label identifier. The key is unique within a service. |
| value | 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z |
yes | Represents the label value. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List certificate bundle labels
Returns a list of available certificate bundle labels by given {certificate_bundle_uuid}.
Request
Normal response
Get certificate bundle label details
Returns label details by given {certificate_bundle_uuid} and {key}.
Request
Normal response
Modify certificate bundle label
Modifies existing label by given {certificate_bundle_uuid} and {key}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| key | 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ |
no | Represents the label identifier. The key is unique within a service. |
| value | 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z / null |
no | Represents the label value. |
Normal response
Delete certificate bundle label
Deletes existing label by given {certificate_bundle_uuid} and {key}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Rule Matchers
| Matcher | Type | Frontend modes | Description |
|---|---|---|---|
| body_size | Integer | http | Matches by HTTP request body size. |
| cookie | String with argument | http | Matches by HTTP cookie value. Cookie name must be provided. |
| header | String with argument | http | Deprecated, alias for request_header. |
| host | Host | tcp / http | Matches by hostname. Header extracted from HTTP Headers or from TLS certificate in case of secured connection. |
| http_method | HTTP method | http | Matches by HTTP method. |
| http_status | Integer | http | Matches by member server's response status code. |
| path | String | http | Matches by URL path. |
| request_header | String with argument | http | Matches by request's header value. The name of the header must be provided. |
| response_header | String with argument | http | Matches by a member server's response header value. The name of the header must be provided. |
| src_ip | IP | tcp / http | Matches by source IP address. |
| src_port | Integer | tcp / http | Matches by source port number. |
| url | String | http | Matches by URL without scheme, e.g. example.com/dashboard. |
| url_query | String | http | Matches by URL query string. |
| url_param | String with argument | http | Matches by URL query parameter value. Query parameter name must be provided |
Matcher type IP
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | src_ip |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| value | IPv4 / IPv6 | yes | IP address. CIDR masks are supported, e.g. 192.168.0.0/24. |
Example:
Matcher type Integer
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | body_size / http_status / src_port |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| method | equal / greater_or_equal / greater / less_or_equal / less |
yes | Match method. |
| value | >= 0 | yes | Integer value. |
Example:
Matcher type Integer (range)
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | src_port / body_size |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| method | range |
yes | Match method. |
| range_start | >= 0 | yes | Integer value (inclusive). |
| range_end | >= 0 | yes | Integer value (inclusive). |
Example:
{
"type": "src_port",
"inverse": true,
"match_src_port": {
"method": "range",
"range_start": 8000,
"range_end": 9000
}
}
Matcher type String
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | path / url / url_query |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| method | exact / substring / regexp / starts / ends / domain / exists / ip |
yes | Match method. |
| value | 1-255 characters | yes | String value. |
| ignore_case | true / false |
no | Ignore case, default false. |
Examples:
{
"type": "path",
"match_path": {
"method": "starts",
"value": "/application",
"ignore_case": true
}
}
Notes:
- matcher with
existsandipmethods must be used withoutvalueandignore_casefields.
Matcher type Host
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | host |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_host | Matcher object | yes | Embedded matcher configuration. |
| value | 1-255 characters | yes | String value. |
Examples:
Matcher type HTTP Method
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | http_method |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_host | Matcher object | yes | Embedded matcher configuration. |
| value | GET / HEAD / POST / PUT / PATCH / DELETE / CONNECT / OPTIONS / TRACE |
yes | String value. |
Examples:
Matcher type String with argument
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | cookie / header / request_header / response_header / url_param |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| method | exact / substring / regexp / starts / ends / domain / exists / ip |
yes | Match method. |
| name | 1-255 characters | yes | Name of the argument. |
| value | 1-255 characters | yes | String value. |
| ignore_case | true / false |
no | Ignore case, default false. |
Example:
{
"type": "url_param",
"match_url_param": {
"method": "exact",
"name": "status",
"value": "active",
"ignore_case": true
}
}
Notes:
- matcher with
existsandipmethods must be used withoutvalueandignore_casefields.
Matcher type Backend
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | num_members_up |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| method | equal / greater_or_equal / greater / less_or_equal / less |
yes | Match method. |
| value | 0-100 | yes | Integer value. |
| backend | A valid backend identifier, e.g. example-backend |
yes | The name of the backend which members will be monitored. |
Example:
{
"type": "num_members_up",
"match_num_members_up": {
"method": "less",
"value": 1,
"backend": "example-fallback-backend"
}
}
Matcher type Backend (range)
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | num_members_up |
yes | Matcher type. |
| inverse | true / false |
no | Optional flag indicates that condition should be inverted, default is false. Works similar to logical NOT operator. |
| match_{type} | Matcher object | yes | Embedded matcher configuration. |
| method | range |
yes | Match method. |
| range_start | 0-100 | yes | Integer value (inclusive). |
| range_end | 0-100 | yes | Integer value (inclusive). |
| backend | A valid backend identifier, e.g. example-backend |
yes | The name of the backend which members will be monitored. |
Example:
{
"type": "num_members_up",
"match_num_members_up": {
"method": "less",
"range_start": 10,
"range_end": 20,
"backend": "example-fallback-backend"
}
}
Rule Actions
| Action | Type | Frontend modes | Description |
|---|---|---|---|
| use_backend | Use backend | tcp / http | Rotes traffic to specified backend. |
| tcp_reject | TCP Reject | tcp / http | Terminates a connection. |
| http_return | HTTP Return | http | Returns HTTP response with specified HTTP status. |
| http_redirect | HTTP Redirect | http | Redirects HTTP requests to specified location or URL scheme. |
| set_forwarded_headers | Set X-Forwarded Headers | http | Adds "X-Forwarded-For / -Proto / -Port" headers in the forwarded requests. |
| set_request_header | Set Request Headers | http | Adds/Overrides custom headers in requests. |
| set_response_header | Set Response Headers | http | Adds/Overrides custom headers in responses. |
Action type Use Backend
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | use_backend |
yes | Action type. |
| action_use_backend | Action object | yes | Embedded action configuration. |
| backend | A valid backend identifier, e.g. example-backend |
yes | The name of the backend where traffic will be routed. |
Example:
Action type TCP Reject
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | tcp_reject |
yes | Action type. |
| action_tcp_reject | Action object | yes | Embedded action configuration. Intended to be empty. |
Example:
Action type HTTP Return
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | http_return |
yes | Action type. |
| action_http_return | Action object | yes | Embedded action configuration. |
| status | 100-599 | yes | HTTP status code. |
| content_type | text/plain / text/html / application/json |
yes | Content type. |
| payload | Base64 encoded string of 1-4096 characters | yes | The payload. |
Example:
{
"type": "http_return",
"action_http_return": {
"status": 200,
"content_type": "text/html",
"payload": "PGgxPmFwcGxlYmVlPC9oMT4K"
}
}
Action type HTTP Redirect
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | http_redirect |
yes | Action type. |
| action_http_redirect | Action object | yes | Embedded action configuration. |
| location | URI | yes | Target location. |
| status | 301, 302, 303, 307 or 308 | no | HTTP status code. Default is 301. |
Example:
{
"type": "http_redirect",
"action_http_redirect": {
"location": "https://internal.example.com",
"status": 301
}
}
Action type HTTP Redirect (scheme)
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | http_redirect |
yes | Action type. |
| action_http_redirect | Action object | yes | Embedded action configuration. |
| scheme | http / https |
yes | Target scheme. |
| status | 301, 302, 303, 307 or 308 | no | HTTP status code. Default is 302. |
Example:
Action Set X-Forwarded Headers
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | set_forwarded_headers |
yes | Action type. |
| action_set_forwarded_headers | Action object | yes | Embedded action configuration. Intended to be empty. |
Example:
Action Set Request Header
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | set_request_header |
yes | Action type. |
| action_set_request_header | Action object | yes | Embedded action configuration. |
| header | 1-256 characters | yes | Header name. |
| value | 0-256 characters | no | Header value. |
Example:
{
"type": "set_request_header",
"action_set_request_header": {
"header": "example-header",
"value": "example-value"
}
}
Action Set Response Header
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| type | set_response_header |
yes | Action type. The rule with set_response_header action should not contain any matchers. |
| action_set_response_header | Action object | yes | Embedded action configuration. |
| header | 1-256 characters | yes | Header name. |
| value | 0-256 characters | no | Header value. |
Example:
{
"type": "set_response_header",
"action_set_response_header": {
"header": "example-header",
"value": "example-value"
}
}
Frontend Properties
| Attribute | Accepted value | Required | Default | Description |
|---|---|---|---|---|
| timeout_client | 1-86400 | no | 10 | Client request timeout in seconds. |
| inbound_proxy_protocol | true / false |
no | false |
Enable or disable inbound proxy protocol support. |
| http2_enabled | true / false |
no | false |
Allow HTTP/2 connections to frontend by utilizing ALPN extension of TLS protocol, therefore can only be enabled when at least one TLS config is attached. |
Example:
Backend Properties
| Attribute | Accepted value | Required | Default | Description |
|---|---|---|---|---|
| timeout_server | 1-86400 | no | 10 | Backend server timeout in seconds. |
| timeout_tunnel | 1-3024000 | no | 3600 | Maximum inactivity time on the client and server side for tunnels in seconds. |
| health_check_type | tcp / http |
no | tcp |
Health check type. |
| health_check_interval | 1-86400 | no | 10 | Interval between health checks. |
| health_check_fall | 1-100 | no | 3 | Sets how many failed health checks are allowed until the backend member is taken off from the rotation. |
| health_check_rise | 1-100 | no | 3 | Sets how many passing checks there must be before returning the backend member to the rotation. |
| health_check_url | 1-255 characters | no | / |
Health check endpoint. The field accepts URLs in the following formats [scheme:]//[host][:port][/path] or /path. Supported URL schemes are tcp/http/https or omitted. If port is provided as part of a URL, then checks go to that port instead of ports where members are listening. If host is provided as part of a URL, then HTTP checks contain a Host header. Examples: //:8080, tcp://:8080, http://anyhost/anypath, https://anyhost:443, /anypath. |
| health_check_tls_verify | true / false |
no | false |
Enables certificate verification. For the verification will be used the certificate bundle of type authority if it attached via TLS config, or system CA certificate. Works when tls_enabled or with https scheme in health_check_url, otherwise ignored. |
| health_check_expected_status | 100-599 | no | 200 | Expected HTTP status code returned by the customer application to mark server as healthy. Ignored for tcp type. |
| health_check_on_down | (empty string) / shutdown-sessions |
no | (empty string) | Immediately terminates the peer connections, if the server goes down. |
| sticky_session_cookie_name | 0-64 / null |
no | Sets sticky session cookie name. Empty string disables sticky session. | |
| outbound_proxy_protocol | v1 / v2 / null |
no | Enables outbound proxy protocol by setting the desired version. Empty string disables. | |
| tls_enabled | true / false |
no | false |
Enables TLS connection from the load balancer to backend servers. |
| tls_verify | true / false |
no | false |
Enables backend servers certificate verification. Please make sure that TLS config with the certificate bundle of type authority attached to the backend or tls_use_system_ca enabled. Note: tls_verify has preference over health_check_tls_verify when tls_enabled in true. |
| tls_use_system_ca | true / false |
no | false |
If enabled, then the system CA certificate bundle will be used for the certificate verification. |
| http2_enabled | true / false |
no | false |
Allow HTTP/2 connections to backend members by utilizing ALPN extension of TLS protocol, therefore it can only be enabled when tls_enabled is set to true. Note: members should support HTTP/2 for this setting to work. |
Example:
{
"timeout_server": 30,
"timeout_tunnel": 3600,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_interval": 20,
"health_check_fall": 3,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_url": "/health",
"health_check_expected_status": 200,
"sticky_session_cookie_name": "SERVERID",
"outbound_proxy_protocol": "v1",
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false,
"http2_enabled": false
}
Service configured status
The service configured status indicates the service's current intended status. Managed by the customer.
| Status | Description |
|---|---|
| started | The service is running. |
| stopped | The service is stopped. |
Service operational state
The service operational state indicates the service's current operational, effective state. Managed by the system.
| State | Description |
|---|---|
| pending | Indicates newly created service or started reconfiguration. |
| setup-agent | Configuring management tool. |
| setup-server | Configuring load balancer nodes. |
| setup-network | Configuring network. |
| setup-lb | Configuring load balancer. |
| setup-dns | Updating DNS records. |
| checkup | Verifying load balancer correctly configured and running. |
| running | Indicates service up and running. |
| delete-dns | Removing DNS records. |
| delete-network | Reconfiguring network. |
| delete-server | Deleting load balancer nodes. |
| delete-service | Deleting the service. |
Dynamic certificate bundle operational state
Indicates current operational state for certificate bundle of dynamic type. Operational state is driven by the system.
System automatically starts renew process when the certificate is about to expire.
| State | Description |
|---|---|
| idle | Newly created certificate / Ready to use. |
| pending | Indicates that certificate attached to load balancer service and about to start the challenge. |
| setup-challenge | Setting up challenge for the certificate retrieval process and waiting for validation request. |
| complete-challenge | Confirming success response on validation request. Back to idle state. |
DNS challenge
Returns DNS challenge domain.
This can be used to validate domain ownership using the ACME challenge method. To validate your domain, you need to add CNAME record to the domain provided by this API to your DNS settings. The name/host of the CNAME record should be _acme-challenge or _acme-challenge.mysubdomain if you are setting up a subdomain called mysubdomain. The target/points to of the record needs to be set to the value returned by this API.
Request
Normal response
Example DNS record
| Type | Name/Host | Target/Points |
|---|---|---|
| CNAME | _acme-challenge.objects |
_acme-challenge.xxxxx.upcloudlb.com |