Documentation

os_server - Create/Delete Compute Instances from OpenStack

New in version 2.0.

Synopsis

  • Create or Remove compute instances from OpenStack.

Requirements (on host that executes module)

  • python >= 2.6
  • python >= 2.7
  • shade

Options

parameter required default choices comments
api_timeout
no None
    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
    no
      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 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
      no password
        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
        no yes
          Ensure instance has public ip however the cloud wants to do that

          aliases: auto_floating_ip, public_ip
          availability_zone
          no
            Availability zone in which to create the server.
            boot_from_volume
            no
              Should the instance boot from a persistent volume created based on the image given. Mututally exclusive with boot_volume.
              boot_volume
              no None
                Volume name or id to use as the volume to boot from. Implies boot_from_volume. Mutually exclusive with image and boot_from_volume.

                aliases: root_volume
                cacert
                no None
                  A path to a CA Cert bundle that can be used as part of verifying SSL API requests.
                  cert
                  no None
                    A path to a client certificate to use as part of the SSL transaction.
                    cloud
                    no
                      Named cloud to operate against. 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.
                      config_drive
                      no no
                        Whether to boot the server with config drive enabled
                        delete_fip
                        (added in 2.2)
                        no
                          When state is absent and this option is true, any floating IP associated with the instance will be deleted along with the instance.
                          endpoint_type
                          no public
                          • public
                          • internal
                          • admin
                          Endpoint URL type to fetch from the service catalog.
                          flavor
                          no 1
                            The name or id of the flavor in which the new instance has to be created. Mutually exclusive with flavor_ram
                            flavor_include
                            no
                              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.
                              flavor_ram
                              no 1
                                The minimum amount of ram in MB that the flavor in which the new instance has to be created must have. Mutually exclusive with flavor.
                                floating_ip_pools
                                no None
                                  Name of floating IP pool from which to choose a floating IP
                                  floating_ips
                                  no None
                                    list of valid floating IPs that pre-exist to assign to this node
                                    image
                                    yes
                                      The name or id of the base image to boot.
                                      image_exclude
                                      no
                                        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. Defaults to "(deprecated)"
                                        key
                                        no None
                                          A path to a client key to use as part of the SSL transaction.
                                          key_name
                                          no None
                                            The key pair name to be used when creating a instance
                                            meta
                                            no None
                                              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. Eg: meta: "key1=value1,key2=value2"
                                              name
                                              yes
                                                Name that has to be given to the instance
                                                network
                                                no None
                                                  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.
                                                  nics
                                                  no None
                                                    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) Eg: nics: "net-id=uuid-1,port-name=myport" Only one of network or nics should be supplied.
                                                    region_name
                                                    no
                                                      Name of the region.
                                                      reuse_ips
                                                      (added in 2.2)
                                                      no True
                                                        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_fip.
                                                        scheduler_hints
                                                        (added in 2.1)
                                                        no None
                                                          Arbitrary key/value pairs to the scheduler for custom use
                                                          security_groups
                                                          no None
                                                            Names of the security groups to which the instance should be added. This may be a YAML list or a comma separated string.
                                                            state
                                                            no present
                                                            • present
                                                            • absent
                                                            Should the resource be present or absent.
                                                            terminate_volume
                                                            no
                                                              If true, delete volume when deleting instance (if booted from volume)
                                                              timeout
                                                              no 180
                                                                How long should ansible wait for the requested resource.
                                                                userdata
                                                                no None
                                                                  Opaque blob of data which is made available to the instance
                                                                  validate_certs
                                                                  no
                                                                    Whether or not SSL API requests should be verified. Before 2.3 this defaulted to True.

                                                                    aliases: verify
                                                                    volume_size
                                                                    no
                                                                      The size of the volume to create in GB if booting from volume based on an image.
                                                                      volumes
                                                                      no
                                                                        A list of preexisting volumes names or ids to attach to the instance
                                                                        wait
                                                                        no yes
                                                                        • yes
                                                                        • no
                                                                        Should ansible wait until the requested resource is complete.

                                                                        Examples

                                                                        - name: Create a new instance and attaches to a network and passes metadata to the instance
                                                                          os_server:
                                                                               state: present
                                                                               auth:
                                                                                 auth_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/
                                                                                 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
                                                                              os_server:
                                                                                state: present
                                                                                auth:
                                                                                  auth_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/
                                                                                  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: yes
                                                                        
                                                                        # 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
                                                                              os_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
                                                                              os_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
                                                                              os_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
                                                                              os_server:
                                                                                auth:
                                                                                   auth_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/
                                                                                   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 and attaches to a network and passes metadata to the instance
                                                                          os_server:
                                                                               state: present
                                                                               auth:
                                                                                 auth_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/
                                                                                 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
                                                                          os_server:
                                                                            state: present
                                                                            auth:
                                                                              auth_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/
                                                                              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
                                                                              os_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
                                                                              os_server:
                                                                                name: vm1
                                                                                state: present
                                                                                cloud: mordred
                                                                                region_name: ams01
                                                                                image: Ubuntu Server 14.04
                                                                                flavor_ram: 4096
                                                                                volumes:
                                                                                - photos
                                                                                - music
                                                                        

                                                                        Notes

                                                                        Note

                                                                        • The standard OpenStack environment variables, such as OS_USERNAME may be used instead of providing explicit values.
                                                                        • Auth information is driven by os-client-config, 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 http://docs.openstack.org/developer/os-client-config

                                                                        Status

                                                                        This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

                                                                        Support

                                                                        This module is community maintained without core committer oversight.

                                                                        For more information on what this means please read Module Support

                                                                        For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.