mirror of https://github.com/hashicorp/consul
Backport of Add docs for usage endpoint and command into release/1.15.x (#16383)
* backport of commitpull/16389/head92acb57e4d
* backport of commita97ccea4b0
--------- Co-authored-by: Kyle Havlovitz <kylehav@gmail.com>
parent
926d480ff0
commit
2fb0a2f16e
@ -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.
|
@ -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`.
|
Loading…
Reference in new issue