Usage

To use shade in a project:

import shade

Note

API methods that return a description of an OpenStack resource (e.g., server instance, image, volume, etc.) do so using a munch.Munch object from the Munch library. Munch objects can be accessed using either dictionary or object notation (e.g., server.id, image.name and server['id'], image['name'])

class shade.OpenStackCloud(cloud_config=None, manager=None, log_inner_exceptions=False, strict=False, app_name=None, app_version=None, **kwargs)

Represent a connection to an OpenStack Cloud.

OpenStackCloud is the entry point for all cloud operations, regardless of which OpenStack service those operations may ultimately come from. The operations on an OpenStackCloud are resource oriented rather than REST API operation oriented. For instance, one will request a Floating IP and that Floating IP will be actualized either via neutron or via nova depending on how this particular cloud has decided to arrange itself.

Parameters:
  • manager (TaskManager) – Optional task manager to use for running OpenStack API tasks. Unless you’re doing rate limiting client side, you almost certainly don’t need this. (optional)
  • log_inner_exceptions (bool) – Send wrapped exceptions to the error log. Defaults to false, because there are a number of wrapped exceptions that are noise for normal usage. It’s possible that for a user that has python logging configured properly, it’s desirable to have all of the wrapped exceptions be emitted to the error log. This flag will enable that behavior.
  • strict (bool) – Only return documented attributes for each resource as per the shade Data Model contract. (Default False)
  • app_name – Name of the application to be appended to the user-agent string. Optional, defaults to None.
  • app_version – Version of the application to be appended to the user-agent string. Optional, defaults to None.
  • cloud_config (CloudConfig) – Cloud config object from os-client-config In the future, this will be the only way to pass in cloud configuration, but is being phased in currently.
add_auto_ip(server, wait=False, timeout=60, reuse=True)

Add a floating IP to a server.

This method is intended for basic usage. For advanced network architecture (e.g. multiple external networks or servers with multiple interfaces), use other floating IP methods.

This method can reuse available IPs, or allocate new IPs to the current project.

Parameters:
  • server – a server dictionary.
  • reuse – Whether or not to attempt to reuse IPs, defaults to True.
  • wait – (optional) Wait for the address to appear as assigned to the server. Defaults to False.
  • timeout – (optional) Seconds to wait, defaults to 60. See the wait parameter.
  • reuse – Try to reuse existing ips. Defaults to True.
Returns:

Floating IP address attached to server.

add_ip_list(server, ips, wait=False, timeout=60, fixed_address=None)

Attach a list of IPs to a server.

Parameters:
  • server – a server object
  • ips – list of floating IP addresses or a single address
  • wait – (optional) Wait for the address to appear as assigned to the server. Defaults to False.
  • timeout – (optional) Seconds to wait, defaults to 60. See the wait parameter.
  • fixed_address – (optional) Fixed address of the server to attach the IP to
Returns:

The updated server munch.Munch

Raises:

OpenStackCloudException, on operation error.

add_router_interface(router, subnet_id=None, port_id=None)

Attach a subnet to an internal router interface.

Either a subnet ID or port ID must be specified for the internal interface. Supplying both will result in an error.

Parameters:
  • router (dict) – The dict object of the router being changed
  • subnet_id (string) – The ID of the subnet to use for the interface
  • port_id (string) – The ID of the port to use for the interface
Returns:

A munch.Munch with the router ID (ID), subnet ID (subnet_id), port ID (port_id) and tenant ID (tenant_id).

Raises:

OpenStackCloudException on operation error.

add_server_security_groups(server, security_groups)

Add security groups to a server.

Add existing security groups to an existing server. If the security groups are already present on the server this will continue unaffected.

Returns:False if server or security groups are undefined, True otherwise.
Raises:OpenStackCloudException, on operation error.
add_user_to_group(name_or_id, group_name_or_id)

Add a user to a group.

Parameters:
  • name_or_id (string) – User name or ID
  • group_name_or_id (string) – Group name or ID
Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call

attach_volume(server, volume, device=None, wait=True, timeout=None)

Attach a volume to a server.

This will attach a volume, described by the passed in volume dict (as returned by get_volume()), to the server described by the passed in server dict (as returned by get_server()) on the named device on the server.

If the volume is already attached to the server, or generally not available, then an exception is raised. To re-attach to a server, but under a different device, the user must detach it first.

Parameters:
  • server – The server dict to attach to.
  • volume – The volume dict to attach.
  • device – The device name where the volume will attach.
  • wait – If true, waits for volume to be attached.
  • timeout – Seconds to wait for volume attachment. None is forever.
Returns:

a volume attachment object.

Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

available_floating_ip(network=None, server=None)

Get a floating IP from a network or a pool.

Return the first available floating IP or allocate a new one.

Parameters:
  • network – Name or ID of the network.
  • server – Server the IP is for if known
Returns:

a (normalized) structure with a floating IP address description.

create_baymodel(name, image_id=None, keypair_id=None, coe=None, **kwargs)

Create a cluster template.

Parameters:
  • name (string) – Name of the cluster template.
  • image_id (string) – Name or ID of the image to use.
  • keypair_id (string) – Name or ID of the keypair to use.
  • coe (string) – Name of the coe for the cluster template.

Other arguments will be passed in kwargs.

Returns:a dict containing the cluster template description
Raises:OpenStackCloudException if something goes wrong during the OpenStack API call
create_cluster_template(name, image_id=None, keypair_id=None, coe=None, **kwargs)

Create a cluster template.

Parameters:
  • name (string) – Name of the cluster template.
  • image_id (string) – Name or ID of the image to use.
  • keypair_id (string) – Name or ID of the keypair to use.
  • coe (string) – Name of the coe for the cluster template.

Other arguments will be passed in kwargs.

Returns:a dict containing the cluster template description
Raises:OpenStackCloudException if something goes wrong during the OpenStack API call
create_floating_ip(network=None, server=None, fixed_address=None, nat_destination=None, port=None, wait=False, timeout=60)

Allocate a new floating IP from a network or a pool.

Parameters:
  • network – Name or ID of the network that the floating IP should come from.
  • server – (optional) Server dict for the server to create the IP for and to which it should be attached.
  • fixed_address – (optional) Fixed IP to attach the floating ip to.
  • nat_destination – (optional) Name or ID of the network that the fixed IP to attach the floating IP to should be on.
  • port – (optional) The port ID that the floating IP should be attached to. Specifying a port conflicts with specifying a server, fixed_address or nat_destination.
  • wait – (optional) Whether to wait for the IP to be active. Defaults to False. Only applies if a server is provided.
  • timeout – (optional) How long to wait for the IP to be active. Defaults to 60. Only applies if a server is provided.
Returns:

a floating IP address

Raises:

OpenStackCloudException, on operation error.

create_image(name, filename=None, container='images', md5=None, sha256=None, disk_format=None, container_format=None, disable_vendor_agent=True, wait=False, timeout=3600, allow_duplicates=False, meta=None, volume=None, **kwargs)

Upload an image.

Parameters:
  • name (str) – Name of the image to create. If it is a pathname of an image, the name will be constructed from the extensionless basename of the path.
  • filename (str) – The path to the file to upload, if needed. (optional, defaults to None)
  • container (str) – Name of the container in swift where images should be uploaded for import if the cloud requires such a thing. (optiona, defaults to ‘images’)
  • md5 (str) – md5 sum of the image file. If not given, an md5 will be calculated.
  • sha256 (str) – sha256 sum of the image file. If not given, an md5 will be calculated.
  • disk_format (str) – The disk format the image is in. (optional, defaults to the os-client-config config value for this cloud)
  • container_format (str) – The container format the image is in. (optional, defaults to the os-client-config config value for this cloud)
  • disable_vendor_agent (bool) – Whether or not to append metadata flags to the image to inform the cloud in question to not expect a vendor agent to be runing. (optional, defaults to True)
  • wait (bool) – If true, waits for image to be created. Defaults to true - however, be aware that one of the upload methods is always synchronous.
  • timeout – Seconds to wait for image creation. None is forever.
  • allow_duplicates – If true, skips checks that enforce unique image name. (optional, defaults to False)
  • meta – A dict of key/value pairs to use for metadata that bypasses automatic type conversion.
  • volume – Name or ID or volume object of a volume to create an image from. Mutually exclusive with (optional, defaults to None)

Additional kwargs will be passed to the image creation as additional metadata for the image and will have all values converted to string except for min_disk, min_ram, size and virtual_size which will be converted to int.

If you are sure you have all of your data types correct or have an advanced need to be explicit, use meta. If you are just a normal consumer, using kwargs is likely the right choice.

If a value is in meta and kwargs, meta wins.

Returns:A munch.Munch of the Image object
Raises:OpenStackCloudException if there are problems uploading
create_image_snapshot(name, server, wait=False, timeout=3600, **metadata)

Create an image by snapshotting an existing server.

..note::
On most clouds this is a cold snapshot - meaning that the server in question will be shutdown before taking the snapshot. It is possible that it’s a live snapshot - but there is no way to know as a user, so caveat emptor.
Parameters:
  • name – Name of the image to be created
  • server – Server name or ID or dict representing the server to be snapshotted
  • wait – If true, waits for image to be created.
  • timeout – Seconds to wait for image creation. None is forever.
  • metadata – Metadata to give newly-created image entity
Returns:

A munch.Munch of the Image object

Raises:

OpenStackCloudException if there are problems uploading

create_keypair(name, public_key)

Create a new keypair.

Parameters:
  • name – Name of the keypair being created.
  • public_key – Public key for the new keypair.
Raises:

OpenStackCloudException on operation error.

create_network(name, shared=False, admin_state_up=True, external=False, provider=None, project_id=None)

Create a network.

Parameters:
  • name (string) – Name of the network being created.
  • shared (bool) – Set the network as shared.
  • admin_state_up (bool) – Set the network administrative state to up.
  • external (bool) – Whether this network is externally accessible.
  • provider (dict) –

    A dict of network provider options. Example:

    { 'network_type': 'vlan', 'segmentation_id': 'vlan1' }
    
  • project_id (string) – Specify the project ID this network will be created on (admin-only).
Returns:

The network object.

Raises:

OpenStackCloudException on operation error.

create_object(container, name, filename=None, md5=None, sha256=None, segment_size=None, use_slo=True, metadata=None, **headers)

Create a file object

Parameters:
  • container – The name of the container to store the file in. This container will be created if it does not exist already.
  • name – Name for the object within the container.
  • filename – The path to the local file whose contents will be uploaded.
  • md5 – A hexadecimal md5 of the file. (Optional), if it is known and can be passed here, it will save repeating the expensive md5 process. It is assumed to be accurate.
  • sha256 – A hexadecimal sha256 of the file. (Optional) See md5.
  • segment_size – Break the uploaded object into segments of this many bytes. (Optional) Shade will attempt to discover the maximum value for this from the server if it is not specified, or will use a reasonable default.
  • headers – These will be passed through to the object creation API as HTTP Headers.
  • use_slo – If the object is large enough to need to be a Large Object, use a static rather than dynamic object. Static Objects will delete segment objects when the manifest object is deleted. (optional, defaults to True)
  • metadata – This dict will get changed into headers that set metadata of the object
Raises:

OpenStackCloudException on operation error.

create_port(network_id, **kwargs)

Create a port

Parameters:
  • network_id – The ID of the network. (Required)
  • name – A symbolic name for the port. (Optional)
  • admin_state_up – The administrative status of the port, which is up (true, default) or down (false). (Optional)
  • mac_address – The MAC address. (Optional)
  • fixed_ips

    List of ip_addresses and subnet_ids. See subnet_id and ip_address. (Optional) For example:

    [
      {
        "ip_address": "10.29.29.13",
        "subnet_id": "a78484c4-c380-4b47-85aa-21c51a2d8cbd"
      }, ...
    ]
    
  • subnet_id – If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. (Optional) If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port.
  • ip_address – If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port.
  • security_groups – List of security group UUIDs. (Optional)
  • allowed_address_pairs

    Allowed address pairs list (Optional) For example:

    [
      {
        "ip_address": "23.23.23.1",
        "mac_address": "fa:16:3e:c4:cd:3f"
      }, ...
    ]
    
  • extra_dhcp_opts

    Extra DHCP options. (Optional). For example:

    [
      {
        "opt_name": "opt name1",
        "opt_value": "value1"
      }, ...
    ]
    
  • device_owner – The ID of the entity that uses this port. For example, a DHCP agent. (Optional)
  • device_id – The ID of the device that uses this port. For example, a virtual server. (Optional)
Returns:

a munch.Munch describing the created port.

Raises:

OpenStackCloudException on operation error.

create_project(name, description=None, domain_id=None, enabled=True)

Create a project.

create_recordset(zone, name, recordset_type, records, description=None, ttl=None)

Create a recordset.

Parameters:
  • zone – Name or ID of the zone managing the recordset
  • name – Name of the recordset
  • recordset_type – Type of the recordset
  • records – List of the recordset definitions
  • description – Description of the recordset
  • ttl – TTL value of the recordset
Returns:

a dict representing the created recordset.

Raises:

OpenStackCloudException on operation error.

create_router(name=None, admin_state_up=True, ext_gateway_net_id=None, enable_snat=None, ext_fixed_ips=None, project_id=None)

Create a logical router.

Parameters:
  • name (string) – The router name.
  • admin_state_up (bool) – The administrative state of the router.
  • ext_gateway_net_id (string) – Network ID for the external gateway.
  • enable_snat (bool) – Enable Source NAT (SNAT) attribute.
  • ext_fixed_ips (list) –

    List of dictionaries of desired IP and/or subnet on the external network. Example:

    [
      {
        "subnet_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
        "ip_address": "192.168.10.2"
      }
    ]
    
  • project_id (string) – Project ID for the router.
Returns:

The router object.

Raises:

OpenStackCloudException on operation error.

create_security_group(name, description, project_id=None)

Create a new security group

Parameters:
  • name (string) – A name for the security group.
  • description (string) – Describes the security group.
  • project_id (string) – Specify the project ID this security group will be created on (admin-only).
Returns:

A munch.Munch representing the new security group.

Raises:

OpenStackCloudException on operation error.

Raises:

OpenStackCloudUnavailableFeature if security groups are not supported on this cloud.

create_security_group_rule(secgroup_name_or_id, port_range_min=None, port_range_max=None, protocol=None, remote_ip_prefix=None, remote_group_id=None, direction='ingress', ethertype='IPv4', project_id=None)

Create a new security group rule

Parameters:
  • secgroup_name_or_id (string) – The security group name or ID to associate with this security group rule. If a non-unique group name is given, an exception is raised.
  • port_range_min (int) – The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If nova is used by the cloud provider for security groups, then a value of None will be transformed to -1.
  • port_range_max (int) – The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If nova is used by the cloud provider for security groups, then a value of None will be transformed to -1.
  • protocol (string) – The protocol that is matched by the security group rule. Valid values are None, tcp, udp, and icmp.
  • remote_ip_prefix (string) – The remote IP prefix to be associated with this security group rule. This attribute matches the specified IP prefix as the source IP address of the IP packet.
  • remote_group_id (string) – The remote group ID to be associated with this security group rule.
  • direction (string) – Ingress or egress: The direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.
  • ethertype (string) – Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
  • project_id (string) – Specify the project ID this security group will be created on (admin-only).
Returns:

A munch.Munch representing the new security group rule.

Raises:

OpenStackCloudException on operation error.

create_server(name, image, flavor, auto_ip=True, ips=None, ip_pool=None, root_volume=None, terminate_volume=False, wait=False, timeout=180, reuse_ips=True, network=None, boot_from_volume=False, volume_size='50', boot_volume=None, volumes=None, nat_destination=None, **kwargs)

Create a virtual server instance.

Parameters:
  • name – Something to name the server.
  • image – Image dict, name or ID to boot with.
  • flavor – Flavor dict, name or ID to boot onto.
  • auto_ip – Whether to take actions to find a routable IP for the server. (defaults to True)
  • ips – List of IPs to attach to the server (defaults to None)
  • ip_pool – Name of the network or floating IP pool to get an address from. (defaults to None)
  • root_volume – Name or ID of a volume to boot from (defaults to None - deprecated, use boot_volume)
  • boot_volume – Name or ID of a volume to boot from (defaults to None)
  • terminate_volume – If booting from a volume, whether it should be deleted when the server is destroyed. (defaults to False)
  • volumes – (optional) A list of volumes to attach to the server
  • meta – (optional) A dict of arbitrary key/value metadata to store for this server. Both keys and values must be <=255 characters.
  • files – (optional, deprecated) A dict of files to overwrite on the server upon boot. Keys are file names (i.e. /etc/passwd) and values are the file contents (either as a string or as a file-like object). A maximum of five entries is allowed, and each file must be 10k or less.
  • reservation_id – a UUID for the set of servers being requested.
  • min_count – (optional extension) The minimum number of servers to launch.
  • max_count – (optional extension) The maximum number of servers to launch.
  • security_groups – A list of security group names
  • userdata – user data to pass to be exposed by the metadata server this can be a file type object as well or a string.
  • key_name – (optional extension) name of previously created keypair to inject into the instance.
  • availability_zone – Name of the availability zone for instance placement.
  • block_device_mapping – (optional) A dict of block device mappings for this server.
  • block_device_mapping_v2 – (optional) A dict of block device mappings for this server.
  • nics – (optional extension) an ordered list of nics to be added to this server, with information about connected networks, fixed IPs, port etc.
  • scheduler_hints – (optional extension) arbitrary key-value pairs specified by the client to help boot an instance
  • config_drive – (optional extension) value for config drive either boolean, or volume-id
  • disk_config – (optional extension) control how the disk is partitioned when the server is created. possible values are ‘AUTO’ or ‘MANUAL’.
  • admin_pass – (optional extension) add a user supplied admin password.
  • wait – (optional) Wait for the address to appear as assigned to the server. Defaults to False.
  • timeout – (optional) Seconds to wait, defaults to 60. See the wait parameter.
  • reuse_ips – (optional) Whether to attempt to reuse pre-existing floating ips should a floating IP be needed (defaults to True)
  • network – (optional) Network dict or name or ID to attach the server to. Mutually exclusive with the nics parameter. Can also be be a list of network names or IDs or network dicts.
  • boot_from_volume – Whether to boot from volume. ‘boot_volume’ implies True, but boot_from_volume=True with no boot_volume is valid and will create a volume from the image and use that.
  • volume_size – When booting an image from volume, how big should the created volume be? Defaults to 50.
  • nat_destination – Which network should a created floating IP be attached to, if it’s not possible to infer from the cloud’s configuration. (Optional, defaults to None)
Returns:

A munch.Munch representing the created server.

Raises:

OpenStackCloudException on operation error.

create_server_group(name, policies)

Create a new server group.

Parameters:
  • name – Name of the server group being created
  • policies – List of policies for the server group.
Returns:

a dict representing the new server group.

Raises:

OpenStackCloudException on operation error.

create_stack(name, template_file=None, template_url=None, template_object=None, files=None, rollback=True, wait=False, timeout=3600, environment_files=None, **parameters)

Create a stack.

Parameters:
  • name (string) – Name of the stack.
  • template_file (string) – Path to the template.
  • template_url (string) – URL of template.
  • template_object (string) – URL to retrieve template object.
  • files (dict) – dict of additional file content to include.
  • rollback (boolean) – Enable rollback on create failure.
  • wait (boolean) – Whether to wait for the delete to finish.
  • timeout (int) – Stack create timeout in seconds.
  • environment_files (list) – Paths to environment files to apply.

Other arguments will be passed as stack parameters which will take precedence over any parameters specified in the environments.

Only one of template_file, template_url, template_object should be specified.

Returns:a dict containing the stack description
Raises:OpenStackCloudException if something goes wrong during the OpenStack API call
create_subnet(network_name_or_id, cidr=None, ip_version=4, enable_dhcp=False, subnet_name=None, tenant_id=None, allocation_pools=None, gateway_ip=None, disable_gateway_ip=False, dns_nameservers=None, host_routes=None, ipv6_ra_mode=None, ipv6_address_mode=None, use_default_subnetpool=False)

Create a subnet on a specified network.

Parameters:
  • network_name_or_id (string) – The unique name or ID of the attached network. If a non-unique name is supplied, an exception is raised.
  • cidr (string) – The CIDR.
  • ip_version (int) – The IP version, which is 4 or 6.
  • enable_dhcp (bool) – Set to True if DHCP is enabled and False if disabled. Default is False.
  • subnet_name (string) – The name of the subnet.
  • tenant_id (string) – The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own.
  • allocation_pools (list) –

    A list of dictionaries of the start and end addresses for the allocation pools. For example:

    [
      {
        "start": "192.168.199.2",
        "end": "192.168.199.254"
      }
    ]
    
  • gateway_ip (string) – The gateway IP address. When you specify both allocation_pools and gateway_ip, you must ensure that the gateway IP does not overlap with the specified allocation pools.
  • disable_gateway_ip (bool) – Set to True if gateway IP address is disabled and False if enabled. It is not allowed with gateway_ip. Default is False.
  • dns_nameservers (list) –

    A list of DNS name servers for the subnet. For example:

    [ "8.8.8.7", "8.8.8.8" ]
    
  • host_routes (list) –

    A list of host route dictionaries for the subnet. For example:

    [
      {
        "destination": "0.0.0.0/0",
        "nexthop": "123.456.78.9"
      },
      {
        "destination": "192.168.0.0/24",
        "nexthop": "192.168.0.1"
      }
    ]
    
  • ipv6_ra_mode (string) – IPv6 Router Advertisement mode. Valid values are: ‘dhcpv6-stateful’, ‘dhcpv6-stateless’, or ‘slaac’.
  • ipv6_address_mode (string) – IPv6 address mode. Valid values are: ‘dhcpv6-stateful’, ‘dhcpv6-stateless’, or ‘slaac’.
  • use_default_subnetpool (bool) – Use the default subnetpool for ip_version to obtain a CIDR. It is required to pass None to the cidr argument when enabling this option.
Returns:

The new subnet object.

Raises:

OpenStackCloudException on operation error.

create_user(name, password=None, email=None, default_project=None, enabled=True, domain_id=None, description=None)

Create a user.

create_volume(size, wait=True, timeout=None, image=None, **kwargs)

Create a volume.

Parameters:
  • size – Size, in GB of the volume to create.
  • name – (optional) Name for the volume.
  • description – (optional) Name for the volume.
  • wait – If true, waits for volume to be created.
  • timeout – Seconds to wait for volume creation. None is forever.
  • image – (optional) Image name, ID or object from which to create the volume
  • kwargs – Keyword arguments as expected for cinder client.
Returns:

The created volume object.

Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

create_volume_backup(volume_id, name=None, description=None, force=False, wait=True, timeout=None)

Create a volume backup.

Parameters:
  • volume_id – the ID of the volume to backup.
  • name – name of the backup, one will be generated if one is not provided
  • description – description of the backup, one will be generated if one is not provided
  • force – If set to True the backup will be created even if the volume is attached to an instance, if False it will not
  • wait – If true, waits for volume backup to be created.
  • timeout – Seconds to wait for volume backup creation. None is forever.
Returns:

The created volume backup object.

Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

create_volume_snapshot(volume_id, force=False, wait=True, timeout=None, **kwargs)

Create a volume.

Parameters:
  • volume_id – the ID of the volume to snapshot.
  • force – If set to True the snapshot will be created even if the volume is attached to an instance, if False it will not
  • name – name of the snapshot, one will be generated if one is not provided
  • description – description of the snapshot, one will be generated if one is not provided
  • wait – If true, waits for volume snapshot to be created.
  • timeout – Seconds to wait for volume snapshot creation. None is forever.
Returns:

The created volume object.

Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

create_zone(name, zone_type=None, email=None, description=None, ttl=None, masters=None)

Create a new zone.

Parameters:
  • name – Name of the zone being created.
  • zone_type – Type of the zone (primary/secondary)
  • email – Email of the zone owner (only applies if zone_type is primary)
  • description – Description of the zone
  • ttl – TTL (Time to live) value in seconds
  • masters – Master nameservers (only applies if zone_type is secondary)
Returns:

a dict representing the created zone.

Raises:

OpenStackCloudException on operation error.

current_location

Return a munch.Munch explaining the current cloud location.

current_project

Return a munch.Munch describing the current project

current_project_id

Get the current project ID.

Returns the project_id of the current token scope. None means that the token is domain scoped or unscoped.

Raises:
  • keystoneauth1.exceptions.auth.AuthorizationFailure – if a new token fetch fails.
  • keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.
delete_baymodel(name_or_id)

Delete a cluster template.

Parameters:name_or_id – Name or unique ID of the cluster template.
Returns:True if the delete succeeded, False if the cluster template was not found.
Raises:OpenStackCloudException on operation error.
delete_cluster_template(name_or_id)

Delete a cluster template.

Parameters:name_or_id – Name or unique ID of the cluster template.
Returns:True if the delete succeeded, False if the cluster template was not found.
Raises:OpenStackCloudException on operation error.
delete_floating_ip(floating_ip_id, retry=1)

Deallocate a floating IP from a project.

Parameters:
  • floating_ip_id – a floating IP address ID.
  • retry – number of times to retry. Optional, defaults to 1, which is in addition to the initial delete call. A value of 0 will also cause no checking of results to occur.
Returns:

True if the IP address has been deleted, False if the IP address was not found.

Raises:

OpenStackCloudException, on operation error.

delete_image(name_or_id, wait=False, timeout=3600, delete_objects=True)

Delete an existing image.

Parameters:
  • name_or_id – Name of the image to be deleted.
  • wait – If True, waits for image to be deleted.
  • timeout – Seconds to wait for image deletion. None is forever.
  • delete_objects – If True, also deletes uploaded swift objects.
Returns:

True if delete succeeded, False otherwise.

Raises:

OpenStackCloudException if there are problems deleting.

delete_keypair(name)

Delete a keypair.

Parameters:name – Name of the keypair to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_network(name_or_id)

Delete a network.

Parameters:name_or_id – Name or ID of the network being deleted.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_object(container, name)

Delete an object from a container.

Parameters:
  • container (string) – Name of the container holding the object.
  • name (string) – Name of the object to delete.
Returns:

True if delete succeeded, False if the object was not found.

Raises:

OpenStackCloudException on operation error.

delete_port(name_or_id)

Delete a port

Parameters:name_or_id – ID or name of the port to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_project(name_or_id, domain_id=None)

Delete a project.

Parameters:
  • name_or_id (string) – Project name or ID.
  • domain_id (string) – Domain ID containing the project(identity v3 only).
Returns:

True if delete succeeded, False if the project was not found.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call

delete_recordset(zone, name_or_id)

Delete a recordset.

Parameters:
  • zone – Name or ID of the zone managing the recordset.
  • name_or_id – Name or ID of the recordset being deleted.
Returns:

True if delete succeeded, False otherwise.

Raises:

OpenStackCloudException on operation error.

delete_router(name_or_id)

Delete a logical router.

If a name, instead of a unique UUID, is supplied, it is possible that we could find more than one matching router since names are not required to be unique. An error will be raised in this case.

Parameters:name_or_id – Name or ID of the router being deleted.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_security_group(name_or_id)

Delete a security group

Parameters:name_or_id (string) – The name or unique ID of the security group.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
Raises:OpenStackCloudUnavailableFeature if security groups are not supported on this cloud.
delete_security_group_rule(rule_id)

Delete a security group rule

Parameters:rule_id (string) – The unique ID of the security group rule.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
Raises:OpenStackCloudUnavailableFeature if security groups are not supported on this cloud.
delete_server(name_or_id, wait=False, timeout=180, delete_ips=False, delete_ip_retry=1)

Delete a server instance.

Parameters:
  • name_or_id – name or ID of the server to delete
  • wait (bool) – If true, waits for server to be deleted.
  • timeout (int) – Seconds to wait for server deletion.
  • delete_ips (bool) – If true, deletes any floating IPs associated with the instance.
  • delete_ip_retry (int) – Number of times to retry deleting any floating ips, should the first try be unsuccessful.
Returns:

True if delete succeeded, False otherwise if the server does not exist.

Raises:

OpenStackCloudException on operation error.

delete_server_group(name_or_id)

Delete a server group.

Parameters:name_or_id – Name or ID of the server group to delete
Returns:True if delete succeeded, False otherwise
Raises:OpenStackCloudException on operation error.
delete_server_metadata(name_or_id, metadata_keys)

Delete metadata from a server instance.

Parameters:
  • name_or_id (str) – The name or ID of the server instance to update.
  • metadata_keys (list) – A list with the keys to be deleted from the server instance.
Raises:

OpenStackCloudException on operation error.

delete_stack(name_or_id, wait=False)

Delete a stack

Parameters:
  • name_or_id (string) – Stack name or ID.
  • wait (boolean) – Whether to wait for the delete to finish
Returns:

True if delete succeeded, False if the stack was not found.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call

delete_subnet(name_or_id)

Delete a subnet.

If a name, instead of a unique UUID, is supplied, it is possible that we could find more than one matching subnet since names are not required to be unique. An error will be raised in this case.

Parameters:name_or_id – Name or ID of the subnet being deleted.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_unattached_floating_ips(retry=1)

Safely delete unattached floating ips.

If the cloud can safely purge any unattached floating ips without race conditions, do so.

Safely here means a specific thing. It means that you are not running this while another process that might do a two step create/attach is running. You can safely run this method while another process is creating servers and attaching floating IPs to them if either that process is using add_auto_ip from shade, or is creating the floating IPs by passing in a server to the create_floating_ip call.

Parameters:retry – number of times to retry. Optional, defaults to 1, which is in addition to the initial delete call. A value of 0 will also cause no checking of results to occur.
Returns:True if Floating IPs have been deleted, False if not
Raises:OpenStackCloudException, on operation error.
delete_volume(name_or_id=None, wait=True, timeout=None)

Delete a volume.

Parameters:
  • name_or_id – Name or unique ID of the volume.
  • wait – If true, waits for volume to be deleted.
  • timeout – Seconds to wait for volume deletion. None is forever.
Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

delete_volume_backup(name_or_id=None, force=False, wait=False, timeout=None)

Delete a volume backup.

Parameters:
  • name_or_id – Name or unique ID of the volume backup.
  • force – Allow delete in state other than error or available.
  • wait – If true, waits for volume backup to be deleted.
  • timeout – Seconds to wait for volume backup deletion. None is forever.
Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

delete_volume_snapshot(name_or_id=None, wait=False, timeout=None)

Delete a volume snapshot.

Parameters:
  • name_or_id – Name or unique ID of the volume snapshot.
  • wait – If true, waits for volume snapshot to be deleted.
  • timeout – Seconds to wait for volume snapshot deletion. None is forever.
Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

delete_zone(name_or_id)

Delete a zone.

Parameters:name_or_id – Name or ID of the zone being deleted.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
detach_ip_from_server(server_id, floating_ip_id)

Detach a floating IP from a server.

Parameters:
  • server_id – ID of a server.
  • floating_ip_id – Id of the floating IP to detach.
Returns:

True if the IP has been detached, or False if the IP wasn’t attached to any server.

Raises:

OpenStackCloudException, on operation error.

detach_volume(server, volume, wait=True, timeout=None)

Detach a volume from a server.

Parameters:
  • server – The server dict to detach from.
  • volume – The volume dict to detach.
  • wait – If true, waits for volume to be detached.
  • timeout – Seconds to wait for volume detachment. None is forever.
Raises:

OpenStackCloudTimeout if wait time exceeded.

Raises:

OpenStackCloudException on operation error.

download_image(name_or_id, output_path=None, output_file=None, chunk_size=1024)

Download an image by name or ID

Parameters:
  • name_or_id (str) – Name or ID of the image.
  • output_path – the output path to write the image to. Either this or output_file must be specified
  • output_file – a file object (or file-like object) to write the image data to. Only write() will be called on this object. Either this or output_path must be specified
  • chunk_size (int) – size in bytes to read from the wire and buffer at one time. Defaults to 1024
Raises:

OpenStackCloudException in the event download_image is called without exactly one of either output_path or output_file

Raises:

OpenStackCloudResourceNotFound if no images are found matching the name or ID provided

get_baymodel(name_or_id, filters=None, detail=False)

Get a cluster template by name or ID.

Parameters:
  • name_or_id – Name or ID of the cluster template.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A cluster template dict or None if no matching cluster template is found.

get_cluster_template(name_or_id, filters=None, detail=False)

Get a cluster template by name or ID.

Parameters:
  • name_or_id – Name or ID of the cluster template.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A cluster template dict or None if no matching cluster template is found.

get_compute_limits(name_or_id=None)

Get compute limits for a project

Parameters:name_or_id – (optional) project name or ID to get limits for if different from the current project
Raises:OpenStackCloudException if it’s not a valid project
Returns:Munch object with the limits
get_default_network()

Return the network that is configured to be the default interface.

Returns:A network dict if one is found
get_external_ipv4_floating_networks()

Return the networks that are configured to route northbound.

Returns:A list of network munch.Munch if one is found
get_external_ipv4_networks()

Return the networks that are configured to route northbound.

Returns:A list of network munch.Munch if one is found
get_external_ipv6_networks()

Return the networks that are configured to route northbound.

Returns:A list of network munch.Munch if one is found
get_external_networks()

Return the networks that are configured to route northbound.

This should be avoided in favor of the specific ipv4/ipv6 method, but is here for backwards compatibility.

Returns:A list of network munch.Munch if one is found
get_flavor(name_or_id, filters=None, get_extra=True)

Get a flavor by name or ID.

Parameters:
  • name_or_id – Name or ID of the flavor.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

  • get_extra – Whether or not the list_flavors call should get the extra flavor specs.
Returns:

A flavor munch.Munch or None if no matching flavor is found.

get_flavor_by_ram(ram, include=None, get_extra=True)

Get a flavor based on amount of RAM available.

Finds the flavor with the least amount of RAM that is at least as much as the specified amount. If include is given, further filter based on matching flavor name.

Parameters:
  • ram (int) – Minimum amount of RAM.
  • include (string) – If given, will return a flavor whose name contains this string as a substring.
get_floating_ip(id, filters=None)

Get a floating IP by ID

Parameters:
  • id – ID of the floating IP.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A floating IP munch.Munch or None if no matching floating IP is found.

get_image(name_or_id, filters=None)

Get an image by name or ID.

Parameters:
  • name_or_id – Name or ID of the image.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

An image munch.Munch or None if no matching image is found

get_internal_ipv4_networks()

Return the networks that are configured to not route northbound.

Returns:A list of network munch.Munch if one is found
get_internal_ipv6_networks()

Return the networks that are configured to not route northbound.

Returns:A list of network munch.Munch if one is found
get_internal_networks()

Return the networks that are configured to not route northbound.

This should be avoided in favor of the specific ipv4/ipv6 method, but is here for backwards compatibility.

Returns:A list of network munch.Munch if one is found
get_keypair(name_or_id, filters=None)

Get a keypair by name or ID.

Parameters:
  • name_or_id – Name or ID of the keypair.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A keypair munch.Munch or None if no matching keypair is found.

get_nat_destination()

Return the network that is configured to be the NAT destination.

Returns:A network dict if one is found
get_network(name_or_id, filters=None)

Get a network by name or ID.

Parameters:
  • name_or_id – Name or ID of the network.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A network munch.Munch or None if no matching network is found.

get_object(container, obj, query_string=None, resp_chunk_size=1024, outfile=None)

Get the headers and body of an object

Parameters:
  • container (string) – name of the container.
  • obj (string) – name of the object.
  • query_string (string) – query args for uri. (delimiter, prefix, etc.)
  • resp_chunk_size (int) – chunk size of data to read. Only used if the results are being written to a file. (optional, defaults to 1k)
  • outfile – Write the object to a file instead of returning the contents. If this option is given, body in the return tuple will be None. outfile can either be a file path given as a string, or a File like object.
Returns:

Tuple (headers, body) of the object, or None if the object is not found (404)

Raises:

OpenStackCloudException on operation error.

get_object_segment_size(segment_size)

Get a segment size that will work given capabilities

get_port(name_or_id, filters=None)

Get a port by name or ID.

Parameters:
  • name_or_id – Name or ID of the port.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A port munch.Munch or None if no matching port is found.

get_project(name_or_id, filters=None, domain_id=None)

Get exactly one project.

Parameters:
  • name_or_id – project name or ID.
  • filters – a dict containing additional filters to use.
  • domain_id – domain ID (identity v3 only).
Returns:

a list of munch.Munch containing the project description.

Raises:

OpenStackCloudException: if something goes wrong during the OpenStack API call.

get_recordset(zone, name_or_id)

Get a recordset by name or ID.

Parameters:
  • zone – Name or ID of the zone managing the recordset
  • name_or_id – Name or ID of the recordset
Returns:

A recordset dict or None if no matching recordset is found.

get_router(name_or_id, filters=None)

Get a router by name or ID.

Parameters:
  • name_or_id – Name or ID of the router.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A router munch.Munch or None if no matching router is found.

get_security_group(name_or_id, filters=None)

Get a security group by name or ID.

Parameters:
  • name_or_id – Name or ID of the security group.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A security group munch.Munch or None if no matching security group is found.

get_server(name_or_id=None, filters=None, detailed=False, bare=False)

Get a server by name or ID.

Parameters:
  • name_or_id – Name or ID of the server.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

  • detailed – Whether or not to add detailed additional information. Defaults to False.
  • bare – Whether to skip adding any additional information to the server record. Defaults to False, meaning the addresses dict will be populated as needed from neutron. Setting to True implies detailed = False.
Returns:

A server munch.Munch or None if no matching server is found.

get_server_console(server, length=None)

Get the console log for a server.

Parameters:
  • server – The server to fetch the console log for. Can be either a server dict or the Name or ID of the server.
  • length (int) – The number of lines you would like to retrieve from the end of the log. (optional, defaults to all)
Returns:

A string containing the text of the console log or an empty string if the cloud does not support console logs.

Raises:

OpenStackCloudException if an invalid server argument is given or if something else unforseen happens

get_server_group(name_or_id=None, filters=None)

Get a server group by name or ID.

Parameters:
  • name_or_id – Name or ID of the server group.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'policy': 'affinity',
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A server groups dict or None if no matching server group is found.

get_stack(name_or_id, filters=None)

Get exactly one stack.

Parameters:
  • name_or_id – Name or ID of the desired stack.
  • filters – a dict containing additional filters to use. e.g. {‘stack_status’: ‘CREATE_COMPLETE’}
Returns:

a munch.Munch containing the stack description

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call or if multiple matches are found.

get_subnet(name_or_id, filters=None)

Get a subnet by name or ID.

Parameters:
  • name_or_id – Name or ID of the subnet.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    
Returns:

A subnet munch.Munch or None if no matching subnet is found.

get_user(name_or_id, filters=None)

Get exactly one user.

Parameters:
  • name_or_id (string) – user name or ID.
  • filters – a dict containing additional filters to use. OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”
Returns:

a single munch.Munch containing the user description.

Raises:

OpenStackCloudException: if something goes wrong during the OpenStack API call.

get_user_by_id(user_id, normalize=True)

Get a user by ID.

Parameters:
  • user_id (string) – user ID
  • normalize (bool) – Flag to control dict normalization
Returns:

a single munch.Munch containing the user description

get_volume(name_or_id, filters=None)

Get a volume by name or ID.

Parameters:
  • name_or_id – Name or ID of the volume.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A volume munch.Munch or None if no matching volume is found.

get_volume_attach_device(volume, server_id)

Return the device name a volume is attached to for a server.

This can also be used to verify if a volume is attached to a particular server.

Parameters:
  • volume – Volume dict
  • server_id – ID of server to check
Returns:

Device name if attached, None if volume is not attached.

get_volume_backup(name_or_id, filters=None)

Get a volume backup by name or ID.

Returns:A backup munch.Munch or None if no matching backup is found.
get_volume_snapshot(name_or_id, filters=None)

Get a volume by name or ID.

Parameters:
  • name_or_id – Name or ID of the volume snapshot.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A volume munch.Munch or None if no matching volume is found.

get_volume_snapshot_by_id(snapshot_id)

Takes a snapshot_id and gets a dict of the snapshot that maches that ID.

Note: This is more efficient than get_volume_snapshot.

param: snapshot_id: ID of the volume snapshot.

get_volume_type(name_or_id, filters=None)

Get a volume type by name or ID.

Parameters:
  • name_or_id – Name or ID of the volume.
  • filters

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'last_name': 'Smith',
      'other': {
          'gender': 'Female'
      }
    }
    

    OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”

Returns:

A volume munch.Munch or None if no matching volume is found.

get_zone(name_or_id, filters=None)

Get a zone by name or ID.

Parameters:
  • name_or_id – Name or ID of the zone
  • filters – A dictionary of meta data to use for further filtering OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”
Returns:

A zone dict or None if no matching zone is found.

is_user_in_group(name_or_id, group_name_or_id)

Check to see if a user is in a group.

Parameters:
  • name_or_id (string) – User name or ID
  • group_name_or_id (string) – Group name or ID
Returns:

True if user is in the group, False otherwise

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call

list_containers(full_listing=True)

List containers.

Parameters:full_listing – Ignored. Present for backwards compat
Returns:list of Munch of the container objects
Raises:OpenStackCloudException on operation error.
list_floating_ip_pools()

List all available floating IP pools.

NOTE: This function supports the nova-net view of the world. nova-net has been deprecated, so it’s highly recommended to switch to using neutron. get_external_ipv4_floating_networks is what you should almost certainly be using.

Returns:A list of floating IP pool munch.Munch.
list_floating_ips(filters=None)

List all available floating IPs.

Parameters:filters – (optional) dict of filter conditions to push down
Returns:A list of floating IP munch.Munch.
list_keypairs()

List all available keypairs.

Returns:A list of munch.Munch containing keypair info.
list_networks(filters=None)

List all available networks.

Parameters:filters – (optional) dict of filter conditions to push down
Returns:A list of munch.Munch containing network info.
list_objects(container, full_listing=True)

List objects.

Parameters:
  • container – Name of the container to list objects in.
  • full_listing – Ignored. Present for backwards compat
Returns:

list of Munch of the objects

Raises:

OpenStackCloudException on operation error.

list_ports(filters=None)

List all available ports.

Parameters:filters – (optional) dict of filter conditions to push down
Returns:A list of port munch.Munch.
list_recordsets(zone)

List all available recordsets.

Parameters:zone – Name or ID of the zone managing the recordset
Returns:A list of recordsets.
list_router_interfaces(router, interface_type=None)

List all interfaces for a router.

Parameters:
  • router (dict) – A router dict object.
  • interface_type (string) – One of None, “internal”, or “external”. Controls whether all, internal interfaces or external interfaces are returned.
Returns:

A list of port munch.Munch objects.

list_routers(filters=None)

List all available routers.

Parameters:filters – (optional) dict of filter conditions to push down
Returns:A list of router munch.Munch.
list_security_groups(filters=None)

List all available security groups.

Parameters:filters – (optional) dict of filter conditions to push down
Returns:A list of security group munch.Munch.
list_server_groups()

List all available server groups.

Returns:A list of server group dicts.
list_server_security_groups(server)

List all security groups associated with the given server.

Returns:A list of security group munch.Munch.
list_servers(detailed=False, all_projects=False, bare=False)

List all available servers.

Parameters:
  • detailed – Whether or not to add detailed additional information. Defaults to False.
  • all_projects – Whether to list servers from all projects or just the current auth scoped project.
  • bare – Whether to skip adding any additional information to the server record. Defaults to False, meaning the addresses dict will be populated as needed from neutron. Setting to True implies detailed = False.
Returns:

A list of server munch.Munch.

list_subnets(filters=None)

List all available subnets.

Parameters:filters – (optional) dict of filter conditions to push down
Returns:A list of subnet munch.Munch.
list_volume_backups(detailed=True, search_opts=None)

List all volume backups.

Parameters:
  • detailed (bool) – Also list details for each entry
  • search_opts (dict) –

    Search options A dictionary of meta data to use for further filtering. Example:

    {
        'name': 'my-volume-backup',
        'status': 'available',
        'volume_id': 'e126044c-7b4c-43be-a32a-c9cbbc9ddb56',
        'all_tenants': 1
    }
    
Returns:

A list of volume backups munch.Munch.

list_volume_snapshots(detailed=True, search_opts=None)

List all volume snapshots.

Returns:A list of volume snapshots munch.Munch.
list_zones()

List all available zones.

Returns:A list of zones dicts.
pformat(resource)

Wrapper aroud pformat that groks munch objects

pprint(resource)

Wrapper aroud pprint that groks munch objects

Perform integer range searches across a list of dictionaries.

Given a list of dictionaries, search across the list using the given dictionary keys and a range of integer values for each key. Only dictionaries that match ALL search filters across the entire original data set will be returned.

It is not a requirement that each dictionary contain the key used for searching. Those without the key will be considered non-matching.

The range values must be string values and is either a set of digits representing an integer for matching, or a range operator followed by a set of digits representing an integer for matching. If a range operator is not given, exact value matching will be used. Valid operators are one of: <,>,<=,>=

Parameters:
  • data (list) – List of dictionaries to be searched.
  • filters

    Dict describing the one or more range searches to perform. If more than one search is given, the result will be the members of the original data set that match ALL searches. An example of filtering by multiple ranges:

    {"vcpus": "<=5", "ram": "<=2048", "disk": "1"}
    
Returns:

A list subset of the original data set.

Raises:

OpenStackCloudException on invalid range expressions.

remove_router_interface(router, subnet_id=None, port_id=None)

Detach a subnet from an internal router interface.

At least one of subnet_id or port_id must be supplied.

If you specify both subnet and port ID, the subnet ID must correspond to the subnet ID of the first IP address on the port specified by the port ID. Otherwise an error occurs.

Parameters:
  • router (dict) – The dict object of the router being changed
  • subnet_id (string) – The ID of the subnet to use for the interface
  • port_id (string) – The ID of the port to use for the interface
Returns:

None on success

Raises:

OpenStackCloudException on operation error.

remove_server_security_groups(server, security_groups)

Remove security groups from a server

Remove existing security groups from an existing server. If the security groups are not present on the server this will continue unaffected.

Returns:False if server or security groups are undefined, True otherwise.
Raises:OpenStackCloudException, on operation error.
remove_user_from_group(name_or_id, group_name_or_id)

Remove a user from a group.

Parameters:
  • name_or_id (string) – User name or ID
  • group_name_or_id (string) – Group name or ID
Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call

search_baymodels(name_or_id=None, filters=None, detail=False)

Search cluster templates.

Parameters:
  • name_or_id – cluster template name or ID.
  • filters – a dict containing additional filters to use.
  • detail – a boolean to control if we need summarized or detailed output.
Returns:

a list of dict containing the cluster templates

Raises:

OpenStackCloudException: if something goes wrong during the OpenStack API call.

search_cluster_templates(name_or_id=None, filters=None, detail=False)

Search cluster templates.

Parameters:
  • name_or_id – cluster template name or ID.
  • filters – a dict containing additional filters to use.
  • detail – a boolean to control if we need summarized or detailed output.
Returns:

a list of dict containing the cluster templates

Raises:

OpenStackCloudException: if something goes wrong during the OpenStack API call.

search_networks(name_or_id=None, filters=None)

Search networks

Parameters:
  • name_or_id – Name or ID of the desired network.
  • filters – a dict containing additional filters to use. e.g. {‘router:external’: True}
Returns:

a list of munch.Munch containing the network description.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call.

search_ports(name_or_id=None, filters=None)

Search ports

Parameters:
  • name_or_id – Name or ID of the desired port.
  • filters – a dict containing additional filters to use. e.g. {‘device_id’: ‘2711c67a-b4a7-43dd-ace7-6187b791c3f0’}
Returns:

a list of munch.Munch containing the port description.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call.

search_projects(name_or_id=None, filters=None, domain_id=None)

Backwards compatibility method for search_projects

search_projects originally had a parameter list that was name_or_id, filters and list had domain_id first. This method exists in this form to allow code written with positional parameter to still work. But really, use keyword arguments.

search_routers(name_or_id=None, filters=None)

Search routers

Parameters:
  • name_or_id – Name or ID of the desired router.
  • filters – a dict containing additional filters to use. e.g. {‘admin_state_up’: True}
Returns:

a list of munch.Munch containing the router description.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call.

search_server_groups(name_or_id=None, filters=None)

Seach server groups.

Parameters:
  • name – server group name or ID.
  • filters – a dict containing additional filters to use.
Returns:

a list of dicts containing the server groups

Raises:

OpenStackCloudException: if something goes wrong during the OpenStack API call.

search_stacks(name_or_id=None, filters=None)

Search stacks.

Parameters:
  • name_or_id – Name or ID of the desired stack.
  • filters – a dict containing additional filters to use. e.g. {‘stack_status’: ‘CREATE_COMPLETE’}
Returns:

a list of munch.Munch containing the stack description.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call.

search_subnets(name_or_id=None, filters=None)

Search subnets

Parameters:
  • name_or_id – Name or ID of the desired subnet.
  • filters – a dict containing additional filters to use. e.g. {‘enable_dhcp’: True}
Returns:

a list of munch.Munch containing the subnet description.

Raises:

OpenStackCloudException if something goes wrong during the OpenStack API call.

search_users(name_or_id=None, filters=None)

Search users.

Parameters:
  • name_or_id (string) – user name or ID.
  • filters – a dict containing additional filters to use. OR A string containing a jmespath expression for further filtering. Example:: “[?last_name==`Smith`] | [?other.gender]==`Female`]”
Returns:

a list of munch.Munch containing the users

Raises:

OpenStackCloudException: if something goes wrong during the OpenStack API call.

set_server_metadata(name_or_id, metadata)

Set metadata in a server instance.

Parameters:
  • name_or_id (str) – The name or ID of the server instance to update.
  • metadata (dict) – A dictionary with the key=value pairs to set in the server instance. It only updates the key=value pairs provided. Existing ones will remain untouched.
Raises:

OpenStackCloudException on operation error.

update_baymodel(name_or_id, operation, **kwargs)

Update a cluster template.

Parameters:
  • name_or_id – Name or ID of the cluster template being updated.
  • operation – Operation to perform - add, remove, replace.

Other arguments will be passed with kwargs.

Returns:a dict representing the updated cluster template.
Raises:OpenStackCloudException on operation error.
update_cluster_template(name_or_id, operation, **kwargs)

Update a cluster template.

Parameters:
  • name_or_id – Name or ID of the cluster template being updated.
  • operation – Operation to perform - add, remove, replace.

Other arguments will be passed with kwargs.

Returns:a dict representing the updated cluster template.
Raises:OpenStackCloudException on operation error.
update_object(container, name, metadata=None, **headers)

Update the metadata of an object

Parameters:
  • container – The name of the container the object is in
  • name – Name for the object within the container.
  • metadata – This dict will get changed into headers that set metadata of the object
  • headers – These will be passed through to the object update API as HTTP Headers.
Raises:

OpenStackCloudException on operation error.

update_port(name_or_id, **kwargs)

Update a port

Note: to unset an attribute use None value. To leave an attribute untouched just omit it.

Parameters:
  • name_or_id – name or ID of the port to update. (Required)
  • name – A symbolic name for the port. (Optional)
  • admin_state_up – The administrative status of the port, which is up (true) or down (false). (Optional)
  • fixed_ips

    List of ip_addresses and subnet_ids. (Optional) If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port. For example:

    [
      {
        "ip_address": "10.29.29.13",
        "subnet_id": "a78484c4-c380-4b47-85aa-21c51a2d8cbd"
      }, ...
    ]
    
  • security_groups – List of security group UUIDs. (Optional)
  • allowed_address_pairs

    Allowed address pairs list (Optional) For example:

    [
      {
        "ip_address": "23.23.23.1",
        "mac_address": "fa:16:3e:c4:cd:3f"
      }, ...
    ]
    
  • extra_dhcp_opts

    Extra DHCP options. (Optional). For example:

    [
      {
        "opt_name": "opt name1",
        "opt_value": "value1"
      }, ...
    ]
    
  • device_owner – The ID of the entity that uses this port. For example, a DHCP agent. (Optional)
  • device_id – The ID of the resource this port is attached to.
Returns:

a munch.Munch describing the updated port.

Raises:

OpenStackCloudException on operation error.

update_recordset(zone, name_or_id, **kwargs)

Update a recordset.

Parameters:
  • zone – Name or ID of the zone managing the recordset
  • name_or_id – Name or ID of the recordset being updated.
  • records – List of the recordset definitions
  • description – Description of the recordset
  • ttl – TTL (Time to live) value in seconds of the recordset
Returns:

a dict representing the updated recordset.

Raises:

OpenStackCloudException on operation error.

update_router(name_or_id, name=None, admin_state_up=None, ext_gateway_net_id=None, enable_snat=None, ext_fixed_ips=None)

Update an existing logical router.

Parameters:
  • name_or_id (string) – The name or UUID of the router to update.
  • name (string) – The new router name.
  • admin_state_up (bool) – The administrative state of the router.
  • ext_gateway_net_id (string) – The network ID for the external gateway.
  • enable_snat (bool) – Enable Source NAT (SNAT) attribute.
  • ext_fixed_ips (list) –

    List of dictionaries of desired IP and/or subnet on the external network. Example:

    [
      {
        "subnet_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
        "ip_address": "192.168.10.2"
      }
    ]
    
Returns:

The router object.

Raises:

OpenStackCloudException on operation error.

update_security_group(name_or_id, **kwargs)

Update a security group

Parameters:
  • name_or_id (string) – Name or ID of the security group to update.
  • name (string) – New name for the security group.
  • description (string) – New description for the security group.
Returns:

A munch.Munch describing the updated security group.

Raises:

OpenStackCloudException on operation error.

update_server(name_or_id, **kwargs)

Update a server.

Parameters:name_or_id – Name of the server to be updated.
Name:New name for the server
Description:New description for the server
Returns:a dictionary representing the updated server.
Raises:OpenStackCloudException on operation error.
update_stack(name_or_id, template_file=None, template_url=None, template_object=None, files=None, rollback=True, wait=False, timeout=3600, environment_files=None, **parameters)

Update a stack.

Parameters:
  • name_or_id (string) – Name or ID of the stack to update.
  • template_file (string) – Path to the template.
  • template_url (string) – URL of template.
  • template_object (string) – URL to retrieve template object.
  • files (dict) – dict of additional file content to include.
  • rollback (boolean) – Enable rollback on update failure.
  • wait (boolean) – Whether to wait for the delete to finish.
  • timeout (int) – Stack update timeout in seconds.
  • environment_files (list) – Paths to environment files to apply.

Other arguments will be passed as stack parameters which will take precedence over any parameters specified in the environments.

Only one of template_file, template_url, template_object should be specified.

Returns:a dict containing the stack description
Raises:OpenStackCloudException if something goes wrong during the OpenStack API calls
update_subnet(name_or_id, subnet_name=None, enable_dhcp=None, gateway_ip=None, disable_gateway_ip=None, allocation_pools=None, dns_nameservers=None, host_routes=None)

Update an existing subnet.

Parameters:
  • name_or_id (string) – Name or ID of the subnet to update.
  • subnet_name (string) – The new name of the subnet.
  • enable_dhcp (bool) – Set to True if DHCP is enabled and False if disabled.
  • gateway_ip (string) – The gateway IP address. When you specify both allocation_pools and gateway_ip, you must ensure that the gateway IP does not overlap with the specified allocation pools.
  • disable_gateway_ip (bool) – Set to True if gateway IP address is disabled and False if enabled. It is not allowed with gateway_ip. Default is False.
  • allocation_pools (list) –

    A list of dictionaries of the start and end addresses for the allocation pools. For example:

    [
      {
        "start": "192.168.199.2",
        "end": "192.168.199.254"
      }
    ]
    
  • dns_nameservers (list) –

    A list of DNS name servers for the subnet. For example:

    [ "8.8.8.7", "8.8.8.8" ]
    
  • host_routes (list) –

    A list of host route dictionaries for the subnet. For example:

    [
      {
        "destination": "0.0.0.0/0",
        "nexthop": "123.456.78.9"
      },
      {
        "destination": "192.168.0.0/24",
        "nexthop": "192.168.0.1"
      }
    ]
    
Returns:

The updated subnet object.

Raises:

OpenStackCloudException on operation error.

update_zone(name_or_id, **kwargs)

Update a zone.

Parameters:
  • name_or_id – Name or ID of the zone being updated.
  • email – Email of the zone owner (only applies if zone_type is primary)
  • description – Description of the zone
  • ttl – TTL (Time to live) value in seconds
  • masters – Master nameservers (only applies if zone_type is secondary)
Returns:

a dict representing the updated zone.

Raises:

OpenStackCloudException on operation error.

wait_for_server(server, auto_ip=True, ips=None, ip_pool=None, reuse=True, timeout=180, nat_destination=None)

Wait for a server to reach ACTIVE status.

class shade.OperatorCloud(cloud_config=None, manager=None, log_inner_exceptions=False, strict=False, app_name=None, app_version=None, **kwargs)

Represent a privileged/operator connection to an OpenStack Cloud.

OperatorCloud is the entry point for all admin operations, regardless of which OpenStack service those operations are for.

See the OpenStackCloud class for a description of most options.

add_flavor_access(flavor_id, project_id)

Grant access to a private flavor for a project/tenant.

Parameters:
  • flavor_id (string) – ID of the private flavor.
  • project_id (string) – ID of the project/tenant.
Raises:

OpenStackCloudException on operation error.

add_host_to_aggregate(name_or_id, host_name)

Add a host to an aggregate.

Parameters:
  • name_or_id – Name or ID of the host aggregate.
  • host_name – Host to add.
Raises:

OpenStackCloudException on operation error.

add_volume_type_access(name_or_id, project_id)

Grant access on a volume_type to a project.

Parameters:
  • name_or_id – ID or name of a volume_type
  • project_id – A project id

NOTE: the call works even if the project does not exist.

Raises:OpenStackCloudException on operation error.
create_aggregate(name, availability_zone=None)

Create a new host aggregate.

Parameters:
  • name – Name of the host aggregate being created
  • availability_zone – Availability zone to assign hosts
Returns:

a dict representing the new host aggregate.

Raises:

OpenStackCloudException on operation error.

create_domain(name, description=None, enabled=True)

Create a Keystone domain.

Parameters:
  • name – The name of the domain.
  • description – A description of the domain.
  • enabled – Is the domain enabled or not (default True).
Returns:

a munch.Munch containing the domain description

Raises:

OpenStackCloudException – if the domain cannot be created

create_endpoint(service_name_or_id, url=None, interface=None, region=None, enabled=True, **kwargs)

Create a Keystone endpoint.

Parameters:
  • service_name_or_id – Service name or id for this endpoint.
  • url – URL of the endpoint
  • interface – Interface type of the endpoint
  • public_url – Endpoint public URL.
  • internal_url – Endpoint internal URL.
  • admin_url – Endpoint admin URL.
  • region – Endpoint region.
  • enabled – Whether the endpoint is enabled
NOTE: Both v2 (public_url, internal_url, admin_url) and v3
(url, interface) calling semantics are supported. But you can only use one of them at a time.
Returns:a list of munch.Munch containing the endpoint description
Raises:OpenStackCloudException if the service cannot be found or if something goes wrong during the openstack API call.
create_flavor(name, ram, vcpus, disk, flavorid='auto', ephemeral=0, swap=0, rxtx_factor=1.0, is_public=True)

Create a new flavor.

Parameters:
  • name – Descriptive name of the flavor
  • ram – Memory in MB for the flavor
  • vcpus – Number of VCPUs for the flavor
  • disk – Size of local disk in GB
  • flavorid – ID for the flavor (optional)
  • ephemeral – Ephemeral space size in GB
  • swap – Swap space in MB
  • rxtx_factor – RX/TX factor
  • is_public – Make flavor accessible to the public
Returns:

A munch.Munch describing the new flavor.

Raises:

OpenStackCloudException on operation error.

create_group(name, description, domain=None)

Create a group.

Parameters:
  • name (string) – Group name.
  • description (string) – Group description.
  • domain (string) – Domain name or ID for the group.
Returns:

A munch.Munch containing the group description.

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

create_role(name)

Create a Keystone role.

Parameters:name (string) – The name of the role.
Returns:a munch.Munch containing the role description
Raises:OpenStackCloudException – if the role cannot be created
create_service(name, enabled=True, **kwargs)

Create a service.

Parameters:
  • name – Service name.
  • type – Service type. (type or service_type required.)
  • service_type – Service type. (type or service_type required.)
  • description – Service description (optional).
  • enabled – Whether the service is enabled (v3 only)
Returns:

a munch.Munch containing the services description, i.e. the following attributes:: - id: <service id> - name: <service name> - type: <service type> - service_type: <service type> - description: <service description>

Raises:

OpenStackCloudException if something goes wrong during the openstack API call.

delete_aggregate(name_or_id)

Delete a host aggregate.

Parameters:name_or_id – Name or ID of the host aggregate to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_compute_quotas(name_or_id)

Delete quota for a project

Parameters:name_or_id – project name or id
Raises:OpenStackCloudException if it’s not a valid project or the nova client call failed
Returns:dict with the quotas
delete_domain(domain_id=None, name_or_id=None)

Delete a Keystone domain.

Parameters:
  • domain_id – ID of the domain to delete.
  • name_or_id – Name or ID of the domain to delete.
Returns:

True if delete succeeded, False otherwise.

Raises:

OpenStackCloudException if something goes wrong during the openstack API call.

delete_endpoint(id)

Delete a Keystone endpoint.

Parameters:id – Id of the endpoint to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException if something goes wrong during the openstack API call.
delete_flavor(name_or_id)

Delete a flavor

Parameters:name_or_id – ID or name of the flavor to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException on operation error.
delete_group(name_or_id)

Delete a group

Parameters:name_or_id – ID or name of the group to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException: if something goes wrong during the openstack API call.
delete_network_quotas(name_or_id)

Delete network quotas for a project

Parameters:name_or_id – project name or id
Raises:OpenStackCloudException if it’s not a valid project or the network client call failed
Returns:dict with the quotas
delete_role(name_or_id)

Delete a Keystone role.

Parameters:id (string) – Name or id of the role to delete.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException if something goes wrong during the openstack API call.
delete_service(name_or_id)

Delete a Keystone service.

Parameters:name_or_id – Service name or id.
Returns:True if delete succeeded, False otherwise.
Raises:OpenStackCloudException if something goes wrong during the openstack API call
delete_volume_quotas(name_or_id)

Delete volume quotas for a project

Parameters:name_or_id – project name or id
Raises:OpenStackCloudException if it’s not a valid project or the cinder client call failed
Returns:dict with the quotas
get_aggregate(name_or_id, filters=None)

Get an aggregate by name or ID.

Parameters:
  • name_or_id – Name or ID of the aggregate.
  • filters (dict) –

    A dictionary of meta data to use for further filtering. Elements of this dictionary may, themselves, be dictionaries. Example:

    {
      'availability_zone': 'nova',
      'metadata': {
          'cpu_allocation_ratio': '1.0'
      }
    }
    
Returns:

An aggregate dict or None if no matching aggregate is found.

get_compute_quotas(name_or_id)

Get quota for a project

Parameters:name_or_id – project name or id
Raises:OpenStackCloudException if it’s not a valid project
Returns:Munch object with the quotas
get_compute_usage(name_or_id, start=None, end=None)

Get usage for a specific project

Parameters:
  • name_or_id – project name or id
  • startdatetime.datetime or string. Start date in UTC Defaults to 2010-07-06T12:00:00Z (the date the OpenStack project was started)
  • enddatetime.datetime or string. End date in UTC. Defaults to now
Raises:

OpenStackCloudException if it’s not a valid project

Returns:

Munch object with the usage

get_domain(domain_id=None, name_or_id=None, filters=None)

Get exactly one Keystone domain.

Parameters:
  • domain_id – domain id.
  • name_or_id – domain name or id.
  • filters (dict) – A dict containing additional filters to use. Keys to search on are id, name, enabled and description.
Returns:

a munch.Munch containing the domain description, or None if not found. Each munch.Munch contains the following attributes:: - id: <domain id> - name: <domain name> - description: <domain description>

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

get_endpoint(id, filters=None)

Get exactly one Keystone endpoint.

Parameters:
  • id – endpoint id.
  • filters – a dict containing additional filters to use. e.g. {‘region’: ‘region-a.geo-1’}
Returns:

a munch.Munch containing the endpoint description. i.e. a munch.Munch containing the following attributes:: - id: <endpoint id> - region: <endpoint region> - public_url: <endpoint public url> - internal_url: <endpoint internal url> (optional) - admin_url: <endpoint admin url> (optional)

get_group(name_or_id, filters=None)

Get exactly one Keystone group.

Parameters:
  • id – Group name or id.
  • filters – A dict containing additional filters to use.
Returns:

A munch.Munch containing the group description.

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

get_machine(name_or_id)

Get Machine by name or uuid

Search the baremetal host out by utilizing the supplied id value which can consist of a name or UUID.

Parameters:name_or_id – A node name or UUID that will be looked up.
Returns:munch.Munch representing the node found or None if no nodes are found.
get_machine_by_mac(mac)

Get machine by port MAC address

Parameters:mac – Port MAC address to query in order to return a node.
Returns:munch.Munch representing the node found or None if the node is not found.
get_network_quotas(name_or_id)

Get network quotas for a project

Parameters:name_or_id – project name or id
Raises:OpenStackCloudException if it’s not a valid project
Returns:Munch object with the quotas
get_role(name_or_id, filters=None)

Get exactly one Keystone role.

Parameters:
  • id – role name or id.
  • filters – a dict containing additional filters to use.
Returns:

a single munch.Munch containing the role description. Each munch.Munch contains the following attributes:

- id: <role id>
- name: <role name>
- description: <role description>

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

get_service(name_or_id, filters=None)

Get exactly one Keystone service.

Parameters:
  • name_or_id – Name or id of the desired service.
  • filters – a dict containing additional filters to use. e.g. {‘type’: ‘network’}
Returns:

a munch.Munch containing the services description, i.e. the following attributes:: - id: <service id> - name: <service name> - type: <service type> - description: <service description>

Raises:

OpenStackCloudException if something goes wrong during the openstack API call or if multiple matches are found.

get_volume_quotas(name_or_id)

Get volume quotas for a project

Parameters:name_or_id – project name or id
Raises:OpenStackCloudException if it’s not a valid project
Returns:Munch object with the quotas
get_volume_type_access(name_or_id)

Return a list of volume_type_access.

Parameters:name_or_id – Name or ID of the volume type.
Raises:OpenStackCloudException on operation error.
grant_role(name_or_id, user=None, group=None, project=None, domain=None, wait=False, timeout=60)

Grant a role to a user.

Parameters:
  • name_or_id (string) – The name or id of the role.
  • user (string) – The name or id of the user.
  • group (string) – The name or id of the group. (v3)
  • project (string) – The name or id of the project.
  • domain (string) – The id of the domain. (v3)
  • wait (bool) – Wait for role to be granted
  • timeout (int) – Timeout to wait for role to be granted
NOTE: for wait and timeout, sometimes granting roles is not
instantaneous for granting roles.

NOTE: project is required for keystone v2

Returns:True if the role is assigned, otherwise False
Raises:OpenStackCloudException – if the role cannot be granted
inspect_machine(name_or_id, wait=False, timeout=3600)

Inspect a Barmetal machine

Engages the Ironic node inspection behavior in order to collect metadata about the baremetal machine.

Parameters:
  • name_or_id – String representing machine name or UUID value in order to identify the machine.
  • wait – Boolean value controlling if the method is to wait for the desired state to be reached or a failure to occur.
  • timeout – Integer value, defautling to 3600 seconds, for the$ wait state to reach completion.
Returns:

munch.Munch representing the current state of the machine upon exit of the method.

list_aggregates()

List all available host aggregates.

Returns:A list of aggregate dicts.
list_domains()

List Keystone domains.

Returns:a list of munch.Munch containing the domain description.
Raises:OpenStackCloudException: if something goes wrong during the openstack API call.
list_endpoints()

List Keystone endpoints.

Returns:a list of munch.Munch containing the endpoint description
Raises:OpenStackCloudException: if something goes wrong during the openstack API call.
list_flavor_access(flavor_id)

List access from a private flavor for a project/tenant.

Parameters:flavor_id (string) – ID of the private flavor.
Returns:a list of munch.Munch containing the access description
Raises:OpenStackCloudException on operation error.
list_hypervisors()

List all hypervisors

Returns:A list of hypervisor munch.Munch.
list_magnum_services()

List all Magnum services. :returns: a list of dicts containing the service details.

Raises:OpenStackCloudException on operation error.
list_role_assignments(filters=None)

List Keystone role assignments

Parameters:filters (dict) –

Dict of filter conditions. Acceptable keys are:

  • ‘user’ (string) - User ID to be used as query filter.
  • ‘group’ (string) - Group ID to be used as query filter.
  • ‘project’ (string) - Project ID to be used as query filter.
  • ‘domain’ (string) - Domain ID to be used as query filter.
  • ‘role’ (string) - Role ID to be used as query filter.
  • ‘os_inherit_extension_inherited_to’ (string) - Return inherited role assignments for either ‘projects’ or ‘domains’
  • ‘effective’ (boolean) - Return effective role assignments.
  • ‘include_subtree’ (boolean) - Include subtree

‘user’ and ‘group’ are mutually exclusive, as are ‘domain’ and ‘project’.

NOTE: For keystone v2, only user, project, and role are used.
Project and user are both required in filters.
Returns:a list of munch.Munch containing the role assignment description. Contains the following attributes:
- id: <role id>
- user|group: <user or group id>
- project|domain: <project or domain id>
Raises:OpenStackCloudException: if something goes wrong during the openstack API call.
list_roles()

List Keystone roles.

Returns:a list of munch.Munch containing the role description.
Raises:OpenStackCloudException: if something goes wrong during the openstack API call.
list_services()

List all Keystone services.

Returns:a list of munch.Munch containing the services description
Raises:OpenStackCloudException if something goes wrong during the openstack API call.
node_set_provision_state(name_or_id, state, configdrive=None, wait=False, timeout=3600)

Set Node Provision State

Enables a user to provision a Machine and optionally define a config drive to be utilized.

Parameters:
  • name_or_id (string) – The Name or UUID value representing the baremetal node.
  • state (string) – The desired provision state for the baremetal node.
  • configdrive (string) – An optional URL or file or path representing the configdrive. In the case of a directory, the client API will create a properly formatted configuration drive file and post the file contents to the API for deployment.
  • wait (boolean) – A boolean value, defaulted to false, to control if the method will wait for the desire end state to be reached before returning.
  • timeout (integer) – Integer value, defaulting to 3600 seconds, representing the amount of time to wait for the desire end state to be reached.
Raises:

OpenStackCloudException on operation error.

Returns:

munch.Munch representing the current state of the machine upon exit of the method.

patch_machine(name_or_id, patch)

Patch Machine Information

This method allows for an interface to manipulate node entries within Ironic. Specifically, it is a pass-through for the ironicclient.nodes.update interface which allows the Ironic Node properties to be updated.

Parameters:
  • node_id – The server object to attach to.
  • patch

    The JSON Patch document is a list of dictonary objects that comply with RFC 6902 which can be found at https://tools.ietf.org/html/rfc6902.

    Example patch construction:

    patch=[]
    patch.append({
        'op': 'remove',
        'path': '/instance_info'
    })
    patch.append({
        'op': 'replace',
        'path': '/name',
        'value': 'newname'
    })
    patch.append({
        'op': 'add',
        'path': '/driver_info/username',
        'value': 'administrator'
    })
    
Raises:

OpenStackCloudException on operation error.

Returns:

munch.Munch representing the newly updated node.

register_machine(nics, wait=False, timeout=3600, lock_timeout=600, **kwargs)

Register Baremetal with Ironic

Allows for the registration of Baremetal nodes with Ironic and population of pertinant node information or configuration to be passed to the Ironic API for the node.

This method also creates ports for a list of MAC addresses passed in to be utilized for boot and potentially network configuration.

If a failure is detected creating the network ports, any ports created are deleted, and the node is removed from Ironic.

Parameters:
  • nics (list) –

    An array of MAC addresses that represent the network interfaces for the node to be created.

    Example:

    [
        {'mac': 'aa:bb:cc:dd:ee:01'},
        {'mac': 'aa:bb:cc:dd:ee:02'}
    ]
    
  • wait – Boolean value, defaulting to false, to wait for the node to reach the available state where the node can be provisioned. It must be noted, when set to false, the method will still wait for locks to clear before sending the next required command.
  • timeout – Integer value, defautling to 3600 seconds, for the wait state to reach completion.
  • lock_timeout – Integer value, defaulting to 600 seconds, for locks to clear.
  • kwargs – Key value pairs to be passed to the Ironic API, including uuid, name, chassis_uuid, driver_info, parameters.
Raises:

OpenStackCloudException on operation error.

Returns:

Returns a munch.Munch representing the new baremetal node.

remove_flavor_access(flavor_id, project_id)

Revoke access from a private flavor for a project/tenant.

Parameters:
  • flavor_id (string) – ID of the private flavor.
  • project_id (string) – ID of the project/tenant.
Raises:

OpenStackCloudException on operation error.

remove_host_from_aggregate(name_or_id, host_name)

Remove a host from an aggregate.

Parameters:
  • name_or_id – Name or ID of the host aggregate.
  • host_name – Host to remove.
Raises:

OpenStackCloudException on operation error.

remove_machine_from_maintenance(name_or_id)

Remove Baremetal Machine from Maintenance State

Similarly to set_machine_maintenance_state, this method removes a machine from maintenance state. It must be noted that this method simpily calls set_machine_maintenace_state for the name_or_id requested and sets the state to False.

Parameters:name_or_id (string) – The Name or UUID value representing the baremetal node.
Raises:OpenStackCloudException on operation error.
Returns:None
remove_volume_type_access(name_or_id, project_id)

Revoke access on a volume_type to a project.

Parameters:
  • name_or_id – ID or name of a volume_type
  • project_id – A project id
Raises:

OpenStackCloudException on operation error.

revoke_role(name_or_id, user=None, group=None, project=None, domain=None, wait=False, timeout=60)

Revoke a role from a user.

Parameters:
  • name_or_id (string) – The name or id of the role.
  • user (string) – The name or id of the user.
  • group (string) – The name or id of the group. (v3)
  • project (string) – The name or id of the project.
  • domain (string) – The id of the domain. (v3)
  • wait (bool) – Wait for role to be revoked
  • timeout (int) – Timeout to wait for role to be revoked
NOTE: for wait and timeout, sometimes revoking roles is not
instantaneous for revoking roles.

NOTE: project is required for keystone v2

Returns:True if the role is revoke, otherwise False
Raises:OpenStackCloudException – if the role cannot be removed
search_aggregates(name_or_id=None, filters=None)

Seach host aggregates.

Parameters:
  • name – aggregate name or id.
  • filters – a dict containing additional filters to use.
Returns:

a list of dicts containing the aggregates

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

search_domains(filters=None, name_or_id=None)

Search Keystone domains.

Parameters:
  • name_or_id – domain name or id
  • filters (dict) – A dict containing additional filters to use. Keys to search on are id, name, enabled and description.
Returns:

a list of munch.Munch containing the domain description. Each munch.Munch contains the following attributes:: - id: <domain id> - name: <domain name> - description: <domain description>

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

search_endpoints(id=None, filters=None)

List Keystone endpoints.

Parameters:
  • id – endpoint id.
  • filters – a dict containing additional filters to use. e.g. {‘region’: ‘region-a.geo-1’}
Returns:

a list of munch.Munch containing the endpoint description. Each dict contains the following attributes:: - id: <endpoint id> - region: <endpoint region> - public_url: <endpoint public url> - internal_url: <endpoint internal url> (optional) - admin_url: <endpoint admin url> (optional)

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

search_groups(name_or_id=None, filters=None)

Search Keystone groups.

Parameters:
  • name – Group name or id.
  • filters – A dict containing additional filters to use.
Returns:

A list of munch.Munch containing the group description.

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

search_roles(name_or_id=None, filters=None)

Seach Keystone roles.

Parameters:
  • name (string) – role name or id.
  • filters (dict) – a dict containing additional filters to use.
Returns:

a list of munch.Munch containing the role description. Each munch.Munch contains the following attributes:

- id: <role id>
- name: <role name>
- description: <role description>

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

search_services(name_or_id=None, filters=None)

Search Keystone services.

Parameters:
  • name_or_id – Name or id of the desired service.
  • filters – a dict containing additional filters to use. e.g. {‘type’: ‘network’}.
Returns:

a list of munch.Munch containing the services description

Raises:

OpenStackCloudException if something goes wrong during the openstack API call.

set_aggregate_metadata(name_or_id, metadata)

Set aggregate metadata, replacing the existing metadata.

Parameters:
  • name_or_id – Name of the host aggregate to update
  • metadata – Dict containing metadata to replace (Use {‘key’: None} to remove a key)
Returns:

a dict representing the new host aggregate.

Raises:

OpenStackCloudException on operation error.

set_compute_quotas(name_or_id, **kwargs)

Set a quota in a project

Parameters:
  • name_or_id – project name or id
  • kwargs – key/value pairs of quota name and quota value
Raises:

OpenStackCloudException if the resource to set the quota does not exist.

set_flavor_specs(flavor_id, extra_specs)

Add extra specs to a flavor

Parameters:
  • flavor_id (string) – ID of the flavor to update.
  • extra_specs (dict) – Dictionary of key-value pairs.
Raises:

OpenStackCloudException on operation error.

Raises:

OpenStackCloudResourceNotFound if flavor ID is not found.

set_machine_maintenance_state(name_or_id, state=True, reason=None)

Set Baremetal Machine Maintenance State

Sets Baremetal maintenance state and maintenance reason.

Parameters:
  • name_or_id (string) – The Name or UUID value representing the baremetal node.
  • state (boolean) – The desired state of the node. True being in maintenance where as False means the machine is not in maintenance mode. This value defaults to True if not explicitly set.
  • reason (string) – An optional freeform string that is supplied to the baremetal API to allow for notation as to why the node is in maintenance state.
Raises:

OpenStackCloudException on operation error.

Returns:

None

set_machine_power_off(name_or_id)

De-activate baremetal machine power

This is a method that sets the node power state to “off”.

Params string name_or_id:
 A string representing the baremetal node to have power turned to an “off” state.
Raises:OpenStackCloudException on operation error.
Returns:
set_machine_power_on(name_or_id)

Activate baremetal machine power

This is a method that sets the node power state to “on”.

Params string name_or_id:
 A string representing the baremetal node to have power turned to an “on” state.
Raises:OpenStackCloudException on operation error.
Returns:None
set_machine_power_reboot(name_or_id)

De-activate baremetal machine power

This is a method that sets the node power state to “reboot”, which in essence changes the machine power state to “off”, and that back to “on”.

Params string name_or_id:
 A string representing the baremetal node to have power turned to an “off” state.
Raises:OpenStackCloudException on operation error.
Returns:None
set_network_quotas(name_or_id, **kwargs)

Set a network quota in a project

Parameters:
  • name_or_id – project name or id
  • kwargs – key/value pairs of quota name and quota value
Raises:

OpenStackCloudException if the resource to set the quota does not exist.

set_volume_quotas(name_or_id, **kwargs)

Set a volume quota in a project

Parameters:
  • name_or_id – project name or id
  • kwargs – key/value pairs of quota name and quota value
Raises:

OpenStackCloudException if the resource to set the quota does not exist.

unregister_machine(nics, uuid, wait=False, timeout=600)

Unregister Baremetal from Ironic

Removes entries for Network Interfaces and baremetal nodes from an Ironic API

Parameters:
  • nics (list) – An array of strings that consist of MAC addresses to be removed.
  • uuid (string) – The UUID of the node to be deleted.
  • wait – Boolean value, defaults to false, if to block the method upon the final step of unregistering the machine.
  • timeout – Integer value, representing seconds with a default value of 600, which controls the maximum amount of time to block the method’s completion on.
Raises:

OpenStackCloudException on operation failure.

unset_flavor_specs(flavor_id, keys)

Delete extra specs from a flavor

Parameters:
  • flavor_id (string) – ID of the flavor to update.
  • keys (list) – List of spec keys to delete.
Raises:

OpenStackCloudException on operation error.

Raises:

OpenStackCloudResourceNotFound if flavor ID is not found.

update_aggregate(name_or_id, **kwargs)

Update a host aggregate.

Parameters:
  • name_or_id – Name or ID of the aggregate being updated.
  • name – New aggregate name
  • availability_zone – Availability zone to assign to hosts
Returns:

a dict representing the updated host aggregate.

Raises:

OpenStackCloudException on operation error.

update_group(name_or_id, name=None, description=None)

Update an existing group

Parameters:
  • name (string) – New group name.
  • description (string) – New group description.
Returns:

A munch.Munch containing the group description.

Raises:

OpenStackCloudException: if something goes wrong during the openstack API call.

update_machine(name_or_id, chassis_uuid=None, driver=None, driver_info=None, name=None, instance_info=None, instance_uuid=None, properties=None)

Update a machine with new configuration information

A user-friendly method to perform updates of a machine, in whole or part.

Parameters:
  • name_or_id (string) – A machine name or UUID to be updated.
  • chassis_uuid (string) – Assign a chassis UUID to the machine. NOTE: As of the Kilo release, this value cannot be changed once set. If a user attempts to change this value, then the Ironic API, as of Kilo, will reject the request.
  • driver (string) – The driver name for controlling the machine.
  • driver_info (dict) – The dictonary defining the configuration that the driver will utilize to control the machine. Permutations of this are dependent upon the specific driver utilized.
  • name (string) – A human relatable name to represent the machine.
  • instance_info (dict) – A dictonary of configuration information that conveys to the driver how the host is to be configured when deployed. be deployed to the machine.
  • instance_uuid (string) – A UUID value representing the instance that the deployed machine represents.
  • properties (dict) – A dictonary defining the properties of a machine.
Raises:

OpenStackCloudException on operation error.

Returns:

munch.Munch containing a machine sub-dictonary consisting of the updated data returned from the API update operation, and a list named changes which contains all of the API paths that received updates.