From 80eafef4e2ad2fa5bfbbf6e1fe5ff3ce5cd2fa8c Mon Sep 17 00:00:00 2001 From: Yoko Hyakuna Date: Thu, 15 Feb 2024 14:42:49 -0800 Subject: [PATCH] [Docs] Add manual reporting doc (#25309) * Add manual util reporting doc * Update the instruction * Fix format * Remove the note about API endpoint * Removed minimum days requirement from the sentence * Update website/content/docs/enterprise/license/manual-reporting.mdx Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com> * Update website/content/docs/enterprise/license/manual-reporting.mdx Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com> * Update website/content/docs/enterprise/license/manual-reporting.mdx Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com> * Update website/content/docs/enterprise/license/manual-reporting.mdx Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com> * Update website/content/docs/enterprise/license/manual-reporting.mdx Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com> * Incorporated review feedbacks * Update the sample payload --------- Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com> --- .../enterprise/license/manual-reporting.mdx | 173 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 177 insertions(+) create mode 100644 website/content/docs/enterprise/license/manual-reporting.mdx diff --git a/website/content/docs/enterprise/license/manual-reporting.mdx b/website/content/docs/enterprise/license/manual-reporting.mdx new file mode 100644 index 0000000000..8d2d98c0ab --- /dev/null +++ b/website/content/docs/enterprise/license/manual-reporting.mdx @@ -0,0 +1,173 @@ +--- +layout: docs +page_title: Manual license utilization reporting +description: >- + Manual license utilization reporting allows you to export, review, and send license utilization data to HashiCorp through the CLI or HCP Web Portal. +--- + +# Manual license utilization reporting + +@include 'alerts/enterprise-only.mdx' + +Manual license utilization reporting allows you to export, review, and send +license utilization data to HashiCorp via the CLI or HCP Web Portal. Use these +reports to understand how much more you can deploy under your current contract, +protect against overutilization, and budget for predicted consumption. Manual +reporting shares the minimum data required to validate license utilization as +defined in our contracts. The reports consist of mostly computed metrics and +will never contain Personal Identifiable Information (PII) or other sensitive +information. + +Manual license utilization shares the same data as automated license utilization +but is more time consuming. Unless you are running in an air-gapped environment +or have another reason to report data manually, we strongly recommend using +automated reporting instead. If you have disabled automated license reporting, +you can re-enable it by reversing the opt-out process described in the +[documentation](/vault/docs/enterprise/license/utilization-reporting#opt-out). + +If you are considering manual reporting because you’re worried about your data, +we strongly recommend that you review the [example +payloads](#data-file-content), which are the same for automated and manual +reporting. If you have further concerns with any of the automatically-reported +data please bring them to your account manager before opting out of automated +reporting in favor of manual reporting. + +## How to manually send data reports + +### Generate a data bundle + +Data bundles include collections of JSON snapshots that contain license +utilization information. + +1. Login into your [cluster node](/vault/tutorials/cloud/vault-access-cluster). +1. Run this CLI command to generate a data bundle: + + ```shell-session + $ vault operator utilization + ``` + + By default, the bundle will include all historical snapshots. + + You can provide context about the conditions under which the report was + generated and submitted by providing a comment. This optional comment will + not be included in the license utilization bundle, but will be included in + the Vault server logs. + + **Example:** + + ```shell-session + $ vault operator utilization -message=”Change Control 654987” \ + -output=”/utilization/reports/latest.json” + ``` + + This command will export all the persisted snapshots into a bundle. The + message “Change Control 654987” will not be included in the bundle but will + be included in Vault server logs. The `-output` flags specifies the output + location of the JSON bundle. + + **Available command flags:** + + - `-message` `(string: “”)` - Provide context about the conditions under + which the report was generated and submitted. This message is not included + in the license utilization bundle but will be included in the vault server + logs. (optional) + + - `-today-only` `(bool: false)` - To include only today’s snapshot, no + historical snapshots. If no snapshots were persisted in the last 24 hrs, it + takes a snapshot and exports it to a bundle. (optional) + + - `-output` `(string: “”)` - Specifies the output path for the bundle. + Defaults to a time-based generated file name. (optional) + + +### Send the data bundle to HashiCorp + +1. Go to https://portal.cloud.hashicorp.com/license-utilization/reports/create +1. Click on **Choose files**, or drop your file(s) into the container. + + a. If the upload succeeded, the HCP user interface will change the file + status to **Uploaded** in green. + + b. If the upload failed, the file status will say **Failed** in red, and + will include error information. + +If the upload fails make sure you haven’t modified the file signature. If the +error persists, please contact your account representative. + + +## Enable manual reporting + +Upgrade to a release that supports manual license utilization reporting. These +releases include: + +- Vault Enterprise 1.16.0 and later +- Vault Enterprise 1.15.6 and later +- Vault Enterprise 1.14.10 and later + +## Configuration + +Administrators can manage disk space for storing snapshots by defining the +number of days snapshots can be retained. + +```hcl +reporting { + snapshot_retention_time = "2400h" +} +``` + +The default retention period is 400 days. + +## Data file content + + + +```json +{ + "snapshot_version": 2, + "id": "0001JWAY00BRF8TEXC9CVRHBAC", + "timestamp": "2024-02-08T16:55:28.085215-08:00", + "schema_version": "2.0.0", + "product": "vault", + "process_id": "01HP5NJS21HN50FY0CBS0SYGCH", + "metrics": { + "clientcount.current_month_estimate.type.entity": { + "key": "clientcount.current_month_estimate.type.entity", + "value": 20, + "mode": "write" + }, + "clientcount.current_month_estimate.type.nonentity": { + "key": "clientcount.current_month_estimate.type.nonentity", + "value": 11, + "mode": "write" + }, + "clientcount.current_month_estimate.type.secret_sync": { + "key": "clientcount.current_month_estimate.type.secret_sync", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.entity": { + "key": "clientcount.previous_month_complete.type.entity", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.nonentity": { + "key": "clientcount.previous_month_complete.type.nonentity", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.secret_sync": { + "key": "clientcount.previous_month_complete.type.secret_sync", + "value": 0, + "mode": "write" + } + }, + "product_version": "1.16.0+ent", + "license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c", + "checksum": 6861637915450723051, + "metadata": { + "billing_start": "2023-05-04T00:00:00Z", + "cluster_id": "16d0ff5b-9d40-d7a7-384c-c9b95320c60e" + } +``` + + \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 4f81173e1b..4e96e4b53f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -2529,6 +2529,10 @@ "title": "Automated license utilization reporting", "path": "enterprise/license/utilization-reporting" }, + { + "title": "Manual license utilization reporting", + "path": "enterprise/license/manual-reporting" + }, { "title": "FAQ", "path": "enterprise/license/faq"