charmhelpers.contrib.openstack package

charmhelpers.contrib.openstack.alternatives module

Helper for managing alternatives for file conflict resolution

charmhelpers.contrib.openstack.alternatives.install_alternative(name, target, source, priority=50)

Install alternative configuration

charmhelpers.contrib.openstack.alternatives.remove_alternative(name, source)

Remove an installed alternative configuration file

Parameters:
  • name – string name of the alternative to remove
  • source – string full path to alternative to remove

charmhelpers.contrib.openstack.context module

class charmhelpers.contrib.openstack.context.AMQPContext(ssl_dir=None, rel_name='amqp', relation_prefix=None, relation_id=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.ApacheSSLContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Generates a context for an apache vhost configuration that configures HTTPS reverse proxying for one or many endpoints. Generated context looks something like:

{
    'namespace': 'cinder',
    'private_address': 'iscsi.mycinderhost.com',
    'endpoints': [(8776, 8766), (8777, 8767)]
}

The endpoints list consists of a tuples mapping external ports to internal ports.

canonical_names()

Figure out which canonical names clients will access this service.

configure_ca()
configure_cert(cn=None)
enable_modules()
external_ports = []
get_network_addresses()
For each network configured, return corresponding address and
hostnamr or vip (if available).

Returns a list of tuples of the form:

[(address_in_net_a, hostname_in_net_a),
(address_in_net_b, hostname_in_net_b), …]

or, if no hostnames(s) available:

[(address_in_net_a, vip_in_net_a),
(address_in_net_b, vip_in_net_b), …]

or, if no vip(s) available:

[(address_in_net_a, address_in_net_a),
(address_in_net_b, address_in_net_b), …]
group = 'root'
interfaces = ['https']
service_namespace = None
user = 'root'
class charmhelpers.contrib.openstack.context.AppArmorContext(profile_name=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Base class for apparmor contexts.

ctxt
install_aa_utils()

Install packages required for apparmor configuration.

manually_disable_aa_profile()

Manually disable an apparmor profile.

If aa-profile-mode is set to disabled (default) this is required as the template has been written but apparmor is yet unaware of the profile and aa-disable aa-profile fails. Without this the profile would kick into enforce mode on the next service restart.

setup_aa_profile()

Setup an apparmor profile. The ctxt dictionary will contain the apparmor profile mode and the apparmor profile name. Makes calls out to aa-disable, aa-complain, or aa-enforce to setup the apparmor profile.

class charmhelpers.contrib.openstack.context.BindHostContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.CephContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Generates context for /etc/ceph/ceph.conf templates.

context_complete(ctxt)

Overridden here to ensure the context is actually complete.

We set key and auth to None here, by default, to ensure that the context will always evaluate to incomplete until the Ceph relation has actually sent these details; otherwise, there is a potential race condition between the relation appearing and the first unit actually setting this data on the relation.

Parameters:ctxt (Dict[str, ANY]) – The current context members
Returns:True if the context is complete
Return type:bool
interfaces = ['ceph']
class charmhelpers.contrib.openstack.context.DHCPAgentContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

static get_existing_ovs_use_veth()

Return existing ovs_use_veth setting from dhcp_agent.ini.

Returns:Boolean value of existing ovs_use_veth setting or None
Return type:Optional[Bool]
get_ovs_use_veth()

Return correct ovs_use_veth setting for use in dhcp_agent.ini.

Get the right value from config or existing dhcp_agent.ini file. Existing has precedence. Attempt to default to “False” without disrupting existing deployments. Handle existing deployments and upgrades safely. See LP Bug#1831935

Returns:Value to use for ovs_use_veth setting
Return type:Bool
static parse_ovs_use_veth()

Parse the ovs-use-veth config setting.

Parse the string config setting for ovs-use-veth and return a boolean or None.

bool_from_string will raise a ValueError if the string is not falsy or truthy.

Raises:ValueError for invalid input
Returns:Boolean value of ovs-use-veth or None
Return type:Optional[Bool]
class charmhelpers.contrib.openstack.context.DataPortContext

Bases: charmhelpers.contrib.openstack.context.NeutronPortContext

class charmhelpers.contrib.openstack.context.EnsureDirContext(dirname, **kwargs)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Serves as a generic context to create a directory as a side-effect.

Useful for software that supports drop-in files (.d) in conjunction with config option-based templates. Examples include:

  • OpenStack oslo.policy drop-in files;
  • systemd drop-in config files;
  • other software that supports overriding defaults with .d files

Another use-case is when a subordinate generates a configuration for primary to render in a separate directory.

Some software requires a user to create a target directory to be scanned for drop-in files with a specific format. This is why this context is needed to do that before rendering a template.

class charmhelpers.contrib.openstack.context.ExternalPortContext

Bases: charmhelpers.contrib.openstack.context.NeutronPortContext

class charmhelpers.contrib.openstack.context.HAProxyContext(singlenode_mode=False, address_types=['admin', 'internal', 'public'])

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Provides half a context for the haproxy template, which describes all peers to be included in the cluster. Each charm needs to include its own context generator that describes the port mapping.

Side effect:mkdir is called on HAPROXY_RUN_DIR
interfaces = ['cluster']
class charmhelpers.contrib.openstack.context.HostInfoContext(use_fqdn_hint_cb=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Context to provide host information.

class charmhelpers.contrib.openstack.context.IdentityCredentialsContext(service=None, service_user=None, rel_name='identity-credentials')

Bases: charmhelpers.contrib.openstack.context.IdentityServiceContext

Context for identity-credentials interface type

class charmhelpers.contrib.openstack.context.IdentityServiceContext(service=None, service_user=None, rel_name='identity-service')

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.ImageServiceContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

interfaces = ['image-service']
class charmhelpers.contrib.openstack.context.InternalEndpointContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Internal endpoint context.

This context provides the endpoint type used for communication between services e.g. between Nova and Cinder internally. Openstack uses Public endpoints by default so this allows admins to optionally use internal endpoints.

class charmhelpers.contrib.openstack.context.LibvirtConfigFlagsContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

This context provides support for extending the libvirt section through user-defined flags.

class charmhelpers.contrib.openstack.context.LogLevelContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.LogrotateContext(location, interval, count)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Common context generator for logrotate.

class charmhelpers.contrib.openstack.context.MemcacheContext(package=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Memcache context

This context provides options for configuring a local memcache client and server for both IPv4 and IPv6

class charmhelpers.contrib.openstack.context.NetworkServiceContext(rel_name='quantum-network-service')

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.NeutronAPIContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Inspects current neutron-plugin-api relation for neutron settings. Return defaults if it is not present.

get_neutron_options(rdata)
interfaces = ['neutron-plugin-api']
class charmhelpers.contrib.openstack.context.NeutronContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

calico_ctxt()
interfaces = []
midonet_ctxt()
n1kv_ctxt()
network_manager
neutron_ctxt()
neutron_security_groups
nuage_ctxt()
nvp_ctxt()
ovs_ctxt()
packages
pg_ctxt()
plugin
class charmhelpers.contrib.openstack.context.NeutronPortContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

resolve_ports(ports)

Resolve NICs not yet bound to bridge(s)

If hwaddress provided then returns resolved hwaddress otherwise NIC.

class charmhelpers.contrib.openstack.context.NotificationDriverContext(zmq_relation='zeromq-configuration', amqp_relation='amqp')

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.NovaVendorMetadataContext(os_release_pkg, interfaces=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Context used for configuring nova vendor metadata on nova.conf file.

class charmhelpers.contrib.openstack.context.NovaVendorMetadataJSONContext(os_release_pkg)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Context used for writing nova vendor metadata json file.

class charmhelpers.contrib.openstack.context.OSConfigFlagContext(charm_flag='config-flags', template_flag='user_config_flags')

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Provides support for user-defined config flags.

Users can define a comma-seperated list of key=value pairs in the charm configuration and apply them at any point in any file by using a template flag.

Sometimes users might want config flags inserted within a specific section so this class allows users to specify the template flag name, allowing for multiple template flags (sections) within the same context.

NOTE: the value of config-flags may be a comma-separated list of
key=value pairs and some Openstack config files support comma-separated lists as values.
class charmhelpers.contrib.openstack.context.OSContextGenerator

Bases: object

Base class for all context generators.

complete = False
context_complete(ctxt)

Check for missing data for the required context data. Set self.missing_data if it exists and return False. Set self.complete if no missing data and return True.

Check if any of the context interfaces have relation ids. Set self.related and return True if one of the interfaces has relation ids.

interfaces = []
missing_data = []
related = False
class charmhelpers.contrib.openstack.context.PhyNICMTUContext

Bases: charmhelpers.contrib.openstack.context.DataPortContext

class charmhelpers.contrib.openstack.context.PostgresqlDBContext(database=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

interfaces = ['pgsql-db']
class charmhelpers.contrib.openstack.context.SharedDBContext(database=None, user=None, relation_prefix=None, ssl_dir=None, relation_id=None)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

interfaces = ['shared-db']
class charmhelpers.contrib.openstack.context.SubordinateConfigContext(service, config_file, interface)

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Responsible for inspecting relations to subordinates that may be exporting required config via a json blob.

The subordinate interface allows subordinates to export their configuration requirements to the principle for multiple config files and multiple services. Ie, a subordinate that has interfaces to both glance and nova may export to following yaml blob as json:

glance:
    /etc/glance/glance-api.conf:
        sections:
            DEFAULT:
                - [key1, value1]
    /etc/glance/glance-registry.conf:
            MYSECTION:
                - [key2, value2]
nova:
    /etc/nova/nova.conf:
        sections:
            DEFAULT:
                - [key3, value3]

It is then up to the principle charms to subscribe this context to the service+config file it is interestd in. Configuration data will be available in the template context, in glance’s case, as:

ctxt = {
    ... other context ...
    'subordinate_configuration': {
        'DEFAULT': {
            'key1': 'value1',
        },
        'MYSECTION': {
            'key2': 'value2',
        },
    }
}
class charmhelpers.contrib.openstack.context.SysctlContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

This context check if the ‘sysctl’ option exists on configuration then creates a file with the loaded contents

class charmhelpers.contrib.openstack.context.SyslogContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.VersionsContext(pkg='python-keystone')

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

Context to return the openstack and operating system versions.

class charmhelpers.contrib.openstack.context.VolumeAPIContext(pkg)

Bases: charmhelpers.contrib.openstack.context.InternalEndpointContext

Volume API context.

This context provides information regarding the volume endpoint to use when communicating between services. It determines which version of the API is appropriate for use.

This value will be determined in the resulting context dictionary returned from calling the VolumeAPIContext object. Information provided by this context is as follows:

volume_api_version: the volume api version to use, currently
‘v2’ or ‘v3’
volume_catalog_info: the information to use for a cinder client
configuration that consumes API endpoints from the keystone catalog. This is defined as the type:name:endpoint_type string.
ctxt
class charmhelpers.contrib.openstack.context.WSGIWorkerConfigContext(name=None, script=None, admin_script=None, public_script=None, user=None, group=None, process_weight=1.0, admin_process_weight=0.25, public_process_weight=0.75)

Bases: charmhelpers.contrib.openstack.context.WorkerConfigContext

class charmhelpers.contrib.openstack.context.WorkerConfigContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

class charmhelpers.contrib.openstack.context.ZeroMQContext

Bases: charmhelpers.contrib.openstack.context.OSContextGenerator

interfaces = ['zeromq-configuration']
charmhelpers.contrib.openstack.context.context_complete(ctxt)
charmhelpers.contrib.openstack.context.db_ssl(rdata, ctxt, ssl_dir)
charmhelpers.contrib.openstack.context.ensure_packages(packages)

Install but do not upgrade required plugin packages.

charmhelpers.contrib.openstack.context.get_ipv4_addr(iface='eth0', *, inet_type='AF_INET', inc_aliases=False, fatal=True, exc_list=None)

Return the assigned IP address for a given interface, if any.

Parameters:
  • iface – network interface on which address(es) are expected to be found.
  • inet_type – inet address family
  • inc_aliases – include alias interfaces in search
  • fatal – if True, raise exception if address not found
  • exc_list – list of addresses to ignore
Returns:

list of ip addresses

charmhelpers.contrib.openstack.context.get_netmask_for_address(address, *, key='netmask')

Retrieve an attribute of or the physical interface that the IP address provided could be bound to.

Parameters:
  • (str) (address) – An individual IPv4 or IPv6 address without a net mask or subnet prefix. For example, ‘192.168.1.1’.
  • key – ‘iface’ for the physical interface name or an attribute of the configured interface, for example ‘netmask’.
Returns str:

Requested attribute or None if address is not bindable.

charmhelpers.contrib.openstack.context.validate_ovs_use_veth(*args, **kwargs)

Validate OVS use veth setting for dhcp agents

The ovs_use_veth setting is considered immutable as it will break existing deployments. Historically, we set ovs_use_veth=True in dhcp_agent.ini. It turns out this is no longer necessary. Ideally, all new deployments would have this set to False.

This function validates that the config value does not conflict with previously deployed settings in dhcp_agent.ini.

See LP Bug#1831935 for details.

Returns:Status state and message
Return type:Union[(None, None), (string, string)]

charmhelpers.contrib.openstack.neutron module

charmhelpers.contrib.openstack.neutron.determine_dkms_package()

Determine which DKMS package should be used based on kernel version

charmhelpers.contrib.openstack.neutron.headers_package()

Ensures correct linux-headers for running kernel are installed, for building DKMS package

charmhelpers.contrib.openstack.neutron.kernel_version()

Retrieve the current major kernel version as a tuple e.g. (3, 13)

charmhelpers.contrib.openstack.neutron.network_manager()

Deals with the renaming of Quantum to Neutron in H and any situations that require compatability (eg, deploying H with network-manager=quantum, upgrading from G).

charmhelpers.contrib.openstack.neutron.neutron_plugin_attribute(plugin, attr, net_manager=None)
charmhelpers.contrib.openstack.neutron.neutron_plugins()
charmhelpers.contrib.openstack.neutron.parse_bridge_mappings(mappings)

Parse bridge mappings.

Mappings must be a space-delimited list of provider:bridge mappings.

Returns dict of the form {provider:bridge}.

charmhelpers.contrib.openstack.neutron.parse_data_port_mappings(mappings, default_bridge='br-data')

Parse data port mappings.

Mappings must be a space-delimited list of bridge:port.

Returns dict of the form {port:bridge} where ports may be mac addresses or interface names.

charmhelpers.contrib.openstack.neutron.parse_mappings(mappings, key_rvalue=False)

By default mappings are lvalue keyed.

If key_rvalue is True, the mapping will be reversed to allow multiple configs for the same lvalue.

charmhelpers.contrib.openstack.neutron.parse_vlan_range_mappings(mappings)

Parse vlan range mappings.

Mappings must be a space-delimited list of provider:start:end mappings.

The start:end range is optional and may be omitted.

Returns dict of the form {provider: (start, end)}.

charmhelpers.contrib.openstack.neutron.quantum_plugins()

charmhelpers.contrib.openstack.templating module

exception charmhelpers.contrib.openstack.templating.OSConfigException

Bases: Exception

class charmhelpers.contrib.openstack.templating.OSConfigRenderer(templates_dir, openstack_release)

Bases: object

This class provides a common templating system to be used by OpenStack charms. It is intended to help charms share common code and templates, and ease the burden of managing config templates across multiple OpenStack releases.

Basic usage:

# import some common context generates from charmhelpers
from charmhelpers.contrib.openstack import context

# Create a renderer object for a specific OS release.
configs = OSConfigRenderer(templates_dir='/tmp/templates',
                           openstack_release='folsom')
# register some config files with context generators.
configs.register(config_file='/etc/nova/nova.conf',
                 contexts=[context.SharedDBContext(),
                           context.AMQPContext()])
configs.register(config_file='/etc/nova/api-paste.ini',
                 contexts=[context.IdentityServiceContext()])
configs.register(config_file='/etc/haproxy/haproxy.conf',
                 contexts=[context.HAProxyContext()])
configs.register(config_file='/etc/keystone/policy.d/extra.cfg',
                 contexts=[context.ExtraPolicyContext()
                           context.KeystoneContext()],
                 config_template=hookenv.config('extra-policy'))
# write out a single config
configs.write('/etc/nova/nova.conf')
# write out all registered configs
configs.write_all()

OpenStack Releases and template loading

When the object is instantiated, it is associated with a specific OS release. This dictates how the template loader will be constructed.

The constructed loader attempts to load the template from several places in the following order: - from the most recent OS release-specific template dir (if one exists) - the base templates_dir - a template directory shipped in the charm with this helper file.

For the example above, ‘/tmp/templates’ contains the following structure:

/tmp/templates/nova.conf
/tmp/templates/api-paste.ini
/tmp/templates/grizzly/api-paste.ini
/tmp/templates/havana/api-paste.ini

Since it was registered with the grizzly release, it first searches the grizzly directory for nova.conf, then the templates dir.

When writing api-paste.ini, it will find the template in the grizzly directory.

If the object were created with folsom, it would fall back to the base templates dir for its api-paste.ini template.

This system should help manage changes in config files through openstack releases, allowing charms to fall back to the most recently updated config template for a given release

The haproxy.conf, since it is not shipped in the templates dir, will be loaded from the module directory’s template directory, eg $CHARM/hooks/charmhelpers/contrib/openstack/templates. This allows us to ship common templates (haproxy, apache) with the helpers.

Context generators

Context generators are used to generate template contexts during hook execution. Doing so may require inspecting service relations, charm config, etc. When registered, a config file is associated with a list of generators. When a template is rendered and written, all context generates are called in a chain to generate the context dictionary passed to the jinja2 template. See context.py for more info.

complete_contexts()

Returns a list of context interfaces that yield a complete context.

get_incomplete_context_data(interfaces)

Return dictionary of relation status of interfaces and any missing required context data. Example:

{‘amqp’: {‘missing_data’: [‘rabbitmq_password’], ‘related’: True},
‘zeromq-configuration’: {‘related’: False}}
register(config_file, contexts, config_template=None)

Register a config file with a list of context generators to be called during rendering. config_template can be used to load a template from a string instead of using template loaders and template files. :param config_file (str): a path where a config file will be rendered :param contexts (list): a list of context dictionaries with kv pairs :param config_template (str): an optional template string to use

render(config_file)
set_release(openstack_release)

Resets the template environment and generates a new template loader based on a the new openstack release.

write(config_file)

Write a single config file, raises if config file is not registered.

write_all()

Write out all registered config files.

class charmhelpers.contrib.openstack.templating.OSConfigTemplate(config_file, contexts, config_template=None)

Bases: object

Associates a config file template with a list of context generators. Responsible for constructing a template context based on those generators.

complete_contexts()

Return a list of interfaces that have satisfied contexts.

context()
is_string_template
Returns:Boolean if this instance is a template initialised with a string
charmhelpers.contrib.openstack.templating.get_loader(templates_dir, os_release)

Create a jinja2.ChoiceLoader containing template dirs up to and including os_release. If directory template directory is missing at templates_dir, it will be omitted from the loader. templates_dir is added to the bottom of the search list as a base loading dir.

A charm may also ship a templates dir with this module and it will be appended to the bottom of the search list, eg:

hooks/charmhelpers/contrib/openstack/templates
Parameters:
  • (str) (os_release) – Base template directory containing release sub-directories.
  • (str) – OpenStack release codename to construct template loader.
Returns:

jinja2.ChoiceLoader constructed with a list of jinja2.FilesystemLoaders, ordered in descending order by OpenStack release.

charmhelpers.contrib.openstack.utils module

class charmhelpers.contrib.openstack.utils.CompareOpenStackReleases(item)

Bases: charmhelpers.core.strutils.BasicStringComparator

Provide comparisons of OpenStack releases.

Use in the form of

if CompareOpenStackReleases(release) > ‘mitaka’:
# do something with mitaka
charmhelpers.contrib.openstack.utils.check_actually_paused(services=None, ports=None)

Check that services listed in the services object and ports are actually closed (not listened to), to verify that the unit is properly paused.

@param services: See _extract_services_list_helper @returns status, : string for status (None if okay)

message : string for problem for status_set
charmhelpers.contrib.openstack.utils.clean_storage(block_device)
Ensures a block device is clean. That is:
  • unmounted
  • any lvm volume groups are deactivated
  • any lvm physical device signatures removed
  • partition table wiped
Parameters:block_device – str: Full path to block device to clean.
charmhelpers.contrib.openstack.utils.clear_unit_paused()

Clear the unit from a paused state in the local kv() store This does NOT actually restart any services - it only clears the local state.

charmhelpers.contrib.openstack.utils.clear_unit_upgrading()

Clear the unit from a upgrading state in the local kv() store

charmhelpers.contrib.openstack.utils.config_flags_parser(config_flags)

Parses config flags string into dict.

This parsing method supports a few different formats for the config flag values to be parsed:

  1. A string in the simple format of key=value pairs, with the possibility of specifying multiple key value pairs within the same string. For example, a string in the format of ‘key1=value1, key2=value2’ will return a dict of:

    {‘key1’: ‘value1’, ‘key2’: ‘value2’}.

  2. A string in the above format, but supporting a comma-delimited list of values for the same key. For example, a string in the format of ‘key1=value1, key2=value3,value4,value5’ will return a dict of:

    {‘key1’: ‘value1’, ‘key2’: ‘value2,value3,value4’}

  3. A string containing a colon character (:) prior to an equal character (=) will be treated as yaml and parsed as such. This can be used to specify more complex key value pairs. For example, a string in the format of ‘key1: subkey1=value1, subkey2=value2’ will return a dict of:

    {‘key1’, ‘subkey1=value1, subkey2=value2’}

The provided config_flags string may be a list of comma-separated values which themselves may be comma-separated list of values.

charmhelpers.contrib.openstack.utils.config_value_changed(option)

Determine if config value changed since last call to this function.

charmhelpers.contrib.openstack.utils.configure_installation_source(source_plus_key)

Configure an installation source.

The functionality is provided by charmhelpers.fetch.add_source() The difference between the two functions is that add_source() signature requires the key to be passed directly, whereas this function passes an optional key by appending ‘|<key>’ to the end of the source specificiation ‘source’.

Another difference from add_source() is that the function calls sys.exit(1) if the configuration fails, whereas add_source() raises SourceConfigurationError(). Another difference, is that add_source() silently fails (with a juju_log command) if there is no matching source to configure, whereas this function fails with a sys.exit(1)

Parameters:source – String_plus_key – see above for details.

Note that the behaviour on error is to log the error to the juju log and then call sys.exit(1).

charmhelpers.contrib.openstack.utils.do_action_openstack_upgrade(package, upgrade_callback, configs)

Perform action-managed OpenStack upgrade.

Upgrades packages to the configured openstack-origin version and sets the corresponding action status as a result.

If the charm was installed from source we cannot upgrade it. For backwards compatibility a config flag (action-managed-upgrade) must be set for this code to run, otherwise a full service level upgrade will fire on config-changed.

@param package: package name for determining if upgrade available @param upgrade_callback: function callback to charm’s upgrade function @param configs: templating object derived from OSConfigRenderer class

@return: True if upgrade successful; False if upgrade failed or skipped

charmhelpers.contrib.openstack.utils.enable_memcache(source=None, release=None, package=None)

Determine if memcache should be enabled on the local unit

@param release: release of OpenStack currently deployed @param package: package to derive OpenStack version deployed @returns boolean Whether memcache should be enabled

charmhelpers.contrib.openstack.utils.endpoint_changed(service_name, rel_name='identity-service')

Whether a new notification has been recieved for an endpoint.

Parameters:
  • service_name (str) – Service name eg nova, neutron, placement etc
  • rel_name (str) – Name of the relation to query
Returns:

Whether endpoint has changed

Return type:

bool

charmhelpers.contrib.openstack.utils.ensure_block_device(block_device)

Confirm block_device, create as loopback if necessary.

Parameters:block_device – str: Full path of block device to ensure.
Returns:str: Full path of ensured block device.
charmhelpers.contrib.openstack.utils.error_out(msg)
charmhelpers.contrib.openstack.utils.get_endpoint_key(service_name, relation_id, unit_name)

Return the key used to refer to an ep changed notification from a unit.

Parameters:
  • service_name (str) – Service name eg nova, neutron, placement etc
  • relation_id (str) – The id of the relation the unit is on.
  • unit_name (str) – The name of the unit publishing the notification.
Returns:

The key used to refer to an ep changed notification from a unit

Return type:

str

charmhelpers.contrib.openstack.utils.get_endpoint_notifications(service_names, rel_name='identity-service')

Return all notifications for the given services.

Parameters:
  • service_names – List of service name.
  • rel_name (str) – Name of the relation to query
Returns:

A dict containing the source of the notification and its nonce.

Return type:

Dict[str, str]

charmhelpers.contrib.openstack.utils.get_installed_semantic_versioned_packages()

Get a list of installed packages which have OpenStack semantic versioning

:returns List of installed packages :rtype: [pkg1, pkg2, …]

charmhelpers.contrib.openstack.utils.get_matchmaker_map(mm_file='/etc/oslo/matchmaker_ring.json')
charmhelpers.contrib.openstack.utils.get_os_codename_install_source(src)

Derive OpenStack release codename from a given installation source.

charmhelpers.contrib.openstack.utils.get_os_codename_package(package, fatal=True)

Derive OpenStack release codename from an installed package.

charmhelpers.contrib.openstack.utils.get_os_codename_version(vers)

Determine OpenStack codename from version number.

charmhelpers.contrib.openstack.utils.get_os_version_codename(codename, version_map={'2011.2': 'diablo', '2012.1': 'essex', '2012.2': 'folsom', '2013.1': 'grizzly', '2013.2': 'havana', '2014.1': 'icehouse', '2014.2': 'juno', '2015.1': 'kilo', '2015.2': 'liberty', '2016.1': 'mitaka', '2016.2': 'newton', '2017.1': 'ocata', '2017.2': 'pike', '2018.1': 'queens', '2018.2': 'rocky', '2019.1': 'stein', '2019.2': 'train', '2020.1': 'ussuri'})

Determine OpenStack version number from codename.

charmhelpers.contrib.openstack.utils.get_os_version_codename_swift(codename)

Determine OpenStack version number of swift from codename.

charmhelpers.contrib.openstack.utils.get_os_version_install_source(src)
charmhelpers.contrib.openstack.utils.get_os_version_package(pkg, fatal=True)

Derive OpenStack version number from an installed package.

charmhelpers.contrib.openstack.utils.get_snaps_install_info_from_origin(snaps, src, mode='classic')

Generate a dictionary of snap install information from origin

@param snaps: List of snaps @param src: String of openstack-origin or source of the form

snap:track/channel

@param mode: String classic, devmode or jailmode @returns: Dictionary of snaps with channels and modes

charmhelpers.contrib.openstack.utils.get_source_and_pgp_key(source_and_key)

Look for a pgp key ID or ascii-armor key in the given input.

Parameters:source_and_key – Sting, “source_spec|keyid” where ‘|keyid’ is optional.
:returns (source_spec, key_id OR None) as a tuple. Returns None for key_id
if there was no ‘|’ in the source_and_key string.
charmhelpers.contrib.openstack.utils.get_swift_codename(version)

Determine OpenStack codename that corresponds to swift version.

charmhelpers.contrib.openstack.utils.import_key(keyid)

Import a key, either ASCII armored, or a GPG key id.

@param keyid: the key in ASCII armor format, or a GPG key id. @raises SystemExit() via sys.exit() on failure.

charmhelpers.contrib.openstack.utils.incomplete_relation_data(configs, required_interfaces)

Check complete contexts against required_interfaces Return dictionary of incomplete relation data.

configs is an OSConfigRenderer object with configs registered

required_interfaces is a dictionary of required general interfaces with dictionary values of possible specific interfaces. Example: required_interfaces = {‘database’: [‘shared-db’, ‘pgsql-db’]}

The interface is said to be satisfied if anyone of the interfaces in the list has a complete context.

Return dictionary of incomplete or missing required contexts with relation status of interfaces and any missing data points. Example:

{‘message’:
{‘amqp’: {‘missing_data’: [‘rabbitmq_password’], ‘related’: True},
‘zeromq-configuration’: {‘related’: False}},
‘identity’:
{‘identity-service’: {‘related’: False}},
‘database’:
{‘pgsql-db’: {‘related’: False},
‘shared-db’: {‘related’: True}}}
charmhelpers.contrib.openstack.utils.install_os_snaps(snaps, refresh=False)

Install OpenStack snaps from channel and with mode

@param snaps: Dictionary of snaps with channels and modes of the form:
{‘snap_name’: {‘channel’: ‘snap_channel’,
‘mode’: ‘snap_mode’}}

Where channel is a snapstore channel and mode is –classic, –devmode or –jailmode.

@param post_snap_install: Callback function to run after snaps have been installed

charmhelpers.contrib.openstack.utils.is_db_initialised()

Check leader storage to see if database has been initialised.

Returns:Whether DB has been initialised
Return type:bool
charmhelpers.contrib.openstack.utils.is_db_maintenance_mode(relid=None)

Check relation data from notifications of db in maintenance mode.

Returns:Whether db has notified it is in maintenance mode.
Return type:bool
charmhelpers.contrib.openstack.utils.is_unit_paused_set()

Return the state of the kv().get(‘unit-paused’). This does NOT verify that the unit really is paused.

To help with units that don’t have HookData() (testing) if it excepts, return False

charmhelpers.contrib.openstack.utils.is_unit_upgrading_set()

Return the state of the kv().get(‘unit-upgrading’).

To help with units that don’t have HookData() (testing) if it excepts, return False

charmhelpers.contrib.openstack.utils.make_assess_status_func(*args, **kwargs)

Creates an assess_status_func() suitable for handing to pause_unit() and resume_unit().

This uses the _determine_os_workload_status(…) function to determine what the workload_status should be for the unit. If the unit is not in maintenance or active states, then the message is returned to the caller. This is so an action that doesn’t result in either a complete pause or complete resume can signal failure with an action_fail()

charmhelpers.contrib.openstack.utils.manage_payload_services(action, services=None, charm_func=None)

Run an action against all services.

An optional charm_func() can be called. It should raise an Exception to indicate that the function failed. If it was succesfull it should return None or an optional message.

The signature for charm_func is: charm_func() -> message: str

charm_func() is executed after any services are stopped, if supplied.

The services object can either be:
  • None : no services were passed (an empty dict is returned)
  • a list of strings
  • A dictionary (optionally OrderedDict) {service_name: {‘service’: ..}}
  • An array of [{‘service’: service_name, …}, …]
Parameters:
  • action (str) – Action to run: pause, resume, start or stop.
  • services (See above) – See above
  • charm_func (f()) – function to run for custom charm pausing.
Returns:

Status boolean and list of messages

Return type:

(bool, [])

Raises:

RuntimeError

charmhelpers.contrib.openstack.utils.openstack_upgrade_available(package)

Determines if an OpenStack upgrade is available from installation source, based on version of installed package.

Parameters:package – str: Name of installed package.
Returns:bool: : Returns True if configured installation source offers a newer version of package.
charmhelpers.contrib.openstack.utils.ordered(orderme)

Converts the provided dictionary into a collections.OrderedDict.

The items in the returned OrderedDict will be inserted based on the natural sort order of the keys. Nested dictionaries will also be sorted in order to ensure fully predictable ordering.

Parameters:orderme – the dict to order
Returns:collections.OrderedDict
Raises:ValueError: if orderme isn’t a dict instance.
charmhelpers.contrib.openstack.utils.os_application_version_set(package)

Set version of application for Juju 2.0 and later

charmhelpers.contrib.openstack.utils.os_release(package, base=None, reset_cache=False, source_key=None)

Returns OpenStack release codename from a cached global.

If reset_cache then unset the cached os_release version and return the freshly determined version.

If the codename can not be determined from either an installed package or the installation source, the earliest release supported by the charm should be returned.

Parameters:
  • package (str) – Name of package to determine release from
  • base (Optional[str]) – Fallback codename if endavours to determine from package fail
  • reset_cache (bool) – Reset any cached codename value
  • source_key (Optional[str]) – Name of source configuration option (default: ‘openstack-origin’)
Returns:

OpenStack release codename

Return type:

str

charmhelpers.contrib.openstack.utils.os_requires_version(ostack_release, pkg)

Decorator for hook to specify minimum supported release

charmhelpers.contrib.openstack.utils.os_workload_status(configs, required_interfaces, charm_func=None)

Decorator to set workload status based on complete contexts

charmhelpers.contrib.openstack.utils.pausable_restart_on_change(restart_map, stopstart=False, restart_functions=None)

A restart_on_change decorator that checks to see if the unit is paused. If it is paused then the decorated function doesn’t fire.

This is provided as a helper, as the @restart_on_change(…) decorator is in core.host, yet the openstack specific helpers are in this file (contrib.openstack.utils). Thus, this needs to be an optional feature for openstack charms (or charms that wish to use the openstack pause/resume type features).

It is used as follows:

from contrib.openstack.utils import (
pausable_restart_on_change as restart_on_change)

@restart_on_change(restart_map, stopstart=<boolean>) def some_hook(…):

pass

see core.utils.restart_on_change() for more details.

Note restart_map can be a callable, in which case, restart_map is only evaluated at runtime. This means that it is lazy and the underlying function won’t be called if the decorated function is never called. Note, retains backwards compatibility for passing a non-callable dictionary.

@param f: the function to decorate @param restart_map: (optionally callable, which then returns the

restart_map) the restart map {conf_file: [services]}

@param stopstart: DEFAULT false; whether to stop, start or just restart @returns decorator to use a restart_on_change with pausability

charmhelpers.contrib.openstack.utils.pause_unit(assess_status_func, services=None, ports=None, charm_func=None)

Pause a unit by stopping the services and setting ‘unit-paused’ in the local kv() store.

Also checks that the services have stopped and ports are no longer being listened to.

An optional charm_func() can be called that can either raise an Exception or return non None, None to indicate that the unit didn’t pause cleanly.

The signature for charm_func is: charm_func() -> message: string

charm_func() is executed after any services are stopped, if supplied.

The services object can either be:
  • None : no services were passed (an empty dict is returned)
  • a list of strings
  • A dictionary (optionally OrderedDict) {service_name: {‘service’: ..}}
  • An array of [{‘service’: service_name, …}, …]

@param assess_status_func: (f() -> message: string | None) or None @param services: OPTIONAL see above @param ports: OPTIONAL list of port @param charm_func: function to run for custom charm pausing. @returns None @raises Exception(message) on an error for action_fail().

charmhelpers.contrib.openstack.utils.remote_restart(rel_name, remote_service=None)
charmhelpers.contrib.openstack.utils.reset_os_release()

Unset the cached os_release version

charmhelpers.contrib.openstack.utils.resume_unit(assess_status_func, services=None, ports=None, charm_func=None)

Resume a unit by starting the services and clearning ‘unit-paused’ in the local kv() store.

Also checks that the services have started and ports are being listened to.

An optional charm_func() can be called that can either raise an Exception or return non None to indicate that the unit didn’t resume cleanly.

The signature for charm_func is: charm_func() -> message: string

charm_func() is executed after any services are started, if supplied.

The services object can either be:
  • None : no services were passed (an empty dict is returned)
  • a list of strings
  • A dictionary (optionally OrderedDict) {service_name: {‘service’: ..}}
  • An array of [{‘service’: service_name, …}, …]

@param assess_status_func: (f() -> message: string | None) or None @param services: OPTIONAL see above @param ports: OPTIONAL list of port @param charm_func: function to run for custom charm resuming. @returns None @raises Exception(message) on an error for action_fail().

charmhelpers.contrib.openstack.utils.save_endpoint_changed_triggers(service_names, rel_name='identity-service')

Save the enpoint triggers in db so it can be tracked if they changed.

Parameters:
  • service_names – List of service name.
  • rel_name (str) – Name of the relation to query
charmhelpers.contrib.openstack.utils.save_script_rc(script_path='scripts/scriptrc', **env_vars)

Write an rc file in the charm-delivered directory containing exported environment variables provided by env_vars. Any charm scripts run outside the juju hook environment can source this scriptrc to obtain updated config information necessary to perform health checks or service changes.

charmhelpers.contrib.openstack.utils.series_upgrade_complete(resume_unit_helper=None, configs=None)

Run common series upgrade complete tasks.

Parameters:
  • resume_unit_helper – function: Function to resume unit
  • configs – OSConfigRenderer object: Configurations
Returns None:
charmhelpers.contrib.openstack.utils.series_upgrade_prepare(pause_unit_helper=None, configs=None)

Run common series upgrade prepare tasks.

Parameters:
  • pause_unit_helper – function: Function to pause unit
  • configs – OSConfigRenderer object: Configurations
Returns None:
charmhelpers.contrib.openstack.utils.set_db_initialised()

Add flag to leader storage to indicate database has been initialised.

charmhelpers.contrib.openstack.utils.set_os_workload_status(configs, required_interfaces, charm_func=None, services=None, ports=None)

Set the state of the workload status for the charm.

This calls _determine_os_workload_status() to get the new state, message and sets the status using status_set()

@param configs: a templating.OSConfigRenderer() object @param required_interfaces: {generic: [specific, specific2, …]} @param charm_func: a callable function that returns state, message. The

signature is charm_func(configs) -> (state, message)

@param services: list of strings OR dictionary specifying services/ports @param ports: OPTIONAL list of port numbers. @returns state, message: the new workload status, user message

charmhelpers.contrib.openstack.utils.set_unit_paused()

Set the unit to a paused state in the local kv() store. This does NOT actually pause the unit

charmhelpers.contrib.openstack.utils.set_unit_upgrading()

Set the unit to a upgrading state in the local kv() store.

charmhelpers.contrib.openstack.utils.snap_install_requested()

Determine if installing from snaps

If openstack-origin is of the form snap:track/channel[/branch] and channel is in SNAPS_CHANNELS return True.

charmhelpers.contrib.openstack.utils.sync_db_with_multi_ipv6_addresses(database, database_user, relation_prefix=None)
charmhelpers.contrib.openstack.utils.token_cache_pkgs(source=None, release=None)

Determine additional packages needed for token caching

@param source: source string for charm @param release: release of OpenStack currently deployed @returns List of package to enable token caching

charmhelpers.contrib.openstack.utils.update_json_file(filename, items)

Updates the json filename with a given dict. :param filename: path to json file (e.g. /etc/glance/policy.json) :param items: dict of items to update

charmhelpers.contrib.openstack.utils.workload_state_compare(current_workload_state, workload_state)

Return highest priority of two states