load_balancers

Creates, updates, deletes, gets or lists a load_balancers resource.

Overview

Name	load_balancers
Type	Resource
Id	digitalocean.compute.load_balancers

Fields

The following fields are returned by SELECT queries:

load_balancers_get

The response will be a JSON object with a key called load_balancer. The
value of this will be an object that contains the standard attributes
associated with a load balancer

Name	Datatype	Description
id	string (uuid)	A unique ID that can be used to identify and reference a load balancer. (example: 4de7ac8b-495b-4884-9a69-1050c6793cd6)
name	string	A human-readable name for a load balancer instance. (example: example-lb-01)
project_id	string	The ID of the project that the load balancer is associated with. If no ID is provided at creation, the load balancer associates with the user's default project. If an invalid project ID is provided, the load balancer will not be created. (example: 4de7ac8b-495b-4884-9a69-1050c6793cd6)
algorithm	string	This field has been deprecated. You can no longer specify an algorithm for load balancers. (example: round_robin, default: round_robin)
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the load balancer was created. (example: 2017-02-01T22:22:58Z)
disable_lets_encrypt_dns_records	boolean	A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.
domains	array	An array of objects specifying the domain configurations for a Global load balancer.
droplet_ids	array	An array containing the IDs of the Droplets assigned to the load balancer.
enable_backend_keepalive	boolean	A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.
enable_proxy_protocol	boolean	A boolean value indicating whether PROXY Protocol is in use.
firewall	object	An object specifying allow and deny rules to control traffic to the load balancer.
forwarding_rules	array	An array of objects specifying the forwarding rules for a load balancer.
glb_settings	object	An object specifying forwarding configurations for a Global load balancer.
health_check	object	An object specifying health check settings for the load balancer.
http_idle_timeout_seconds	integer	An integer value which configures the idle timeout for HTTP requests to the target droplets.
ip	string	An attribute containing the public-facing IP address of the load balancer. (pattern: ^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$, example: 104.131.186.241)
ipv6	string	An attribute containing the public-facing IPv6 address of the load balancer. (example: 2604:a880:800:14::85f5:c000)
network	string	A string indicating whether the load balancer should be external or internal. Internal load balancers have no public IPs and are only accessible to resources on the same VPC network. This property cannot be updated after creating the load balancer. (example: EXTERNAL, default: EXTERNAL)
network_stack	string	A string indicating whether the load balancer will support IPv4 or both IPv4 and IPv6 networking. This property cannot be updated after creating the load balancer. (example: IPV4, default: IPV4)
redirect_http_to_https	boolean	A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.
region	object	The region where the load balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a load balancer, an entire region object will be returned.
size	string	This field has been replaced by the size_unit field for all regions except in AMS2, NYC2, and SFO1. Each available load balancer size now equates to the load balancer having a set number of nodes. * lb-small = 1 node * lb-medium = 3 nodes * lb-large = 6 nodes You can resize load balancers after creation up to once per hour. You cannot resize a load balancer within the first hour of its creation. (default: lb-small, example: lb-small)
size_unit	integer	How many nodes the load balancer contains. Each additional node increases the load balancer's ability to manage more connections. Load balancers can be scaled up or down, and you can change the number of nodes after creation up to once per hour. This field is currently not available in the AMS2, NYC2, or SFO1 regions. Use the size field to scale load balancers that reside in these regions.
status	string	A status string indicating the current state of the load balancer. This can be new, active, or errored. (example: new)
sticky_sessions	object	An object specifying sticky sessions settings for the load balancer.
tag	string	The name of a Droplet tag corresponding to Droplets assigned to the load balancer. (example: prod:web)
target_load_balancer_ids	array	An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.
tls_cipher_policy	string	A string indicating the policy for the TLS cipher suites used by the load balancer. The possible values are DEFAULT or STRONG. The default value is DEFAULT. (example: STRONG, default: DEFAULT)
type	string	A string indicating whether the load balancer should be a standard regional HTTP load balancer, a regional network load balancer that routes traffic at the TCP/UDP transport layer, or a global load balancer. (example: REGIONAL, default: REGIONAL)
vpc_uuid	string (uuid)	A string specifying the UUID of the VPC to which the load balancer is assigned. (example: c33931f2-a26a-4e61-b85c-4e95a2ec431b)

load_balancers_list

A JSON object with a key of load_balancers. This will be set to an array of objects, each of which will contain the standard load balancer attributes.

Name	Datatype	Description
id	string (uuid)	A unique ID that can be used to identify and reference a load balancer. (example: 4de7ac8b-495b-4884-9a69-1050c6793cd6)
name	string	A human-readable name for a load balancer instance. (example: example-lb-01)
project_id	string	The ID of the project that the load balancer is associated with. If no ID is provided at creation, the load balancer associates with the user's default project. If an invalid project ID is provided, the load balancer will not be created. (example: 4de7ac8b-495b-4884-9a69-1050c6793cd6)
algorithm	string	This field has been deprecated. You can no longer specify an algorithm for load balancers. (example: round_robin, default: round_robin)
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the load balancer was created. (example: 2017-02-01T22:22:58Z)
disable_lets_encrypt_dns_records	boolean	A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.
domains	array	An array of objects specifying the domain configurations for a Global load balancer.
droplet_ids	array	An array containing the IDs of the Droplets assigned to the load balancer.
enable_backend_keepalive	boolean	A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.
enable_proxy_protocol	boolean	A boolean value indicating whether PROXY Protocol is in use.
firewall	object	An object specifying allow and deny rules to control traffic to the load balancer.
forwarding_rules	array	An array of objects specifying the forwarding rules for a load balancer.
glb_settings	object	An object specifying forwarding configurations for a Global load balancer.
health_check	object	An object specifying health check settings for the load balancer.
http_idle_timeout_seconds	integer	An integer value which configures the idle timeout for HTTP requests to the target droplets.
ip	string	An attribute containing the public-facing IP address of the load balancer. (pattern: ^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$, example: 104.131.186.241)
ipv6	string	An attribute containing the public-facing IPv6 address of the load balancer. (example: 2604:a880:800:14::85f5:c000)
network	string	A string indicating whether the load balancer should be external or internal. Internal load balancers have no public IPs and are only accessible to resources on the same VPC network. This property cannot be updated after creating the load balancer. (example: EXTERNAL, default: EXTERNAL)
network_stack	string	A string indicating whether the load balancer will support IPv4 or both IPv4 and IPv6 networking. This property cannot be updated after creating the load balancer. (example: IPV4, default: IPV4)
redirect_http_to_https	boolean	A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.
region	object	The region where the load balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a load balancer, an entire region object will be returned.
size	string	This field has been replaced by the size_unit field for all regions except in AMS2, NYC2, and SFO1. Each available load balancer size now equates to the load balancer having a set number of nodes. * lb-small = 1 node * lb-medium = 3 nodes * lb-large = 6 nodes You can resize load balancers after creation up to once per hour. You cannot resize a load balancer within the first hour of its creation. (default: lb-small, example: lb-small)
size_unit	integer	How many nodes the load balancer contains. Each additional node increases the load balancer's ability to manage more connections. Load balancers can be scaled up or down, and you can change the number of nodes after creation up to once per hour. This field is currently not available in the AMS2, NYC2, or SFO1 regions. Use the size field to scale load balancers that reside in these regions.
status	string	A status string indicating the current state of the load balancer. This can be new, active, or errored. (example: new)
sticky_sessions	object	An object specifying sticky sessions settings for the load balancer.
tag	string	The name of a Droplet tag corresponding to Droplets assigned to the load balancer. (example: prod:web)
target_load_balancer_ids	array	An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.
tls_cipher_policy	string	A string indicating the policy for the TLS cipher suites used by the load balancer. The possible values are DEFAULT or STRONG. The default value is DEFAULT. (example: STRONG, default: DEFAULT)
type	string	A string indicating whether the load balancer should be a standard regional HTTP load balancer, a regional network load balancer that routes traffic at the TCP/UDP transport layer, or a global load balancer. (example: REGIONAL, default: REGIONAL)
vpc_uuid	string (uuid)	A string specifying the UUID of the VPC to which the load balancer is assigned. (example: c33931f2-a26a-4e61-b85c-4e95a2ec431b)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
load_balancers_get	select	lb_id		To show information about a load balancer instance, send a GET request to /v2/load_balancers/$LOAD_BALANCER_ID.
load_balancers_list	select		per_page, page	To list all of the load balancer instances on your account, send a GET request to /v2/load_balancers.
load_balancers_create	insert			To create a new load balancer instance, send a POST request to /v2/load_balancers. You can specify the Droplets that will sit behind the load balancer using one of two methods: * Set droplet_ids to a list of specific Droplet IDs. * Set tag to the name of a tag. All Droplets with this tag applied will be assigned to the load balancer. Additional Droplets will be automatically assigned as they are tagged. These methods are mutually exclusive.
load_balancers_update	replace	lb_id		To update a load balancer's settings, send a PUT request to /v2/load_balancers/$LOAD_BALANCER_ID. The request should contain a full representation of the load balancer including existing attributes. It may contain one of the droplets_ids or tag attributes as they are mutually exclusive. Note that any attribute that is not provided will be reset to its default value.
load_balancers_delete	delete	lb_id		To delete a load balancer instance, disassociating any Droplets assigned to it and removing it from your account, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
load_balancers_delete_cache	exec	lb_id		To delete a Global load balancer CDN cache, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/cache. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
load_balancers_add_droplets	exec	lb_id, droplet_ids		To assign a Droplet to a load balancer instance, send a POST request to /v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs. Individual Droplets can not be added to a load balancer configured with a Droplet tag. Attempting to do so will result in a "422 Unprocessable Entity" response from the API. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
load_balancers_remove_droplets	exec	lb_id, droplet_ids		To remove a Droplet from a load balancer instance, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
load_balancers_add_forwarding_rules	exec	lb_id, forwarding_rules		To add an additional forwarding rule to a load balancer instance, send a POST request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body of the request, there should be a forwarding_rules attribute containing an array of rules to be added. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
load_balancers_remove_forwarding_rules	exec	lb_id, forwarding_rules		To remove forwarding rules from a load balancer instance, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body of the request, there should be a forwarding_rules attribute containing an array of rules to be removed. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
lb_id	string	A unique identifier for a load balancer. (example: 4de7ac8b-495b-4884-9a69-1050c6793cd6)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)

SELECT examples

load_balancers_get

To show information about a load balancer instance, send a GET request to
/v2/load_balancers/$LOAD_BALANCER_ID.

SELECT
id,
name,
project_id,
algorithm,
created_at,
disable_lets_encrypt_dns_records,
domains,
droplet_ids,
enable_backend_keepalive,
enable_proxy_protocol,
firewall,
forwarding_rules,
glb_settings,
health_check,
http_idle_timeout_seconds,
ip,
ipv6,
network,
network_stack,
redirect_http_to_https,
region,
size,
size_unit,
status,
sticky_sessions,
tag,
target_load_balancer_ids,
tls_cipher_policy,
type,
vpc_uuid
FROM digitalocean.compute.load_balancers
WHERE lb_id = '{{ lb_id }}' -- required;

load_balancers_list

To list all of the load balancer instances on your account, send a GET request
to /v2/load_balancers.

SELECT
id,
name,
project_id,
algorithm,
created_at,
disable_lets_encrypt_dns_records,
domains,
droplet_ids,
enable_backend_keepalive,
enable_proxy_protocol,
firewall,
forwarding_rules,
glb_settings,
health_check,
http_idle_timeout_seconds,
ip,
ipv6,
network,
network_stack,
redirect_http_to_https,
region,
size,
size_unit,
status,
sticky_sessions,
tag,
target_load_balancer_ids,
tls_cipher_policy,
type,
vpc_uuid
FROM digitalocean.compute.load_balancers
WHERE per_page = '{{ per_page }}'
AND page = '{{ page }}';

INSERT examples

load_balancers_create

To create a new load balancer instance, send a POST request to
/v2/load_balancers.

You can specify the Droplets that will sit behind the load balancer using one
of two methods:

* Set droplet_ids to a list of specific Droplet IDs.
* Set tag to the name of a tag. All Droplets with this tag applied will be
assigned to the load balancer. Additional Droplets will be automatically
assigned as they are tagged.

These methods are mutually exclusive.

INSERT INTO digitalocean.compute.load_balancers (

)
SELECT 

RETURNING
load_balancer
;

Manifest

# Description fields are for documentation purposes
- name: load_balancers
  props:

REPLACE examples

load_balancers_update

To update a load balancer's settings, send a PUT request to
/v2/load_balancers/$LOAD_BALANCER_ID. The request should contain a full
representation of the load balancer including existing attributes. It may
contain one of the droplets_ids or tag attributes as they are mutually
exclusive. Note that any attribute that is not provided will be reset to its
default value.

REPLACE digitalocean.compute.load_balancers
SET 
-- No updatable properties
WHERE 
lb_id = '{{ lb_id }}' --required
RETURNING
load_balancer;

DELETE examples

load_balancers_delete

To delete a load balancer instance, disassociating any Droplets assigned to it
and removing it from your account, send a DELETE request to
/v2/load_balancers/$LOAD_BALANCER_ID.

A successful request will receive a 204 status code with no body in response.
This indicates that the request was processed successfully.

DELETE FROM digitalocean.compute.load_balancers
WHERE lb_id = '{{ lb_id }}' --required;

Lifecycle Methods

load_balancers_delete_cache

To delete a Global load balancer CDN cache, send a DELETE request to
/v2/load_balancers/$LOAD_BALANCER_ID/cache.

A successful request will receive a 204 status code with no body in response.
This indicates that the request was processed successfully.

EXEC digitalocean.compute.load_balancers.load_balancers_delete_cache 
@lb_id='{{ lb_id }}' --required;

load_balancers_add_droplets

To assign a Droplet to a load balancer instance, send a POST request to
/v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request,
there should be a droplet_ids attribute containing a list of Droplet IDs.
Individual Droplets can not be added to a load balancer configured with a
Droplet tag. Attempting to do so will result in a "422 Unprocessable Entity"
response from the API.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

EXEC digitalocean.compute.load_balancers.load_balancers_add_droplets 
@lb_id='{{ lb_id }}' --required 
@@json=
'{
"droplet_ids": "{{ droplet_ids }}"
}';

load_balancers_remove_droplets

To remove a Droplet from a load balancer instance, send a DELETE request to
/v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request,
there should be a droplet_ids attribute containing a list of Droplet IDs.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

EXEC digitalocean.compute.load_balancers.load_balancers_remove_droplets 
@lb_id='{{ lb_id }}' --required 
@@json=
'{
"droplet_ids": "{{ droplet_ids }}"
}';

load_balancers_add_forwarding_rules

To add an additional forwarding rule to a load balancer instance, send a POST
request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body
of the request, there should be a forwarding_rules attribute containing an
array of rules to be added.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

EXEC digitalocean.compute.load_balancers.load_balancers_add_forwarding_rules 
@lb_id='{{ lb_id }}' --required 
@@json=
'{
"forwarding_rules": "{{ forwarding_rules }}"
}';

load_balancers_remove_forwarding_rules

To remove forwarding rules from a load balancer instance, send a DELETE
request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the
body of the request, there should be a forwarding_rules attribute containing
an array of rules to be removed.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

EXEC digitalocean.compute.load_balancers.load_balancers_remove_forwarding_rules 
@lb_id='{{ lb_id }}' --required 
@@json=
'{
"forwarding_rules": "{{ forwarding_rules }}"
}';