Skip to content

Latest commit

 

History

History
1708 lines (969 loc) · 44.6 KB

REFERENCE.md

File metadata and controls

1708 lines (969 loc) · 44.6 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • grafana::config: Manage grafana configuration
  • grafana::install: Manage grafana installation
  • grafana::service: Manage grafana service

Resource types

Functions

  • grafana::deep_find_and_remove: == Function: deep_find_and_remove This function takes a hash as input, along with a string (key). Additionally, the optional removekey (defa
  • grafana::get_sub_paths: == Function get_sub_paths This function receives an input path as an input parameter, and returns an array of the subpaths in the input, exc

Tasks

Classes

grafana

Installs and configures Grafana.

Examples

Using the Class
class { 'grafana':
  install_method  => 'docker',
}

Parameters

The following parameters are available in the grafana class:

archive_source

Data type: Optional[String]

Download location of tarball to be used with the 'archive' install method.

Default value: undef

cfg_location

Data type: String

Location of the configuration file.

ldap_cfg

Data type: Optional[Variant[Hash,Array[Hash],Sensitive[Hash],Sensitive[Array[Hash]]]]

Default value: undef

container_cfg

Data type: Boolean

Determines whether a configuration file should be generated when using the 'docker' install method. If true, use the cfg and cfg_location parameters to control creation of the file.

Default value: false

container_params

Data type: Hash

Parameters to use when creating the Docker container. For use with the 'docker' install method. Refer to documentation of the docker::run resource in the garethr-docker module for details of available parameters.

Default value: {}

data_dir

Data type: String

The directory Grafana will use for storing its data.

Default value: '/var/lib/grafana'

install_dir

Data type: String

Installation directory to be used with the 'archive' install method.

Default value: '/usr/share/grafana'

install_method

Data type: Enum['archive', 'docker', 'package', 'repo']

Set to 'archive' to install Grafana using the tar archive. Set to 'docker' to install Grafana using the official Docker container. Set to 'package' to install Grafana using .deb or .rpm packages. Set to 'repo' to install Grafana using an apt or yum repository.

manage_package_repo

Data type: Boolean

If true this will setup the official grafana repositories on your host.

package_name

Data type: String

The name of the package managed with the 'package' install method.

package_source

Data type: Optional[String]

Download location of package to be used with the 'package' install method.

Default value: undef

service_name

Data type: String

The name of the service managed with the 'archive' and 'package' install methods.

version

Data type: String

The version of Grafana to install and manage.

Default value: 'installed'

repo_name

Data type: Enum['stable', 'beta', 'custom']

When using 'repo' install_method, the repo to look for packages in. Set to 'stable' to install only stable versions Set to 'beta' to install beta versions Set to 'custom' to install from custom repo. Use full URL

Default value: 'stable'

repo_gpg_key_url

Data type: Stdlib::HTTPUrl

When using 'repo' install_method, the repo_gpg_key_url to look for the gpg signing key of the repo.

Default value: 'https://packages.grafana.com/gpg.key'

repo_key_id

Data type: String[1]

When using 'repo' install_method, the repo_key_id of the repo_gpg_key_url key on Debian based systems.

Default value: 'B53AE77BADB630A683046005963FA27710458545'

repo_release

Data type: Optional[String[1]]

Optional value, needed on Debian based systems. If repo name is set to custom, used to identify the release of the repo. No default value.

Default value: undef

repo_url

Data type: Optional[Stdlib::HTTPUrl]

When using 'repo' install_method, the repo_url to look for packages in. Set to a custom string value to install from a custom repo.

plugins

Data type: Hash

Plugins to be passed to create_resources, wraps around the grafana_plugin resource.

Default value: {}

provisioning_dir

Data type: Stdlib::Absolutepath

Path to the grafana provisioning dir e.g /etc/grafana/provisioning

Default value: '/etc/grafana/provisioning'

provisioning_dashboards

Data type: Hash

Dashboards to provision into grafana. grafana > v5.0.0 required. Will be converted into YAML and used by grafana to provision dashboards.

Default value: {}

provisioning_datasources

Data type: Hash

Datasources to provision into grafana, grafana > v5.0.0 required. Will be converted into YAML and used by granfana to configure datasources.

Default value: {}

provisioning_dashboards_file

Data type: Stdlib::Absolutepath

Fully qualified path to place the provisioning file for dashboards, only used if provisioning_dashboards is specified.

Default value: "${provisioning_dir}/dashboards/puppetprovisioned.yaml"

provisioning_datasources_file

Data type: Stdlib::Absolutepath

Fully qualified path to place the provisioning file for datasources, only used if provisioning_datasources is specified.

Default value: "${provisioning_dir}/datasources/puppetprovisioned.yaml"

create_subdirs_provisioning

Data type: Boolean

If true puppet will create any subdirectories in the given path when provisioning dashboards.

Default value: false

sysconfig_location

Data type: Optional[String]

Location of the sysconfig file for the environment of the grafana-server service. This is only used when the install_method is 'package' or 'repo'.

sysconfig

Data type: Optional[Hash]

Environment variables for the grafana-server service

Example: sysconfig => { 'http_proxy' => 'http://proxy.example.com/' }

Default value: undef

ldap_servers

Data type: Hash[String[1], Hash]

Servers to be passed to create_resources, wraps around the grafana_ldap_server resource.

Default value: {}

ldap_group_mappings

Data type: Hash[String[1], Hash]

ldap_group_mappings Mappings to be passed to create_resources, wraps around the grafana_ldap_group_mapping resource.

Default value: {}

toml_manage_package

Data type: Boolean

ruby-toml is required to generate the TOML-based LDAP config for Grafana. Set to false if you manage package- or gem-install somewhere else.

Default value: true

toml_package_name

Data type: String[1]

Name of the software-package providing the TOML parser library.

Default value: 'ruby-toml'

toml_package_ensure

Data type: String[1]

Ensure the package-resource - e.g. installed, absent, etc. https://puppet.com/docs/puppet/latest/types/package.html#package-attribute-ensure

Default value: 'present'

toml_package_provider

Data type: Optional[String[1]]

The package-provider used to install the TOML parser library.

Default value: undef

docker_image

Data type: String

name of the docker image that provides grafana

Default value: 'grafana/grafana'

docker_ports

Data type: String

ports docker should expose

Default value: '3000:3000'

rpm_iteration

Data type: String

explicit Iteration / epoch for the rpm

Default value: '1'

cfg

Data type: Variant[Hash,Sensitive[Hash]]

The whole grafana configuration

Default value: {}

grafana::validator

Manage grafana_conn_validator resource

Parameters

The following parameters are available in the grafana::validator class:

grafana_url

Data type: Stdlib::HTTPUrl

Grafana URL.

Default value: 'http://localhost:3000'

grafana_api_path

Data type: Stdlib::Absolutepath

API path to validate with.

Default value: '/api/health'

Resource types

grafana_conn_validator

Verify connectivity to the Grafana API

Properties

The following properties are available in the grafana_conn_validator type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the grafana_conn_validator type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api/health

grafana_url

The URL of the Grafana server

Default value: http://localhost:3000

name

namevar

Arbitrary name of this resource

provider

The specific backend to use for this grafana_conn_validator resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

timeout

How long to wait for the API to be available

Default value: 20

grafana_dashboard

Manage dashboards in Grafana

Properties

The following properties are available in the grafana_dashboard type.

content

The JSON representation of the dashboard.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the grafana_dashboard type.

folder

The folder to place the dashboard in (optional)

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server (optional)

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server (optional)

organization

The organization name to create the datasource on

Default value: 1

provider

The specific backend to use for this grafana_dashboard resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

title

The title of the dashboard.

grafana_dashboard_permission

Manage dashboard permissions in Grafana

Properties

The following properties are available in the grafana_dashboard_permission type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

permission

Valid values: Admin, Edit, View

The role to apply

Parameters

The following parameters are available in the grafana_dashboard_permission type.

dashboard

Dashboard to modify permissions for

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

name

namevar

The name of the permission.

organization

The name of the organization to add permission for

Default value: Main Org.

provider

The specific backend to use for this grafana_dashboard_permission resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

team

Team to add the permission for

user

User to add the permission for

grafana_datasource

Manage datasources in Grafana

Properties

The following properties are available in the grafana_datasource type.

access_mode

Valid values: direct, proxy

Whether the datasource is accessed directly or not by the clients

basic_auth

Valid values: true, false

Whether basic auth is enabled or not

basic_auth_password

The password for basic auth if enabled

basic_auth_user

The username for basic auth if enabled

database

The name of the database (optional)

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

is_default

Valid values: true, false

Whether the datasource is the default one

json_data

Additional JSON data to configure the datasource (optional)

password

The password for the datasource (optional)

secure_json_data

Additional secure JSON data to configure the datasource (optional)

type

The datasource type

uid

An optional unique identifier for the datasource. Supported by grafana 7.3 onwards. If you do not specify this parameter, grafana will assign a uid for you

url

The URL/Endpoint of the datasource

user

The username for the datasource (optional)

with_credentials

Valid values: true, false

Whether credentials such as cookies or auth headers should be sent with cross-site requests

Parameters

The following parameters are available in the grafana_datasource type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

name

namevar

The name of the datasource.

organization

The organization name to create the datasource on

Default value: 1

provider

The specific backend to use for this grafana_datasource resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

grafana_folder

Manage folders in Grafana

Properties

The following properties are available in the grafana_folder type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

permissions

The permissions of the folder

Parameters

The following parameters are available in the grafana_folder type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server (optional)

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server (optional)

organization

The organization name to create the folder on

Default value: 1

provider

The specific backend to use for this grafana_folder resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

title

The title of the folder

uid

UID of the folder

grafana_ldap_config

Manage Grafana LDAP configuration

Parameters

The following parameters are available in the grafana_ldap_config type.

backup

Valid values: true, false, yes, no

Backup existing files before replacing them into the file-bucket

Default value: false

group

Group of the LDAP configuration file either as String or Integer (default: grafana)

Default value: grafana

mode

File-permissions mode of the LDAP configuration file as String

Default value: 0440

owner

Owner of the LDAP configuration-file either as String or Integer (default: root)

Default value: root

replace

Valid values: true, false, yes, no

Replace existing files

Default value: true

title

Path to ldap.toml

validate_cmd

A command to validate the new Grafana LDAP configuration before actually replacing it

grafana_ldap_group_mapping

Map an LDAP group to a Grafana role.

Parameters

The following parameters are available in the grafana_ldap_group_mapping type.

grafana_admin

Valid values: true, false, yes, no

Additonal flag for Grafana > v5.3 to signal admin-role to Grafana

Default value: false

group_dn

The LDAP distinguished-name of the group

ldap_server_name

The LDAP server config to apply the group-mappings on

org_role

Valid values: Admin, Editor, Viewer

The Grafana role the shall be assigned to this group

title

A unique identifier of the resource

grafana_ldap_server

Manage Grafana LDAP servers for LDAP authentication.

Parameters

The following parameters are available in the grafana_ldap_server type.

attributes

Mapping LDAP attributes to their Grafana user-account-properties (optional)

bind_dn

If the LDAP server requires authentication (i.e. non-anonymous), provide the distinguished-name (dn) here (optional)

bind_password

If the LDAP server requires authentication (i.e. non-anonymous), provide the password (optional)

client_cert

If the LDAP server requires certificate-based authentication, specify the client's certificate (for TLS and SSL, optional)

client_key

If the LDAP server requires certificate-based authentication, specify the client's certificate (for TLS and SSL, optional)

group_search_base_dns

The base-dn to be used when querying LDAP for group-accounts (optional)

group_search_filter

A search-filter to be used when querying LDAP for group-accounts (optional)

group_search_filter_user_attribute

The attribute to be used to locate matching user-accounts in the group (optional)

hosts

The servers to perform LDAP authentication at

port

The port to connect at the LDAP servers (389 for TLS/plaintext, 636 for SSL [ldaps], optional)

Default value: 389

root_ca_cert

The root ca-certificate to verify the LDAP server's SSL certificate against (for TLS and SSL, optional)

Default value: /etc/ssl/certs/ca-certificates.crt

search_base_dns

The one or more base-dn to be used when querying LDAP for user-accounts (optional)

Default value: []

search_filter

A search-filter to be used when querying LDAP for user-accounts (optional)

ssl_skip_verify

Valid values: true, false, yes, no

Set to true to disable verification of the LDAP server's SSL certificate (for TLS and SSL, optional)

Default value: false

start_tls

Valid values: true, false, yes, no

Set to true if you want to perform LDAP via a TLS-connection (not meant to be for SSL, optional)

Default value: true

title

A unique identified for this LDAP server.

use_ssl

Valid values: true, false, yes, no

Set to true if you want to perform LDAP via a SSL-connection (not meant to be for TLS, optional)

Default value: false

grafana_membership

Manage resource memberships in Grafana

Properties

The following properties are available in the grafana_membership type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

role

Valid values: Admin, Editor, Viewer

The role to apply to the membership (Admin, Editor, Viewer)

Parameters

The following parameters are available in the grafana_membership type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

membership_type

Valid values: organization, team

The underlying type of the membership (organization, team)

name

namevar

The name of the membership.

organization

The name of the organization to add membership for (team only)

Default value: Main Org.

provider

The specific backend to use for this grafana_membership resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

target_name

The name of the target to add membership for

user_name

The name of the user to add membership for

grafana_notification

Manage notification in Grafana

Properties

The following properties are available in the grafana_notification type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

frequency

The notification reminder frequency

is_default

Valid values: true, false

Whether the notification is the default one

Default value: false

send_reminder

Valid values: true, false

Whether automatic message resending is enabled or not

Default value: false

settings

Additional JSON data to configure the notification

type

The notification type

Parameters

The following parameters are available in the grafana_notification type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

name

namevar

The name of the notification.

provider

The specific backend to use for this grafana_notification resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

grafana_organization

Manage organizations in Grafana

Properties

The following properties are available in the grafana_organization type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the grafana_organization type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

name

namevar

The name of the organization.

provider

The specific backend to use for this grafana_organization resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

grafana_plugin

manages grafana plugins

Examples

Install a grafana plugin
grafana_plugin { 'grafana-simple-json-datasource': }
Install a grafana plugin from different repo
grafana_plugin { 'grafana-simple-json-datasource':
  ensure => 'present',
  repo   => 'https://nexus.company.com/grafana/plugins',
}
Install a grafana plugin from a plugin url
grafana_plugin { 'grafana-example-custom-plugin':
  ensure     => 'present',
  plugin_url => 'https://github.com/example/example-custom-plugin/zipball/v1.0.0'
}
Uninstall a grafana plugin
grafana_plugin { 'grafana-simple-json-datasource':
  ensure => 'absent',
}
Show resources
$ puppet resource grafana_plugin

Properties

The following properties are available in the grafana_plugin type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the grafana_plugin type.

name

Valid values: %r{^\S+$}

namevar

The name of the plugin to enable

plugin_url

Full url to the plugin zip file

provider

The specific backend to use for this grafana_plugin resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

repo

The URL of an internal plugin server

grafana_team

Manage teams in Grafana

Properties

The following properties are available in the grafana_team type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

home_dashboard

The id or name of the home dashboard

Default value: Default

home_dashboard_folder

The UID or name of the home dashboard folder

theme

The theme to use for the team

timezone

The timezone to use for the team

Parameters

The following parameters are available in the grafana_team type.

email

The email for the team

Default value: ''

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

name

namevar

The name of the team

organization

The organization the team belongs to

Default value: Main Org.

provider

The specific backend to use for this grafana_team resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

grafana_user

Manage users in Grafana

Properties

The following properties are available in the grafana_user type.

email

The email for the user

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

full_name

The full name of the user.

is_admin

Valid values: true, false

Whether the user is a grafana admin

organizations

A hash of organizations and roles

password

The password for the user

theme

The theme for the user

Parameters

The following parameters are available in the grafana_user type.

grafana_api_path

The absolute path to the API endpoint

Default value: /api

grafana_password

The password for the Grafana server

grafana_url

The URL of the Grafana server

Default value: ''

grafana_user

The username for the Grafana server

name

namevar

The username of the user.

provider

The specific backend to use for this grafana_user resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

Functions

grafana::deep_find_and_remove

Type: Ruby 4.x API

== Function: deep_find_and_remove

This function takes a hash as input, along with a string (key). Additionally, the optional removekey (defaults to 'puppetsource') is a parameter.

The purpose of this function is to extract the 'options' subhash from the array of hashes given to provision dashboards. This options subhash may contain a path and source which puppet will use for provisioning: creating the path and applying the files from the source.

Additionally, if the key 'puppetsource' exists in the sub-hash, it will be deleted from the structure. Thus the output of this function may be used in yaml format for grafana's provisioning configuration file for dashboards.

grafana::deep_find_and_remove(String $key, Hash $object, Optional[String] $removekey)

== Function: deep_find_and_remove

This function takes a hash as input, along with a string (key). Additionally, the optional removekey (defaults to 'puppetsource') is a parameter.

The purpose of this function is to extract the 'options' subhash from the array of hashes given to provision dashboards. This options subhash may contain a path and source which puppet will use for provisioning: creating the path and applying the files from the source.

Additionally, if the key 'puppetsource' exists in the sub-hash, it will be deleted from the structure. Thus the output of this function may be used in yaml format for grafana's provisioning configuration file for dashboards.

Returns: Array

key

Data type: String

object

Data type: Hash

removekey

Data type: Optional[String]

grafana::get_sub_paths

Type: Ruby 4.x API

== Function get_sub_paths

This function receives an input path as an input parameter, and returns an array of the subpaths in the input, excluding the input path itself. The function will attempt to ignore any extra slashes in the path given.

This function will only work on UNIX paths with forward slashes (/).

Examples: input = '/var/lib/grafana/dashboards' output = [ '/var', '/var/lib', '/var/lib/grafana'/ ]

input = '/opt' output = []

input = '/first/second/' output = [ '/first' ]

grafana::get_sub_paths(String $inputpath)

== Function get_sub_paths

This function receives an input path as an input parameter, and returns an array of the subpaths in the input, excluding the input path itself. The function will attempt to ignore any extra slashes in the path given.

This function will only work on UNIX paths with forward slashes (/).

Examples: input = '/var/lib/grafana/dashboards' output = [ '/var', '/var/lib', '/var/lib/grafana'/ ]

input = '/opt' output = []

input = '/first/second/' output = [ '/first' ]

Returns: Array

inputpath

Data type: String

Tasks

change_grafana_admin_password

Change the Grafana admin user's password

Supports noop? false

Parameters

old_password

Data type: Optional[String[1]]

The old admin password

new_password

Data type: Optional[String[1]]

The new admin password

uri

Data type: Enum['http','https']

http or https

port

Data type: Integer

The port Grafana is running on