- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# cs_template – Manages templates on Apache CloudStack based clouds

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## Synopsis

- Register templates from an URL.

- Create templates from a ROOT volume of a stopped VM or its snapshot.

- Update (since version 2.7), extract and delete templates.

## 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 template, snapshot or VM is related to.
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.
bits integer | Choices: 32 64 ← | 32 or 64 bits support.
checksum string |  | The MD5 checksum value of this template. If set, we search by checksum instead of name.
cross_zones boolean | Choices: no ← yes | Whether the template should be synced or removed across zones. Only used if state is `present` or `absent`.
details string |  | Template details in key/value pairs.
display_text string |  | Display text of the template.
domain string |  | Domain the template, snapshot or VM is related to.
format string | Choices: QCOW2 RAW VHD OVA | The format for the template. Only considered if state=present.
hypervisor string |  | Name the hypervisor to be used for creating the new template. Relevant when using state=present. Possible values are `KVM`, `VMware`, `BareMetal`, `XenServer`, `LXC`, `HyperV`, `UCS`, `OVM`, `Simulator`.
is_dynamically_scalable boolean | Choices: no yes | Register the template having XS/VMware tools installed in order to support dynamic scaling of VM CPU/memory. Only used if state is `present`.
is_extractable boolean | Choices: no yes | Allows the template or its derivatives to be extractable.
is_featured boolean | Choices: no yes | Register the template to be featured. Only used if state is `present`.
is_public boolean | Choices: no yes | Register the template to be publicly available to all users. Only used if state is `present`.
is_ready boolean | Choices: no yes | Note: this flag was not implemented and therefore marked as deprecated. Deprecated, will be removed in version 2.11.
is_routing boolean | Choices: no yes | Sets the template type to routing, i.e. if template is used to deploy routers. Only considered if url is used.
mode string | Choices: http_download ← ftp_upload | Mode for the template extraction. Only used if state=extracted.
name string / required |  | Name of the template.
os_type string |  | OS type that best represents the OS of this template.
password_enabled boolean | Choices: no yes | Enable template password reset support.
poll_async boolean | Choices: no yes ← | Poll async jobs until job has finished.
project string |  | Name of the project the template to be registered in.
requires_hvm boolean | Choices: no yes | Whether the template requires HVM or not. Only considered while creating the template.
snapshot string |  | Name of the snapshot, created from the VM ROOT volume, the template will be created from. vm is required together with this argument.
sshkey_enabled boolean | Choices: no yes | True if the template supports the sshkey upload feature. Only considered if url is used (API limitation).
state string | Choices: present ← absent extracted | State of the template.
tags list added in 2.4 |  | List of tags. Tags are a list of dictionaries having keys key and value. To delete all tags, set a empty list e.g. tags: []. aliases: tag
template_filter string | Choices: all featured self ← selfexecutable sharedexecutable executable community | Name of the filter used to search for the template. The filter `all` was added in 2.7.
template_find_options list added in 2.7 | Choices: display_text checksum cross_zones Default: [] | Options to find a template uniquely. More than one allowed. aliases: template_find_option
template_tag string |  | The tag for this template.
url string |  | URL of where the template is hosted on state=present. URL to which the template would be extracted on state=extracted. Mutually exclusive with vm.
vm string |  | VM name the template will be created from its volume or alternatively from a snapshot. VM must be in stopped state if created from its volume. Mutually exclusive with url.
zone string |  | Name of the zone you wish the template to be registered or deleted from. If not specified, first found zone will be 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: register a systemvm template
      cs_template:
        name: systemvm-vmware-4.5
        url: "http://packages.shapeblue.com/systemvmtemplate/4.5/systemvm64template-4.5-vmware.ova"
        hypervisor: VMware
        format: OVA
        cross_zones: yes
        os_type: Debian GNU/Linux 7(64-bit)
      delegate_to: localhost

    - name: Create a template from a stopped virtual machine's volume
      cs_template:
        name: Debian 9 (64-bit) 20GB ({{ ansible_date_time.date }})
        vm: debian-9-base-vm
        os_type: Debian GNU/Linux 9 (64-bit)
        zone: tokio-ix
        password_enabled: yes
        is_public: yes
      delegate_to: localhost

    # Note: Use template_find_option(s) when a template name is not unique
    - name: Create a template from a stopped virtual machine's volume
      cs_template:
        name: Debian 9 (64-bit)
        display_text: Debian 9 (64-bit) 20GB ({{ ansible_date_time.date }})
        template_find_option: display_text
        vm: debian-9-base-vm
        os_type: Debian GNU/Linux 9 (64-bit)
        zone: tokio-ix
        password_enabled: yes
        is_public: yes
      delegate_to: localhost

    - name: create a template from a virtual machine's root volume snapshot
      cs_template:
        name: Debian 9 (64-bit) Snapshot ROOT-233_2015061509114
        snapshot: ROOT-233_2015061509114
        os_type: Debian GNU/Linux 9 (64-bit)
        zone: tokio-ix
        password_enabled: yes
        is_public: yes
      delegate_to: localhost

    - name: Remove a template
      cs_template:
        name: systemvm-4.2
        cross_zones: yes
        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 template is related to. Sample: example account
checksum string | if available | MD5 checksum of the template. Sample: 0b31bccccb048d20b551f70830bb7ad0
created string | success | Date of registering. Sample: 2015-03-29T14:57:06+0200
cross_zones boolean | if available | true if the template is managed across all zones, false otherwise.
display_text string | if available | Display text of the template. Sample: Debian 7.7 64-bit minimal 2015-03-19
domain string | success | Domain the template is related to. Sample: example domain
format string | if available | Format of the template. Sample: OVA
hypervisor string | if available | Hypervisor related to this template. Sample: VMware
id string | success | UUID of the template or extracted object. Sample: a6f7a5fc-43f8-11e5-a151-feff819cdc9f
is_extractable boolean | if available | True if the template is extractable. Sample: True
is_featured boolean | if available | True if the template is featured. Sample: True
is_public boolean | if available | True if the template is public. Sample: True
is_ready boolean | if available | True if the template is ready to be deployed from. Sample: True
mode string | on state=extracted | Mode of extraction Sample: http_download
name string | success | Name of the template or extracted object. Sample: Debian 7 64-bit
os_type string | if available | Type of the OS. Sample: CentOS 6.5 (64-bit)
password_enabled boolean | if available | True if the reset password feature is enabled, false otherwise.
project string | success | Name of project the template is related to. Sample: Production
sshkey_enabled boolean | if available | true if template is sshkey enabled, false otherwise.
state string | on state=extracted | State of the extracted template Sample: DOWNLOAD_URL_CREATED
status string | success | Status of the template or extracted object. Sample: Download Complete
tags list | if available | List of resource tags associated with the template. Sample: [ { "key": "foo", "value": "bar" } ]
template_tag string | if available | Template tag related to this template. Sample: special
template_type string | if available | Type of the template. Sample: USER
url string | on state=extracted | Url to which the template is extracted to Sample: http://1.2.3.4/userdata/eb307f13-4aca-45e8-b157-a414a14e6b04.ova
zone string | success | Name of zone the template is registered in. Sample: zuerich

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