Juju Model

Module for interacting with a juju model.

This module contains a number of functions for interacting with a Juju model mostly via libjuju. Async function also provice a non-async alternative via ‘sync_wrapper’.

exception zaza.model.ActionFailed(action, output=None)

Exception raised when action fails.

class zaza.model.CloudData(cloud_name, cloud, credential_name, credential)
property cloud

Alias for field number 1

property cloud_name

Alias for field number 0

property credential

Alias for field number 3

property credential_name

Alias for field number 2

exception zaza.model.CommandRunFailed(cmd, result)

Command failed to run.

exception zaza.model.MachineError(units)

Exception raised for units in error state.

exception zaza.model.ModelTimeout

Model timeout exception.

exception zaza.model.RemoteFileError

Error with a remote file.

exception zaza.model.ServiceNotRunning(service)

Exception raised when service not running.

class zaza.model.StatusResult(time, result)
property result

Alias for field number 1

property time

Alias for field number 0

exception zaza.model.UnitError(units)

Exception raised for units in error state.

exception zaza.model.UnitNotFound(unit_name)

Unit was not found in model.

async zaza.model.async_add_relation(application_name, local_relation, remote_relation, model_name=None)

Add relation between applications.

Parameters
  • application_name (str) – Name of application on this side of relation

  • local_relation (str) – Name of relation on this application

  • remote_relation (str ‘<application>[:<relation_name>]) – Name of relation on the other application.

  • model_name (str) – Name of model to operate on.

async zaza.model.async_add_unit(application_name, count=1, to=None, model_name=None, wait_appear=False)

Add unit(s) to an application.

Parameters
  • application_name (str) – Name of application to add unit(s) to

  • count (int) – Number of units to add

  • to (str) – Location to add unit i.e. lxd:0

  • model_name (str) – Name of model to operate on.

  • wait_appear (bool) – Whether to wait for the unit to appear in juju status

async zaza.model.async_block_until(*conditions, timeout=None, wait_period=0.5, loop=None)

Return only after all async conditions are true.

Based on juju.utils.block_until which currently does not support async methods as conditions.

Parameters
  • conditions (functions) – Functions to evaluate.

  • timeout (float) – Timeout in seconds

  • wait_period (float) – Time to wait between re-assessing conditions.

  • loop (An event loop) – The event loop to use

async zaza.model.async_block_until_all_units_idle(model_name=None, timeout=2700)

Block until all units in the given model are idle.

An example accessing this function via its sync wrapper:

block_until_all_units_idle('modelname')
Parameters
  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for status to be achieved

async zaza.model.async_block_until_charm_url(application, target_url, model_name=None, timeout=2700)

Block until the charm url matches target_url.

An example accessing this function via its sync wrapper:

block_until_charm_url('cinder', 'cs:openstack-charmers-next/cinder')
Parameters
  • application_name (str) – Name of application

  • target_url (str) – Target charm url

  • model_name (str) – Name of model to interact with.

  • timeout (float) – Time to wait for status to be achieved

async zaza.model.async_block_until_file_has_contents(application_name, remote_file, expected_contents, model_name=None, timeout=2700)

Block until the expected_contents are present on all units.

Block until the given string (expected_contents) is present in the file (remote_file) on all units of the given application.

An example accessing this function via its sync wrapper:

block_until_file_has_contents(
    'keystone',
    '/etc/apache2/apache2.conf',
    'KeepAlive On',
    model_name='modelname')
Parameters
  • application_name (str) – Name of application

  • remote_file (str) – Remote path of file to transfer

  • expected_contents (str) – String to look for in file

  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for contents to appear in file

async zaza.model.async_block_until_file_matches_re(application_name, remote_file, pattern, re_flags=RegexFlag.MULTILINE, model_name=None, timeout=2700)

Block until a file matches a pattern.

Block until the provided regular expression pattern matches the given file on all units of the given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

  • remote_file (str) – Remote path of file to match

  • pattern (str or compiled regex) – Regular expression

  • re_flags (re.RegexFlag (int flag constants from the re module)) – Regular expression flags if the pattern is a string

  • timeout (float) – Time to wait for contents to appear in file

async zaza.model.async_block_until_file_missing(app, path, model_name=None, timeout=2700)

Block until the file at path is not there.

Block until the file at the param ‘path’ is not present on the file system for all units on a given application.

An example accessing this function via its sync wrapper:

block_until_file_missing(
    'keystone',
    '/some/path/name')
Parameters
  • app (str) – the application name

  • path (str) – the file name to check for.

  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for contents to appear in file

async zaza.model.async_block_until_file_missing_on_machine(machine, path, model_name=None, timeout=2700)

Block until the file at ‘path’ is not present for a machine.

An example accessing this function via its sync wrapper:

block_until_file_missing_on_machine(
    '0',
    '/some/path/name')
Parameters
  • machine (str) – the machine

  • path (str) – the file name to check for.

  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for until file is missing on a machine.

async zaza.model.async_block_until_file_ready(application_name, remote_file, check_function, model_name=None, timeout=2700)

Block until the check_function passes against.

Block until the check_function passes against the provided file. It is unlikely that a test would call this function directly, rather it is provided as scaffolding for tests with a more specialised purpose.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

  • remote_file (str) – Remote path of file to transfer

  • check_function (function) – Function to use to check if file is ready, must take exactly one argument which is the file contents.

  • timeout (float) – Time to wait for contents to appear in file

async zaza.model.async_block_until_machine_status_is(machine, status, model_name=None, invert_check=False, timeout=600, interval=4.0, refresh=True)

Block until the agent status for a machine (doesn’t) match status.

Block until the agent status of a machine does (or doesn’t with the param invert_status=True) match the passed string (in param status). If the timeout is exceeded then the function raises an Exception.

Parameters
  • machine (str) – the machine to watch, as provided from the get_status()

  • status (str) – the string to match the machine’s agent status to.

  • model_name (str) – Name of model to query.

  • invert_check (boolean) – whether to invert the check (default False)

  • timeout (int) – the time to wait for the status (or inverse of) (default 600 seconds).

  • interval (float) – The minimum time between calls to get_status

  • refresh (boolean) – Force a refresh; do not used cached results

Raises

asyncio.TimeoutError if the timeout is exceeded.

async zaza.model.async_block_until_oslo_config_entries_match(application_name, remote_file, expected_contents, model_name=None, timeout=2700)

Block until dict is represented in the file using oslo.config parser.

Block until the expected_contents are in the given file on all units of the application. For example to check for the following configuration:

[DEFAULT]
debug = False

[glance_store]
filesystem_store_datadir = /var/lib/glance/images/
default_store = file

Call the check via its sync wrapper:

expected_contents = {
    'DEFAULT': {
        'debug': ['False']},
    'glance_store': {
        'filesystem_store_datadir': ['/var/lib/glance/images/'],
         'default_store': ['file']}}

block_until_oslo_config_entries_match(
    'glance',
    '/etc/glance/glance-api.conf',
    expected_contents,
    model_name='modelname')
Parameters
  • application_name (str) – Name of application

  • remote_file (str) – Remote path of file to transfer

  • expected_contents ({}) – The key value pairs in their corresponding sections to be looked for in the remote_file

  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for contents to appear in file

async zaza.model.async_block_until_service_status(unit_name, services, target_status, model_name=None, timeout=2700, pgrep_full=False)

Block until all services on the unit are in the desired state.

Block until all services on the unit are in the desired state (stopped or running):

block_until_service_status(
    first_unit,
    ['glance-api'],
    'running',
    model_name='modelname')
Parameters
  • unit_name (str) – Name of unit to run action on

  • services ([]) – List of services to check

  • target_status (str) – State services should be in (stopped or running)

  • model_name (str) – Name of model to query.

  • pgrep_full (bool) – Should pgrep be used rather than pidof to identify a service.

  • timeout (int) – Time to wait for status to be achieved

async zaza.model.async_block_until_services_restarted(application_name, mtime, services, model_name=None, timeout=2700, pgrep_full=False)

Block until the given services have a start time later then mtime.

For example to check that the glance-api service has been restarted:

block_until_services_restarted(
    'glance',
    1528294585,
    ['glance-api'],
    model_name='modelname')
Parameters
  • application_name (str) – Name of application

  • mtime (int) – Time in seconds since Epoch to check against

  • services ([]) – Listr of services to check restart time of

  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for services to be restarted

  • pgrep_full (bool) – Should pgrep be used rather than pidof to identify a service.

async zaza.model.async_block_until_unit_count(application, target_count, model_name=None, timeout=2700)

Block until the number of units matches target_count.

An example accessing this function via its sync wrapper:

block_until_unit_count('keystone', 4)
Parameters
  • application_name (str) – Name of application

  • target_count (int) – Number of expected units.

  • model_name (str) – Name of model to interact with.

  • timeout (float) – Time to wait for status to be achieved

async zaza.model.async_block_until_unit_wl_message_match(unit, status_pattern, model_name=None, negate_match=False, timeout=2700)

Block until the unit has a workload status message that matches pattern.

Parameters
  • unit (str) – the unit to check against

  • status_pattern (str) – Regex pattern to check status against.

  • model_name (Union[None, str]) – Name of model to query.

  • negate_match (Union[None, bool]) – Wait until the match is not true; i.e. none match

  • timeout (float) – Time to wait for unit to achieved desired status

async zaza.model.async_block_until_unit_wl_status(unit_name, status, model_name=None, negate_match=False, timeout=2700, subordinate_principal=None)

Block until the given unit has the desired workload status.

A units workload status may change during a given action. This function blocks until the given unit has the desired workload status:

block_until_unit_wl_status(
   aunit,
   'active'
   model_name='modelname')
NOTE: unit.workload_status was actually reporting the application workload

status. Using the full status output from model.get_status() gives us unit by unit workload status.

Parameters
  • unit_name (str) – Name of unit

  • status (str) – Status to wait for (active, maintenance etc)

  • model_name (str) – Name of model to query.

  • negate_match (bool) – Wait until the match is not true.

  • timeout (float) – Time to wait for unit to achieved desired status

  • subordinate_principal (str) – Name of the principal of unit_name, if unit_name is a subordinate

async zaza.model.async_block_until_units_on_machine_are_idle(machine, model_name=None, timeout=2700)

Block until all the units on a machine are idle.

Parameters
  • machine (str) – the machine

  • model_name (str) – Name of model to query.

  • timeout (float) – Time to wait for units on machine to be idle.

async zaza.model.async_block_until_wl_status_info_starts_with(app, status, model_name=None, negate_match=False, timeout=2700)

Block until the all the units have a desired workload status.

Block until all of the units have a desired workload status that starts with the string in the status param.

Parameters
  • app (str) – the application to check against

  • status (str) – Status to wait for at the start of the string

  • model_name (Union[None, str]) – Name of model to query.

  • negate_match (Union[None, bool]) – Wait until the match is not true; i.e. none match

  • timeout (float) – Time to wait for unit to achieved desired status

async zaza.model.async_check_if_subordinates_idle(app, unit_name)

Check if the specified unit’s subordinates are idle.

Parameters
  • app (str) – The name of the Juju application, ex: mysql

  • unit_name (str) – The unit name of the application, ex: mysql/0

Returns

The agent status, either active / idle, returned by Juju

Return type

str

async zaza.model.async_destroy_unit(application_name, *unit_names, model_name=None, wait_disappear=False)

Remove unit(s) of an application.

Parameters
  • application_name (str) – Name of application to remove unit(s) from

  • model_name (str) – Name of model to operate on.

  • wait_disappear (bool) – Whether to wait for the unit to disappear from juju status

Parm unit_names

One or more unit names. i.e. app/0

async zaza.model.async_get_agent_status(app, unit_name)

Get the current status of the specified unit.

Parameters
  • app (str) – The name of the Juju application, ex: mysql

  • unit_name (str) – The unit name of the application, ex: mysql/0

Returns

The agent status, either active / idle, returned by Juju

Return type

str

async zaza.model.async_get_application(application_name, model_name=None)

Return an application object.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application to retrieve units for

Returns

Application object

Return type

object

async zaza.model.async_get_application_config(application_name, model_name=None)

Return application configuration.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

Dictionary of configuration

Return type

dict

async zaza.model.async_get_cloud_data(credential_name=None, model_name=None)

Get connection details and credentials for cloud supporting given model.

Parameters
  • credential_name (Optional[str]) – Name of credential to retrieve.

  • model_name (Optional[str]) – Model name to operate on.

Returns

Credential Name, Juju Cloud Credential object

Return type

CloudData[str, Cloud, str, CloudCredential]

Raises

AssertionError

async zaza.model.async_get_current_model()

Return the current active model name.

Connect to the current active model and return its name.

Returns

String curenet model name

Return type

str

async zaza.model.async_get_juju_model()

Retrieve current model.

First check the environment for JUJU_MODEL. If this is not set, get the current active model.

Returns

In focus model name

Return type

str

async zaza.model.async_get_latest_charm_url(charm_url, channel=None, model_name=None)

Get charm url, including revision number, for latest charm version.

Parameters
  • charm_url (str) – Charm url without revision number

  • channel (str) – Channel to use when getting the charm from the charm store, e.g. ‘development’

  • model_name (str) – Name of model to operate on

async zaza.model.async_get_lead_unit(application_name, model_name=None)

Return the leader unit for a given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

Name of unit with leader status

Raises

zaza.utilities.exceptions.JujuError

async zaza.model.async_get_lead_unit_ip(application_name, model_name=None)

Return the IP address of the lead unit of a given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

IP of the lead unit

Return type

str

Raises

zaza.utilities.exceptions.JujuError

async zaza.model.async_get_lead_unit_name(application_name, model_name=None)

Return name of unit with leader status for given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

Name of unit with leader status

Return type

str

Raises

zaza.utilities.exceptions.JujuError

async zaza.model.async_get_machines(application_name, model_name=None)

Return all the machines of a given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application to retrieve units for

Returns

List of juju machines

Return type

[juju.machine.Machine, juju.machine.Machine,…]

async zaza.model.async_get_principle_sub_map(model_name=None)

Get a map of principle units to a list subordinates.

Parameters

model_name (str) – Name of model to operate on

Returns

Name of unit

Return type

Dict[str, [str]]

async zaza.model.async_get_principle_unit(unit_name, model_name=None)

Get principle unit name for subordinate.

Parameters
  • unit_name (str) – Name of unit

  • model_name (str) – Name of model to operate on

Returns

Name of unit

Return type

Union[str, None]

async zaza.model.async_get_relation_id(application_name, remote_application_name, model_name=None, remote_interface_name=None)

Get relation id of relation from model.

Parameters
  • application_name (str) – Name of application on this side of relation

  • remote_application_name (str) – Name of application on other side of relation

  • remote_interface_name (Optional(str)) – Name of interface on remote end of relation

  • model_name (str) – Name of model to operate on

Returns

Relation id of relation if found or None

Return type

any

async zaza.model.async_get_status(model_name=None, interval=4.0, refresh=True)

Return the full status, but share calls between different asyncs.

Return the full status for the model_name (current model is None), but no faster than interval time, which is a default of 4 seconds. If refresh is True, then this function waits until the interval is exceeded, and then returns the refreshed status. This is the default. If refresh is False, then the function immediately returns with the cached information.

This is to enable multiple co-routines to access the status information without making multiple calls to Juju which all essentially will return identical information.

Note that this is NOT thread-safe, but is async safe. i.e. multiple different co-operating async futures can call this (in the same thread) and all access the same status.

Parameters
  • model_name (str) – Name of model to query.

  • interval (float) – The minimum time between calls to get_status

  • refresh (boolean) – Force a refresh; do not used cached results

Returns

dictionary of juju status

Return type

dict

async zaza.model.async_get_unit_service_start_time(unit_name, service, model_name=None, timeout=None, pgrep_full=False)

Return the time that the given service was started on a unit.

Return the time (in seconds since Epoch) that the oldest process of the given service was started on the given unit. If the service is not running raise ServiceNotRunning exception.

If pgrep_full is True ensure that any special characters in the name of the service are escaped e.g.

service = ‘aodh-evaluator: AlarmEvaluationService worker(0)’

Parameters
  • model_name (str) – Name of model to query.

  • unit_name (str) – Name of unit to run action on

  • service (str) – Name of service to check is running

  • timeout (int) – Time to wait for status to be achieved

  • pgrep_full (bool) – Should pgrep be used rather than pidof to identify a service.

Returns

time in seconds since Epoch on unit

Return type

int

Raises

ServiceNotRunning

async zaza.model.async_get_unit_time(unit_name, model_name=None, timeout=None)

Get the current time (in seconds since Epoch) on the given unit.

Parameters
  • model_name (str) – Name of model to query.

  • unit_name (str) – Name of unit to run action on

Returns

time in seconds since Epoch on unit

Return type

int

async zaza.model.async_get_units(application_name, model_name=None)

Return all the units of a given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application to retrieve units for

Returns

List of juju units

Return type

[juju.unit.Unit, juju.unit.Unit,…]

async zaza.model.async_remove_application(application_name, model_name=None, forcefully_remove_machines=False)

Remove application from model.

Parameters
  • application_name (str) – Name of application

  • model_name (str) – Name of model to query.

  • forcefully_remove_machines (bool) – Forcefully remove the machines the application is runing on.

async zaza.model.async_remove_relation(application_name, local_relation, remote_relation, model_name=None)

Remove relation between applications.

Parameters
  • application_name (str) – Name of application on this side of relation

  • local_relation (str) – Name of relation on this application

  • remote_relation (str ‘<application>[:<relation_name>]) – Name of relation on the other application.

  • model_name (str) – Name of model to operate on.

async zaza.model.async_reset_application_config(application_name, config_keys, model_name=None)

Reset application configuration to default values.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

  • config_keys (List[str]) – List of configuration keys to reset to their defaults.

async zaza.model.async_resolve_units(application_name=None, wait=True, timeout=60, erred_hook=None, model_name=None)

Mark all the errored units as resolved or limit to an application.

Parameters
  • application_name (str) – Name of application

  • wait (bool) – Whether to wait for error state to have cleared.

  • timeout (int) – Seconds to wait for an individual units state to clear.

  • erred_hook (str) – Only resolve units that went into an error state when running the specified hook.

  • model_name (str) – Name of model to query.

async zaza.model.async_run_action(unit_name, action_name, model_name=None, action_params=None, raise_on_failure=False)

Run action on given unit.

Parameters
  • unit_name (str) – Name of unit to run action on

  • action_name (str) – Name of action to run

  • model_name (str) – Name of model to query.

  • action_params (dict) – Dictionary of config options for action

  • raise_on_failure (bool) – Raise ActionFailed exception on failure

Returns

Action object

Return type

juju.action.Action

Raises

ActionFailed

async zaza.model.async_run_action_on_leader(application_name, action_name, model_name=None, action_params=None, raise_on_failure=False)

Run action on lead unit of the given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

  • action_name (str) – Name of action to run

  • action_params (dict) – Dictionary of config options for action

  • raise_on_failure (bool) – Raise ActionFailed exception on failure

Returns

Action object

Return type

juju.action.Action

Raises

ActionFailed

async zaza.model.async_run_action_on_units(units, action_name, action_params=None, model_name=None, raise_on_failure=False, timeout=600)

Run action on list of unit in parallel.

The action is run on all units first without waiting for the action to complete. Then block until they are done.

Parameters
  • units (List[str]) – List of unit names

  • action_name (str) – Name of action to run

  • action_params (dict) – Dictionary of config options for action

  • model_name (str) – Name of model to query.

  • raise_on_failure (bool) – Raise ActionFailed exception on failure

  • timeout (int) – Time to wait for actions to complete

Returns

Action object

Return type

juju.action.Action

Raises

ActionFailed

async zaza.model.async_run_on_leader(application_name, command, model_name=None, timeout=None)

Juju run on leader unit.

Parameters
  • application_name (str) – Application to match

  • command (str) – Command to execute

  • model_name (str) – Name of model unit is in

  • timeout (int) – How long in seconds to wait for command to complete

Returns

action.data[‘results’] {‘Code’: ‘’, ‘Stderr’: ‘’, ‘Stdout’: ‘’}

Return type

dict

async zaza.model.async_run_on_machine(machine, command, model_name=None, timeout=None)

Juju run on unit.

This function uses a spawned process to run the juju run command rather that a native libjuju call as libjuju hasn’t implemented juju.Machine.run yet: https://github.com/juju/python-libjuju/issues/403

Parameters
  • model_name (str) – Name of model unit is in

  • unit_name – Name of unit to match

  • command (str) – Command to execute

  • timeout (int) – How long in seconds to wait for command to complete

Returns

action.data[‘results’] {‘Code’: ‘’, ‘Stderr’: ‘’, ‘Stdout’: ‘’}

Return type

dict

async zaza.model.async_run_on_unit(unit_name, command, model_name=None, timeout=None)

Juju run on unit.

Parameters
  • model_name (str) – Name of model unit is in

  • unit_name – Name of unit to match

  • command (str) – Command to execute

  • timeout (int) – How long in seconds to wait for command to complete

Returns

action.data[‘results’] {‘Code’: ‘’, ‘Stderr’: ‘’, ‘Stdout’: ‘’}

Return type

dict

async zaza.model.async_scp_from_unit(unit_name, source, destination, model_name=None, user='ubuntu', proxy=False, scp_opts='')

Transfer files from to unit_name in model_name.

Parameters
  • model_name (str) – Name of model unit is in

  • unit_name (str) – Name of unit to scp from

  • source (str) – Remote path of file(s) to transfer

  • destination – Local destination of transferred files

  • user – Remote username

  • proxy (bool) – Proxy through the Juju API server

  • scp_opts (str) – Additional options to the scp command

async zaza.model.async_scp_to_all_units(application_name, source, destination, model_name=None, user='ubuntu', proxy=False, scp_opts='')

Transfer files from to all units of an application.

Parameters
  • model_name (str) – Name of model unit is in

  • application_name (str) – Name of application to scp file to

  • source (str) – Local path of file(s) to transfer

  • destination – Remote destination of transferred files

  • user – Remote username

  • proxy (bool) – Proxy through the Juju API server

  • scp_opts (str) – Additional options to the scp command

async zaza.model.async_scp_to_unit(unit_name, source, destination, model_name=None, user='ubuntu', proxy=False, scp_opts='')

Transfer files to unit_name in model_name.

Parameters
  • model_name (str) – Name of model unit is in

  • unit_name (str) – Name of unit to scp to

  • source (str) – Local path of file(s) to transfer

  • destination – Remote destination of transferred files

  • user – Remote username

  • proxy (bool) – Proxy through the Juju API server

  • scp_opts (str) – Additional options to the scp command

async zaza.model.async_set_application_config(application_name, configuration, model_name=None)

Set application configuration.

NOTE: At the time of this writing python-libjuju requires all values passed to set_config to be str. https://github.com/juju/python-libjuju/issues/388

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

  • configuration (Dict[str,str]) – Dictionary of configuration setting(s)

async zaza.model.async_upgrade_charm(application_name, channel=None, force_series=False, force_units=False, path=None, resources=None, revision=None, switch=None, model_name=None)

Upgrade the given charm.

Parameters
  • application_name (str) – Name of application on this side of relation

  • channel (str) – Channel to use when getting the charm from the charm store, e.g. ‘development’

  • force_series (bool) – Upgrade even if series of deployed application is not supported by the new charm

  • force_units (bool) – Upgrade all units immediately, even if in error state

  • path (str) – Uprade to a charm located at path

  • resources (dict) – Dictionary of resource name/filepath pairs

  • revision (int) – Explicit upgrade revision

  • switch (str) – Crossgrade charm url

  • model_name (str) – Name of model to operate on

async zaza.model.async_wait_for_agent_status(model_name=None, status='executing', timeout=60)

Wait for at least one unit to enter a specific agent status.

This is useful for awaiting execution after mutating charm configuration.

Parameters
  • model_name (str) – Name of model to query.

  • status (str) – The desired agent status we are looking for.

  • timeout (int) – Time to wait for status to be achieved.

async zaza.model.async_wait_for_application_states(model_name=None, states=None, timeout=2700)

Wait for model to achieve the desired state.

Check the workload status and workload status message for every unit of every application. By default look for an ‘active’ workload status and a message that starts with one of the approved_message_prefixes.

Bespoke statuses and messages can be passed in with states. states takes the form:

states = {
    'app': {
        'workload-status': 'blocked',
        'workload-status-message-prefix': 'No requests without a prod',
        'num-expected-units': 3,
    },
    'anotherapp': {
        'workload-status-message-prefix': 'Unit is super ready'}}
wait_for_application_states('modelname', states=states)

The keys that can be used are:

  • “workload-status” - an exact match of the workload-status

  • “workload-status-message-prefix” - an exact match, that starts with the string passed.

  • “workload-status-message-regex” - the entire string matches if the regex matches.

  • “workloaed-status-message” - DEPRECATED; use

    “workload-status-message-prefix” instead.

  • “num-expected-units’ - the number of units to be ‘ready’.

To match an empty string, use:

“workload-status-message-regex”: “^$”

NOTE: all applications that are being waited on are expected to have at least one unit for that application to be ready. Any subordinate charms which have not be related to their principle by the time this function is called will ‘hang’ the function; in this case (if this is expected), then the application should be passed in the :param:states parameter with a ‘num-expected-units’ of 0 for the app in question.

Parameters
  • model_name (str) – Name of model to query.

  • states (dict) – States to look for

  • timeout (int) – Time to wait for status to be achieved

async zaza.model.async_wait_for_unit_idle(unit_name, timeout=600, include_subordinates=False)

Wait until the unit’s agent is idle.

Parameters
  • unit_name (str) – The unit name of the application, ex: mysql/0

  • timeout (int) – How long to wait before timing out

  • include_subordinates (bool) – Should this function wait for subordinate idle

Returns

None

Return type

None

zaza.model.attach_resource(application, resource_name, resource_path)

Attach resource to charm.

Parameters
  • application (str) – Application to get leader settings from.

  • resource_name (str) – The name of the resource as defined in metadata.yaml

  • resource_path (str) – The path to the resource on disk

Returns

None

Return type

None

async zaza.model.block_until_auto_reconnect_model(*conditions, model=None, aconditions=None, timeout=None, wait_period=0.5, loop=None)

Async block on the model until conditions met.

This function doesn’t use model.block_until() which unfortunately raises websockets.exceptions.ConnectionClosed if the connections gets closed, which seems to happen quite frequently. This funtion blocks until the conditions are met or a timeout occurs, and reconnects the model if it becomes disconnected.

Note that conditions are just passed as an unamed list in the function call to make it work more like the more simple ‘block_until’ function.

Parameters
  • model (:class:'juju.Model()') – the model to use

  • conditions ([List[Callable[[:class:'juju.Model()'], bool]]]) – a list of callables that need to evaluate to True.

  • aconditions (Optional[List[AsyncCallable[[:class:'juju.Model()'], bool]]]) – an optional list of async callables that need to evaluate to True.

  • timeout (float) – the timeout to wait for the block on.

  • wait_period (float) – The time to sleep between checking the conditions.

  • loop (An event loop) – The event loop to use

Raises

TimeoutError if the conditions never match (assuming timeout is not None).

zaza.model.check_model_for_hard_errors(model)

Check model for any hard errors that should halt a deployment.

The check for units or machines in an error state

Raises

Union[UnitError, MachineError]

zaza.model.check_unit_workload_status(model, unit, states)

Check that the units workload status matches the supplied state.

This function has the side effect of also checking for any units in an error state and aborting if any are found.

Parameters
  • model (juju.Model) – Model object to check in

  • unit (juju.Unit) – Unit to check wl status of

  • states (List[str]) – Acceptable unit work load states

Raises

UnitError

Returns

Whether units workload status matches desired state

Return type

bool

zaza.model.check_unit_workload_status_message(model, unit, message=None, prefixes=None, regex=None)

Check that the units workload status message.

Check that the units workload status message matches the supplied message, matches a regular expression (regex) or starts with one of the supplied prefixes. Raises an exception if neither prefixes or message is set. This function has the side effect of also checking for any units in an error state and aborting if any are found.

Note that the priority of checking is: message, then regex, then prefixes.

Parameters
  • model (juju.Model) – Model object to check in

  • unit (juju.Unit) – Unit to check wl status of

  • message (Optiona[str]) – Expected message text

  • prefixes (Optional[List[str]]) – Prefixes to match message against

  • regex (Optional[str]) – A regular expression against which to test the message

Raises

ValueError, UnitError

Returns

Whether message matches desired string

Return type

bool

zaza.model.complete_series_upgrade(machine_num)

Execute juju series-upgrade complete on machine.

NOTE: This is a new feature in juju behind a feature flag and not yet in libjuju. export JUJU_DEV_FEATURE_FLAGS=upgrade-series

Parameters

machine_num (str) – Machine number

Returns

None

Return type

None

async zaza.model.deployed(model_name=None)

List deployed applications.

Parameters

model_name (string) – Name of the model to list applications from

async zaza.model.ensure_model_connected(model)

Ensure that the model is connected.

If model is disconnected then reconnect it.

Parameters

model (:class:'juju.Model') – the model to check

zaza.model.file_contents(unit_name, path, timeout=None)

Return the contents of a file.

Parameters
  • path – File path

  • unit_name (str) – Unit name, either appname/N or appname/leader

  • timeout (float) – Timeout in seconds

Returns

File contents

Return type

str

zaza.model.get_actions(application_name, model_name=None)

Get the actions an applications supports.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

Dictionary of actions and their descriptions

Return type

dict

zaza.model.get_app_ips(application_name, model_name=None)

Return public address of all units of an application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

List of ip addresses

Return type

[str, str,…]

zaza.model.get_first_unit_name(application_name, model_name=None)

Return name of lowest numbered unit of given application.

Parameters
  • model_name (str) – Name of model to query.

  • application_name (str) – Name of application

Returns

Name of lowest numbered unit

Return type

str

zaza.model.get_juju_model_aliases()

Return the model aliases from global.

Returns

Model alias map

Return type

dict

zaza.model.get_unit_from_name(unit_name, model=None, model_name=None)

Return the units that corresponds to the name in the given model.

Parameters
  • unit_name (str) – Name of unit to match

  • model (model.Model()) – Model to perform lookup in

  • model_name (string) – Name of the model to perform lookup in

Returns

Unit matching given name

Return type

juju.unit.Unit or None

Raises

UnitNotFound

zaza.model.is_model_disconnected(model)

Return True if the model is disconnected.

Parameters

model (:class:'juju.Model') – the model to check

Returns

True if disconnected

Return type

bool

zaza.model.is_unit_idle(unit)

Return True if the unit is in the idle state.

Note: the unit only makes progress (in terms of updating it’s idle status) if this function is called as part of an asyncio loop as the status is updated in a co-routine/future.

Parameters

unit (:class:'juju.unit.Unit') – the unit to test

Returns

True if the unit is in the idle state

Return type

bool

zaza.model.machines_in_state(model, states)

Check model for machines whose state is in the list ‘states’.

Parameters
  • model (juju.Model) – Model object to check

  • states (List) – List of states to check for

Returns

List of machines

Return type

List[juju.machine.Machine]

zaza.model.prepare_series_upgrade(machine_num, to_series='xenial')

Execute juju series-upgrade prepare on machine.

NOTE: This is a new feature in juju behind a feature flag and not yet in libjuju. export JUJU_DEV_FEATURE_FLAGS=upgrade-series

Parameters
  • machine_num (str) – Machine number

  • to_series (str) – The series to which to upgrade

Returns

None

Return type

None

zaza.model.run_in_model(model_name)

Context manager for executing code inside a libjuju model.

Example of using run_in_model:
async with run_in_model(model_name) as model:

model.do_something()

Parameters

model_name (str) – Name of model to run function in

Returns

The juju Model object correcsponding to model_name

Return type

Iterator[:class:’juju.Model()’]

zaza.model.set_juju_model(model_name)

Point environment at the given model.

Parameters

model_name (str) – Model to point environment at

zaza.model.set_juju_model_aliases(model_aliases)

Store the model aliases in a global.

Parameters

model_aliases (dict) – Model alias map to store

zaza.model.set_model_constraints(constraints, model_name=None)

Set constraints on a model.

Note: Subprocessing out to ‘juju’ is a temporary solution until

https://bit.ly/2ujbVPA lands in libjuju.

Parameters
  • constraints (dict) – Constraints to be applied to model

  • model_name (str) – Name of model to operate on

zaza.model.set_series(application, to_series)

Execute juju set-series complete on application.

NOTE: This is a new feature in juju and not yet in libjuju.

Parameters
  • application (str) – Name of application to upgrade series

  • to_series (str) – The series to which to upgrade

Returns

None

Return type

None

zaza.model.units_with_wl_status_state(model, state)

Return a list of unit which have a matching workload status.

Returns

Units in error state

Return type

[juju.Unit, …]

zaza.model.unset_juju_model_aliases()

Remove model alias data.