backport of commit 00485c7 (#20956)

Co-authored-by: Yoko Hyakuna <[email protected]>
hashicorp · Jun 2, 2023 · 6c6eb64 · 6c6eb64
1 parent 08cbaab
commit 6c6eb64
Show file tree

Hide file tree

Showing 2 changed files with 256 additions and 0 deletions.
diff --git a/website/content/docs/enterprise/license/utilization-reporting.mdx b/website/content/docs/enterprise/license/utilization-reporting.mdx
@@ -0,0 +1,252 @@
+---
+layout: docs
+page_title: Automated license utilization reporting
+description: >-
+  Learn what data HashiCorp collects to meter Enterprise license utilization. Enable or disable reporting. Review sample payloads and logs.
+---
+
+# Automated License utilization reporting
+
+Automated license utilization reporting sends license utilization data to
+HashiCorp without requiring you to manually collect and report them. It also
+lets you review your license usage with the monitoring solution you already use
+(for example Splunk, Datadog, or others) so you can optimize and manage your
+deployments. Use these reports to understand how much more you can deploy under
+your current contract, protect against overutilization, and budget for predicted
+consumption.  
+
+Automated reporting shares the minimum data required to validate license
+utilization as defined in our contracts. They consist of mostly computed metrics
+and will never contain Personal Identifiable Information (PII) or other
+sensitive information. Automated reporting shares the data with HashiCorp using
+a secure, unidirectional HTTPS API and makes an auditable record in the product
+logs each time it submits a report.
+
+## Enable automated reporting
+
+To enable automated reporting, you need to make sure that outbound network
+traffic is configured correctly and upgrade your enterprise product to a version
+that supports it. If your installation is air-gapped or network settings are not
+in place, automated reporting will not work. 
+
+### 1. Allow outbound HTTPS traffic on port 443
+
+Make sure that your network allows HTTPS egress on port 443 to
+https://reporting.hashicorp.services by allow-listing the following IP
+addresses: 
+
+- 100.20.70.12
+- 35.166.5.222
+- 23.95.85.111
+- 44.215.244.1
+
+### 2. Upgrade
+
+Upgrade to a release that supports entitlement utilization reporting. These
+releases include:
+
+- [Vault Enterprise 1.14.0](https://releases.hashicorp.com/vault/) and later
+
+
+### 3. Check logs
+
+Automatic license utilization reporting will start sending data within 24 hours.
+Check the server logs for records that the data sent successfully.
+
+You will find log entries similar to the following:
+
+<CodeBlockConfig hideClipboard>
+
+```
+[DEBUG] core.reporting: beginning snapshot export
+[DEBUG] core.reporting: creating payload
+[DEBUG] core.reporting: marshalling payload to json
+[DEBUG] core.reporting: generating authentication headers
+[DEBUG] core.reporting: creating request
+[DEBUG] core.reporting: sending request
+[DEBUG] core.reporting: performing request: method=POST url=https://reporting.hashicorp.services
+[DEBUG] core.reporting: recording audit record
+[INFO]  core.reporting: Report sent: auditRecord="{\"payload\":{\"payload_version\":\"1\",\"license_id\":\"97afe7b4-b9c8-bf19-bf35-b89b5cc0efea\",\"product\":\"vault\",\"product_version\":\"1.14.0-rc1+ent\",\"export_timestamp\":\"2023-06-01T09:34:44.215133-04:00\",\"snapshots\":[{\"snapshot_version\":1,\"snapshot_id\":\"0001J7H7KMEDRXKM5C1QJGBXV3\",\"process_id\":\"01H1T45CZK2GN9WR22863W2K32\",\"timestamp\":\"2023-06-01T09:34:44.215001-04:00\",\"schema_version\":\"1.0.0\",\"service\":\"vault\",\"metrics\":{\"clientcount.current_month_estimate\":{\"key\":\"clientcount.current_month_estimate\",\"kind\":\"sum\",\"mode\":\"write\",\"labels\":{\"type\":{\"entity\":20,\"nonentity\":11}}},\"clientcount.previous_month_complete\":{\"key\":\"clientcount.previous_month_complete\",\"kind\":\"sum\",\"mode\":\"write\",\"labels\":{\"type\":{\"entity\":10,\"nonentity\":11}}}}}],\"metadata\":{\"vault\":{\"billing_start\":\"2023-03-01T00:00:00Z\",\"cluster_id\":\"a8d95acc-ec0a-6087-d7f6-4f054ab2e7fd\"}}}}"
+[DEBUG] core.reporting: completed recording audit record
+[DEBUG] core.reporting: export finished successfully
+```
+
+</CodeBlockConfig>
+
+If your installation is air-gapped or your network doesn’t allow the correct
+egress, logs will show an error. 
+
+<CodeBlockConfig hideClipboard>
+
+```
+[DEBUG] core.reporting: beginning snapshot export
+[DEBUG] core.reporting: creating payload
+[DEBUG] core.reporting: marshalling payload to json
+[DEBUG] core.reporting: generating authentication headers
+[DEBUG] core.reporting: creating request
+[DEBUG] core.reporting: sending request
+[DEBUG] core.reporting: performing request: method=POST url=https://reporting.hashicorp.services
+[DEBUG] core.reporting: error status code received: statusCode=403
+```
+
+</CodeBlockConfig>
+
+In this case, reconfigure your network to allow egress and check back in 24
+hours. 
+
+## Opt out
+
+If your installation is air-gapped or you want to manually collect and report on
+the same license utilization metrics, you can opt-out of automated reporting. 
+
+Manually reporting these metrics can be time consuming. Opting out of automated
+reporting does not mean that you also opt out from sending license utilization
+metrics. Customers who opt out of automated reporting will still be required to
+manually collect and send license utilization metrics to HashiCorp. 
+
+If you are considering opting out because you’re worried about the data, we
+strongly recommend that you review the [example payloads](#example-payloads)
+before opting out. If you have concerns with any of the automatically-reported
+data please bring them to your account manager. 
+
+You have two options to opt out of automated reporting: 
+
+- HCL configuration (recommended) 
+- Environment variable (requires restart)
+
+
+#### HCL configuration
+
+Opting out in your product’s configuration file doesn’t require a system
+restart, and is the method we recommend. Add the following block to your server
+configuration file (e.g. `vault-config.hcl`).
+
+```hcl
+reporting {
+	license {
+		enabled = false
+   }
+}
+```
+
+<Warning>
+
+When you have a cluster, each node must have the reporting stanza in its
+configuration to be consistent. In the event of leadership change, nodes will
+use its server configuration to determine whether or not to opt-out the
+automated reporting. Inconsistent configuration between nodes will change the
+reporting status upon active unseal.
+
+</Warning>
+
+
+You will find the following entries in the server log.
+
+<CodeBlockConfig hideClipboard>
+
+```
+[DEBUG] core: reloading automated reporting
+[INFO]  core: opting out of automated reporting
+[DEBUG] activity: there is no reporting agent configured, skipping counts reporting
+```
+
+</CodeBlockConfig>
+
+#### Environment variable
+
+If you need to, you can also opt out using an environment variable, which will
+provide a startup message confirming that you have disabled automated reporting.
+This option requires a system restart. 
+
+<Note>
+
+If the reporting stanza exists in the configuration file, the
+`OPTOUT_LICENSE_REPORTING` value overrides the configuration.
+
+</Note>
+
+Set the following environment variable.
+
+```shell-session
+$ export OPTOUT_LICENSE_REPORTING=true
+```
+
+Now, restart your [Vault servers](/vault/docs/commands/server) from the shell
+where you set the environment variable.
+
+You will find the following entries in the server log.
+
+<CodeBlockConfig hideClipboard>
+
+```
+[INFO]  core: automated reporting disabled via environment variable: env=OPTOUT_LICENSE_REPORTING
+[INFO]  core: opting out of automated reporting
+[DEBUG] activity: there is no reporting agent configured, skipping counts reporting
+```
+
+</CodeBlockConfig>
+
+
+Check your product logs 24 hours after opting out to make sure that the system
+isn’t trying to send reports. 
+
+If your configuration file and environment variable differ, the environment
+variable setting will take precedence.
+
+## Example payloads
+
+HashiCorp collects the following utilization data as JSON payloads:
+
+<CodeBlockConfig hideClipboard>
+
+```json
+{
+  "payload_version": "1",
+  "license_id": "97afe7b4-b9c8-bf19-bf35-b89b5cc0efea",
+  "product": "vault",
+  "product_version": "1.14.0-rc1+ent",
+  "export_timestamp": "2023-06-01T11:39:00.76643-04:00",
+  "snapshots": [
+    {
+      "snapshot_version": 1,
+      "snapshot_id": "0001J7HEWM1PEHPMF5YZT8EV65",
+      "process_id": "01H1VSQMNYAP77R566F1Y03GE6",
+      "timestamp": "2023-06-01T11:39:00.766099-04:00",
+      "schema_version": "1.0.0",
+      "service": "vault",
+      "metrics": {
+        "clientcount.current_month_estimate": {
+          "key": "clientcount.current_month_estimate",
+          "kind": "sum",
+          "mode": "write",
+          "labels": {
+            "type": {
+              "entity": 20,
+              "nonentity": 11
+            }
+          }
+        },
+        "clientcount.previous_month_complete": {
+          "key": "clientcount.previous_month_complete",
+          "kind": "sum",
+          "mode": "write",
+          "labels": {
+            "type": {
+              "entity": 10,
+              "nonentity": 11
+            }
+          }
+        }
+      }
+    }
+  ],
+  "metadata": {
+    "vault": {
+      "billing_start": "2023-03-01T00:00:00Z",
+      "cluster_id": "a8d95acc-ec0a-6087-d7f6-4f054ab2e7fd"
+    }
+  }
+}
+```
+
+</CodeBlockConfig>
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
@@ -2242,6 +2242,10 @@
             "title": "Autoloading",
             "path": "enterprise/license/autoloading"
           },
+          {
+            "title": "Automated license utilization reporting",
+            "path": "enterprise/license/utilization-reporting"
+          },
           {
             "title": "FAQ",
             "path": "enterprise/license/faq"