From 97262fb8fcaf548d87e3e81775bc491bd24664c9 Mon Sep 17 00:00:00 2001 From: ndeevy <30370363+ndeevy@users.noreply.github.com> Date: Tue, 3 Nov 2020 11:09:49 +0000 Subject: [PATCH] Docs: Made usage of config/configuration consistent #19270 (#28167) Rebased ndeevy:docs-config/configuration-consistency-update from grafana/master to resolve conflicts Co-authored-by: ndeevy --- docs/sources/administration/cli.md | 2 +- docs/sources/administration/provisioning.md | 4 ++-- docs/sources/administration/security.md | 2 +- docs/sources/alerting/create-alerts.md | 2 +- docs/sources/auth/ldap.md | 5 ++--- docs/sources/datasources/azuremonitor.md | 2 +- docs/sources/developers/plugins/legacy/apps.md | 2 +- docs/sources/developers/plugins/legacy/review-guidelines.md | 4 ++-- docs/sources/developers/plugins/migration-guide.md | 2 +- docs/sources/enterprise/saml.md | 2 +- docs/sources/http_api/admin.md | 2 +- docs/sources/http_api/org.md | 2 +- docs/sources/installation/upgrading.md | 6 +++--- docs/sources/whatsnew/whats-new-in-v2-1.md | 3 +-- docs/sources/whatsnew/whats-new-in-v4-1.md | 2 +- docs/sources/whatsnew/whats-new-in-v4.md | 2 +- docs/sources/whatsnew/whats-new-in-v5-3.md | 2 +- docs/sources/whatsnew/whats-new-in-v6-1.md | 4 ++-- 18 files changed, 24 insertions(+), 26 deletions(-) diff --git a/docs/sources/administration/cli.md b/docs/sources/administration/cli.md index 98322332c58..f5edd13ce8e 100644 --- a/docs/sources/administration/cli.md +++ b/docs/sources/administration/cli.md @@ -112,7 +112,7 @@ grafana-cli --debug plugins install `--configOverrides` is a command line argument that acts like an environmental variable override. -For example, you can use it to redirect logging to another file (maybe to log plugin installations in Grafana Cloud) or when resetting the admin password and you have non-default values for some important config value (like where the database is located). +For example, you can use it to redirect logging to another file (maybe to log plugin installations in Grafana Cloud) or when resetting the admin password and you have non-default values for some important configuration value (like where the database is located). **Example:** ```bash diff --git a/docs/sources/administration/provisioning.md b/docs/sources/administration/provisioning.md index 24ad4741d8b..0093bc18f15 100644 --- a/docs/sources/administration/provisioning.md +++ b/docs/sources/administration/provisioning.md @@ -30,9 +30,9 @@ Check out the [configuration]({{< relref "configuration.md" >}}) page for more i ### Using Environment Variables -It is possible to use environment variable interpolation in all 3 provisioning config types. Allowed syntax +It is possible to use environment variable interpolation in all 3 provisioning configuration types. Allowed syntax is either `$ENV_VAR_NAME` or `${ENV_VAR_NAME}` and can be used only for values not for keys or bigger parts -of the configs. It is not available in the dashboard's definition files just the dashboard provisioning +of the configurations. It is not available in the dashboard's definition files just the dashboard provisioning configuration. Example: diff --git a/docs/sources/administration/security.md b/docs/sources/administration/security.md index 445b2eb1506..247915abc6f 100644 --- a/docs/sources/administration/security.md +++ b/docs/sources/administration/security.md @@ -39,5 +39,5 @@ Users with the Viewer role can enter *any possible query* in *any* of the data s To address this vulnerability, you can restrict data source query access in the following ways: -- Create multiple data sources with some restrictions added in data source config that restrict access (like database name or credentials). Then use the [Data Source Permissions]({{< relref "../permissions/datasource_permissions.md" >}}) Enterprise feature to restrict user access to the data source in Grafana. +- Create multiple data sources with some restrictions added in data source configuration that restrict access (like database name or credentials). Then use the [Data Source Permissions]({{< relref "../permissions/datasource_permissions.md" >}}) Enterprise feature to restrict user access to the data source in Grafana. - Create a separate Grafana organization, and in that organization, create a separate data source. Make sure the data source has some option/user/credentials setting that limits access to a subset of the data. Not all data sources have an option to limit access. diff --git a/docs/sources/alerting/create-alerts.md b/docs/sources/alerting/create-alerts.md index abd1bea786e..262c2906479 100644 --- a/docs/sources/alerting/create-alerts.md +++ b/docs/sources/alerting/create-alerts.md @@ -42,7 +42,7 @@ This section describes the fields you fill out to create an alert. - **Evaluate every -** Specify how often the scheduler should evaluate the alert rule. This is referred to as the _evaluation interval_. - **For -** Specify how long the query needs to violate the configured thresholds before the alert notification triggers. -You can set a minimum evaluation interval in the `alerting.min_interval_seconds` config field, to set a minimum time between evaluations. Refer to [Configuration]({{< relref "../administration/configuration.md" >}}#min-interval-seconds) for more information. +You can set a minimum evaluation interval in the `alerting.min_interval_seconds` configuration field, to set a minimum time between evaluations. Refer to [Configuration]({{< relref "../administration/configuration.md" >}}#min-interval-seconds) for more information. > **Caution:** Do not use `For` with the `If no data or all values are null` setting set to `No Data`. The triggering of `No Data` will trigger instantly and not take `For` into consideration. This may also result in that an OK notification not being sent if alert transitions from `No Data -> Pending -> OK`. diff --git a/docs/sources/auth/ldap.md b/docs/sources/auth/ldap.md index a4856be3231..facac356c74 100644 --- a/docs/sources/auth/ldap.md +++ b/docs/sources/auth/ldap.md @@ -94,7 +94,7 @@ email = "email" ### Using environment variables -You can interpolate variables in the TOML config from environment variables. For instance, you could externalize your `bind_password` that way: +You can interpolate variables in the TOML configuration from environment variables. For instance, you could externalize your `bind_password` that way: ```bash bind_password = "${LDAP_ADMIN_PASSWORD}" @@ -161,8 +161,7 @@ In `[[servers.group_mappings]]` you can map an LDAP group to a Grafana organizat the authoritative source. So, if you change a user's role in the Grafana Org. Users page, this change will be reset the next time the user logs in. If you change the LDAP groups of a user, the change will take effect the next time the user logs in. -The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the -TOML config will be used. +The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the TOML configuration will be used. **LDAP specific configuration file (ldap.toml) example:** ```bash diff --git a/docs/sources/datasources/azuremonitor.md b/docs/sources/datasources/azuremonitor.md index 37df276e380..0348b420547 100644 --- a/docs/sources/datasources/azuremonitor.md +++ b/docs/sources/datasources/azuremonitor.md @@ -47,7 +47,7 @@ The data source can access metrics from four different services. You can configu - The Subscription Id can be changed per query. Save the data source and refresh the page to see the list of subscriptions available for the specified Client Id. -1. If you are also using the Azure Log Analytics service, then you need to specify these two config values (or you can reuse the Client Id and Secret from the previous step). +1. If you are also using the Azure Log Analytics service, then you need to specify these two configuration values (or you can reuse the Client Id and Secret from the previous step). - Client Id (Azure Active Directory -> App Registrations -> Choose your app -> Application ID) - Client Secret (Azure Active Directory -> App Registrations -> Choose your app -> Keys -> Create a key -> Use client secret) diff --git a/docs/sources/developers/plugins/legacy/apps.md b/docs/sources/developers/plugins/legacy/apps.md index 4bca36ca875..ad9728dfeed 100644 --- a/docs/sources/developers/plugins/legacy/apps.md +++ b/docs/sources/developers/plugins/legacy/apps.md @@ -15,7 +15,7 @@ Data source and panel plugins will show up like normal plugins. The app pages wi ## Enabling app plugins -After installing an app, it has to be enabled before it shows up as a data source or panel. You can do that on the app page in the config tab. +After installing an app, it has to be enabled before it shows up as a data source or panel. You can do that on the app page in the configuration tab. ## Developing an App Plugin diff --git a/docs/sources/developers/plugins/legacy/review-guidelines.md b/docs/sources/developers/plugins/legacy/review-guidelines.md index 572fbd29500..b0d93a3d2b4 100644 --- a/docs/sources/developers/plugins/legacy/review-guidelines.md +++ b/docs/sources/developers/plugins/legacy/review-guidelines.md @@ -135,7 +135,7 @@ Use the `width-x` and `max-width-x` classes to control the width of your labels ## Data Sources For more information about data sources, refer to the [basic guide for data sources](http://docs.grafana.org/plugins/developing/datasources/). -### Config Page Guidelines +### Configuration Page Guidelines - It should be as easy as possible for a user to configure a URL. If the data source is using the `datasource-http-settings` component, it should use the `suggest-url` attribute to suggest the default URL or a URL that is similar to what it should be (especially important if the URL refers to a REST endpoint that is not common knowledge for most users e.g. `https://yourserver:4000/api/custom-endpoint`). @@ -155,7 +155,7 @@ If possible, any passwords or secrets should be saved in the `secureJsonData` bl Read more here about how [authentication for data sources]({{< relref "../add-authentication-for-data-source-plugins.md" >}}) works. -If using the proxy feature, the Config page should use the `secureJsonData` blob like this: +If using the proxy feature, the Configuration page should use the `secureJsonData` blob like this: - good: `` - bad: `` diff --git a/docs/sources/developers/plugins/migration-guide.md b/docs/sources/developers/plugins/migration-guide.md index 596997dff7e..990531ec9be 100644 --- a/docs/sources/developers/plugins/migration-guide.md +++ b/docs/sources/developers/plugins/migration-guide.md @@ -127,7 +127,7 @@ export const MyPanel: React.FC = ({ options, data, width, height }) => { While all plugins are different, we'd like to share a migration process that has worked for some of our users. -1. Define your configuration model and `ConfigEditor`. For many plugins, the config editor is the simplest component so it's a good candidate to start with. +1. Define your configuration model and `ConfigEditor`. For many plugins, the configuration editor is the simplest component so it's a good candidate to start with. 1. Implement the `testDatasource()` method on the class that extends `DataSourceApi` using the settings in your configuration model to make sure you can successfully configure and access the external API. 1. Implement the `query()` method. At this point, you can hard-code your query, because we haven’t yet implemented the query editor. The `query()` method supports both the new data frame response and the old TimeSeries response, so don’t worry about converting to the new format just yet. 1. Implement the `QueryEditor`. How much work this requires depends on how complex your query model is. diff --git a/docs/sources/enterprise/saml.md b/docs/sources/enterprise/saml.md index 82a6522fe5b..bc5c0a78e0b 100644 --- a/docs/sources/enterprise/saml.md +++ b/docs/sources/enterprise/saml.md @@ -185,7 +185,7 @@ Organization mapping allows you to assign users to particular organization in Gr 1. In configuration file, set [`assertion_attribute_org`]({{< relref "./enterprise-configuration.md#assertion-attribute-org" >}}) to the attribute name you store organization info in. 1. Set [`org_mapping`]({{< relref "./enterprise-configuration.md#org-mapping" >}}) option to the comma-separated list of `Organization:OrgId` pairs to map organization from IdP to Grafana organization specified by id. -For example, use following config to assign users from `Engineering` organization to the Grafana organization with id `2` and users from `Sales` - to the org with id `3`, based on `Org` assertion attribute value: +For example, use following configuration to assign users from `Engineering` organization to the Grafana organization with id `2` and users from `Sales` - to the org with id `3`, based on `Org` assertion attribute value: ```bash [auth.saml] diff --git a/docs/sources/http_api/admin.md b/docs/sources/http_api/admin.md index 1b234ac982a..69c72f41890 100644 --- a/docs/sources/http_api/admin.md +++ b/docs/sources/http_api/admin.md @@ -471,7 +471,7 @@ Content-Type: application/json Reloads the provisioning config files for specified type and provision entities again. It won't return until the new provisioned entities are already stored in the database. In case of dashboards, it will stop -polling for changes in dashboard files and then restart it with new configs after returning. +polling for changes in dashboard files and then restart it with new configurations after returning. Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation. diff --git a/docs/sources/http_api/org.md b/docs/sources/http_api/org.md index 74469520eb6..dbf1c7dfc5d 100644 --- a/docs/sources/http_api/org.md +++ b/docs/sources/http_api/org.md @@ -309,7 +309,7 @@ Content-Type: application/json ``` Note: The api will work in the following two ways 1) Need to set GF_USERS_ALLOW_ORG_CREATE=true -2) Set the config users.allow_org_create to true in ini file +2) Set the config value users.allow_org_create to true in ini file **Example Response**: diff --git a/docs/sources/installation/upgrading.md b/docs/sources/installation/upgrading.md index 244e565588e..cecb4391175 100755 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -21,7 +21,7 @@ Upgrading is generally safe (between many minor and one major version) and dashb We recommend that you backup a few things in case you have to rollback the upgrade. - Installed plugins - Back them up before you upgrade them in case you want to rollback the Grafana version and want to get the exact same versions you were running before the upgrade. -- Configuration files do not need to be backed up. However, you might want to in case you add new config options after upgrade and then rollback. +- Configuration files do not need to be backed up. However, you might want to in case you add new configuration options after upgrade and then rollback. ### Database backup @@ -82,7 +82,7 @@ sudo apt-get upgrade If you downloaded the binary `.tar.gz` package, then you can just download and extract the new package and overwrite all your existing files. However, this might overwrite your config changes. -We recommend that you save your custom config changes in a file named `/conf/custom.ini`. +We recommend that you save your custom configuration changes in a file named `/conf/custom.ini`. This allows you to upgrade Grafana without risking losing your configuration changes. ### Centos / RHEL @@ -108,7 +108,7 @@ docker run -d --name=my-grafana-container --restart=always -v /var/lib/grafana:/ ### Windows -If you downloaded the Windows binary package you can just download a newer package and extract to the same location (and overwrite the existing files). This might overwrite your config changes. We recommend that you save your config changes in a file named `/conf/custom.ini` as this will make upgrades easier without risking losing your config changes. +If you downloaded the Windows binary package you can just download a newer package and extract to the same location (and overwrite the existing files). This might overwrite your configuration changes. We recommend that you save your configuration changes in a file named `/conf/custom.ini` as this will make upgrades easier without risking losing your configuration changes. ## Update plugins diff --git a/docs/sources/whatsnew/whats-new-in-v2-1.md b/docs/sources/whatsnew/whats-new-in-v2-1.md index 86567d7ac5f..223f4f7c3b8 100644 --- a/docs/sources/whatsnew/whats-new-in-v2-1.md +++ b/docs/sources/whatsnew/whats-new-in-v2-1.md @@ -61,7 +61,7 @@ You can also specify mappings between LDAP group memberships and Grafana Organiz ### Basic Auth Support You can now authenticate against the Grafana API utilizing a simple username and password with basic HTTP authentication. -> **Note:** This can be useful for provisioning and config management systems that need +> **Note:** This can be useful for provisioning and configuring management systems that need > to utilize the API without having to create an API key. @@ -129,4 +129,3 @@ string values. ### Changelog For a detailed list and link to github issues for everything included in the 2.1 release please view the [CHANGELOG.md](https://github.com/grafana/grafana/blob/master/CHANGELOG.md) file. - diff --git a/docs/sources/whatsnew/whats-new-in-v4-1.md b/docs/sources/whatsnew/whats-new-in-v4-1.md index d0d71060e53..790aee8a3b6 100644 --- a/docs/sources/whatsnew/whats-new-in-v4-1.md +++ b/docs/sources/whatsnew/whats-new-in-v4-1.md @@ -15,7 +15,7 @@ weight = 3 - **Graph**: Support for shared tooltip on all graphs as you hover over one graph. [#1578](https://github.com/grafana/grafana/pull/1578), [#6274](https://github.com/grafana/grafana/pull/6274) - **Victorops**: Add VictorOps notification integration [#6411](https://github.com/grafana/grafana/issues/6411), thx [@ichekrygin](https://github.com/ichekrygin) - **Opsgenie**: Add OpsGenie notification integratiion [#6687](https://github.com/grafana/grafana/issues/6687), thx [@kylemcc](https://github.com/kylemcc) -- **Cloudwatch**: Make it possible to specify access and secret key on the data source config page [#6697](https://github.com/grafana/grafana/issues/6697) +- **Cloudwatch**: Make it possible to specify access and secret key on the data source configuration page [#6697](https://github.com/grafana/grafana/issues/6697) - **Elasticsearch**: Added support for Elasticsearch 5.x [#5740](https://github.com/grafana/grafana/issues/5740), thx [@lpic10](https://github.com/lpic10) - **Panel**: Added help text for panels. [#4079](https://github.com/grafana/grafana/issues/4079), thx [@utkarshcmu](https://github.com/utkarshcmu) - [Full changelog](https://github.com/grafana/grafana/blob/master/CHANGELOG.md) diff --git a/docs/sources/whatsnew/whats-new-in-v4.md b/docs/sources/whatsnew/whats-new-in-v4.md index abe5a0ac40c..ca694c4a5c5 100644 --- a/docs/sources/whatsnew/whats-new-in-v4.md +++ b/docs/sources/whatsnew/whats-new-in-v4.md @@ -38,7 +38,7 @@ on but will be not ready for v4 release. {{< imgbox max-width="40%" img="/img/docs/v4/alerting_conditions.png" caption="Alerting Conditions" >}} -The rule config allows you to specify a name, how often the rule should be evaluated and a series +The rule configuration allows you to specify a name, how often the rule should be evaluated and a series of conditions that all need to be true for the alert to fire. Currently the only condition type that exists is a `Query` condition that allows you to diff --git a/docs/sources/whatsnew/whats-new-in-v5-3.md b/docs/sources/whatsnew/whats-new-in-v5-3.md index 3cb8fac533d..feae52d43db 100644 --- a/docs/sources/whatsnew/whats-new-in-v5-3.md +++ b/docs/sources/whatsnew/whats-new-in-v5-3.md @@ -29,7 +29,7 @@ Grafana v5.3 brings new features, many enhancements and bug fixes. This article Grafana v5.3 ships with built-in support for [Google Stackdriver](https://cloud.google.com/stackdriver/) and enables you to visualize your Stackdriver metrics in Grafana. -Getting started with the plugin is easy. Simply create a GCE Service account that has access to the Stackdriver API scope, download the Service Account key file from Google and upload it on the Stackdriver data source config page in Grafana and you should have a secure server-to-server authentication setup. Like other core plugins, Stackdriver has built-in support for alerting. It also comes with support for heatmaps and basic variables. +Getting started with the plugin is easy. Simply create a GCE Service account that has access to the Stackdriver API scope, download the Service Account key file from Google and upload it on the Stackdriver data source configuration page in Grafana and you should have a secure server-to-server authentication setup. Like other core plugins, Stackdriver has built-in support for alerting. It also comes with support for heatmaps and basic variables. If you're already accustomed to the Stackdriver Metrics Explorer UI, you'll notice that there are a lot of similarities to the query editor in Grafana. It is possible to add filters using wildcards and regular expressions. You can do Group By, Primary Aggregation and Alignment. diff --git a/docs/sources/whatsnew/whats-new-in-v6-1.md b/docs/sources/whatsnew/whats-new-in-v6-1.md index b8b8c3f7867..4934cc2b1bd 100644 --- a/docs/sources/whatsnew/whats-new-in-v6-1.md +++ b/docs/sources/whatsnew/whats-new-in-v6-1.md @@ -27,13 +27,13 @@ Support for fetching a list of label names was released in Prometheus v2.6.0 so ### Permissions: Editors can own dashboards, folders and teams they create -When the dashboard folders feature and permissions system was released in Grafana 5.0, users with the editor role were not allowed to administrate dashboards, folders or teams. In the 6.1 release, we have added a config option that can change the default permissions so that editors are admins for any Dashboard, Folder or Team they create. +When the dashboard folders feature and permissions system was released in Grafana 5.0, users with the editor role were not allowed to administrate dashboards, folders or teams. In the 6.1 release, we have added a configuration option that can change the default permissions so that editors are admins for any Dashboard, Folder or Team they create. This feature also adds a new Team permission that can be assigned to any user with the editor or viewer role and enables that user to add other users to the Team. We believe that this is more in line with the Grafana philosophy, as it will allow teams to be more self-organizing. This option will be made permanent if it gets positive feedback from the community so let us know what you think in the [issue on GitHub](https://github.com/grafana/grafana/issues/15590). -To turn this feature on add the following [config option](/administration/configuration/#editors-can-admin) to your Grafana ini file in the `users` section and then restart the Grafana server: +To turn this feature on add the following [configuration option](/administration/configuration/#editors-can-admin) to your Grafana ini file in the `users` section and then restart the Grafana server: ```ini [users]