Auto-rolling billing start docs PR (#27926)

* auto-roll docs changes * addressing comments * address comments * Update website/content/api-docs/system/internal-counters.mdx Co-authored-by: Sarah Chavis <[email protected]> * addressing some changes * update docs * update docs with common explanation file * updated note info * fix 1.18 upgrade doc * fix content-check error * Update website/content/partials/auto-roll-billing-start-example.mdx Co-authored-by: miagilepner <[email protected]> --------- Co-authored-by: Sarah Chavis <[email protected]> Co-authored-by: miagilepner <[email protected]>
hashicorp · Aug 7, 2024 · 7622740 · 7622740
1 parent c3f050a
commit 7622740
Show file tree

Hide file tree

Showing 9 changed files with 83 additions and 2 deletions.
diff --git a/website/content/api-docs/system/internal-counters.mdx b/website/content/api-docs/system/internal-counters.mdx
@@ -255,6 +255,8 @@ not have namespace attribution for the `new_clients` stanza. Furthermore, the
 `new_clients` counts returned for the current month will be an approximation.
 That is to say, the response will appear as follows.
 
+  @include 'auto-roll-billing-start-example.mdx'
+
 ```json
 {
    "months":[
@@ -331,6 +333,7 @@ This endpoint was added in Vault 1.6.
 
 - `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the start of the
   period for which client counts will be reported. If no start time is specified, the billing start date will be used.
+  The [billing start date](/vault/docs/concepts/billing-start-date) automatically rolls over to the latest billing year at the end of the last cycle.
 - `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period
   for which client counts will be reported. If no end time is specified, the end of the current month will be used.
 - `limit_namespaces` `(int, optional)` - Controls the total number of by_namespace data returned. This can
@@ -1047,6 +1050,18 @@ $ curl \
 }
 ```
 
+<Note title="Important change to supported versions">
+   As of 1.16.7, 1.17.3 and later, 
+   the <a href="/vault/docs/concepts/billing-start-date">billing start date</a> automatically 
+   rolls over to the latest billing year at the end of the last cycle.
+
+   For more information, refer to the upgrade guide for your Vault version:
+
+   [Vault v1.16.x](/vault/docs/upgrading/upgrade-to-1.16.x#auto-rolled-billing-start-date),
+   [Vault v1.17.x](/vault/docs/upgrading/upgrade-to-1.17.x#auto-rolled-billing-start-date)
+
+</Note>
+
 ## Activity export
 
 This endpoint returns an export of the clients that had activity within the

diff --git a/website/content/docs/concepts/billing-start-date.mdx b/website/content/docs/concepts/billing-start-date.mdx
@@ -0,0 +1,21 @@
+---
+layout: docs
+page_title: Billing start date
+description: >-
+   A description of Vault cluster's billing start date used throughout Vault.
+---
+
+# Billing start date
+
+It is the start of the period for which [automated](/vault/docs/enterprise/license/utilization-reporting) and [manual](/vault/docs/enterprise/license/manual-reporting) license utilization data will be reported for a cluster. This is the license start date if you do not have an explicit
+billing start date configured. 
+
+Vault also uses the billing start date as a default start timestamp for:
+- [Direct queries via the activity log API](/vault/api-docs/system/internal-counters)
+- [Activity export CLI](/vault/api-docs/system/internal-counters#activity-export)
+
+As of 1.16.7, 1.17.3 and later, Vault clusters will automatically adjust the billing start date to provide a year's worth of utilization data. 
+
+@include 'auto-roll-billing-start.mdx'
+
+@include 'auto-roll-billing-start-example.mdx'
diff --git a/website/content/docs/enterprise/license/utilization-reporting.mdx b/website/content/docs/enterprise/license/utilization-reporting.mdx
@@ -227,7 +227,21 @@ HashiCorp collects the following utilization data as JSON payloads:
          - `entity` - The sum of tokens generated for a unique client identifier
          - `nonentity` - The sum of tokens without an entity attached
 - `metadata` - Optional product-specific metadata
-   - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured)
+   - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured).
+
+   <Note title="Important change to supported versions">
+
+      As of 1.16.7, 1.17.3 and later, 
+      the <a href="/vault/docs/concepts/billing-start-date">billing start date</a> automatically 
+      rolls over to the latest billing year at the end of the last cycle.
+
+      For more information, refer to the upgrade guide for your Vault version:
+
+      [Vault v1.16.x](/vault/docs/upgrading/upgrade-to-1.16.x#auto-rolled-billing-start-date),
+      [Vault v1.17.x](/vault/docs/upgrading/upgrade-to-1.17.x#auto-rolled-billing-start-date)
+
+    </Note> 
+
    - `cluster_id` - The cluster UUID as shown by `vault status` on the reporting
      cluster
 

diff --git a/website/content/docs/upgrading/upgrade-to-1.16.x.mdx b/website/content/docs/upgrading/upgrade-to-1.16.x.mdx
@@ -88,6 +88,14 @@ operation called an activation-flag. The feature is gated until a Vault operator
 decides to trigger the flag. More information can be found in the
 [secrets sync documentation](/vault/docs/sync#activating-the-feature).
 
+### Auto-rolled billing start date
+
+As of 1.16.7 and later, the billing start date (license start date if not configured) automatically rolls over to the latest billing year at the end of the last cycle. 
+
+@include 'auto-roll-billing-start.mdx'
+
+@include 'auto-roll-billing-start-example.mdx'
+
 ## Known issues and workarounds
 
 @include 'known-issues/1_16-jwt_auth_bound_audiences.mdx'

diff --git a/website/content/docs/upgrading/upgrade-to-1.17.x.mdx b/website/content/docs/upgrading/upgrade-to-1.17.x.mdx
@@ -81,6 +81,14 @@ Users may not be able to log into Vault if the JWT role is configured
 incorrectly. For additional details, refer to the
 [JWT auth method (API)](/vault/api-docs/auth/jwt) documentation.
 
+### Auto-rolled billing start date
+
+As of 1.17.3 and later, the billing start date (license start date if not configured) rolls over to the latest billing year at the end of the last cycle. 
+
+@include 'auto-roll-billing-start.mdx'
+
+@include 'auto-roll-billing-start-example.mdx'
+
 ## Known issues and workarounds
 
 @include 'known-issues/ocsp-redirect.mdx'

diff --git a/website/content/docs/upgrading/upgrade-to-1.18.x.mdx b/website/content/docs/upgrading/upgrade-to-1.18.x.mdx
@@ -56,4 +56,4 @@ WARNING! The following warnings were returned from Vault:
 
 ```
 
-</CodeBlockConfig>
+</CodeBlockConfig>
diff --git a/website/content/partials/auto-roll-billing-start-example.mdx b/website/content/partials/auto-roll-billing-start-example.mdx
@@ -0,0 +1,8 @@
+
+The default billing start date used in queries and license utilization reporting will be automatically adjusted to the latest billing year. Past year billing information will still be retained.
+
+For example, assume a customer has signed a deal for 3 years with a license start date of Dec 1, 2023. After upgrading to the version with this change, the billing start date 
+auto-rolls to the most recent year.
+- If the upgrade happens on Sept 1, 2024, the billing start date will continue to be Dec 1, 2023. Once we reach Dec 1, 2024, the billing start date 
+will automatically roll to Dec 1, 2024. 
+- If the upgrade happens on Dec 15, 2024, the billing start date should automatically roll to Dec 1, 2024 after upgrade.
diff --git a/website/content/partials/auto-roll-billing-start.mdx b/website/content/partials/auto-roll-billing-start.mdx
@@ -0,0 +1,3 @@
+
+This means that the billing start dates from earlier years will get updated to current calendar year, unless the date has not yet occured this year, in which case 
+it will remain in the last calendar year. The billing start date will adjust accordingly for leap years.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
@@ -257,6 +257,10 @@
         "title": "Resource Quotas",
         "path": "concepts/resource-quotas"
       },
+      {
+        "title": "Billing Start Date",
+        "path": "concepts/billing-start-date"
+      },
       {
         "title": "Client count",
         "routes": [