ngine_io.cloudstack.lb_internal module – Manages internal load balancers on Apache CloudStack based clouds.

Note

This module is part of the ngine_io.cloudstack collection (version 3.3.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ngine_io.cloudstack. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: ngine_io.cloudstack.lb_internal.

New in ngine_io.cloudstack 3.3.0

Synopsis

• Create and remove internal (application) load balancers on a VPC tier.

• Internal load balancers use a different API family than ngine_io.cloudstack.lb_rule, which manages public load balancer rules only and can not see or manage internal ones.

• Existing internal load balancers are matched by name within the network scope.

• Only for_display can be changed after creation. See the notes below.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 2.6

• cs >= 0.9.0

Parameters

Parameter	Comments
account string	Account the internal load balancer is related to.
algorithm string	Load balancing algorithm. Defaults to source when the load balancer is created. When not given, the algorithm of an existing load balancer is left as it is. Can not be changed after creation. Choices: "source" "roundrobin" "leastconn"
api_http_method string	HTTP method used to query the API endpoint. If not given, the CLOUDSTACK_METHOD env variable is considered. Choices: "get" ← (default) "post"
api_key string / required	API key of the CloudStack API. If not given, the CLOUDSTACK_KEY env variable is considered.
api_secret string / required	Secret key of the CloudStack API. If not set, the CLOUDSTACK_SECRET env variable is considered.
api_timeout integer	HTTP timeout in seconds. If not given, the CLOUDSTACK_TIMEOUT env variable is considered. Default: 10
api_url string / required	URL of the CloudStack API e.g. https://cloud.example.com/client/api. If not given, the CLOUDSTACK_ENDPOINT env variable is considered.
api_verify_ssl_cert string	Verify CA authority cert file. If not given, the CLOUDSTACK_VERIFY env variable is considered.
description string	Description of the internal load balancer. Only used on creation, see the notes below.
domain string	Domain the internal load balancer is related to.
for_display boolean	Whether the internal load balancer is displayed to the regular user. Requires an admin account to be idempotent, see the notes below. Choices: false true
force boolean	Whether to delete and recreate the internal load balancer when an option which can not be updated differs from the existing one. Without it, such a difference only produces a warning and the load balancer is left unchanged. Only considered on state=present. See the notes below for the consequences. Choices: false ← (default) true
instance_port integer	Port on the balanced instances traffic is forwarded to. Required on state=present. Can not be changed after creation.
name string / required	Name of the internal load balancer.
network string / required	Name of the VPC tier the internal load balancer balances traffic to. The network offering of this tier must support the LB service with the InternalLbVm provider.
poll_async boolean	Poll async jobs until job has finished. Choices: false true ← (default)
project string	Name of the project the internal load balancer is related to.
source_ip string	Source IP address of the internal load balancer. Automatically allocated from source_ip_network when not given. On force=true, the address of the existing load balancer is kept when not given. Can not be changed after creation.
source_ip_network string	Name of the network the source IP address is taken from. Defaults to network when not given. Can not be changed after creation.
source_port integer	Source port the internal load balancer listens on. Required on state=present. Can not be changed after creation.
state string	State of the internal load balancer. Choices: "present" ← (default) "absent"
validate_certs boolean added in ngine_io.cloudstack 2.4.0	If false, SSL certificates will not be validated. If not given, the CLOUDSTACK_DANGEROUS_NO_TLS_VERIFY env variable is considered. This should only be used on personally controlled sites using self-signed certificates. Choices: false true ← (default)
vpc string	Name of the VPC the network belongs to.
zone string / required	Name of the zone the internal load balancer belongs to.

Notes

Note

• The CloudStack API only allows for_display to be updated on an existing internal load balancer. When any other option differs, this module leaves the load balancer as it is and warns, naming the differing options, so a live load balancer is never torn down by an unrelated playbook run. Set force=true to delete and recreate it instead, or use state=absent followed by state=present.

• force=true only acts when an option actually differs, so it stays idempotent and can safely be driven by a playbook variable.

• Recreating drops every member assigned to the load balancer. Re-apply them with ngine_io.cloudstack.lb_internal_member afterwards.

• Recreating keeps the source IP address of the existing load balancer, so the address stays stable across a recreate. Give source_ip to move it to a different address.

• The API returns fordisplay to admin accounts only. When running as a regular user, this module can not detect drift on for_display and will emit a warning instead of updating it. for_display is always applied on creation.

• The API does not return description at all, so it can neither be verified nor changed after creation.

• Members are managed separately and are not in the scope of this module. They can be assigned using the assignToLoadBalancerRule API.

• A detailed guide about cloudstack modules can be found in the CloudStack Cloud Guide.

• This module supports check mode.

Examples

- name: Ensure an internal load balancer is present
  ngine_io.cloudstack.lb_internal:
    name: web-ilb
    vpc: my-vpc
    network: web-tier
    zone: zone01
    source_port: 80
    instance_port: 8080
    algorithm: roundrobin

- name: Ensure an internal load balancer with a fixed source IP
  ngine_io.cloudstack.lb_internal:
    name: web-ilb
    vpc: my-vpc
    network: web-tier
    zone: zone01
    source_port: 80
    instance_port: 8080
    source_ip: 10.10.1.100

- name: Ensure an internal load balancer, recreating it if an immutable option changed
  ngine_io.cloudstack.lb_internal:
    name: web-ilb
    vpc: my-vpc
    network: web-tier
    zone: zone01
    source_port: 8080
    instance_port: 8080
    force: true

- name: Ensure an internal load balancer is absent
  ngine_io.cloudstack.lb_internal:
    name: web-ilb
    vpc: my-vpc
    network: web-tier
    zone: zone01
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
account string	Account the internal load balancer is related to. Returned: when available Sample: "example-account"
algorithm string	Load balancing algorithm used. Returned: success Sample: "roundrobin"
domain string	Domain the internal load balancer is related to. Returned: when available Sample: "ROOT"
for_display boolean	Whether the internal load balancer is displayed to the regular user. Returned: when running as an admin account Sample: true
id string	UUID of the internal load balancer. Returned: success Sample: "a5396f25-945f-4968-854e-8400af7bee97"
instance_port integer	Port on the balanced instances traffic is forwarded to. Returned: success Sample: 8080
name string	Name of the internal load balancer. Returned: success Sample: "web-ilb"
network string	Name of the network the internal load balancer balances traffic to. Returned: success Sample: "web-tier"
network_id string	UUID of the network the internal load balancer balances traffic to. Returned: success Sample: "e83f0010-4e08-493f-acc8-f5205d83b30d"
project string	Name of the project the internal load balancer is related to. Returned: when available Sample: "Production"
source_ip string	Source IP address of the internal load balancer. Returned: success Sample: "10.10.1.247"
source_ip_network_id string	UUID of the network the source IP address is taken from. Returned: success Sample: "e83f0010-4e08-493f-acc8-f5205d83b30d"
source_port integer	Source port the internal load balancer listens on. Returned: success Sample: 80
state string	State of the internal load balancer rule. Returned: success Sample: "Active"
zone string	Name of the zone the internal load balancer belongs to. Returned: success Sample: "zone01"

Authors

• Mitch Drage (@MitchDrage)

Collection links

• Issue Tracker
• Repository (Sources)