sensu · hillaryfraley · Aug 1, 2022 · Aug 1, 2022 · Aug 3, 2022 · Aug 4, 2022
diff --git a/integrations/influxdb/influxdb-metrics/CHANGELOG.md b/integrations/influxdb/influxdb-metrics/CHANGELOG.md
@@ -7,7 +7,12 @@ to [Semantic Versioning][semver].
 
 ## Unreleased
 
-- N/A
+- Revise text labels and prompts in configuration modal
+- Revise summary for success screen in integration yaml file
+- Restore instruction comments in README
+- Add and revise setup steps and options in README
+- Remove token substitution from reference documentation
+- Add reference documentation list in README
 
 ## [ 20220421.0.0 ] - 2022-04-21
 

diff --git a/integrations/influxdb/influxdb-metrics/README.md b/integrations/influxdb/influxdb-metrics/README.md
@@ -1,10 +1,14 @@
 ## Overview
 
-The `influxdb-metrics` integration provides a Sensu pipeline for sending metrics
-to the InfluxDB time series database. This integration is compatible with InfluxDB versions 2.x 
-with backwards compatibility for InfluxDB v1.8+.
+<!-- Sensu Integration description; supports markdown -->
 
-This integration provides the following resources:
+The InfluxDB Metrics integration provides a Sensu pipeline for sending metrics to an InfluxDB time-series database.
+
+This integration is compatible with InfluxDB v2 and backward-compatible with InfluxDB v1.8+.
+
+<!-- Provide a high level overview of the integration contents (e.g. checks, filters, mutators, handlers, assets, etc) -->
+
+This integration provides the following Sensu resources:
 
 * `influxdb` [handler]
 * `influxdb-metrics` [pipeline]
@@ -14,56 +18,76 @@ This integration provides the following resources:
 
 <!-- List of supported dashboards w/ screenshots (supports png, jpeg, and gif images; relative paths only; e.g. `![](img/dashboard-1.png)` )-->
 
-There are no supported dashboards for this integration.
+The InfluxDB Metrics integration does not have compatible dashboards.
 
 ## Setup
 
-1. To process metrics with InfluxDB, install this integration, then modify one or more Sensu [checks][check] to use the `influxdb-metrics` [pipeline].
+<!-- Sensu Integration setup instructions, including Sensu agent configuration and external component configuration -->
+<!-- EXAMPLE: what configuration (if any) is required in a third-party service to enable monitoring? -->
+
+**NOTE**: The InfluxDB Metrics integration is compatible with InfluxDB v2. If you use InfluxDb v1.8+, follow the substitution summary below to use this integration. Read the [InfluxDB 1.x compatibility API] documentation for details.
+
+<details><summary><strong>Substitution summary for InfluxDB v1.8+</strong></summary>
+
+If you use InfluxDB v1.8+, use the following substitutions to install this integration:
+
+- Use an empty string for the organization name.
+- Use [database and retention policy mapping] (e.g. `sensu/autogen`) for the bucket name. To use the default retention policy, use only the database name (e.g. `sensu`).
+- Use the InfluxDB username and password separated by a colon to create an API token: `<USERNAME>:<PASSWORD>`. If the InfluxDB server doesn't require authentication, use an empty string (`""`). 
+
+</details>
+<br>
+
+1. Get the InfluxDB v2 server URL, [organization] name, [bucket] name, and [API token].
+
+   **Optional**: If you want to use Sensu [secrets] to represent the InfluxDB v2 bucket name and API token, you will need the secret names when you install this integration.
+
+1. Add the `influxdb-metrics` [pipeline] to one or more [checks].
+
+   <details><summary><strong>Example: Check pipeline configuration</strong></summary>
 
    ```yaml
    spec:
-      ...: ...
-      pipelines:
-        - api_version: core/v2
-           type: Pipeline
-           name: influxdb-metrics
+     pipelines:
+       - api_version: core/v2
+         type: Pipeline
+         name: influxdb-metrics
    ```
-## InfluxDBv1.8+ Compatibility
 
+   </details>
+   <br>
 
-This plugin was written for InfluxDB 2.x, but it is possible to have it work with InfluxDB v1.8+ databases by using [v1.8 forward compatibility support](https://github.com/influxdata/influxdb-client-go#influxdb-18-api-compatibility).
+## Plugins
 
-InfluxDB v1.8+ compatibility summary:
- 1. Use the form `username:password` for an **authentication token**. Example: `my-user:my-password`. Use an empty string (`""`) if the server doesn't require authentication.
- 1. The organization parameter is not used. Use an empty string (`""`) where necessary.
- 1. Use the form `database/retention-policy` where a **bucket** is required. Skip retention policy if the default retention policy should be used. Examples: `sensu/autogen`, `sensu`.  
+<!-- Links to any Sensu Integration dependencies (i.e. Sensu Plugins) -->
 
+The InfluxDB Metrics integration uses the following Sensu [plugins]:
 
-# Plugins
+- [sensu-influxdb-handler][sensu-influxdb-handler-bonsai] ([GitHub][sensu-elasticsearch-influxdb-github])
 
-This integration uses the `sensu-influxdb-handler`:
+## Alerts
 
-- [sensu-influxdb-handler on Github](https://github.com/sensu/sensu-influxdb-handler)
-- [sensu/sensu-influxdb-handler on Bonsai](https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler)
+<!-- List of all alerts generated by this integration. -->
 
-## Metrics & Events
+The InfluxDB Metrics integration does not produce any events that should be processed by an alert or incident management [pipeline].
 
-<!-- List of all metrics or events collected by this integration. -->
+## Metrics
 
-This integration does not produce any [metrics].
-
-## Alerts
+<!-- List of all metrics or events collected by this integration. -->
 
-This integration does not produce any events that should be processed by an alert or incident management [handler].
+The InfluxDB Metrics integration does not produce any [metrics].
 
 ## Reference Documentation
 
 <!-- Please provide links to any relevant reference documentation to help users learn more and/or troubleshoot this integration. -->
 
-1. This plugin uses a [Sensu Token][tokens] for variable substitution.
+- [InfluxDB Cloud] (InfluxDB documentation)
+- [InfluxDB 1.x compatibility API] (InfluxDB documentation)
+
 
 <!-- Links -->
 [check]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/checks/
+[checks]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/checks/
 [asset]: https://docs.sensu.io/sensu-go/latest/plugins/assets/
 [subscription]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/subscriptions/
 [agents]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/agent/
@@ -72,5 +96,13 @@ This integration does not produce any events that should be processed by an aler
 [metrics]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/metrics/
 [handler]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/handlers/
 [tokens]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/tokens/
-[secret]: https://docs.sensu.io/sensu-go/latest/reference/secrets/
+[secrets]: https://docs.sensu.io/sensu-go/latest/reference/secrets/
 [pipeline]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/
+[API token]: https://docs.influxdata.com/influxdb/cloud/security/tokens/
+[organization]: https://docs.influxdata.com/influxdb/cloud/organizations/
+[bucket]: https://docs.influxdata.com/influxdb/cloud/organizations/buckets/
+[InfluxDB 1.x compatibility API]: https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/
+[sensu-influxdb-handler]: https://github.com/sensu/sensu-influxdb-handler
+[sensu-influxdb-handler-bonsai]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler
+[sensu-elasticsearch-influxdb-github]: https://github.com/sensu/sensu-influxdb-handler
+[InfluxDB Cloud]: https://docs.influxdata.com/influxdb/cloud/
diff --git a/integrations/influxdb/influxdb-metrics/sensu-integration.yaml b/integrations/influxdb/influxdb-metrics/sensu-integration.yaml
@@ -19,26 +19,28 @@ spec:
       title: InfluxDB Configuration
     - type: markdown
       body: |
-        This integration requires an InfluxDBv2 URL, org, bucket, and token.  InfluxDb v1.8+ users can encode database name into bucket and username:password as token according to backwards compatibility rules (ref: https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/).
+        Specify the InfluxDB v2 server, organization name, bucket name, and API token.
+
+        For InfluxDb v1.8+, substitute `""` for organization, `<DATABASE>/<RETENTION_POLICY>` for bucket, and `<USERNAME>:<PASSWORD>` for API token.
     - type: question
       name: influxdb_addr
       required: true
       input:
         type: string
         required: true
-        title: InfluxDB Address
+        title: InfluxDB v2 server URL
         description: >-
-          Provide the InfluxDB address (e.g. "http://influxdb.mycompany.com:8086")
+          Enter the InfluxDB v2 URL (e.g. http://influxdb.mycompany.com:8086)
         default: http://influxdb.mycompany.com:8086
     - type: question
       name: influxdb_org
       required: true
       input:
         type: string
         required: true
-        title: InfluxDB Org
+        title: InfluxDB v2 organization
         description: >-
-          Provide the InfluxDB org name (e.g. "sensu")
+          Enter the InfluxDB v2 organization name
         default: "sensu"
     - type: question
       name: influxdb_bucket
@@ -53,17 +55,17 @@ spec:
             properties:
               option:
                 type: string
-                title: InfluxDB Bucket
+                title: InfluxDB bucket
                 const: secret
                 constLocale:
                   title: Secret
                   description: >-
-                    Select this option to use Sensu Secrets Management
+                    Use a Sensu secret to provide the InfluxDB bucket name
               secret:
                 type: string
-                title: InfluxDB Bucket (Sensu Secret)
+                title: Secret name
                 description: >-
-                  Select the InfluxDB bucket (Sensu Secret)
+                  Enter the secret name for the InfluxDB bucket name
                 ref: secrets/v1/secret/metadata/name
           - type: object
             required:
@@ -72,17 +74,17 @@ spec:
             properties:
               option:
                 type: string
-                title: InfluxDB Bucket
+                title: InfluxDB bucket
                 const: env_var
                 constLocale:
-                  title: Environment Variable
+                  title: Environment variable
                   description: >-
-                    Select this option to store sensitive configuration as environment variables
+                    Save the InfluxDB bucket name as a backend environment variable
               env_var:
                 type: string
                 title: InfluxDB Bucket
                 description: >-
-                  Provide the InfluxDB bucket (NOTE: this will be stored in the Sensu API as unencrypted plaintext).
+                  Enter the InfluxDB bucket name (bucket name will be stored in the Sensu API as unencrypted plaintext)
     - type: question
       name: influxdb_token
       required: true
@@ -96,17 +98,17 @@ spec:
             properties:
               option:
                 type: string
-                title: InfluxDB Token
+                title: InfluxDB API token
                 const: secret
                 constLocale:
                   title: Secret
                   description: >-
-                    Select this option to use Sensu Secrets Management
+                    Use a Sensu secret to provide the InfluxDB API token
               secret:
                 type: string
-                title: InfluxDB Token (Sensu Secret)
+                title: Secret name
                 description: >-
-                  Select the InfluxDB token (Sensu Secret)
+                  Enter the secret name for the InfluxDB API token
                 ref: secrets/v1/secret/metadata/name
           - type: object
             required:
@@ -115,18 +117,17 @@ spec:
             properties:
               option:
                 type: string
-                title: InfluxDB Token
+                title: InfluxDB API token
                 const: env_var
                 constLocale:
-                  title: Environment Variable
+                  title: Environment variable
                   description: >-
-                    Select this option to store sensitive configuration as environment variables
+                    Save the InfluxDB API token as a backend environment variable
               env_var:
                 type: string
-                title: InfluxDB Token
+                title: InfluxDB API token
                 description: >-
-                  Provide the InfluxDB token (NOTE: this will be stored in the Sensu API as unencrypted plaintext).
-
+                  Enter the InfluxDB API token (token will be stored in the Sensu API as unencrypted plaintext)
   resource_patches:
     - resource:
         api_version: core/v2
@@ -155,20 +156,21 @@ spec:
           value:
             name: INFLUXDB_BUCKET
             secret: "[[influxdb_bucket.secret]]"
-
   post_install:
     - type: section
       title: Success
     - type: markdown
       body: |
-        You have successfully enabled the InfluxDB metrics pipeline integration.
+        You enabled the InfluxDB Metrics integration.
+
+        Sensu will forward events from checks that reference the `influxdb-metrics` pipeline to `[[influxdb_addr]]`.
 
-        Checks configured with the `influxdb-metrics` pipeline will send Sensu metric data to [[influxdb_addr]].
+        Add the `influxdb-metrics` pipeline reference to one or more checks:
 
         ```yaml
         spec:
           pipelines:
             - api_version: core/v2
               type: Pipeline
               name: influxdb-metrics
-        ```
+        ```