Data Platform Libs

Canonical
Databases

Architecture:

Base version:

Channel	Revision	Published	Runs on
latest/stable	54	01 Nov 2023	Ubuntu 22.04 Ubuntu 20.04
latest/stable	2	21 Jul 2022	Ubuntu 22.04 Ubuntu 20.04
latest/candidate	54	01 Nov 2023	Ubuntu 22.04
latest/edge	81	27 Sep 2024	Ubuntu 22.04 Ubuntu 20.04
latest/edge	9	21 Oct 2022	Ubuntu 22.04 Ubuntu 20.04

Learn to deploy on juju >

Platform:

22.04 20.04

charms.data_platform_libs.v0.data_interfaces

Docstrings Source code
- Fetch library
  
  charmcraft fetch-lib charms.data_platform_libs.v0.data_interfaces
  Download data_interfaces.py
- 27 Sep 2024
- Library version 0.40

Library to manage the relation for the data-platform products.

This library contains the Requires and Provides classes for handling the relation between an application and multiple managed application supported by the data-team: MySQL, Postgresql, MongoDB, Redis, and Kafka.

Database (MySQL, Postgresql, MongoDB, and Redis)

Requires Charm

This library is a uniform interface to a selection of common database metadata, with added custom events that add convenience to database management, and methods to consume the application related data.

Following an example of using the DatabaseCreatedEvent, in the context of the application charm code:


from charms.data_platform_libs.v0.data_interfaces import (
    DatabaseCreatedEvent,
    DatabaseRequires,
)

class ApplicationCharm(CharmBase):
    # Application charm that connects to database charms.

    def __init__(self, *args):
        super().__init__(*args)

        # Charm events defined in the database requires charm library.
        self.database = DatabaseRequires(self, relation_name="database", database_name="database")
        self.framework.observe(self.database.on.database_created, self._on_database_created)

    def _on_database_created(self, event: DatabaseCreatedEvent) -> None:
        # Handle the created database

        # Create configuration file for app
        config_file = self._render_app_config_file(
            event.username,
            event.password,
            event.endpoints,
        )

        # Start application with rendered configuration
        self._start_application(config_file)

        # Set active status
        self.unit.status = ActiveStatus("received database credentials")

As shown above, the library provides some custom events to handle specific situations, which are listed below:

database_created: event emitted when the requested database is created.
endpoints_changed: event emitted when the read/write endpoints of the database have changed.
read_only_endpoints_changed: event emitted when the read-only endpoints of the database have changed. Event is not triggered if read/write endpoints changed too.

If it is needed to connect multiple database clusters to the same relation endpoint the application charm can implement the same code as if it would connect to only one database cluster (like the above code example).

To differentiate multiple clusters connected to the same relation endpoint the application charm can use the name of the remote application:


def _on_database_created(self, event: DatabaseCreatedEvent) -> None:
    # Get the remote app name of the cluster that triggered this event
    cluster = event.relation.app.name

It is also possible to provide an alias for each different database cluster/relation.

So, it is possible to differentiate the clusters in two ways. The first is to use the remote application name, i.e., event.relation.app.name, as above.

The second way is to use different event handlers to handle each cluster events. The implementation would be something like the following code:


from charms.data_platform_libs.v0.data_interfaces import (
    DatabaseCreatedEvent,
    DatabaseRequires,
)

class ApplicationCharm(CharmBase):
    # Application charm that connects to database charms.

    def __init__(self, *args):
        super().__init__(*args)

        # Define the cluster aliases and one handler for each cluster database created event.
        self.database = DatabaseRequires(
            self,
            relation_name="database",
            database_name="database",
            relations_aliases = ["cluster1", "cluster2"],
        )
        self.framework.observe(
            self.database.on.cluster1_database_created, self._on_cluster1_database_created
        )
        self.framework.observe(
            self.database.on.cluster2_database_created, self._on_cluster2_database_created
        )

    def _on_cluster1_database_created(self, event: DatabaseCreatedEvent) -> None:
        # Handle the created database on the cluster named cluster1

        # Create configuration file for app
        config_file = self._render_app_config_file(
            event.username,
            event.password,
            event.endpoints,
        )
        ...

    def _on_cluster2_database_created(self, event: DatabaseCreatedEvent) -> None:
        # Handle the created database on the cluster named cluster2

        # Create configuration file for app
        config_file = self._render_app_config_file(
            event.username,
            event.password,
            event.endpoints,
        )
        ...

When it's needed to check whether a plugin (extension) is enabled on the PostgreSQL charm, you can use the is_postgresql_plugin_enabled method. To use that, you need to add the following dependency to your charmcraft.yaml file:


parts:
  charm:
    charm-binary-python-packages:
      - psycopg[binary]

Provider Charm

Following an example of using the DatabaseRequestedEvent, in the context of the database charm code:

from charms.data_platform_libs.v0.data_interfaces import DatabaseProvides

class SampleCharm(CharmBase):

    def __init__(self, *args):
        super().__init__(*args)
        # Charm events defined in the database provides charm library.
        self.provided_database = DatabaseProvides(self, relation_name="database")
        self.framework.observe(self.provided_database.on.database_requested,
            self._on_database_requested)
        # Database generic helper
        self.database = DatabaseHelper()

    def _on_database_requested(self, event: DatabaseRequestedEvent) -> None:
        # Handle the event triggered by a new database requested in the relation
        # Retrieve the database name using the charm library.
        db_name = event.database
        # generate a new user credential
        username = self.database.generate_user()
        password = self.database.generate_password()
        # set the credentials for the relation
        self.provided_database.set_credentials(event.relation.id, username, password)
        # set other variables for the relation event.set_tls("False")

As shown above, the library provides a custom event (database_requested) to handle the situation when an application charm requests a new database to be created. It's preferred to subscribe to this event instead of relation changed event to avoid creating a new database when other information other than a database name is exchanged in the relation databag.

Kafka

This library is the interface to use and interact with the Kafka charm. This library contains custom events that add convenience to manage Kafka, and provides methods to consume the application related data.

Requirer Charm


from charms.data_platform_libs.v0.data_interfaces import (
    BootstrapServerChangedEvent,
    KafkaRequires,
    TopicCreatedEvent,
)

class ApplicationCharm(CharmBase):

    def __init__(self, *args):
        super().__init__(*args)
        self.kafka = KafkaRequires(self, "kafka_client", "test-topic")
        self.framework.observe(
            self.kafka.on.bootstrap_server_changed, self._on_kafka_bootstrap_server_changed
        )
        self.framework.observe(
            self.kafka.on.topic_created, self._on_kafka_topic_created
        )

    def _on_kafka_bootstrap_server_changed(self, event: BootstrapServerChangedEvent):
        # Event triggered when a bootstrap server was changed for this application

        new_bootstrap_server = event.bootstrap_server
        ...

    def _on_kafka_topic_created(self, event: TopicCreatedEvent):
        # Event triggered when a topic was created for this application
        username = event.username
        password = event.password
        tls = event.tls
        tls_ca= event.tls_ca
        bootstrap_server event.bootstrap_server
        consumer_group_prefic = event.consumer_group_prefix
        zookeeper_uris = event.zookeeper_uris
        ...

As shown above, the library provides some custom events to handle specific situations, which are listed below:

topic_created: event emitted when the requested topic is created.
bootstrap_server_changed: event emitted when the bootstrap server have changed.
credential_changed: event emitted when the credentials of Kafka changed.

Provider Charm

Following the previous example, this is an example of the provider charm.

class SampleCharm(CharmBase):

from charms.data_platform_libs.v0.data_interfaces import (
    KafkaProvides,
    TopicRequestedEvent,
)

    def __init__(self, *args):
        super().__init__(*args)

        # Default charm events.
        self.framework.observe(self.on.start, self._on_start)

        # Charm events defined in the Kafka Provides charm library.
        self.kafka_provider = KafkaProvides(self, relation_name="kafka_client")
        self.framework.observe(self.kafka_provider.on.topic_requested, self._on_topic_requested)
        # Kafka generic helper
        self.kafka = KafkaHelper()

    def _on_topic_requested(self, event: TopicRequestedEvent):
        # Handle the on_topic_requested event.

        topic = event.topic
        relation_id = event.relation.id
        # set connection info in the databag relation
        self.kafka_provider.set_bootstrap_server(relation_id, self.kafka.get_bootstrap_server())
        self.kafka_provider.set_credentials(relation_id, username=username, password=password)
        self.kafka_provider.set_consumer_group_prefix(relation_id, ...)
        self.kafka_provider.set_tls(relation_id, "False")
        self.kafka_provider.set_zookeeper_uris(relation_id, ...)

As shown above, the library provides a custom event (topic_requested) to handle the situation when an application charm requests a new topic to be created. It is preferred to subscribe to this event instead of relation changed event to avoid creating a new topic when other information other than a topic name is exchanged in the relation databag.

Index

class DataInterfacesError
class SecretError
class SecretAlreadyExistsError
class SecretsUnavailableError
class SecretsIllegalUpdateError
class IllegalOperationError
class PrematureDataAccessError
def get_encoded_dict( relation, member, field )
def get_encoded_list( relation, member, field )
def set_encoded_field( relation, member, field, value )
def diff( event, bucket )
def leader_only( f )
- def wrapper( self)
def juju_secrets_only( f )
- def wrapper( self)
def dynamic_secrets_only( f )
- def wrapper( self)
def either_static_or_dynamic_secrets( f )
- def wrapper( self)
def legacy_apply_from_version( version )
- def decorator( f)
class Scope
class SecretGroup
class SecretGroupsAggregate
- def __init__( self)
- def __setattr__( self, name, value)
- def groups( self)
- def get_group( self, group)
class CachedSecret
- def __init__( self, model, component, label, secret_uri, legacy_labels)
- def meta( self)
- def add_secret( self, content, relation, label)
- def get_content( self)
- def set_content( self, content)
- def get_info( self)
- def remove( self)
class SecretCache
- def __init__( self, model, component)
- def get( self, label, uri, legacy_labels)
- def add( self, label, content, relation)
- def remove( self, label)
class DataDict
- def __init__( self, relation_data, relation_id)
- def data( self)
- def __setitem__( self, key, item)
- def __getitem__( self, key)
- def __eq__( self, d)
- def __repr__( self)
- def __len__( self)
- def __delitem__( self, key)
- def has_key( self, key)
- def update( self, items)
- def keys( self)
- def values( self)
- def items( self)
- def pop( self, item)
- def __contains__( self, item)
- def __iter__( self)
- def get( self, key, default)
class Data
- def __init__( self, model, relation_name)
- def relations( self)
- def secrets_enabled( self)
- def secret_label_map( self)
- def as_dict( self, relation_id)
- def get_relation( self, relation_name, relation_id)
- def get_secret_uri( self, relation, group)
- def set_secret_uri( self, relation, group, secret_uri)
- def fetch_relation_data( self, relation_ids, fields, relation_name)
- def fetch_relation_field( self, relation_id, field, relation_name)
- def fetch_my_relation_data( self, relation_ids, fields, relation_name)
- def fetch_my_relation_field( self, relation_id, field, relation_name)
- def update_relation_data( self, relation_id, data)
- def delete_relation_data( self, relation_id, fields)
class EventHandlers
- def __init__( self, charm, relation_data, unique_key)
class ProviderData
- def __init__( self, model, relation_name)
- def set_credentials( self, relation_id, username, password)
- def set_tls( self, relation_id, tls)
- def set_tls_ca( self, relation_id, tls_ca)
class RequirerData
- def __init__( self, model, relation_name, extra_user_roles, additional_secret_fields)
- def secret_fields( self)
- def get_secret_uri( self, relation, group)
- def set_secret_uri( self, relation, group, uri)
- def is_resource_created( self, relation_id)
class RequirerEventHandlers
- def __init__( self, charm, relation_data, unique_key)
class DataPeerData
- def __init__( self, model, relation_name, extra_user_roles, additional_secret_fields, additional_secret_group_mapping, secret_field_name, deleted_label)
- def scope( self)
- def secret_label_map( self)
- def static_secret_fields( self)
- def secret_fields( self)
- def current_secret_fields( self)
- def set_secret( self, relation_id, field, value, group_mapping)
- def get_secret( self, relation_id, field, group_mapping)
- def delete_secret( self, relation_id, field, group_mapping)
- def valid_field_pattern( self, field, full_field)
- def fetch_relation_data( self, relation_ids, fields, relation_name)
- def fetch_relation_field( self, relation_id, field, relation_name)
class DataPeerEventHandlers
- def __init__( self, charm, relation_data, unique_key)
class DataPeer
- def __init__( self, charm, relation_name, extra_user_roles, additional_secret_fields, additional_secret_group_mapping, secret_field_name, deleted_label, unique_key)
class DataPeerUnitData
- def __init__( self)
class DataPeerUnit
- def __init__( self, charm, relation_name, extra_user_roles, additional_secret_fields, additional_secret_group_mapping, secret_field_name, deleted_label, unique_key)
class DataPeerOtherUnitData
- def __init__( self, unit)
- def update_relation_data( self, relation_id, data)
- def delete_relation_data( self, relation_id, fields)
class DataPeerOtherUnitEventHandlers
- def __init__( self, charm, relation_data)
class DataPeerOtherUnit
- def __init__( self, unit, charm, relation_name, extra_user_roles, additional_secret_fields, additional_secret_group_mapping, secret_field_name, deleted_label)
class ExtraRoleEvent
- def extra_user_roles( self)
class RelationEventWithSecret
- def secrets_enabled( self)
class AuthenticationEvent
- def username( self)
- def password( self)
- def tls( self)
- def tls_ca( self)
class DatabaseProvidesEvent
- def database( self)
class DatabaseRequestedEvent
- def external_node_connectivity( self)
class DatabaseProvidesEvents
class DatabaseRequiresEvent
- def database( self)
- def endpoints( self)
- def read_only_endpoints( self)
- def replset( self)
- def uris( self)
- def version( self)
class DatabaseCreatedEvent
class DatabaseEndpointsChangedEvent
class DatabaseReadOnlyEndpointsChangedEvent
class DatabaseRequiresEvents
class DatabaseProviderData
- def __init__( self, model, relation_name)
- def set_database( self, relation_id, database_name)
- def set_endpoints( self, relation_id, connection_strings)
- def set_read_only_endpoints( self, relation_id, connection_strings)
- def set_replset( self, relation_id, replset)
- def set_uris( self, relation_id, uris)
- def set_version( self, relation_id, version)
- def set_subordinated( self, relation_id)
class DatabaseProviderEventHandlers
- def __init__( self, charm, relation_data, unique_key)
class DatabaseProvides
- def __init__( self, charm, relation_name)
class DatabaseRequirerData
- def __init__( self, model, relation_name, database_name, extra_user_roles, relations_aliases, additional_secret_fields, external_node_connectivity)
- def is_postgresql_plugin_enabled( self, plugin, relation_index)
class DatabaseRequirerEventHandlers
- def __init__( self, charm, relation_data, unique_key)
class DatabaseRequires
- def __init__( self, charm, relation_name, database_name, extra_user_roles, relations_aliases, additional_secret_fields, external_node_connectivity)
class KafkaProvidesEvent
- def topic( self)
- def consumer_group_prefix( self)
class TopicRequestedEvent
class KafkaProvidesEvents
class KafkaRequiresEvent
- def topic( self)
- def bootstrap_server( self)
- def consumer_group_prefix( self)
- def zookeeper_uris( self)
class TopicCreatedEvent
class BootstrapServerChangedEvent
class KafkaRequiresEvents
class KafkaProviderData
- def __init__( self, model, relation_name)
- def set_topic( self, relation_id, topic)
- def set_bootstrap_server( self, relation_id, bootstrap_server)
- def set_consumer_group_prefix( self, relation_id, consumer_group_prefix)
- def set_zookeeper_uris( self, relation_id, zookeeper_uris)
class KafkaProviderEventHandlers
- def __init__( self, charm, relation_data)
class KafkaProvides
- def __init__( self, charm, relation_name)
class KafkaRequirerData
- def __init__( self, model, relation_name, topic, extra_user_roles, consumer_group_prefix, additional_secret_fields)
- def topic( self)
- def topic( self, value)
class KafkaRequirerEventHandlers
- def __init__( self, charm, relation_data)
class KafkaRequires
- def __init__( self, charm, relation_name, topic, extra_user_roles, consumer_group_prefix, additional_secret_fields)
class OpenSearchProvidesEvent
- def index( self)
class IndexRequestedEvent
class OpenSearchProvidesEvents
class OpenSearchRequiresEvent
class IndexCreatedEvent
class OpenSearchRequiresEvents
class OpenSearchProvidesData
- def __init__( self, model, relation_name)
- def set_index( self, relation_id, index)
- def set_endpoints( self, relation_id, endpoints)
- def set_version( self, relation_id, version)
class OpenSearchProvidesEventHandlers
- def __init__( self, charm, relation_data)
class OpenSearchProvides
- def __init__( self, charm, relation_name)
class OpenSearchRequiresData
- def __init__( self, model, relation_name, index, extra_user_roles, additional_secret_fields)
class OpenSearchRequiresEventHandlers
- def __init__( self, charm, relation_data)
class OpenSearchRequires
- def __init__( self, charm, relation_name, index, extra_user_roles, additional_secret_fields)

Description

Common ancestor for DataInterfaces related exceptions. None

Description

Common ancestor for Secrets related exceptions. None

Description

A secret that was to be added already exists. None

Description

Secrets aren't yet available for Juju version used. None

Description

Secrets aren't yet available for Juju version used. None

Description

To be used when an operation is not allowed to be performed. None

Description

To be raised when the Relation Data may be accessed (written) before protocol init complete. None

Description

Retrieve and decode an encoded field from relation data. None

Description

Retrieve and decode an encoded field from relation data. None

Description

Set an encoded field from relation data. None

Arguments

event

relation changed event.

bucket

bucket of the databag (app or unit)

Returns

a Diff instance containing the added, deleted and changed keys from the event relation databag.

Description

Decorator to ensure that only leader can perform given operation. None

Methods

leader_only. wrapper( self )

Description

Decorator to ensure that certain operations would be only executed on Juju3. None

Methods

juju_secrets_only. wrapper( self )

Description

Decorator to ensure that certain operations would be only executed when NO static secrets are defined. None

Methods

dynamic_secrets_only. wrapper( self )

Description

Decorator to ensure that static and dynamic secrets won't be used in parallel. None

Methods

either_static_or_dynamic_secrets. wrapper( self )

Description

Based on LEGACY_SUPPORT_FROM module variable value, the importer charm may only want to apply legacy solutions starting from a specific LIBPATCH.

NOTE: All 'legacy' functions have to be defined and called in a way that they return None. This results in cleaner and more secure execution flows in case the function may be disabled. This requirement implicitly means that legacy functions change the internal state strictly, don't return information.

Methods

legacy_apply_from_version. decorator( f )

Description

Signature is ensuring None return value. None

Description

Peer relations scope. None

Description

Secret groups specific type. None

Description

Secret groups with option to extend with additional constants. None

Methods

SecretGroupsAggregate. __init__( self )

SecretGroupsAggregate. __setattr__( self , name , value )

Description

Setting internal constants. None

SecretGroupsAggregate. groups( self )

Description

Return the list of stored SecretGroups. None

SecretGroupsAggregate. get_group( self , group: str )

Description

If the input str translates to a group name, return that. None

Description

The data structure is precisely re-using/simulating as in the actual Secret Storage

Methods

CachedSecret. __init__( self , model: Model , component , label: str , secret_uri , legacy_labels )

CachedSecret. meta( self )

Description

Getting cached secret meta-information. None

CachedSecret. add_secret( self , content , relation , label )

Description

Create a new secret. None

CachedSecret. get_content( self )

Description

Getting cached secret content. None

CachedSecret. set_content( self , content )

Description

Setting cached secret content. None

CachedSecret. get_info( self )

Description

Wrapper function to apply the corresponding call on the Secret object within CachedSecret if any. None

CachedSecret. remove( self )

Description

Remove secret. None

Description

A data structure storing CachedSecret objects. None

Methods

SecretCache. __init__( self , model: Model , component )

SecretCache. get( self , label: str , uri , legacy_labels )

Description

Getting a secret from Juju Secret store or cache. None

SecretCache. add( self , label: str , content , relation: Relation )

Description

Adding a secret to Juju Secret. None

SecretCache. remove( self , label: str )

Description

Remove a secret from the cache. None

Description

Python Standard Library 'dict' - like representation of Relation Data. None

Methods

DataDict. __init__( self , relation_data , relation_id: int )

DataDict. data( self )

Description

Return the full content of the Abstract Relation Data dictionary. None

DataDict. __setitem__( self , key: str , item: str )

Description

Set an item of the Abstract Relation Data dictionary. None

DataDict. __getitem__( self , key: str )

Description

Get an item of the Abstract Relation Data dictionary. None

DataDict. __eq__( self , d: dict )

Description

Equality. None

DataDict. __repr__( self )

Description

String representation Abstract Relation Data dictionary. None

DataDict. __len__( self )

Description

Length of the Abstract Relation Data dictionary. None

DataDict. __delitem__( self , key: str )

Description

Delete an item of the Abstract Relation Data dictionary. None

DataDict. has_key( self , key: str )

Description

Does the key exist in the Abstract Relation Data dictionary? None

DataDict. update( self , items )

Description

Update the Abstract Relation Data dictionary. None

DataDict. keys( self )

Description

Keys of the Abstract Relation Data dictionary. None

DataDict. values( self )

Description

Values of the Abstract Relation Data dictionary. None

DataDict. items( self )

Description

Items of the Abstract Relation Data dictionary. None

DataDict. pop( self , item: str )

Description

Pop an item of the Abstract Relation Data dictionary. None

DataDict. __contains__( self , item: str )

Description

Does the Abstract Relation Data dictionary contain item? None

DataDict. __iter__( self )

Description

Iterate through the Abstract Relation Data dictionary. None

DataDict. get( self , key: str , default )

Description

Safely get an item of the Abstract Relation Data dictionary. None

Description

Base relation data mainpulation (abstract) class. None

Methods

Data. __init__( self , model: Model , relation_name: str )

Data. relations( self )

Description

The list of Relation instances associated with this relation_name. None

Data. secrets_enabled( self )

Description

Is this Juju version allowing for Secrets usage? None

Data. secret_label_map( self )

Description

Exposing secret-label map via a property -- could be overridden in descendants! None

Data. as_dict( self , relation_id: int )

Description

Dict behavior representation of the Abstract Data. None

Data. get_relation( self , relation_name , relation_id )

Description

Safe way of retrieving a relation. None

Data. get_secret_uri( self , relation: Relation , group: SecretGroup )

Description

Get the secret URI for the corresponding group. None

Data. set_secret_uri( self , relation: Relation , group: SecretGroup , secret_uri: str )

Description

Set the secret URI for the corresponding group. None

Data. fetch_relation_data( self , relation_ids , fields , relation_name )

Retrieves data from relation.

Returns

a dict of the values stored in the relation data bag for all relation instances (indexed by the relation ID).

Description

This function can be used to retrieve data from a relation in the charm code when outside an event callback. Function cannot be used in *-relation-broken events and will raise an exception.

Data. fetch_relation_field( self , relation_id: int , field: str , relation_name )

Description

Get a single field from the relation data. None

Data. fetch_my_relation_data( self , relation_ids , fields , relation_name )

Fetch data of the 'owner' (or 'this app') side of the relation.

Description

NOTE: Since only the leader can read the relation's 'this_app'-side Application databag, the functionality is limited to leaders

Data. fetch_my_relation_field( self , relation_id: int , field: str , relation_name )

Get a single field from the relation data -- owner side.

Description

NOTE: Since only the leader can read the relation's 'this_app'-side Application databag, the functionality is limited to leaders

Data. update_relation_data( self , relation_id: int , data: dict )

Description

Update the data within the relation. None

Data. delete_relation_data( self , relation_id: int , fields )

Description

Remove field from the relation. None

Description

Requires-side of the relation. None

Methods

EventHandlers. __init__( self , charm: CharmBase , relation_data: Data , unique_key: str )

Description

Manager of base client relations. None

Description

Base provides-side of the data products relation. None

Methods

ProviderData. __init__( self , model: Model , relation_name: str )

ProviderData. set_credentials( self , relation_id: int , username: str , password: str )

Set credentials.

Arguments

relation_id

the identifier for a particular relation.

username

user that was created.

password

password of the created user.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

ProviderData. set_tls( self , relation_id: int , tls: str )

Set whether TLS is enabled.

Arguments

relation_id

the identifier for a particular relation.

tls

whether tls is enabled (True or False).

ProviderData. set_tls_ca( self , relation_id: int , tls_ca: str )

Set the TLS CA in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

tls_ca

TLS certification authority.

Description

Requirer-side of the relation. None

Methods

RequirerData. __init__( self , model , relation_name: str , extra_user_roles , additional_secret_fields )

Description

Manager of base client relations. None

RequirerData. secret_fields( self )

Description

Local access to secrets field, in case they are being used. None

RequirerData. get_secret_uri( self , relation: Relation , group: SecretGroup )

Description

Getting relation secret URI for the corresponding Secret Group. None

RequirerData. set_secret_uri( self , relation: Relation , group: SecretGroup , uri: str )

Description

Setting relation secret URI is not possible for a Requirer. None

RequirerData. is_resource_created( self , relation_id )

Check if the resource has been created.

Arguments

relation_id (int)

When provided the check is done only for the relation id provided, otherwise the check is done for all relations

Returns

True or False

Description

This function can be used to check if the Provider answered with data in the charm code when outside an event callback.

Description

Requires-side of the relation. None

Methods

RequirerEventHandlers. __init__( self , charm: CharmBase , relation_data: RequirerData , unique_key: str )

Description

Manager of base client relations. None

Description

Represents peer relations data. None

Methods

DataPeerData. __init__( self , model , relation_name: str , extra_user_roles , additional_secret_fields , additional_secret_group_mapping , secret_field_name , deleted_label )

DataPeerData. scope( self )

Description

Turn component information into Scope. None

DataPeerData. secret_label_map( self )

Description

Property storing secret mappings. None

DataPeerData. static_secret_fields( self )

Description

Re-definition of the property in a way that dynamically extended list is retrieved. None

DataPeerData. secret_fields( self )

Description

Re-definition of the property in a way that dynamically extended list is retrieved. None

DataPeerData. current_secret_fields( self )

Description

Helper method to get all currently existing secret fields (added statically or dynamically). None

DataPeerData. set_secret( self , relation_id: int , field: str , value: str , group_mapping )

Public interface method to add a Relation Data field specifically as a Juju Secret.

Arguments

relation_id

ID of the relation

field

The secret field that is to be added

value

The string value of the secret

group_mapping

The name of the "secret group", in case the field is to be added to an existing secret

DataPeerData. get_secret( self , relation_id: int , field: str , group_mapping )

Description

Public interface method to fetch secrets only. None

DataPeerData. delete_secret( self , relation_id: int , field: str , group_mapping )

Description

Public interface method to delete secrets only. None

DataPeerData. valid_field_pattern( self , field: str , full_field: str )

Check that no secret group is attempted to be used together without secrets being enabled.

Description

Secrets groups are impossible to use with versions that are not yet supporting secrets.

DataPeerData. fetch_relation_data( self , relation_ids , fields , relation_name )

Description

This method makes no sense for a Peer Relation. None

DataPeerData. fetch_relation_field( self , relation_id: int , field: str , relation_name )

Description

This method makes no sense for a Peer Relation. None

Description

Requires-side of the relation. None

Methods

DataPeerEventHandlers. __init__( self , charm: CharmBase , relation_data: RequirerData , unique_key: str )

Description

Manager of base client relations. None

Description

Represents peer relations. None

Methods

DataPeer. __init__( self , charm , relation_name: str , extra_user_roles , additional_secret_fields , additional_secret_group_mapping , secret_field_name , deleted_label , unique_key: str )

Description

Unit data abstraction representation. None

Methods

DataPeerUnitData. __init__( self )

Description

Unit databag representation. None

Methods

DataPeerUnit. __init__( self , charm , relation_name: str , extra_user_roles , additional_secret_fields , additional_secret_group_mapping , secret_field_name , deleted_label , unique_key: str )

Description

Unit data abstraction representation. None

Methods

DataPeerOtherUnitData. __init__( self , unit: Unit )

DataPeerOtherUnitData. update_relation_data( self , relation_id: int , data: dict )

Description

This method makes no sense for a Other Peer Relation. None

DataPeerOtherUnitData. delete_relation_data( self , relation_id: int , fields )

Description

This method makes no sense for a Other Peer Relation. None

Description

Requires-side of the relation. None

Methods

DataPeerOtherUnitEventHandlers. __init__( self , charm: CharmBase , relation_data: DataPeerUnitData )

Description

Manager of base client relations. None

Description

Unit databag representation for another unit than the executor. None

Methods

DataPeerOtherUnit. __init__( self , unit: Unit , charm: CharmBase , relation_name: str , extra_user_roles , additional_secret_fields , additional_secret_group_mapping , secret_field_name , deleted_label )

Description

Base class for data events. None

Methods

ExtraRoleEvent. extra_user_roles( self )

Description

Returns the extra user roles that were requested. None

Description

Base class for Relation Events that need to handle secrets. None

Methods

RelationEventWithSecret. secrets_enabled( self )

Description

Is this Juju version allowing for Secrets usage? None

Description

The amount of logic added here is not ideal -- but this was the only way to preserve the interface when moving to Juju Secrets

Methods

AuthenticationEvent. username( self )

Description

Returns the created username. None

AuthenticationEvent. password( self )

Description

Returns the password for the created user. None

AuthenticationEvent. tls( self )

Description

Returns whether TLS is configured. None

AuthenticationEvent. tls_ca( self )

Description

Returns TLS CA. None

Description

Base class for database events. None

Methods

DatabaseProvidesEvent. database( self )

Description

Returns the database that was requested. None

Description

Event emitted when a new database is requested for use on this relation. None

Methods

DatabaseRequestedEvent. external_node_connectivity( self )

Description

Returns the requested external_node_connectivity field. None

Description

This class defines the events that the database can emit.

Description

Base class for database events. None

Methods

DatabaseRequiresEvent. database( self )

Description

Returns the database name. None

DatabaseRequiresEvent. endpoints( self )

Returns a comma separated list of read/write endpoints.

Description

In VM charms, this is the primary's address. In kubernetes charms, this is the service to the primary pod.

DatabaseRequiresEvent. read_only_endpoints( self )

Returns a comma separated list of read only endpoints.

Description

In VM charms, this is the address of all the secondary instances. In kubernetes charms, this is the service to all replica pod instances.

DatabaseRequiresEvent. replset( self )

Returns the replicaset name.

Description

MongoDB only.

DatabaseRequiresEvent. uris( self )

Returns the connection URIs.

Description

MongoDB, Redis, OpenSearch.

DatabaseRequiresEvent. version( self )

Returns the version of the database.

Description

Version as informed by the database daemon.

Description

Event emitted when a new database is created for use on this relation. None

Description

Event emitted when the read/write endpoints are changed. None

Description

Event emitted when the read only endpoints are changed. None

Description

This class defines the events that the database can emit.

Description

Provider-side data of the database relations. None

Methods

DatabaseProviderData. __init__( self , model: Model , relation_name: str )

DatabaseProviderData. set_database( self , relation_id: int , database_name: str )

Set database name.

Arguments

relation_id

the identifier for a particular relation.

database_name

database name.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

DatabaseProviderData. set_endpoints( self , relation_id: int , connection_strings: str )

Set database primary connections.

Arguments

relation_id

the identifier for a particular relation.

connection_strings

database hosts and ports comma separated list.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

In VM charms, only the primary's address should be passed as an endpoint. In kubernetes charms, the service endpoint to the primary pod should be passed as an endpoint.

DatabaseProviderData. set_read_only_endpoints( self , relation_id: int , connection_strings: str )

Set database replicas connection strings.

Arguments

relation_id

the identifier for a particular relation.

connection_strings

database hosts and ports comma separated list.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

DatabaseProviderData. set_replset( self , relation_id: int , replset: str )

Set replica set name in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

replset

replica set name.

Description

MongoDB only.

DatabaseProviderData. set_uris( self , relation_id: int , uris: str )

Set the database connection URIs in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

uris

connection URIs.

Description

MongoDB, Redis, and OpenSearch only.

DatabaseProviderData. set_version( self , relation_id: int , version: str )

Set the database version in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

version

database version.

DatabaseProviderData. set_subordinated( self , relation_id: int )

Raises the subordinated flag in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

Description

Provider-side of the database relation handlers. None

Methods

DatabaseProviderEventHandlers. __init__( self , charm: CharmBase , relation_data: DatabaseProviderData , unique_key: str )

Description

Manager of base client relations. None

Description

Provider-side of the database relations. None

Methods

DatabaseProvides. __init__( self , charm: CharmBase , relation_name: str )

Description

Requirer-side of the database relation. None

Methods

DatabaseRequirerData. __init__( self , model: Model , relation_name: str , database_name: str , extra_user_roles , relations_aliases , additional_secret_fields , external_node_connectivity: bool )

Description

Manager of database client relations. None

DatabaseRequirerData. is_postgresql_plugin_enabled( self , plugin: str , relation_index: int )

Returns whether a plugin is enabled in the database.

Arguments

plugin

name of the plugin to check.

relation_index

optional relation index to check the database (default: 0 - first relation).

Description

Requires-side of the relation. None

Methods

DatabaseRequirerEventHandlers. __init__( self , charm: CharmBase , relation_data: DatabaseRequirerData , unique_key: str )

Description

Manager of base client relations. None

Description

Provider-side of the database relations. None

Methods

DatabaseRequires. __init__( self , charm: CharmBase , relation_name: str , database_name: str , extra_user_roles , relations_aliases , additional_secret_fields , external_node_connectivity: bool )

Description

Base class for Kafka events. None

Methods

KafkaProvidesEvent. topic( self )

Description

Returns the topic that was requested. None

KafkaProvidesEvent. consumer_group_prefix( self )

Description

Returns the consumer-group-prefix that was requested. None

Description

Event emitted when a new topic is requested for use on this relation. None

Description

This class defines the events that the Kafka can emit.

Description

Base class for Kafka events. None

Methods

KafkaRequiresEvent. topic( self )

Description

Returns the topic. None

KafkaRequiresEvent. bootstrap_server( self )

Description

Returns a comma-separated list of broker uris. None

KafkaRequiresEvent. consumer_group_prefix( self )

Description

Returns the consumer-group-prefix. None

KafkaRequiresEvent. zookeeper_uris( self )

Description

Returns a comma separated list of Zookeeper uris. None

Description

Event emitted when a new topic is created for use on this relation. None

Description

Event emitted when the bootstrap server is changed. None

Description

This class defines the events that the Kafka can emit.

Description

Provider-side of the Kafka relation. None

Methods

KafkaProviderData. __init__( self , model: Model , relation_name: str )

KafkaProviderData. set_topic( self , relation_id: int , topic: str )

Set topic name in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

topic

the topic name.

KafkaProviderData. set_bootstrap_server( self , relation_id: int , bootstrap_server: str )

Set the bootstrap server in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

bootstrap_server

the bootstrap server address.

KafkaProviderData. set_consumer_group_prefix( self , relation_id: int , consumer_group_prefix: str )

Set the consumer group prefix in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

consumer_group_prefix

the consumer group prefix string.

KafkaProviderData. set_zookeeper_uris( self , relation_id: int , zookeeper_uris: str )

Set the zookeeper uris in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

zookeeper_uris

comma-separated list of ZooKeeper server uris.

Description

Provider-side of the Kafka relation. None

Methods

KafkaProviderEventHandlers. __init__( self , charm: CharmBase , relation_data: KafkaProviderData )

Description

Provider-side of the Kafka relation. None

Methods

KafkaProvides. __init__( self , charm: CharmBase , relation_name: str )

Description

Requirer-side of the Kafka relation. None

Methods

KafkaRequirerData. __init__( self , model: Model , relation_name: str , topic: str , extra_user_roles , consumer_group_prefix , additional_secret_fields )

Description

Manager of Kafka client relations. None

KafkaRequirerData. topic( self )

Description

Topic to use in Kafka. None

KafkaRequirerData. topic( self , value )

Description

Requires-side of the Kafka relation. None

Methods

KafkaRequirerEventHandlers. __init__( self , charm: CharmBase , relation_data: KafkaRequirerData )

Description

Provider-side of the Kafka relation. None

Methods

KafkaRequires. __init__( self , charm: CharmBase , relation_name: str , topic: str , extra_user_roles , consumer_group_prefix , additional_secret_fields )

Description

Base class for OpenSearch events. None

Methods

OpenSearchProvidesEvent. index( self )

Description

Returns the index that was requested. None

Description

Event emitted when a new index is requested for use on this relation. None

Description

This class defines the events that OpenSearch can emit.

Description

Base class for OpenSearch requirer events. None

Description

Event emitted when a new index is created for use on this relation. None

Description

This class defines the events that the opensearch requirer can emit.

Description

Provider-side of the OpenSearch relation. None

Methods

OpenSearchProvidesData. __init__( self , model: Model , relation_name: str )

OpenSearchProvidesData. set_index( self , relation_id: int , index: str )

Set the index in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

index

the index as it is created on the provider charm. This needn't match the requested index, and can be used to present a different index name if, for example, the requested index is invalid.

OpenSearchProvidesData. set_endpoints( self , relation_id: int , endpoints: str )

Set the endpoints in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

endpoints

the endpoint addresses for opensearch nodes.

OpenSearchProvidesData. set_version( self , relation_id: int , version: str )

Set the opensearch version in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

version

database version.

Description

Provider-side of the OpenSearch relation. None

Methods

OpenSearchProvidesEventHandlers. __init__( self , charm: CharmBase , relation_data: OpenSearchProvidesData )

Description

Provider-side of the OpenSearch relation. None

Methods

OpenSearchProvides. __init__( self , charm: CharmBase , relation_name: str )

Description

Requires data side of the OpenSearch relation. None

Methods

OpenSearchRequiresData. __init__( self , model: Model , relation_name: str , index: str , extra_user_roles , additional_secret_fields )

Description

Manager of OpenSearch client relations. None

Description

Requires events side of the OpenSearch relation. None

Methods

OpenSearchRequiresEventHandlers. __init__( self , charm: CharmBase , relation_data: OpenSearchRequiresData )

Description

Requires-side of the OpenSearch relation. None

Methods

OpenSearchRequires. __init__( self , charm: CharmBase , relation_name: str , index: str , extra_user_roles , additional_secret_fields )

Data Platform Libs

charms.data_platform_libs.v0.data_interfaces

Database (MySQL, Postgresql, MongoDB, and Redis)

Requires Charm

Provider Charm

Kafka

Requirer Charm

Provider Charm

class DataInterfacesError

class SecretError

class SecretAlreadyExistsError

class SecretsUnavailableError

class SecretsIllegalUpdateError

class IllegalOperationError

class PrematureDataAccessError

def get_encoded_dict( relation: Relation, member, field: str )

def get_encoded_list( relation: Relation, member, field: str )

def set_encoded_field( relation: Relation, member, field: str, value )

def diff( event: RelationChangedEvent, bucket )

def leader_only(f)

def juju_secrets_only(f)

def dynamic_secrets_only(f)

def either_static_or_dynamic_secrets(f)

def legacy_apply_from_version(version: int)

class Scope

class SecretGroup

class SecretGroupsAggregate

class CachedSecret

class SecretCache

class DataDict

class Data

class EventHandlers

class ProviderData

class RequirerData

class RequirerEventHandlers

class DataPeerData

class DataPeerEventHandlers

class DataPeer

class DataPeerUnitData

class DataPeerUnit

class DataPeerOtherUnitData

class DataPeerOtherUnitEventHandlers

class DataPeerOtherUnit

class ExtraRoleEvent

class RelationEventWithSecret

class AuthenticationEvent

class DatabaseProvidesEvent

class DatabaseRequestedEvent

class DatabaseProvidesEvents

class DatabaseRequiresEvent

class DatabaseCreatedEvent

class DatabaseEndpointsChangedEvent

class DatabaseReadOnlyEndpointsChangedEvent

class DatabaseRequiresEvents

class DatabaseProviderData

class DatabaseProviderEventHandlers

class DatabaseProvides

class DatabaseRequirerData

class DatabaseRequirerEventHandlers

class DatabaseRequires

class KafkaProvidesEvent

class TopicRequestedEvent

class KafkaProvidesEvents

class KafkaRequiresEvent

class TopicCreatedEvent

class BootstrapServerChangedEvent

class KafkaRequiresEvents

class KafkaProviderData

class KafkaProviderEventHandlers

class KafkaProvides

class KafkaRequirerData

class KafkaRequirerEventHandlers

class KafkaRequires

class OpenSearchProvidesEvent

class IndexRequestedEvent

class OpenSearchProvidesEvents

class OpenSearchRequiresEvent

class IndexCreatedEvent

class OpenSearchRequiresEvents

class OpenSearchProvidesData

def get_encoded_dict(
relation: Relation,
member,
field: str
)

def get_encoded_list(
relation: Relation,
member,
field: str
)

def set_encoded_field(
relation: Relation,
member,
field: str,
value
)

def diff(
event: RelationChangedEvent,
bucket
)