Documentation

cs_host - Manages hosts on Apache CloudStack based clouds.

New in version 2.3.

Synopsis

  • Create, update and remove hosts.

Requirements

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

  • python >= 2.6
  • cs >= 0.6.10

Parameters

Parameter Choices/Defaults Comments
allocation_state
    Choices:
  • enabled
  • disabled
Allocation state of the host.
api_http_method
    Choices:
  • get
  • post
HTTP method used to query the API endpoint.
If not given, the CLOUDSTACK_METHOD env variable is considered.
As the last option, the value is taken from the ini config file, also see the notes.
Fallback value is get if not specified.
api_key
API key of the CloudStack API.
If not given, the CLOUDSTACK_KEY env variable is considered.
As the last option, the value is taken from the ini config file, also see the notes.
api_region Default:
cloudstack
Name of the ini section in the cloustack.ini file.
If not given, the CLOUDSTACK_REGION env variable is considered.
api_secret
Secret key of the CloudStack API.
If not set, the CLOUDSTACK_SECRET env variable is considered.
As the last option, the value is taken from the ini config file, also see the notes.
api_timeout
HTTP timeout in seconds.
If not given, the CLOUDSTACK_TIMEOUT env variable is considered.
As the last option, the value is taken from the ini config file, also see the notes.
Fallback value is 10 seconds if not specified.
api_url
URL of the CloudStack API e.g. https://cloud.example.com/client/api.
If not given, the CLOUDSTACK_ENDPOINT env variable is considered.
As the last option, the value is taken from the ini config file, also see the notes.
cluster
Name of the cluster.
host_tags
Tags of the host.

aliases: host_tag
hypervisor
    Choices:
  • KVM
  • VMware
  • BareMetal
  • XenServer
  • LXC
  • HyperV
  • UCS
  • OVM
  • Simulator
Name of the cluster.
Required if state=present and host does not yet exist.
name
required
Name of the host.

aliases: ip_address
password
Password for the host.
Required if state=present and host does not yet exist.
pod
Name of the pod.
Required if state=present and host does not yet exist.
state
    Choices:
  • present ←
  • absent
State of the host.
url
Url of the host used to create a host.
If not provided, http:// and param name is used as url.
Only considered if state=present and host does not yet exist.
username
Username for the host.
Required if state=present and host does not yet exist.
zone
Name of the zone in which the host should be deployed.
If not set, default zone is used.

Notes

Note

  • Ansible uses the cs library’s configuration method if credentials are not provided by the arguments api_url, api_key, api_secret. Configuration is read from several locations, in the following order. The CLOUDSTACK_ENDPOINT, CLOUDSTACK_KEY, CLOUDSTACK_SECRET and CLOUDSTACK_METHOD. CLOUDSTACK_TIMEOUT environment variables. A CLOUDSTACK_CONFIG environment variable pointing to an .ini file. A cloudstack.ini file in the current working directory. A .cloudstack.ini file in the users home directory. Optionally multiple credentials and endpoints can be specified using ini sections in cloudstack.ini. Use the argument api_region to select the section name, default section is cloudstack. See https://github.com/exoscale/cs for more information.
  • A detailed guide about cloudstack modules can be found in the CloudStack Cloud Guide.
  • This module supports check mode.

Examples

- name: Ensure a host is present but disabled
  local_action:
    module: cs_host
    name: ix-pod01-esx01.example.com
    cluster: vcenter.example.com/ch-zrh-ix/pod01-cluster01
    pod: pod01
    zone: ch-zrh-ix-01
    hypervisor: VMware
    allocation_state: disabled
    host_tags:
    - perf
    - gpu

- name: Ensure an existing host is disabled
  local_action:
    module: cs_host
    name: ix-pod01-esx01.example.com
    zone: ch-zrh-ix-01
    allocation_state: disabled

- name: Ensure an existing host is enabled
  local_action:
    module: cs_host
    name: ix-pod01-esx01.example.com
    zone: ch-zrh-ix-01
    allocation_state: enabled

- name: Ensure a host is absent
  local_action:
    module: cs_host
    name: ix-pod01-esx01.example.com
    zone: ch-zrh-ix-01
    state: absent

Return Values

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

Key Returned Description
allocation_state:
string
success
Allocation state of the host.

Sample:
enabled
capabilities
string
success
Capabilities of the host.

Sample:
hvm
cluster
string
success
Cluster of the host.

Sample:
vcenter.example.com/zone/cluster01
cluster_type
string
success
Type of the cluster of the host.

Sample:
ExternalManaged
cpu_allocated
string
success
Amount in percent of the host's CPU currently allocated.

Sample:
166.25%
cpu_number
string
success
Number of CPUs of the host.

Sample:
24
cpu_sockets
int
success
Number of CPU sockets of the host.

Sample:
2
cpu_speed
int
success
CPU speed in Mhz

Sample:
1999
cpu_used
string
success
Amount of the host's CPU currently used.

Sample:
33.6%
cpu_with_overprovisioning
string
success
Amount of the host's CPU after applying the cpu.overprovisioning.factor.

Sample:
959520.0
created
string
success
Date when the host was created.

Sample:
2015-05-03T15:05:51+0200
disconnected
string
success
Date when the host was disconnected.

Sample:
2015-05-03T15:05:51+0200
disk_size_allocated
int
success
Host's currently allocated disk size.

Sample:
2593
disk_size_total
int
success
Total disk size of the host

Sample:
259300
events
string
success
Events available for the host

Sample:
Ping; HostDown; AgentConnected; AgentDisconnected; PingTimeout; ShutdownRequested; Remove; StartAgentRebalance; ManagementServerDown
gpu_group
list
success
GPU cards present in the host.

ha_host
bool
success
Whether the host is a HA host.

has_enough_capacity
bool
success
Whether the host has enough CPU and RAM capacity to migrate a VM to it.

Sample:
True
host_tags
string
success
Comma-separated list of tags for the host.

Sample:
perf
host_type
string
success
Type of the host.

Sample:
Routing
host_version
string
success
Version of the host.

Sample:
4.5.2
hypervisor
string
success
Host's hypervisor.

Sample:
VMware
hypervisor_version
string
success
Hypervisor version.

Sample:
5.1
ip_address
string
success
IP address of the host

Sample:
10.10.10.1
is_local_storage_active
bool
success
Whether the local storage is available or not.

last_pinged
string
success
Date and time the host was last pinged.

Sample:
1970-01-17T17:27:32+0100
management_server_id
int
success
Management server ID of the host.

Sample:
345050593418
memory_allocated
int
success
Amount of the host's memory currently allocated.

Sample:
69793218560
memory_total
int
success
Total of memory of the host.

Sample:
206085263360
memory_used
int
success
Amount of the host's memory currently used.

Sample:
65504776192
name
string
success
Name of the host.

Sample:
esx32.example.com
network_kbs_read
int
success
Incoming network traffic on the host.

network_kbs_write
int
success
Outgoing network traffic on the host.

os_category
string
success
OS category name of the host.

Sample:
...
out_of_band_management
string
success
Host out-of-band management information.

Sample:
...
pod
string
success
Pod name of the host.

Sample:
Pod01
removed
string
success
Date and time the host was removed.

Sample:
1970-01-17T17:27:32+0100
resource_state
string
success
Resource state of the host.

Sample:
Enabled
state
string
success
State of the host.

Sample:
Up
suitable_for_migration
string
success
Whether this host is suitable (has enough capacity and satisfies all conditions like hosttags, max guests VM limit, etc) to migrate a VM to it or not.

Sample:
True
zone
string
success
Zone of the host.

Sample:
zone01


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • René Moser (@resmo)

Hint

If you notice any issues in this documentation you can edit this document to improve it.