From: Florian Forster <octo@collectd.org>
Date: Thu, 7 Dec 2017 13:17:20 +0000 (+0100)
Subject: collectd.conf(5): Improve write_stackdriver documentation.
X-Git-Url: https://git.octo.it/?p=collectd.git;a=commitdiff_plain;h=1c671085c3b5f42d852f143c986c6a2e268be5db

collectd.conf(5): Improve write_stackdriver documentation.
---

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 7ff36b2c..b73ab681 100644
--- 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.
 
-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>
 
@@ -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.
 
-=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>
 
@@ -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">
-    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>
 
-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">
-    project_id "${Project}"
+    project_id "<Project>"
   </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>
 
-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