collectd.conf(5): Improve write_stackdriver documentation.

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 7ff36b2..b73ab68 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -10334,9 +10334,35 @@ B<Synopsis:>
 Path to a JSON credentials file holding the credentials for a GCP service
 account.
 
 Path to a JSON credentials file holding the credentials for a GCP service
 account.
 

-If not specified, I<Application Default Credentials>. If running on GCE,
-B<Email> may be set to chose a different service account associated with the
-instance.
+If B<CredentialFile> is not specified, the plugin uses I<Application Default
+Credentials>. That means which credentials are used depends on the environment:
+
+=over 4
+
+=item
+
+The environment variable C<GOOGLE_APPLICATION_CREDENTIALS> is checked. If this
+variable is specified it should point to a JSON file that defines the
+credentials.
+
+=item
+
+The patch C<${HOME}/.config/gcloud/application_default_credentials.json> is
+checked. This where credentials used by the I<gcloud> command line utility are
+stored. You can use C<gcloud auth application-default login> to create these
+credentials.
+
+Please note that these credentials are often of your personal account, not a
+service account, and are therefore unfit to be used in a production
+environment.
+
+=item
+
+When running on GCE, the built-in service account associated with the virtual
+machine instance is used.
+See also the B<Email> option below.
+
+=back

 
 =item B<Project> I<Project>
 
 
 =item B<Project> I<Project>
 


@@ -10348,11 +10374,17 @@ number. You can look up both on the I<Developer Console>.
 This setting is optional. If not set, the project ID is read from the
 credentials file or determined from the GCE's metadata service.
 
 This setting is optional. If not set, the project ID is read from the
 credentials file or determined from the GCE's metadata service.
 

-=item B<Email> I<Email>
+=item B<Email> I<Email> (GCE only)
+
+Choses the GCE I<Service Account> used for authentication.

 
 

-Email address of an GCE I<Service Account>. This setting is only effective when
-running on GCE and using I<Application Default Credentials> (see
-B<CredentialFile> above).
+Each GCE instance has a C<default> I<Service Account> but may also be
+associated with additional I<Service Accounts>. This is often used to restrict
+the permissions of services running on the GCE instance to the required
+minimum. The I<write_stackdriver plugin> requires the
+C<https://www.googleapis.com/auth/monitoring> scope. When multiple I<Service
+Accounts> are available, this option selects which one is used by
+I<write_stackdriver plugin>.

 
 =item B<Resource> I<ResourceType>
 
 
 =item B<Resource> I<ResourceType>
 


@@ -10362,27 +10394,28 @@ takes a I<ResourceType> and arbitrary string options which are used as labels.
 On GCE, defaults to the equivalent of this config:
 
   <Resource "gce_instance">
 On GCE, defaults to the equivalent of this config:
 
   <Resource "gce_instance">

-    project_id "${meta/project/project-id}"
-    instance_id "${meta/instance/id}"
-    zone "${meta/instance/zone}"
+    project_id "<project_id>"
+    instance_id "<instance_id>"
+    zone "<zone>"

   </Resource>
 
   </Resource>
 

-Where C<${meta/...}> are values read from the meta data service.
+The values for I<project_id>, I<instance_id> and I<zone> are read from the GCE
+metadata service.

 
 When not running on GCE, defaults to the equivalent of this config:
 
   <Resource "global">
 
 When not running on GCE, defaults to the equivalent of this config:
 
   <Resource "global">

-    project_id "${Project}"
+    project_id "<Project>"

   </Resource>
 
   </Resource>
 

-Where C<${Project}> refers to the B<Project> option.
+Where I<Project> refers to the value of the B<Project> option.

 
 See L<https://cloud.google.com/monitoring/api/resources> for more information
 on I<Monitored Resource Types>.
 
 =item B<Url> I<Url>
 
 
 See L<https://cloud.google.com/monitoring/api/resources> for more information
 on I<Monitored Resource Types>.
 
 =item B<Url> I<Url>
 

-URL of the I<Google Cloud Monitoring> API. Defaults to
+URL of the I<Stackdriver Monitoring> API. Defaults to

 C<https://monitoring.googleapis.com/v3>.
 
 =back
 C<https://monitoring.googleapis.com/v3>.
 
 =back