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