Skip to content

Commit

Permalink
Clean up Grafana docs a bit (#37516)
Browse files Browse the repository at this point in the history 
* Clean up Grafana docs a bit

But more is needed, default values, missing choices, proper
descriptions, actual sentences :-)

* Remove validate-modules entries
  • Loading branch information
@dagwieers
dagwieers committed Mar 17, 2018
1 parent 775e8ed commit 51662ac
Show file tree
Hide file tree
Showing 4 changed files with 112 additions and 137 deletions.
70 changes: 33 additions & 37 deletions lib/ansible/modules/monitoring/grafana_dashboard.py
View file
@@ -1,7 +1,7 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
#
# Copyright 2017, Thierry Sallé (@tsalle)

# Copyright: (c) 2017, Thierry Sallé (@tsalle)
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
Expand All @@ -16,80 +16,76 @@
---
module: grafana_dashboard
author:
- "Thierry Sallé (@tsalle)"
- Thierry Sallé (@tsalle)
version_added: "2.5"
short_description: Manage grafana dashboards
short_description: Manage Grafana dashboards
description:
- Create, update, delete, export grafana dashboards via API
- Create, update, delete, export Grafana dashboards via API.
options:
grafana_url:
required: true
description:
- Grafana url
- The Grafana URL.
required: true
grafana_user:
required: false
default: admin
description:
- Grafana API user
grafana_password:
required: false
- The Grafana API user.
default: admin
grafana_password:
description:
- Grafana API password
- The Grafana API password.
default: admin
grafana_api_key:
required: false
description:
- Grafana API key
- If set, I(grafana_user) and I(grafana_password) will be ignored
- The Grafana API key.
- If set, I(grafana_user) and I(grafana_password) will be ignored.
org_id:
required: false
description:
- Grafana Organisation ID where the dashboard will be imported / exported
- Not used when I(grafana_api_key) is set, because the grafana_api_key only belong to one organisation.
- The Grafana Organisation ID where the dashboard will be imported / exported.
- Not used when I(grafana_api_key) is set, because the grafana_api_key only belong to one organisation..
default: 1
state:
required: true
default: present
description:
- State of the dashboard.
choices: ['present', 'absent', 'export']
required: true
choices: [ absent, export, present ]
default: present
slug:
description:
- slug of the dashboard. It's the friendly url name of the dashboard.
- When state is present, this parameter can override the slug in the meta section of the json file.
- When C(state) is C(present), this parameter can override the slug in the meta section of the json file.
- If you want to import a json dashboard exported directly from the interface (not from the api),
- you have to specify the slug parameter because there is no meta section in the exported json.
you have to specify the slug parameter because there is no meta section in the exported json.
path:
description:
- path to the json file containing the grafana dashboard to import or export.
- The path to the json file containing the Grafana dashboard to import or export.
overwrite:
default: false
description:
- override existing dashboard when state is present.
- Override existing dashboard when state is present.
type: bool
default: 'no'
message:
description:
- Set a commit message for the version history.
- Only used when state is present
- Only used when C(state) is C(present).
validate_certs:
default: true
type: bool
description:
- If C(no), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
- If C(no), SSL certificates will not be validated.
- This should only be used on personally controlled sites using self-signed certificates.
type: bool
default: 'yes'
'''

EXAMPLES = '''
---
- name: import grafana dashboard foo
- name: Import Grafana dashboard foo
grafana_dashboard:
grafana_url: http://grafana.company.com
grafana_api_key: XXXXXXXXXXXX
state: present
message: "updated by ansible"
overwrite: true
message: Updated by ansible
overwrite: yes
path: /path/to/dashboards/foo.json
- name: export dashboard
- name: Export dashboard
grafana_dashboard:
grafana_url: http://grafana.company.com
grafana_api_key: XXXXXXXXXXXX
Expand Down
157 changes: 69 additions & 88 deletions lib/ansible/modules/monitoring/grafana_datasource.py
View file
@@ -1,7 +1,7 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
#
# Copyright 2017, Thierry Sallé (@tsalle)

# Copyright: (c) 2017, Thierry Sallé (@tsalle)
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
Expand All @@ -16,171 +16,152 @@
---
module: grafana_datasource
author:
- "Thierry Sallé (@tsalle)"
- Thierry Sallé (@tsalle)
version_added: "2.5"
short_description: Manage grafana datasources
short_description: Manage Grafana datasources
description:
- Create/update/delete grafana datasources via API
- Create/update/delete Grafana datasources via API.
options:
grafana_url:
required: true
description:
- Grafana url
name:
- The Grafana URL.
required: true
name:
description:
- Name of the datasource
ds_type:
- The name of the datasource.
required: true
choices: [graphite,prometheus,elasticsearch,influxdb,opentsdb,mysql,postgres]
ds_type:
description:
- Type of the datasource
url:
- The type of the datasource.
required: true
choices: [ elasticsearch, graphite, influxdb, mysql, opentsdb, postgres, prometheus ]
url:
description:
- Url of the datasource
- The URL of the datasource.
required: true
access:
required: false
default: proxy
choices: [proxy,direct]
description:
- Access mode for this datasource
- The access mode for this datasource.
choices: [ direct, proxy ]
default: proxy
grafana_user:
required: false
default: admin
description:
- Grafana API user
grafana_password:
required: false
- The Grafana API user.
default: admin
grafana_password:
description:
- Grafana API password
- The Grafana API password.
default: admin
grafana_api_key:
required: false
description:
- Grafana API key
- If set, grafana_user and grafana_password will be ignored
- The Grafana API key.
- If set, C(grafana_user) and C(grafana_password) will be ignored.
database:
required: false
description:
- Name of the database for the datasource.
- This options is required when the ds_type is influxdb, elasticsearch (index name), mysql or postgres
user:
- This options is required when the C(ds_type) is C(influxdb), C(elasticsearch) (index name), C(mysql) or C(postgres).
required: false
user:
description:
- Datasource login user for influxdb datasources
- The datasource login user for influxdb datasources.
password:
required: false
description:
- Datasource password
- The datasource password
basic_auth_user:
required: false
description:
- Datasource basic auth user.
- The datasource basic auth user.
- Setting this option with basic_auth_password will enable basic auth.
basic_auth_password:
required: false
description:
- Datasource basic auth password, when basic auth is true
- The datasource basic auth password, when C(basic auth) is C(yes).
with_credentials:
required: false
default: false
description:
- Whether credentials such as cookies or auth headers should be sent with cross-site requests.
type: bool
default: 'no'
tls_client_cert:
required: false
description:
- client tls certificate.
- If tls_client_cert and tls_client_key are set, this will enable tls auth.
- begins with ----- BEGIN CERTIFICATE -----
- The client TLS certificate.
- If C(tls_client_cert) and C(tls_client_key) are set, this will enable TLS authentication.
- Starts with ----- BEGIN CERTIFICATE -----
tls_client_key:
required: false
description:
- client tls private key
- befins with ----- BEGIN RSA PRIVATE KEY -----
- The client TLS private key
- Starts with ----- BEGIN RSA PRIVATE KEY -----
tls_ca_cert:
required: false
description:
- tls ca certificate for self signed certificates.
- only used when tls_client_cert and tls_client_key are set
- The TLS CA certificate for self signed certificates.
- Only used when C(tls_client_cert) and C(tls_client_key) are set.
is_default:
required: false
default: false
description:
- Make this datasource the default one
- Make this datasource the default one.
type: bool
default: 'no'
org_id:
required: false
description:
- Grafana Organisation ID in which the datasource should be created
- Not used when grafana_api_key is set, because the grafana_api_key only belong to one organisation.
- Grafana Organisation ID in which the datasource should be created.
- Not used when C(grafana_api_key) is set, because the C(grafana_api_key) only belong to one organisation.
default: 1
state:
required: false
default: present
choices: [present, absent]
description:
- Status of the datasource
choices: [ absent, present ]
default: present
es_version:
required: false
default: 5
choices: [2, 5, 56]
description:
- Elasticsearch version (for ds_type = elasticsearch only)
- Version 56 is for elasticsearch 5.6+ where tou can specify the max_concurrent_shard_requests option.
- Elasticsearch version (for C(ds_type = elasticsearch) only)
- Version 56 is for elasticsearch 5.6+ where tou can specify the C(max_concurrent_shard_requests) option.
choices: [ 2, 5, 56 ]
default: 5
max_concurrent_shard_requests:
required: false
default: 256
description:
- Starting with elasticsearch 5.6, you can specify the max concurrent shard per requests.
default: 256
time_field:
required: false
default: timestamp
description:
- Name of the time field in elasticsearch ds
- Name of the time field in elasticsearch ds.
- For example C(@timestamp)
default: timestamp
time_interval:
required: false
description:
- Minimum group by interval for influxdb or elasticsearch datasources
- for example '>10s'
- Minimum group by interval for C(influxdb) or C(elasticsearch) datasources.
- for example C(>10s)
interval:
required: false
choices: ['', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Yearly']
description:
- for elasticsearch ds_type, this is the index pattern used.
- For elasticsearch C(ds_type), this is the index pattern used.
choices: ['', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Yearly']
tsdb_version:
required: false
choices: [1, 2, 3]
description:
- opentsdb version (1 for <= 2.1, 2 for ==2.2, 3 for ==2.3)
- The opentsdb version.
- Use C(1) for <=2.1, C(2) for ==2.2, C(3) for ==2.3.
choices: [ 1, 2, 3 ]
default: 1
tsdb_resolution:
required: false
choices: [second, millisecond]
description:
- opentsdb time resolution
default: 1
- The opentsdb time resolution.
choices: [ millisecond, second ]
default: second
sslmode:
choices: ['disable','require','verify-ca','verify-full']
description:
- SSL mode for postgres datasoure type.
- SSL mode for C(postgres) datasoure type.
choices: [ disable, require, verify-ca, verify-full ]
validate_certs:
required: false
default: True
description:
- Validate or not grafana certificate
- Whether to validate the Grafana certificate.
type: bool
default: 'yes'
'''

EXAMPLES = '''
---
- name: create elasticsearch datasource
- name: Create elasticsearch datasource
grafana_datasource:
name: my_elastic
grafana_url: http://grafana.company.com
type: elasticsearch
url: https://elasticsearch.company.com:9200
database: my-index_*
basic_auth: true
basic_auth: yes
basic_auth_user: grafana
basic_auth_password: xxxxxxxx
json_data: '{"esVersion":5, "timeField": "@timestamp"}'
Expand Down

0 comments on commit 51662ac

Please sign in to comment.