From a6295fd286a2147f5ddce60f8808df94d41e78d5 Mon Sep 17 00:00:00 2001
From: Guilherme Santos <157053549+gsantos-hc@users.noreply.github.com>
Date: Wed, 5 Nov 2025 14:07:58 -0500
Subject: [PATCH] vault(pki-only): add pki-only mode docs

---
 .../v1.21.x/content/docs/license/index.mdx    |  6 ++
 .../v1.21.x/content/docs/license/pki.mdx      | 78 +++++++++++++++++++
 content/vault/v1.21.x/data/docs-nav-data.json |  4 +
 3 files changed, 88 insertions(+)
 create mode 100644 content/vault/v1.21.x/content/docs/license/pki.mdx

diff --git a/content/vault/v1.21.x/content/docs/license/index.mdx b/content/vault/v1.21.x/content/docs/license/index.mdx
index af1be18b71..cdd66f0b4a 100644
--- a/content/vault/v1.21.x/content/docs/license/index.mdx
+++ b/content/vault/v1.21.x/content/docs/license/index.mdx
@@ -23,6 +23,12 @@ Evaluation licenses have a 1-day grace period until the license expires. Once
 the evaluation license expires, Vault seals and cannot unseal until you apply
 a valid license.
 
+## PKI-only licenses
+
+PKI-only licenses restrict the secrets engines available on a cluster to Vault's
+built-in PKI secrets engine.
+Review the documentation on <a href="./license/pki">certificates-based entitlements</a>
+for additional information.
 
 ## How licensing works
 
diff --git a/content/vault/v1.21.x/content/docs/license/pki.mdx b/content/vault/v1.21.x/content/docs/license/pki.mdx
new file mode 100644
index 0000000000..23edc64e3e
--- /dev/null
+++ b/content/vault/v1.21.x/content/docs/license/pki.mdx
@@ -0,0 +1,78 @@
+---
+layout: docs
+page_title: PKI-only clusters
+description: Technical overview of Vault licensing on PKI-only clusters
+---
+
+# PKI-only clusters
+
+Vault Enterprise 1.21 introduced the ability for customers to license a cluster based on the number of certificates issued through Vault's built-in PKI secrets engine. Customers choosing this option must deploy a cluster that is dedicated to PKI and operating in PKI-only mode.
+
+## Certificate counting
+
+Vault Enterprise clusters running v1.21 and later maintain a count of every certificate issued across all mounts of the built-in PKI secrets engine.
+
+Vault does not deduplicate certificate counts. For example, if you request two certificates with the same Common Name (CN) and Subject Alternative Names (SANs), Vault counts them as two separate certificates.
+
+### Retrieve certificate counts
+
+To retrieve the current certificate usage counts, query the [`sys/billing/certificates`](../../api-docs/system/billing/certificates) endpoint.
+
+#### Sample CLI command and response
+
+<CodeBlockConfig>
+
+```shell-session
+$ vault read -format=json sys/billing/certificates \
+    start_time=2025-10 end_time=2025-11
+{
+  "request_id": "1014dfdc-25f5-9157-ecd2-6991de363831",
+  "lease_id": "",
+  "lease_duration": 0,
+  "renewable": false,
+  "data": {
+    "months": [
+      {
+        "counts": {
+          "issued_certificates": 0
+        },
+        "error": "certificate counts not found for 2025-10",
+        "timestamp": "2025-10"
+      },
+      {
+        "counts": {
+          "issued_certificates": 2
+        },
+        "timestamp": "2025-11"
+      }
+    ]
+  },
+  "warnings": null,
+  "mount_type": "system"
+}
+```
+
+</CodeBlockConfig>
+
+## PKI-only mode
+
+Vault Enterprise clusters entitled on the basis of certificates operate in PKI-only mode. A special flag in the license key automatically activates this mode.
+
+When running in PKI-only mode, the cluster's behavior changes in the following ways:
+
+1. **Restricted Mounts:** The cluster rejects all API requests to any mount of a secret engine other than the built-in PKI secrets engine. This restriction does not affect any authentication or system API paths.
+2. **Client Counting:** The cluster hides the Client Usage dashboard in the Vault UI. Note that the cluster will continue to count clients, but that metric is irrelevant for license utilization purposes on PKI-only clusters.
+
+## Considerations
+
+### Count persistence and data loss
+
+Vault aggregates and persists certificate counts approximately every two minutes. If a cluster node terminates before persisting its in-memory counts, Vault may lose the counts of certificates issued during that interval.
+
+Additionally, Vault attributes certificate issuance counts to the day when those counts were persisted to storage. Certificates issued at the very end of a day, month, or year may be counted on the following day, month, or year.
+
+### Attribution
+
+The certificates issued API endpoint provides certificate counts only. It does not provide attribution to namespaces, mounts, roles, or entities.
+
+To attribute certificate issuance, you must correlate the counts with your audit logs.
diff --git a/content/vault/v1.21.x/data/docs-nav-data.json b/content/vault/v1.21.x/data/docs-nav-data.json
index d4fec40110..121cf0988d 100644
--- a/content/vault/v1.21.x/data/docs-nav-data.json
+++ b/content/vault/v1.21.x/data/docs-nav-data.json
@@ -371,6 +371,10 @@
         "title": "Change licenses",
         "path": "license/change-license"
       },
+      {
+        "title": "PKI-only licenses",
+        "path": "license/pki"
+      },
       {
         "title": "Anonymized usage reporting",
         "path": "license/product-usage-reporting"