README.rst - salt-formulas/grafana - Gitiles


 =======
 Grafana
 =======

 A beautiful, easy to use and feature rich Graphite dashboard replacement and graph editor.


 Sample pillars
 ==============


 Server deployments
 ------------------

 Server installed from system package and listening on 1.2.3.4:3000 (the default
 is 0.0.0.0:3000)

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         bind:
           address: 1.2.3.4
           port: 3000
         admin:
           user: admin
           password: passwd
         database:
           engine: sqlite3

 Server installed with PostgreSQL database

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         admin:
           user: admin
           password: passwd
         database:
           engine: postgresql
           host: localhost
           port: 5432
           name: grafana
           user: grafana
           password: passwd

 Server installed with LDAP authentication and all authenticated users are
 administrators

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         admin:
           user: admin
           password: passwd
         auth:
           ldap:
             enabled: true
             host: '127.0.0.1'
             port: 389
             use_ssl: false
             bind_dn: "cn=admin,dc=grafana,dc=org"
             bind_password: "grafana"
             user_search_filter: "(cn=%s)"
             user_search_base_dns:
             - "dc=grafana,dc=org"

 Server installed with LDAP and basic authentication

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         admin:
           user: admin
           password: passwd
         auth:
           basic:
             enabled: true
           ldap:
             enabled: true
             host: '127.0.0.1'
             port: 389
             use_ssl: false
             bind_dn: "cn=admin,dc=grafana,dc=org"
             bind_password: "grafana"
             user_search_filter: "(cn=%s)"
             user_search_base_dns:
             - "dc=grafana,dc=org"

 Server installed with LDAP for authentication and authorization

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         admin:
           user: admin
           password: passwd
         auth:
           ldap:
             enabled: true
             host: '127.0.0.1'
             port: 389
             use_ssl: false
             bind_dn: "cn=admin,dc=grafana,dc=org"
             bind_password: "grafana"
             user_search_filter: "(cn=%s)"
             user_search_base_dns:
             - "dc=grafana,dc=org"
             group_search_filter: "(&(objectClass=posixGroup)(memberUid=%s))"
             group_search_base_dns:
             - "ou=groups,dc=grafana,dc=org"
             authorization:
               enabled: true
               admin_group: "admins"
               editor_group: "editors"
               viewer_group: "viewers"

 Server installed with default StackLight JSON dashboards. This will
 be replaced by the possibility for a service to provide its own dashboard
 using salt-mine.

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         dashboards:
           enabled: true
           path: /var/lib/grafana/dashboards

 Server with theme overrides

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         theme:
           light:
             css_override:
               source: http://path.to.theme
               source_hash: sha256=xyz
               build: xyz
           dark:
             css_override:
               source: salt://path.to.theme

 Server with two additionals plugins. It requires to have access to the Internet.

 .. code-block:: yaml

     grafana:
       server:
         enabled: true
         plugins:
           grafana-piechart-panel:
             enabled: true
           grafana-example-app:
             enabled: true

 Collector setup
 ---------------

 Used to aggregate dashboards from monitoring node.

 .. code-block:: yaml

     grafana:
       collector:
         enabled: true


 Client setups
 -------------

 Client with token based auth

 .. code-block:: yaml

     grafana:
       client:
         enabled: true
         server:
           protocol: https
           host: grafana.host
           port: 3000
           token: token

 Client with base auth

 .. code-block:: yaml

     grafana:
       client:
         enabled: true
         server:
           protocol: https
           host: grafana.host
           port: 3000
           user: admin
           password: password

 Client enforcing graphite data source

 .. code-block:: yaml

     grafana:
       client:
         enabled: true
         datasource:
           graphite:
             type: graphite
             host: mtr01.domain.com
             protocol: https
             port: 443

 Client enforcing elasticsearch data source

 .. code-block:: yaml

     grafana:
       client:
         enabled: true
         datasource:
           elasticsearch:
             type: elasticsearch
             host: log01.domain.com
             port: 80
             index: grafana-dash

 Client defined and enforced dashboard

 .. code-block:: yaml

     grafana:
       client:
         enabled: true
         server:
           host: grafana.host
           port: 3000
           token: token
         dashboard:
           system_metrics:
             title: "Generic system metrics"
             style: dark
             editable: false
             row:
               top:
                 title: "First row"

 Client enforced dashboards defined in salt-mine

 .. code-block:: yaml

     grafana:
       client:
         enabled: true
         remote_data:
           engine: salt_mine
         server:
           host: grafana.host
           port: 3000
           token: token


 Usage
 =====

 There's a difference between JSON dashboard representation and models we us.
 The lists used in JSON format [for rows, panels and target] were replaced by
 dictionaries. This form of serialization allows better merging and overrides
 of hierarchical data structures that dashboard models are.

 The default format of Grafana dashboards with lists for rows, panels and targets.

 .. code-block:: yaml

     system_metrics:
       title: graph
       editable: true
       hideControls: false
       rows:
       - title: Usage
         height: 250px
         panels:
         - title: Panel Title
           span: 6
           editable: false
           type: graph
           targets:
           - refId: A
             target: "support_prd.cfg01_iot_tcpcloud_eu.cpu.0.idle"
           datasource: graphite01
           renderer: flot
         showTitle: true

 The modified version of Grafana dashboard format with dictionary declarations.
 Please note that dictionary keys are only for logical separation and are not
 displayed in generated dashboards.

 .. code-block:: yaml

     system_metrics:
         system_metrics2:
           title: graph
           editable: true
           hideControls: false
           row:
             usage:
               title: Usage
               height: 250px
               panel:
                 usage-panel:
                   title: Panel Title
                   span: 6
                   editable: false
                   type: graph
                   target:
                     A:
                       refId: A
                       target: "support_prd.cfg01_iot_tcpcloud_eu.cpu.0.idle"
                   datasource: graphite01
                   renderer: flot
               showTitle: true


 Read more
 =========

 * http://grafana.org/
 * http://docs.grafana.org/reference/export_import/

 Documentation and Bugs
 ======================

 To learn how to install and update salt-formulas, consult the documentation
 available online at:

     http://salt-formulas.readthedocs.io/

 In the unfortunate event that bugs are discovered, they should be reported to
 the appropriate issue tracker. Use Github issue tracker for specific salt
 formula:

     https://github.com/salt-formulas/salt-formula-grafana/issues

 For feature requests, bug reports or blueprints affecting entire ecosystem,
 use Launchpad salt-formulas project:

     https://launchpad.net/salt-formulas

 You can also join salt-formulas-users team and subscribe to mailing list:

     https://launchpad.net/~salt-formulas-users

 Developers wishing to work on the salt-formulas projects should always base
 their work on master branch and submit pull request against specific formula.

     https://github.com/salt-formulas/salt-formula-grafana

 Any questions or feedback is always welcome so feel free to join our IRC
 channel:

     #salt-formulas @ irc.freenode.net

	=======
	Grafana
	=======

	A beautiful, easy to use and feature rich Graphite dashboard replacement and graph editor.


	Sample pillars
	==============


	Server deployments
	------------------

	Server installed from system package and listening on 1.2.3.4:3000 (the default
	is 0.0.0.0:3000)

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	bind:
	address: 1.2.3.4
	port: 3000
	admin:
	user: admin
	password: passwd
	database:
	engine: sqlite3

	Server installed with PostgreSQL database

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	admin:
	user: admin
	password: passwd
	database:
	engine: postgresql
	host: localhost
	port: 5432
	name: grafana
	user: grafana
	password: passwd

	Server installed with LDAP authentication and all authenticated users are
	administrators

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	admin:
	user: admin
	password: passwd
	auth:
	ldap:
	enabled: true
	host: '127.0.0.1'
	port: 389
	use_ssl: false
	bind_dn: "cn=admin,dc=grafana,dc=org"
	bind_password: "grafana"
	user_search_filter: "(cn=%s)"
	user_search_base_dns:
	- "dc=grafana,dc=org"

	Server installed with LDAP and basic authentication

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	admin:
	user: admin
	password: passwd
	auth:
	basic:
	enabled: true
	ldap:
	enabled: true
	host: '127.0.0.1'
	port: 389
	use_ssl: false
	bind_dn: "cn=admin,dc=grafana,dc=org"
	bind_password: "grafana"
	user_search_filter: "(cn=%s)"
	user_search_base_dns:
	- "dc=grafana,dc=org"

	Server installed with LDAP for authentication and authorization

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	admin:
	user: admin
	password: passwd
	auth:
	ldap:
	enabled: true
	host: '127.0.0.1'
	port: 389
	use_ssl: false
	bind_dn: "cn=admin,dc=grafana,dc=org"
	bind_password: "grafana"
	user_search_filter: "(cn=%s)"
	user_search_base_dns:
	- "dc=grafana,dc=org"
	group_search_filter: "(&(objectClass=posixGroup)(memberUid=%s))"
	group_search_base_dns:
	- "ou=groups,dc=grafana,dc=org"
	authorization:
	enabled: true
	admin_group: "admins"
	editor_group: "editors"
	viewer_group: "viewers"

	Server installed with default StackLight JSON dashboards. This will
	be replaced by the possibility for a service to provide its own dashboard
	using salt-mine.

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	dashboards:
	enabled: true
	path: /var/lib/grafana/dashboards

	Server with theme overrides

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	theme:
	light:
	css_override:
	source: http://path.to.theme
	source_hash: sha256=xyz
	build: xyz
	dark:
	css_override:
	source: salt://path.to.theme

	Server with two additionals plugins. It requires to have access to the Internet.

	.. code-block:: yaml

	grafana:
	server:
	enabled: true
	plugins:
	grafana-piechart-panel:
	enabled: true
	grafana-example-app:
	enabled: true

	Collector setup
	---------------

	Used to aggregate dashboards from monitoring node.

	.. code-block:: yaml

	grafana:
	collector:
	enabled: true


	Client setups
	-------------

	Client with token based auth

	.. code-block:: yaml

	grafana:
	client:
	enabled: true
	server:
	protocol: https
	host: grafana.host
	port: 3000
	token: token

	Client with base auth

	.. code-block:: yaml

	grafana:
	client:
	enabled: true
	server:
	protocol: https
	host: grafana.host
	port: 3000
	user: admin
	password: password

	Client enforcing graphite data source

	.. code-block:: yaml

	grafana:
	client:
	enabled: true
	datasource:
	graphite:
	type: graphite
	host: mtr01.domain.com
	protocol: https
	port: 443

	Client enforcing elasticsearch data source

	.. code-block:: yaml

	grafana:
	client:
	enabled: true
	datasource:
	elasticsearch:
	type: elasticsearch
	host: log01.domain.com
	port: 80
	index: grafana-dash

	Client defined and enforced dashboard

	.. code-block:: yaml

	grafana:
	client:
	enabled: true
	server:
	host: grafana.host
	port: 3000
	token: token
	dashboard:
	system_metrics:
	title: "Generic system metrics"
	style: dark
	editable: false
	row:
	top:
	title: "First row"

	Client enforced dashboards defined in salt-mine

	.. code-block:: yaml

	grafana:
	client:
	enabled: true
	remote_data:
	engine: salt_mine
	server:
	host: grafana.host
	port: 3000
	token: token


	Usage
	=====

	There's a difference between JSON dashboard representation and models we us.
	The lists used in JSON format [for rows, panels and target] were replaced by
	dictionaries. This form of serialization allows better merging and overrides
	of hierarchical data structures that dashboard models are.

	The default format of Grafana dashboards with lists for rows, panels and targets.

	.. code-block:: yaml

	system_metrics:
	title: graph
	editable: true
	hideControls: false
	rows:
	- title: Usage
	height: 250px
	panels:
	- title: Panel Title
	span: 6
	editable: false
	type: graph
	targets:
	- refId: A
	target: "support_prd.cfg01_iot_tcpcloud_eu.cpu.0.idle"
	datasource: graphite01
	renderer: flot
	showTitle: true

	The modified version of Grafana dashboard format with dictionary declarations.
	Please note that dictionary keys are only for logical separation and are not
	displayed in generated dashboards.

	.. code-block:: yaml

	system_metrics:
	system_metrics2:
	title: graph
	editable: true
	hideControls: false
	row:
	usage:
	title: Usage
	height: 250px
	panel:
	usage-panel:
	title: Panel Title
	span: 6
	editable: false
	type: graph
	target:
	A:
	refId: A
	target: "support_prd.cfg01_iot_tcpcloud_eu.cpu.0.idle"
	datasource: graphite01
	renderer: flot
	showTitle: true


	Read more
	=========

	* http://grafana.org/
	* http://docs.grafana.org/reference/export_import/

	Documentation and Bugs
	======================

	To learn how to install and update salt-formulas, consult the documentation
	available online at:

	http://salt-formulas.readthedocs.io/

	In the unfortunate event that bugs are discovered, they should be reported to
	the appropriate issue tracker. Use Github issue tracker for specific salt
	formula:

	https://github.com/salt-formulas/salt-formula-grafana/issues

	For feature requests, bug reports or blueprints affecting entire ecosystem,
	use Launchpad salt-formulas project:

	https://launchpad.net/salt-formulas

	You can also join salt-formulas-users team and subscribe to mailing list:

	https://launchpad.net/~salt-formulas-users

	Developers wishing to work on the salt-formulas projects should always base
	their work on master branch and submit pull request against specific formula.

	https://github.com/salt-formulas/salt-formula-grafana

	Any questions or feedback is always welcome so feel free to join our IRC
	channel:

	#salt-formulas @ irc.freenode.net