Grafana

By Jose C. Massón

Architecture:

Channel	Version	Revision	Published	Runs on
latest/stable	52	52	21 Oct 2022	Ubuntu 20.04
latest/candidate	52	52	21 Oct 2022	Ubuntu 20.04
latest/beta	52	52	21 Oct 2022	Ubuntu 20.04
latest/edge	54	54	24 Nov 2022	Ubuntu 20.04
1.0/stable	52	52	21 Oct 2022	Ubuntu 20.04
1.0/candidate	52	52	21 Oct 2022	Ubuntu 20.04
1.0/beta	52	52	21 Oct 2022	Ubuntu 20.04
1.0/edge	52	52	21 Oct 2022	Ubuntu 20.04

Platform:

charms.grafana_k8s.v0.grafana_auth

Docstrings Source code
- Fetch library
  
  charmcraft fetch-lib charms.grafana_k8s.v0.grafana_auth
  Download grafana_auth.py
- 21 Nov 2022
- Library version 0

grafana-auth library.

This library implements the grafana-auth relation interface, it contains the Requirer and Provider classes for handling the interface. With this library charms can to configure authentication to Grafana. The provider will set the authentication mode that it needs, and will pass the necessary configuration of that authentication mode. The requirer will consume the authentication configuration to authenticate to Grafana.

Getting Started

From a charm directory, fetch the library using charmcraft:

charmcraft fetch-lib charms.grafana_k8s.v0.grafana_auth

You will also need to add the following library to the charm's requirements.txt file:

jsonschema

Provider charm

Example: An example on how to use the AuthProvider with proxy mode using default configuration options. The default arguments are: charm : CharmBase relation_name: str : grafana-auth header_name: str : X-WEBAUTH-USER header_property: str : username auto_sign_up: bool : True sync_ttl: int : None whitelist: list[str] : None headers: list[str] : None headers_encoded: bool : None enable_login_token: bool : None

from charms.grafana_k8s.v0.grafana_auth import GrafanaAuthProxyProvider
from ops.charm import CharmBase
class ExampleProviderCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        ...
        self.grafana_auth_proxy_provider = GrafanaAuthProxyProvider(self)
        self.framework.observe(
            self.grafana_auth_proxy_provider.on.urls_available, self._on_urls_available
        )
        ...

Values different than defaults must be set from the class constructor. The official documentation of Grafana provides further explanation on the values that can be assigned to the different variables. Example:

from charms.grafana_k8s.v0.grafana_auth import GrafanaAuthProxyProvider
from ops.charm import CharmBase
class ExampleProviderCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        ...
        self.grafana_auth_proxy_provider = GrafanaAuthProxyProvider(
            self,
            header_property="email",
            auto_sign_up=False,
            whitelist=["localhost","canonical.com"],
        )
        self.framework.observe(
            self.grafana_auth_proxy_provider.on.urls_available, self._on_urls_available
        )
        ...

Requirer charm

Example: An example on how to use the auth requirer.

from charms.grafana_k8s.v0.grafana_auth import AuthRequirer
from ops.charm import CharmBase
class ExampleRequirerCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.auth_requirer = AuthRequirer(
            self,
            auth_requirer=["https://example.com/"]
        )
        self.framework.observe(
            self.auth_requirer.on.auth_conf_available, self._on_auth_conf_available
        )

Index

def _type_convert_stored(obj)
class UrlsAvailableEvent
- def __init__(self, handle, urls, relation_id)
- def snapshot(self)
- def restore(self, snapshot)
class AuthProviderCharmEvents
class AuthProvider
- def __init__(self, charm, relation_name, refresh_event)
- def _set_auth_config_in_relation_data(self, event)
- def _get_urls_from_relation_data(self, event)
- def _validate_auth_config_json_schema(self)
class AuthConfAvailableEvent
- def __init__(self, handle, auth, relation_id)
- def snapshot(self)
- def restore(self, snapshot)
class AuthRequirerCharmEvents
class AuthRequirer
- def __init__(self, charm, urls, relation_name, refresh_event)
- def _set_urls_in_relation_data(self, event)
- def _get_auth_config_from_relation_data(self, event)
class GrafanaAuthProxyProvider
- def __init__(self, charm, relation_name, refresh_event, header_name, header_property, auto_sign_up, sync_ttl, whitelist, headers, headers_encoded, enable_login_token)
- def _validate_auth_config_json_schema(self)

Description

Convert Stored* to their appropriate types, recursively. None

Description

Charm event triggered when provider charm extracts the urls from relation data. None

Methods

UrlsAvailableEvent. __init__( self , handle , urls: list , relation_id: int )

Description

Returns snapshot. None

UrlsAvailableEvent. restore( self , snapshot: dict )

Description

Restores snapshot. None

Description

List of events that the auth provider charm can leverage. None

Description

This class shouldn't be initialized, Its children classes define the authentication mode and configuration to be used.

Methods

AuthProvider. __init__( self , charm: CharmBase , relation_name: str , refresh_event )

AuthProvider. _set_auth_config_in_relation_data( self , event )

Handler triggered on relation joined and leader elected events.

Arguments

event

Juju event

Returns

None

Description

Adds authentication config to relation data.

AuthProvider. _get_urls_from_relation_data( self , event )

Handler triggered on relation changed and pebble_ready events.

Arguments

event

Juju event

Returns

None

Description

Extracts urls from relation data and emits the urls_available event

Description

Implemented in children classes. None

Description

Charm Event triggered when authentication config is ready. None

Methods

AuthConfAvailableEvent. __init__( self , handle , auth: dict , relation_id: int )

Description

Returns snapshot. None

AuthConfAvailableEvent. restore( self , snapshot: dict )

Description

Restores snapshot. None

Description

List of events that the auth requirer charm can leverage. None

Description

Authentication configuration requirer class. None

Methods

AuthRequirer. __init__( self , charm , urls , relation_name: str , refresh_event )

Constructs an authentication requirer that consumes authentication configuration.

Arguments

charm

CharmBase: the charm which manages this object.

urls

List[str]: a list of urls to access the service the charm needs to authenticate to.

relation_name

str: name of the relation in `metadata.yaml` that has the `grafana_auth` interface.

refresh_event

an optional bound event which will be observed to re-set authentication configuration.

Description

The charm initializing this class requires authentication configuration, and it's expected to provide a list of url(s) to the service it's authenticating to. This class can be initialized as follows: self.auth_requirer = AuthRequirer( self, auth_requirer=["https://example.com/"] )

AuthRequirer. _set_urls_in_relation_data( self , event )

Handler triggered on relation joined events. Adds URL(s) to relation data.

Arguments

event

Juju event

Returns

None

AuthRequirer. _get_auth_config_from_relation_data( self , event )

Handler triggered on relation changed and pebble_ready events.

Arguments

event

Juju event

Returns

None

Description

Extracts authentication config from relation data. Emits an event that contains the config.

Description

Provides proxy mode for authentication to Grafana.

Methods

GrafanaAuthProxyProvider. __init__( self , charm: CharmBase , relation_name: str , refresh_event , header_name: str , header_property: str , auto_sign_up: bool , sync_ttl , whitelist , headers , headers_encoded , enable_login_token )

Constructs GrafanaAuthProxyProvider.

Arguments

charm

CharmBase: the charm which manages this object.

relation_name

str: name of the relation in `metadata.yaml` that has the `grafana_auth` interface.

refresh_event

an optional bound event which will be observed to re-set urls.

header_name

str: HTTP Header name that will contain the username or email

header_property

str: HTTP Header property, defaults to username but can also be `email`.

auto_sign_up

bool: Set to `true` to enable auto sign-up of users who do not exist in Grafana DB.

sync_ttl

int: Define cache time to live in minutes.

whitelist

list[str]: Limits where auth proxy requests come from by configuring a list of IP addresses.

headers

list[str]: Optionally define more headers to sync other user attributes.

headers_encoded

bool: Non-ASCII strings in header values are encoded using quoted-printable encoding

enable_login_token

bool

Returns

None

Description

The charm initializing this object configures the authentication to grafana using proxy authentication mode. This object can be initialized as follows: self.grafana_auth_proxy_provider = GrafanaAuthProxyProvider(self)

GrafanaAuthProxyProvider. _validate_auth_config_json_schema( self )

Validates authentication configuration using json schemas.

Returns

bool

Whether the configuration is valid or not based on the json schema.

Grafana

charms.grafana_k8s.v0.grafana_auth

Getting Started

Provider charm

Requirer charm

def _type_convert_stored(obj)

class UrlsAvailableEvent

class AuthProviderCharmEvents

class AuthProvider

class AuthConfAvailableEvent

class AuthRequirerCharmEvents

class AuthRequirer

class GrafanaAuthProxyProvider