Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thenodon/gonb

A Grafana onboarding tool
https://github.com/thenodon/gonb

grafana

Last synced: 6 days ago
JSON representation

A Grafana onboarding tool

Awesome Lists containing this project

README 

        
[![Python application](https://github.com/thenodon/gonb/actions/workflows/python-app.yml/badge.svg)](https://github.com/thenodon/gonb/actions/workflows/python-app.yml)

[![PyPI version](https://badge.fury.io/py/gonb.svg)](https://badge.fury.io/py/gonb)



gonb - A Grafana onboarding tool

---------------------------------

# Overview

Gonb enable continues provisioning and configuration of Grafana based on an IAM source system.

This includes the lifecycle of organizations, users and teams.   



Users should authenticate using some SSO provider, but gonb us the same SSO IAM system to configure users into different

Grafana organizations and teams. 

Gonb should be run using some scheduling tool to keep user in sync with the users definition in the IAM source.



A typical patterns supported are:

- Map users in an IAM group to a corresponding organization.

- Map users in an IAM group into an organization and team



In the later use case gonb also provide the creation of folders that are specific to a team. This support the 

model where different teams have their own folder to create dashboards and alerts separated from other teams.



The user model in the IAM system must be mapped to the Grafana model. The model include the objects for 

organization, team and user where teams and users are linked to an organization.



# Features

- Integration with different IAM solution using a provider pattern.

- Multiple providers could operate against same Grafana instance, but should not operate on the same organization.

- A user can belong to multiple organizations.

- Automatic add and remove of user from organization(s) based on the lifecycle in the IAM.

- Update users in Grafana if any attributes in the user's IAM "object" is changed, e.g. the role, email.

- Create organization if they do not exist in Grafana, default false.

- Automatic creation of team folder, folder with same name as team, if teams are created. Default folder permission

for team is Editor. 

- Team member lifecycle in the same way as for users in organization

- Manage permission for user with Grafana Admin (instance admin) rights. Default is false.

- Create folders and one level of subfolder. Top folders and subfolders can have different permissions for teams.



# Argument passing

The only way to pass arguments to gonb is by environment variables. Each provider must define their own and 

required environment variables, and they must be exposed by the interface method:



```python

def mandatory_env_vars(self) -> Dict[str, str]:

    pass

```



For the grafana integration the following 3 must exist and have valid values, the rest are optional:



- GONB_GRAFANA_URL 

- GONB_GRAFANA_USER

- GONB_GRAFANA_PASSWORD

- GONB_GRAFANA_CREATE_ORGS - Will create organization(s) if not exists, default `False`

- GONB_GRAFANA_ADMINS - will manage users Grafana admin rights, default `False`

- GONB_GRAFANA_MAIN_ORG - allow management of Grafana `Main Org.`, default `False`

- GONB_GRAFANA_TEAM_FOLDER - create team folder, default `True` 

- GONB_SSO_PROVIDER - specify if the provider is based on a IAM used for Grafana authentication, default `True`.



> If `GONB_SSO_PROVIDER` is True there is some updating operations that are not done by gonb, e.g. update a 

> user's name or email.  



# Develop a provider

A provider must implement the class `gonb.provider.Provider` and implement the following methods:

```python

    def get_organisations(self) -> Dict[str, OrganizationDTO]:

    



    def mandatory_env_vars(self) -> Dict[str, str]:



```

If not implemented a `NotImplementedError` will be raised.



Please see examples in the directory `json_gonb_provider`, `json_team_gonb_provider` and `okta_gonb_provider`.



> Both these example providers are part of gonb pip package https://pypi.org/project/gonb.



# Running gonb

There are two ways you can use gonb. The first is to use it as package and build a provider. 

The other way is to let gonb execute the provider. In this case the provider must be a python package and the 

following environment variables must be set before gonb is executed:

- GONB_PROVIDER_CLASS_PATH  - the class name that is a subclass to `Provider`, e.g. `json_gonb_provider.json_file.JSONFile`

where `json_gonb_provider.json_file` is the package part.



Gonb will dynamical load the module an instantiate the implemented `Provider` class.

The second option enable building different providers as packages and use, e.g. pip to deploy dependency.



>Of course, you can use both gonb and a provider as packages and build something totally new like web service 

>that sync on external events.



# Run the json provider example

The json file provider is just for testing. 



```shell

git clone [email protected]:thenodon/gonb.git

python3 -m venv venv

. venv/bin/activate

pip install -r requirements.txt



export GONB_GRAFANA_PASSWORD=xyz

export GONB_GRAFANA_URL=http://localhost:3000

export GONB_GRAFANA_USER=admin

export GONB_JSON_FILE=json_file_example/users.json;



# Set to true if organizations should be created if not existing

export GONB_GRAFANA_CREATE_ORGS=true



cp json_file_example/users_add.json json_file_example/users.json

python -m json_gonb_provider



# check your Grafana for results

```

# System requirements



- Python 3.8

- Grafana 9 - tested on 9.3.6



# Important notes

- Password can be set by the provider, but should typical not since SSO would typical be used. 

The default is to set the password to a 30 character random string of a mix of characters, 

numbers and special characters.

- The GONB_GRAFANA_USER must be a Grafana instance admin.

- If the GONB_GRAFANA_USER do not exist in an organization that is to be managed, the user is added as an organization 

admin. 



# Future

- Support for Grafana Enterprise options for RBAC and team sync groups