Backport of Add docs for usage endpoint and command into release/1.15.x (#16383)

* backport of commit 92acb57e4d * backport of commit a97ccea4b0 --------- Co-authored-by: Kyle Havlovitz <kylehav@gmail.com>
2 years ago · 2fb0a2f16e
parent 926d480ff0
commit 2fb0a2f16e
5 changed files with 271 additions and 0 deletions
--- a/website/content/api-docs/operator/usage.mdx
+++ b/website/content/api-docs/operator/usage.mdx
@ -0,0 +1,161 @@
+---
+layout: api
+page_title: Usage - Operator - HTTP API
+description: |-
+  The /operator/usage endpoint returns usage information about the number of
+  services, service instances and Connect-enabled service instances by
+  datacenter.
+---
+
+# Usage Operator HTTP API
+
+The `/operator/usage` endpoint returns usage information about the number of
+services, service instances and Connect-enabled service instances by datacenter.
+
+| Method | Path              | Produces           |
+| ------ | ----------------- | ------------------ |
+| `GET`  | `/operator/usage` | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
+| ---------------- | ----------------- | ------------- | --------------- |
+| `YES`            | `all`             | `none`        | `operator:read` |
+
+The corresponding CLI command is [`consul operator usage instances`](/consul/commands/operator/usage).
+
+### Query Parameters
+
+- `global` `(bool: false)` - If present, usage information for all
+  known datacenters will be returned. By default, only the local datacenter's
+  usage information is returned.
+
+- `stale` `(bool: false)` - If the cluster does not currently have a leader, an
+  error will be returned. You can use the `?stale` query parameter to read the
+  Raft configuration from any of the Consul servers.
+
+### Sample Request
+
+```shell-session
+$ curl \
+    http://127.0.0.1:8500/v1/operator/usage
+```
+
+### Sample Response
+
+<Tabs>
+<Tab heading="OSS">
+```json
+{
+  "Usage": {
+    "dc1": {
+      "Services": 1,
+      "ServiceInstances": 1,
+      "ConnectServiceInstances": {
+        "connect-native": 0,
+        "connect-proxy": 0,
+        "ingress-gateway": 0,
+        "mesh-gateway": 0,
+        "terminating-gateway": 0
+      },
+      "BillableServiceInstances": 0
+    }
+  },
+  "Index": 13,
+  "LastContact": 0,
+  "KnownLeader": true,
+  "ConsistencyLevel": "leader",
+  "NotModified": false,
+  "Backend": 0,
+  "ResultsFilteredByACLs": false
+}
+```
+</Tab>
+<Tab heading="Enterprise">
+```json
+{
+  "Usage": {
+    "dc1": {
+      "Services": 1,
+      "ServiceInstances": 1,
+      "ConnectServiceInstances": {
+        "connect-native": 0,
+        "connect-proxy": 0,
+        "ingress-gateway": 0,
+        "mesh-gateway": 0,
+        "terminating-gateway": 0
+      },
+      "BillableServiceInstances": 0,
+      "PartitionNamespaceServices": {
+        "default": {
+          "default": 1
+        }
+      },
+      "PartitionNamespaceServiceInstances": {
+        "default": {
+          "default": 1
+        }
+      },
+      "PartitionNamespaceBillableServiceInstances": {
+        "default": {
+          "default": 1
+        }
+      },
+      "PartitionNamespaceConnectServiceInstances": {
+        "default": {
+          "default": {
+            "connect-native": 0,
+            "connect-proxy": 0,
+            "ingress-gateway": 0,
+            "mesh-gateway": 0,
+            "terminating-gateway": 0
+          }
+        }
+      }
+    }
+  },
+  "Index": 13,
+  "LastContact": 0,
+  "KnownLeader": true,
+  "ConsistencyLevel": "leader",
+  "NotModified": false,
+  "Backend": 0,
+  "ResultsFilteredByACLs": false
+}
+```
+</Tab>
+</Tabs>
+
+- `Services` is the total number of unique service names registered in the
+  datacenter.
+
+- `ServiceInstances` is the total number of service instances registered in
+  the datacenter.
+
+- `ConnectServiceInstances` is the total number of Connect service instances
+  registered in the datacenter.
+
+- `BillableServiceInstances` is the total number of billable service instances
+  registered in the datacenter. This is only relevant in Consul Enterprise
+  and is the total service instance count, not including any Connect service
+  instances or any Consul server instances.
+
+- `PartitionNamespaceServices` <EnterpriseAlert inline /> is the total number
+  of unique service names registered in the datacenter, by partition and
+  namespace.
+
+- `PartitionNamespaceServiceInstances` <EnterpriseAlert inline /> is the total
+  number of service instances registered in the datacenter, by partition and
+  namespace.
+
+- `PartitionNamespaceBillableServiceInstances` <EnterpriseAlert inline /> is
+  the total number of billable service instances registered in the datacenter,
+  by partition and namespace.
+
+- `PartitionNamespaceConnectServiceInstances` <EnterpriseAlert inline /> is
+  the total number of Connect service instances registered in the datacenter,
+  by partition and namespace.
--- a/website/content/commands/operator/index.mdx
+++ b/website/content/commands/operator/index.mdx
@ -37,6 +37,7 @@ Subcommands:
    area         Provides tools for working with network areas (Enterprise-only)
    autopilot    Provides tools for modifying Autopilot configuration
    raft         Provides cluster-level tools for Consul operators
+    usage        Provides cluster-level usage information
 ```

 For more information, examples, and usage about a subcommand, click on the name
@ -45,3 +46,4 @@ of the subcommand in the sidebar or one of the links below:
 - [area](/consul/commands/operator/area) <EnterpriseAlert inline />
 - [autopilot](/consul/commands/operator/autopilot)
 - [raft](/consul/commands/operator/raft)
+- [usage](/consul/commands/operator/usage)
--- a/website/content/commands/operator/usage.mdx
+++ b/website/content/commands/operator/usage.mdx
@ -0,0 +1,100 @@
+---
+layout: commands
+page_title: 'Commands: Operator Usage'
+description: >
+  The operator usage command provides cluster-level tools for Consul operators
+  to view usage information, such as service and service instance counts.
+---
+
+# Consul Operator Usage
+
+Command: `consul operator usage`
+
+The Usage `operator` command provides cluster-level tools for Consul operators
+to view usage information, such as service and service instance counts.
+
+```text
+Usage: consul operator usage <subcommand> [options]
+
+  # ...
+
+Subcommands:
+    instances    Display service instance usage information
+```
+
+## instances
+
+Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/usage](/consul/api-docs/operator/usage#operator-usage)
+
+This command retrieves usage information about the number of services registered in a given
+datacenter. By default, the datacenter of the local agent is queried.
+
+The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
+[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
+are not supported from commands, but may be from the corresponding HTTP endpoint.
+
+| ACL Required    |
+| --------------- |
+| `operator:read` |
+
+Usage: `consul operator usage instances`
+
+The output looks like this:
+
+```text
+$ consul operator usage instances
+Billable Service Instances Total: 3
+dc1 Billable Service Instances: 3
+
+Billable Services
+Services      Service instances
+2             3
+
+Connect Services
+Type                     Service instances
+connect-native           0
+connect-proxy            0
+ingress-gateway          0
+mesh-gateway             1
+terminating-gateway      0
+```
+
+With the `-all-datacenters` flag:
+
+```text
+$ consul operator usage instances -all-datacenters
+Billable Service Instances Total: 4
+dc1 Billable Service Instances: 3
+dc2 Billable Service Instances: 1
+
+Billable Services
+Datacenter      Services      Service instances
+dc1             2             3
+dc2             1             1
+
+Total           3             4
+
+Connect Services
+Datacenter      Type                     Service instances
+dc1             connect-native           0
+dc1             connect-proxy            0
+dc1             ingress-gateway          0
+dc1             mesh-gateway             1
+dc1             terminating-gateway      0
+dc2             connect-native           0
+dc2             connect-proxy            0
+dc2             ingress-gateway          0
+dc2             mesh-gateway             1
+dc2             terminating-gateway      1
+
+Total                                    3
+```
+
+#### Command Options
+
+- `-all-datacenters` - Display service counts from all known datacenters.
+  Default is `false`.
+
+- `-billable` - Display only billable service information. Default is `false`.
+
+- `-connect` - Display only Connect service information. Default is `false`.
--- a/website/data/api-docs-nav-data.json
+++ b/website/data/api-docs-nav-data.json
@ -165,6 +165,10 @@
      {
        "title": "Segment",
        "path": "operator/segment"
+      },
+      {
+        "title": "Usage",
+        "path": "operator/usage"
      }
    ]
  },
--- a/website/data/commands-nav-data.json
+++ b/website/data/commands-nav-data.json
@ -425,6 +425,10 @@
      {
        "title": "raft",
        "path": "operator/raft"
+      },
+      {
+        "title": "usage",
+        "path": "operator/usage"
      }
    ]
  },