---
title: Charmhub | Deploy Data Platform Libs using Charmhub - The Open Operator Collection
description: Deploy the latest version of Data Platform Libs on any cloud.
url: https://charmhub.io/data-platform-libs/libraries/s3
---

# Data Platform Libs

[Canonical](https://charmhub.io/publisher/data-platform "View all packages from Canonical")

* [Canonical](https://charmhub.io/publisher/data-platform "View all packages from Canonical")
* [Databases](https://charmhub.io/?filter=databases)

Platform:

22.04

stable 81

```
juju deploy data-platform-libs
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

[Toggle side navigation](https://charmhub.io/data-platform-libs/libraries/s3#drawer)

## charms.data\_platform\_libs.v0.s3

* [*Docstrings*Docstrings](https://charmhub.io/data-platform-libs/libraries/s3)
  [*Code*Source code](https://charmhub.io/data-platform-libs/libraries/s3/source-code)
* + Download

    Fetch library

    ```
    charmcraft fetch-lib charms.data_platform_libs.v0.s3
    ```

    [Download s3.py](https://charmhub.io/data-platform-libs/libraries/s3/download)
  + *Last updated* 17 Jul 2025
  + *Revision* Library version 0.6

A library for communicating with the S3 credentials providers and consumers.

This library provides the relevant interface code implementing the communication
specification for fetching, retrieving, triggering, and responding to events related to
the S3 provider charm and its consumers.

###### Provider charm

The provider is implemented in the `s3-provider` charm which is meant to be deployed
alongside one or more consumer charms. The provider charm is serving the s3 credentials and
metadata needed to communicate and work with an S3 compatible backend.

Example:

```
from charms.data_platform_libs.v0.s3 import CredentialRequestedEvent, S3Provider

class ExampleProviderCharm(CharmBase):
    def __init__(self, *args) -> None:
        super().__init__(*args)
        self.s3_provider = S3Provider(self, "s3-credentials")

        self.framework.observe(self.s3_provider.on.credentials_requested,
            self._on_credential_requested)

    def _on_credential_requested(self, event: CredentialRequestedEvent):
        if not self.unit.is_leader():
            return

        # get relation id
        relation_id = event.relation.id

        # get bucket name
        bucket = event.bucket

        # S3 configuration parameters
        desired_configuration = {"access-key": "your-access-key", "secret-key":
            "your-secret-key", "bucket": "your-bucket"}

        # update the configuration
        self.s3_provider.update_connection_info(relation_id, desired_configuration)

        # or it is possible to set each field independently

        self.s3_provider.set_secret_key(relation_id, "your-secret-key")

if __name__ == "__main__":
    main(ExampleProviderCharm)

### Requirer charm

The requirer charm is the charm requiring the S3 credentials.
An example of requirer charm is the following:

Example:
```python

from charms.data_platform_libs.v0.s3 import (
    CredentialsChangedEvent,
    CredentialsGoneEvent,
    S3Requirer
)

class ExampleRequirerCharm(CharmBase):

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

         bucket_name = "test-bucket"
        # if bucket name is not provided the bucket name will be generated
        # e.g., ('relation-{relation.id}')

        self.s3_client = S3Requirer(self, "s3-credentials", bucket_name)

        self.framework.observe(self.s3_client.on.credentials_changed, self._on_credential_changed)
        self.framework.observe(self.s3_client.on.credentials_gone, self._on_credential_gone)

    def _on_credential_changed(self, event: CredentialsChangedEvent):

        # access single parameter credential
        secret_key = event.secret_key
        access_key = event.access_key

        # or as alternative all credentials can be collected as a dictionary
        credentials = self.s3_client.get_s3_credentials()

    def _on_credential_gone(self, event: CredentialsGoneEvent):
        # credentials are removed
        pass

 if __name__ == "__main__":
    main(ExampleRequirerCharm)
```

---

Index

* [def diff(
  event,
  bucket
  )](https://charmhub.io/data-platform-libs/libraries/s3#diff)
* [class BucketEvent](https://charmhub.io/data-platform-libs/libraries/s3#bucketevent)
* + [def bucket(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#bucketevent-bucket)
* [class CredentialRequestedEvent](https://charmhub.io/data-platform-libs/libraries/s3#credentialrequestedevent)
* [class S3CredentialEvents](https://charmhub.io/data-platform-libs/libraries/s3#s3credentialevents)
* [class S3Provider](https://charmhub.io/data-platform-libs/libraries/s3#s3provider)
* + [def \_\_init\_\_(
    self,
    charm,
    relation\_name)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-__init__)
* + [def fetch\_relation\_data(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-fetch_relation_data)
* + [def update\_connection\_info(
    self,
    relation\_id,
    connection\_data)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-update_connection_info)
* + [def relations(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-relations)
* + [def set\_bucket(
    self,
    relation\_id,
    bucket)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_bucket)
* + [def set\_access\_key(
    self,
    relation\_id,
    access\_key)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_access_key)
* + [def set\_secret\_key(
    self,
    relation\_id,
    secret\_key)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_secret_key)
* + [def set\_path(
    self,
    relation\_id,
    path)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_path)
* + [def set\_endpoint(
    self,
    relation\_id,
    endpoint)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_endpoint)
* + [def set\_region(
    self,
    relation\_id,
    region)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_region)
* + [def set\_s3\_uri\_style(
    self,
    relation\_id,
    s3\_uri\_style)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_s3_uri_style)
* + [def set\_storage\_class(
    self,
    relation\_id,
    storage\_class)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_storage_class)
* + [def set\_tls\_ca\_chain(
    self,
    relation\_id,
    tls\_ca\_chain)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_tls_ca_chain)
* + [def set\_s3\_api\_version(
    self,
    relation\_id,
    s3\_api\_version)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_s3_api_version)
* + [def set\_delete\_older\_than\_days(
    self,
    relation\_id,
    days)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_delete_older_than_days)
* + [def set\_attributes(
    self,
    relation\_id,
    attributes)](https://charmhub.io/data-platform-libs/libraries/s3#s3provider-set_attributes)
* [class S3Event](https://charmhub.io/data-platform-libs/libraries/s3#s3event)
* + [def bucket(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-bucket)
* + [def access\_key(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-access_key)
* + [def secret\_key(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-secret_key)
* + [def path(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-path)
* + [def endpoint(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-endpoint)
* + [def region(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-region)
* + [def s3\_uri\_style(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-s3_uri_style)
* + [def storage\_class(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-storage_class)
* + [def tls\_ca\_chain(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-tls_ca_chain)
* + [def s3\_api\_version(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-s3_api_version)
* + [def delete\_older\_than\_days(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-delete_older_than_days)
* + [def attributes(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3event-attributes)
* [class CredentialsChangedEvent](https://charmhub.io/data-platform-libs/libraries/s3#credentialschangedevent)
* [class CredentialsGoneEvent](https://charmhub.io/data-platform-libs/libraries/s3#credentialsgoneevent)
* [class S3CredentialRequiresEvents](https://charmhub.io/data-platform-libs/libraries/s3#s3credentialrequiresevents)
* [class S3Requirer](https://charmhub.io/data-platform-libs/libraries/s3#s3requirer)
* + [def \_\_init\_\_(
    self,
    charm,
    relation\_name,
    bucket\_name)](https://charmhub.io/data-platform-libs/libraries/s3#s3requirer-__init__)
* + [def fetch\_relation\_data(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3requirer-fetch_relation_data)
* + [def update\_connection\_info(
    self,
    relation\_id,
    connection\_data)](https://charmhub.io/data-platform-libs/libraries/s3#s3requirer-update_connection_info)
* + [def get\_s3\_connection\_info(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3requirer-get_s3_connection_info)
* + [def relations(
    self)](https://charmhub.io/data-platform-libs/libraries/s3#s3requirer-relations)

#### def diff(     event: RelationChangedEvent,     bucket )

Retrieves the diff of the data in the relation changed databag.

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.

#### class BucketEvent

Description

Base class for bucket events. None

Methods

BucketEvent.
bucket(

*self*
)

Description

Returns the bucket was requested. None

#### class CredentialRequestedEvent

Description

Event emitted when a set of credential is requested for use on this relation. None

#### class S3CredentialEvents

Description

Event descriptor for events raised by S3Provider. None

#### class S3Provider

Description

A provider handler for communicating S3 credentials to consumers. None

Methods

S3Provider.
\_\_init\_\_(

*self*

,
charm: CharmBase

,
relation\_name: str
)

S3Provider.
fetch\_relation\_data(

*self*
)

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.

S3Provider.
update\_connection\_info(

*self*

,
relation\_id: int

,
connection\_data: dict
)

Updates the credential data as set of key-value pairs in the relation.

Arguments

relation\_id

the identifier for a particular relation.

connection\_data

dict containing the key-value pairs
that should be updated.

Description

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

S3Provider.
relations(

*self*
)

Description

The list of Relation instances associated with this relation\_name. None

S3Provider.
set\_bucket(

*self*

,
relation\_id: int

,
bucket: str
)

Sets bucket name in application databag.

Arguments

relation\_id

the identifier for a particular relation.

bucket

the bucket name.

Description

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

S3Provider.
set\_access\_key(

*self*

,
relation\_id: int

,
access\_key: str
)

Sets access-key value in application databag.

Arguments

relation\_id

the identifier for a particular relation.

access\_key

the access-key value.

Description

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

S3Provider.
set\_secret\_key(

*self*

,
relation\_id: int

,
secret\_key: str
)

Sets the secret key value in application databag.

Arguments

relation\_id

the identifier for a particular relation.

secret\_key

the value of the secret key.

Description

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

S3Provider.
set\_path(

*self*

,
relation\_id: int

,
path: str
)

Sets the path value in application databag.

Arguments

relation\_id

the identifier for a particular relation.

path

the path value.

Description

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

S3Provider.
set\_endpoint(

*self*

,
relation\_id: int

,
endpoint: str
)

Sets the endpoint address in application databag.

Arguments

relation\_id

the identifier for a particular relation.

endpoint

the endpoint address.

Description

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

S3Provider.
set\_region(

*self*

,
relation\_id: int

,
region: str
)

Sets the region location in application databag.

Arguments

relation\_id

the identifier for a particular relation.

region

the region address.

Description

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

S3Provider.
set\_s3\_uri\_style(

*self*

,
relation\_id: int

,
s3\_uri\_style: str
)

Sets the S3 URI style in application databag.

Arguments

relation\_id

the identifier for a particular relation.

s3\_uri\_style

the s3 URI style.

Description

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

S3Provider.
set\_storage\_class(

*self*

,
relation\_id: int

,
storage\_class: str
)

Sets the storage class in application databag.

Arguments

relation\_id

the identifier for a particular relation.

storage\_class

the storage class.

Description

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

S3Provider.
set\_tls\_ca\_chain(

*self*

,
relation\_id: int

,
tls\_ca\_chain
)

Sets the tls\_ca\_chain value in application databag.

Arguments

relation\_id

the identifier for a particular relation.

tls\_ca\_chain

the TLS Chain value.

Description

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

S3Provider.
set\_s3\_api\_version(

*self*

,
relation\_id: int

,
s3\_api\_version: str
)

Sets the S3 API version in application databag.

Arguments

relation\_id

the identifier for a particular relation.

s3\_api\_version

the S3 version value.

Description

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

S3Provider.
set\_delete\_older\_than\_days(

*self*

,
relation\_id: int

,
days: int
)

Sets the retention days for full backups in application databag.

Arguments

relation\_id

the identifier for a particular relation.

days

the value.

Description

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

S3Provider.
set\_attributes(

*self*

,
relation\_id: int

,
attributes
)

Sets the connection attributes in application databag.

Arguments

relation\_id

the identifier for a particular relation.

attributes

the attributes value.

Description

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

#### class S3Event

Description

Base class for S3 storage events. None

Methods

S3Event.
bucket(

*self*
)

Description

Returns the bucket name. None

S3Event.
access\_key(

*self*
)

Description

Returns the access key. None

S3Event.
secret\_key(

*self*
)

Description

Returns the secret key. None

S3Event.
path(

*self*
)

Description

Returns the path where data can be stored. None

S3Event.
endpoint(

*self*
)

Description

Returns the endpoint address. None

S3Event.
region(

*self*
)

Description

Returns the region. None

S3Event.
s3\_uri\_style(

*self*
)

Description

Returns the s3 uri style. None

S3Event.
storage\_class(

*self*
)

Description

Returns the storage class name. None

S3Event.
tls\_ca\_chain(

*self*
)

Description

Returns the TLS CA chain. None

S3Event.
s3\_api\_version(

*self*
)

Description

Returns the S3 API version. None

S3Event.
delete\_older\_than\_days(

*self*
)

Description

Returns the retention days for full backups. None

S3Event.
attributes(

*self*
)

Description

Returns the attributes. None

#### class CredentialsChangedEvent

Description

Event emitted when S3 credential are changed on this relation. None

#### class CredentialsGoneEvent

Description

Event emitted when S3 credential are removed from this relation. None

#### class S3CredentialRequiresEvents

Description

Event descriptor for events raised by the S3Provider. None

#### class S3Requirer

Description

Requires-side of the s3 relation. None

Methods

S3Requirer.
\_\_init\_\_(

*self*

,
charm

,
relation\_name: str

,
bucket\_name
)

Description

Manager of the s3 client relations. None

S3Requirer.
fetch\_relation\_data(

*self*
)

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.

S3Requirer.
update\_connection\_info(

*self*

,
relation\_id: int

,
connection\_data: dict
)

Updates the credential data as set of key-value pairs in the relation.

Arguments

relation\_id

the identifier for a particular relation.

connection\_data

dict containing the key-value pairs
that should be updated.

Description

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

S3Requirer.
get\_s3\_connection\_info(

*self*
)

Description

Return the s3 credentials as a dictionary. None

S3Requirer.
relations(

*self*
)

Description

The list of Relation instances associated with this relation\_name. None