juju.model
Summary
Create a Zip archive of a local charm directory for upload to a controller. Methods: |
CharmhubDeployType defines a class for resolving and deploying charmhub charms and bundles. Methods: |
DeployTypeResult represents the result of a deployment type after a resolution. |
LocalDeployType deals with local only deployments. Methods: |
The main API for interacting with a Juju model. Methods: |
An object in the Model tree Methods: |
Methods: |
Base class for creating observers that react to changes in a model. Methods: |
Holds the state of the model, including the delta history of all entities in the model. Methods: |
Reference
- class juju.model.CharmArchiveGenerator(path)[source]
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)[source]
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)[source]
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)[source]
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)[source]
Bases:
object
DeployTypeResult represents the result of a deployment type after a resolution.
- class juju.model.LocalDeployType[source]
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)[source]
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)[source]
Bases:
object
The main API for interacting with a Juju model.
- add_local_charm(charm_file, series='', size=None)[source]
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)[source]
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)[source]
_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)[source]
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)[source]
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.- delta - An instance of
- coroutine add_relation(relation1, relation2)[source]
Deprecated since version 2.9.9: Use
relate()
instead
- coroutine add_space(name, cidrs=None, public=True)[source]
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)[source]
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
- 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)[source]
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)[source]
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 theendpoint
anduuid
are not.Otherwise, all of the
endpoint
,uuid
, and authentication information (username
andpassword
, orbakery_client
and/ormacaroons
) 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 theendpoint
.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_model(model_name, **kwargs)[source]
Deprecated since version 0.6.2: Use
connect(model_name=model_name)
instead.
- connection()[source]
Return the current Connection object. It raises an exception if the Model is disconnected
- coroutine consume(endpoint, application_alias='', controller_name=None, controller=None)[source]
Adds a remote offer to the model. Relations can be created later using “juju relate”.
- coroutine create_backup(notes=None)[source]
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)[source]
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='')[source]
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=[])[source]
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=[])[source]
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 constraintsforce (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)[source]
Destroy units by name.
- coroutine destroy_units(*unit_names, destroy_storage=False, dry_run=False, force=False, max_wait=None)[source]
Destroy several units at once.
- download_backup(archive_id, target_filename=None)[source]
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)[source]
Exports the current model configuration as a reusable bundle.
- coroutine get_action_output(action_uuid, wait=None)[source]
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)[source]
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()[source]
Get annotations on this model.
- Return dict:
The annotations for this model
- coroutine get_backups()[source]
Retrieve metadata for backups in this model.
- Return [dict]:
List of metadata for the stored backups
- coroutine get_config()[source]
Return the configuration settings for this model.
- Returns:
A
dict
mapping keys to ConfigValue instances, which have source and value attributes.
- coroutine get_constraints()[source]
Return the machine constraints for this model.
- Returns:
A
dict
of constraints.
- coroutine get_controller()[source]
Return a Controller instance for the currently connected model. :return Controller:
- coroutine get_metrics(*tags)[source]
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()[source]
Return list of all known spaces, including associated subnets.
Returns a List of
Space
instances.
- coroutine get_ssh_key(raw_ssh=False)[source]
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)[source]
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)[source]
Add a relation between two applications.
- Parameters:
relation1 (str) – ‘<application>[:<relation_name>]’
relation2 (str) – ‘<application>[:<relation_name>]’
- coroutine list_offers()[source]
Offers list information about applications’ endpoints that have been shared and who is connected.
- coroutine list_secrets(filter='', show_secrets=False)[source]
Returns the list of available secrets.
- coroutine list_storage(filesystem=False, volume=False)[source]
Lists storage details.
- Parameters:
filesystem (bool) – List filesystem storage
volume (bool) – List volume storage
- 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)[source]
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)[source]
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)[source]
Delete a backup.
- Parameters:
backup_id (str) – The id of the backup to remove
- coroutine remove_backups(backup_ids)[source]
Delete the given backups.
- Parameters:
backup_ids ([str]) – The list of ids of the backups to remove
- coroutine remove_offer(endpoint, force=False)[source]
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)[source]
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)[source]
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)[source]
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)[source]
Remove an existing storage pool.
- Parameters:
name (str) –
- Returns:
- coroutine reset(force=False)[source]
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)[source]
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 constraintsarchive (str) – Path to backup archive to restore
upload_tools (bool) – Upload tools if bootstrapping a new machine
- coroutine set_annotations(annotations)[source]
Set annotations on this model.
- Parameters:
map[string]string (annotations) – the annotations as key/value pairs.
- coroutine set_config(config)[source]
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)[source]
Set machine constraints on this model.
- Parameters:
config (dict) – Mapping of model constraints
- coroutine show_storage_details(*storage_ids)[source]
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='')[source]
Update storage pool attributes.
- Parameters:
name –
attributes – “key=value key=value …”
- Returns:
- 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)[source]
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)[source]
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()[source]
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()[source]
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).
- previous()[source]
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)[source]
Bases:
ModelEntity
- property tag
- class juju.model.ModelObserver[source]
Bases:
object
Base class for creating observers that react to changes in a model.
- coroutine on_change(delta, old, new, model)[source]
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)[source]
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)[source]
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)[source]
Return the data dict for an entity at a specific index of its history.
- get_entity(entity_type, entity_id, history_index=-1, connected=True)[source]
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.