From 51662acc6c7934a2658b1d2f4dda18711583033e Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Sat, 17 Mar 2018 02:53:26 +0100 Subject: [PATCH] Clean up Grafana docs a bit (#37516) * Clean up Grafana docs a bit But more is needed, default values, missing choices, proper descriptions, actual sentences :-) * Remove validate-modules entries --- .../modules/monitoring/grafana_dashboard.py | 70 ++++---- .../modules/monitoring/grafana_datasource.py | 157 ++++++++---------- .../modules/monitoring/grafana_plugin.py | 20 +-- test/sanity/validate-modules/ignore.txt | 2 - 4 files changed, 112 insertions(+), 137 deletions(-) diff --git a/lib/ansible/modules/monitoring/grafana_dashboard.py b/lib/ansible/modules/monitoring/grafana_dashboard.py index e351204693c..98ac597883c 100644 --- a/lib/ansible/modules/monitoring/grafana_dashboard.py +++ b/lib/ansible/modules/monitoring/grafana_dashboard.py @@ -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 @@ -16,80 +16,76 @@ DOCUMENTATION = ''' --- 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: + description: + - The Grafana URL. required: true - description: - - Grafana url grafana_user: - required: false - default: admin description: - - Grafana API user + - The Grafana API user. + default: admin grafana_password: - required: false + description: + - The Grafana API password. default: admin - description: - - Grafana API password 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 diff --git a/lib/ansible/modules/monitoring/grafana_datasource.py b/lib/ansible/modules/monitoring/grafana_datasource.py index 3e8acde8576..e7aea10a71d 100644 --- a/lib/ansible/modules/monitoring/grafana_datasource.py +++ b/lib/ansible/modules/monitoring/grafana_datasource.py @@ -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 @@ -16,171 +16,152 @@ DOCUMENTATION = ''' --- 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 + - The Grafana URL. + required: true name: - required: true description: - - Name of the datasource + - The name of the datasource. + required: true ds_type: - required: true - choices: [graphite,prometheus,elasticsearch,influxdb,opentsdb,mysql,postgres] description: - - Type of the datasource + - The type of the datasource. + required: true + choices: [ elasticsearch, graphite, influxdb, mysql, opentsdb, postgres, prometheus ] url: + description: + - The URL of the datasource. required: true - description: - - Url of the datasource access: - required: false + description: + - The access mode for this datasource. + choices: [ direct, proxy ] default: proxy - choices: [proxy,direct] - description: - - Access mode for this datasource grafana_user: - required: false - default: admin description: - - Grafana API user + - The Grafana API user. + default: admin grafana_password: - required: false + description: + - The Grafana API password. default: admin - description: - - Grafana API password 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 + - This options is required when the C(ds_type) is C(influxdb), C(elasticsearch) (index name), C(mysql) or C(postgres). + required: false user: - required: false 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 + description: + - For elasticsearch C(ds_type), this is the index pattern used. choices: ['', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Yearly'] - description: - - for elasticsearch ds_type, this is the index pattern used. 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"}' diff --git a/lib/ansible/modules/monitoring/grafana_plugin.py b/lib/ansible/modules/monitoring/grafana_plugin.py index eb32cf56b91..1c2a7f65b3a 100644 --- a/lib/ansible/modules/monitoring/grafana_plugin.py +++ b/lib/ansible/modules/monitoring/grafana_plugin.py @@ -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 @@ -16,20 +16,20 @@ DOCUMENTATION = ''' --- module: grafana_plugin author: - - "Thierry Sallé (@tsalle)" + - Thierry Sallé (@tsalle) version_added: "2.5" short_description: Manage Grafana plugins via grafana-cli description: - Install and remove Grafana plugins. options: name: - required: true description: - Name of the plugin. + required: true version: description: - Version of the plugin to install. - - Default to latest + - Default to latest. grafana_plugins_dir: description: - Directory where Grafana plugin will be installed. @@ -38,19 +38,19 @@ options: - Grafana repository. If not set, gafana-cli will use the default value C(https://grafana.net/api/plugins). grafana_plugin_url: description: - - Custom Grafana plugin URL - - Require grafana 4.6.x or later + - Custom Grafana plugin URL. + - Requires grafana 4.6.x or later. state: - default: present - choices: [present, absent] description: - Status of the Grafana plugin. - If latest is set, the version parameter will be ignored. + choices: [ absent, present ] + default: present ''' EXAMPLES = ''' --- -- name: install - update Grafana piechart panel plugin +- name: Install - update Grafana piechart panel plugin grafana_plugin: name: grafana-piechart-panel version: latest diff --git a/test/sanity/validate-modules/ignore.txt b/test/sanity/validate-modules/ignore.txt index 579f0bd2801..9e7a43d666a 100644 --- a/test/sanity/validate-modules/ignore.txt +++ b/test/sanity/validate-modules/ignore.txt @@ -911,9 +911,7 @@ lib/ansible/modules/monitoring/datadog_event.py E324 lib/ansible/modules/monitoring/datadog_monitor.py E324 lib/ansible/modules/monitoring/datadog_monitor.py E325 lib/ansible/modules/monitoring/datadog_monitor.py E326 -lib/ansible/modules/monitoring/grafana_dashboard.py E325 lib/ansible/modules/monitoring/grafana_datasource.py E324 -lib/ansible/modules/monitoring/grafana_datasource.py E325 lib/ansible/modules/monitoring/icinga2_host.py E322 lib/ansible/modules/monitoring/icinga2_host.py E324 lib/ansible/modules/monitoring/logentries.py E322