juju.model

Summary

CharmArchiveGenerator

Create a Zip archive of a local charm directory for upload to a controller. Methods: make_archive

CharmhubDeployType

CharmhubDeployType defines a class for resolving and deploying charmhub charms and bundles. Methods: resolve

DeployTypeResult

DeployTypeResult represents the result of a deployment type after a resolution.

LocalDeployType

LocalDeployType deals with local only deployments. Methods: resolve

Model

The main API for interacting with a Juju model. Methods: add_local_charm add_local_charm_dir add_local_resources add_machine add_observer add_relation add_space add_ssh_key add_ssh_keys all_units_idle block_until connect connect_current connect_model connect_to connection consume create_backup create_offer create_storage_pool debug_log deploy destroy_unit destroy_units disconnect download_backup export_bundle get_action_output get_action_status get_annotations get_backups get_config get_constraints get_controller get_machines get_metrics get_spaces get_ssh_key get_ssh_keys get_status integrate is_connected list_offers list_secrets list_storage list_storage_pools relate remove_application remove_backup remove_backups remove_offer remove_saas remove_ssh_key remove_ssh_keys remove_storage remove_storage_pool reset restore_backup set_annotations set_config set_constraints show_storage_details update_storage_pool wait_for_action wait_for_idle

ModelEntity

An object in the Model tree Methods: latest next on_change on_remove previous

ModelInfo

Methods: latest next on_change on_remove previous type_name_override

ModelObserver

Base class for creating observers that react to changes in a model. Methods: on_change

ModelState

Holds the state of the model, including the delta history of all entities in the model. Methods: apply_delta entity_data entity_history get_entity

Reference

class juju.model.CharmArchiveGenerator(path)

Bases: object

Create a Zip archive of a local charm directory for upload to a controller.

This is used automatically by Model.add_local_charm_dir.

make_archive(path)

Create archive of directory and write to path.

Parameters:

path – Path to archive

Ignored:

* build/* - This is used for packing the charm itself and any
              similar tasks.
* */.*    - Hidden files are all ignored for now.  This will most
              likely be changed into a specific ignore list
              (.bzr, etc)

class juju.model.CharmhubDeployType(charm_resolver)

Bases: object

CharmhubDeployType defines a class for resolving and deploying charmhub charms and bundles.

coroutine resolve(url, architecture, app_name=None, channel=None, series=None, revision=None, entity_url=None, force=False, model_conf=None)

resolve attempts to resolve charmhub charms or bundles. A request to the charmhub API is required to correctly determine the charm url and underlying origin.

class juju.model.DeployTypeResult(identifier, origin, app_name, is_local=False, is_bundle=False)

Bases: object

DeployTypeResult represents the result of a deployment type after a resolution.

class juju.model.LocalDeployType

Bases: object

LocalDeployType deals with local only deployments.

coroutine resolve(charm_path, architecture, app_name=None, channel=None, series=None, revision=None, entity_url=None, force=False, model_conf=None)

resolve attempts to resolve a local charm or bundle using the url and architecture. If information is missing, it will attempt to backfill that information, before sending the result back.

– revision flag is ignored for local charms

class juju.model.Model(max_frame_size=None, bakery_client=None, jujudata=None)

Bases: object

The main API for interacting with a Juju model.

add_local_charm(charm_file, series='', size=None)

Upload a local charm archive to the model.

Returns the ‘local:…’ url that should be used to deploy the charm.

Parameters:

• charm_file – Path to charm zip archive

• series – Charm series

• size – Size of the archive, in bytes

Return str:

‘local:…’ url for deploying the charm

Raises:

JujuError if the upload fails

Uses an https endpoint at the same host:port as the wss. Supports large file uploads.

Warning

This method will block. Consider using add_local_charm_dir() instead.

coroutine add_local_charm_dir(charm_dir, series)

Upload a local charm to the model.

This will automatically generate an archive from the charm dir.

Parameters:

• charm_dir – Path to the charm directory

• series – Charm series

coroutine add_local_resources(application, entity_url, metadata, resources)

_add_local_resources is called by the deploy to add pending local resources requested by the charm being deployed. It calls the ResourcesFacade.AddPendingResources. After getting the pending IDs from the controller it sends an HTTP PUT request to actually upload local resources.

Parameters:

• application (str) – the name of the application

• entity_url (client.CharmURL) – url for the charm that we add resources for

• metadata ([string]string) – metadata for the charm that we add resources for

• resources ([string]) – the paths for the local files (or oci-images) to be added as

local resources

:returns [string]string resource_map that is a map of resources to their assigned pendingIDs.

coroutine add_machine(spec=None, constraints=None, disks=None, series=None)

Start a new, empty machine and optionally a container, or add a container to a machine.

Parameters:

• spec (str) –

  Machine specification Examples:

  (None) - starts a new machine
  'lxd' - starts a new machine with one lxd container
  'lxd:4' - starts a new lxd container on machine 4
  'ssh:user@10.10.0.3:/path/to/private/key' - manually provision
  a machine with ssh and the private key used for authentication
  'zone=us-east-1a' - starts a machine in zone us-east-1s on AWS
  'maas2.name' - acquire machine maas2.name on MAAS
  

• constraints (dict) –

  Machine constraints, which can contain the the following keys:

  arch : str
  container : str
  cores : int
  cpu_power : int
  instance_type : str
  mem : int
  root_disk : int
  spaces : list(str)
  tags : list(str)
  virt_type : str
  

  Example:

  constraints={
      'mem': 256 * MB,
      'tags': ['virtual'],
  }
  

• disks (list) –

  List of disk constraint dictionaries, which can contain the following keys:

  count : int
  pool : str
  size : int
  

  Example:

  disks=[{
      'pool': 'rootfs',
      'size': 10 * GB,
      'count': 1,
  }]
  

• series (str) – Series, e.g. ‘xenial’

Supported container types are: lxd, kvm

When deploying a container to an existing machine, constraints cannot be used.

add_observer(callable_, entity_type=None, action=None, entity_id=None, predicate=None)

Register an “on-model-change” callback

Once the model is connected, callable_ will be called each time the model changes. callable_ should be Awaitable and accept the following positional arguments:

delta - An instance of juju.delta.EntityDelta

containing the raw delta data recv’d from the Juju websocket.

old_obj - If the delta modifies an existing object in the model,

old_obj will be a copy of that object, as it was before the delta was applied. Will be None if the delta creates a new entity in the model.

new_obj - A copy of the new or updated object, after the delta

is applied. Will be None if the delta removes an entity from the model.

model - The Model itself.

Events for which callable_ is called can be specified by passing entity_type, action, and/or entitiy_id filter criteria, e.g.:

add_observer(
    myfunc,
    entity_type='application', action='add', entity_id='ubuntu')

For more complex filtering conditions, pass a predicate function. It will be called with a delta as its only argument. If the predicate function returns True, the callable_ will be called.

coroutine add_relation(relation1, relation2)

Deprecated since version 2.9.9: Use relate() instead

coroutine add_space(name, cidrs=None, public=True)

Add a new network space.

Adds a new space with the given name and associates the given (optional) list of existing subnet CIDRs with it.

Parameters:

• name (str) – Name of the space

• cidrs (List[str]) – Optional list of existing subnet CIDRs

coroutine add_ssh_key(user, key)

Add a public SSH key to this model.

Parameters:

• user (str) – The username of the user

• key (str) – The public ssh key

coroutine add_ssh_keys(user, key)

Add a public SSH key to this model.

Parameters:

• user (str) – The username of the user

• key (str) – The public ssh key

all_units_idle()

Return True if all units are idle.

property application_offers

Return a map of application-name:Application for all applications offers currently in the model.

property applications

Return a map of application-name:Application for all applications currently in the model.

coroutine block_until(*conditions, timeout=None, wait_period=0.5)

Return only after all conditions are true.

Raises websockets.ConnectionClosed if disconnected.

property charmhub

Return a charmhub repository for requesting charm information using the charm-hub-url model config.

coroutine connect(*args, **kwargs)

Connect to a juju model.

This supports two calling conventions:

The model and (optionally) authentication information can be taken from the data files created by the Juju CLI. This convention will be used if a model_name is specified, or if the endpoint and uuid are not.

Otherwise, all of the endpoint, uuid, and authentication information (username and password, or bakery_client and/or macaroons) are required.

If a single positional argument is given, it will be assumed to be the model_name. Otherwise, the first positional argument, if any, must be the endpoint.

Available parameters are:

Parameters:

• model_name – Format [controller:][user/]model

• endpoint (str) – The hostname:port of the controller to connect to.

• uuid (str) – The model UUID to connect to.

• username (str) – The username for controller-local users (or None to use macaroon-based login.)

• password (str) – The password for controller-local users.

• cacert (str) – The CA certificate of the controller (PEM formatted).

• bakery_client (httpbakery.Client) – The macaroon bakery client to to use when performing macaroon-based login. Macaroon tokens acquired when logging will be saved to bakery_client.cookies. If this is None, a default bakery_client will be used.

• macaroons (list) – List of macaroons to load into the bakery_client.

• max_frame_size (int) – The maximum websocket frame size to allow.

• specified_facades – Overwrite the facades with a series of specified facades.

coroutine connect_current()

Deprecated since version 0.6.2: Use connect() instead.

coroutine connect_model(model_name, **kwargs)

Deprecated since version 0.6.2: Use connect(model_name=model_name) instead.

coroutine connect_to(connection)

connection()

Return the current Connection object. It raises an exception if the Model is disconnected

coroutine consume(endpoint, application_alias='', controller_name=None, controller=None)

Adds a remote offer to the model. Relations can be created later using “juju relate”.

coroutine create_backup(notes=None)

Create a backup of this model.

Parameters:

• note (str) – A note to store with the backup

• keep_copy (bool) – Keep a copy of the archive on the controller

• no_download (bool) – Do not download the backup archive

Return str, dict:

Filename for the downloaded archive file, Extra metadata for the created backup

coroutine create_offer(endpoint, offer_name=None, application_name=None)

Offer a deployed application using a series of endpoints for use by consumers.

@param endpoint: holds the application and endpoint you want to offer @param offer_name: over ride the offer name to help the consumer

coroutine create_storage_pool(name, provider_type, attributes='')

Create or define a storage pool.

Parameters:

• name (str) – a pool name

• provider_type (str) – provider type (defaults to “kubernetes” for

Kubernetes models) :param str attributes: attributes for configuration as space-separated pairs, e.g. tags, size, path, etc. :return:

coroutine debug_log(target=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, no_tail=False, exclude_module=[], include_module=[], include=[], level='', limit=9223372036854775807, lines=10, exclude=[])

Get log messages for this model.

Parameters:

• no_tail (bool) – Stop after returning existing log messages

• exclude_module (list) – Do not show log messages for these logging modules

• include_module (list) – Only show log messages for these logging modules

• include (list) – Only show log messages for these entities

• level (str) – Log level to show, valid options are ‘TRACE’, ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR,

• limit (int) – Return this many of the most recent (possibly filtered) lines are shown

• lines (int) – Yield this many of the most recent lines, and keep yielding

• exclude (list) – Do not show log messages for these entities

coroutine deploy(entity_url, application_name=None, bind=None, channel=None, config=None, constraints=None, force=False, num_units=1, overlays=[], base=None, resources=None, series=None, revision=None, storage=None, to=None, devices=None, trust=False, attach_storage=[])

Deploy a new service or bundle.

Parameters:

• entity_url (str) – Charm or bundle to deploy. Charm url or file path

• application_name (str) – Name to give the service

• bind (dict) – <charm endpoint>:<network space> pairs

• channel (str) – Charm store channel from which to retrieve the charm or bundle, e.g. ‘edge’

• config (dict) – Charm configuration dictionary

• constraints (juju.Constraints) – Service constraints

• force (bool) – Allow charm to be deployed to a machine running an unsupported series

• num_units (int) – Number of units to deploy

• overlays ([]) – Bundles to overlay on the primary bundle, applied in order

• base (str) – The base on which to deploy

• resources (dict) – <resource name>:<file path> pairs

• series (str) – Series on which to deploy DEPRECATED: use –base (with Juju 3.1)

• revision (int) – specifying a revision requires a channel for future upgrades for charms. For bundles, revision and channel are mutually exclusive.

• storage (dict) – Storage constraints TODO how do these look?

• to –

  Placement directive as a string. For example:

  ’23’ - place on machine 23 ‘lxd:7’ - place in new lxd container on machine 7 ‘24/lxd/3’ - place in container 3 on machine 24

  If None, a new machine is provisioned.

• devices – charm device constraints

• trust (bool) – Trust signifies that the charm should be deployed with access to trusted credentials. Hooks run by the charm can access cloud credentials and other trusted access credentials.

• attach_storage (str[]) – Existing storage to attach to the deployed unit (not available on k8s models)

coroutine destroy_unit(unit_id, destroy_storage=False, dry_run=False, force=False, max_wait=None)

Destroy units by name.

coroutine destroy_units(*unit_names, destroy_storage=False, dry_run=False, force=False, max_wait=None)

Destroy several units at once.

coroutine disconnect()

Shut down the watcher task and close websockets.

download_backup(archive_id, target_filename=None)

Download a backup archive file.

Parameters:

• archive_id (str) – The id of the archive to download

• target_filename (str (optional)) – A custom name for the target file

Return str:

Path to the archive file

coroutine export_bundle(filename=None)

Exports the current model configuration as a reusable bundle.

coroutine get_action_output(action_uuid, wait=None)

Get the results of an action by ID.

Parameters:

• action_uuid (str) – Id of the action

• wait (int) – Time in seconds to wait for action to complete.

Return dict:

Output from action

Raises:

JujuError if invalid action_uuid

coroutine get_action_status(uuid_or_prefix=None, name=None)

Get the status of all actions, filtered by ID, ID prefix, or name.

Parameters:

• uuid_or_prefix (str) – Filter by action uuid or prefix

• name (str) – Filter by action name

coroutine get_annotations()

Get annotations on this model.

Return dict:

The annotations for this model

coroutine get_backups()

Retrieve metadata for backups in this model.

Return [dict]:

List of metadata for the stored backups

coroutine get_config()

Return the configuration settings for this model.

Returns:

A dict mapping keys to ConfigValue instances, which have source and value attributes.

coroutine get_constraints()

Return the machine constraints for this model.

Returns:

A dict of constraints.

coroutine get_controller()

Return a Controller instance for the currently connected model. :return Controller:

coroutine get_machines()

Return list of machines in this model.

coroutine get_metrics(*tags)

Retrieve metrics.

Parameters:

*tags (str) –

Tags of entities from which to retrieve metrics. No tags retrieves the metrics of all units in the model.

Returns:

Dictionary of unit_name:metrics

coroutine get_spaces()

Return list of all known spaces, including associated subnets.

Returns a List of Space instances.

coroutine get_ssh_key(raw_ssh=False)

Return known SSH keys for this model. :param bool raw_ssh: if True, returns the raw ssh key,

else it’s fingerprint

coroutine get_ssh_keys(raw_ssh=False)

Return known SSH keys for this model. :param bool raw_ssh: if True, returns the raw ssh key,

else it’s fingerprint

coroutine get_status(filters=None, utc=False)

Return the status of the model.

Parameters:

• filters (str) – Optional list of applications, units, or machines to include, which can use wildcards (‘*’).

• utc (bool) – Display time as UTC in RFC3339 format

property info

Return the cached client.ModelInfo object for this Model.

If Model.get_info() has not been called, this will return None.

coroutine integrate(relation1, relation2)

Add a relation between two applications.

Parameters:

• relation1 (str) – ‘<application>[:<relation_name>]’

• relation2 (str) – ‘<application>[:<relation_name>]’

is_connected()

Reports whether the Model is currently connected.

coroutine list_offers()

Offers list information about applications’ endpoints that have been shared and who is connected.

coroutine list_secrets(filter='', show_secrets=False)

Returns the list of available secrets.

coroutine list_storage(filesystem=False, volume=False)

Lists storage details.

Parameters:

• filesystem (bool) – List filesystem storage

• volume (bool) – List volume storage

Returns:

coroutine list_storage_pools()

List storage pools.

Returns:

property machines

Return a map of machine-id:Machine for all machines currently in the model.

property name

Return the name of this model

coroutine relate(relation1, relation2)

The relate function is deprecated in favor of integrate.

The logic is the same.

property relations

Return a list of all Relations currently in the model.

property remote_applications

Return a map of application-name:Application for all remote applications currently in the model.

coroutine remove_application(app_name, block_until_done=False, force=False, destroy_storage=False, no_wait=False)

Removes the given application from the model.

Parameters:

• app_name (str) – Name of the application

• force (bool) – Completely remove an application and all its dependencies. (=false)

• destroy_storage (bool) – Destroy storage attached to application unit. (=false)

• no_wait (bool) – Rush through application removal without waiting for each individual step to complete (=false)

• block_until_done (bool) – Ensure the app is removed from the

model when returned

coroutine remove_backup(backup_id)

Delete a backup.

Parameters:

backup_id (str) – The id of the backup to remove

coroutine remove_backups(backup_ids)

Delete the given backups.

Parameters:

backup_ids ([str]) – The list of ids of the backups to remove

coroutine remove_offer(endpoint, force=False)

Remove offer for an application.

Offers will also remove relations to those offers, use force to do so, without an error.

coroutine remove_saas(name)

Removing a consumed (SAAS) application will terminate any relations that application has, potentially leaving any related local applications in a non-functional state.

coroutine remove_ssh_key(user, key)

Remove a public SSH key(s) from this model.

Parameters:

• key (str) – Full ssh key

• user (str) – Juju user to which the key is registered

coroutine remove_ssh_keys(user, key)

Remove a public SSH key(s) from this model.

Parameters:

• key (str) – Full ssh key

• user (str) – Juju user to which the key is registered

coroutine remove_storage(*storage_ids, force=False, destroy_storage=False)

Removes storage from the model.

Parameters:

• force (bool) – Remove storage even if it is currently attached

• destroy_storage (bool) – Remove the storage and destroy it

• storage_ids ([]str) –

Returns:

coroutine remove_storage_pool(name)

Remove an existing storage pool.

Parameters:

name (str) –

Returns:

coroutine reset(force=False)

Reset the model to a clean state.

Parameters:

force (bool) – Force-terminate machines.

This returns only after the model has reached a clean state. “Clean” means no applications or machines exist in the model.

restore_backup(backup_id, bootstrap=False, constraints=None, archive=None, upload_tools=False)

Restore a backup archive to a new controller.

Parameters:

• backup_id (str) – Id of backup to restore

• bootstrap (bool) – Bootstrap a new state machine

• constraints (juju.Constraints) – Model constraints

• archive (str) – Path to backup archive to restore

• upload_tools (bool) – Upload tools if bootstrapping a new machine

coroutine set_annotations(annotations)

Set annotations on this model.

Parameters:

map[string]string (annotations) – the annotations as key/value pairs.

coroutine set_config(config)

Set configuration keys on this model.

Parameters:

config (dict) – Mapping of config keys to either string values or ConfigValue instances, as returned by get_config.

coroutine set_constraints(constraints)

Set machine constraints on this model.

Parameters:

config (dict) – Mapping of model constraints

coroutine show_storage_details(*storage_ids)

Shows storage instance information.

Parameters:

storage_ids ([]str) –

Returns:

property strict_mode

property subordinate_units

Return a map of unit-id:Unit for all subordiante units currently in the model.

property tag

property units

Return a map of unit-id:Unit for all units currently in the model.

coroutine update_storage_pool(name, attributes='')

Update storage pool attributes.

Parameters:

• name –

• attributes – “key=value key=value …”

Returns:

coroutine wait_for_action(action_id)

Given an action, wait for it to complete.

coroutine wait_for_idle(apps=None, raise_on_error=True, raise_on_blocked=False, wait_for_active=False, timeout=600, idle_period=15, check_freq=0.5, status=None, wait_for_at_least_units=None, wait_for_exact_units=None)

Wait for applications in the model to settle into an idle state.

Parameters:

• apps (List[str]) – Optional list of specific app names to wait on. If given, all apps must be present in the model and idle, while other apps in the model can still be busy. If not given, all apps currently in the model must be idle.

• raise_on_error (bool) – If True, then any unit or app going into “error” status immediately raises either a JujuAppError or a JujuUnitError. Note that machine or agent failures will always raise an exception (either JujuMachineError or JujuAgentError), regardless of this param. The default is True.

• raise_on_blocked (bool) – If True, then any unit or app going into “blocked” status immediately raises either a JujuAppError or a JujuUnitError. The default is False.

• wait_for_active (bool) – If True, then also wait for all unit workload statuses to be “active” as well. The default is False.

• timeout (float) – How long to wait, in seconds, for the bundle settles before raising an asyncio.TimeoutError. If None, will wait forever. The default is 10 minutes.

• idle_period (float) – How long, in seconds, the agent statuses of all units of all apps need to be idle. This delay is used to ensure that any pending hooks have a chance to start to avoid false positives. The default is 15 seconds.

• check_freq (float) – How frequently, in seconds, to check the model. The default is every half-second.

• status (str) – The status to wait for. If None, not waiting. The default is None (not waiting for any status).

• wait_for_at_least_units (int) – The least number of units to go into the idle

state. wait_for_idle will return after that many units are available (across all the given applications).

The default is 1 unit.

Parameters:

wait_for_exact_units (int) – The exact number of units to be expected before going into the idle state. (e.g. useful for scaling down). When set, takes precedence over the wait_for_units parameter.

class juju.model.ModelEntity(entity_id, model, history_index=-1, connected=True)

Bases: object

An object in the Model tree

property alive

Returns True if this entity still exists in the underlying model.

property current

Return True if this object represents the current state of the entity in the underlying model.

This will be True except when the object represents an entity at a non-latest state in history, e.g. if the object was obtained by calling .previous() on another object.

property data

The data dictionary for this entity.

property dead

Returns True if this entity no longer exists in the underlying model.

property entity_type

A string identifying the entity type of this object, e.g. ‘application’ or ‘unit’, etc.

latest()

Return a copy of this object at its current state in the model.

Returns self if this object is already the latest.

The returned object is always “connected”, i.e. receives live updates from the model.

next()

Return a copy of this object at its next state in history.

Returns None if this object is already the latest.

The returned object is “disconnected”, i.e. does not receive live updates, unless it is current (latest).

on_change(callable_)

Add a change observer to this entity.

on_remove(callable_)

Add a remove observer to this entity.

previous()

Return a copy of this object as was at its previous state in history.

Returns None if this object is new (and therefore has no history).

The returned object is always “disconnected”, i.e. does not receive live updates.

property safe_data

The data dictionary for this entity.

If this ModelEntity points to the dead state, it will raise DeadEntityException.

class juju.model.ModelInfo(entity_id, model, history_index=-1, connected=True)

Bases: ModelEntity

property tag

static type_name_override()

class juju.model.ModelObserver

Bases: object

Base class for creating observers that react to changes in a model.

coroutine on_change(delta, old, new, model)

Generic model-change handler.

This should be overridden in a subclass.

Parameters:

• delta – juju.client.overrides.Delta

• old – juju.model.ModelEntity

• new – juju.model.ModelEntity

• model – juju.model.Model

class juju.model.ModelState(model)

Bases: object

Holds the state of the model, including the delta history of all entities in the model.

property application_offers

Return a map of application-name:Application for all applications offers currently in the model.

property applications

Return a map of application-name:Application for all applications currently in the model.

apply_delta(delta)

Apply delta to our state and return a copy of the affected object as it was before and after the update, e.g.:

old_obj, new_obj = self.apply_delta(delta)

old_obj may be None if the delta is for the creation of a new object, e.g. a new application or unit is deployed.

new_obj will never be None, but may be dead (new_obj.dead == True) if the object was deleted as a result of the delta being applied.

entity_data(entity_type, entity_id, history_index)

Return the data dict for an entity at a specific index of its history.

entity_history(entity_type, entity_id)

Return the history deque for an entity.

get_entity(entity_type, entity_id, history_index=-1, connected=True)

Return an object instance for the given entity_type and id.

By default the object state matches the most recent state from Juju. To get an instance of the object in an older state, pass history_index, an index into the history deque for the entity.

property machines

Return a map of machine-id:Machine for all machines currently in the model.

property relations

Return a map of relation-id:Relation for all relations currently in the model.

property remote_applications

Return a map of application-name:Application for all remote applications currently in the model.

property subordinate_units

Return a map of unit-id:Unit for all subordinate units

property units

Return a map of unit-id:Unit for all units currently in the model.