intro and api navigation converted

This commit is contained in:
Jeff Escalante 2020-04-07 14:55:19 -04:00
parent 0d9e72f1dc
commit 957c04eb20
No known key found for this signature in database
GPG Key ID: 32D23C61AB5450DB
335 changed files with 6917 additions and 6332 deletions

View File

@ -0,0 +1,50 @@
// The root folder for this documentation category is `pages/guides`
//
// - A string refers to the name of a file
// - A "category" value refers to the name of a directory
// - All directories must have an "index.mdx" file to serve as
// the landing page for the category
export default [
'index',
{
category: 'features',
content: ['consistency', 'blocking', 'filtering', 'caching'],
},
'--------',
{
category: 'acl',
content: [
'tokens',
'legacy',
'policies',
'roles',
'auth-methods',
'binding-rules',
],
},
{
category: 'agent',
content: ['check', 'service', 'connect'],
},
'catalog',
'config',
{ category: 'connect', content: ['ca', 'intentions'] },
'coordinate',
'discovery-chain',
'event',
'health',
'kv',
{
category: 'operator',
content: ['area', 'autopilot', 'keyring', 'license', 'raft', 'segment'],
},
'namespaces',
'query',
'session',
'snapshot',
'status',
'txn',
'-------',
'libraries-and-sdks',
]

View File

@ -1,8 +0,0 @@
// The root folder for this documentation category is `pages/guides`
//
// - A string refers to the name of a file
// - A "category" value refers to the name of a directory
// - All directories must have an "index.mdx" file to serve as
// the landing page for the category
export default []

View File

@ -5,4 +5,22 @@
// - All directories must have an "index.mdx" file to serve as
// the landing page for the category
export default []
export default [
'index',
{
category: 'vs',
content: [
'zookeeper',
'chef-puppet',
'nagios-sensu',
'skydns',
'smartstack',
'serf',
'eureka',
'istio',
'proxies',
'custom',
],
},
'getting-started',
]

View File

@ -1,5 +1,5 @@
import DocsPage from '@hashicorp/react-docs-page'
import order from '../data/api-docs-navigation.js'
import order from '../data/api-navigation.js'
import { frontMatter as data } from '../pages/api-docs/**/*.mdx'
import Head from 'next/head'
import Link from 'next/link'

View File

@ -2,8 +2,9 @@
layout: api
page_title: Legacy ACLs - HTTP API
sidebar_current: api-acls-legacy
description: |-
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in Consul.
description: >-
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
Consul.
---
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_

View File

@ -1,15 +1,15 @@
---
layout: api
page_title: ACL Auth Methods - HTTP API
sidebar_title: 'Auth Methods'
sidebar_current: api-acl-auth-methods
description: |-
The /acl/auth-method endpoints manage Consul's ACL Auth Methods.
description: The /acl/auth-method endpoints manage Consul's ACL Auth Methods.
---
-> **1.5.0+:** The auth method APIs are available in Consul versions 1.5.0 and newer.
# ACL Auth Method HTTP API
-> **1.5.0+:** The auth method APIs are available in Consul versions 1.5.0 and newer.
The `/acl/auth-method` endpoints [create](#create-an-auth-method),
[read](#read-an-auth-method), [update](#update-an-auth-method),
[list](#list-auth-methods) and [delete](#delete-an-auth-method)

View File

@ -1,15 +1,15 @@
---
layout: api
page_title: ACL Binding Rules - HTTP API
sidebar_title: 'Binding Rules'
sidebar_current: api-acl-binding-rules
description: |-
The /acl/binding-rule endpoints manage Consul's ACL Binding Rules.
description: The /acl/binding-rule endpoints manage Consul's ACL Binding Rules.
---
-> **1.5.0+:** The binding rule APIs are available in Consul versions 1.5.0 and newer.
# ACL Binding Rule HTTP API
-> **1.5.0+:** The binding rule APIs are available in Consul versions 1.5.0 and newer.
The `/acl/binding-rule` endpoints [create](#create-a-binding-rule),
[read](#read-a-binding-rule), [update](#update-a-binding-rule),
[list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding

View File

@ -1,15 +1,15 @@
---
layout: api
page_title: ACLs - HTTP API
sidebar_title: 'ACLs'
sidebar_current: api-acl
description: |-
The /acl endpoints manage the Consul's ACL system.
description: The /acl endpoints manage the Consul's ACL system.
---
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html)
# ACL HTTP API
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html)
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens.html) and [policies](/api/acl/policies.html) with the `/acl` endpoints.
For more information on how to setup ACLs, please see

View File

@ -1,17 +1,19 @@
---
layout: api
page_title: Legacy ACLs - HTTP API
sidebar_title: 'Legacy Tokens'
sidebar_current: api-acl-tokens-legacy
description: |-
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in Consul.
description: >-
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
Consul.
---
# ACL HTTP API
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_
recommended you do not build anything using the legacy system and consider using
the new ACL [Token](/api/acl/tokens.html) and [Policy](/api/acl/policies.html) APIs instead.
# ACL HTTP API
The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul.
For more information about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/consul/security-networking/production-acls).

View File

@ -1,15 +1,15 @@
---
layout: api
page_title: ACL Policies - HTTP API
sidebar_title: 'Policies'
sidebar_current: api-acl-policies
description: |-
The /acl/policy endpoints manage Consul's ACL policies.
description: The /acl/policy endpoints manage Consul's ACL policies.
---
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html)
# ACL Policy HTTP API
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html)
The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy),
[update](#update-a-policy), [list](#list-policies) and
[delete](#delete-a-policy) ACL policies in Consul.

View File

@ -1,15 +1,15 @@
---
layout: api
page_title: ACL Roles - HTTP API
sidebar_title: 'Roles'
sidebar_current: api-acl-roles
description: |-
The /acl/role endpoints manage Consul's ACL Roles.
description: The /acl/role endpoints manage Consul's ACL Roles.
---
-> **1.5.0+:** The role APIs are available in Consul versions 1.5.0 and newer.
# ACL Role HTTP API
-> **1.5.0+:** The role APIs are available in Consul versions 1.5.0 and newer.
The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul.

View File

@ -1,15 +1,15 @@
---
layout: api
page_title: ACL Tokens - HTTP API
sidebar_title: 'Tokens'
sidebar_current: api-acl-tokens
description: |-
The /acl/token endpoints manage Consul's ACL Tokens.
description: The /acl/token endpoints manage Consul's ACL Tokens.
---
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html)
# ACL Token HTTP API
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html)
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.

View File

@ -1,9 +1,9 @@
---
layout: api
page_title: Check - Agent - HTTP API
sidebar_title: 'Checks'
sidebar_current: api-agent-check
description: |-
The /agent/check endpoints interact with checks on the local agent in Consul.
description: The /agent/check endpoints interact with checks on the local agent in Consul.
---
# Check - Agent HTTP API

View File

@ -1,9 +1,11 @@
---
layout: api
page_title: Connect - Agent - HTTP API
sidebar_title: 'Connect'
sidebar_current: api-agent-connect
description: |-
The /agent/connect endpoints interact with Connect with agent-local operations.
description: >-
The /agent/connect endpoints interact with Connect with agent-local
operations.
---
# Connect - Agent HTTP API

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Agent - HTTP API
sidebar_title: 'Agent'
sidebar_current: api-agent
description: |-
The /agent endpoints interact with the local Consul agent to register

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Service - Agent - HTTP API
sidebar_title: 'Services'
sidebar_current: api-agent-service
description: |-
The /agent/service endpoints interact with services on the local agent in
@ -145,8 +146,8 @@ The table below shows this endpoint's support for
| ----------------- | ----------------- | ------------- | -------------- |
| `YES`<sup>1</sup> | `none` | `none` | `service:read` |
<sup>1</sup> Supports [hash-based
blocking](/api/features/blocking.html#hash-based-blocking-queries) only.
<sup>1</sup> Supports [hash-based blocking](/api/features/blocking.html#hash-based-blocking-queries)
only.
### Parameters

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Catalog - HTTP API
sidebar_title: 'Catalog'
sidebar_current: api-catalog
description: |-
The /catalog endpoints register and deregister nodes, services, and checks in

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Config - HTTP API
sidebar_title: 'Config'
sidebar_current: api-config
description: |-
The /config endpoints are for managing centralized configuration
@ -30,11 +31,13 @@ The table below shows this endpoint's support for
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------------------------- |
| `NO` | `none` | `none` | `service:write`<br>`operator:write`<sup>1</sup> |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
| `NO` | `none` | `none` | `service:write`<br />`operator:write`<sup>1</sup> |
<sup>1</sup> The ACL required depends on the config entry kind being updated:
<p>
<sup>1</sup> The ACL required depends on the config entry kind being updated:
</p>
| Config Entry Kind | Required ACL |
| ----------------- | ---------------- |
@ -221,9 +224,9 @@ The table below shows this endpoint's support for
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------------------------- |
| `NO` | `none` | `none` | `service:write`<br>`operator:write`<sup>1</sup> |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
| `NO` | `none` | `none` | `service:write`<br />`operator:write`<sup>1</sup> |
<sup>1</sup> The ACL required depends on the config entry kind being deleted:

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Certificate Authority - Connect - HTTP API
sidebar_title: 'Certificate Authority (CA)'
sidebar_current: api-connect-ca
description: |-
The /connect/ca endpoints provide tools for interacting with Connect's

View File

@ -1,9 +1,11 @@
---
layout: api
page_title: Connect - HTTP API
sidebar_title: 'Connect'
sidebar_current: api-connect
description: |-
The `/connect` endpoints provide access to Connect-related operations for intentions and the certificate authority.
description: >-
The `/connect` endpoints provide access to Connect-related operations for
intentions and the certificate authority.
---
# Connect HTTP Endpoint

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Intentions - Connect - HTTP API
sidebar_title: 'Intentions'
sidebar_current: api-connect-intentions
description: |-
The /connect/intentions endpoint provide tools for managing intentions via
@ -35,8 +36,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
@ -106,8 +113,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
@ -162,8 +175,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
@ -241,8 +260,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
@ -289,8 +314,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
@ -329,8 +360,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
@ -376,8 +413,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Coordinate - HTTP API
sidebar_title: 'Coordinates'
sidebar_current: api-coordinate
description: |-
The /coordinate endpoints query for the network coordinates for nodes in the

View File

@ -1,9 +1,9 @@
---
layout: api
page_title: Discovery Chain - HTTP API
sidebar_title: 'Discovery Chain'
sidebar_current: api-discovery-chain
description: |-
The /discovery-chain endpoints are for interacting with the discovery chain.
description: The /discovery-chain endpoints are for interacting with the discovery chain.
---
-> **1.6.0+:** The discovery chain API is available in Consul versions 1.6.0 and newer.
@ -33,8 +33,11 @@ the `POST` method must be used, otherwise `GET` is sufficient.
| `GET` | `/discovery-chain/:service` | `application/json` |
| `POST`<sup>1</sup> | `/discovery-chain/:service` | `application/json` |
<sup>1</sup> Both GET and POST are for **read** operations. GET requests do not
permit request bodies so a POST is required if override parameters are needed.
<p>
<sup>1</sup> Both GET and POST are for <strong>read</strong> operations. GET
requests do not permit request bodies so a POST is required if override
parameters are needed.
</p>
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Events - HTTP API
sidebar_title: 'Events'
sidebar_current: api-event
description: |-
The /event endpoints fire new events and to query the available events in

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Blocking Queries
sidebar_title: 'Blocking Queries'
sidebar_current: api-features-blocking
description: |-
Many endpoints in Consul support a feature known as "blocking queries". A

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Agent Caching
sidebar_title: 'Agent Caching'
sidebar_current: api-features-caching
description: |-
Some read endpoints support agent caching. They are clearly marked in the

View File

@ -1,9 +1,13 @@
---
layout: api
page_title: Consistency Modes
sidebar_title: 'API Features'
sidebar_current: api-features-consistency
description: |-
Most of the read query endpoints support multiple levels of consistency. Since no policy will suit all clients' needs, these consistency modes allow the user to have the ultimate say in how to balance the trade-offs inherent in a distributed system.
description: >-
Most of the read query endpoints support multiple levels of consistency. Since
no policy will suit all clients' needs, these consistency modes allow the user
to have the ultimate say in how to balance the trade-offs inherent in a
distributed system.
---
# Consistency Modes

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Filtering
sidebar_title: 'Filtering'
sidebar_current: api-features-filtering
description: |-
Consul exposes a RESTful HTTP API to control almost every aspect of the

View File

@ -0,0 +1,7 @@
---
layout: api
page_title: API Features
sidebar_title: 'API Features'
---
Placeholder

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Health - HTTP API
sidebar_title: 'Health'
sidebar_current: api-health
description: |-
The /health endpoints query health-related information for services and checks

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: HTTP API
sidebar_title: 'API Introduction'
sidebar_current: api-introduction
description: |-
Consul exposes a RESTful HTTP API to control almost every aspect of the

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: KV Store - HTTP API
sidebar_title: 'KV Store'
sidebar_current: api-kv-store
description: |-
The /kv endpoints access Consul's simple key/value store, useful for storing

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Libraries and SDKs - HTTP API
sidebar_title: 'Libraries &amp; SDKs'
sidebar_current: api-libraries-and-sdks
description: |-
There are many third-party libraries for interacting with Consul's HTTP API.
@ -16,76 +17,112 @@ the community.
<ul>
<li>
<a href="https://github.com/hashicorp/consul/tree/master/api">api</a> - Official Go client for the Consul HTTP API
<a href="https://github.com/hashicorp/consul/tree/master/api">api</a> -
Official Go client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/gmr/consulate">consulate</a> - Python client for the Consul HTTP API
<a href="https://github.com/gmr/consulate">consulate</a> - Python client for
the Consul HTTP API
</li>
<li>
<a href="https://github.com/cablehead/python-consul">python-consul</a> - Python client for the Consul HTTP API
<a href="https://github.com/cablehead/python-consul">python-consul</a> -
Python client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/poppyred/python-consul2">python-consul2</a> - Python client for the Consul HTTP API
<a href="https://github.com/poppyred/python-consul2">python-consul2</a> -
Python client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/vdloo/consul-kv">consul-kv</a> - Python 3 client for the Consul KV-store
<a href="https://github.com/vdloo/consul-kv">consul-kv</a> - Python 3 client
for the Consul KV-store
</li>
<li>
<a href="https://github.com/sensiolabs/consul-php-sdk">consul-php-sdk</a> - PHP client for the Consul HTTP API
<a href="https://github.com/sensiolabs/consul-php-sdk">consul-php-sdk</a> -
PHP client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/dcarbone/php-consul-api">php-consul-api</a> - GO-like PHP Client for the Consul HTTP API
<a href="https://github.com/dcarbone/php-consul-api">php-consul-api</a> -
GO-like PHP Client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/tolitius/envoy">envoy</a> - Consul Clojure client with watchers and other goodies
<a href="https://github.com/tolitius/envoy">envoy</a> - Consul Clojure
client with watchers and other goodies
</li>
<li>
<a href="https://github.com/hadielmougy/clj-consul-catalog">clj-consul-catalog</a> - Clojure discovery client for the Consul HTTP API
<a href="https://github.com/hadielmougy/clj-consul-catalog">
clj-consul-catalog
</a>{' '}
- Clojure discovery client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/Verizon/helm">helm</a> - A native Scala client for interacting with Consul
<a href="https://github.com/Verizon/helm">helm</a> - A native Scala client
for interacting with Consul
</li>
<li>
<a href="https://github.com/rickfast/consul-client">consul-client</a> - Java client for the Consul HTTP API
<a href="https://github.com/rickfast/consul-client">consul-client</a> - Java
client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/Ecwid/consul-api">consul-api</a> - Java client for the Consul HTTP API
<a href="https://github.com/Ecwid/consul-api">consul-api</a> - Java client
for the Consul HTTP API
</li>
<li>
<a href="http://cloud.spring.io/spring-cloud-consul/">Spring Cloud Consul</a> - Consul integration for <a href="https://projects.spring.io/spring-boot/">Spring Boot</a> applications (Uses
<li>
<a href="http://cloud.spring.io/spring-cloud-consul/">
Spring Cloud Consul
</a>{' '}
- Consul integration for{' '}
<a href="https://projects.spring.io/spring-boot/">Spring Boot</a>{' '}
applications (Uses
<a href="https://github.com/Ecwid/consul-api">consul-api</a> internally)
</li>
<li>
<a href="https://github.com/vert-x3/vertx-consul-client">vertx-consul-client</a> - Vert.x client for the Consul HTTP API
<a href="https://github.com/vert-x3/vertx-consul-client">
vertx-consul-client
</a>{' '}
- Vert.x client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/undeadlabs/discovery">discovery</a> - Erlang/OTP client for the Consul HTTP API
<a href="https://github.com/undeadlabs/discovery">discovery</a> - Erlang/OTP
client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/WeAreFarmGeek/diplomat">diplomat</a> - Ruby library to query Consul's KV-store and services directory
<a href="https://github.com/WeAreFarmGeek/diplomat">diplomat</a> - Ruby
library to query Consul's KV-store and services directory
</li>
<li>
<a href="https://www.npmjs.com/package/consul">node-consul</a> - Node.js client for the Consul HTTP API
<a href="https://www.npmjs.com/package/consul">node-consul</a> - Node.js
client for the Consul HTTP API
</li>
<li>
<a href="https://www.nuget.org/packages/Consul">Consul.NET</a> - C# client for the Consul HTTP API
<a href="https://www.nuget.org/packages/Consul">Consul.NET</a> - C# client
for the Consul HTTP API
</li>
<li>
<a href="https://metacpan.org/pod/Consul">Consul</a> - Perl client for the Consul HTTP API
<a href="https://metacpan.org/pod/Consul">Consul</a> - Perl client for the
Consul HTTP API
</li>
<li>
<a href="https://github.com/Drawaes/CondenserDotNet">CondenserDotNet</a> - C# an opinionated API for .NET that provides higher level functionality for services using the HTTP API
<a href="https://github.com/Drawaes/CondenserDotNet">CondenserDotNet</a> -
C# an opinionated API for .NET that provides higher level functionality for
services using the HTTP API
</li>
<li>
<a href="https://github.com/cpageler93/ConsulSwift">ConsulSwift</a> - Swift client for the Consul HTTP API
<a href="https://github.com/cpageler93/ConsulSwift">ConsulSwift</a> - Swift
client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/oatpp/oatpp-consul">oatpp-consul</a> - C++ Consul integration for <a href="https://oatpp.io/">oatpp</a> applications
<a href="https://github.com/oatpp/oatpp-consul">oatpp-consul</a> - C++
Consul integration for <a href="https://oatpp.io/">oatpp</a> applications
</li>
<li>
<a href="https://github.com/marlonmleite/consul-env-webpack-plugin">consul-env-webpack-plugin</a> - Webpack plugin for converting KV store JSON output to environments variables.
<a href="https://github.com/marlonmleite/consul-env-webpack-plugin">
consul-env-webpack-plugin
</a>{' '}
- Webpack plugin for converting KV store JSON output to environments
variables.
</li>
<li>
<a href="https://github.com/rogerwelin/crystal-consul">crystal-consul</a> - Crystal client for the Consul HTTP API
<a href="https://github.com/rogerwelin/crystal-consul">crystal-consul</a> -
Crystal client for the Consul HTTP API
</li>
</ul>

View File

@ -1,9 +1,9 @@
---
layout: api
page_title: Namespace - HTTP API
sidebar_title: 'Namespaces'
sidebar_current: api-namespaces
description: |-
The /namespace endpoints allow for managing Consul Enterprise Namespaces.
description: The /namespace endpoints allow for managing Consul Enterprise Namespaces.
---
# Namespace - HTTP API
@ -153,9 +153,9 @@ The table below shows this endpoint's support for
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------------------------ |
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1<sup> |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1</sup> |
<sup>1</sup> Access can be granted to list the Namespace if the token used when making
the request has been granted any access in the namespace (read, list or write).

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Network Areas - Operator - HTTP API
sidebar_title: 'Area'
sidebar_current: api-operator-area
description: |-
The /operator/area endpoints expose the network tomography information via

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Autopilot - Operator - HTTP API
sidebar_title: 'Autopilot'
sidebar_current: api-operator-autopilot
description: |-
The /operator/autopilot endpoints allow for automatic operator-friendly

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Operator - HTTP API
sidebar_title: 'Operator'
sidebar_current: api-operator
description: |-
The /operator endpoints provide cluster-level tools for Consul operators,

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Keyring - Operator - HTTP API
sidebar_title: 'Keyring'
sidebar_current: api-operator-keyring
description: |-
The /operator/keyring endpoints allow for management of the gossip encryption

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: License - Operator - HTTP API
sidebar_title: 'License'
sidebar_current: api-operator-license
description: |-
The /operator/license endpoints allow for setting and retrieving the Consul

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Raft - Operator - HTTP API
sidebar_title: 'Raft'
sidebar_current: api-operator-raft
description: |-
The /operator/raft endpoints provide tools for management of Raft the

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Network Segments - Operator - HTTP API
sidebar_title: 'Segment'
sidebar_current: api-operator-segment
description: |-
The /operator/segment endpoint exposes the network segment information via

View File

@ -1,9 +1,9 @@
---
layout: api
page_title: Prepared Queries - HTTP API
sidebar_title: 'Prepared Queries'
sidebar_current: api-query
description: |-
The /query endpoints manage and execute prepared queries in Consul.
description: The /query endpoints manage and execute prepared queries in Consul.
---
# Prepared Query HTTP Endpoint
@ -491,9 +491,9 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------------- |
| `NO` | `none` | `simple` | `depends`<sup>1</sup> |
<sup>1</sup> If an ACL Token was bound to the query when it was defined then it
will be used when executing the request. Otherwise, the client's supplied ACL
Token will be used.
<sup>1</sup> If an ACL Token was bound to the query when it was defined then it will
be used when executing the request. Otherwise, the client's supplied ACL Token will
be used.
### Parameters

View File

@ -1,9 +1,9 @@
---
layout: api
page_title: Session - HTTP API
sidebar_title: 'Sessions'
sidebar_current: api-session
description: |-
The /session endpoints create, destroy, and query sessions in Consul.
description: 'The /session endpoints create, destroy, and query sessions in Consul.'
---
# Session HTTP Endpoint

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Snapshot - HTTP API
sidebar_title: 'Snapshots'
sidebar_current: api-snapshot
description: |-
The /snapshot endpoints save and restore Consul's server state for disaster

View File

@ -1,6 +1,7 @@
---
layout: api
page_title: Status - HTTP API
sidebar_title: 'Status'
sidebar_current: api-status
description: |-
The /status endpoints return information about the status of the Consul

View File

@ -1,9 +1,12 @@
---
layout: api
page_title: Transaction - HTTP API
sidebar_title: 'Transactions'
sidebar_current: api-txn
description: |-
The /txn endpoint manages multiple operations in Consul, including catalog updates and fetches of multiple KV entries inside a single, atomic transaction.
description: >-
The /txn endpoint manages multiple operations in Consul, including catalog
updates and fetches of multiple KV entries inside a single, atomic
transaction.
---
# Transactions HTTP API
@ -40,13 +43,15 @@ The table below shows this endpoint's support for
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------------------------------------------------------------------ |
| `NO` | `all`<sup>1</sup> | `none` | `key:read,key:write`<br>`node:read,node:write`<br>`service:read,service:write`<sup>2</sup> |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `NO` | `all`<sup>1</sup> | `none` | `key:read,key:write`<br />`node:read,node:write`<br />`service:read,service:write`<sup>2</sup> |
<sup>1</sup> For read-only transactions
<br>
<sup>2</sup> The ACL required depends on the operations in the transaction.
<p>
<sup>1</sup> For read-only transactions
<br />
<sup>2</sup> The ACL required depends on the operations in the transaction.
</p>
### Parameters
@ -109,7 +114,7 @@ The table below shows this endpoint's support for
The body of the request should be a list of operations to perform inside the
atomic transaction. Up to 64 operations may be present in a single transaction.
```javascript
```json
[
{
"KV": {
@ -182,7 +187,7 @@ was successfully applied, or a status code of 409 will be returned if it was
rolled back. If either of these status codes are returned, the response will
look like this:
```javascript
```json
{
"Results": [
{

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
page_title: 'ACL Auth Methods'
sidebar_current: 'docs-acl-auth-methods'
description: |-
An auth method is a component in Consul that performs authentication against a trusted external party to authorize the creation of an ACL tokens usable within the local datacenter.
layout: docs
page_title: ACL Auth Methods
sidebar_current: docs-acl-auth-methods
description: >-
An auth method is a component in Consul that performs authentication against a
trusted external party to authorize the creation of an ACL tokens usable
within the local datacenter.
---
-> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer.

View File

@ -1,9 +1,12 @@
---
layout: 'docs'
page_title: 'ACL System (Legacy Mode)'
sidebar_current: 'docs-acl-legacy'
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
layout: docs
page_title: ACL System (Legacy Mode)
sidebar_current: docs-acl-legacy
description: >-
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. The ACL system is a Capability-based
system that relies on tokens which can have fine grained rules applied to
them. It is very similar to AWS IAM in many ways.
---
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system.html)
@ -988,43 +991,14 @@ prepared query namespace.
These differences are outlined in the table below:
<table class="table table-bordered table-striped">
<tr>
<th>Operation</th>
<th>Version <= 0.6.3 </th>
<th>Version > 0.6.3 </th>
</tr>
<tr>
<td>Create static query without `Name`</td>
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
<td>No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
</tr>
<tr>
<td>Create static query with `Name`</td>
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
<td>The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
</tr>
<tr>
<td>Manage static query without `Name`</td>
<td>The ACL Token used to create the query, or a management token must be supplied in order to perform these operations.</td>
<td>Any client with the ID of the query can perform these operations.</td>
</tr>
<tr>
<td>Manage static query with a `Name`</td>
<td>The ACL token used to create the query, or a management token must be supplied in order to perform these operations.</td>
<td>Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed.</td>
</tr>
<tr>
<td>List queries</td>
<td>A management token is required to list any queries.</td>
<td>The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`.</td>
</tr>
<tr>
<td>Execute query</td>
<td>Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored.</td>
<td>The captured token, client's token, or anonymous token is used to filter the results, as described above.</td>
</tr>
</table>
| Operation | Version <= 0.6.3 | Version > 0.6.3 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create static query without `Name` | The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. | No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
| Create static query with `Name` | The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. | The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
| Manage static query without `Name` | The ACL Token used to create the query, or a management token must be supplied in order to perform these operations. | Any client with the ID of the query can perform these operations. |
| Manage static query with a `Name` | The ACL token used to create the query, or a management token must be supplied in order to perform these operations. | Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed. |
| List queries | A management token is required to list any queries. | The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`. |
| Execute query | Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored. | The captured token, client's token, or anonymous token is used to filter the results, as described above. |
#### Service Rules

View File

@ -1,10 +1,13 @@
---
layout: 'docs'
page_title: 'ACL Token Migration'
sidebar_current: 'docs-acl-migrate-tokens'
description: |-
Consul 1.4.0 introduces a new ACL system with improvements for the security and
layout: docs
page_title: ACL Token Migration
sidebar_current: docs-acl-migrate-tokens
description: >-
Consul 1.4.0 introduces a new ACL system with improvements for the security
and
management of ACL tokens and policies. This guide documents how to upgrade
existing (now called "legacy") tokens after upgrading to 1.4.0.
---

View File

@ -1,22 +1,25 @@
---
layout: "docs"
page_title: "ACL Rules"
sidebar_current: "docs-acl-rules"
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
layout: docs
page_title: ACL Rules
sidebar_current: docs-acl-rules
description: >-
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. The ACL system is a Capability-based
system that relies on tokens which can have fine grained rules applied to
them. It is very similar to AWS IAM in many ways.
---
-> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy.html)
# ACL Rules
Consul provides an optional Access Control List (ACL) system which can be used
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. To learn more about Consul's ACL review the
[ACL system documentation](/docs/acl/acl-system.html)
A core part of the ACL system is the rule language, which is used to describe the policy
that must be enforced. There are two types of rules: prefix based rules and exact matching
rules.
rules.
## Rule Specification
@ -38,17 +41,17 @@ Note that not all resource areas are segmented such as the `keyring`, `operator`
Policies can have several control levels:
* `read`: allow the resource to be read but not modified.
* `write`: allow the resource to be read and modified.
* `deny`: do not allow the resource to be read or modified.
* `list`: allows access to all the keys under a segment in the Consul KV. Note, this policy can only be used with the `key_prefix` resource and [`acl.enable_key_list_policy`](/docs/agent/options.html#acl_enable_key_list) must be set to true.
- `read`: allow the resource to be read but not modified.
- `write`: allow the resource to be read and modified.
- `deny`: do not allow the resource to be read or modified.
- `list`: allows access to all the keys under a segment in the Consul KV. Note, this policy can only be used with the `key_prefix` resource and [`acl.enable_key_list_policy`](/docs/agent/options.html#acl_enable_key_list) must be set to true.
When using prefix-based rules, the most specific prefix match determines the action. This
allows for flexible rules like an empty prefix to allow read-only access to all
resources, along with some specific prefixes that allow write access or that are
denied all access. Exact matching rules will only apply to the exact resource specified.
The order of precedence for matching rules are, DENY has priority over WRITE or READ and
WRITE has priority over READ.
The order of precedence for matching rules are, DENY has priority over WRITE or READ and
WRITE has priority over READ.
We make use of the
[HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl/) to specify
@ -92,9 +95,9 @@ This is equivalent to the following JSON input:
"policy": "deny"
}
},
"key" : {
"foo/bar/secret" : {
"policy" : "deny"
"key": {
"foo/bar/secret": {
"policy": "deny"
}
},
"operator": "read"
@ -132,20 +135,20 @@ On success, the Policy is returned:
```json
{
"CreateIndex": 7,
"Hash": "UMG6QEbV40Gs7Cgi6l/ZjYWUwRS0pIxxusFKyKOt8qI=",
"ID": "5f423562-aca1-53c3-e121-cb0eb2ea1cd3",
"ModifyIndex": 7,
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
"CreateIndex": 7,
"Hash": "UMG6QEbV40Gs7Cgi6l/ZjYWUwRS0pIxxusFKyKOt8qI=",
"ID": "5f423562-aca1-53c3-e121-cb0eb2ea1cd3",
"ModifyIndex": 7,
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}
```
The created policy can now be specified either by name or by ID when
The created policy can now be specified either by name or by ID when
[creating a token](https://learn.hashicorp.com/consul/security-networking/production-acls#create-the-agent-token). This will grant the rules
provided to the [bearer of that token](/api/index.html#authentication).
Below is a breakdown of each rule type.
Below is a breakdown of each rule type.
#### ACL Resource Rules
@ -183,9 +186,9 @@ agent_prefix "bar" {
```
Agent rules are keyed by the node name they apply to. In the example above the rules
allow read-only access to any node name by using the empty prefix, read-write access to
allow read-only access to any node name by using the empty prefix, read-write access to
the node with the _exact_ name `foo`, and denies all access to any node name that starts
with `bar`.
with `bar`.
Since [Agent API](/api/agent.html) utility operations may be required before an agent is joined to
a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be
@ -211,7 +214,7 @@ event "deploy" {
Event rules are segmented by the event name they apply to. In the example above, the rules allow
read-only access to any event, and firing of the "deploy" event.
The [`consul exec`](/docs/commands/exec.html) command uses events with the "_rexec" prefix during
The [`consul exec`](/docs/commands/exec.html) command uses events with the "\_rexec" prefix during
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options.html#disable_remote_exec) to `false`.
@ -391,7 +394,7 @@ There are a few variations when using ACLs with prepared queries, each of which
ways: open, protected by unguessable IDs or closed, managed by ACL policies. These variations are covered
here, with examples:
* Static queries with no `Name` defined are not controlled by any ACL policies.
- Static queries with no `Name` defined are not controlled by any ACL policies.
These types of queries are meant to be ephemeral and not shared to untrusted
clients, and they are only reachable if the prepared query ID is known. Since
these IDs are generated using the same random ID scheme as ACL Tokens, it is
@ -401,7 +404,7 @@ here, with examples:
startup script, tied to a session, and written to a configuration file for a
process to use via DNS.
* Static queries with a `Name` defined are controlled by the `query` and `query_prefix`
- Static queries with a `Name` defined are controlled by the `query` and `query_prefix`
ACL resources. Clients are required to have an ACL token with permissions on to
access that query name. Clients can list or read queries for
which they have "read" access based on their prefix, and similar they can
@ -410,7 +413,7 @@ here, with examples:
that is used and known by many clients to provide geo-failover behavior for
a database.
* [Template queries](/api/query.html#templates)
- [Template queries](/api/query.html#templates)
queries work like static queries with a `Name` defined, except that a catch-all
template with an empty `Name` requires an ACL token that can write to any query
prefix.
@ -420,14 +423,14 @@ checks are run against the service being queried, similar to how ACLs work with
other service lookups. There are several ways the ACL token is selected for this
check:
* If an ACL Token was captured when the prepared query was defined, it will be
- If an ACL Token was captured when the prepared query was defined, it will be
used to perform the service lookup. This allows queries to be executed by
clients with lesser or even no ACL Token, so this should be used with care.
* If no ACL Token was captured, then the client's ACL Token will be used to
- If no ACL Token was captured, then the client's ACL Token will be used to
perform the service lookup.
* If no ACL Token was captured and the client has no ACL Token, then the
- If no ACL Token was captured and the client has no ACL Token, then the
anonymous token will be used to perform the service lookup.
In the common case, the ACL Token of the invoker is used
@ -446,43 +449,14 @@ prepared query namespace.
These differences are outlined in the table below:
<table class="table table-bordered table-striped">
<tr>
<th>Operation</th>
<th>Version <= 0.6.3 </th>
<th>Version > 0.6.3 </th>
</tr>
<tr>
<td>Create static query without `Name`</td>
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
<td>No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
</tr>
<tr>
<td>Create static query with `Name`</td>
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
<td>The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
</tr>
<tr>
<td>Manage static query without `Name`</td>
<td>The ACL Token used to create the query or a token with management privileges must be supplied in order to perform these operations.</td>
<td>Any client with the ID of the query can perform these operations.</td>
</tr>
<tr>
<td>Manage static query with a `Name`</td>
<td>The ACL token used to create the query or a token with management privileges must be supplied in order to perform these operations.</td>
<td>Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed.</td>
</tr>
<tr>
<td>List queries</td>
<td>A token with management privileges is required to list any queries.</td>
<td>The client token's `query` ACL policy is used to determine which queries they can see. Only tokens with management privileges can see prepared queries without `Name`.</td>
</tr>
<tr>
<td>Execute query</td>
<td>Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored.</td>
<td>The captured token, client's token, or anonymous token is used to filter the results, as described above.</td>
</tr>
</table>
| Operation | Version <= 0.6.3 | Version > 0.6.3 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create static query without `Name` | The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. | No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
| Create static query with `Name` | The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. | The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
| Manage static query without `Name` | The ACL Token used to create the query or a token with management privileges must be supplied in order to perform these operations. | Any client with the ID of the query can perform these operations. |
| Manage static query with a `Name` | The ACL token used to create the query or a token with management privileges must be supplied in order to perform these operations. | Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed. |
| List queries | A token with management privileges is required to list any queries. | The client token's `query` ACL policy is used to determine which queries they can see. Only tokens with management privileges can see prepared queries without `Name`. |
| Execute query | Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored. | The captured token, client's token, or anonymous token is used to filter the results, as described above. |
#### Service Rules
@ -565,19 +539,19 @@ and deny all access to any sessions on the "admin" node.
#### Namespace Rules <span class="label-enterprise label-enterprise-lg">Enterprise</span>
[Consul Enterprise](https://www.hashicorp.com/consul.html) 1.7.0 adds support for namespacing many
[Consul Enterprise](https://www.hashicorp.com/consul.html) 1.7.0 adds support for namespacing many
Consul resources. ACL rules themselves can then be defined to only to apply to specific namespaces.
A Namespace specific rule would look like this:
```hcl
namespace_prefix "" {
# grant service:read for all services in all namespaces
service_prefix "" {
policy = "read"
}
# grant node:read for all nodes in all namespaces
node_prefix "" {
policy = "read"
@ -587,22 +561,22 @@ namespace_prefix "" {
namespace "foo" {
# grants permission to manage ACLs only for the foo namespace
acl = "write"
# grants write permissions to the KV for namespace foo
key_prefix "" {
policy = "write"
}
# grants write permissions for sessions for namespace foo
session_prefix "" {
policy = "write"
}
# grants service:write for all services in the foo namespace
service_prefix "" {
policy = "write"
}
# grants node:read for all nodes
node_prefix "" {
policy = "read"
@ -618,11 +592,11 @@ Note, when a rule is defined in any user created namespace, the following restri
4. `query` rules are not allowed.
5. `node` rules that attempt to grant `write` privileges are not allowed.
These restrictions do not apply to the `default` namespace created by Consul. In general all of the
These restrictions do not apply to the `default` namespace created by Consul. In general all of the
above are permissions that only an operator should have and thus granting these permissions can
only be done within the default namespace.
-> **Implicit namespacing:** Rules and policies created within a namespace will inherit the namespace configuration.
This means that rules and policies will be implicitly namespaced and do not need additional configuration.
The restrictions outlined above will apply to these rules and policies. Additionally, rules and policies within a
-> **Implicit namespacing:** Rules and policies created within a namespace will inherit the namespace configuration.
This means that rules and policies will be implicitly namespaced and do not need additional configuration.
The restrictions outlined above will apply to these rules and policies. Additionally, rules and policies within a
specific namespace are prevented from accessing resources in another namespace.

View File

@ -1,9 +1,12 @@
---
layout: 'docs'
page_title: 'ACL System'
sidebar_current: 'docs-acl-system'
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
layout: docs
page_title: ACL System
sidebar_current: docs-acl-system
description: >-
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. The ACL system is a Capability-based
system that relies on tokens which can have fine grained rules applied to
them. It is very similar to AWS IAM in many ways.
---
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy.html)

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
page_title: 'Kubernetes Auth Method'
sidebar_current: 'docs-acl-auth-methods-kubernetes'
description: |-
The Kubernetes auth method type allows for a Kubernetes service account token to be used to authenticate to Consul. This method of authentication makes it easy to introduce a Consul token into a Kubernetes pod.
layout: docs
page_title: Kubernetes Auth Method
sidebar_current: docs-acl-auth-methods-kubernetes
description: >-
The Kubernetes auth method type allows for a Kubernetes service account token
to be used to authenticate to Consul. This method of authentication makes it
easy to introduce a Consul token into a Kubernetes pod.
---
-> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer.

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
page_title: 'ACL Guides'
sidebar_current: 'docs-acl-index'
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. Select the following guide for your use case.
layout: docs
page_title: ACL Guides
sidebar_current: docs-acl-index
description: >-
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. Select the following guide for your use
case.
---
# ACL Documentation and Guides

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
page_title: 'Agent'
sidebar_current: 'docs-agent-running'
description: |-
The Consul agent is the core process of Consul. The agent maintains membership information, registers services, runs checks, responds to queries, and more. The agent must run on every node that is part of a Consul cluster.
layout: docs
page_title: Agent
sidebar_current: docs-agent-running
description: >-
The Consul agent is the core process of Consul. The agent maintains membership
information, registers services, runs checks, responds to queries, and more.
The agent must run on every node that is part of a Consul cluster.
---
# Consul Agent

View File

@ -1,9 +1,12 @@
---
layout: 'docs'
page_title: 'Check Definition'
sidebar_current: 'docs-agent-checks'
description: |-
One of the primary roles of the agent is management of system- and application-level health checks. A health check is considered to be application-level if it is associated with a service. A check is defined in a configuration file or added at runtime over the HTTP interface.
layout: docs
page_title: Check Definition
sidebar_current: docs-agent-checks
description: >-
One of the primary roles of the agent is management of system- and
application-level health checks. A health check is considered to be
application-level if it is associated with a service. A check is defined in a
configuration file or added at runtime over the HTTP interface.
---
# Checks
@ -77,23 +80,19 @@ There are several different kinds of checks:
It is possible to configure a custom TCP check timeout value by specifying the
`timeout` field in the check definition.
- <a name="TTL"></a>Time to Live (TTL) - These checks retain their last known
state for a given TTL. The state of the check must be updated periodically
over the HTTP interface. If an external system fails to update the status
within a given TTL, the check is set to the failed state. This mechanism,
conceptually similar to a dead man's switch, relies on the application to
directly report its health. For example, a healthy app can periodically `PUT` a
status update to the HTTP endpoint; if the app fails, the TTL will expire and
the health check enters a critical state. The endpoints used to update health
information for a given check are:
[pass](/api/agent/check.html#ttl-check-pass),
[warn](/api/agent/check.html#ttl-check-warn),
[fail](/api/agent/check.html#ttl-check-fail), and
[update](/api/agent/check.html#ttl-check-update). TTL
checks also persist their last known status to disk. This allows the Consul
agent to restore the last known status of the check across restarts. Persisted
check status is valid through the end of the TTL from the time of the last
check.
- <a name="TTL"></a>Time to Live (TTL) - These checks retain their last known state
for a given TTL. The state of the check must be updated periodically over the HTTP
interface. If an external system fails to update the status within a given TTL,
the check is set to the failed state. This mechanism, conceptually similar to a
dead man's switch, relies on the application to directly report its health. For
example, a healthy app can periodically `PUT` a status update to the HTTP endpoint;
if the app fails, the TTL will expire and the health check enters a critical state.
The endpoints used to update health information for a given check are: [pass](/api/agent/check.html#ttl-check-pass),
[warn](/api/agent/check.html#ttl-check-warn), [fail](/api/agent/check.html#ttl-check-fail),
and [update](/api/agent/check.html#ttl-check-update). TTL checks also persist their
last known status to disk. This allows the Consul agent to restore the last known
status of the check across restarts. Persisted check status is valid through the
end of the TTL from the time of the last check.
- Docker + Interval - These checks depend on invoking an external application which
is packaged within a Docker Container. The application is triggered within the running
@ -121,15 +120,14 @@ There are several different kinds of checks:
To check on a specific service instead of the whole gRPC server, add the service identifier after the `gRPC` check's endpoint in the following format `/:service_identifier`.
- <a name="alias"></a>Alias - These checks alias the health state of another registered
node or service. The state of the check will be updated asynchronously,
but is nearly instant. For aliased services on the same agent, the local
state is monitored and no additional network resources are consumed. For
other services and nodes, the check maintains a blocking query over the
agent's connection with a current server and allows stale requests. If there
are any errors in watching the aliased node or service, the check state will be
critical. For the blocking query, the check will use the ACL token set
on the service or check definition or otherwise will fall back to the default ACL
token set with the agent (`acl_token`).
node or service. The state of the check will be updated asynchronously, but is
nearly instant. For aliased services on the same agent, the local state is monitored
and no additional network resources are consumed. For other services and nodes,
the check maintains a blocking query over the agent's connection with a current
server and allows stale requests. If there are any errors in watching the aliased
node or service, the check state will be critical. For the blocking query, the
check will use the ACL token set on the service or check definition or otherwise
will fall back to the default ACL token set with the agent (`acl_token`).
## Check Definition

View File

@ -1,9 +1,10 @@
---
layout: 'docs'
page_title: 'Cloud Auto-join'
sidebar_current: 'docs-agent-cloud-auto-join'
description: |-
Consul supports automatically joining a Consul datacenter using cloud metadata on various providers.
layout: docs
page_title: Cloud Auto-join
sidebar_current: docs-agent-cloud-auto-join
description: >-
Consul supports automatically joining a Consul datacenter using cloud metadata
on various providers.
---
# Cloud Auto-join
@ -180,7 +181,10 @@ $ consul agent -retry-join "provider=softlayer datacenter=... tag_value=... user
```
- `provider` (required) - the name of the provider ("softlayer" in this case).
- <a name="sl_datacenter"></a><a href="#sl_datacenter"><code>datacenter</code></a> (required) - the name of the datacenter to auto-join in.
- <a name="sl_datacenter"></a>
<a href="#sl_datacenter">
<code>datacenter</code>
</a> (required) - the name of the datacenter to auto-join in.
- `tag_value` (required) - the value of the tag to auto-join on.
- `username` (required) - the username to use for auth.
- `api_key` (required) - the api key to use for auth.

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
layout: docs
page_title: 'Configuration Entry Kind: Proxy Defaults'
sidebar_current: 'docs-agent-cfg_entries-proxy_defaults'
description: |-
The proxy-defaults config entry kind allows for configuring global config defaults across all services for Connect proxy configuration. Currently, only one global entry is supported.
sidebar_current: docs-agent-cfg_entries-proxy_defaults
description: >-
The proxy-defaults config entry kind allows for configuring global config
defaults across all services for Connect proxy configuration. Currently, only
one global entry is supported.
---
# Proxy Defaults

View File

@ -1,9 +1,10 @@
---
layout: 'docs'
layout: docs
page_title: 'Configuration Entry Kind: Service Defaults'
sidebar_current: 'docs-agent-cfg_entries-service_defaults'
description: |-
The service-defaults config entry kind controls default global values for a service, such as its protocol.
sidebar_current: docs-agent-cfg_entries-service_defaults
description: >-
The service-defaults config entry kind controls default global values for a
service, such as its protocol.
---
# Service Defaults

View File

@ -1,9 +1,10 @@
---
layout: 'docs'
layout: docs
page_title: 'Configuration Entry Kind: Service Resolver'
sidebar_current: 'docs-agent-cfg_entries-service_resolver'
description: |-
The `service-resolver` config entry kind controls which service instances should satisfy Connect upstream discovery requests for a given service name.
sidebar_current: docs-agent-cfg_entries-service_resolver
description: >-
The `service-resolver` config entry kind controls which service instances
should satisfy Connect upstream discovery requests for a given service name.
---
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.

View File

@ -1,9 +1,10 @@
---
layout: 'docs'
layout: docs
page_title: 'Configuration Entry Kind: Service Router'
sidebar_current: 'docs-agent-cfg_entries-service_router'
description: |-
The service-router config entry kind controls Connect traffic routing and manipulation at networking layer 7 (e.g. HTTP).
sidebar_current: docs-agent-cfg_entries-service_router
description: >-
The service-router config entry kind controls Connect traffic routing and
manipulation at networking layer 7 (e.g. HTTP).
---
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.

View File

@ -1,9 +1,12 @@
---
layout: 'docs'
layout: docs
page_title: 'Configuration Entry Kind: Service Splitter'
sidebar_current: 'docs-agent-cfg_entries-service_splitter'
description: |-
The service-splitter config entry kind controls how to split incoming Connect requests across different subsets of a single service (like during staged canary rollouts), or perhaps across different services (like during a v2 rewrite or other type of codebase migration).
sidebar_current: docs-agent-cfg_entries-service_splitter
description: >-
The service-splitter config entry kind controls how to split incoming Connect
requests across different subsets of a single service (like during staged
canary rollouts), or perhaps across different services (like during a v2
rewrite or other type of codebase migration).
---
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.

View File

@ -1,9 +1,10 @@
---
layout: 'docs'
page_title: 'Configuration Entry Definitions'
sidebar_current: 'docs-agent-cfg_entries'
description: |-
Consul allows storing configuration entries centrally to be used as defaults for configuring other aspects of Consul.
layout: docs
page_title: Configuration Entry Definitions
sidebar_current: docs-agent-cfg_entries
description: >-
Consul allows storing configuration entries centrally to be used as defaults
for configuring other aspects of Consul.
---
# Configuration Entries

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
page_title: 'DNS Interface'
sidebar_current: 'docs-agent-dns'
description: |-
One of the primary query interfaces for Consul is DNS. The DNS interface allows applications to make use of service discovery without any high-touch integration with Consul.
layout: docs
page_title: DNS Interface
sidebar_current: docs-agent-dns
description: >-
One of the primary query interfaces for Consul is DNS. The DNS interface
allows applications to make use of service discovery without any high-touch
integration with Consul.
---
# DNS Interface
@ -48,7 +50,9 @@ To resolve names, Consul relies on a very specific format for queries.
There are fundamentally two types of queries: node lookups and service lookups.
A node lookup, a simple query for the address of a named node, looks like this:
<node>.node[.datacenter].<domain>
```text
<node>.node[.datacenter].<domain>
```
For example, if we have a `foo` node with default settings, we could
look for `foo.node.dc1.consul.` The datacenter is an optional part of
@ -115,7 +119,9 @@ it is recommended to use the HTTP API to retrieve the list of nodes.
The format of a standard service lookup is:
[tag.]<service>.service[.datacenter].<domain>
```text
[tag.]<service>.service[.datacenter].<domain>
```
The `tag` is optional, and, as with node lookups, the `datacenter` is as
well. If no tag is provided, no filtering is done on tag. If no
@ -204,7 +210,9 @@ Again, note that the SRV record returns the port of the service as well as its I
The format of a prepared query lookup is:
<query or name>.query[.datacenter].<domain>
```text
<query or name>.query[.datacenter].<domain>
```
The `datacenter` is optional, and if not provided, the datacenter of this Consul
agent is assumed.
@ -227,7 +235,9 @@ only served if the client specifically requests them.
To find Connect-capable services:
<service>.connect.<domain>
```text
<service>.connect.<domain>
```
This will find all [Connect-capable](/docs/connect/index.html)
endpoints for the given `service`. A Connect-capable endpoint may be
@ -274,7 +284,9 @@ services via DNS. To maintain backwards compatibility existing queries can be us
and these will resolve services within the `default` namespace. However, for resolving
services from other namespaces the following form can be used:
[tag.]<service>.service.<namespace>.<datacenter>.<domain>
```text
[tag.]<service>.service.<namespace>.<datacenter>.<domain>
```
This is the canonical name of a Consul Enterprise service with all parts present. Like
Consul OSS some parts may be omitted but which parts depend on the value of the
@ -283,12 +295,16 @@ Consul OSS some parts may be omitted but which parts depend on the value of the
With `prefer_namespace` set to `true` the datacenter may be omitted and will be defaulted
to the local agents datacenter:
[tag.]<service>.service.<namespace>.<domain>
```text
[tag.]<service>.service.<namespace>.<domain>
```
With `prefer_namespace` set to `false` the namespace may be omitted and will be defaulted
to the `default` namespace:
[tag.]<service>.service.<datacenter>
```text
[tag.]<service>.service.<datacenter>
```
Finally, both the namespace and datacenter may be omitted and the service will be resolved
in the `default` namespace and in the datacenter of the local agent.

View File

@ -1,9 +1,11 @@
---
layout: 'docs'
page_title: 'Encryption'
sidebar_current: 'docs-agent-encryption'
description: |-
The Consul agent supports encrypting all of its network traffic. The exact method of encryption is described on the encryption internals page. There are two separate encryption systems, one for gossip traffic and one for RPC.
layout: docs
page_title: Encryption
sidebar_current: docs-agent-encryption
description: >-
The Consul agent supports encrypting all of its network traffic. The exact
method of encryption is described on the encryption internals page. There are
two separate encryption systems, one for gossip traffic and one for RPC.
---
# Encryption

View File

@ -1,9 +1,8 @@
---
layout: 'docs'
page_title: 'Consul KV'
sidebar_current: 'docs-agent-kv'
description: |-
Consul KV is a core feature of Consul and is installed with the Consul agent.
layout: docs
page_title: Consul KV
sidebar_current: docs-agent-kv
description: Consul KV is a core feature of Consul and is installed with the Consul agent.
---
# Consul KV

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -1,9 +1,12 @@
---
layout: 'docs'
page_title: 'RPC'
sidebar_current: 'docs-agent-rpc'
description: |-
The Consul agent provides a complete RPC mechanism that can be used to control the agent programmatically. This RPC mechanism is the same one used by the CLI but can be used by other applications to easily leverage the power of Consul without directly embedding.
layout: docs
page_title: RPC
sidebar_current: docs-agent-rpc
description: >-
The Consul agent provides a complete RPC mechanism that can be used to control
the agent programmatically. This RPC mechanism is the same one used by the CLI
but can be used by other applications to easily leverage the power of Consul
without directly embedding.
---
# RPC Protocol

View File

@ -1,20 +1,24 @@
---
layout: "docs"
page_title: "Sentinel in Consul"
sidebar_current: "docs-agent-sentinel"
description: |-
Consul Enterprise uses Sentinel to augment the built-in ACL system to provide advanced policy enforcement. Sentinel policies can currently execute on KV modify and service registration.
layout: docs
page_title: Sentinel in Consul
sidebar_current: docs-agent-sentinel
description: >-
Consul Enterprise uses Sentinel to augment the built-in ACL system to provide
advanced policy enforcement. Sentinel policies can currently execute on KV
modify and service registration.
---
# Sentinel Overview
[//]: # ( ~> The Sentinel functionality described here is available only in )
[//]: # ( [Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.0.0 and later. )
[//]: # ' ~> The Sentinel functionality described here is available only in '
[//]: # ( [Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.0.0 and later. )
<%= enterprise_alert :consul %>
Consul 1.0 adds integration with [Sentinel](https://hashicorp.com/sentinel) for policy enforcement.
Sentinel policies help extend the ACL system in Consul beyond the static "read", "write", and "deny"
policies to support full conditional logic and integration with external systems.
Consul 1.0 adds integration with [Sentinel](https://hashicorp.com/sentinel) for policy enforcement.
Sentinel policies help extend the ACL system in Consul beyond the static "read", "write", and "deny"
policies to support full conditional logic and integration with external systems.
## Sentinel in Consul
@ -47,18 +51,17 @@ Consul passes some context as variables into Sentinel, which are available to us
#### Variables injected during KV store writes
| Variable Name | Type | Description |
| ------------- | -------- | ----------- |
| `key` | `string` | Key being written |
| `value` | `string` | Value being written |
| Variable Name | Type | Description |
| ------------- | -------- | --------------------------- |
| `key` | `string` | Key being written |
| `value` | `string` | Value being written |
| `flags` | `uint64` | [Flags](/api/kv.html#flags) |
## Sentinel Examples
The following are two examples of ACL policies with Sentinel rules.
### Required Key Suffix
### Required Key Suffix
Any values stored under the key prefix "dc1" must end with "dev"

View File

@ -1,9 +1,14 @@
---
layout: 'docs'
page_title: 'Service Definition'
sidebar_current: 'docs-agent-services'
description: |-
One of the main goals of service discovery is to provide a catalog of available services. To that end, the agent provides a simple service definition format to declare the availability of a service and to potentially associate it with a health check. A health check is considered to be application level if it is associated with a service. A service is defined in a configuration file or added at runtime over the HTTP interface.
layout: docs
page_title: Service Definition
sidebar_current: docs-agent-services
description: >-
One of the main goals of service discovery is to provide a catalog of
available services. To that end, the agent provides a simple service
definition format to declare the availability of a service and to potentially
associate it with a health check. A health check is considered to be
application level if it is associated with a service. A service is defined in
a configuration file or added at runtime over the HTTP interface.
---
# Services

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,338 @@
---
layout: docs
page_title: Telemetry
sidebar_current: docs-agent-telemetry
description: >-
The Consul agent collects various runtime metrics about the performance of
different libraries and subsystems. These metrics are aggregated on a ten
second interval and are retained for one minute.
---
# Telemetry
The Consul agent collects various runtime metrics about the performance of
different libraries and subsystems. These metrics are aggregated on a ten
second interval and are retained for one minute.
To view this data, you must send a signal to the Consul process: on Unix,
this is `USR1` while on Windows it is `BREAK`. Once Consul receives the signal,
it will dump the current telemetry information to the agent's `stderr`.
This telemetry information can be used for debugging or otherwise
getting a better view of what Consul is doing. Review the [Monitoring and
Metrics guide](https://learn.hashicorp.com/consul/day-2-operations/monitoring?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data.
Additionally, if the [`telemetry` configuration options](/docs/agent/options.html#telemetry)
are provided, the telemetry information will be streamed to a
[statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where
it can be aggregated and flushed to Graphite or any other metrics store.
For a configuration example for Telegraf, review the [Monitoring with Telegraf guide](https://learn.hashicorp.com/consul/integrations/telegraf?utm_source=consul.io&utm_medium=docs).
This
information can also be viewed with the [metrics endpoint](/api/agent.html#view-metrics) in JSON
format or using [Prometheus](https://prometheus.io/) format.
Below is sample output of a telemetry dump:
```text
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.num_goroutines': 19.000
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.alloc_bytes': 755960.000
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.malloc_count': 7550.000
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.free_count': 4387.000
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.heap_objects': 3163.000
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.total_gc_pause_ns': 1151002.000
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.total_gc_runs': 4.000
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.agent.ipc.accept': Count: 5 Sum: 5.000
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.agent.ipc.command': Count: 10 Sum: 10.000
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.serf.events': Count: 5 Sum: 5.000
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.serf.events.foo': Count: 4 Sum: 4.000
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.serf.events.baz': Count: 1 Sum: 1.000
[2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.memberlist.gossip': Count: 50 Min: 0.007 Mean: 0.020 Max: 0.041 Stddev: 0.007 Sum: 0.989
[2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.serf.queue.Intent': Count: 10 Sum: 0.000
[2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.serf.queue.Event': Count: 10 Min: 0.000 Mean: 2.500 Max: 5.000 Stddev: 2.121 Sum: 25.000
```
# Key Metrics
These are some metrics emitted that can help you understand the health of your cluster at a glance. For a full list of metrics emitted by Consul, see [Metrics Reference](#metrics-reference)
### Transaction timing
| Metric Name | Description |
| :----------------------- | :----------------------------------------------------------------------------------- |
| `consul.kvs.apply` | This measures the time it takes to complete an update to the KV store. |
| `consul.txn.apply` | This measures the time spent applying a transaction operation. |
| `consul.raft.apply` | This counts the number of Raft transactions occurring over the interval. |
| `consul.raft.commitTime` | This measures the time it takes to commit a new entry to the Raft log on the leader. |
**Why they're important:** Taken together, these metrics indicate how long it takes to complete write operations in various parts of the Consul cluster. Generally these should all be fairly consistent and no more than a few milliseconds. Sudden changes in any of the timing values could be due to unexpected load on the Consul servers, or due to problems on the servers themselves.
**What to look for:** Deviations (in any of these metrics) of more than 50% from baseline over the previous hour.
### Leadership changes
| Metric Name | Description |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. |
| `consul.raft.state.candidate` | This increments whenever a Consul server starts an election. |
| `consul.raft.state.leader` | This increments whenever a Consul server becomes a leader. |
**Why they're important:** Normally, your Consul cluster should have a stable leader. If there are frequent elections or leadership changes, it would likely indicate network issues between the Consul servers, or that the Consul servers themselves are unable to keep up with the load.
**What to look for:** For a healthy cluster, you're looking for a `lastContact` lower than 200ms, `leader` > 0 and `candidate` == 0. Deviations from this might indicate flapping leadership.
### Autopilot
| Metric Name | Description |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. |
**Why it's important:** Obviously, you want your cluster to be healthy.
**What to look for:** Alert if `healthy` is 0.
### Memory usage
| Metric Name | Description |
| :--------------------------- | :----------------------------------------------------------------- |
| `consul.runtime.alloc_bytes` | This measures the number of bytes allocated by the Consul process. |
| `consul.runtime.sys_bytes` | This is the total number of bytes of memory obtained from the OS. |
**Why they're important:** Consul keeps all of its data in memory. If Consul consumes all available memory, it will crash.
**What to look for:** If `consul.runtime.sys_bytes` exceeds 90% of total available system memory.
### Garbage collection
| Metric Name | Description |
| :--------------------------------- | :---------------------------------------------------------------------------------------------------- |
| `consul.runtime.total_gc_pause_ns` | Number of nanoseconds consumed by stop-the-world garbage collection (GC) pauses since Consul started. |
**Why it's important:** GC pause is a "stop-the-world" event, meaning that all runtime threads are blocked until GC completes. Normally these pauses last only a few nanoseconds. But if memory usage is high, the Go runtime may GC so frequently that it starts to slow down Consul.
**What to look for:** Warning if `total_gc_pause_ns` exceeds 2 seconds/minute, critical if it exceeds 5 seconds/minute.
**NOTE:** `total_gc_pause_ns` is a cumulative counter, so in order to calculate rates (such as GC/minute),
you will need to apply a function such as InfluxDB's [`non_negative_difference()`](https://docs.influxdata.com/influxdb/v1.5/query_language/functions/#non-negative-difference).
### Network activity - RPC Count
| Metric Name | Description |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server |
| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options.html#limits) configuration. |
| `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. |
**Why they're important:** These measurements indicate the current load created from a Consul agent, including when the load becomes high enough to be rate limited. A high RPC count, especially from `consul.client.rpcexceeded` meaning that the requests are being rate-limited, could imply a misconfigured Consul agent.
**What to look for:**
Sudden large changes to the `consul.client.rpc` metrics (greater than 50% deviation from baseline).
`consul.client.rpc.exceeded` or `consul.client.rpc.failed` count > 0, as it implies that an agent is being rate-limited or fails to make an RPC request to a Consul server
When telemetry is being streamed to an external metrics store, the interval is defined to
be that store's flush interval. Otherwise, the interval can be assumed to be 10 seconds
when retrieving metrics from the built-in store using the above described signals.
## Metrics Reference
This is a full list of metrics emitted by Consul.
| Metric | Description | Unit | Type |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | ------- |
| `consul.acl.blocked.service.registration` | This increments whenever a deregistration fails for a service (blocked by an ACL) | requests | counter |
| `consul.acl.blocked..registration` | This increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL | requests | counter |
| `consul.client.rpc` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter |
| `consul.client.rpc.exceeded` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options.html#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter |
| `consul.client.rpc.failed` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter |
| `consul.client.api.catalog_register.` | This increments whenever a Consul agent receives a catalog register request. | requests | counter |
| `consul.client.api.success.catalog_register.` | This increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter |
| `consul.client.rpc.error.catalog_register.` | This increments whenever a Consul agent receives an RPC error for a catalog register request. | errors | counter |
| `consul.client.api.catalog_deregister.` | This increments whenever a Consul agent receives a catalog de-register request. | requests | counter |
| `consul.client.api.success.catalog_deregister.` | This increments whenever a Consul agent successfully responds to a catalog de-register request. | requests | counter |
| `consul.client.rpc.error.catalog_deregister.` | This increments whenever a Consul agent receives an RPC error for a catalog de-register request. | errors | counter |
| `consul.client.api.catalog_datacenters.` | This increments whenever a Consul agent receives a request to list datacenters in the catalog. | requests | counter |
| `consul.client.api.success.catalog_datacenters.` | This increments whenever a Consul agent successfully responds to a request to list datacenters. | requests | counter |
| `consul.client.rpc.error.catalog_datacenters.` | This increments whenever a Consul agent receives an RPC error for a request to list datacenters. | errors | counter |
| `consul.client.api.catalog_nodes.` | This increments whenever a Consul agent receives a request to list nodes from the catalog. | requests | counter |
| `consul.client.api.success.catalog_nodes.` | This increments whenever a Consul agent successfully responds to a request to list nodes. | requests | counter |
| `consul.client.rpc.error.catalog_nodes.` | This increments whenever a Consul agent receives an RPC error for a request to list nodes. | errors | counter |
| `consul.client.api.catalog_services.` | This increments whenever a Consul agent receives a request to list services from the catalog. | requests | counter |
| `consul.client.api.success.catalog_services.` | This increments whenever a Consul agent successfully responds to a request to list services. | requests | counter |
| `consul.client.rpc.error.catalog_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services. | errors | counter |
| `consul.client.api.catalog_service_nodes.` | This increments whenever a Consul agent receives a request to list nodes offering a service. | requests | counter |
| `consul.client.api.success.catalog_service_nodes.` | This increments whenever a Consul agent successfully responds to a request to list nodes offering a service. | requests | counter |
| `consul.client.rpc.error.catalog_service_nodes.` | This increments whenever a Consul agent receives an RPC error for a request to list nodes offering a service. | errors | counter |
| `consul.client.api.catalog_node_services.` | This increments whenever a Consul agent receives a request to list services registered in a node. | requests | counter |
| `consul.client.api.success.catalog_node_services.` | This increments whenever a Consul agent successfully responds to a request to list services in a service. | requests | counter |
| `consul.client.rpc.error.catalog_node_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services in a service. | errors | counter |
| `consul.runtime.num_goroutines` | This tracks the number of running goroutines and is a general load pressure indicator. This may burst from time to time but should return to a steady state value. | number of goroutines | gauge |
| `consul.runtime.alloc_bytes` | This measures the number of bytes allocated by the Consul process. This may burst from time to time but should return to a steady state value. | bytes | gauge |
| `consul.runtime.heap_objects` | This measures the number of objects allocated on the heap and is a general memory pressure indicator. This may burst from time to time but should return to a steady state value. | number of objects | gauge |
| `consul.acl.cache_hit` | The number of ACL cache hits. | hits | counter |
| `consul.acl.cache_miss` | The number of ACL cache misses. | misses | counter |
| `consul.acl.replication_hit` | The number of ACL replication cache hits (when not running in the ACL datacenter). | hits | counter |
| `consul.dns.stale_queries` | This increments when an agent serves a query within the allowed stale threshold. | queries | counter |
| `consul.dns.ptr_query.` | This measures the time spent handling a reverse DNS query for the given node. | ms | timer |
| `consul.dns.domain_query.` | This measures the time spent handling a domain query for the given node. | ms | timer |
| `consul.http..` | This tracks how long it takes to service the given HTTP request for the given verb and path. Paths do not include details like service or key names, for these an underscore will be present as a placeholder (eg. `consul.http.GET.v1.kv._`) | ms | timer |
## Server Health
These metrics are used to monitor the health of the Consul servers.
| Metric | Description | Unit | Type |
| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `consul.raft.fsm.snapshot` | This metric measures the time taken by the FSM to record the current state for the snapshot. | ms | timer |
| `consul.raft.fsm.apply` | This metric gives the number of logs committed since the last interval. | commit logs / interval | counter |
| `consul.raft.commitNumLogs` | This metric measures the count of logs processed for application to the FSM in a single batch. | logs | gauge |
| `consul.raft.fsm.enqueue` | This metric measures the amount of time to enqueue a batch of logs for the FSM to apply. | ms | timer |
| `consul.raft.fsm.restore` | This metric measures the time taken by the FSM to restore its state from a snapshot. | ms | timer |
| `consul.raft.snapshot.create` | This metric measures the time taken to initialize the snapshot process. | ms | timer |
| `consul.raft.snapshot.persist` | This metric measures the time taken to dump the current snapshot taken by the Consul agent to the disk. | ms | timer |
| `consul.raft.snapshot.takeSnapshot` | This metric measures the total time involved in taking the current snapshot (creating one and persisting it) by the Consul agent. | ms | timer |
| `consul.raft.replication.heartbeat` | This metric measures the time taken to invoke appendEntries on a peer, so that it doesnt timeout on a periodic basis. | ms | timer |
| `consul.serf.snapshot.appendLine` | This metric measures the time taken by the Consul agent to append an entry into the existing log. | ms | timer |
| `consul.serf.snapshot.compact` | This metric measures the time taken by the Consul agent to compact a log. This operation occurs only when the snapshot becomes large enough to justify the compaction . | ms | timer |
| `consul.raft.state.leader` | This increments whenever a Consul server becomes a leader. If there are frequent leadership changes this may be indication that the servers are overloaded and aren't meeting the soft real-time requirements for Raft, or that there are networking problems between the servers. | leadership transitions / interval | counter |
| `consul.raft.state.candidate` | This increments whenever a Consul server starts an election. If this increments without a leadership change occurring it could indicate that a single server is overloaded or is experiencing network connectivity issues. | election attempts / interval | counter |
| `consul.raft.apply` | This counts the number of Raft transactions occurring over the interval, which is a general indicator of the write load on the Consul servers. | raft transactions / interval | counter |
| `consul.raft.barrier` | This metric counts the number of times the agent has started the barrier i.e the number of times it has |
| issued a blocking call, to ensure that the agent has all the pending operations that were queued, to be applied to the agent's FSM. | blocks / interval | counter |
| `consul.raft.verify_leader` | This metric counts the number of times an agent checks whether it is still the leader or not | checks / interval | Counter |
| `consul.raft.restore` | This metric counts the number of times the restore operation has been performed by the agent. Here, restore refers to the action of raft consuming an external snapshot to restore its state. | operation invoked / interval | counter |
| `consul.raft.commitTime` | This measures the time it takes to commit a new entry to the Raft log on the leader. | ms | timer |
| `consul.raft.leader.dispatchLog` | This measures the time it takes for the leader to write log entries to disk. | ms | timer |
| `consul.raft.leader.dispatchNumLogs` | This metric measures the number of logs committed to disk in a batch. | logs | gauge |
| `consul.raft.replication.appendEntries` | This measures the time it takes to replicate log entries to followers. This is a general indicator of the load pressure on the Consul servers, as well as the performance of the communication between the servers. | ms | timer |
| `consul.raft.state.follower` | This metric counts the number of times an agent has entered the follower mode. This happens when a new agent joins the cluster or after the end of a leader election. | follower state entered / interval | counter |
| `consul.raft.transistion.heartbeat_timeout` | This metric gives the number of times an agent has transitioned to the Candidate state, after receive no heartbeat messages from the last known leader. | timeouts / interval | counter |
| `consul.raft.restoreUserSnapshot` | This metric measures the time taken by the agent to restore the FSM state from a user's snapshot | ms | timer |
| `consul.raft.rpc.processHeartBeat` | This metric measures the time taken to process a heartbeat request. | ms | timer |
| `consul.raft.rpc.appendEntries` | This metric measures the time taken to process an append entries RPC call from an agent. | ms | timer |
| `consul.raft.rpc.appendEntries.storeLogs` | This metric measures the time taken to add any outstanding logs for an agent, since the last appendEntries was invoked | ms | timer |
| `consul.raft.rpc.appendEntries.processLogs` | This metric measures the time taken to process the outstanding log entries of an agent. | ms | timer |
| `consul.raft.rpc.requestVote` | This metric measures the time taken to process the request vote RPC call. | ms | timer |
| `consul.raft.rpc.installSnapshot` | This metric measures the time taken to process the installSnapshot RPC call. This metric should only be seen on agents which are currently in the follower state. | ms | timer |
| `consul.raft.replication.appendEntries.rpc` | This metric measures the time taken by the append entries RFC, to replicate the log entries of a leader agent onto its follower agent(s) | ms | timer |
| `consul.raft.replication.appendEntries.logs` | This metric measures the number of logs replicated to an agent, to bring it up to speed with the leader's logs. | logs appended/ interval | counter |
| `consul.raft.leader.lastContact` | This will only be emitted by the Raft leader and measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/options.html#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance.html) guide for more details. | ms | timer |
| `consul.acl.apply` | This measures the time it takes to complete an update to the ACL store. | ms | timer |
| `consul.acl.fault` | This measures the time it takes to fault in the rules for an ACL during a cache miss. | ms | timer |
| `consul.acl.fetchRemoteACLs` | This measures the time it takes to fetch remote ACLs during replication. | ms | timer |
| `consul.acl.updateLocalACLs` | This measures the time it takes to apply replication changes to the local ACL store. | ms | timer |
| `consul.acl.replicateACLs` | This measures the time it takes to do one pass of the ACL replication algorithm. | ms | timer |
| `consul.acl.resolveToken` | This measures the time it takes to resolve an ACL token. | ms | timer |
| `consul.rpc.accept_conn` | This increments when a server accepts an RPC connection. | connections | counter |
| `consul.catalog.register` | This measures the time it takes to complete a catalog register operation. | ms | timer |
| `consul.catalog.deregister` | This measures the time it takes to complete a catalog deregister operation. | ms | timer |
| `consul.fsm.register` | This measures the time it takes to apply a catalog register operation to the FSM. | ms | timer |
| `consul.fsm.deregister` | This measures the time it takes to apply a catalog deregister operation to the FSM. | ms | timer |
| `consul.fsm.acl.` | This measures the time it takes to apply the given ACL operation to the FSM. | ms | timer |
| `consul.fsm.session.` | This measures the time it takes to apply the given session operation to the FSM. | ms | timer |
| `consul.fsm.kvs.` | This measures the time it takes to apply the given KV operation to the FSM. | ms | timer |
| `consul.fsm.tombstone.` | This measures the time it takes to apply the given tombstone operation to the FSM. | ms | timer |
| `consul.fsm.coordinate.batch-update` | This measures the time it takes to apply the given batch coordinate update to the FSM. | ms | timer |
| `consul.fsm.prepared-query.` | This measures the time it takes to apply the given prepared query update operation to the FSM. | ms | timer |
| `consul.fsm.txn` | This measures the time it takes to apply the given transaction update to the FSM. | ms | timer |
| `consul.fsm.autopilot` | This measures the time it takes to apply the given autopilot update to the FSM. | ms | timer |
| `consul.fsm.persist` | This measures the time it takes to persist the FSM to a raft snapshot. | ms | timer |
| `consul.kvs.apply` | This measures the time it takes to complete an update to the KV store. | ms | timer |
| `consul.leader.barrier` | This measures the time spent waiting for the raft barrier upon gaining leadership. | ms | timer |
| `consul.leader.reconcile` | This measures the time spent updating the raft store from the serf member information. | ms | timer |
| `consul.leader.reconcileMember` | This measures the time spent updating the raft store for a single serf member's information. | ms | timer |
| `consul.leader.reapTombstones` | This measures the time spent clearing tombstones. | ms | timer |
| `consul.prepared-query.apply` | This measures the time it takes to apply a prepared query update. | ms | timer |
| `consul.prepared-query.explain` | This measures the time it takes to process a prepared query explain request. | ms | timer |
| `consul.prepared-query.execute` | This measures the time it takes to process a prepared query execute request. | ms | timer |
| `consul.prepared-query.execute_remote` | This measures the time it takes to process a prepared query execute request that was forwarded to another datacenter. | ms | timer |
| `consul.rpc.raft_handoff` | This increments when a server accepts a Raft-related RPC connection. | connections | counter |
| `consul.rpc.request_error` | This increments when a server returns an error from an RPC request. | errors | counter |
| `consul.rpc.request` | This increments when a server receives a Consul-related RPC request. | requests | counter |
| `consul.rpc.query` | This increments when a server receives a new blocking RPC request, indicating the rate of new blocking query calls. See consul.rpc.queries_blocking for the current number of in-flight blocking RPC calls. This metric changed in 1.7.0 to only increment on the the start of a query. The rate of queries will appear lower, but is more accurate. | queries | counter |
| `consul.rpc.queries_blocking` | This shows the current number of in-flight blocking queries the server is handling. | queries | gauge |
| `consul.rpc.cross-dc` | This increments when a server sends a (potentially blocking) cross datacenter RPC query. | queries | counter |
| `consul.rpc.consistentRead` | This measures the time spent confirming that a consistent read can be performed. | ms | timer |
| `consul.session.apply` | This measures the time spent applying a session update. | ms | timer |
| `consul.session.renew` | This measures the time spent renewing a session. | ms | timer |
| `consul.session_ttl.invalidate` | This measures the time spent invalidating an expired session. | ms | timer |
| `consul.txn.apply` | This measures the time spent applying a transaction operation. | ms | timer |
| `consul.txn.read` | This measures the time spent returning a read transaction. | ms | timer |
## Cluster Health
These metrics give insight into the health of the cluster as a whole.
| Metric | Description | Unit | Type |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- |
| `consul.memberlist.degraded.probe` | This metric counts the number of times the agent has performed failure detection on another agent at a slower probe rate. The agent uses its own health metric as an indicator to perform this action. (If its health score is low, means that the node is healthy, and vice versa.) | probes / interval | counter |
| `consul.memberlist.degraded.timeout` | This metric counts the number of times an agent was marked as a dead node, whilst not getting enough confirmations from a randomly selected list of agent nodes in an agent's membership. | occurrence / interval | counter |
| `consul.memberlist.msg.dead` | This metric counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter |
| `consul.memberlist.health.score` | This metric describes a node's perception of its own health based on how well it is meeting the soft real-time requirements of the protocol. This metric ranges from 0 to 8, where 0 indicates "totally healthy". This health score is used to scale the time between outgoing probes, and higher scores translate into longer probing intervals. For more details see section IV of the Lifeguard paper: https://arxiv.org/pdf/1707.00788.pdf | score | gauge |
| `consul.memberlist.msg.suspect` | This increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/options.html#ports). | suspect messages received / interval | counter |
| `consul.memberlist.tcp.accept` | This metric counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter |
| `consul.memberlist.udp.sent/received` | This metric measures the total number of bytes sent/received by an agent through the UDP protocol. | bytes sent or bytes received / interval | counter |
| `consul.memberlist.tcp.connect` | This metric counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter |
| `consul.memberlist.tcp.sent` | This metric measures the total number of bytes sent by an agent through the TCP protocol | bytes sent / interval | counter |
| `consul.memberlist.gossip` | This metric gives the number of gossips (messages) broadcasted to a set of randomly selected nodes. | messages / Interval | counter |
| `consul.memberlist.msg_alive` | This metric counts the number of alive agents, that the agent has mapped out so far, based on the message information given by the network layer. | nodes / Interval | counter |
| `consul.memberlist.msg_dead` | This metric gives the number of dead agents, that the agent has mapped out so far, based on the message information given by the network layer. | nodes / Interval | counter |
| `consul.memberlist.msg_suspect` | This metric gives the number of suspect nodes, that the agent has mapped out so far, based on the message information given by the network layer. | nodes / Interval | counter |
| `consul.memberlist.probeNode` | This metric measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter |
| `consul.memberlist.pushPullNode` | This metric measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter |
| `consul.serf.member.failed` | This increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options.html#ports). | failures / interval | counter |
| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options.html#ports). | flaps / interval | counter |
| `consul.serf.member.join` | This increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter |
| `consul.serf.member.left` | This increments when an agent leaves the cluster. | leaves / interval | counter |
| `consul.serf.events` | This increments when an agent processes an [event](/docs/commands/event.html). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter |
| `consul.autopilot.failure_tolerance` | This tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge |
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. | boolean | gauge |
| `consul.session_ttl.active` | This tracks the active number of sessions being tracked. | sessions | gauge |
| `consul.catalog.service.query.` | This increments for each catalog query for the given service. | queries | counter |
| `consul.catalog.service.query-tag..` | This increments for each catalog query for the given service with the given tag. | queries | counter |
| `consul.catalog.service.query-tags..` | This increments for each catalog query for the given service with the given tags. | queries | counter |
| `consul.catalog.service.not-found.` | This increments for each catalog query where the given service could not be found. | queries | counter |
| `consul.health.service.query.` | This increments for each health query for the given service. | queries | counter |
| `consul.health.service.query-tag..` | This increments for each health query for the given service with the given tag. | queries | counter |
| `consul.health.service.query-tags..` | This increments for each health query for the given service with the given tags. | queries | counter |
| `consul.health.service.not-found.` | This increments for each health query where the given service could not be found. | queries | counter |
## Connect Built-in Proxy Metrics
Consul Connect's built-in proxy is by default configured to log metrics to the
same sink as the agent that starts it.
When running in this mode it emits some basic metrics. These will be expanded
upon in the future.
All metrics are prefixed with `consul.proxy.<proxied-service-id>` to distinguish
between multiple proxies on a given host. The table below use `web` as an
example service name for brevity.
### Labels
Most labels have a `dst` label and some have a `src` label. When using metrics
sinks and timeseries stores that support labels or tags, these allow aggregating
the connections by service name.
Assuming all services are using a managed built-in proxy, you can get a complete
overview of both number of open connections and bytes sent and received between
all services by aggregating over these metrics.
For example aggregating over all `upstream` (i.e. outbound) connections which
have both `src` and `dst` labels, you can get a sum of all the bandwidth in and
out of a given service or the total number of connections between two services.
### Metrics Reference
The standard go runtime metrics are exported by `go-metrics` as with Consul
agent. The table below describes the additional metrics exported by the proxy.
| Metric | Description | Unit | Type |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- |
| `consul.proxy.web.runtime.*` | The same go runtime metrics as documented for the agent above. | mixed | mixed |
| `consul.proxy.web.inbound.conns` | Shows the current number of connections open from inbound requests to the proxy. Where supported a `dst` label is added indicating the service name the proxy represents. | connections | gauge |
| `consul.proxy.web.inbound.rx_bytes` | This increments by the number of bytes received from an inbound client connection. Where supported a `dst` label is added indicating the service name the proxy represents. | bytes | counter |
| `consul.proxy.web.inbound.tx_bytes` | This increments by the number of bytes transferred to an inbound client connection. Where supported a `dst` label is added indicating the service name the proxy represents. | bytes | counter |
| `consul.proxy.web.upstream.conns` | Shows the current number of connections open from a proxy instance to an upstream. Where supported a `src` label is added indicating the service name the proxy represents, and a `dst` label is added indicating the service name the upstream is connecting to. | connections | gauge |
| `consul.proxy.web.inbound.rx_bytes` | This increments by the number of bytes received from an upstream connection. Where supported a `src` label is added indicating the service name the proxy represents, and a `dst` label is added indicating the service name the upstream is connecting to. | bytes | counter |
| `consul.proxy.web.inbound.tx_bytes` | This increments by the number of bytes transferred to an upstream connection. Where supported a `src` label is added indicating the service name the proxy represents, and a `dst` label is added indicating the service name the upstream is connecting to. | bytes | counter |

View File

@ -1,9 +1,13 @@
---
layout: 'docs'
page_title: 'Watches'
sidebar_current: 'docs-agent-watches'
description: |-
Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs, health checks) which is monitored for updates. When an update is detected, an external handler is invoked. A handler can be any executable. As an example, you could watch the status of health checks and notify an external system when a check is critical.
layout: docs
page_title: Watches
sidebar_current: docs-agent-watches
description: >-
Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs,
health checks) which is monitored for updates. When an update is detected, an
external handler is invoked. A handler can be any executable. As an example,
you could watch the status of health checks and notify an external system when
a check is critical.
---
# Watches

View File

@ -1,7 +1,7 @@
---
layout: 'docs'
layout: docs
page_title: 'Commands: ACL'
sidebar_current: 'docs-commands-acl'
sidebar_current: docs-commands-acl
---
# Consul ACLs

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Methods"
sidebar_current: "docs-commands-acl-auth-method"
layout: docs
page_title: 'Commands: ACL Auth Methods'
sidebar_current: docs-commands-acl-auth-method
---
# Consul ACL Auth Methods
@ -15,7 +15,7 @@ This command is available in Consul 1.5.0 and newer.
ACL auth methods may also be managed via the [HTTP API](/api/acl/auth-methods.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
@ -23,8 +23,7 @@ secret ID as the value of the `-token` parameter.
Usage: `consul acl auth-method <subcommand>`
For the exact documentation for your Consul version, run `consul acl
auth-method -h` to view the complete list of subcommands.
For the exact documentation for your Consul version, run `consul acl auth-method -h` to view the complete list of subcommands.
```text
Usage: consul acl auth-method <subcommand> [options] [args]

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Create"
sidebar_current: "docs-commands-acl-auth-method-create"
layout: docs
page_title: 'Commands: ACL Auth Method Create'
sidebar_current: docs-commands-acl-auth-method-create
---
# Consul ACL Auth Method Create
@ -16,37 +16,37 @@ Usage: `consul acl auth-method create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-description=<string>` - A description of the auth method.
- `-description=<string>` - A description of the auth method.
* `-meta` - Indicates that auth method metadata such as the raft indices should
- `-meta` - Indicates that auth method metadata such as the raft indices should
be shown for each entry.
* `-name=<string>` - The new auth method's name. This flag is required.
- `-name=<string>` - The new auth method's name. This flag is required.
* `-type=<string>` - The new auth method's type. This flag is required.
- `-type=<string>` - The new auth method's type. This flag is required.
* `-kubernetes-ca-cert=<string>` - PEM encoded CA cert for use by the TLS
- `-kubernetes-ca-cert=<string>` - PEM encoded CA cert for use by the TLS
client used to talk with the Kubernetes API. May be prefixed with '@' to
indicate that the value is a file path to load the cert from. This flag is
required for `-type=kubernetes`.
* `-kubernetes-host=<string>` - Address of the Kubernetes API server. This flag
- `-kubernetes-host=<string>` - Address of the Kubernetes API server. This flag
is required for `-type=kubernetes`.
* `-kubernetes-service-account-jwt=<string>` - A Kubernetes service account JWT
- `-kubernetes-service-account-jwt=<string>` - A Kubernetes service account JWT
used to access the TokenReview API to validate other JWTs during login. This
flag is required for `-type=kubernetes`.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Delete"
sidebar_current: "docs-commands-acl-auth-method-delete"
layout: docs
page_title: 'Commands: ACL Auth Method Delete'
sidebar_current: docs-commands-acl-auth-method-delete
---
# Consul ACL Auth Method Delete
@ -16,16 +16,16 @@ Usage: `consul acl auth-method delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-name=<string>` - The Name of the auth method to delete.
- `-name=<string>` - The Name of the auth method to delete.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method List"
sidebar_current: "docs-commands-acl-auth-method-list"
layout: docs
page_title: 'Commands: ACL Auth Method List'
sidebar_current: docs-commands-acl-auth-method-list
---
# Consul ACL Auth Method List
@ -16,19 +16,19 @@ Usage: `consul acl auth-method list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-meta` - Indicates that auth method metadata such as the raft indices should
- `-meta` - Indicates that auth method metadata such as the raft indices should
be shown for each entry.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Read"
sidebar_current: "docs-commands-acl-auth-method-read"
layout: docs
page_title: 'Commands: ACL Auth Method Read'
sidebar_current: docs-commands-acl-auth-method-read
---
# Consul ACL Auth Method Read
@ -16,21 +16,21 @@ Usage: `consul acl auth-method read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-meta` - Indicates that auth method metadata such as the raft
- `-meta` - Indicates that auth method metadata such as the raft
indices should be shown for each entry.
* `-name=<string>` - The name of the auth method to read.
- `-name=<string>` - The name of the auth method to read.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Update"
sidebar_current: "docs-commands-acl-auth-method-update"
layout: docs
page_title: 'Commands: ACL Auth Method Update'
sidebar_current: docs-commands-acl-auth-method-update
---
# Consul ACL Auth Method Update
@ -19,39 +19,39 @@ Usage: `consul acl auth-method update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-description=<string>` - A description of the auth method.
- `-description=<string>` - A description of the auth method.
* `-kubernetes-ca-cert=<string>` - PEM encoded CA cert for use by the TLS
- `-kubernetes-ca-cert=<string>` - PEM encoded CA cert for use by the TLS
client used to talk with the Kubernetes API. May be prefixed with '@' to
indicate that the value is a file path to load the cert from. This flag is
required for `-type=kubernetes`.
* `-kubernetes-host=<string>` - Address of the Kubernetes API server. This flag
- `-kubernetes-host=<string>` - Address of the Kubernetes API server. This flag
is required for `-type=kubernetes`.
* `-kubernetes-service-account-jwt=<string>` - A Kubernetes service account JWT
- `-kubernetes-service-account-jwt=<string>` - A Kubernetes service account JWT
used to access the TokenReview API to validate other JWTs during login. This
flag is required for `-type=kubernetes`.
* `-meta` - Indicates that auth method metadata such as the raft
- `-meta` - Indicates that auth method metadata such as the raft
indices should be shown for each entry
* `-name=<string>` - The name of the auth method to update.
- `-name=<string>` - The name of the auth method to update.
* `-no-merge` - Do not merge the current auth method information with what is provided
- `-no-merge` - Do not merge the current auth method information with what is provided
to the command. Instead overwrite all fields with the exception of the auth method
ID which is immutable.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule"
sidebar_current: "docs-commands-acl-binding-rule"
layout: docs
page_title: 'Commands: ACL Binding Rule'
sidebar_current: docs-commands-acl-binding-rule
---
# Consul ACL Binding Rules
@ -15,7 +15,7 @@ This command is available in Consul 1.5.0 and newer.
ACL binding rules may also be managed via the [HTTP API](/api/acl/binding-rules.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
@ -23,8 +23,7 @@ secret ID as the value of the `-token` parameter.
Usage: `consul acl binding-rule <subcommand>`
For the exact documentation for your Consul version, run `consul acl
binding-rule -h` to view the complete list of subcommands.
For the exact documentation for your Consul version, run `consul acl binding-rule -h` to view the complete list of subcommands.
```text
Usage: consul acl binding-rule <subcommand> [options] [args]
@ -88,4 +87,3 @@ Delete a binding rule:
```sh
$ consul acl binding-rule delete -id b6b856da-5193-4e78-845a-7d61ca8371ba
```

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Create"
sidebar_current: "docs-commands-acl-binding-rule-create"
layout: docs
page_title: 'Commands: ACL Binding Rule Create'
sidebar_current: docs-commands-acl-binding-rule-create
---
# Consul ACL Binding Rule Create
@ -16,32 +16,32 @@ Usage: `consul acl binding-rule create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-bind-name=<string>` - Name to bind on match. Can use `${var}`
- `-bind-name=<string>` - Name to bind on match. Can use `${var}`
interpolation. This flag is required.
* `-bind-type=<string>` - Type of binding to perform (`"service"` or `"role"`).
- `-bind-type=<string>` - Type of binding to perform (`"service"` or `"role"`).
* `-description=<string>` - A description of the binding rule.
- `-description=<string>` - A description of the binding rule.
* `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
- `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
* `-method=<string>` - The auth method's name for which this binding rule
- `-method=<string>` - The auth method's name for which this binding rule
applies. This flag is required.
* `-selector=<string>` - Selector is an expression that matches against
- `-selector=<string>` - Selector is an expression that matches against
verified identity attributes returned from the auth method during login.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Delete"
sidebar_current: "docs-commands-acl-binding-rule-delete"
layout: docs
page_title: 'Commands: ACL Binding Rule Delete'
sidebar_current: docs-commands-acl-binding-rule-delete
---
# Consul ACL Binding Rule Delete
@ -16,17 +16,17 @@ Usage: `consul acl binding-rule delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-id=<string>` - The ID of the binding rule to delete. It may be specified as a
- `-id=<string>` - The ID of the binding rule to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple binding rule IDs.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule List"
sidebar_current: "docs-commands-acl-binding-rule-list"
layout: docs
page_title: 'Commands: ACL Binding Rule List'
sidebar_current: docs-commands-acl-binding-rule-list
---
# Consul ACL Binding Rule List
@ -16,19 +16,19 @@ Usage: `consul acl binding-rule list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-meta` - Indicates that binding rule metadata such as the raft indices
- `-meta` - Indicates that binding rule metadata such as the raft indices
should be shown for each entry.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Read"
sidebar_current: "docs-commands-acl-binding-rule-read"
layout: docs
page_title: 'Commands: ACL Binding Rule Read'
sidebar_current: docs-commands-acl-binding-rule-read
---
# Consul ACL Binding Rule Read
@ -16,22 +16,22 @@ Usage: `consul acl binding-rule read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-id=<string>` - The ID of the binding rule to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple binding rule IDs.
- `-id=<string>` - The ID of the binding rule to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple binding rule IDs.
* `-meta` - Indicates that binding rule metadata such as the raft
- `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Update"
sidebar_current: "docs-commands-acl-binding-rule-update"
layout: docs
page_title: 'Commands: ACL Binding Rule Update'
sidebar_current: docs-commands-acl-binding-rule-update
---
# Consul ACL Binding Rule Update
@ -19,36 +19,36 @@ Usage: `consul acl binding-rule update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-bind-name=<string>` - Name to bind on match. Can use `${var}`
- `-bind-name=<string>` - Name to bind on match. Can use `${var}`
interpolation. This flag is required.
* `-bind-type=<string>` - Type of binding to perform (`"service"` or `"role"`).
- `-bind-type=<string>` - Type of binding to perform (`"service"` or `"role"`).
* `-description=<string>` - A description of the binding rule.
- `-description=<string>` - A description of the binding rule.
* `-id=<string>` - The ID of the binding rule to update. It may be specified as a
- `-id=<string>` - The ID of the binding rule to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple binding rule IDs
* `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
- `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
* `-no-merge` - Do not merge the current binding rule information with what is
- `-no-merge` - Do not merge the current binding rule information with what is
provided to the command. Instead overwrite all fields with the exception of the
binding rule ID which is immutable.
* `-selector=<string>` - Selector is an expression that matches against
- `-selector=<string>` - Selector is an expression that matches against
verified identity attributes returned from the auth method during login.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Bootstrap"
sidebar_current: "docs-commands-acl-bootstrap"
layout: docs
page_title: 'Commands: ACL Bootstrap'
sidebar_current: docs-commands-acl-bootstrap
---
# Consul ACL Bootstrap
@ -21,11 +21,12 @@ Usage: `consul acl bootstrap [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
The output looks like this:

View File

@ -1,21 +1,21 @@
---
layout: "docs"
page_title: "Commands: ACL Policy"
sidebar_current: "docs-commands-acl-policy"
layout: docs
page_title: 'Commands: ACL Policy'
sidebar_current: docs-commands-acl-policy
---
# Consul ACL Policies
Command: `consul acl policy`
The `acl policy` command is used to manage Consul's ACL policies.
The `acl policy` command is used to manage Consul's ACL policies.
It exposes commands for creating, updating, reading, deleting, and listing policies.
This command is available in Consul 1.4.0 and newer.
ACL policies may also be managed via the [HTTP API](/api/acl/policies.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
@ -23,8 +23,7 @@ secret ID as the value of the `-token` parameter.
Usage: `consul acl policy <subcommand>`
For the exact documentation for your Consul version, run `consul acl
policy -h` to view the complete list of subcommands.
For the exact documentation for your Consul version, run `consul acl policy -h` to view the complete list of subcommands.
```text
Usage: consul acl policy <subcommand> [options] [args]

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Create"
sidebar_current: "docs-commands-acl-policy-create"
layout: docs
page_title: 'Commands: ACL Policy Create'
sidebar_current: docs-commands-acl-policy-create
---
# Consul ACL Policy Create
@ -28,38 +28,38 @@ Usage: `consul acl policy create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-description=<string>` - A description of the policy.
- `-description=<string>` - A description of the policy.
* `-from-token=<string>` - The legacy token to retrieve the rules for when creating this
policy. When this is specified no other rules should be given.
Similar to the -rules option the token to use can be loaded from
stdin or from a file.
- `-from-token=<string>` - The legacy token to retrieve the rules for when creating this
policy. When this is specified no other rules should be given.
Similar to the -rules option the token to use can be loaded from
stdin or from a file.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
- `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The new policy's name. This flag is required.
- `-name=<string>` - The new policy's name. This flag is required.
* `-rules=<string>` - The policy rules. May be prefixed with '@' to indicate that the
value is a file path to load the rules from. '-' may also be given
to indicate that the rules are available on stdin.
- `-rules=<string>` - The policy rules. May be prefixed with '@' to indicate that the
value is a file path to load the rules from. '-' may also be given
to indicate that the rules are available on stdin.
* `-token-secret` - Indicates the token provided with -from-token is a SecretID and not
an AccessorID.
- `-token-secret` - Indicates the token provided with -from-token is a SecretID and not
an AccessorID.
* `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
- `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Delete"
sidebar_current: "docs-commands-acl-policy-delete"
layout: docs
page_title: 'Commands: ACL Policy Delete'
sidebar_current: docs-commands-acl-policy-delete
---
# Consul ACL Policy Delete
@ -16,19 +16,19 @@ Usage: `consul acl policy delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-id=<string>` - The ID of the policy to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs.
- `-id=<string>` - The ID of the policy to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs.
* `-name=<string>` - The Name of the policy to delete.
- `-name=<string>` - The Name of the policy to delete.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Policy List"
sidebar_current: "docs-commands-acl-policy-list"
layout: docs
page_title: 'Commands: ACL Policy List'
sidebar_current: docs-commands-acl-policy-list
---
# Consul ACL Policy List
@ -16,19 +16,19 @@ Usage: `consul acl policy list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-meta` - Indicates that policy metadata such as the content hash and
Raft indices should be shown for each entry.
- `-meta` - Indicates that policy metadata such as the content hash and
Raft indices should be shown for each entry.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Read"
sidebar_current: "docs-commands-acl-policy-read"
layout: docs
page_title: 'Commands: ACL Policy Read'
sidebar_current: docs-commands-acl-policy-read
---
# Consul ACL Policy Read
@ -16,24 +16,24 @@ Usage: `consul acl policy read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple policy IDs.
- `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple policy IDs.
* `-meta` - Indicates that policy metadata such as the content hash and raft
- `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The name of the policy to read.
- `-name=<string>` - The name of the policy to read.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Update"
sidebar_current: "docs-commands-acl-policy-update"
layout: docs
page_title: 'Commands: ACL Policy Update'
sidebar_current: docs-commands-acl-policy-update
---
# Consul ACL Policy Update
@ -20,37 +20,37 @@ Usage: `consul acl policy update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-description=<string>` - A description of the policy.
- `-description=<string>` - A description of the policy.
* `-id=<string>` - The ID of the policy to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs
- `-id=<string>` - The ID of the policy to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs
* `-meta` - Indicates that policy metadata such as the content hash and raft
- `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry
* `-name=<string>` - The policy's name.
- `-name=<string>` - The policy's name.
* `-no-merge` - Do not merge the current policy information with what is provided
to the command. Instead overwrite all fields with the exception of
the policy ID which is immutable.
- `-no-merge` - Do not merge the current policy information with what is provided
to the command. Instead overwrite all fields with the exception of
the policy ID which is immutable.
* `-rules=<string>` - The policy rules. May be prefixed with `@` to indicate that
the value is a file path to load the rules from. `-` may also be given to
indicate that the rules are available on stdin.
- `-rules=<string>` - The policy rules. May be prefixed with `@` to indicate that
the value is a file path to load the rules from. `-` may also be given to
indicate that the rules are available on stdin.
* `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
- `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Role"
sidebar_current: "docs-commands-acl-role"
layout: docs
page_title: 'Commands: ACL Role'
sidebar_current: docs-commands-acl-role
---
# Consul ACL Roles
@ -15,7 +15,7 @@ This command is available in Consul 1.5.0 and newer.
ACL roles may also be managed via the [HTTP API](/api/acl/roles.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
@ -23,8 +23,7 @@ secret ID as the value of the `-token` parameter.
Usage: `consul acl role <subcommand>`
For the exact documentation for your Consul version, run `consul acl
role -h` to view the complete list of subcommands.
For the exact documentation for your Consul version, run `consul acl role -h` to view the complete list of subcommands.
```text
Usage: consul acl role <subcommand> [options] [args]

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Role Create"
sidebar_current: "docs-commands-acl-role-create"
layout: docs
page_title: 'Commands: ACL Role Create'
sidebar_current: docs-commands-acl-role-create
---
# Consul ACL Role Create
@ -16,33 +16,33 @@ Usage: `consul acl role create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-description=<string>` - A description of the role.
- `-description=<string>` - A description of the role.
* `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry.
- `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The new role's name. This flag is required.
- `-name=<string>` - The new role's name. This flag is required.
* `-policy-id=<value>` - ID of a policy to use for this role. May be specified
- `-policy-id=<value>` - ID of a policy to use for this role. May be specified
multiple times
* `-policy-name=<value>` - Name of a policy to use for this role. May be
- `-policy-name=<value>` - Name of a policy to use for this role. May be
specified multiple times
* `-service-identity=<value>` - Name of a service identity to use for this
- `-service-identity=<value>` - Name of a service identity to use for this
role. May be specified multiple times. Format is the `SERVICENAME` or
`SERVICENAME:DATACENTER1,DATACENTER2,...`
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Role Delete"
sidebar_current: "docs-commands-acl-role-delete"
layout: docs
page_title: 'Commands: ACL Role Delete'
sidebar_current: docs-commands-acl-role-delete
---
# Consul ACL Role Delete
@ -16,19 +16,19 @@ Usage: `consul acl role delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-id=<string>` - The ID of the role to delete. It may be specified as a
- `-id=<string>` - The ID of the role to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple role IDs.
* `-name=<string>` - The Name of the role to delete.
- `-name=<string>` - The Name of the role to delete.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Role List"
sidebar_current: "docs-commands-acl-role-list"
layout: docs
page_title: 'Commands: ACL Role List'
sidebar_current: docs-commands-acl-role-list
---
# Consul ACL Role List
@ -16,19 +16,19 @@ Usage: `consul acl role list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-meta` - Indicates that role metadata such as the content hash and
Raft indices should be shown for each entry.
- `-meta` - Indicates that role metadata such as the content hash and
Raft indices should be shown for each entry.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Role Read"
sidebar_current: "docs-commands-acl-role-read"
layout: docs
page_title: 'Commands: ACL Role Read'
sidebar_current: docs-commands-acl-role-read
---
# Consul ACL Role Read
@ -16,24 +16,24 @@ Usage: `consul acl role read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-id=<string>` - The ID of the role to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple role IDs.
- `-id=<string>` - The ID of the role to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple role IDs.
* `-meta` - Indicates that role metadata such as the content hash and raft
- `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The name of the role to read.
- `-name=<string>` - The name of the role to read.
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Commands: ACL Role Update"
sidebar_current: "docs-commands-acl-role-update"
layout: docs
page_title: 'Commands: ACL Role Update'
sidebar_current: docs-commands-acl-role-update
---
# Consul ACL Role Update
@ -20,40 +20,40 @@ Usage: `consul acl role update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
@include 'http_api_options_client.mdx'
@include 'http_api_options_server.mdx'
#### Command Options
* `-description=<string>` - A description of the role.
- `-description=<string>` - A description of the role.
* `-id=<string>` - The ID of the role to update. It may be specified as a
- `-id=<string>` - The ID of the role to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple role IDs
* `-meta` - Indicates that role metadata such as the content hash and raft
- `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry
* `-name=<string>` - The role name.
- `-name=<string>` - The role name.
* `-no-merge` - Do not merge the current role information with what is provided
- `-no-merge` - Do not merge the current role information with what is provided
to the command. Instead overwrite all fields with the exception of the role
ID which is immutable.
* `-policy-id=<value>` - ID of a policy to use for this role. May be specified
- `-policy-id=<value>` - ID of a policy to use for this role. May be specified
multiple times
* `-policy-name=<value>` - Name of a policy to use for this role. May be
- `-policy-name=<value>` - Name of a policy to use for this role. May be
specified multiple times
* `-service-identity=<value>` - Name of a service identity to use for this
- `-service-identity=<value>` - Name of a service identity to use for this
role. May be specified multiple times. Format is the `SERVICENAME` or
`SERVICENAME:DATACENTER1,DATACENTER2,...`
* `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
#### Enterprise Options
<%= partial "docs/commands/http_api_namespace_options" %>
@include 'http_api_namespace_options.mdx'
## Examples

View File

@ -1,49 +0,0 @@
---
layout: "docs"
page_title: "Commands: ACL Set Agent Token"
sidebar_current: "docs-commands-acl-set-agent-token"
---
# Consul ACL Set Agent Token
Command: `consul acl set-agent-token`
This command updates the ACL tokens currently in use by the agent. It can be used to introduce
ACL tokens to the agent for the first time, or to update tokens that were initially loaded from
the agent's configuration. Tokens are not persisted, so will need to be updated again if the
agent is restarted.
## Usage
Usage: consul acl set-agent-token [options] TYPE TOKEN
### Token Types
* `default` - The default token is the token that the agent will use for
both internal agent operations and operations initiated by the HTTP
and DNS interfaces when no specific token is provided. If not set the
agent will use the anonymous token.
* `agent` - The token that the agent will use for internal agent operations.
If not given then the default token is used for these operations.
* `master` - This sets the token that can be used to access the Agent APIs in
the event that the ACL datacenter cannot be reached.
* `replication` - This is the token that the agent will use for replication
operations. This token will need to be configured with read access to
whatever data is being replicated.
### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
## Examples
Set the `default` token:
```
$ consul acl set-agent-token default c4d0f8df-3aba-4ab6-a7a0-35b760dc29a1
```

Some files were not shown because too many files have changed in this diff Show More