openstack.cloud.server module – Create/Delete Compute Instances from OpenStack

Note

This module is part of the openstack.cloud collection (version 2.3.2).

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 openstack.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: openstack.cloud.server.

Synopsis

• Create or Remove compute instances from OpenStack.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 3.6

• openstacksdk >= 1.0.0

Parameters

Parameter	Comments
api_timeout integer	How long should the socket layer wait before timing out for API calls. If this is omitted, nothing will be passed to the requests library.
auth dictionary	Dictionary containing auth information as needed by the cloud’s auth plugin strategy. For the default password plugin, this would contain auth_url, username, password, project_name and any information about domains (for example, user_domain_name or project_domain_name) if the cloud supports them. For other plugins, this param will need to contain whatever parameters that auth plugin requires. This parameter is not needed if a named cloud is provided or OpenStack OS_* environment variables are present.
auth_type string	Name of the auth plugin to use. If the cloud uses something other than password authentication, the name of the plugin should be indicated here and the contents of the auth parameter should be updated accordingly.
auto_ip aliases: auto_floating_ip, public_ip boolean	Ensure instance has public ip however the cloud wants to do that. For example, the cloud could add a floating ip for the server or attach the server to a public network. Requires wait to be True during server creation. Floating IP support is unstable in this module, use with caution. Options auto_ip, floating_ip_pools and floating_ips interact in non-obvious ways and undocumentable depth. For explicit and safe attaching and detaching of floating ip addresses use module openstack.cloud.resource instead. Choices: false true ← (default)
availability_zone string	Availability zone in which to create the server. This server attribute cannot be updated.
boot_from_volume boolean	Should the instance boot from a persistent volume created based on the image given. Mutually exclusive with boot_volume. This server attribute cannot be updated. Choices: false ← (default) true
boot_volume aliases: root_volume string	Volume name or id to use as the volume to boot from. Implies boot_from_volume. Mutually exclusive with image and boot_from_volume. This server attribute cannot be updated.
ca_cert aliases: cacert string	A path to a CA Cert bundle that can be used as part of verifying SSL API requests.
client_cert aliases: cert string	A path to a client certificate to use as part of the SSL transaction.
client_key aliases: key string	A path to a client key to use as part of the SSL transaction.
cloud any	Named cloud or cloud config to operate against. If cloud is a string, it references a named cloud config as defined in an OpenStack clouds.yaml file. Provides default values for auth and auth_type. This parameter is not needed if auth is provided or if OpenStack OS_* environment variables are present. If cloud is a dict, it contains a complete cloud configuration like would be in a section of clouds.yaml.
config_drive boolean	Whether to boot the server with config drive enabled. This server attribute cannot be updated. Choices: false ← (default) true
delete_ips aliases: delete_fip boolean	When state is absent and this option is true, any floating IP address associated with this server will be deleted along with it. Floating IP support is unstable in this module, use with caution. Choices: false ← (default) true
description string	Description of the server.
flavor string	The name or id of the flavor in which the new instance has to be created. Exactly one of flavor and flavor_ram must be defined when state=present. This server attribute cannot be updated.
flavor_include string	Text to use to filter flavor names, for the case, such as Rackspace, where there are multiple flavors that have the same ram count. flavor_include is a positive match filter - it must exist in the flavor name. This server attribute cannot be updated.
flavor_ram integer	The minimum amount of ram in MB that the flavor in which the new instance has to be created must have. Exactly one of flavor and flavor_ram must be defined when state=present. This server attribute cannot be updated.
floating_ip_pools list / elements=string	Name of floating IP pool from which to choose a floating IP. Requires wait to be True during server creation. Floating IP support is unstable in this module, use with caution. Options auto_ip, floating_ip_pools and floating_ips interact in non-obvious ways and undocumentable depth. For explicit and safe attaching and detaching of floating ip addresses use module openstack.cloud.resource instead.
floating_ips list / elements=string	list of valid floating IPs that pre-exist to assign to this node. Requires wait to be True during server creation. Floating IP support is unstable in this module, use with caution. Options auto_ip, floating_ip_pools and floating_ips interact in non-obvious ways and undocumentable depth. For explicit and safe attaching and detaching of floating ip addresses use module openstack.cloud.resource instead.
image string	The name or id of the base image to boot. Required when boot_from_volume=true. This server attribute cannot be updated.
image_exclude string	Text to use to filter image names, for the case, such as HP, where there are multiple image names matching the common identifying portions. image_exclude is a negative match filter - it is text that may not exist in the image name. This server attribute cannot be updated. Default: "(deprecated)"
interface aliases: endpoint_type string	Endpoint URL type to fetch from the service catalog. Choices: "admin" "internal" "public" ← (default)
key_name string	The key pair name to be used when creating a instance. This server attribute cannot be updated.
metadata aliases: meta any	A list of key value pairs that should be provided as a metadata to the new instance or a string containing a list of key-value pairs. Example: metadata: “key1=value1,key2=value2”
name string / required	Name that has to be given to the instance. It is also possible to specify the ID of the instance instead of its name if state is absent. This server attribute cannot be updated.
network string	Name or ID of a network to attach this instance to. A simpler version of the nics parameter, only one of network or nics should be supplied. This server attribute cannot be updated.
nics list / elements=any	A list of networks to which the instance’s interface should be attached. Networks may be referenced by net-id/net-name/port-id or port-name. Also this accepts a string containing a list of (net/port)-(id/name) Example: nics: "net-id=uuid-1,port-name=myport" Only one of network or nics should be supplied. This server attribute cannot be updated. Default: []
tag string	A tag for the specific port to be passed via metadata. Eg: tag: test_tag
region_name string	Name of the region.
reuse_ips boolean	When auto_ip is true and this option is true, the auto_ip code will attempt to re-use unassigned floating ips in the project before creating a new one. It is important to note that it is impossible to safely do this concurrently, so if your use case involves concurrent server creation, it is highly recommended to set this to false and to delete the floating ip associated with a server when the server is deleted using delete_ips. Floating IP support is unstable in this module, use with caution. This server attribute cannot be updated. Choices: false true ← (default)
scheduler_hints dictionary	Arbitrary key/value pairs to the scheduler for custom use. This server attribute cannot be updated.
sdk_log_level string	Log level of the OpenStackSDK Choices: "INFO" ← (default) "DEBUG"
sdk_log_path string	Path to the logfile of the OpenStackSDK. If empty no log is written
security_groups list / elements=string	Names or IDs of the security groups to which the instance should be added. On server creation, if security_groups is omitted, the API creates the server in the default security group. Requested security groups are not applied to pre-existing ports. Default: []
state string	Should the resource be present or absent. Choices: "present" ← (default) "absent"
terminate_volume boolean	If true, delete volume when deleting the instance and if it has been booted from volume(s). This server attribute cannot be updated. Choices: false ← (default) true
timeout integer	The amount of time the module should wait for the instance to get into active state. Default: 180
userdata string	Opaque blob of data which is made available to the instance. This server attribute cannot be updated.
validate_certs aliases: verify boolean	Whether or not SSL API requests should be verified. Before Ansible 2.3 this defaulted to true. Choices: false true
volume_size integer	The size of the volume to create in GB if booting from volume based on an image. This server attribute cannot be updated.
volumes list / elements=string	A list of preexisting volumes names or ids to attach to the instance This server attribute cannot be updated. Default: []
wait boolean	If the module should wait for the instance to be created. Choices: false true ← (default)

Notes

Note

• The standard OpenStack environment variables, such as OS_USERNAME may be used instead of providing explicit values.

• Auth information is driven by openstacksdk, which means that values can come from a yaml config file in /etc/ansible/openstack.yaml, /etc/openstack/clouds.yaml or ~/.config/openstack/clouds.yaml, then from standard environment variables, then finally by explicit parameters in plays. More information can be found at https://docs.openstack.org/openstacksdk/

Examples

- name: Create a new instance with metadata and attaches it to a network
  openstack.cloud.server:
       state: present
       auth:
         auth_url: https://identity.example.com
         username: admin
         password: admin
         project_name: admin
       name: vm1
       image: 4f905f38-e52a-43d2-b6ec-754a13ffb529
       key_name: ansible_key
       timeout: 200
       flavor: 4
       nics:
         - net-id: 34605f38-e52a-25d2-b6ec-754a13ffb723
         - net-name: another_network
       meta:
         hostname: test1
         group: uge_master

# Create a new instance in HP Cloud AE1 region availability zone az2 and
# automatically assigns a floating IP
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        state: present
        auth:
          auth_url: https://identity.example.com
          username: username
          password: Equality7-2521
          project_name: username-project1
        name: vm1
        region_name: region-b.geo-1
        availability_zone: az2
        image: 9302692b-b787-4b52-a3a6-daebb79cb498
        key_name: test
        timeout: 200
        flavor: 101
        security_groups:
        - default
        auto_ip: true

# Create a new instance in named cloud mordred availability zone az2
# and assigns a pre-known floating IP
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        state: present
        cloud: mordred
        name: vm1
        availability_zone: az2
        image: 9302692b-b787-4b52-a3a6-daebb79cb498
        key_name: test
        timeout: 200
        flavor: 101
        floating_ips:
          - 12.34.56.79

# Create a new instance with 4G of RAM on Ubuntu Trusty, ignoring
# deprecated images
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        name: vm1
        state: present
        cloud: mordred
        region_name: region-b.geo-1
        image: Ubuntu Server 14.04
        image_exclude: deprecated
        flavor_ram: 4096

# Create a new instance with 4G of RAM on Ubuntu Trusty on a Performance node
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        name: vm1
        cloud: rax-dfw
        state: present
        image: Ubuntu 14.04 LTS (Trusty Tahr) (PVHVM)
        flavor_ram: 4096
        flavor_include: Performance

# Creates a new instance and attaches to multiple network
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance with a string
      openstack.cloud.server:
        auth:
           auth_url: https://identity.example.com
           username: admin
           password: admin
           project_name: admin
        name: vm1
        image: 4f905f38-e52a-43d2-b6ec-754a13ffb529
        key_name: ansible_key
        timeout: 200
        flavor: 4
        nics: >-
            net-id=4cb08b20-62fe-11e5-9d70-feff819cdc9f,
            net-id=542f0430-62fe-11e5-9d70-feff819cdc9f

- name: Creates a new instance with metadata and attaches it to a network
  openstack.cloud.server:
       state: present
       auth:
         auth_url: https://identity.example.com
         username: admin
         password: admin
         project_name: admin
       name: vm1
       image: 4f905f38-e52a-43d2-b6ec-754a13ffb529
       key_name: ansible_key
       timeout: 200
       flavor: 4
       nics:
         - net-id: 34605f38-e52a-25d2-b6ec-754a13ffb723
         - net-name: another_network
       meta: "hostname=test1,group=uge_master"

- name:  Creates a new instance and attaches to a specific network
  openstack.cloud.server:
    state: present
    auth:
      auth_url: https://identity.example.com
      username: admin
      password: admin
      project_name: admin
    name: vm1
    image: 4f905f38-e52a-43d2-b6ec-754a13ffb529
    key_name: ansible_key
    timeout: 200
    flavor: 4
    network: another_network

# Create a new instance with 4G of RAM on a 75G Ubuntu Trusty volume
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        name: vm1
        state: present
        cloud: mordred
        region_name: ams01
        image: Ubuntu Server 14.04
        flavor_ram: 4096
        boot_from_volume: True
        volume_size: 75

# Creates a new instance with 2 volumes attached
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        name: vm1
        state: present
        cloud: mordred
        region_name: ams01
        image: Ubuntu Server 14.04
        flavor_ram: 4096
        volumes:
        - photos
        - music

# Creates a new instance with provisioning userdata using Cloud-Init
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        name: vm1
        state: present
        image: "Ubuntu Server 14.04"
        flavor: "P-1"
        network: "Production"
        userdata: |
          #cloud-config
          chpasswd:
            list: |
              ubuntu:{{ default_password }}
            expire: False
          packages:
            - ansible
          package_upgrade: true

# Creates a new instance with provisioning userdata using Bash Scripts
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        name: vm1
        state: present
        image: "Ubuntu Server 22.04"
        flavor: "P-1"
        network: "Production"
        userdata: |
          #!/bin/sh
          apt update
          apt -y full-upgrade

# Create a new instance with server group for (anti-)affinity
# server group ID is returned from openstack.cloud.server_group module.
- name: launch a compute instance
  hosts: localhost
  tasks:
    - name: launch an instance
      openstack.cloud.server:
        state: present
        name: vm1
        image: 4f905f38-e52a-43d2-b6ec-754a13ffb529
        flavor: 4
        scheduler_hints:
          group: f5c8c61a-9230-400a-8ed2-3b023c190a7f

# Create an instance with "tags" for the nic
- name: Create instance with nics "tags"
  openstack.cloud.server:
    state: present
    auth:
        auth_url: https://identity.example.com
        username: admin
        password: admin
        project_name: admin
    name: vm1
    image: 4f905f38-e52a-43d2-b6ec-754a13ffb529
    key_name: ansible_key
    flavor: 4
    nics:
      - port-name: net1_port1
        tag: test_tag
      - net-name: another_network

# Deletes an instance via its ID
- name: remove an instance
  hosts: localhost
  tasks:
    - name: remove an instance
      openstack.cloud.server:
        name: abcdef01-2345-6789-0abc-def0123456789
        state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
server dictionary	Dictionary describing the server. Returned: On success when state is ‘present’.
access_ipv4 string	IPv4 address that should be used to access this server. May be automatically set by the provider. Returned: success
access_ipv6 string	IPv6 address that should be used to access this server. May be automatically set by the provider. Returned: success
addresses dictionary	A dictionary of addresses this server can be accessed through. The dictionary contains keys such as ‘private’ and ‘public’, each containing a list of dictionaries for addresses of that type. The addresses are contained in a dictionary with keys ‘addr’ and ‘version’, which is either 4 or 6 depending on the protocol of the IP address. Returned: success
admin_password string	When a server is first created, it provides the administrator password. Returned: success
attached_volumes list / elements=string	A list of an attached volumes. Each item in the list contains at least an ‘id’ key to identify the specific volumes. Returned: success
availability_zone string	The name of the availability zone this server is a part of. Returned: success
block_device_mapping string	Enables fine grained control of the block device mapping for an instance. This is typically used for booting servers from volumes. Returned: success
compute_host string	The name of the compute host on which this instance is running. Appears in the response for administrative users only. Returned: success
config_drive string	Indicates whether or not a config drive was used for this server. Returned: success
created_at string	Timestamp of when the server was created. Returned: success
description string	The description of the server. Before microversion 2.19 this was set to the server name. Returned: success
disk_config string	The disk configuration. Either AUTO or MANUAL. Returned: success
flavor dictionary	The flavor property as returned from server. Returned: success
flavor_id string	The flavor reference, as a ID or full URL, for the flavor to use for this server. Returned: success
has_config_drive string	Indicates whether a configuration drive enables metadata injection. Not all cloud providers enable this feature. Returned: success
host_id string	An ID representing the host of this server. Returned: success
host_status string	The host status. Returned: success
hostname string	The hostname set on the instance when it is booted. By default, it appears in the response for administrative users only. Returned: success
hypervisor_hostname string	The hypervisor host name. Appears in the response for administrative users only. Returned: success
id string	ID of the server. Returned: success
image dictionary	The image property as returned from server. Returned: success
image_id string	The image reference, as a ID or full URL, for the image to use for this server. Returned: success
instance_name string	The instance name. The Compute API generates the instance name from the instance name template. Appears in the response for administrative users only. Returned: success
is_locked boolean	The locked status of the server Returned: success
kernel_id string	The UUID of the kernel image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only. Returned: success
key_name string	The name of an associated keypair. Returned: success
launch_index integer	When servers are launched via multiple create, this is the sequence in which the servers were launched. By default, it appears in the response for administrative users only. Returned: success
launched_at string	The timestamp when the server was launched. Returned: success
links string	A list of dictionaries holding links relevant to this server. Returned: success
max_count string	The maximum number of servers to create. Returned: success
metadata dictionary	List of tag strings. Returned: success
min_count string	The minimum number of servers to create. Returned: success
name string	Name of the server Returned: success
networks string	A networks object. Required parameter when there are multiple networks defined for the tenant. When you do not specify the networks parameter, the server attaches to the only network created for the current tenant. Returned: success
power_state string	The power state of this server. Returned: success
progress integer	While the server is building, this value represents the percentage of completion. Once it is completed, it will be 100. Returned: success
project_id string	The ID of the project this server is associated with. Returned: success
ramdisk_id string	The UUID of the ramdisk image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only. Returned: success
reservation_id string	The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id. By default, it appears in the response for administrative users only. Returned: success
root_device_name string	The root device name for the instance By default, it appears in the response for administrative users only. Returned: success
scheduler_hints dictionary	The dictionary of data to send to the scheduler. Returned: success
security_groups list / elements=dictionary	A list of applicable security groups. Each group contains keys for: description, name, id, and rules. Returned: success
server_groups list / elements=string	The UUIDs of the server groups to which the server belongs. Currently this can contain at most one entry. Returned: success
status string	The state this server is in. Valid values include ‘ACTIVE’, ‘BUILDING’, ‘DELETED’, ‘ERROR’, ‘HARD_REBOOT’, ‘PASSWORD’, ‘PAUSED’, ‘REBOOT’, ‘REBUILD’, ‘RESCUED’, ‘RESIZED’, ‘REVERT_RESIZE’, ‘SHUTOFF’, ‘SOFT_DELETED’, ‘STOPPED’, ‘SUSPENDED’, ‘UNKNOWN’, or ‘VERIFY_RESIZE’. Returned: success
tags list / elements=string	A list of associated tags. Returned: success
task_state string	The task state of this server. Returned: success
terminated_at string	The timestamp when the server was terminated (if it has been). Returned: success
trusted_image_certificates list / elements=string	A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate. Returned: success
updated_at string	Timestamp of when this server was last updated. Returned: success
user_data string	Configuration information or scripts to use upon launch. Base64 encoded. Returned: success
user_id string	The ID of the owners of this server. Returned: success
vm_state string	The VM state of this server. Returned: success
volumes list / elements=string	Same as attached_volumes. Returned: success

Authors

• OpenStack Ansible SIG

Collection links

• Issue Tracker
• Repository (Sources)