ngine_io.cloudstack.cs_instance module – Manages instances and virtual machines on Apache CloudStack based clouds.
Note
This module is part of the ngine_io.cloudstack collection (version 2.5.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.cs_instance.
New in ngine_io.cloudstack 0.1.0
Synopsis
Deploy, start, update, scale, restart, restore, stop and destroy instances.
Requirements
The below requirements are needed on the host that executes this module.
python >= 2.6
cs >= 0.9.0
Parameters
Parameter |
Comments |
|---|---|
Account the instance is related to. |
|
Affinity groups names to be applied to the new instance. |
|
Enables a volume shrinkage when the new size is smaller than the old one. Choices:
|
|
HTTP method used to query the API endpoint. If not given, the Choices:
|
|
API key of the CloudStack API. If not given, the |
|
Secret key of the CloudStack API. If not set, the |
|
HTTP timeout in seconds. If not given, the Default: |
|
URL of the CloudStack API e.g. https://cloud.example.com/client/api. If not given, the |
|
Verify CA authority cert file. If not given, the |
|
Cluster on which an instance should be deployed or started on. Only considered when state=started or instance is running. Requires root admin privileges. |
|
The number of CPUs to allocate to the instance, used with custom service offerings |
|
The clock speed/shares allocated to the instance, used with custom service offerings |
|
Map to specify custom parameters. |
|
Name of the disk offering to be used. |
|
Disk size in GByte required if deploying instance from ISO. |
|
Custom display name of the instances. Display name will be set to name if not specified. Either name or display_name is required. |
|
Domain the instance is related to. |
|
Force stop/start the instance if required to apply changes, otherwise a running instance will not be changed. Choices:
|
|
Group in where the new instance should be in. |
|
Host on which an instance should be deployed or started on. Only considered when state=started or instance is running. Requires root admin privileges. |
|
Name the hypervisor to be used for creating the new instance. Relevant when using state=present, but only considered if not set on ISO/template. If not set or found on ISO/template, first found hypervisor will be used. Possible values are |
|
IPv6 address for default instance’s network. |
|
IPv4 address for default instance’s network during creation. |
|
List of mappings in the form {‘network’: NetworkName, ‘ip’: 1.2.3.4} Mutually exclusive with networks option. |
|
Name or id of the ISO to be used for creating the new instance. Required when using state=present. Mutually exclusive with template option. |
|
Keyboard device type for the instance. Choices:
|
|
The memory allocated to the instance, used with custom service offerings |
|
Host name of the instance. Name will be generated (UUID) by CloudStack if not specified and can not be changed afterwards. Either |
|
List of networks to use for the new instance. |
|
Pod on which an instance should be deployed or started on. Only considered when state=started or instance is running. Requires root admin privileges. |
|
Poll async jobs until job has finished. Choices:
|
|
Name of the project the instance to be deployed in. |
|
Root disk size in GByte required if deploying instance with KVM hypervisor and want resize the root disk size at startup (needs CloudStack >= 4.4, cloud-initramfs-growroot installed and enabled in the template). |
|
List of security groups the instance to be applied to. |
|
Name or id of the service offering of the new instance. If not set, first found service offering is used. |
|
Name of the SSH key to be deployed on the new instance. |
|
State of the instance. Choices:
|
|
List of tags. Tags are a list of dictionaries having keys If you want to delete all tags, set a empty list e.g. tags: []. |
|
Name, display text or id of the template to be used for creating the new instance. Required when using state=present. Mutually exclusive with iso option. |
|
Name of the filter used to search for the template or iso. Used for params iso or template on state=present. Choices:
|
|
Optional data (ASCII) that can be sent to the instance upon a successful deployment. The data will be automatically base64 encoded. Consider switching to HTTP_POST by using CLOUDSTACK_METHOD=post to increase the HTTP_GET size limit of 2KB to 32 KB. Mutually exclusive with user_data_name option. |
|
Map used to specify the parameters values for the variables in userdata. |
|
Name of user data to be used. Mutually exclusive with user_data option. |
|
If If not given, the This should only be used on personally controlled sites using self-signed certificates. Choices:
|
|
Name of the zone in which the instance should be deployed. |
Notes
Note
A detailed guide about cloudstack modules can be found in the CloudStack Cloud Guide.
This module supports check mode.
Examples
# NOTE: Names of offerings and ISOs depending on the CloudStack configuration.
- name: create a instance from an ISO
ngine_io.cloudstack.cs_instance:
name: web-vm-1
iso: Linux Debian 7 64-bit
hypervisor: VMware
project: Integration
zone: ch-zrh-ix-01
service_offering: 1cpu_1gb
disk_offering: PerfPlus Storage
disk_size: 20
networks:
- Server Integration
- Sync Integration
- Storage Integration
- name: for changing a running instance, use the 'force' parameter
ngine_io.cloudstack.cs_instance:
name: web-vm-1
zone: zone01
display_name: web-vm-01.example.com
iso: Linux Debian 7 64-bit
service_offering: 2cpu_2gb
force: yes
# NOTE: user_data can be used to kickstart the instance using cloud-init yaml config.
- name: create or update a instance on Exoscale's public cloud using display_name.
ngine_io.cloudstack.cs_instance:
display_name: web-vm-1
zone: zone01
template: Linux Debian 7 64-bit
service_offering: Tiny
ssh_key: [email protected]
tags:
- key: admin
value: john
- key: foo
value: bar
user_data: |
#cloud-config
packages:
- nginx
- name: create an instance with multiple interfaces specifying the IP addresses
ngine_io.cloudstack.cs_instance:
name: web-vm-1
zone: zone01
template: Linux Debian 7 64-bit
service_offering: Tiny
ip_to_networks:
- network: NetworkA
ip: 10.1.1.1
- network: NetworkB
ip: 192.0.2.1
- name: ensure an instance is stopped
ngine_io.cloudstack.cs_instance:
name: web-vm-1
zone: zone01
state: stopped
- name: ensure an instance is running
ngine_io.cloudstack.cs_instance:
name: web-vm-1
zone: zone01
state: started
- name: remove an instance
ngine_io.cloudstack.cs_instance:
name: web-vm-1
zone: zone01
state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Account the instance is related to. Returned: success Sample: |
|
Affinity groups the instance is in. Returned: success Sample: |
|
Date of the instance was created. Returned: success Sample: |
|
Default IP address of the instance. Returned: success Sample: |
|
Default IPv6 address of the instance. Returned: if available Sample: |
|
Display name of the instance. Returned: success Sample: |
|
Domain the instance is related to. Returned: success Sample: |
|
Group name of the instance is related. Returned: success Sample: |
|
Hostname of hypervisor an instance is running on. Returned: success and instance is running Sample: |
|
Hypervisor related to this instance. Returned: success Sample: |
|
UUID of the instance. Returned: success Sample: |
|
Internal name of the instance (ROOT admin only). Returned: success Sample: |
|
Name of ISO the instance was deployed with. Returned: if available Sample: |
|
Name of the instance. Returned: success Sample: |
|
The password of the instance if exists. Returned: if available Sample: |
|
True if password setting is enabled. Returned: success Sample: |
|
Name of project the instance is related to. Returned: success Sample: |
|
Public IP address with instance via static NAT rule. Returned: if available Sample: |
|
Security groups the instance is in. Returned: success Sample: |
|
Name of the service offering the instance has. Returned: success Sample: |
|
Name of SSH key deployed to instance. Returned: if available Sample: |
|
Names of SSH key deployed to instance. Returned: if available Sample: |
|
State of the instance. Returned: success Sample: |
|
List of resource tags associated with the instance. Returned: success Sample: |
|
Name of template the instance was deployed with. Returned: success Sample: |
|
Display text of template the instance was deployed with. Returned: success Sample: |
|
Optional data sent to the instance. Returned: success Sample: |
|
Name of zone the instance is in. Returned: success Sample: |