New in version 2.0.
The below requirements are needed on the host that executes this module.
Parameter | Choices/Defaults | Comments |
---|---|---|
account
string
|
Account the instance is related to.
|
|
affinity_groups
list
|
Affinity groups names to be applied to the new instance.
aliases: affinity_group |
|
allow_root_disk_shrink
boolean
added in 2.7 |
|
Enables a volume shrinkage when the new size is smaller than the old one.
|
api_http_method
string
|
|
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
string
|
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
string
|
Default: "cloudstack"
|
Name of the ini section in the
cloustack.ini file.If not given, the
CLOUDSTACK_REGION env variable is considered. |
api_secret
string
|
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
integer
|
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
string
|
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.
|
|
cpu
integer
|
The number of CPUs to allocate to the instance, used with custom service offerings
|
|
cpu_speed
integer
|
The clock speed/shares allocated to the instance, used with custom service offerings
|
|
details
dictionary
added in 2.6 |
Map to specify custom parameters.
|
|
disk_offering
string
|
Name of the disk offering to be used.
|
|
disk_size
integer
|
Disk size in GByte required if deploying instance from ISO.
|
|
display_name
string
|
Custom display name of the instances.
Display name will be set to name if not specified.
Either name or display_name is required.
|
|
domain
string
|
Domain the instance is related to.
|
|
force
boolean
|
|
Force stop/start the instance if required to apply changes, otherwise a running instance will not be changed.
|
group
string
|
Group in where the new instance should be in.
|
|
host
string
added in 2.6 |
Host on which an instance should be deployed or started on.
Only considered when state=started or instance is running.
Requires root admin privileges.
|
|
hypervisor
string
|
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
KVM , VMware , BareMetal , XenServer , LXC , HyperV , UCS , OVM , Simulator . |
|
ip6_address
string
|
IPv6 address for default instance's network.
|
|
ip_address
string
|
IPv4 address for default instance's network during creation.
|
|
ip_to_networks
list
|
List of mappings in the form {'network': NetworkName, 'ip': 1.2.3.4}
Mutually exclusive with networks option.
aliases: ip_to_network |
|
iso
string
|
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
string
|
|
Keyboard device type for the instance.
|
memory
integer
|
The memory allocated to the instance, used with custom service offerings
|
|
name
string
|
Host name of the instance.
name can only contain ASCII letters.Name will be generated (UUID) by CloudStack if not specified and can not be changed afterwards.
Either
name or display_name is required. |
|
networks
list
|
List of networks to use for the new instance.
aliases: network |
|
poll_async
boolean
|
|
Poll async jobs until job has finished.
|
project
string
|
Name of the project the instance to be deployed in.
|
|
root_disk_size
integer
|
Root disk size in GByte required if deploying instance with KVM hypervisor and want resize the root disk size at startup (need CloudStack >= 4.4, cloud-initramfs-growroot installed and enabled in the template)
|
|
security_groups
list
|
List of security groups the instance to be applied to.
aliases: security_group |
|
service_offering
string
|
Name or id of the service offering of the new instance.
If not set, first found service offering is used.
|
|
ssh_key
string
|
Name of the SSH key to be deployed on the new instance.
|
|
state
string
|
|
State of the instance.
|
tags
list
|
List of tags. Tags are a list of dictionaries having keys
key and value .If you want to delete all tags, set a empty list e.g. tags: [].
aliases: tag |
|
template
string
|
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.
|
|
template_filter
string
added in 2.1 |
|
Name of the filter used to search for the template or iso.
Used for params iso or template on state=present.
The filter
all was added in 2.6.aliases: iso_filter |
user_data
string
|
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.
|
|
zone
string
|
Name of the zone in which the instance should be deployed.
If not set, default zone is used.
|
Note
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.# NOTE: Names of offerings and ISOs depending on the CloudStack configuration.
- name: create a instance from an ISO
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
delegate_to: localhost
- name: for changing a running instance, use the 'force' parameter
cs_instance:
name: web-vm-1
display_name: web-vm-01.example.com
iso: Linux Debian 7 64-bit
service_offering: 2cpu_2gb
force: yes
delegate_to: localhost
# 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.
cs_instance:
display_name: web-vm-1
template: Linux Debian 7 64-bit
service_offering: Tiny
ssh_key: john@example.com
tags:
- key: admin
value: john
- key: foo
value: bar
user_data: |
#cloud-config
packages:
- nginx
delegate_to: localhost
- name: create an instance with multiple interfaces specifying the IP addresses
cs_instance:
name: web-vm-1
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
delegate_to: localhost
- name: ensure an instance is stopped
cs_instance:
name: web-vm-1
state: stopped
delegate_to: localhost
- name: ensure an instance is running
cs_instance:
name: web-vm-1
state: started
delegate_to: localhost
- name: remove an instance
cs_instance:
name: web-vm-1
state: absent
delegate_to: localhost
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
account
string
|
success |
Account the instance is related to.
Sample:
example account
|
affinity_groups
list
|
success |
Affinity groups the instance is in.
Sample:
[ "webservers" ]
|
created
string
|
success |
Date of the instance was created.
Sample:
2014-12-01T14:57:57+0100
|
default_ip
string
|
success |
Default IP address of the instance.
Sample:
10.23.37.42
|
default_ip6
string
added in 2.6 |
if available |
Default IPv6 address of the instance.
Sample:
2a04:c43:c00:a07:4b4:beff:fe00:74
|
display_name
string
|
success |
Display name of the instance.
Sample:
web-01
|
domain
string
|
success |
Domain the instance is related to.
Sample:
example domain
|
group
string
|
success |
Group name of the instance is related.
Sample:
web
|
host
string
added in 2.6 |
success and instance is running |
Hostname of hypervisor an instance is running on.
Sample:
host-01.example.com
|
hypervisor
string
|
success |
Hypervisor related to this instance.
Sample:
KVM
|
id
string
|
success |
UUID of the instance.
Sample:
04589590-ac63-4ffc-93f5-b698b8ac38b6
|
instance_name
string
|
success |
Internal name of the instance (ROOT admin only).
Sample:
i-44-3992-VM
|
iso
string
|
if available |
Name of ISO the instance was deployed with.
Sample:
Debian-8-64bit
|
name
string
|
success |
Name of the instance.
Sample:
web-01
|
password
string
|
if available |
The password of the instance if exists.
Sample:
Ge2oe7Do
|
password_enabled
boolean
|
success |
True if password setting is enabled.
Sample:
True
|
project
string
|
success |
Name of project the instance is related to.
Sample:
Production
|
public_ip
string
|
if available |
Public IP address with instance via static NAT rule.
Sample:
1.2.3.4
|
security_groups
list
|
success |
Security groups the instance is in.
Sample:
[ "default" ]
|
service_offering
string
|
success |
Name of the service offering the instance has.
Sample:
2cpu_2gb
|
ssh_key
string
|
if available |
Name of SSH key deployed to instance.
Sample:
key@work
|
state
string
|
success |
State of the instance.
Sample:
Running
|
tags
list
|
success |
List of resource tags associated with the instance.
Sample:
[ { "key": "foo", "value": "bar" } ]
|
template
string
|
success |
Name of template the instance was deployed with.
Sample:
Linux Debian 9 64-bit
|
template_display_text
string
added in 2.6 |
success |
Display text of template the instance was deployed with.
Sample:
Linux Debian 9 64-bit 200G Disk (2017-10-08-622866)
|
user-data
string
|
success |
Optional data sent to the instance.
Sample:
VXNlciBkYXRhIGV4YW1wbGUK
|
zone
string
|
success |
Name of zone the instance is in.
Sample:
ch-gva-2
|
Hint
If you notice any issues in this documentation you can edit this document to improve it.