Welcome to The Operator Framework’s documentation!¶
ops package¶
The Operator Framework.
Submodules¶
ops.charm module¶
Base objects for the Charm, events and metadata.
-
class
ops.charm.
HookEvent
(handle)[source]¶ Bases:
ops.framework.EventBase
Events raised by Juju to progress a charm’s lifecycle.
Hooks are callback methods of a charm class (a subclass of
CharmBase
) that are invoked in response to events raised by Juju. These callback methods are the means by which a charm governs the lifecycle of its application.The
HookEvent
class is the base of a type hierarchy of events related to the charm’s lifecycle.HookEvent
subtypes are grouped into the following categoriesCore lifecycle events
Relation events
Storage events
Metric events
-
class
ops.charm.
ActionEvent
(handle)[source]¶ Bases:
ops.framework.EventBase
Events raised by Juju when an administrator invokes a Juju Action.
This class is the data type of events triggered when an administrator invokes a Juju Action. Callbacks bound to these events may be used for responding to the administrator’s Juju Action request.
To read the parameters for the action, see the instance variable
params
. To respond with the result of the action, callset_results()
. To add progress messages that are visible as the action is progressing uselog()
.-
params
¶ The parameters passed to the action.
-
defer
()[source]¶ Action events are not deferable like other events.
This is because an action runs synchronously and the administrator is waiting for the result.
-
restore
(snapshot)[source]¶ Used by the operator framework to record the action.
Not meant to be called directly by charm code.
-
set_results
(results)[source]¶ Report the result of the action.
- Parameters
results (Mapping) – The result of the action as a Dict
- Return type
-
-
class
ops.charm.
InstallEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered when a charm is installed.
This event is triggered at the beginning of a charm’s lifecycle. Any associated callback method should be used to perform one-time setup operations, such as installing prerequisite software.
-
class
ops.charm.
StartEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered immediately after first configuation change.
This event is triggered immediately after the first
ConfigChangedEvent
. Callback methods bound to the event should be used to ensure that the charm’s software is in a running state. Note that the charm’s software should be configured so as to persist in this state through reboots without further intervention on Juju’s part.
-
class
ops.charm.
StopEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered when a charm is shut down.
This event is triggered when an application’s removal is requested by the client. The event fires immediately before the end of the unit’s destruction sequence. Callback methods bound to this event should be used to ensure that the charm’s software is not running, and that it will not start again on reboot.
-
class
ops.charm.
RemoveEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered when a unit is about to be terminated.
This event fires prior to Juju removing the charm and terminating its unit.
-
class
ops.charm.
ConfigChangedEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered when a configuration change is requested.
This event fires in several different situations.
immediately after the
install
event.after a
relation is created
.after a
leader is elected
.after changing charm configuration using the GUI or command line interface
when the charm
starts
.when a new unit
joins a relation
.when there is a
change to an existing relation
.
Any callback method bound to this event cannot assume that the software has already been started; it should not start stopped software, but should (if appropriate) restart running software to take configuration changes into account.
-
class
ops.charm.
UpdateStatusEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered by a status update request from Juju.
This event is periodically triggered by Juju so that it can provide constant feedback to the administrator about the status of the application the charm is modeling. Any callback method bound to this event should determine the “health” of the application and set the status appropriately.
The interval between
update-status
events can be configured model-wide, e.g.juju model-config update-status-hook-interval=1m
.
-
class
ops.charm.
UpgradeCharmEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered by request to upgrade the charm.
This event will be triggered when an administrator executes
juju upgrade-charm
. The event fires after Juju has unpacked the upgraded charm code, and so this event will be handled by the callback method bound to the event in the new codebase. The associated callback method is invoked provided there is no existing error state. The callback method should be used to reconcile current state written by an older version of the charm into whatever form that is needed by the current charm version.
-
class
ops.charm.
PreSeriesUpgradeEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered to prepare a unit for series upgrade.
This event triggers when an administrator executes
juju upgrade-series MACHINE prepare
. The event will fire for each unit that is running on the specified machine. Any callback method bound to this event must prepare the charm for an upgrade to the series. This may include things like exporting database content to a version neutral format, or evacuating running instances to other machines.It can be assumed that only after all units on a machine have executed the callback method associated with this event, the administrator will initiate steps to actually upgrade the series. After the upgrade has been completed, the
PostSeriesUpgradeEvent
will fire.
-
class
ops.charm.
PostSeriesUpgradeEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered after a series upgrade.
This event is triggered after the administrator has done a distribution upgrade (or rolled back and kept the same series). It is called in response to
juju upgrade-series MACHINE complete
. Associated charm callback methods are expected to do whatever steps are necessary to reconfigure their applications for the new series. This may include things like populating the upgraded version of a database. Note however charms are expected to check if the series has actually changed or whether it was rolled back to the original series.
-
class
ops.charm.
LeaderElectedEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered when a new leader has been elected.
Juju will trigger this event when a new leader unit is chosen for a given application.
This event fires at least once after Juju selects a leader unit. Callback methods bound to this event may take any action required for the elected unit to assert leadership. Note that only the elected leader unit will receive this event.
-
class
ops.charm.
LeaderSettingsChangedEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered when leader changes any settings.
DEPRECATED NOTICE
This event has been deprecated in favor of using a Peer relation, and having the leader set a value in the Application data bag for that peer relation. (see
RelationChangedEvent
).
-
class
ops.charm.
CollectMetricsEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Event triggered by Juju to collect metrics.
Juju fires this event every five minutes for the lifetime of the unit. Callback methods bound to this event may use the
add_metrics()
method of this class to send measurements to Juju.Note that associated callback methods are currently sandboxed in how they can interact with Juju.
-
add_metrics
(metrics, labels=None)[source]¶ Record metrics that have been gathered by the charm for this unit.
- Parameters
metrics (Mapping) – A collection of {key: float} pairs that contains the metrics that have been gathered
labels (Mapping) – {key:value} strings that can be applied to the metrics that are being gathered
- Return type
-
-
class
ops.charm.
RelationEvent
(handle, relation, app=None, unit=None)[source]¶ Bases:
ops.charm.HookEvent
A base class representing the various relation lifecycle events.
Relation lifecycle events are generated when application units participate in relations. Units can only participate in relations after they have been “started”, and before they have been “stopped”. Within that time window, the unit may participate in several different relations at a time, including multiple relations with the same name.
-
app
¶ The remote
Application
that has triggered this event
-
unit
¶ The remote unit that has triggered this event. This may be
None
if the relation event was triggered as anApplication
level event
-
-
class
ops.charm.
RelationCreatedEvent
(handle, relation, app=None, unit=None)[source]¶ Bases:
ops.charm.RelationEvent
Event triggered when a new relation is created.
This is triggered when a new relation to another app is added in Juju. This can occur before units for those applications have started. All existing relations should be established before start.
-
class
ops.charm.
RelationJoinedEvent
(handle, relation, app=None, unit=None)[source]¶ Bases:
ops.charm.RelationEvent
Event triggered when a new unit joins a relation.
This event is triggered whenever a new unit of a related application joins the relation. The event fires only when that remote unit is first observed by the unit. Callback methods bound to this event may set any local unit settings that can be determined using no more than the name of the joining unit and the remote
private-address
setting, which is always available when the relation is created and is by convention not deleted.
-
class
ops.charm.
RelationChangedEvent
(handle, relation, app=None, unit=None)[source]¶ Bases:
ops.charm.RelationEvent
Event triggered when relation data changes.
This event is triggered whenever there is a change to the data bucket for a related application or unit. Look at
event.relation.data[event.unit/app]
to see the new information, whereevent
is the event object passed to the callback method bound to this event.This event always fires once, after
RelationJoinedEvent
, and will subsequently fire whenever that remote unit changes its settings for the relation. Callback methods bound to this event should be the only ones that rely on remote relation settings. They should not error if the settings are incomplete, since it can be guaranteed that when the remote unit or application changes its settings, the event will fire again.The settings that may be queried, or set, are determined by the relation’s interface.
-
class
ops.charm.
RelationDepartedEvent
(handle, relation, app=None, unit=None)[source]¶ Bases:
ops.charm.RelationEvent
Event triggered when a unit leaves a relation.
This is the inverse of the
RelationJoinedEvent
, representing when a unit is leaving the relation (the unit is being removed, the app is being removed, the relation is being removed). It is fired once for each unit that is going away.When the remote unit is known to be leaving the relation, this will result in the
RelationChangedEvent
firing at least once, after which theRelationDepartedEvent
will fire. TheRelationDepartedEvent
will fire once only. Once theRelationDepartedEvent
has fired no furtherRelationChangedEvent
will fire.Callback methods bound to this event may be used to remove all references to the departing remote unit, because there’s no guarantee that it’s still part of the system; it’s perfectly probable (although not guaranteed) that the system running that unit has already shut down.
Once all callback methods bound to this event have been run for such a relation, the unit agent will fire the
RelationBrokenEvent
.
-
class
ops.charm.
RelationBrokenEvent
(handle, relation, app=None, unit=None)[source]¶ Bases:
ops.charm.RelationEvent
Event triggered when a relation is removed.
If a relation is being removed (
juju remove-relation
orjuju remove-application
), once all the units have been removed, this event will fire to signal that the relationship has been fully terminated.The event indicates that the current relation is no longer valid, and that the charm’s software must be configured as though the relation had never existed. It will only be called after every callback method bound to
RelationDepartedEvent
has been run. If a callback method bound to this event is being executed, it is gauranteed that no remote units are currently known locally.
-
class
ops.charm.
StorageEvent
(handle)[source]¶ Bases:
ops.charm.HookEvent
Base class representing storage-related events.
Juju can provide a variety of storage types to a charms. The charms can define several different types of storage that are allocated from Juju. Changes in state of storage trigger sub-types of
StorageEvent
.
-
class
ops.charm.
StorageAttachedEvent
(handle)[source]¶ Bases:
ops.charm.StorageEvent
Event triggered when new storage becomes available.
This event is triggered when new storage is available for the charm to use.
Callback methods bound to this event allow the charm to run code when storage has been added. Such methods will be run before the
InstallEvent
fires, so that the installation routine may use the storage. The name prefix of this hook will depend on the storage key defined in themetadata.yaml
file.
-
class
ops.charm.
StorageDetachingEvent
(handle)[source]¶ Bases:
ops.charm.StorageEvent
Event triggered prior to removal of storage.
This event is triggered when storage a charm has been using is going away.
Callback methods bound to this event allow the charm to run code before storage is removed. Such methods will be run before storage is detached, and always before the
StopEvent
fires, thereby allowing the charm to gracefully release resources before they are removed and before the unit terminates. The name prefix of the hook will depend on the storage key defined in themetadata.yaml
file.
-
class
ops.charm.
CharmEvents
(parent=None, key=None)[source]¶ Bases:
ops.framework.ObjectEvents
Events generated by Juju pertaining to application lifecycle.
This class is used to create an event descriptor (
self.on
) attribute for a charm class that inherits fromCharmBase
. The event descriptor may be used to set up event handlers for corresponding events.By default the following events will be provided through
CharmBase
:self.on.install self.on.start self.on.remove self.on.update_status self.on.config_changed self.on.upgrade_charm self.on.pre_series_upgrade self.on.post_series_upgrade self.on.leader_elected self.on.collect_metrics
In addition to these, depending on the charm’s metadata (
metadata.yaml
), named relation and storage events may also be defined. These named events are created byCharmBase
using charm metadata. The named events may be accessed asself.on[<name>].<relation_or_storage_event>
-
install
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
start
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
stop
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
remove
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
update_status
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
config_changed
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
upgrade_charm
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
pre_series_upgrade
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
post_series_upgrade
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
leader_elected
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
leader_settings_changed
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
collect_metrics
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
-
class
ops.charm.
CharmBase
(framework, key=None)[source]¶ Bases:
ops.framework.Object
Base class that represents the charm overall.
CharmBase
is used to create a charm. This is done by inheriting fromCharmBase
and customising the sub class as required. So to create your own charm, sayMyCharm
, define a charm class and set up the required event handlers (“hooks”) in its constructor:import logging from ops.charm import CharmBase from ops.main import main logger = logging.getLogger(__name__) def MyCharm(CharmBase): def __init__(self, *args): logger.debug('Initializing Charm') super().__init__(*args) self.framework.observe(self.on.config_changed, self._on_config_changed) self.framework.observe(self.on.stop, self._on_stop) # ... if __name__ == "__main__": main(MyCharm)
As shown in the example above, a charm class is instantiated by
main()
rather than charm authors directly instantiating a charm.- Parameters
framework (ops.framework.Framework) – The framework responsible for managing the Model and events for this charm.
key (Optional) – Ignored; will remove after deprecation period of the signature change.
-
on
¶ Used to set up event handlers; see
CharmEvents
.
-
property
app
¶ Application that this unit is part of.
-
property
unit
¶ Unit that this execution is responsible for.
-
property
meta
¶ Metadata of this charm.
-
property
charm_dir
¶ Root directory of the charm as it is running.
-
property
config
¶ A mapping containing the charm’s config and current values.
-
class
ops.charm.
CharmMeta
(raw={}, actions_raw={})[source]¶ Bases:
object
Object containing the metadata for the charm.
This is read from
metadata.yaml
and/oractions.yaml
. Generally charms will define this information, rather than reading it at runtime. This class is mostly for the framework to understand what the charm has defined.The
maintainers
,tags
,terms
,series
, andextra_bindings
attributes are all lists of strings. Therequires
,provides
,peers
,relations
,storages
,resources
, andpayloads
attributes are all mappings of names to instances of the respectiveRelationMeta
,StorageMeta
,ResourceMeta
, orPayloadMeta
.The
relations
attribute is a convenience accessor which includes all of therequires
,provides
, andpeers
RelationMeta
items. If needed, the role of the relation definition can be obtained from itsrole
attribute.-
name
¶ The name of this charm
-
summary
¶ Short description of what this charm does
-
description
¶ Long description for this charm
-
maintainers
¶ A list of strings of the email addresses of the maintainers of this charm.
Charm store tag metadata for categories associated with this charm.
-
terms
¶ Charm store terms that should be agreed to before this charm can be deployed. (Used for things like licensing issues.)
-
series
¶ The list of supported OS series that this charm can support. The first entry in the list is the default series that will be used by deploy if no other series is requested by the user.
-
subordinate
¶ True/False whether this charm is intended to be used as a subordinate charm.
-
min_juju_version
¶ If supplied, indicates this charm needs features that are not available in older versions of Juju.
-
requires
¶ A dict of {name:
RelationMeta
} for each ‘requires’ relation.
-
provides
¶ A dict of {name:
RelationMeta
} for each ‘provides’ relation.
-
peers
¶ A dict of {name:
RelationMeta
} for each ‘peer’ relation.
-
relations
¶ A dict containing all
RelationMeta
attributes (merged from other sections)
-
storages
¶ A dict of {name:
StorageMeta
} for each defined storage.
-
resources
¶ A dict of {name:
ResourceMeta
} for each defined resource.
-
payloads
¶ A dict of {name:
PayloadMeta
} for each defined payload.
-
extra_bindings
¶ A dict of additional named bindings that a charm can use for network configuration.
-
actions
¶ A dict of {name:
ActionMeta
} for actions that the charm has defined.
- Parameters
-
-
class
ops.charm.
RelationRole
(value)[source]¶ Bases:
enum.Enum
An annotation for a charm’s role in a relation.
For each relation a charm’s role may be
A Peer
A service consumer in the relation (‘requires’)
A service provider in the relation (‘provides’)
-
peer
= 'peer'¶
-
requires
= 'requires'¶
-
provides
= 'provides'¶
-
class
ops.charm.
RelationMeta
(role, relation_name, raw)[source]¶ Bases:
object
Object containing metadata about a relation definition.
Should not be constructed directly by charm code. Is gotten from one of
CharmMeta.peers
,CharmMeta.requires
,CharmMeta.provides
, orCharmMeta.relations
.- Parameters
role (ops.charm.RelationRole) –
relation_name (str) –
raw (dict) –
-
role
¶ This is
RelationRole
; one of peer/requires/provides
-
relation_name
¶ Name of this relation from metadata.yaml
-
interface_name
¶ Optional definition of the interface protocol.
-
scope
¶ “global” or “container” scope based on how the relation should be used.
-
class
ops.charm.
StorageMeta
(name, raw)[source]¶ Bases:
object
Object containing metadata about a storage definition.
-
storage_name
¶ Name of storage
-
type
¶ Storage type
-
description
¶ A text description of the storage
-
read_only
¶ Whether or not the storage is read only
-
minimum_size
¶ Minimum size of storage
-
location
¶ Mount point of storage
-
multiple_range
¶ Range of numeric qualifiers when multiple storage units are used
-
-
class
ops.charm.
ResourceMeta
(name, raw)[source]¶ Bases:
object
Object containing metadata about a resource definition.
-
resource_name
¶ Name of resource
-
filename
¶ Name of file
-
description
¶ A text description of resource
-
ops.framework module¶
The Operator Framework infrastructure.
-
class
ops.framework.
Handle
(parent, kind, key)[source]¶ Bases:
object
Handle defines a name for an object in the form of a hierarchical path.
The provided parent is the object (or that object’s handle) that this handle sits under, or None if the object identified by this handle stands by itself as the root of its own hierarchy.
The handle kind is a string that defines a namespace so objects with the same parent and kind will have unique keys.
The handle key is a string uniquely identifying the object. No other objects under the same parent and kind may have the same key.
-
property
parent
¶ Return own parent handle.
-
property
kind
¶ Return the handle’s kind.
-
property
key
¶ Return the handle’s key.
-
property
path
¶ Return the handle’s path.
-
property
-
class
ops.framework.
EventBase
(handle)[source]¶ Bases:
object
The base for all the different Events.
Inherit this and override ‘snapshot’ and ‘restore’ methods to build a custom event.
-
defer
()[source]¶ Defer the event to the future.
Deferring an event from a handler puts that handler into a queue, to be called again the next time the charm is invoked. This invocation may be the result of an action, or any event other than metric events. The queue of events will be dispatched before the new event is processed.
From the above you may deduce, but it’s important to point out:
defer()
does not interrupt the execution of the current event handler. In almost all cases, a call todefer()
should be followed by an explicitreturn
from the handler;the re-execution of the deferred event handler starts from the top of the handler method (not where defer was called);
only the handlers that actually called
defer()
are called again (that is: despite talking about “deferring an event” it is actually the handler/event combination that is deferred); andany deferred events get processed before the event (or action) that caused the current invocation of the charm.
The general desire to call
defer()
happens when some precondition isn’t yet met. However, care should be exercised as to whether it is better to defer this event so that you see it again, or whether it is better to just wait for the event that indicates the precondition has been met.For example, if
config-changed
is fired, and you are waiting for different config, there is no reason to defer the event because there will be a differentconfig-changed
event when the config actually changes, rather than checking to see if maybe config has changed prior to every other event that occurs.Similarly, if you need 2 events to occur before you are ready to proceed (say event A and B). When you see event A, you could chose to
defer()
it because you haven’t seen B yet. However, that leads to:event A fires, calls defer()
event B fires, event A handler is called first, still hasn’t seen B happen, so is deferred again. Then B happens, which progresses since it has seen A.
At some future time, event C happens, which also checks if A can proceed.
-
-
class
ops.framework.
EventSource
(event_type)[source]¶ Bases:
object
EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
class
ops.framework.
BoundEvent
(emitter, event_type, event_kind)[source]¶ Bases:
object
Event bound to an Object.
-
class
ops.framework.
HandleKind
[source]¶ Bases:
object
Helper descriptor to define the Object.handle_kind field.
The handle_kind for an object defaults to its type name, but it may be explicitly overridden if desired.
-
class
ops.framework.
Object
(parent, key)[source]¶ Bases:
object
Base class of all the charm-related objects.
-
handle_kind
¶ Helper descriptor to define the Object.handle_kind field.
The handle_kind for an object defaults to its type name, but it may be explicitly overridden if desired.
-
property
model
¶ Shortcut for more simple access the model.
-
-
class
ops.framework.
ObjectEvents
(parent=None, key=None)[source]¶ Bases:
ops.framework.Object
Convenience type to allow defining .on attributes at class level.
-
handle_kind
= 'on'¶
-
classmethod
define_event
(event_kind, event_type)[source]¶ Define an event on this type at runtime.
cls: a type to define an event on.
- event_kind: an attribute name that will be used to access the
event. Must be a valid python identifier, not be a keyword or an existing attribute.
event_type: a type of the event to define.
-
-
class
ops.framework.
PrefixedEvents
(emitter, key)[source]¶ Bases:
object
Events to be found in all events using a specific prefix.
-
class
ops.framework.
PreCommitEvent
(handle)[source]¶ Bases:
ops.framework.EventBase
Events that will be emited first on commit.
-
class
ops.framework.
CommitEvent
(handle)[source]¶ Bases:
ops.framework.EventBase
Events that will be emited second on commit.
-
class
ops.framework.
FrameworkEvents
(parent=None, key=None)[source]¶ Bases:
ops.framework.ObjectEvents
Manager of all framework events.
-
pre_commit
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
commit
¶ EventSource wraps an event type with a descriptor to facilitate observing and emitting.
It is generally used as:
- class SomethingHappened(EventBase):
pass
- class SomeObject(Object):
something_happened = EventSource(SomethingHappened)
With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent and may be used to emit and observe the event.
-
-
exception
ops.framework.
NoTypeError
(handle_path)[source]¶ Bases:
Exception
No class to hold it was found when restoring an event.
-
class
ops.framework.
Framework
(storage, charm_dir, meta, model)[source]¶ Bases:
ops.framework.Object
Main interface to from the Charm to the Operator Framework internals.
-
on
¶ Manager of all framework events.
-
charm_dir
= None¶
-
meta
= None¶
-
model
= None¶
-
set_breakpointhook
()[source]¶ Hook into sys.breakpointhook so the builtin breakpoint() works as expected.
This method is called by
main
, and is not intended to be called by users of the framework itself outside of perhaps some testing scenarios.It returns the old value of sys.excepthook.
The breakpoint function is a Python >= 3.7 feature.
This method was added in ops 1.0; before that, it was done as part of the Framework’s __init__.
-
save_snapshot
(value)[source]¶ Save a persistent snapshot of the provided value.
The provided value must implement the following interface:
value.handle = Handle(…) value.snapshot() => {…} # Simple builtin types only. value.restore(snapshot) # Restore custom state from prior snapshot.
-
observe
(bound_event, observer)[source]¶ Register observer to be called when bound_event is emitted.
The bound_event is generally provided as an attribute of the object that emits the event, and is created in this style:
class SomeObject: something_happened = Event(SomethingHappened)
That event may be observed as:
framework.observe(someobj.something_happened, self._on_something_happened)
- Raises
RuntimeError – if bound_event or observer are the wrong type.
- Parameters
bound_event (ops.framework.BoundEvent) –
observer (method) –
-
reemit
()[source]¶ Reemit previously deferred events to the observers that deferred them.
Only the specific observers that have previously deferred the event will be notified again. Observers that asked to be notified about events after it’s been first emitted won’t be notified, as that would mean potentially observing events out of order.
-
breakpoint
(name=None)[source]¶ Add breakpoint, optionally named, at the place where this method is called.
For the breakpoint to be activated the JUJU_DEBUG_AT environment variable must be set to “all” or to the specific name parameter provided, if any. In every other situation calling this method does nothing.
The framework also provides a standard breakpoint named “hook”, that will stop execution when a hook event is about to be handled.
For those reasons, the “all” and “hook” breakpoint names are reserved.
-
-
class
ops.framework.
StoredStateData
(parent, attr_name)[source]¶ Bases:
ops.framework.Object
Manager of the stored data.
-
class
ops.framework.
BoundStoredState
(parent, attr_name)[source]¶ Bases:
object
Stored state data bound to a specific Object.
-
class
ops.framework.
StoredState
[source]¶ Bases:
object
A class used to store data the charm needs persisted across invocations.
Example:
class MyClass(Object): _stored = StoredState()
Instances of MyClass can transparently save state between invocations by setting attributes on _stored. Initial state should be set with set_default on the bound object, that is:
class MyClass(Object): _stored = StoredState() def __init__(self, parent, key): super().__init__(parent, key) self._stored.set_default(seen=set()) self.framework.observe(self.on.seen, self._on_seen) def _on_seen(self, event): self._stored.seen.add(event.uuid)
-
class
ops.framework.
StoredDict
(stored_data, under)[source]¶ Bases:
collections.abc.MutableMapping
A dict-like object that uses the StoredState as backend.
-
class
ops.framework.
StoredList
(stored_data, under)[source]¶ Bases:
collections.abc.MutableSequence
A list-like object that uses the StoredState as backend.
-
class
ops.framework.
StoredSet
(stored_data, under)[source]¶ Bases:
collections.abc.MutableSet
A set-like object that uses the StoredState as backend.
ops.jujuversion module¶
A helper to work with the Juju version.
-
class
ops.jujuversion.
JujuVersion
(version)[source]¶ Bases:
object
Helper to work with the Juju version.
It knows how to parse the
JUJU_VERSION
environment variable, and exposes different capabilities according to the specific version, allowing also to compare with other versions.-
PATTERN
= '^\n (?P<major>\\d{1,9})\\.(?P<minor>\\d{1,9}) # <major> and <minor> numbers are always there\n ((?:\\.|-(?P<tag>[a-z]+))(?P<patch>\\d{1,9}))? # sometimes with .<patch> or -<tag><patch>\n (\\.(?P<build>\\d{1,9}))?$ # and sometimes with a <build> number.\n '¶
-
ops.log module¶
Interface to emit messages to the Juju logging system.
-
class
ops.log.
JujuLogHandler
(model_backend, level=10)[source]¶ Bases:
logging.Handler
A handler for sending logs to Juju via juju-log.
Initializes the instance - basically setting the formatter to None and the filter list to empty.
-
emit
(record)[source]¶ Send the specified logging record to the Juju backend.
This method is not used directly by the Operator Framework code, but by
logging.Handler
itself as part of the logging machinery.
-
-
ops.log.
setup_root_logging
(model_backend, debug=False)[source]¶ Setup python logging to forward messages to juju-log.
By default, logging is set to DEBUG level, and messages will be filtered by Juju. Charmers can also set their own default log level with:
logging.getLogger().setLevel(logging.INFO)
model_backend – a ModelBackend to use for juju-log debug – if True, write logs to stderr as well as to juju-log.
ops.main module¶
Main entry point to the Operator Framework.
-
ops.main.
main
(charm_class, use_juju_for_storage=None)[source]¶ Setup the charm and dispatch the observed event.
The event name is based on the way this executable was called (argv[0]).
- Parameters
charm_class (ops.charm.CharmBase) – your charm class.
use_juju_for_storage (bool) – whether to use controller-side storage. If not specified then kubernetes charms that haven’t previously used local storage and that are running on a new enough Juju default to controller-side storage, otherwise local storage is used.
ops.model module¶
Representations of Juju’s model, application, unit, and other entities.
-
class
ops.model.
Model
(meta, backend)[source]¶ Bases:
object
Represents the Juju Model as seen from this unit.
This should not be instantiated directly by Charmers, but can be accessed as self.model from any class that derives from Object.
- Parameters
meta (ops.charm.CharmMeta) –
backend (_ModelBackend) –
-
property
app
¶ A
Application
that represents the application this unit is a part of.
-
property
relations
¶ Mapping of endpoint to list of
Relation
.Answers the question “what am I currently related to”. See also
get_relation()
.
-
property
config
¶ Return a mapping of config for the current application.
-
property
resources
¶ Access to resources for this charm.
Use
model.resources.fetch(resource_name)
to get the path on disk where the resource can be found.
-
property
pod
¶ Use
model.pod.set_spec
to set the container specification for Kubernetes charms.
-
property
name
¶ Return the name of the Model that this unit is running in.
This is read from the environment variable
JUJU_MODEL_NAME
.
-
get_unit
(unit_name)[source]¶ Get an arbitrary unit by name.
Internally this uses a cache, so asking for the same unit two times will return the same object.
- Parameters
unit_name (str) –
- Return type
-
get_app
(app_name)[source]¶ Get an application by name.
Internally this uses a cache, so asking for the same application two times will return the same object.
- Parameters
app_name (str) –
- Return type
-
get_relation
(relation_name, relation_id=None)[source]¶ Get a specific Relation instance.
If relation_id is not given, this will return the Relation instance if the relation is established only once or None if it is not established. If this same relation is established multiple times the error TooManyRelatedAppsError is raised.
- Parameters
- Raises
TooManyRelatedAppsError – is raised if there is more than one relation to the supplied relation_name and no relation_id was supplied
- Return type
-
get_binding
(binding_key)[source]¶ Get a network space binding.
- Parameters
binding_key (Union[str, Relation]) – The relation name or instance to obtain bindings for.
- Returns
If
binding_key
is a relation name, the method returns the default binding for that relation. If a relation instance is provided, the method first looks up a more specific binding for that specific relation ID, and if none is found falls back to the default binding for the relation name.- Return type
-
class
ops.model.
Application
(name, backend, cache)[source]¶ Bases:
object
Represents a named application in the model.
This might be your application, or might be an application that you are related to. Charmers should not instantiate Application objects directly, but should use
Model.get_app()
if they need a reference to a given application.-
name
¶ The name of this application (eg, ‘mysql’). This name may differ from the name of the charm, if the user has deployed it to a different name.
-
property
status
¶ Used to report or read the status of the overall application.
Can only be read and set by the lead unit of the application.
The status of remote units is always Unknown.
- Raises
RuntimeError – if you try to set the status of another application, or if you try to set the status of this application as a unit that is not the leader.
InvalidStatusError – if you try to set the status to something that is not a
StatusBase
Example:
self.model.app.status = BlockedStatus('I need a human to come help me')
-
-
class
ops.model.
Unit
(name, backend, cache)[source]¶ Bases:
object
Represents a named unit in the model.
This might be your unit, another unit of your application, or a unit of another application that you are related to.
-
name
¶ The name of the unit (eg, ‘mysql/0’)
-
app
¶ The Application the unit is a part of.
-
property
status
¶ Used to report or read the status of a specific unit.
The status of any unit other than yourself is always Unknown.
- Raises
RuntimeError – if you try to set the status of a unit other than yourself.
InvalidStatusError – if you try to set the status to something other than a
StatusBase
Example:
self.model.unit.status = MaintenanceStatus('reconfiguring the frobnicators')
-
is_leader
()[source]¶ Return whether this unit is the leader of its application.
This can only be called for your own unit.
- Returns
True if you are the leader, False otherwise
- Raises
RuntimeError – if called for a unit that is not yourself
- Return type
-
-
class
ops.model.
LazyMapping
[source]¶ Bases:
collections.abc.Mapping
,abc.ABC
Represents a dict that isn’t populated until it is accessed.
Charm authors should generally never need to use this directly, but it forms the basis for many of the dicts that the framework tracks.
-
class
ops.model.
RelationMapping
(relations_meta, our_unit, backend, cache)[source]¶ Bases:
collections.abc.Mapping
Map of relation names to lists of
Relation
instances.
-
class
ops.model.
BindingMapping
(backend)[source]¶ Bases:
object
Mapping of endpoints to network bindings.
Charm authors should not instantiate this directly, but access it via
Model.get_binding()
-
get
(binding_key)[source]¶ Get a specific Binding for an endpoint/relation.
Not used directly by Charm authors. See
Model.get_binding()
- Parameters
- Return type
-
-
class
ops.model.
Binding
(name, relation_id, backend)[source]¶ Bases:
object
Binding to a network space.
-
name
¶ The name of the endpoint this binding represents (eg, ‘db’)
-
property
network
¶ The network information for this binding.
-
-
class
ops.model.
Network
(network_info)[source]¶ Bases:
object
Network space details.
Charm authors should not instantiate this directly, but should get access to the Network definition from
Model.get_binding()
and itsnetwork
attribute.-
interfaces
¶ A list of
NetworkInterface
details. This includes the information about how your application should be configured (eg, what IP addresses should you bind to.) Note that multiple addresses for a single interface are represented as multiple interfaces. (eg,[NetworkInfo('ens1', '10.1.1.1/32'), NetworkInfo('ens1', '10.1.2.1/32'])
)
-
ingress_addresses
¶ A list of
ipaddress.ip_address
objects representing the IP addresses that other units should use to get in touch with you.
-
egress_subnets
¶ A list of
ipaddress.ip_network
representing the subnets that other units will see you connecting from. Due to things like NAT it isn’t always possible to narrow it down to a single address, but when it is clear, the CIDRs will be constrained to a single address. (eg, 10.0.0.1/32)
- Parameters
network_info (dict) – A dict of network information as returned by
network-get
.
-
property
bind_address
¶ A single address that your application should bind() to.
For the common case where there is a single answer. This represents a single address from
interfaces
that can be used to configure where your application should bind() and listen().
-
property
ingress_address
¶ The address other applications should use to connect to your unit.
Due to things like public/private addresses, NAT and tunneling, the address you bind() to is not always the address other people can use to connect() to you. This is just the first address from
ingress_addresses
.
-
-
class
ops.model.
NetworkInterface
(name, address_info)[source]¶ Bases:
object
Represents a single network interface that the charm needs to know about.
Charmers should not instantiate this type directly. Instead use
Model.get_binding()
to get the network information for a given endpoint.-
name
¶ The name of the interface (eg. ‘eth0’, or ‘ens1’)
-
subnet
¶ An
ipaddress.ip_network
representation of the IP for the network interface. This may be a single address (eg ‘10.0.1.2/32’)
-
-
class
ops.model.
Relation
(relation_name, relation_id, is_peer, our_unit, backend, cache)[source]¶ Bases:
object
Represents an established relation between this application and another application.
This class should not be instantiated directly, instead use
Model.get_relation()
orops.charm.RelationEvent.relation
.- Parameters
relation_name (str) –
relation_id (int) –
is_peer (bool) –
our_unit (ops.model.Unit) –
backend (_ModelBackend) –
cache (_ModelCache) –
-
name
¶ The name of the local endpoint of the relation (eg ‘db’)
-
id
¶ The identifier for a particular relation (integer)
-
app
¶ An
Application
representing the remote application of this relation. For peer relations this will be the local application.
-
data
¶ A
RelationData
holding the data buckets for each entity of a relation. Accessed via eg Relation.data[unit][‘foo’]
-
class
ops.model.
RelationData
(relation, our_unit, backend)[source]¶ Bases:
collections.abc.Mapping
Represents the various data buckets of a given relation.
Each unit and application involved in a relation has their own data bucket. Eg:
{entity: RelationDataContent}
where entity can be either aUnit
or aApplication
.Units can read and write their own data, and if they are the leader, they can read and write their application data. They are allowed to read remote unit and application data.
This class should not be created directly. It should be accessed via
Relation.data
- Parameters
relation (ops.model.Relation) –
our_unit (ops.model.Unit) –
backend (_ModelBackend) –
-
class
ops.model.
RelationDataContent
(relation, entity, backend)[source]¶ Bases:
ops.model.LazyMapping
,collections.abc.MutableMapping
Data content of a unit or application in a relation.
-
class
ops.model.
ConfigData
(backend)[source]¶ Bases:
ops.model.LazyMapping
Configuration data.
This class should not be created directly. It should be accessed via
Model.config
.
-
class
ops.model.
StatusBase
(*args, **kwargs)[source]¶ Bases:
object
Status values specific to applications and units.
To access a status by name, see
StatusBase.from_name()
, most use cases will just directly use the child class to indicate their status.Forbid the usage of StatusBase directly.
-
name
= None¶
-
-
class
ops.model.
UnknownStatus
(*args, **kwargs)[source]¶ Bases:
ops.model.StatusBase
The unit status is unknown.
A unit-agent has finished calling install, config-changed and start, but the charm has not called status-set yet.
Forbid the usage of StatusBase directly.
-
name
= 'unknown'¶
-
-
class
ops.model.
ActiveStatus
(*args, **kwargs)[source]¶ Bases:
ops.model.StatusBase
The unit is ready.
The unit believes it is correctly offering all the services it has been asked to offer.
Forbid the usage of StatusBase directly.
-
name
= 'active'¶
-
-
class
ops.model.
BlockedStatus
(*args, **kwargs)[source]¶ Bases:
ops.model.StatusBase
The unit requires manual intervention.
An operator has to manually intervene to unblock the unit and let it proceed.
Forbid the usage of StatusBase directly.
-
name
= 'blocked'¶
-
-
class
ops.model.
MaintenanceStatus
(*args, **kwargs)[source]¶ Bases:
ops.model.StatusBase
The unit is performing maintenance tasks.
The unit is not yet providing services, but is actively doing work in preparation for providing those services. This is a “spinning” state, not an error state. It reflects activity on the unit itself, not on peers or related units.
Forbid the usage of StatusBase directly.
-
name
= 'maintenance'¶
-
-
class
ops.model.
WaitingStatus
(*args, **kwargs)[source]¶ Bases:
ops.model.StatusBase
A unit is unable to progress.
The unit is unable to progress to an active state because an application to which it is related is not running.
Forbid the usage of StatusBase directly.
-
name
= 'waiting'¶
-
-
class
ops.model.
Resources
(names, backend)[source]¶ Bases:
object
Object representing resources for the charm.
- Parameters
names (Iterable[str]) –
backend (_ModelBackend) –
-
class
ops.model.
Pod
(backend)[source]¶ Bases:
object
Represents the definition of a pod spec in Kubernetes models.
Currently only supports simple access to setting the Juju pod spec via
set_spec
.- Parameters
backend (_ModelBackend) –
-
set_spec
(spec, k8s_resources=None)[source]¶ Set the specification for pods that Juju should start in kubernetes.
See juju help-tool pod-spec-set for details of what should be passed.
- Parameters
spec (Mapping) – The mapping defining the pod specification
k8s_resources (Mapping) – Additional kubernetes specific specification.
- Returns
None
-
class
ops.model.
StorageMapping
(storage_names, backend)[source]¶ Bases:
collections.abc.Mapping
Map of storage names to lists of Storage instances.
- Parameters
storage_names (Iterable[str]) –
backend (_ModelBackend) –
-
class
ops.model.
Storage
(storage_name, storage_id, backend)[source]¶ Bases:
object
Represents a storage as defined in metadata.yaml.
-
name
¶ Simple string name of the storage
-
id
¶ The provider id for storage
-
property
location
¶ Return the location of the storage.
-
-
exception
ops.model.
ModelError
[source]¶ Bases:
Exception
Base class for exceptions raised when interacting with the Model.
-
exception
ops.model.
TooManyRelatedAppsError
(relation_name, num_related, max_supported)[source]¶ Bases:
ops.model.ModelError
Raised by
Model.get_relation()
if there is more than one related application.
-
exception
ops.model.
RelationDataError
[source]¶ Bases:
ops.model.ModelError
Raised by
Relation.data[entity][key] = 'foo'
if the data is invalid.This is raised if you’re either trying to set a value to something that isn’t a string, or if you are trying to set a value in a bucket that you don’t have access to. (eg, another application/unit or setting your application data but you aren’t the leader.)
-
exception
ops.model.
RelationNotFoundError
[source]¶ Bases:
ops.model.ModelError
Backend error when querying juju for a given relation and that relation doesn’t exist.
-
exception
ops.model.
InvalidStatusError
[source]¶ Bases:
ops.model.ModelError
Raised if trying to set an Application or Unit status to something invalid.
ops.testing module¶
Infrastructure to build unittests for Charms using the Operator Framework.
-
class
ops.testing.
Harness
(charm_cls, *, meta=None, actions=None, config=None)[source]¶ Bases:
object
This class represents a way to build up the model that will drive a test suite.
The model that is created is from the viewpoint of the charm that you are testing.
Example:
harness = Harness(MyCharm) # Do initial setup here relation_id = harness.add_relation('db', 'postgresql') # Now instantiate the charm to see events as the model changes harness.begin() harness.add_relation_unit(relation_id, 'postgresql/0') harness.update_relation_data(relation_id, 'postgresql/0', {'key': 'val'}) # Check that charm has properly handled the relation_joined event for postgresql/0 self.assertEqual(harness.charm. ...)
- Parameters
charm_cls (Type[ops.charm.CharmBase]) – The Charm class that you’ll be testing.
meta (Optional[Union[str, TextIO]]) – charm.CharmBase is a A string or file-like object containing the contents of metadata.yaml. If not supplied, we will look for a ‘metadata.yaml’ file in the parent directory of the Charm, and if not found fall back to a trivial ‘name: test-charm’ metadata.
actions (Optional[Union[str, TextIO]]) – A string or file-like object containing the contents of actions.yaml. If not supplied, we will look for a ‘actions.yaml’ file in the parent directory of the Charm.
config (Optional[Union[str, TextIO]]) – A string or file-like object containing the contents of config.yaml. If not supplied, we will look for a ‘config.yaml’ file in the parent directory of the Charm.
-
property
charm
¶ Return the instance of the charm class that was passed to __init__.
Note that the Charm is not instantiated until you have called
begin()
.
-
property
framework
¶ Return the Framework that is being driven by this Harness.
-
begin
()[source]¶ Instantiate the Charm and start handling events.
Before calling
begin()
, there is no Charm instance, so changes to the Model won’t emit events. You must callbegin()
beforecharm
is valid.- Return type
-
begin_with_initial_hooks
()[source]¶ Called when you want the Harness to fire the same hooks that Juju would fire at startup.
This triggers install, relation-created, config-changed, start, and any relation-joined hooks. Based on what relations have been defined before you called begin(). Note that all of these are fired before returning control to the test suite, so if you want to introspect what happens at each step, you need to fire them directly (eg Charm.on.install.emit()).
To use this with all the normal hooks, you should instantiate the harness, setup any relations that you want active when the charm starts, and then call this method.
Example:
harness = Harness(MyCharm) # Do initial setup here relation_id = harness.add_relation('db', 'postgresql') harness.add_relation_unit(relation_id, 'postgresql/0') harness.update_relation_data(relation_id, 'postgresql/0', {'key': 'val'}) harness.set_leader(True) harness.update_config({'initial': 'config'}) harness.begin_with_initial_hooks() # This will cause # install, db-relation-created('postgresql'), leader-elected, config-changed, start # db-relation-joined('postrgesql/0'), db-relation-changed('postgresql/0') # To be fired.
- Return type
-
cleanup
()[source]¶ Called by your test infrastructure to cleanup any temporary directories/files/etc.
Currently this only needs to be called if you test with resources. But it is reasonable to always include a testcase.addCleanup(harness.cleanup) just in case.
- Return type
-
add_oci_resource
(resource_name, contents=None)[source]¶ Add oci resources to the backend.
This will register an oci resource and create a temporary file for processing metadata about the resource. A default set of values will be used for all the file contents unless a specific contents dict is provided.
-
add_resource
(resource_name, content)[source]¶ Add content for a resource to the backend.
This will register the content, so that a call to Model.resources.fetch(resource_name) will return a path to a file containing that content.
-
disable_hooks
()[source]¶ Stop emitting hook events when the model changes.
This can be used by developers to stop changes to the model from emitting events that the charm will react to. Call
enable_hooks()
to re-enable them.- Return type
-
enable_hooks
()[source]¶ Re-enable hook events from charm.on when the model is changed.
By default hook events are enabled once you call
begin()
, but if you have useddisable_hooks()
, this can be used to enable them again.- Return type
-
hooks_disabled
()[source]¶ A context manager to run code with hooks disabled.
Example:
with harness.hooks_disabled(): # things in here don't fire events harness.set_leader(True) harness.update_config(unset=['foo', 'bar']) # things here will again fire events
-
add_relation
(relation_name, remote_app)[source]¶ Declare that there is a new relation between this app and remote_app.
-
add_relation_unit
(relation_id, remote_unit_name)[source]¶ Add a new unit to a relation.
Example:
rel_id = harness.add_relation('db', 'postgresql') harness.add_relation_unit(rel_id, 'postgresql/0')
This will trigger a relation_joined event. This would naturally be followed by a relation_changed event, which you can trigger with
update_relation_data()
. This separation is artificial in the sense that Juju will always fire the two, but is intended to make testing relations and their data bags slightly more natural.
-
get_relation_data
(relation_id, app_or_unit)[source]¶ Get the relation data bucket for a single app or unit in a given relation.
This ignores all of the safety checks of who can and can’t see data in relations (eg, non-leaders can’t read their own application’s relation data because there are no events that keep that data up-to-date for the unit).
-
get_pod_spec
()[source]¶ Return the content of the pod spec as last set by the charm.
This returns both the pod spec and any k8s_resources that were supplied. See the signature of Model.pod.set_spec
- Return type
-
set_model_name
(name)[source]¶ Set the name of the Model that this is representing.
This cannot be called once begin() has been called. But it lets you set the value that will be returned by Model.name.
-
update_relation_data
(relation_id, app_or_unit, key_values)[source]¶ Update the relation data for a given unit or application in a given relation.
This also triggers the relation_changed event for this relation_id.