Connection

Connection

The Connection class is the primary interface to the Python SDK. It maintains a context for a connection to a region of a cloud provider. The Connection has an attribute to access each OpenStack service.

At a minimum, the Connection class needs to be created with a config or the parameters to build one.

While the overall system is very flexible, there are four main use cases for different ways to create a Connection.

  • Using config settings and keyword arguments as described in Configuring OpenStack SDK Applications
  • Using only keyword arguments passed to the constructor ignoring config files and environment variables.
  • Using an existing authenticated keystoneauth1.session.Session, such as might exist inside of an OpenStack service operational context.
  • Using an existing CloudRegion.

Using config settings

For users who want to create a Connection making use of named clouds in clouds.yaml files, OS_ environment variables and python keyword arguments, the openstack.connect() factory function is the recommended way to go:

import openstack

conn = openstack.connect(cloud='example', region_name='earth1')

If the application in question is a command line application that should also accept command line arguments, an argparse.Namespace can be passed to openstack.connect() that will have relevant arguments added to it and then subsequently consumed by the construtor:

import argparse
import openstack

options = argparse.ArgumentParser(description='Awesome OpenStack App')
conn = openstack.connect(options=options)

Using Only Keyword Arguments

If the application wants to avoid loading any settings from clouds.yaml or environment variables, use the Connection constructor directly. As long as the cloud argument is omitted or None, the Connection constructor will not load settings from files or the environment.

Note

This is a different default behavior than the connect() factory function. In connect() if cloud is omitted or None, a default cloud will be loaded, defaulting to the envvars cloud if it exists.

from openstack import connection

conn = connection.Connection(
    region_name='example-region',
    auth=dict(
        auth_url='https://auth.example.com',
        username='amazing-user',
        password='super-secret-password',
        project_id='33aa1afc-03fe-43b8-8201-4e0d3b4b8ab5',
        user_domain_id='054abd68-9ad9-418b-96d3-3437bb376703'),
    compute_api_version='2',
    identity_interface='internal')

Per-service settings as needed by keystoneauth1.adapter.Adapter such as api_version, service_name, and interface can be set, as seen above, by prefixing them with the official service-type name of the service. region_name is a setting for the entire CloudRegion and cannot be set per service.

From existing authenticated Session

For applications that already have an authenticated Session, simply passing it to the Connection constructor is all that is needed:

from openstack import connection

conn = connection.Connection(
    session=session,
    region_name='example-region',
    compute_api_version='2',
    identity_interface='internal')

From existing CloudRegion

If you already have an CloudRegion you can pass it in instead:

from openstack import connection
import openstack.config

config = openstack.config.get_cloud_region(
    cloud='example', region_name='earth')
conn = connection.Connection(config=config)

Using the Connection

Services are accessed through an attribute named after the service’s official service-type.

List

An iterator containing a list of all the projects is retrieved in this manner:

projects = conn.identity.projects()

Find or create

If you wanted to make sure you had a network named ‘zuul’, you would first try to find it and if that fails, you would create it:

network = conn.network.find_network("zuul")
if network is None:
    network = conn.network.create_network(name="zuul")

Additional information about the services can be found in the Service Proxies documentation.

from_config

openstack.connection.from_config(cloud=None, config=None, options=None, **kwargs)

Create a Connection using openstack.config

Parameters:
  • cloud (str) – Use the cloud configuration details when creating the Connection.
  • config (openstack.config.cloud_region.CloudRegion) – An existing CloudRegion configuration. If no config is provided, openstack.config.OpenStackConfig will be called, and the provided name will be used in determining which cloud’s configuration details will be used in creation of the Connection instance.
  • options (argparse.Namespace) – Allows direct passing in of options to be added to the cloud config. This does not have to be an actual instance of argparse.Namespace, despite the naming of the the openstack.config.loader.OpenStackConfig.get_one argument to which it is passed.
Return type:

Connection

Connection Object

class openstack.connection.Connection(cloud=None, config=None, session=None, app_name=None, app_version=None, authenticator=None, profile=None, extra_services=None, **kwargs)

Create a connection to a cloud.

A connection needs information about how to connect, how to authenticate and how to select the appropriate services to use.

The recommended way to provide this information is by referencing a named cloud config from an existing clouds.yaml file. The cloud name envvars may be used to consume a cloud configured via OS_ environment variables.

A pre-existing CloudRegion object can be passed in lieu of a cloud name, for cases where the user already has a fully formed CloudRegion and just wants to use it.

Similarly, if for some reason the user already has a Session and wants to use it, it may be passed in.

Parameters:
  • cloud (str) – Name of the cloud from config to use.
  • config (CloudRegion) – CloudRegion object representing the config for the region of the cloud in question.
  • session (Session) – A session object compatible with Session.
  • app_name (str) – Name of the application to be added to User Agent.
  • app_version (str) – Version of the application to be added to User Agent.
  • authenticator – DEPRECATED. Only exists for short-term backwards compatibility for python-openstackclient while we transition. See Transition from Profile for details.
  • profile – DEPRECATED. Only exists for short-term backwards compatibility for python-openstackclient while we transition. See Transition from Profile for details.
  • extra_services – List of ServiceDescription objects describing services that openstacksdk otherwise does not know about.
  • kwargs – If a config is not provided, the rest of the parameters provided are assumed to be arguments to be passed to the CloudRegion contructor.
alarm

BaseProxy for alarm aka aodh

application_catalog

BaseProxy for application-catalog aka murano

application_container

BaseProxy for application-container aka zun

backup

BaseProxy for backup aka freezer-api

baremetal

baremetal Proxy for baremetal aka ironic

baremetal_introspection

BaseProxy for baremetal-introspection aka ironic-inspector

block_storage

block-storage Proxy for block-storage aka cinder

clustering

clustering Proxy for clustering aka senlin

compute

compute Proxy for compute aka nova

container_infrastructure_management

BaseProxy for container-infrastructure-management aka magnum

data_processing

BaseProxy for data-processing aka sahara

data_protection_orchestration

BaseProxy for data-protection-orchestration aka karbor

database

database Proxy for database aka trove

dns

BaseProxy for dns aka designate

event

BaseProxy for event aka panko

identity

Proxy for identity aka keystone

This proxy object could be an instance of openstack.identity.v3._proxy.Proxy openstack.identity.v2._proxy.Proxy depending on client configuration and which version of the service is found on remotely on the cloud.

image

Proxy for image aka glance

This proxy object could be an instance of openstack.image.v2._proxy.Proxy openstack.image.v1._proxy.Proxy depending on client configuration and which version of the service is found on remotely on the cloud.

key_manager

key-manager Proxy for key-manager aka barbican

load_balancer

load-balancer Proxy for load-balancer aka octavia

message

message Proxy for message aka zaqar

meter

BaseProxy for meter aka ceilometer

monitoring

BaseProxy for monitoring aka monasca-api

monitoring_events

BaseProxy for monitoring-events aka monasca-events-api

monitoring_logging

BaseProxy for monitoring-logging aka monasca-log-api

multi_region_network_automation

BaseProxy for multi-region-network-automation aka tricircle

network

network Proxy for network aka neutron

nfv_orchestration

BaseProxy for nfv-orchestration aka tacker

object_store

object-store Proxy for object-store aka swift

operator_policy

BaseProxy for operator-policy aka congress

orchestration

orchestration Proxy for orchestration aka heat

placement

BaseProxy for placement aka nova

rating

BaseProxy for rating aka cloudkitty

resource_optimization

BaseProxy for resource-optimization aka watcher

root_cause_analysis

BaseProxy for root-cause-analysis aka vitrage

search

BaseProxy for search aka searchlight

shared_file_system

BaseProxy for shared-file-system aka manila

workflow

workflow Proxy for workflow aka mistral

add_service(service)

Add a service to the Connection.

Attaches an instance of the BaseProxy class contained in ServiceDescription. The BaseProxy will be attached to the Connection by its service_type and by any aliases that may be specified.

Parameters:service (openstack.service_description.ServiceDescription) – Object describing the service to be attached. As a convenience, if service is a string it will be treated as a service_type and a basic ServiceDescription will be created.
authorize()

Authorize this Connection

Note

This method is optional. When an application makes a call to any OpenStack service, this method allows you to request a token manually before attempting to do anything else.

Returns:A string token.
Raises:HttpException if the authorization fails due to reasons like the credentials provided are unable to be authorized or the auth_type argument is missing, etc.

Transitioning from Profile

Support exists for users coming from older releases of OpenStack SDK who have been using the Profile interface.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.