Merge pull request #77 from axoflow/gcp-cloud-auth

Document missing cloud-auth options
axoflow · Nov 5, 2024 · 8bfa6fe · 8bfa6fe
2 parents b5e17b0 + 3d87a08
commit 8bfa6fe
Show file tree

Hide file tree

Showing 3 changed files with 83 additions and 2 deletions.
diff --git a/...figuring-destinations-http-nonjava/reference-destination-http-nonjava/_index.md b/...figuring-destinations-http-nonjava/reference-destination-http-nonjava/_index.md
@@ -74,8 +74,28 @@ For details on how this option influences HTTP batch mode, see [http: Posting me
 
 *Description:* The string {{% param "product.abbrev" %}} puts to the end of the body of the HTTP request, after the log message. Available in {{% param "product.abbrev" %}} version 3.18 and later.
 
-For details on how this option influences HTTP batch mode, see [http: Posting messages over HTTP without Java]({{< relref "/chapter-destinations/configuring-destinations-http-nonjava/_index.md" >}})
+For details on how this option influences HTTP batch mode, see [http: Posting messages over HTTP without Java]({{< relref "/chapter-destinations/configuring-destinations-http-nonjava/_index.md" >}}).
+
+## cloud-auth()
+
+Authenticate to cloud-based services, for example, GCP, using service accounts.
+
+### gcp()
+
+Authenticate to GCP service accounts. For example:
+
+```shell
+cloud-auth(
+  gcp(
+    user-managed-service-account(
+      name("your-user@your-project.iam.gserviceaccount.com")
+      metadata-url("your-metadata-server:8080")
+    )
+  )
+)
+```
 
+{{< include-headless "chunk/option-gcp-cloud-auth.md" >}}
 
 
 {{% include-headless "chunk/option-destination-tls-ca-dir.md" %}}

diff --git a/content/chapter-destinations/google-pubsub/_index.md b/content/chapter-destinations/google-pubsub/_index.md
@@ -79,7 +79,7 @@ auth(
   )
 ```
 
-### service-account()
+{{< include-headless "chunk/option-gcp-cloud-auth.md" >}}
 
 ## data()
 

diff --git a/content/headless/chunk/option-gcp-cloud-auth.md b/content/headless/chunk/option-gcp-cloud-auth.md
@@ -0,0 +1,61 @@
+---
+---
+<!-- This file is under the copyright of Axoflow, and licensed under Apache License 2.0, except for using the Axoflow and AxoSyslog trademarks. -->
+#### service-account()
+
+Authenticate to a service account using Service Account Key-Based Authentication. This method works both inside and outside GCP It uses a [service account key](https://cloud.google.com/iam/docs/keys-create-delete) generated and downloaded through the GCP IAM & Admin console. The long-term service account key is used to generate short-term tokens for authentication (also called [self-signed JWT](https://google.aip.dev/auth/4111)).
+
+##### audience()
+
+|                  |                  |
+| ---------------- | ---------------- |
+| Type: | string |
+| Default:         |  |
+
+{{% alert title="Note" color="info" %}}
+When using the `google-pubsub()` destination, the `audience()` option is set to `https://pubsub.googleapis.com/google.pubsub.v1.Publisher`. Don't change it.
+{{% /alert %}}
+
+##### key()
+
+|                  |                  |
+| ---------------- | ---------------- |
+| Type: | string (path) |
+| Default:         |  |
+
+Path to the service account key.
+
+##### token-validity-duration()
+
+|                  |                  |
+| ---------------- | ---------------- |
+| Type: | integer (seconds) |
+| Default:         | `3600` |
+
+#### user-managed-service-account()
+
+Available in {{< product >}} version 4.6 and later.
+
+{{% alert title="Note" color="info" %}}
+The `user-managed-service-account()` method is only available for VMs running within GCP.
+{{% /alert %}}
+
+Authenticate to a [user-managed service account](https://cloud.google.com/iam/docs/service-account-types#user-managed) of a GCP virtual machine using the VM Metadata Server Method. {{< product >}} interacts with the internal GCP metadata server, which provides an OAuth2 token for authentication. You can attach the [default service accounts](https://cloud.google.com/iam/docs/service-account-types#default) as well.
+
+##### metadata-url()
+
+|                  |                  |
+| ---------------- | ---------------- |
+| Type: | string |
+| Default:         | `http://metadata.google.internal/computeMetadata/v1/instance/service-accounts` |
+
+The URL of the metadata server. When specifying the port, use the `URL:port` format.
+
+##### name()
+
+|                  |                  |
+| ---------------- | ---------------- |
+| Type: | string |
+| Default:         | `default` |
+
+Name of the service account to use.
-Original file line number
+Diff line change
@@ Expand Up / @@ -79,7 +79,7 @@ auth( @@
       )
     ```
-    ### service-account()
+    {{< include-headless "chunk/option-gcp-cloud-auth.md" >}}
     ## data()
@@ Expand Down @@