# cs_instance – Manages instances and virtual machines on Apache CloudStack based clouds

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## 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.6.10

## Parameters

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

Choices:
- no ←
- yes

Enables a volume shrinkage when the new size is smaller than the old one.

api_http_method
string

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 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

Choices:
- no ←
- yes

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

Choices:
- de
- de-ch
- es
- fi
- fr
- fr-be
- fr-ch
- is
- it
- jp
- nl-be
- no
- pt
- uk
- us

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

Choices:
- no
- yes ←

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

Choices:
- deployed
- started
- stopped
- restarted
- restored
- destroyed
- expunged
- present ←
- absent

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

Choices:
- all
- featured
- self
- selfexecutable
- sharedexecutable
- executable ←
- community

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.

## 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

    # 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

## Return Values

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

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]

- This module is maintained by the Ansible Community. [community]

### Authors

- René Moser (@resmo)

Hint

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