initial
This commit is contained in:
Jeff Escalante
parent
e53b5d2d10
commit
0d9e72f1dc
|
|
@ -0,0 +1,18 @@
|
||||||
|
# This file is for unifying the coding style for different editors and IDEs
|
||||||
|
# editorconfig.org
|
||||||
|
|
||||||
|
root = true
|
||||||
|
|
||||||
|
[*]
|
||||||
|
end_of_line = lf
|
||||||
|
charset = utf-8
|
||||||
|
insert_final_newline = true
|
||||||
|
trim_trailing_whitespace = true
|
||||||
|
indent_style = space
|
||||||
|
indent_size = 2
|
||||||
|
|
||||||
|
[Makefile]
|
||||||
|
indent_style = tab
|
||||||
|
|
||||||
|
[{*.md,*.json}]
|
||||||
|
max_line_length = null
|
||||||
|
|
@ -0,0 +1,4 @@
|
||||||
|
module.exports = {
|
||||||
|
...require('@hashicorp/nextjs-scripts/.eslintrc.js'),
|
||||||
|
ignorePatterns: ['public/'],
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
node_modules
|
||||||
|
.DS_Store
|
||||||
|
.next
|
||||||
|
out
|
||||||
|
.mdx-data
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
{
|
||||||
|
"ignore": {
|
||||||
|
"marked": {
|
||||||
|
"versions": "0.8.2",
|
||||||
|
"reason": "IE breaks"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
FROM node:10.16.3-alpine
|
||||||
|
RUN apk add --update --no-cache git make g++ automake autoconf libtool nasm libpng-dev
|
||||||
|
|
||||||
|
COPY ./package.json /website/package.json
|
||||||
|
COPY ./package-lock.json /website/package-lock.json
|
||||||
|
WORKDIR /website
|
||||||
|
RUN npm install
|
||||||
|
|
@ -1,3 +0,0 @@
|
||||||
source "https://rubygems.org"
|
|
||||||
|
|
||||||
gem "middleman-hashicorp", "0.3.44"
|
|
||||||
|
|
@ -1,161 +0,0 @@
|
||||||
GEM
|
|
||||||
remote: https://rubygems.org/
|
|
||||||
specs:
|
|
||||||
activesupport (4.2.11.1)
|
|
||||||
i18n (~> 0.7)
|
|
||||||
minitest (~> 5.1)
|
|
||||||
thread_safe (~> 0.3, >= 0.3.4)
|
|
||||||
tzinfo (~> 1.1)
|
|
||||||
autoprefixer-rails (9.7.4)
|
|
||||||
execjs
|
|
||||||
bootstrap-sass (3.4.1)
|
|
||||||
autoprefixer-rails (>= 5.2.1)
|
|
||||||
sassc (>= 2.0.0)
|
|
||||||
builder (3.2.4)
|
|
||||||
capybara (2.4.4)
|
|
||||||
mime-types (>= 1.16)
|
|
||||||
nokogiri (>= 1.3.3)
|
|
||||||
rack (>= 1.0.0)
|
|
||||||
rack-test (>= 0.5.4)
|
|
||||||
xpath (~> 2.0)
|
|
||||||
chunky_png (1.3.11)
|
|
||||||
coffee-script (2.4.1)
|
|
||||||
coffee-script-source
|
|
||||||
execjs
|
|
||||||
coffee-script-source (1.12.2)
|
|
||||||
compass (1.0.3)
|
|
||||||
chunky_png (~> 1.2)
|
|
||||||
compass-core (~> 1.0.2)
|
|
||||||
compass-import-once (~> 1.0.5)
|
|
||||||
rb-fsevent (>= 0.9.3)
|
|
||||||
rb-inotify (>= 0.9)
|
|
||||||
sass (>= 3.3.13, < 3.5)
|
|
||||||
compass-core (1.0.3)
|
|
||||||
multi_json (~> 1.0)
|
|
||||||
sass (>= 3.3.0, < 3.5)
|
|
||||||
compass-import-once (1.0.5)
|
|
||||||
sass (>= 3.2, < 3.5)
|
|
||||||
em-websocket (0.5.1)
|
|
||||||
eventmachine (>= 0.12.9)
|
|
||||||
http_parser.rb (~> 0.6.0)
|
|
||||||
erubis (2.7.0)
|
|
||||||
eventmachine (1.2.7)
|
|
||||||
execjs (2.7.0)
|
|
||||||
ffi (1.12.2)
|
|
||||||
haml (5.1.2)
|
|
||||||
temple (>= 0.8.0)
|
|
||||||
tilt
|
|
||||||
hike (1.2.3)
|
|
||||||
hooks (0.4.1)
|
|
||||||
uber (~> 0.0.14)
|
|
||||||
http_parser.rb (0.6.0)
|
|
||||||
i18n (0.7.0)
|
|
||||||
json (2.3.0)
|
|
||||||
kramdown (1.17.0)
|
|
||||||
listen (3.0.8)
|
|
||||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
|
||||||
rb-inotify (~> 0.9, >= 0.9.7)
|
|
||||||
middleman (3.4.1)
|
|
||||||
coffee-script (~> 2.2)
|
|
||||||
compass (>= 1.0.0, < 2.0.0)
|
|
||||||
compass-import-once (= 1.0.5)
|
|
||||||
execjs (~> 2.0)
|
|
||||||
haml (>= 4.0.5)
|
|
||||||
kramdown (~> 1.2)
|
|
||||||
middleman-core (= 3.4.1)
|
|
||||||
middleman-sprockets (>= 3.1.2)
|
|
||||||
sass (>= 3.4.0, < 4.0)
|
|
||||||
uglifier (~> 2.5)
|
|
||||||
middleman-core (3.4.1)
|
|
||||||
activesupport (~> 4.1)
|
|
||||||
bundler (~> 1.1)
|
|
||||||
capybara (~> 2.4.4)
|
|
||||||
erubis
|
|
||||||
hooks (~> 0.3)
|
|
||||||
i18n (~> 0.7.0)
|
|
||||||
listen (~> 3.0.3)
|
|
||||||
padrino-helpers (~> 0.12.3)
|
|
||||||
rack (>= 1.4.5, < 2.0)
|
|
||||||
thor (>= 0.15.2, < 2.0)
|
|
||||||
tilt (~> 1.4.1, < 2.0)
|
|
||||||
middleman-hashicorp (0.3.44)
|
|
||||||
bootstrap-sass (~> 3.3)
|
|
||||||
builder (~> 3.2)
|
|
||||||
middleman (~> 3.4)
|
|
||||||
middleman-livereload (~> 3.4)
|
|
||||||
middleman-syntax (~> 3.0)
|
|
||||||
redcarpet (~> 3.3)
|
|
||||||
turbolinks (~> 5.0)
|
|
||||||
middleman-livereload (3.4.6)
|
|
||||||
em-websocket (~> 0.5.1)
|
|
||||||
middleman-core (>= 3.3)
|
|
||||||
rack-livereload (~> 0.3.15)
|
|
||||||
middleman-sprockets (3.5.0)
|
|
||||||
middleman-core (>= 3.3)
|
|
||||||
sprockets (~> 2.12.1)
|
|
||||||
sprockets-helpers (~> 1.1.0)
|
|
||||||
sprockets-sass (~> 1.3.0)
|
|
||||||
middleman-syntax (3.2.0)
|
|
||||||
middleman-core (>= 3.2)
|
|
||||||
rouge (~> 3.2)
|
|
||||||
mime-types (3.3.1)
|
|
||||||
mime-types-data (~> 3.2015)
|
|
||||||
mime-types-data (3.2019.1009)
|
|
||||||
mini_portile2 (2.4.0)
|
|
||||||
minitest (5.14.0)
|
|
||||||
multi_json (1.14.1)
|
|
||||||
nokogiri (1.10.9)
|
|
||||||
mini_portile2 (~> 2.4.0)
|
|
||||||
padrino-helpers (0.12.9)
|
|
||||||
i18n (~> 0.6, >= 0.6.7)
|
|
||||||
padrino-support (= 0.12.9)
|
|
||||||
tilt (>= 1.4.1, < 3)
|
|
||||||
padrino-support (0.12.9)
|
|
||||||
activesupport (>= 3.1)
|
|
||||||
rack (1.6.13)
|
|
||||||
rack-livereload (0.3.17)
|
|
||||||
rack
|
|
||||||
rack-test (1.1.0)
|
|
||||||
rack (>= 1.0, < 3)
|
|
||||||
rb-fsevent (0.10.3)
|
|
||||||
rb-inotify (0.10.1)
|
|
||||||
ffi (~> 1.0)
|
|
||||||
redcarpet (3.5.0)
|
|
||||||
rouge (3.16.0)
|
|
||||||
sass (3.4.25)
|
|
||||||
sassc (2.2.1)
|
|
||||||
ffi (~> 1.9)
|
|
||||||
sprockets (2.12.5)
|
|
||||||
hike (~> 1.2)
|
|
||||||
multi_json (~> 1.0)
|
|
||||||
rack (~> 1.0)
|
|
||||||
tilt (~> 1.1, != 1.3.0)
|
|
||||||
sprockets-helpers (1.1.0)
|
|
||||||
sprockets (~> 2.0)
|
|
||||||
sprockets-sass (1.3.1)
|
|
||||||
sprockets (~> 2.0)
|
|
||||||
tilt (~> 1.1)
|
|
||||||
temple (0.8.2)
|
|
||||||
thor (1.0.1)
|
|
||||||
thread_safe (0.3.6)
|
|
||||||
tilt (1.4.1)
|
|
||||||
turbolinks (5.2.1)
|
|
||||||
turbolinks-source (~> 5.2)
|
|
||||||
turbolinks-source (5.2.0)
|
|
||||||
tzinfo (1.2.6)
|
|
||||||
thread_safe (~> 0.1)
|
|
||||||
uber (0.0.15)
|
|
||||||
uglifier (2.7.2)
|
|
||||||
execjs (>= 0.3.0)
|
|
||||||
json (>= 1.8.0)
|
|
||||||
xpath (2.1.0)
|
|
||||||
nokogiri (~> 1.3)
|
|
||||||
|
|
||||||
PLATFORMS
|
|
||||||
ruby
|
|
||||||
|
|
||||||
DEPENDENCIES
|
|
||||||
middleman-hashicorp (= 0.3.44)
|
|
||||||
|
|
||||||
BUNDLED WITH
|
|
||||||
1.17.3
|
|
||||||
|
|
@ -1,33 +1,54 @@
|
||||||
VERSION?="0.3.44"
|
# Default: run this if working on the website locally to run in watch mode.
|
||||||
|
|
||||||
# The volume mounting steps are a way to exclude all the consul docs from being built
|
|
||||||
# in the Consul site build process while still including the index.html page that points
|
|
||||||
# users to learn.hashicorp.com. See PR#5847.
|
|
||||||
|
|
||||||
build:
|
|
||||||
@echo "==> Starting build in Docker..."
|
|
||||||
@docker run \
|
|
||||||
--interactive \
|
|
||||||
--rm \
|
|
||||||
--tty \
|
|
||||||
--volume "$(shell pwd):/website" \
|
|
||||||
--volume "/website/source/docs/guides" \
|
|
||||||
--volume "$(shell pwd)/source/docs/guides/index.html.md:/website/source/docs/guides/index.html.md" \
|
|
||||||
-e "ENV=production" \
|
|
||||||
hashicorp/middleman-hashicorp:${VERSION} \
|
|
||||||
bundle exec middleman build --verbose --clean
|
|
||||||
|
|
||||||
website:
|
website:
|
||||||
|
@echo "==> Downloading latest Docker image..."
|
||||||
|
@docker pull hashicorp/consul-website
|
||||||
@echo "==> Starting website in Docker..."
|
@echo "==> Starting website in Docker..."
|
||||||
@docker run \
|
@docker run \
|
||||||
--interactive \
|
--interactive \
|
||||||
--rm \
|
--rm \
|
||||||
--tty \
|
--tty \
|
||||||
--publish "4567:4567" \
|
--workdir "/website" \
|
||||||
--publish "35729:35729" \
|
|
||||||
--volume "$(shell pwd):/website" \
|
--volume "$(shell pwd):/website" \
|
||||||
--volume "/website/source/docs/guides" \
|
--volume "/website/node_modules" \
|
||||||
--volume "$(shell pwd)/source/docs/guides/index.html.md:/website/source/docs/guides/index.html.md" \
|
--publish "3000:3000" \
|
||||||
hashicorp/middleman-hashicorp:${VERSION}
|
hashicorp/consul-website \
|
||||||
|
npm start
|
||||||
|
|
||||||
.PHONY: build website
|
# This command will generate a static version of the website to the "out" folder.
|
||||||
|
build:
|
||||||
|
@echo "==> Downloading latest Docker image..."
|
||||||
|
@docker pull hashicorp/consul-website
|
||||||
|
@echo "==> Starting build in Docker..."
|
||||||
|
@docker run \
|
||||||
|
--interactive \
|
||||||
|
--rm \
|
||||||
|
--tty \
|
||||||
|
--workdir "/website" \
|
||||||
|
--volume "$(shell pwd):/website" \
|
||||||
|
--volume "/website/node_modules" \
|
||||||
|
hashicorp/consul-website \
|
||||||
|
npm run static
|
||||||
|
|
||||||
|
# If you are changing node dependencies locally, run this to generate a new
|
||||||
|
# local Docker image with the dependency changes included.
|
||||||
|
build-image:
|
||||||
|
@echo "==> Building Docker image..."
|
||||||
|
@docker build -t hashicorp-consul-website-local .
|
||||||
|
|
||||||
|
# Use this if you have run `build-image` to use the locally built image
|
||||||
|
# rather than our CI-generated image to test dependency changes.
|
||||||
|
website-local:
|
||||||
|
@echo "==> Starting website in Docker..."
|
||||||
|
@docker run \
|
||||||
|
--interactive \
|
||||||
|
--rm \
|
||||||
|
--tty \
|
||||||
|
--workdir "/website" \
|
||||||
|
--volume "$(shell pwd):/website" \
|
||||||
|
--volume "/website/node_modules" \
|
||||||
|
--publish "3000:3000" \
|
||||||
|
hashicorp-consul-website-local \
|
||||||
|
npm start
|
||||||
|
|
||||||
|
.DEFAULT_GOAL := website
|
||||||
|
.PHONY: build build-image website website-local
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,192 @@
|
||||||
# Consul Website
|
# Consul Website
|
||||||
|
|
||||||
This subdirectory contains the entire source for the [Consul Website][consul].
|
[](https://app.netlify.com/sites/consul-docs-platform/deploys)
|
||||||
This is a [Middleman][middleman] project, which builds a static site from these
|
|
||||||
source files.
|
This subdirectory contains the entire source for the [Consul Website](https://consul.io/). This is a [NextJS](https://nextjs.org/) project, which builds a static site from these source files.
|
||||||
|
|
||||||
## Contributions Welcome!
|
## Contributions Welcome!
|
||||||
|
|
||||||
If you find a typo or you feel like you can improve the HTML, CSS, or
|
If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀
|
||||||
JavaScript, we welcome contributions. Feel free to open issues or pull requests
|
|
||||||
like any normal GitHub project, and we'll merge it in.
|
|
||||||
|
|
||||||
## Running the Site Locally
|
## Running the Site Locally
|
||||||
|
|
||||||
Running the site locally is simple. Clone this repo and run `make website`.
|
The website can be run locally through node.js or Docker. If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use node. Also if you are a vim user, it's also worth noting that vim's swapfile usage can cause issues for the live reload functionality. In order to avoid these issues, make sure you have run `:set backupcopy=yes` within vim.
|
||||||
|
|
||||||
Then open up `http://localhost:4567`. Note that some URLs you may need to append
|
### With Docker
|
||||||
".html" to make them work (in the navigation).
|
|
||||||
|
|
||||||
[middleman]: https://www.middlemanapp.com
|
Running the site locally is simple. Provided you have Docker installed, clone this repo, run `make`, and then visit `http://localhost:3000`.
|
||||||
[consul]: https://www.consul.io
|
|
||||||
|
The docker image is pre-built with all the website dependencies installed, which is what makes it so quick and simple, but also means if you need to change dependencies and test the changes within Docker, you'll need a new image. If this is something you need to do, you can run `make build-image` to generate a local Docker image with updated dependencies, then `make website-local` to use that image and preview.
|
||||||
|
|
||||||
|
### With Node
|
||||||
|
|
||||||
|
If your local development environment has a supported version (v10.0.0+) of [node installed](https://nodejs.org/en/) you can run:
|
||||||
|
|
||||||
|
- `npm install`
|
||||||
|
- `npm start`
|
||||||
|
|
||||||
|
and then visit `http://localhost:3000`.
|
||||||
|
|
||||||
|
If you pull down new code from github, you should run `npm install` again. Otherwise, there's no need to re-run `npm install` each time the site is run, you can just run `npm start` to get it going.
|
||||||
|
|
||||||
|
## Editing Content
|
||||||
|
|
||||||
|
Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/pages` directory.
|
||||||
|
|
||||||
|
To create a new page with Markdown, create a file ending in `.mdx` in the `pages/` directory. The path in the pages directory will be the URL route. For example, `pages/hello/world.mdx` will be served from the `/hello/world` URL.
|
||||||
|
|
||||||
|
This file can be standard Markdown and also supports [YAML frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is optional, there are defaults for all keys.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
title: 'My Title'
|
||||||
|
description: "A thorough, yet succinct description of the page's contents"
|
||||||
|
---
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
The significant keys in the YAML frontmatter are:
|
||||||
|
|
||||||
|
- `title` `(string)` - This is the title of the page that will be set in the HTML title.
|
||||||
|
- `description` `(string)` - This is a description of the page that will be set in the HTML description.
|
||||||
|
|
||||||
|
> ⚠️Since `api` is a reserved directory within NextJS, all `/api/**` pages are listed under the `/pages/api-docs` path.
|
||||||
|
|
||||||
|
### Editing Sidebars
|
||||||
|
|
||||||
|
The structure of the sidebars are controlled by files in the [`/data` directory](data).
|
||||||
|
|
||||||
|
- Edit [this file](data/docs-navigation.js) to change the **docs** sidebar
|
||||||
|
- Edit [this file](data/guides-navigation.js) to change the **guides** sidebar
|
||||||
|
- Edit [this file](data/intro-navigation.js) to change the **intro** sidebar
|
||||||
|
|
||||||
|
To nest sidebar items, you'll want to add a new `category` key/value accompanied by the appropriate embedded `content` values.
|
||||||
|
|
||||||
|
- `category` values will be **directory names** within the `pages` directory
|
||||||
|
- `content` values will be **file names** within their appropriately nested directory.
|
||||||
|
|
||||||
|
### Creating New Pages
|
||||||
|
|
||||||
|
There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server.
|
||||||
|
|
||||||
|
### Changing the Release Version
|
||||||
|
|
||||||
|
To change the version of Consul displayed for download on the website, head over to `data/version.js` and change the number there. It's important to note that the version number must match a version that has been released and is live on `releases.hashicorp.com` -- if it does not, the website will be unable to fetch links to the binaries and will not compile. So this version number should be changed _only after a release_.
|
||||||
|
|
||||||
|
#### Displaying a Prerelease
|
||||||
|
|
||||||
|
If there is a prerelease of any type that should be displayed on the downloads page, this can be done by editing `pages/downloads/index.jsx`. By default, the download component might look something like this:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<ProductDownloader
|
||||||
|
product="Consul"
|
||||||
|
version={VERSION}
|
||||||
|
downloads={downloadData}
|
||||||
|
community="/resources"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
To add a prerelease, an extra `prerelease` property can be added to the component as such:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<ProductDownloader
|
||||||
|
product="Consul"
|
||||||
|
version={VERSION}
|
||||||
|
downloads={downloadData}
|
||||||
|
community="/resources"
|
||||||
|
prerelease={{
|
||||||
|
type: 'release candidate', // the type of prerelease: beta, release candidate, etc.
|
||||||
|
name: 'v1.0.0', // the name displayed in text on the website
|
||||||
|
version: '1.0.0-rc1', // the actual version tag that was pushed to releases.hashicorp.com
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
This configuration would display something like the following text on the website, emphasis added to the configurable parameters:
|
||||||
|
|
||||||
|
```
|
||||||
|
A {{ release candidate }} for Consul {{ v1.0.0 }} is available! The release can be <a href='https://releases.hashicorp.com/consul/{{ 1.0.0-rc1 }}'>downloaded here</a>.
|
||||||
|
```
|
||||||
|
|
||||||
|
You may customize the parameters in any way you'd like. To remove a prerelease from the website, simply delete the `prerelease` paremeter from the above component.
|
||||||
|
|
||||||
|
### Markdown Enhancements
|
||||||
|
|
||||||
|
There are several custom markdown plugins that are available by default that enhance standard markdown to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below:
|
||||||
|
|
||||||
|
- If you see the symbols `~>`, `->`, `=>`, or `!>`, these represent [custom alerts](https://github.com/hashicorp/remark-plugins/tree/master/plugins/paragraph-custom-alerts#paragraph-custom-alerts). These render as colored boxes to draw the user's attention to some type of aside.
|
||||||
|
- If you see `@include '/some/path.mdx'`, this is a [markdown include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). It's worth noting as well that all includes resolve from `website/pages/partials` by default.
|
||||||
|
- If you see `# Headline ((#slug))`, this is an example of an [anchor link alias](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-link-aliases). It adds an extra permalink to a headline for compatibility and is removed from the output.
|
||||||
|
- Due to [automatically generated permalinks](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-links), any text changes to _headlines_ or _list items that begin with inline code_ can and will break existing permalinks. Be very cautious when changing either of these two text items.
|
||||||
|
|
||||||
|
Headlines are fairly self-explanitory, but here's an example of how list items that begin with inline code look.
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
- this is a normal list item
|
||||||
|
- `this` is a list item that begins with inline code
|
||||||
|
```
|
||||||
|
|
||||||
|
Its worth noting that _only the inline code at the beginning of the list item_ will cause problems if changed. So if you changed the above markup to...
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
- lsdhfhksdjf
|
||||||
|
- `this` jsdhfkdsjhkdsfjh
|
||||||
|
```
|
||||||
|
|
||||||
|
...while it perhaps would not be an improved user experience, no links would break because of it. The best approach is to **avoid changing headlines and inline code at the start of a list item**. If you must change one of these items, make sure to tag someone from the digital marketing development team on your pull request, they will help to ensure as much compatibility as possible.
|
||||||
|
|
||||||
|
### Redirects
|
||||||
|
|
||||||
|
This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects.
|
||||||
|
|
||||||
|
To add a redirect, head over to the `_redirects` file - the format is fairly simple. On the left is the current path, and on the right is the path that should be redirected to. It's important to note that if there are links to a `.html` version of a page, that must also be explicitly redirected. For example:
|
||||||
|
|
||||||
|
```
|
||||||
|
/foo /bar
|
||||||
|
/foo.html /bar
|
||||||
|
```
|
||||||
|
|
||||||
|
This redirect rule will send all incoming links to `/foo` and `/foo.html` to `/bar`. For more details on the redirects file format, [check out the docs on netlify](https://docs.netlify.com/routing/redirects/rewrites-proxies).
|
||||||
|
|
||||||
|
There are a couple important caveats with redirects. First, redirects are applied at the hosting layer, and therefore will not work by default in local dev mode. To test in local dev mode, you can use [`netlify dev`](https://www.netlify.com/products/dev/), or just push a commit and check using the deploy preview.
|
||||||
|
|
||||||
|
Second, redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly.
|
||||||
|
|
||||||
|
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such:
|
||||||
|
|
||||||
|
```
|
||||||
|
/foo /nested/foo
|
||||||
|
/foo.html /nested/foo
|
||||||
|
```
|
||||||
|
|
||||||
|
Finally, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
|
||||||
|
|
||||||
|
One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-navigation` file. If previously the structure looked like:
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
category: 'docs',
|
||||||
|
content: [
|
||||||
|
'foo'
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destnation, we need to slightly change the structure as such:
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
category: 'docs',
|
||||||
|
content: [
|
||||||
|
{ title: 'Foo Title', href: 'https://learn.hashicorp.com/vault/foo' }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
As the majority of items in the side nav are internal links, the structure makes it as easy as possible to represent these links. This alternate syntax is the most concise manner than an external link can be represented. External links can be used anywhere within the docs sidenav.
|
||||||
|
|
||||||
|
It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the `_redirects` file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first.
|
||||||
|
|
||||||
|
### Deployment
|
||||||
|
|
||||||
|
This website is hosted on Netlify and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews.
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
# REDIRECTS FILE
|
||||||
|
#
|
||||||
|
# See https://www.netlify.com/docs/redirects/ for documentation. Please do not
|
||||||
|
# modify or delete existing redirects without first verifying internally.
|
||||||
|
|
||||||
|
|
@ -0,0 +1,4 @@
|
||||||
|
module.exports = {
|
||||||
|
presets: ['next/babel'],
|
||||||
|
plugins: ['import-glob-array'],
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,32 @@
|
||||||
|
import Link from 'next/link'
|
||||||
|
|
||||||
|
export default function Footer({ openConsentManager }) {
|
||||||
|
return (
|
||||||
|
<footer className="g-footer">
|
||||||
|
<div className="g-container">
|
||||||
|
<div className="left">
|
||||||
|
<Link href="/intro">
|
||||||
|
<a>Intro</a>
|
||||||
|
</Link>
|
||||||
|
<Link href="/guides">
|
||||||
|
<a>Guides</a>
|
||||||
|
</Link>
|
||||||
|
<Link href="/docs">
|
||||||
|
<a>Docs</a>
|
||||||
|
</Link>
|
||||||
|
<Link href="/community">
|
||||||
|
<a>Community</a>
|
||||||
|
</Link>
|
||||||
|
<a href="https://hashicorp.com/privacy">Privacy</a>
|
||||||
|
<Link href="/security">
|
||||||
|
<a>Security</a>
|
||||||
|
</Link>
|
||||||
|
<Link href="/files/press-kit.zip">
|
||||||
|
<a>Press Kit</a>
|
||||||
|
</Link>
|
||||||
|
<a onClick={openConsentManager}>Consent Manager</a>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</footer>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,32 @@
|
||||||
|
.g-footer {
|
||||||
|
padding: 25px 0 17px 0;
|
||||||
|
flex-shrink: 0;
|
||||||
|
display: flex;
|
||||||
|
|
||||||
|
& .g-container {
|
||||||
|
display: flex;
|
||||||
|
justify-content: space-between;
|
||||||
|
flex-wrap: wrap;
|
||||||
|
}
|
||||||
|
|
||||||
|
& a {
|
||||||
|
color: black;
|
||||||
|
opacity: 0.5;
|
||||||
|
transition: opacity 0.25s ease;
|
||||||
|
cursor: pointer;
|
||||||
|
display: inline-block;
|
||||||
|
|
||||||
|
&:hover {
|
||||||
|
opacity: 1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
& .left > a {
|
||||||
|
margin-right: 20px;
|
||||||
|
margin-bottom: 8px;
|
||||||
|
|
||||||
|
&:last-child {
|
||||||
|
margin-right: 0;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
import Subnav from '@hashicorp/react-subnav'
|
||||||
|
import subnavItems from '../../data/subnav'
|
||||||
|
import { useRouter } from 'next/router'
|
||||||
|
|
||||||
|
export default function ConsulSubnav() {
|
||||||
|
const router = useRouter()
|
||||||
|
return (
|
||||||
|
<Subnav
|
||||||
|
titleLink={{
|
||||||
|
text: 'consul',
|
||||||
|
url: '/',
|
||||||
|
}}
|
||||||
|
ctaLinks={[
|
||||||
|
{ text: 'GitHub', url: 'https://www.github.com/hashicorp/consul' },
|
||||||
|
{ text: 'Download', url: '/downloads' },
|
||||||
|
]}
|
||||||
|
currentPath={router.pathname}
|
||||||
|
menuItemsAlign="right"
|
||||||
|
menuItems={subnavItems}
|
||||||
|
constrainWidth
|
||||||
|
/>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
@ -1,113 +0,0 @@
|
||||||
set :base_url, "https://www.consul.io/"
|
|
||||||
|
|
||||||
activate :hashicorp do |h|
|
|
||||||
h.name = "consul"
|
|
||||||
h.version = "1.7.2"
|
|
||||||
h.github_slug = "hashicorp/consul"
|
|
||||||
end
|
|
||||||
|
|
||||||
# Netlify redirects/headers
|
|
||||||
proxy '_redirects', 'redirects.txt', ignore: true
|
|
||||||
|
|
||||||
helpers do
|
|
||||||
# Returns a segment tracking ID such that local development is not
|
|
||||||
# tracked to production systems.
|
|
||||||
def segmentId()
|
|
||||||
if (ENV['ENV'] == 'production')
|
|
||||||
'IyzLrqXkox5KJ8XL4fo8vTYNGfiKlTCm'
|
|
||||||
else
|
|
||||||
'0EXTgkNx0Ydje2PGXVbRhpKKoe5wtzcE'
|
|
||||||
end
|
|
||||||
end
|
|
||||||
|
|
||||||
# Returns the FQDN of the image URL.
|
|
||||||
#
|
|
||||||
# @param [String] path
|
|
||||||
#
|
|
||||||
# @return [String]
|
|
||||||
def image_url(path)
|
|
||||||
File.join(base_url, image_path(path))
|
|
||||||
end
|
|
||||||
|
|
||||||
# Get the title for the page.
|
|
||||||
#
|
|
||||||
# @param [Middleman::Page] page
|
|
||||||
#
|
|
||||||
# @return [String]
|
|
||||||
def title_for(page)
|
|
||||||
if page && page.data.page_title
|
|
||||||
return "#{page.data.page_title} - Consul by HashiCorp"
|
|
||||||
end
|
|
||||||
|
|
||||||
"Consul by HashiCorp"
|
|
||||||
end
|
|
||||||
|
|
||||||
# Get the description for the page
|
|
||||||
#
|
|
||||||
# @param [Middleman::Page] page
|
|
||||||
#
|
|
||||||
# @return [String]
|
|
||||||
def description_for(page)
|
|
||||||
description = (page.data.description || "Consul by HashiCorp")
|
|
||||||
.gsub('"', '')
|
|
||||||
.gsub(/\n+/, ' ')
|
|
||||||
.squeeze(' ')
|
|
||||||
|
|
||||||
return escape_html(description)
|
|
||||||
end
|
|
||||||
|
|
||||||
# This helps by setting the "active" class for sidebar nav elements
|
|
||||||
# if the YAML frontmatter matches the expected value.
|
|
||||||
def sidebar_current(expected)
|
|
||||||
current = current_page.data.sidebar_current || ""
|
|
||||||
if current.start_with?(expected)
|
|
||||||
return " class=\"active\""
|
|
||||||
else
|
|
||||||
return ""
|
|
||||||
end
|
|
||||||
end
|
|
||||||
|
|
||||||
# Returns the id for this page.
|
|
||||||
# @return [String]
|
|
||||||
def body_id_for(page)
|
|
||||||
if !(name = page.data.sidebar_current).blank?
|
|
||||||
return "page-#{name.strip}"
|
|
||||||
end
|
|
||||||
if page.url == "/" || page.url == "/index.html"
|
|
||||||
return "page-home"
|
|
||||||
end
|
|
||||||
if !(title = page.data.page_title).blank?
|
|
||||||
return title
|
|
||||||
.downcase
|
|
||||||
.gsub('"', '')
|
|
||||||
.gsub(/[^\w]+/, '-')
|
|
||||||
.gsub(/_+/, '-')
|
|
||||||
.squeeze('-')
|
|
||||||
.squeeze(' ')
|
|
||||||
end
|
|
||||||
return ""
|
|
||||||
end
|
|
||||||
|
|
||||||
# Returns the list of classes for this page.
|
|
||||||
# @return [String]
|
|
||||||
def body_classes_for(page)
|
|
||||||
classes = []
|
|
||||||
|
|
||||||
if !(layout = page.data.layout).blank?
|
|
||||||
classes << "layout-#{page.data.layout}"
|
|
||||||
end
|
|
||||||
|
|
||||||
if !(title = page.data.page_title).blank?
|
|
||||||
title = title
|
|
||||||
.downcase
|
|
||||||
.gsub('"', '')
|
|
||||||
.gsub(/[^\w]+/, '-')
|
|
||||||
.gsub(/_+/, '-')
|
|
||||||
.squeeze('-')
|
|
||||||
.squeeze(' ')
|
|
||||||
classes << "page-#{title}"
|
|
||||||
end
|
|
||||||
|
|
||||||
return classes.join(" ")
|
|
||||||
end
|
|
||||||
end
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
// The root folder for this documentation category is `pages/docs`
|
||||||
|
//
|
||||||
|
// - 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 []
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
// 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 []
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
// The root folder for this documentation category is `pages/intro`
|
||||||
|
//
|
||||||
|
// - 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 []
|
||||||
|
|
@ -0,0 +1,33 @@
|
||||||
|
export default [
|
||||||
|
{
|
||||||
|
text: 'Intro',
|
||||||
|
url: '/intro',
|
||||||
|
type: 'inbound',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Learn',
|
||||||
|
url: 'https://learn.hashicorp.com/consul',
|
||||||
|
type: 'outbound',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Docs',
|
||||||
|
url: '/docs',
|
||||||
|
type: 'inbound',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'API',
|
||||||
|
url: '/api-docs',
|
||||||
|
type: 'inbound',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Community',
|
||||||
|
url: '/community',
|
||||||
|
type: 'inbound',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Enterprise',
|
||||||
|
url:
|
||||||
|
'https://www.hashicorp.com/products/consul/?utm_source=oss&utm_medium=header-nav&utm_campaign=consul',
|
||||||
|
type: 'outbound',
|
||||||
|
},
|
||||||
|
]
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
export default '1.7.2'
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
import DocsPage from '@hashicorp/react-docs-page'
|
||||||
|
import order from '../data/api-docs-navigation.js'
|
||||||
|
import { frontMatter as data } from '../pages/api-docs/**/*.mdx'
|
||||||
|
import Head from 'next/head'
|
||||||
|
import Link from 'next/link'
|
||||||
|
|
||||||
|
function ApiDocsLayoutWrapper(pageMeta) {
|
||||||
|
function ApiDocsLayout(props) {
|
||||||
|
return (
|
||||||
|
<DocsPage
|
||||||
|
{...props}
|
||||||
|
product="consul"
|
||||||
|
head={{
|
||||||
|
is: Head,
|
||||||
|
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||||
|
description: pageMeta.description,
|
||||||
|
siteName: 'Consul by HashiCorp',
|
||||||
|
}}
|
||||||
|
sidenav={{
|
||||||
|
Link,
|
||||||
|
category: 'api-docs',
|
||||||
|
currentPage: props.path,
|
||||||
|
data,
|
||||||
|
order,
|
||||||
|
}}
|
||||||
|
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||||
|
/>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
ApiDocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||||
|
|
||||||
|
return ApiDocsLayout
|
||||||
|
}
|
||||||
|
|
||||||
|
export default ApiDocsLayoutWrapper
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
import DocsPage from '@hashicorp/react-docs-page'
|
||||||
|
import order from '../data/docs-navigation.js'
|
||||||
|
import { frontMatter as data } from '../pages/docs/**/*.mdx'
|
||||||
|
import Head from 'next/head'
|
||||||
|
import Link from 'next/link'
|
||||||
|
|
||||||
|
function DocsLayoutWrapper(pageMeta) {
|
||||||
|
function DocsLayout(props) {
|
||||||
|
return (
|
||||||
|
<DocsPage
|
||||||
|
{...props}
|
||||||
|
product="consul"
|
||||||
|
head={{
|
||||||
|
is: Head,
|
||||||
|
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||||
|
description: pageMeta.description,
|
||||||
|
siteName: 'Consul by HashiCorp',
|
||||||
|
}}
|
||||||
|
sidenav={{
|
||||||
|
Link,
|
||||||
|
category: 'docs',
|
||||||
|
currentPage: props.path,
|
||||||
|
data,
|
||||||
|
order,
|
||||||
|
}}
|
||||||
|
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||||
|
/>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
DocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||||
|
|
||||||
|
return DocsLayout
|
||||||
|
}
|
||||||
|
|
||||||
|
export default DocsLayoutWrapper
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
import DocsPage from '@hashicorp/react-docs-page'
|
||||||
|
import Head from 'next/head'
|
||||||
|
import Link from 'next/link'
|
||||||
|
|
||||||
|
function DocsLayoutWrapper(pageMeta) {
|
||||||
|
function DocsLayout(props) {
|
||||||
|
return (
|
||||||
|
<DocsPage
|
||||||
|
{...props}
|
||||||
|
product="consul"
|
||||||
|
head={{
|
||||||
|
is: Head,
|
||||||
|
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||||
|
description: pageMeta.description,
|
||||||
|
siteName: 'Consul by HashiCorp',
|
||||||
|
}}
|
||||||
|
sidenav={{
|
||||||
|
Link,
|
||||||
|
category: 'docs',
|
||||||
|
currentPage: props.path,
|
||||||
|
data: [],
|
||||||
|
order: [],
|
||||||
|
disableFilter: true,
|
||||||
|
}}
|
||||||
|
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||||
|
/>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
DocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||||
|
|
||||||
|
return DocsLayout
|
||||||
|
}
|
||||||
|
|
||||||
|
export default DocsLayoutWrapper
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
import DocsPage from '@hashicorp/react-docs-page'
|
||||||
|
import order from '../data/intro-navigation.js'
|
||||||
|
import { frontMatter as data } from '../pages/intro/**/*.mdx'
|
||||||
|
import Head from 'next/head'
|
||||||
|
import Link from 'next/link'
|
||||||
|
|
||||||
|
function IntroLayoutWrapper(pageMeta) {
|
||||||
|
function IntroLayout(props) {
|
||||||
|
return (
|
||||||
|
<DocsPage
|
||||||
|
{...props}
|
||||||
|
product="consul"
|
||||||
|
head={{
|
||||||
|
is: Head,
|
||||||
|
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||||
|
description: pageMeta.description,
|
||||||
|
siteName: 'Consul by HashiCorp',
|
||||||
|
}}
|
||||||
|
sidenav={{
|
||||||
|
Link,
|
||||||
|
category: 'intro',
|
||||||
|
currentPage: props.path,
|
||||||
|
data,
|
||||||
|
order,
|
||||||
|
}}
|
||||||
|
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||||
|
/>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
IntroLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||||
|
|
||||||
|
return IntroLayout
|
||||||
|
}
|
||||||
|
|
||||||
|
export default IntroLayoutWrapper
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
import React from 'react'
|
||||||
|
import bugsnag from '@bugsnag/js'
|
||||||
|
import bugsnagReact from '@bugsnag/plugin-react'
|
||||||
|
|
||||||
|
const apiKey =
|
||||||
|
typeof window === 'undefined'
|
||||||
|
? 'b6c57b27a37e531a5de94f065dd98bc0'
|
||||||
|
: 'de0b822b269aa57b620efd8927e03744'
|
||||||
|
|
||||||
|
const bugsnagClient = bugsnag({
|
||||||
|
apiKey,
|
||||||
|
releaseStage: process.env.NODE_ENV || 'development',
|
||||||
|
})
|
||||||
|
|
||||||
|
bugsnagClient.use(bugsnagReact, React)
|
||||||
|
|
||||||
|
export default bugsnagClient
|
||||||
|
|
@ -0,0 +1,76 @@
|
||||||
|
const isProd = process.env.NODE_ENV === 'production'
|
||||||
|
|
||||||
|
const segmentWriteKey = isProd
|
||||||
|
? 'AjXdfmTTk1I9q9dfyePuDFHBrz1tCO3l'
|
||||||
|
: '0EXTgkNx0Ydje2PGXVbRhpKKoe5wtzcE'
|
||||||
|
|
||||||
|
// TODO: refactor into web components
|
||||||
|
let utilityServerRoot = isProd
|
||||||
|
? 'https://util.hashicorp.com'
|
||||||
|
: 'https://hashicorp-web-util-staging.herokuapp.com'
|
||||||
|
|
||||||
|
if (process.env.UTIL_SERVER) {
|
||||||
|
utilityServerRoot = process.env.UTIL_SERVER.replace(/\/$/, '')
|
||||||
|
}
|
||||||
|
|
||||||
|
// Consent manager configuration
|
||||||
|
export default {
|
||||||
|
version: 3,
|
||||||
|
container: '#consent-manager',
|
||||||
|
companyName: 'HashiCorp',
|
||||||
|
privacyPolicyLink: '/privacy',
|
||||||
|
segmentWriteKey: segmentWriteKey,
|
||||||
|
utilServerRoot: utilityServerRoot,
|
||||||
|
segmentServices: [
|
||||||
|
{
|
||||||
|
key: 'googleanalytics',
|
||||||
|
name: 'Google Analytics',
|
||||||
|
description:
|
||||||
|
'Google Analytics is a popular service for tracking web traffic. We use this data to determine what content our users find important so that we can dedicate more resources toward it.',
|
||||||
|
category: 'Analytics',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'Hotjar',
|
||||||
|
description:
|
||||||
|
'Hotjar is a service that generates heatmaps of where users click on our sites. We use this information to ensure that our site is not confusing, and simple to use and navigate.',
|
||||||
|
category: 'Analytics',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'LinkedIn Insight Tag',
|
||||||
|
description:
|
||||||
|
'This small script allows us to see how effective our linkedin campaigns are by showing which users have clicked through to our site.',
|
||||||
|
category: 'Analytics',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'Marketo V2',
|
||||||
|
description:
|
||||||
|
'Marketo is a marketing automation tool that allows us to segment users into different categories based off of their behaviors. We use this information to provide tailored information to users in our email campaigns.',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
categories: [
|
||||||
|
{
|
||||||
|
name: 'Functional',
|
||||||
|
description:
|
||||||
|
'Functional services provide a utility to the website, such as the ability to log in, or to get live support. Disabling any of these scripts will cause that utility to be missing from the site.',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'Analytics',
|
||||||
|
description:
|
||||||
|
'Analytics services keep track of page traffic and user behavior while browsing the site. We use this data internally to improve the usability and performance of the site. Disabling any of these scripts makes it more difficult for us to understand how our site is being used, and slower to improve it.',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'Email Marketing',
|
||||||
|
description:
|
||||||
|
'Email Marketing services track user behavior while browsing the site. We use this data internally in our marketing efforts to provide users contextually relevant information based off of their behaviors. Disabling any of these scripts makes it more difficult for us to provide you contextually relevant information.',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
additionalServices: [
|
||||||
|
{
|
||||||
|
name: 'OptinMonster',
|
||||||
|
description:
|
||||||
|
"OptinMonster is a service that we use to show a prompt to sign up for our newsletter if it's perceived that you are interested in our content.",
|
||||||
|
category: 'Functional',
|
||||||
|
body: `var om598c8e3a6e43d,om598c8e3a6e43d_poll=function(){var r=0;return function(n,l){clearInterval(r),r=setInterval(n,l)}}();!function(e,t,n){if(e.getElementById(n)){om598c8e3a6e43d_poll(function(){if(window['om_loaded']){if(!om598c8e3a6e43d){om598c8e3a6e43d=new OptinMonsterApp();return om598c8e3a6e43d.init({"s":"35109.598c8e3a6e43d","staging":0,"dev":0,"beta":0});}}},25);return;}var d=false,o=e.createElement(t);o.id=n,o.src="https://a.optnmstr.com/app/js/api.min.js",o.async=true,o.onload=o.onreadystatechange=function(){if(!d){if(!this.readyState||this.readyState==="loaded"||this.readyState==="complete"){try{d=om_loaded=true;om598c8e3a6e43d=new OptinMonsterApp();om598c8e3a6e43d.init({"s":"35109.598c8e3a6e43d","staging":0,"dev":0,"beta":0});o.onload=o.onreadystatechange=null;}catch(t){}}}};(document.getElementsByTagName("head")[0]||document.documentElement).appendChild(o)}(document,"script","omapi-script");`,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
|
||||||
|
# This file sets configuration for Netlify
|
||||||
|
# ref: https://www.netlify.com/docs/netlify-toml-reference/
|
||||||
|
|
||||||
|
[build]
|
||||||
|
publish = "out"
|
||||||
|
command = "npm run static"
|
||||||
|
|
||||||
|
[context.production]
|
||||||
|
environment = { HASHI_ENV = "production", NODE_ENV = "production"}
|
||||||
|
|
||||||
|
[context.deploy-preview]
|
||||||
|
environment = { HASHI_ENV = "staging" }
|
||||||
|
|
||||||
|
[[headers]]
|
||||||
|
for = "/*"
|
||||||
|
[headers.values]
|
||||||
|
X-Frame-Options = "SAMEORIGIN"
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
const withHashicorp = require('@hashicorp/nextjs-scripts')
|
||||||
|
const path = require('path')
|
||||||
|
|
||||||
|
module.exports = withHashicorp({
|
||||||
|
defaultLayout: true,
|
||||||
|
transpileModules: ['is-absolute-url', '@hashicorp/react-mega-nav'],
|
||||||
|
mdx: { resolveIncludes: path.join(__dirname, 'pages/partials') },
|
||||||
|
})({
|
||||||
|
experimental: {
|
||||||
|
css: true,
|
||||||
|
modern: true,
|
||||||
|
rewrites: () => [
|
||||||
|
{
|
||||||
|
source: '/api/:path*',
|
||||||
|
destination: '/api-docs/:path*',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
exportTrailingSlash: true,
|
||||||
|
env: {
|
||||||
|
HASHI_ENV: process.env.HASHI_ENV,
|
||||||
|
},
|
||||||
|
})
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,72 @@
|
||||||
|
{
|
||||||
|
"name": "consul-docs",
|
||||||
|
"description": "Description of your website",
|
||||||
|
"version": "0.0.1",
|
||||||
|
"author": "HashiCorp",
|
||||||
|
"dependencies": {
|
||||||
|
"@bugsnag/js": "^6.5.2",
|
||||||
|
"@bugsnag/plugin-react": "^6.5.0",
|
||||||
|
"@hashicorp/nextjs-scripts": "^6.2.0-9",
|
||||||
|
"@hashicorp/react-alert": "^2.0.0",
|
||||||
|
"@hashicorp/react-button": "^2.1.7",
|
||||||
|
"@hashicorp/react-consent-manager": "^2.0.7",
|
||||||
|
"@hashicorp/react-content": "^3.0.0-0",
|
||||||
|
"@hashicorp/react-docs-page": "^1.0.2",
|
||||||
|
"@hashicorp/react-docs-sidenav": "^3.0.5",
|
||||||
|
"@hashicorp/react-docs-sitemap": "^1.0.0",
|
||||||
|
"@hashicorp/react-footer": "^3.1.12",
|
||||||
|
"@hashicorp/react-global-styles": "^4.1.0",
|
||||||
|
"@hashicorp/react-head": "^0.1.1",
|
||||||
|
"@hashicorp/react-hero": "^3.0.5",
|
||||||
|
"@hashicorp/react-image": "^2.0.1",
|
||||||
|
"@hashicorp/react-inline-svg": "^1.0.0",
|
||||||
|
"@hashicorp/react-mega-nav": "^4.0.1-2",
|
||||||
|
"@hashicorp/react-product-downloader": "^3.0.5",
|
||||||
|
"@hashicorp/react-section-header": "^2.0.0",
|
||||||
|
"@hashicorp/react-subnav": "^3.0.1",
|
||||||
|
"@hashicorp/react-text-and-content": "^4.0.7",
|
||||||
|
"@hashicorp/react-text-split": "^0.2.4",
|
||||||
|
"@hashicorp/react-text-split-with-code": "0.0.7",
|
||||||
|
"@hashicorp/react-text-split-with-image": "^1.2.4",
|
||||||
|
"@hashicorp/react-vertical-text-block-list": "^2.0.1",
|
||||||
|
"babel-plugin-import-glob-array": "^0.2.0",
|
||||||
|
"highlight.js": "^9.18.1",
|
||||||
|
"imagemin-mozjpeg": "^8.0.0",
|
||||||
|
"imagemin-optipng": "^7.1.0",
|
||||||
|
"imagemin-svgo": "^7.1.0",
|
||||||
|
"isomorphic-unfetch": "^3.0.0",
|
||||||
|
"marked": "^0.7.0",
|
||||||
|
"next": "9.3.4",
|
||||||
|
"nprogress": "^0.2.0",
|
||||||
|
"nuka-carousel": "^4.6.6",
|
||||||
|
"react": "^16.13.1",
|
||||||
|
"react-device-detect": "^1.11.14",
|
||||||
|
"react-dom": "^16.13.1",
|
||||||
|
"slugify": "^1.4.0",
|
||||||
|
"stringify-object": "^3.3.0"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"dart-linkcheck": "^2.0.15",
|
||||||
|
"glob": "^7.1.6",
|
||||||
|
"husky": "^4.2.3",
|
||||||
|
"inquirer": "^7.1.0",
|
||||||
|
"prettier": "^2.0.2"
|
||||||
|
},
|
||||||
|
"husky": {
|
||||||
|
"hooks": {
|
||||||
|
"pre-commit": "next-hashicorp precommit"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"main": "index.js",
|
||||||
|
"scripts": {
|
||||||
|
"build": "node --max-old-space-size=2048 ./node_modules/.bin/next build",
|
||||||
|
"dynamic": "NODE_ENV=production next build && next start",
|
||||||
|
"export": "node --max-old-space-size=2048 ./node_modules/.bin/next export",
|
||||||
|
"format": "next-hashicorp format",
|
||||||
|
"generate:component": "next-hashicorp generate component",
|
||||||
|
"lint": "next-hashicorp lint",
|
||||||
|
"start": "rm -rf .next/cache/next-babel-loader/ && next dev",
|
||||||
|
"static": "npm run build && npm run export && cp _redirects out/.",
|
||||||
|
"linkcheck": "linkcheck https://consul.io"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,87 @@
|
||||||
|
import './style.css'
|
||||||
|
import App from 'next/app'
|
||||||
|
import NProgress from 'nprogress'
|
||||||
|
import Router from 'next/router'
|
||||||
|
import ProductSubnav from '../components/subnav'
|
||||||
|
import MegaNav from '@hashicorp/react-mega-nav'
|
||||||
|
import Footer from '../components/footer'
|
||||||
|
import { ConsentManager, open } from '@hashicorp/react-consent-manager'
|
||||||
|
import consentManagerConfig from '../lib/consent-manager-config'
|
||||||
|
import bugsnagClient from '../lib/bugsnag'
|
||||||
|
import Error from './_error'
|
||||||
|
import Head from 'next/head'
|
||||||
|
import HashiHead from '@hashicorp/react-head'
|
||||||
|
|
||||||
|
Router.events.on('routeChangeStart', NProgress.start)
|
||||||
|
Router.events.on('routeChangeError', NProgress.done)
|
||||||
|
Router.events.on('routeChangeComplete', (url) => {
|
||||||
|
setTimeout(() => window.analytics.page(url), 0)
|
||||||
|
NProgress.done()
|
||||||
|
})
|
||||||
|
|
||||||
|
// Bugsnag
|
||||||
|
const ErrorBoundary = bugsnagClient.getPlugin('react')
|
||||||
|
|
||||||
|
class NextApp extends App {
|
||||||
|
static async getInitialProps({ Component, ctx }) {
|
||||||
|
let pageProps = {}
|
||||||
|
|
||||||
|
if (Component.getInitialProps) {
|
||||||
|
pageProps = await Component.getInitialProps(ctx)
|
||||||
|
} else if (Component.isMDXComponent) {
|
||||||
|
// fix for https://github.com/mdx-js/mdx/issues/382
|
||||||
|
const mdxLayoutComponent = Component({}).props.originalType
|
||||||
|
if (mdxLayoutComponent.getInitialProps) {
|
||||||
|
pageProps = await mdxLayoutComponent.getInitialProps(ctx)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return { pageProps }
|
||||||
|
}
|
||||||
|
|
||||||
|
render() {
|
||||||
|
const { Component, pageProps } = this.props
|
||||||
|
|
||||||
|
return (
|
||||||
|
<ErrorBoundary FallbackComponent={Error}>
|
||||||
|
<HashiHead
|
||||||
|
is={Head}
|
||||||
|
title="Consul by HashiCorp"
|
||||||
|
siteName="Consul by HashiCorp"
|
||||||
|
description="Consul is a free and open source tool for creating golden images for multiple
|
||||||
|
platforms from a single source configuration."
|
||||||
|
image="https://www.consul.io/img/og-image.png"
|
||||||
|
stylesheet={[
|
||||||
|
{ href: '/css/nprogress.css' },
|
||||||
|
{
|
||||||
|
href:
|
||||||
|
'https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700&display=swap',
|
||||||
|
},
|
||||||
|
]}
|
||||||
|
icon={[{ href: '/favicon.ico' }]}
|
||||||
|
preload={[
|
||||||
|
{ href: '/fonts/klavika/medium.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/gilmer/light.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/gilmer/regular.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/gilmer/medium.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/gilmer/bold.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/metro-sans/book.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/metro-sans/regular.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/metro-sans/semi-bold.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/metro-sans/bold.woff2', as: 'font' },
|
||||||
|
{ href: '/fonts/dejavu/mono.woff2', as: 'font' },
|
||||||
|
]}
|
||||||
|
/>
|
||||||
|
<MegaNav product="Consul" />
|
||||||
|
<ProductSubnav />
|
||||||
|
<div className="content">
|
||||||
|
<Component {...pageProps} />
|
||||||
|
</div>
|
||||||
|
<Footer openConsentManager={open} />
|
||||||
|
<ConsentManager {...consentManagerConfig} />
|
||||||
|
</ErrorBoundary>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export default NextApp
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
import Document, { Head, Main, NextScript } from 'next/document'
|
||||||
|
import HashiHead from '@hashicorp/react-head'
|
||||||
|
|
||||||
|
export default class MyDocument extends Document {
|
||||||
|
static async getInitialProps(ctx) {
|
||||||
|
const initialProps = await Document.getInitialProps(ctx)
|
||||||
|
return { ...initialProps }
|
||||||
|
}
|
||||||
|
|
||||||
|
render() {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<HashiHead is={Head} />
|
||||||
|
<body>
|
||||||
|
<Main />
|
||||||
|
<NextScript />
|
||||||
|
<script
|
||||||
|
noModule
|
||||||
|
dangerouslySetInnerHTML={{
|
||||||
|
__html: `window.MSInputMethodContext && document.documentMode && document.write('<script src="/ie-custom-properties.js"><\\x2fscript>');`,
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,13 @@
|
||||||
|
import React from 'react'
|
||||||
|
import ErrorPage from 'next/error'
|
||||||
|
import bugsnagClient from '../lib/bugsnag'
|
||||||
|
|
||||||
|
export default class Page extends React.Component {
|
||||||
|
static async getInitialProps(ctx) {
|
||||||
|
if (ctx.err) bugsnagClient.notify(ctx.err)
|
||||||
|
return ErrorPage.getInitialProps(ctx)
|
||||||
|
}
|
||||||
|
render() {
|
||||||
|
return <ErrorPage statusCode={this.props.statusCode || '¯\\_(ツ)_/¯'} />
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -12,7 +12,7 @@ the new ACL [Token](/docs/api/acl-token.html) and [Policy](/docs/api/acl-policy.
|
||||||
|
|
||||||
# ACL HTTP API
|
# ACL HTTP API
|
||||||
|
|
||||||
These `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. For more information about ACLs, please see the
|
These `/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).
|
[ACL Guide](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
||||||
|
|
||||||
## Bootstrap ACLs
|
## Bootstrap ACLs
|
||||||
|
|
@ -26,9 +26,9 @@ Consul servers to be upgraded in order to operate.
|
||||||
This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
|
This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
|
||||||
configuration files.
|
configuration files.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `PUT` | `/acl/bootstrap` | `application/json` |
|
| `PUT` | `/acl/bootstrap` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -62,16 +62,16 @@ a 403 means that the cluster has already been bootstrapped, at which point you s
|
||||||
consider the cluster in a potentially compromised state.
|
consider the cluster in a potentially compromised state.
|
||||||
|
|
||||||
The returned token will be a management token which can be used to further configure the
|
The returned token will be a management token which can be used to further configure the
|
||||||
ACL system. Please see the
|
ACL system. Please see the
|
||||||
[ACL Guide](https://learn.hashicorp.com/consul/security-networking/production-acls) for more details.
|
[ACL Guide](https://learn.hashicorp.com/consul/security-networking/production-acls) for more details.
|
||||||
|
|
||||||
## Create ACL Token
|
## Create ACL Token
|
||||||
|
|
||||||
This endpoint makes a new ACL token.
|
This endpoint makes a new ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `PUT` | `/acl/create` | `application/json` |
|
| `PUT` | `/acl/create` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -128,9 +128,9 @@ $ curl \
|
||||||
This endpoint is used to modify the policy for a given ACL token. Instead of
|
This endpoint is used to modify the policy for a given ACL token. Instead of
|
||||||
generating a new token ID, the `ID` field must be provided.
|
generating a new token ID, the `ID` field must be provided.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `PUT` | `/acl/update` | `application/json` |
|
| `PUT` | `/acl/update` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -154,7 +154,7 @@ required.
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||||
"Name": "my-app-token-updated",
|
"Name": "my-app-token-updated",
|
||||||
"Type": "client",
|
"Type": "client",
|
||||||
"Rules": "# New Rules",
|
"Rules": "# New Rules"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -179,9 +179,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint deletes an ACL token with the given ID.
|
This endpoint deletes an ACL token with the given ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------- | ------------------ |
|
||||||
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
|
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded.
|
Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded.
|
||||||
|
|
||||||
|
|
@ -214,14 +214,13 @@ $ curl \
|
||||||
true
|
true
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Read ACL Token
|
## Read ACL Token
|
||||||
|
|
||||||
This endpoint reads an ACL token with the given ID.
|
This endpoint reads an ACL token with the given ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `GET` | `/acl/info/:uuid` | `application/json` |
|
| `GET` | `/acl/info/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -268,9 +267,9 @@ This endpoint clones an ACL and returns a new token `ID`. This allows a token to
|
||||||
serve as a template for others, making it simple to generate new tokens without
|
serve as a template for others, making it simple to generate new tokens without
|
||||||
complex rule management.
|
complex rule management.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -307,9 +306,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint lists all the active ACL tokens.
|
This endpoint lists all the active ACL tokens.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------- | ------------------ |
|
||||||
| `GET` | `/acl/list` | `application/json` |
|
| `GET` | `/acl/list` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -349,12 +348,12 @@ This endpoint returns the status of the ACL replication process in the
|
||||||
datacenter. This is intended to be used by operators, or by automation checking
|
datacenter. This is intended to be used by operators, or by automation checking
|
||||||
the health of ACL replication.
|
the health of ACL replication.
|
||||||
|
|
||||||
Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-operations/acl-replication) for more details.
|
Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-operations/acl-replication) for more details.
|
||||||
for more details.
|
for more details.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `GET` | `/acl/replication` | `application/json` |
|
| `GET` | `/acl/replication` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -6,7 +6,7 @@ description: |-
|
||||||
The /acl endpoints manage the Consul's ACL system.
|
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)
|
-> **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
|
# ACL HTTP API
|
||||||
|
|
||||||
|
|
@ -26,9 +26,9 @@ and requires all Consul servers to be upgraded in order to operate.
|
||||||
This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
|
This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
|
||||||
configuration files.
|
configuration files.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `PUT` | `/acl/bootstrap` | `application/json` |
|
| `PUT` | `/acl/bootstrap` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -55,21 +55,21 @@ applications should ignore the `ID` field as it may be removed in a future major
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
|
"ID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
|
||||||
"AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3",
|
"AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3",
|
||||||
"SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
|
"SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
|
||||||
"Description": "Bootstrap Token (Global Management)",
|
"Description": "Bootstrap Token (Global Management)",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "00000000-0000-0000-0000-000000000001",
|
"ID": "00000000-0000-0000-0000-000000000001",
|
||||||
"Name": "global-management"
|
"Name": "global-management"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T10:34:20.843397-04:00",
|
"CreateTime": "2018-10-24T10:34:20.843397-04:00",
|
||||||
"Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
|
"Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
|
||||||
"CreateIndex": 12,
|
"CreateIndex": 12,
|
||||||
"ModifyIndex": 12
|
"ModifyIndex": 12
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -85,15 +85,15 @@ It can then be used to further configure the ACL system. Please see the
|
||||||
## Check ACL Replication
|
## Check ACL Replication
|
||||||
|
|
||||||
This endpoint returns the status of the ACL replication processes in the
|
This endpoint returns the status of the ACL replication processes in the
|
||||||
datacenter. This is intended to be used by operators or by automation checking
|
datacenter. This is intended to be used by operators or by automation checking
|
||||||
to discover the health of ACL replication.
|
to discover the health of ACL replication.
|
||||||
|
|
||||||
Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-operations/acl-replication)
|
Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-operations/acl-replication)
|
||||||
for more details.
|
for more details.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `GET` | `/acl/replication` | `application/json` |
|
| `GET` | `/acl/replication` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -126,7 +126,7 @@ $ curl \
|
||||||
"Enabled": true,
|
"Enabled": true,
|
||||||
"Running": true,
|
"Running": true,
|
||||||
"SourceDatacenter": "dc1",
|
"SourceDatacenter": "dc1",
|
||||||
"ReplicationType" : "tokens",
|
"ReplicationType": "tokens",
|
||||||
"ReplicatedIndex": 1976,
|
"ReplicatedIndex": 1976,
|
||||||
"ReplicatedTokenIndex": 2018,
|
"ReplicatedTokenIndex": 2018,
|
||||||
"LastSuccess": "2018-11-03T06:28:58Z",
|
"LastSuccess": "2018-11-03T06:28:58Z",
|
||||||
|
|
@ -146,12 +146,12 @@ $ curl \
|
||||||
|
|
||||||
- `ReplicationType` - The type of replication that is currently in use.
|
- `ReplicationType` - The type of replication that is currently in use.
|
||||||
|
|
||||||
- `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens.
|
- `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens.
|
||||||
|
|
||||||
- `policies` - ACL replication is only replicating policies as token replication
|
- `policies` - ACL replication is only replicating policies as token replication
|
||||||
is disabled.
|
is disabled.
|
||||||
|
|
||||||
- `tokens` - ACL replication is replicating both policies and tokens.
|
- `tokens` - ACL replication is replicating both policies and tokens.
|
||||||
|
|
||||||
- `ReplicatedIndex` - The last index that was successfully replicated. Which data
|
- `ReplicatedIndex` - The last index that was successfully replicated. Which data
|
||||||
the replicated index refers to depends on the replication type. For `legacy`
|
the replicated index refers to depends on the replication type. For `legacy`
|
||||||
|
|
@ -165,11 +165,11 @@ $ curl \
|
||||||
the primary datacenter.
|
the primary datacenter.
|
||||||
|
|
||||||
- `ReplicatedTokenIndex` - The last token index that was successfully replicated.
|
- `ReplicatedTokenIndex` - The last token index that was successfully replicated.
|
||||||
This index can be compared with the value of the `X-Consul-Index` header returned
|
This index can be compared with the value of the `X-Consul-Index` header returned
|
||||||
by the [`/v1/acl/tokens`](/api/acl/tokens.html#list) endpoint to determine
|
by the [`/v1/acl/tokens`](/api/acl/tokens.html#list) endpoint to determine
|
||||||
if the replication process has gotten all available ACL tokens. Note that ACL
|
if the replication process has gotten all available ACL tokens. Note that ACL
|
||||||
replication is rate limited so the indexes may lag behind the primary
|
replication is rate limited so the indexes may lag behind the primary
|
||||||
datacenter.
|
datacenter.
|
||||||
|
|
||||||
- `LastSuccess` - The UTC time of the last successful sync operation. Since ACL
|
- `LastSuccess` - The UTC time of the last successful sync operation. Since ACL
|
||||||
replication is done with a blocking query, this may not update for up to 5
|
replication is done with a blocking query, this may not update for up to 5
|
||||||
|
|
@ -190,9 +190,9 @@ This endpoint translates the legacy rule syntax into the latest syntax. It is in
|
||||||
to be used by operators managing Consul's ACLs and performing legacy token to new policy
|
to be used by operators managing Consul's ACLs and performing legacy token to new policy
|
||||||
migrations.
|
migrations.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | --------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------ |
|
||||||
| `POST` | `/acl/rules/translate` | `text/plain` |
|
| `POST` | `/acl/rules/translate` | `text/plain` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -215,7 +215,7 @@ agent "" {
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
||||||
```text
|
```text
|
||||||
$ curl -X POST -d @rules.hcl http://127.0.0.1:8500/v1/acl/rules/translate
|
$ curl -X POST -d @rules.hcl http://127.0.0.1:8500/v1/acl/rules/translate
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
@ -237,9 +237,9 @@ legacy token to new policy migrations. Note that this API requires the auto-gene
|
||||||
Accessor ID of the legacy token. This ID can be retrieved using the
|
Accessor ID of the legacy token. This ID can be retrieved using the
|
||||||
[`/v1/acl/token/self`](/api/acl/tokens.html#self) endpoint.
|
[`/v1/acl/token/self`](/api/acl/tokens.html#self) endpoint.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ----------------------------------- | -------------------------- |
|
| ------ | ----------------------------------- | ------------ |
|
||||||
| `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` |
|
| `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -271,9 +271,9 @@ This endpoint was added in Consul 1.5.0 and is used to exchange an [auth
|
||||||
method](/docs/acl/acl-auth-methods.html) bearer token for a newly-created
|
method](/docs/acl/acl-auth-methods.html) bearer token for a newly-created
|
||||||
Consul ACL token.
|
Consul ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------ | ------------------ |
|
||||||
| `POST` | `/acl/login` | `application/json` |
|
| `POST` | `/acl/login` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -292,7 +292,6 @@ enabled. Login requires the ability to create local tokens which is restricted
|
||||||
to the primary datacenter and any secondary datacenters with ACL token
|
to the primary datacenter and any secondary datacenters with ACL token
|
||||||
replication enabled.
|
replication enabled.
|
||||||
|
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login.
|
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login.
|
||||||
|
|
@ -304,19 +303,19 @@ replication enabled.
|
||||||
|
|
||||||
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
|
||||||
linked to the token. Can be useful to track origins.
|
linked to the token. Can be useful to track origins.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||||
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token, or will default to the `default` namespace. Added in Consul 1.7.0.
|
token, or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AuthMethod": "minikube",
|
"AuthMethod": "minikube",
|
||||||
"BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
"BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -333,26 +332,26 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
|
"AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
|
||||||
"SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
|
"SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
|
||||||
"Description": "token created via login",
|
"Description": "token created via login",
|
||||||
"Roles": [
|
"Roles": [
|
||||||
{
|
{
|
||||||
"ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
|
"ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
|
||||||
"Name": "demo"
|
"Name": "demo"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "example"
|
"ServiceName": "example"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": true,
|
"Local": true,
|
||||||
"AuthMethod": "minikube",
|
"AuthMethod": "minikube",
|
||||||
"CreateTime": "2019-04-29T10:08:08.404370762-05:00",
|
"CreateTime": "2019-04-29T10:08:08.404370762-05:00",
|
||||||
"Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
|
"Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
|
||||||
"CreateIndex": 36,
|
"CreateIndex": 36,
|
||||||
"ModifyIndex": 36
|
"ModifyIndex": 36
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -362,9 +361,9 @@ This endpoint was added in Consul 1.5.0 and is used to destroy a token created
|
||||||
via the [login endpoint](#login-to-auth-method). The token deleted is specified
|
via the [login endpoint](#login-to-auth-method). The token deleted is specified
|
||||||
with the `X-Consul-Token` header or the `token` query parameter.
|
with the `X-Consul-Token` header or the `token` query parameter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `POST` | `/acl/logout` | `application/json` |
|
| `POST` | `/acl/logout` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -6,7 +6,7 @@ description: |-
|
||||||
The /acl/auth-method endpoints manage Consul's ACL Auth Methods.
|
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.
|
-> **1.5.0+:** The auth method APIs are available in Consul versions 1.5.0 and newer.
|
||||||
|
|
||||||
# ACL Auth Method HTTP API
|
# ACL Auth Method HTTP API
|
||||||
|
|
||||||
|
|
@ -22,9 +22,9 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
||||||
|
|
||||||
This endpoint creates a new ACL auth method.
|
This endpoint creates a new ACL auth method.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `PUT` | `/acl/auth-method` | `application/json` |
|
| `PUT` | `/acl/auth-method` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -39,9 +39,8 @@ The table below shows this endpoint's support for
|
||||||
### Payload Fields
|
### Payload Fields
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The
|
- `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The
|
||||||
name can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
name can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
||||||
This field is immutable and must be unique.
|
This field is immutable and must be unique.
|
||||||
|
|
||||||
- `Type` `(string: <required>)` - The type of auth method being configured.
|
- `Type` `(string: <required>)` - The type of auth method being configured.
|
||||||
The only allowed value in Consul 1.5.0 is `"kubernetes"`. This field is
|
The only allowed value in Consul 1.5.0 is `"kubernetes"`. This field is
|
||||||
immutable.
|
immutable.
|
||||||
|
|
@ -53,25 +52,25 @@ The table below shows this endpoint's support for
|
||||||
the chosen auth method. Contents will vary depending upon the type chosen.
|
the chosen auth method. Contents will vary depending upon the type chosen.
|
||||||
For more information on configuring specific auth method types, see the [auth
|
For more information on configuring specific auth method types, see the [auth
|
||||||
method documentation](/docs/acl/acl-auth-methods.html).
|
method documentation](/docs/acl/acl-auth-methods.html).
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||||
create the auth method within. If not provided in the JSON body, the value of
|
create the auth method within. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "minikube",
|
"Name": "minikube",
|
||||||
"Type": "kubernetes",
|
"Type": "kubernetes",
|
||||||
"Description": "dev minikube cluster",
|
"Description": "dev minikube cluster",
|
||||||
"Config": {
|
"Config": {
|
||||||
"Host": "https://192.0.2.42:8443",
|
"Host": "https://192.0.2.42:8443",
|
||||||
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
||||||
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -87,16 +86,16 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "minikube",
|
"Name": "minikube",
|
||||||
"Type": "kubernetes",
|
"Type": "kubernetes",
|
||||||
"Description": "dev minikube cluster",
|
"Description": "dev minikube cluster",
|
||||||
"Config": {
|
"Config": {
|
||||||
"Host": "https://192.0.2.42:8443",
|
"Host": "https://192.0.2.42:8443",
|
||||||
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
||||||
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
||||||
},
|
},
|
||||||
"CreateIndex": 15,
|
"CreateIndex": 15,
|
||||||
"ModifyIndex": 15
|
"ModifyIndex": 15
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -106,9 +105,9 @@ This endpoint reads an ACL auth method with the given name. If no
|
||||||
auth method exists with the given name, a 404 is returned instead of a
|
auth method exists with the given name, a 404 is returned instead of a
|
||||||
200 response.
|
200 response.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------ | ------------------ |
|
||||||
| `GET` | `/acl/auth-method/:name` | `application/json` |
|
| `GET` | `/acl/auth-method/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -124,9 +123,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
|
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
|
||||||
read. This is required and is specified as part of the URL path.
|
read. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||||
the auth method within. This value can be specified as the `ns` URL query
|
the auth method within. This value can be specified as the `ns` URL query
|
||||||
parameter or in the `X-Consul-Namespace` header. If not provided by either,
|
parameter or in the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
@ -141,16 +140,16 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "minikube",
|
"Name": "minikube",
|
||||||
"Type": "kubernetes",
|
"Type": "kubernetes",
|
||||||
"Description": "dev minikube cluster",
|
"Description": "dev minikube cluster",
|
||||||
"Config": {
|
"Config": {
|
||||||
"Host": "https://192.0.2.42:8443",
|
"Host": "https://192.0.2.42:8443",
|
||||||
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
||||||
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
||||||
},
|
},
|
||||||
"CreateIndex": 15,
|
"CreateIndex": 15,
|
||||||
"ModifyIndex": 224
|
"ModifyIndex": 224
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -158,9 +157,9 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube
|
||||||
|
|
||||||
This endpoint updates an existing ACL auth method.
|
This endpoint updates an existing ACL auth method.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------ | ------------------ |
|
||||||
| `PUT` | `/acl/auth-method/:name` | `application/json` |
|
| `PUT` | `/acl/auth-method/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -179,7 +178,7 @@ The table below shows this endpoint's support for
|
||||||
JSON body. If specified in both places then they must match exactly.
|
JSON body. If specified in both places then they must match exactly.
|
||||||
|
|
||||||
- `Type` `(string: <required>)` - Specifies the type of the auth method being
|
- `Type` `(string: <required>)` - Specifies the type of the auth method being
|
||||||
updated. This field is immutable so if present in the body then it must
|
updated. This field is immutable so if present in the body then it must
|
||||||
match the existing value. If not present then the value will be filled in by
|
match the existing value. If not present then the value will be filled in by
|
||||||
Consul.
|
Consul.
|
||||||
|
|
||||||
|
|
@ -190,24 +189,24 @@ The table below shows this endpoint's support for
|
||||||
the chosen auth method. Contents will vary depending upon the type chosen.
|
the chosen auth method. Contents will vary depending upon the type chosen.
|
||||||
For more information on configuring specific auth method types, see the [auth
|
For more information on configuring specific auth method types, see the [auth
|
||||||
method documentation](/docs/acl/acl-auth-methods.html).
|
method documentation](/docs/acl/acl-auth-methods.html).
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||||
the auth method to update. If not provided in the JSON body, the value of
|
the auth method to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "minikube",
|
"Name": "minikube",
|
||||||
"Description": "updated name",
|
"Description": "updated name",
|
||||||
"Config": {
|
"Config": {
|
||||||
"Host": "https://192.0.2.42:8443",
|
"Host": "https://192.0.2.42:8443",
|
||||||
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
||||||
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -223,16 +222,16 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "minikube",
|
"Name": "minikube",
|
||||||
"Description": "updated name",
|
"Description": "updated name",
|
||||||
"Type": "kubernetes",
|
"Type": "kubernetes",
|
||||||
"Config": {
|
"Config": {
|
||||||
"Host": "https://192.0.2.42:8443",
|
"Host": "https://192.0.2.42:8443",
|
||||||
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
||||||
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
||||||
},
|
},
|
||||||
"CreateIndex": 15,
|
"CreateIndex": 15,
|
||||||
"ModifyIndex": 224
|
"ModifyIndex": 224
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -244,9 +243,9 @@ This endpoint deletes an ACL auth method.
|
||||||
[binding rules](/api/acl/binding-rules.html) as well as any
|
[binding rules](/api/acl/binding-rules.html) as well as any
|
||||||
outstanding [tokens](/api/acl/tokens.html) created from this auth method.
|
outstanding [tokens](/api/acl/tokens.html) created from this auth method.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ------------------------- | -------------------------- |
|
| -------- | ------------------------ | ------------------ |
|
||||||
| `DELETE` | `/acl/auth-method/:name` | `application/json` |
|
| `DELETE` | `/acl/auth-method/:name` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or
|
Even though the return type is application/json, the value is either true or
|
||||||
false indicating whether the delete succeeded.
|
false indicating whether the delete succeeded.
|
||||||
|
|
@ -265,9 +264,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
|
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
|
||||||
delete. This is required and is specified as part of the URL path.
|
delete. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
||||||
Auth Method to delete. This value can be specified as the `ns` URL query
|
Auth Method to delete. This value can be specified as the `ns` URL query
|
||||||
parameter or in the `X-Consul-Namespace` header. If not provided by either,
|
parameter or in the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
@ -289,9 +288,9 @@ true
|
||||||
|
|
||||||
This endpoint lists all the ACL auth methods.
|
This endpoint lists all the ACL auth methods.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `GET` | `/acl/auth-methods` | `application/json` |
|
| `GET` | `/acl/auth-methods` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -306,13 +305,12 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
||||||
the auth methods for. This value can be specified as the `ns` URL query
|
the auth methods for. This value can be specified as the `ns` URL query
|
||||||
parameter or in the `X-Consul-Namespace` header. If not provided by either,
|
parameter or in the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. The namespace may be specified as '*' and then
|
to the `default` namespace. The namespace may be specified as '\*' and then
|
||||||
results will be returned for all namespaces. Added in Consul 1.7.0.
|
results will be returned for all namespaces. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
||||||
## Sample Request
|
## Sample Request
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
|
@ -326,19 +324,19 @@ listing and must be retrieved by the [auth method reading endpoint](#read-an-aut
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"Name": "minikube-1",
|
"Name": "minikube-1",
|
||||||
"Type": "kubernetes",
|
"Type": "kubernetes",
|
||||||
"Description": "",
|
"Description": "",
|
||||||
"CreateIndex": 14,
|
"CreateIndex": 14,
|
||||||
"ModifyIndex": 14
|
"ModifyIndex": 14
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "minikube-2",
|
"Name": "minikube-2",
|
||||||
"Type": "kubernetes",
|
"Type": "kubernetes",
|
||||||
"Description": "",
|
"Description": "",
|
||||||
"CreateIndex": 15,
|
"CreateIndex": 15,
|
||||||
"ModifyIndex": 15
|
"ModifyIndex": 15
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
@ -12,7 +12,7 @@ description: |-
|
||||||
|
|
||||||
The `/acl/binding-rule` endpoints [create](#create-a-binding-rule),
|
The `/acl/binding-rule` endpoints [create](#create-a-binding-rule),
|
||||||
[read](#read-a-binding-rule), [update](#update-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
|
[list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding
|
||||||
rules in Consul.
|
rules in Consul.
|
||||||
|
|
||||||
For more information on how to setup ACLs, please see
|
For more information on how to setup ACLs, please see
|
||||||
|
|
@ -22,9 +22,9 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
||||||
|
|
||||||
This endpoint creates a new ACL binding rule.
|
This endpoint creates a new ACL binding rule.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `PUT` | `/acl/binding-rule` | `application/json` |
|
| `PUT` | `/acl/binding-rule` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -45,15 +45,15 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `Selector` `(string: "")` - Specifies the expression used to match this rule
|
- `Selector` `(string: "")` - Specifies the expression used to match this rule
|
||||||
against valid identities returned from an auth method validation. If empty
|
against valid identities returned from an auth method validation. If empty
|
||||||
this binding rule matches all valid identities returned from the auth method. For example:
|
this binding rule matches all valid identities returned from the auth method. For example:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
serviceaccount.namespace==default and serviceaccount.name!=vault
|
serviceaccount.namespace==default and serviceaccount.name!=vault
|
||||||
```
|
```
|
||||||
|
|
||||||
- `BindType` `(string: <required>)` - Specifies the way the binding rule
|
- `BindType` `(string: <required>)` - Specifies the way the binding rule
|
||||||
affects a token created at login.
|
affects a token created at login.
|
||||||
|
|
||||||
- `BindType=service` - The computed bind name value is used as an
|
- `BindType=service` - The computed bind name value is used as an
|
||||||
`ACLServiceIdentity.ServiceName` field in the token that is created.
|
`ACLServiceIdentity.ServiceName` field in the token that is created.
|
||||||
|
|
||||||
|
|
@ -79,30 +79,30 @@ The table below shows this endpoint's support for
|
||||||
```
|
```
|
||||||
|
|
||||||
- `BindName` `(string: <required>)` - The name to bind to a token at
|
- `BindName` `(string: <required>)` - The name to bind to a token at
|
||||||
login-time. What it binds to can be adjusted with different values of the
|
login-time. What it binds to can be adjusted with different values of the
|
||||||
`BindType` field. This can either be a plain string or lightly templated
|
`BindType` field. This can either be a plain string or lightly templated
|
||||||
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same
|
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same
|
||||||
values that are usable by the `Selector` syntax. For example:
|
values that are usable by the `Selector` syntax. For example:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
prefixed-${serviceaccount.name}
|
prefixed-${serviceaccount.name}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||||
create the binding rule. If not provided in the JSON body, the value of
|
create the binding rule. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Description": "example rule",
|
"Description": "example rule",
|
||||||
"AuthMethod": "minikube",
|
"AuthMethod": "minikube",
|
||||||
"Selector": "serviceaccount.namespace==default",
|
"Selector": "serviceaccount.namespace==default",
|
||||||
"BindType": "service",
|
"BindType": "service",
|
||||||
"BindName": "{{ serviceaccount.name }}"
|
"BindName": "{{ serviceaccount.name }}"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -118,14 +118,14 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
||||||
"Description": "example rule",
|
"Description": "example rule",
|
||||||
"AuthMethod": "minikube",
|
"AuthMethod": "minikube",
|
||||||
"Selector": "serviceaccount.namespace==default",
|
"Selector": "serviceaccount.namespace==default",
|
||||||
"BindType": "service",
|
"BindType": "service",
|
||||||
"BindName": "{{ serviceaccount.name }}",
|
"BindName": "{{ serviceaccount.name }}",
|
||||||
"CreateIndex": 17,
|
"CreateIndex": 17,
|
||||||
"ModifyIndex": 17
|
"ModifyIndex": 17
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -135,9 +135,9 @@ This endpoint reads an ACL binding rule with the given ID. If no
|
||||||
binding rule exists with the given ID, a 404 is returned instead of a 200
|
binding rule exists with the given ID, a 404 is returned instead of a 200
|
||||||
response.
|
response.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------------- | ------------------ |
|
||||||
| `GET` | `/acl/binding-rule/:id` | `application/json` |
|
| `GET` | `/acl/binding-rule/:id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -153,14 +153,13 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule
|
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule
|
||||||
to read. This is required and is specified as part of the URL path.
|
to read. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||||
the binding rule. This value can be specified as the `ns` URL query
|
the binding rule. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
|
@ -171,14 +170,14 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
||||||
"Description": "example rule",
|
"Description": "example rule",
|
||||||
"AuthMethod": "minikube",
|
"AuthMethod": "minikube",
|
||||||
"Selector": "serviceaccount.namespace==default",
|
"Selector": "serviceaccount.namespace==default",
|
||||||
"BindType": "service",
|
"BindType": "service",
|
||||||
"BindName": "{{ serviceaccount.name }}",
|
"BindName": "{{ serviceaccount.name }}",
|
||||||
"CreateIndex": 17,
|
"CreateIndex": 17,
|
||||||
"ModifyIndex": 17
|
"ModifyIndex": 17
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -186,9 +185,9 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-
|
||||||
|
|
||||||
This endpoint updates an existing ACL binding rule.
|
This endpoint updates an existing ACL binding rule.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------------- | ------------------ |
|
||||||
| `PUT` | `/acl/binding-rule/:id` | `application/json` |
|
| `PUT` | `/acl/binding-rule/:id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -215,15 +214,15 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `Selector` `(string: "")` - Specifies the expression used to match this rule
|
- `Selector` `(string: "")` - Specifies the expression used to match this rule
|
||||||
against valid identities returned from an auth method validation. If empty
|
against valid identities returned from an auth method validation. If empty
|
||||||
this binding rule matches all valid identities returned from the auth method. For example:
|
this binding rule matches all valid identities returned from the auth method. For example:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
serviceaccount.namespace==default and serviceaccount.name!=vault
|
serviceaccount.namespace==default and serviceaccount.name!=vault
|
||||||
```
|
```
|
||||||
|
|
||||||
- `BindType` `(string: <required>)` - Specifies the way the binding rule
|
- `BindType` `(string: <required>)` - Specifies the way the binding rule
|
||||||
affects a token created at login.
|
affects a token created at login.
|
||||||
|
|
||||||
- `BindType=service` - The computed bind name value is used as an
|
- `BindType=service` - The computed bind name value is used as an
|
||||||
`ACLServiceIdentity.ServiceName` field in the token that is created.
|
`ACLServiceIdentity.ServiceName` field in the token that is created.
|
||||||
|
|
||||||
|
|
@ -249,29 +248,29 @@ The table below shows this endpoint's support for
|
||||||
```
|
```
|
||||||
|
|
||||||
- `BindName` `(string: <required>)` - The name to bind to a token at
|
- `BindName` `(string: <required>)` - The name to bind to a token at
|
||||||
login-time. What it binds to can be adjusted with different values of the
|
login-time. What it binds to can be adjusted with different values of the
|
||||||
`BindType` field. This can either be a plain string or lightly templated
|
`BindType` field. This can either be a plain string or lightly templated
|
||||||
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same
|
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same
|
||||||
values that are usable by the `Selector` syntax. For example:
|
values that are usable by the `Selector` syntax. For example:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
prefixed-${serviceaccount.name}
|
prefixed-${serviceaccount.name}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||||
the binding rule to update. If not provided in the JSON body, the value of
|
the binding rule to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Description": "updated rule",
|
"Description": "updated rule",
|
||||||
"Selector": "serviceaccount.namespace=dev",
|
"Selector": "serviceaccount.namespace=dev",
|
||||||
"BindType": "role",
|
"BindType": "role",
|
||||||
"BindName": "{{ serviceaccount.name }}"
|
"BindName": "{{ serviceaccount.name }}"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -287,14 +286,14 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
||||||
"Description": "updated rule",
|
"Description": "updated rule",
|
||||||
"AuthMethod": "minikube",
|
"AuthMethod": "minikube",
|
||||||
"Selector": "serviceaccount.namespace=dev",
|
"Selector": "serviceaccount.namespace=dev",
|
||||||
"BindType": "role",
|
"BindType": "role",
|
||||||
"BindName": "{{ serviceaccount.name }}",
|
"BindName": "{{ serviceaccount.name }}",
|
||||||
"CreateIndex": 17,
|
"CreateIndex": 17,
|
||||||
"ModifyIndex": 18
|
"ModifyIndex": 18
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -302,9 +301,9 @@ $ curl -X PUT \
|
||||||
|
|
||||||
This endpoint deletes an ACL binding rule.
|
This endpoint deletes an ACL binding rule.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ------------------------- | -------------------------- |
|
| -------- | ----------------------- | ------------------ |
|
||||||
| `DELETE` | `/acl/binding-rule/:id` | `application/json` |
|
| `DELETE` | `/acl/binding-rule/:id` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or
|
Even though the return type is application/json, the value is either true or
|
||||||
false indicating whether the delete succeeded.
|
false indicating whether the delete succeeded.
|
||||||
|
|
@ -323,9 +322,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to
|
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to
|
||||||
delete. This is required and is specified as part of the URL path.
|
delete. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
||||||
binding rule to delete. This value can be specified as the `ns` URL query
|
binding rule to delete. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
@ -338,6 +337,7 @@ $ curl -X DELETE \
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
true
|
true
|
||||||
```
|
```
|
||||||
|
|
@ -346,9 +346,9 @@ true
|
||||||
|
|
||||||
This endpoint lists all the ACL binding rules.
|
This endpoint lists all the ACL binding rules.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------- | ------------------ |
|
||||||
| `GET` | `/acl/binding-rules` | `application/json` |
|
| `GET` | `/acl/binding-rules` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -364,12 +364,12 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `authmethod` `(string: "")` - Filters the binding rule list to those binding
|
- `authmethod` `(string: "")` - Filters the binding rule list to those binding
|
||||||
rules that are linked with the specific named auth method.
|
rules that are linked with the specific named auth method.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
||||||
the binding rules for. This value can be specified as the `ns` URL query
|
the binding rules for. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. The namespace may be specified as '*' and then
|
to the `default` namespace. The namespace may be specified as '\*' and then
|
||||||
results will be returned for all namespaces. Added in Consul 1.7.0.
|
results will be returned for all namespaces. Added in Consul 1.7.0.
|
||||||
|
|
||||||
## Sample Request
|
## Sample Request
|
||||||
|
|
@ -382,23 +382,23 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rules
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
|
||||||
"Description": "example 1",
|
"Description": "example 1",
|
||||||
"AuthMethod": "minikube-1",
|
"AuthMethod": "minikube-1",
|
||||||
"BindType": "service",
|
"BindType": "service",
|
||||||
"BindName": "k8s-{{ serviceaccount.name }}",
|
"BindName": "k8s-{{ serviceaccount.name }}",
|
||||||
"CreateIndex": 17,
|
"CreateIndex": 17,
|
||||||
"ModifyIndex": 17
|
"ModifyIndex": 17
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa",
|
"ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa",
|
||||||
"Description": "example 2",
|
"Description": "example 2",
|
||||||
"AuthMethod": "minikube-2",
|
"AuthMethod": "minikube-2",
|
||||||
"Selector": "serviceaccount.namespace==default",
|
"Selector": "serviceaccount.namespace==default",
|
||||||
"BindName": "k8s-{{ serviceaccount.name }}",
|
"BindName": "k8s-{{ serviceaccount.name }}",
|
||||||
"CreateIndex": 18,
|
"CreateIndex": 18,
|
||||||
"ModifyIndex": 18
|
"ModifyIndex": 18
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
@ -20,9 +20,9 @@ For more information about ACLs, please see the [ACL Guide](https://learn.hashic
|
||||||
|
|
||||||
This endpoint makes a new ACL token.
|
This endpoint makes a new ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `PUT` | `/acl/create` | `application/json` |
|
| `PUT` | `/acl/create` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -79,9 +79,9 @@ $ curl \
|
||||||
This endpoint is used to modify the policy for a given ACL token. Instead of
|
This endpoint is used to modify the policy for a given ACL token. Instead of
|
||||||
generating a new token ID, the `ID` field must be provided.
|
generating a new token ID, the `ID` field must be provided.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `PUT` | `/acl/update` | `application/json` |
|
| `PUT` | `/acl/update` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -105,7 +105,7 @@ required.
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||||
"Name": "my-app-token-updated",
|
"Name": "my-app-token-updated",
|
||||||
"Type": "client",
|
"Type": "client",
|
||||||
"Rules": "# New Rules",
|
"Rules": "# New Rules"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -119,20 +119,20 @@ $ curl \
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Delete ACL Token
|
## Delete ACL Token
|
||||||
|
|
||||||
This endpoint deletes an ACL token with the given ID.
|
This endpoint deletes an ACL token with the given ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------- | ------------------ |
|
||||||
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
|
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or
|
Even though the return type is application/json, the value is either true or
|
||||||
false, indicating whether the delete succeeded.
|
false, indicating whether the delete succeeded.
|
||||||
|
|
@ -161,6 +161,7 @@ $ curl \
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
true
|
true
|
||||||
```
|
```
|
||||||
|
|
@ -169,9 +170,9 @@ true
|
||||||
|
|
||||||
This endpoint reads an ACL token with the given ID.
|
This endpoint reads an ACL token with the given ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `GET` | `/acl/info/:uuid` | `application/json` |
|
| `GET` | `/acl/info/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -218,9 +219,9 @@ This endpoint clones an ACL and returns a new token `ID`. This allows a token to
|
||||||
serve as a template for others, making it simple to generate new tokens without
|
serve as a template for others, making it simple to generate new tokens without
|
||||||
complex rule management.
|
complex rule management.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -257,9 +258,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint lists all the active ACL tokens.
|
This endpoint lists all the active ACL tokens.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------- | ------------------ |
|
||||||
| `GET` | `/acl/list` | `application/json` |
|
| `GET` | `/acl/list` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -293,8 +294,6 @@ $ curl \
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Check ACL Replication
|
## Check ACL Replication
|
||||||
|
|
||||||
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl.html#check-acl-replication) to learn more about this endpoint.
|
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl.html#check-acl-replication) to learn more about this endpoint.
|
||||||
|
|
||||||
|
|
@ -6,7 +6,7 @@ description: |-
|
||||||
The /acl/policy endpoints manage Consul's ACL policies.
|
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)
|
-> **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
|
# ACL Policy HTTP API
|
||||||
|
|
||||||
|
|
@ -21,9 +21,9 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
||||||
|
|
||||||
This endpoint creates a new ACL policy.
|
This endpoint creates a new ACL policy.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `PUT` | `/acl/policy` | `application/json` |
|
| `PUT` | `/acl/policy` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -38,7 +38,7 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
|
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
|
||||||
can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
||||||
This name must be unique.
|
This name must be unique.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description of the policy.
|
- `Description` `(string: "")` - Free form human readable description of the policy.
|
||||||
|
|
@ -47,8 +47,8 @@ The table below shows this endpoint's support for
|
||||||
`Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html).
|
`Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html).
|
||||||
|
|
||||||
- `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within.
|
- `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within.
|
||||||
When no datacenters are provided the policy is valid in all datacenters including
|
When no datacenters are provided the policy is valid in all datacenters including
|
||||||
those which do not yet exist but may in the future.
|
those which do not yet exist but may in the future.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||||
create the policy. If not provided in the JSON body, the value of
|
create the policy. If not provided in the JSON body, the value of
|
||||||
|
|
@ -79,27 +79,24 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read",
|
"Name": "node-read",
|
||||||
"Description": "Grants read access to all node information",
|
"Description": "Grants read access to all node information",
|
||||||
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"],
|
||||||
"dc1"
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||||
],
|
"CreateIndex": 14,
|
||||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
"ModifyIndex": 14
|
||||||
"CreateIndex": 14,
|
|
||||||
"ModifyIndex": 14
|
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Read a Policy
|
## Read a Policy
|
||||||
|
|
||||||
This endpoint reads an ACL policy with the given ID.
|
This endpoint reads an ACL policy with the given ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `GET` | `/acl/policy/:id` | `application/json` |
|
| `GET` | `/acl/policy/:id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -132,16 +129,14 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9f
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read",
|
"Name": "node-read",
|
||||||
"Description": "Grants read access to all node information",
|
"Description": "Grants read access to all node information",
|
||||||
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"],
|
||||||
"dc1"
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||||
],
|
"CreateIndex": 14,
|
||||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
"ModifyIndex": 14
|
||||||
"CreateIndex": 14,
|
|
||||||
"ModifyIndex": 14
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -149,9 +144,9 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9f
|
||||||
|
|
||||||
This endpoint reads an ACL policy with the given ID.
|
This endpoint reads an ACL policy with the given ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------ | ------------------ |
|
||||||
| `GET` | `/acl/policy/name/:name` | `application/json` |
|
| `GET` | `/acl/policy/name/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -174,7 +169,6 @@ The table below shows this endpoint's support for
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
|
@ -185,16 +179,14 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/name/node-read
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read",
|
"Name": "node-read",
|
||||||
"Description": "Grants read access to all node information",
|
"Description": "Grants read access to all node information",
|
||||||
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"],
|
||||||
"dc1"
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||||
],
|
"CreateIndex": 14,
|
||||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
"ModifyIndex": 14
|
||||||
"CreateIndex": 14,
|
|
||||||
"ModifyIndex": 14
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -202,9 +194,9 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/name/node-read
|
||||||
|
|
||||||
This endpoint updates an existing ACL policy.
|
This endpoint updates an existing ACL policy.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `PUT` | `/acl/policy/:id` | `application/json` |
|
| `PUT` | `/acl/policy/:id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -219,12 +211,12 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `ID` `(string: <required>)` - Specifies the UUID of the policy to update. This is
|
- `ID` `(string: <required>)` - Specifies the UUID of the policy to update. This is
|
||||||
required in the URL path but may also be specified in the JSON body. If specified
|
required in the URL path but may also be specified in the JSON body. If specified
|
||||||
in both places then they must match exactly.
|
in both places then they must match exactly.
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
|
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
|
||||||
can only contain alphanumeric characters as well as `-` and `_` and must be
|
can only contain alphanumeric characters as well as `-` and `_` and must be
|
||||||
unique.
|
unique.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description of this policy.
|
- `Description` `(string: "")` - Free form human readable description of this policy.
|
||||||
|
|
||||||
|
|
@ -232,8 +224,8 @@ The table below shows this endpoint's support for
|
||||||
`Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html).
|
`Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html).
|
||||||
|
|
||||||
- `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within.
|
- `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within.
|
||||||
When no datacenters are provided the policy is valid in all datacenters including
|
When no datacenters are provided the policy is valid in all datacenters including
|
||||||
those which do not yet exist but may in the future.
|
those which do not yet exist but may in the future.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||||
the policy to update. If not provided in the JSON body, the value of
|
the policy to update. If not provided in the JSON body, the value of
|
||||||
|
|
@ -248,7 +240,7 @@ The table below shows this endpoint's support for
|
||||||
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
|
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
|
||||||
"Name": "register-app-service",
|
"Name": "register-app-service",
|
||||||
"Description": "Grants write permissions necessary to register the 'app' service",
|
"Description": "Grants write permissions necessary to register the 'app' service",
|
||||||
"Rules": "service \"app\" { policy = \"write\"}",
|
"Rules": "service \"app\" { policy = \"write\"}"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -264,13 +256,13 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
|
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
|
||||||
"Name": "register-app-service",
|
"Name": "register-app-service",
|
||||||
"Description": "Grants write permissions necessary to register the 'app' service",
|
"Description": "Grants write permissions necessary to register the 'app' service",
|
||||||
"Rules": "service \"app\" { policy = \"write\"}",
|
"Rules": "service \"app\" { policy = \"write\"}",
|
||||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||||
"CreateIndex": 14,
|
"CreateIndex": 14,
|
||||||
"ModifyIndex": 28
|
"ModifyIndex": 28
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -278,9 +270,9 @@ $ curl -X PUT \
|
||||||
|
|
||||||
This endpoint deletes an ACL policy.
|
This endpoint deletes an ACL policy.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ------------------------- | -------------------------- |
|
| -------- | ----------------- | ------------------ |
|
||||||
| `DELETE` | `/acl/policy/:id` | `application/json` |
|
| `DELETE` | `/acl/policy/:id` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or
|
Even though the return type is application/json, the value is either true or
|
||||||
false indicating whether the delete succeeded.
|
false indicating whether the delete succeeded.
|
||||||
|
|
@ -314,6 +306,7 @@ $ curl -X DELETE \
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
true
|
true
|
||||||
```
|
```
|
||||||
|
|
@ -322,9 +315,9 @@ true
|
||||||
|
|
||||||
This endpoint lists all the ACL policies.
|
This endpoint lists all the ACL policies.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------- | ------------------ |
|
||||||
| `GET` | `/acl/policies` | `application/json` |
|
| `GET` | `/acl/policies` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -342,7 +335,7 @@ The table below shows this endpoint's support for
|
||||||
the Policies for. This value can be specified as the `ns` URL query
|
the Policies for. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. The namespace may be specified as '*' and then
|
to the `default` namespace. The namespace may be specified as '\*' and then
|
||||||
results will be returned for all namespaces. Added in Consul 1.7.0.
|
results will be returned for all namespaces. Added in Consul 1.7.0.
|
||||||
|
|
||||||
## Sample Request
|
## Sample Request
|
||||||
|
|
@ -354,30 +347,27 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policies
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
-> **Note** - The policies rules are not included in the listing and must be
|
-> **Note** - The policies rules are not included in the listing and must be
|
||||||
retrieved by the [policy reading endpoint](#read-a-policy)
|
retrieved by the [policy reading endpoint](#read-a-policy)
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"CreateIndex": 4,
|
"CreateIndex": 4,
|
||||||
"Datacenters": null,
|
"Datacenters": null,
|
||||||
"Description": "Builtin Policy that grants unlimited access",
|
"Description": "Builtin Policy that grants unlimited access",
|
||||||
"Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=",
|
"Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=",
|
||||||
"ID": "00000000-0000-0000-0000-000000000001",
|
"ID": "00000000-0000-0000-0000-000000000001",
|
||||||
"ModifyIndex": 4,
|
"ModifyIndex": 4,
|
||||||
"Name": "global-management"
|
"Name": "global-management"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"CreateIndex": 14,
|
"CreateIndex": 14,
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"],
|
||||||
"dc1"
|
"Description": "Grants read access to all node information",
|
||||||
],
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||||
"Description": "Grants read access to all node information",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
"ModifyIndex": 14,
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"Name": "node-read"
|
||||||
"ModifyIndex": 14,
|
}
|
||||||
"Name": "node-read"
|
|
||||||
}
|
|
||||||
]
|
]
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
@ -6,12 +6,12 @@ description: |-
|
||||||
The /acl/role endpoints manage Consul's ACL Roles.
|
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.
|
-> **1.5.0+:** The role APIs are available in Consul versions 1.5.0 and newer.
|
||||||
|
|
||||||
# ACL Role HTTP API
|
# ACL Role HTTP API
|
||||||
|
|
||||||
The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
|
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.
|
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul.
|
||||||
|
|
||||||
For more information on how to setup ACLs, please see
|
For more information on how to setup ACLs, please see
|
||||||
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
|
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
|
||||||
|
|
@ -20,9 +20,9 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
||||||
|
|
||||||
This endpoint creates a new ACL role.
|
This endpoint creates a new ACL role.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------- | ------------------ |
|
||||||
| `PUT` | `/acl/role` | `application/json` |
|
| `PUT` | `/acl/role` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -37,9 +37,8 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
|
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
|
||||||
can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
||||||
This name must be unique.
|
This name must be unique.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description of the role.
|
- `Description` `(string: "")` - Free form human readable description of the role.
|
||||||
|
|
||||||
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
||||||
|
|
@ -52,7 +51,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
||||||
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
|
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
|
||||||
applied to the role. Added in Consul 1.5.0.
|
applied to the role. Added in Consul 1.5.0.
|
||||||
|
|
||||||
- `ServiceName` `(string: <required>)` - The name of the service. The name
|
- `ServiceName` `(string: <required>)` - The name of the service. The name
|
||||||
must be no longer than 256 characters, must start and end with a lowercase
|
must be no longer than 256 characters, must start and end with a lowercase
|
||||||
|
|
@ -63,38 +62,36 @@ The table below shows this endpoint's support for
|
||||||
policy is valid within. When no datacenters are provided the effective
|
policy is valid within. When no datacenters are provided the effective
|
||||||
policy is valid in all datacenters including those which do not yet exist
|
policy is valid in all datacenters including those which do not yet exist
|
||||||
but may in the future.
|
but may in the future.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||||
create the role. If not provided in the JSON body, the value of
|
create the role. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "example-role",
|
"Name": "example-role",
|
||||||
"Description": "Showcases all input parameters",
|
"Description": "Showcases all input parameters",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765"
|
"ID": "783beef3-783f-f41f-7422-7087dc272765"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "web"
|
"ServiceName": "web"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ServiceName": "db",
|
"ServiceName": "db",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"]
|
||||||
"dc1"
|
}
|
||||||
]
|
]
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -110,29 +107,27 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
||||||
"Name": "example-role",
|
"Name": "example-role",
|
||||||
"Description": "Showcases all input parameters",
|
"Description": "Showcases all input parameters",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "web"
|
"ServiceName": "web"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ServiceName": "db",
|
"ServiceName": "db",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"]
|
||||||
"dc1"
|
}
|
||||||
]
|
],
|
||||||
}
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||||
],
|
"CreateIndex": 57,
|
||||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
"ModifyIndex": 57
|
||||||
"CreateIndex": 57,
|
|
||||||
"ModifyIndex": 57
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -141,9 +136,9 @@ $ curl -X PUT \
|
||||||
This endpoint reads an ACL role with the given ID. If no role exists with the
|
This endpoint reads an ACL role with the given ID. If no role exists with the
|
||||||
given ID, a 404 is returned instead of a 200 response.
|
given ID, a 404 is returned instead of a 200 response.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------- | ------------------ |
|
||||||
| `GET` | `/acl/role/:id` | `application/json` |
|
| `GET` | `/acl/role/:id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -158,10 +153,9 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
|
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
|
||||||
read. This is required and is specified as part of the URL path.
|
read. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||||
the role. This value can be specified as the `ns` URL query
|
the role. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
@ -176,29 +170,27 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc3
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
||||||
"Name": "example-role",
|
"Name": "example-role",
|
||||||
"Description": "Showcases all input parameters",
|
"Description": "Showcases all input parameters",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "web"
|
"ServiceName": "web"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ServiceName": "db",
|
"ServiceName": "db",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"]
|
||||||
"dc1"
|
}
|
||||||
]
|
],
|
||||||
}
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||||
],
|
"CreateIndex": 57,
|
||||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
"ModifyIndex": 57
|
||||||
"CreateIndex": 57,
|
|
||||||
"ModifyIndex": 57
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -207,9 +199,9 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc3
|
||||||
This endpoint reads an ACL role with the given name. If no role exists with the
|
This endpoint reads an ACL role with the given name. If no role exists with the
|
||||||
given name, a 404 is returned instead of a 200 response.
|
given name, a 404 is returned instead of a 200 response.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `GET` | `/acl/role/name/:name` | `application/json` |
|
| `GET` | `/acl/role/name/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -224,10 +216,9 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `name` `(string: <required>)` - Specifies the Name of the ACL role to
|
- `name` `(string: <required>)` - Specifies the Name of the ACL role to
|
||||||
read. This is required and is specified as part of the URL path.
|
read. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||||
the role. This value can be specified as the `ns` URL query
|
the role. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
@ -242,29 +233,27 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
||||||
"Name": "example-role",
|
"Name": "example-role",
|
||||||
"Description": "Showcases all input parameters",
|
"Description": "Showcases all input parameters",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "web"
|
"ServiceName": "web"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ServiceName": "db",
|
"ServiceName": "db",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"]
|
||||||
"dc1"
|
}
|
||||||
]
|
],
|
||||||
}
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||||
],
|
"CreateIndex": 57,
|
||||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
"ModifyIndex": 57
|
||||||
"CreateIndex": 57,
|
|
||||||
"ModifyIndex": 57
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -272,9 +261,9 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
|
||||||
|
|
||||||
This endpoint updates an existing ACL role.
|
This endpoint updates an existing ACL role.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------- | ------------------ |
|
||||||
| `PUT` | `/acl/role/:id` | `application/json` |
|
| `PUT` | `/acl/role/:id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -289,13 +278,12 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `ID` `(string: <required>)` - Specifies the ID of the role to update. This is
|
- `ID` `(string: <required>)` - Specifies the ID of the role to update. This is
|
||||||
required in the URL path but may also be specified in the JSON body. If specified
|
required in the URL path but may also be specified in the JSON body. If specified
|
||||||
in both places then they must match exactly.
|
in both places then they must match exactly.
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
|
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
|
||||||
can only contain alphanumeric characters as well as `-` and `_` and must be
|
can only contain alphanumeric characters as well as `-` and `_` and must be
|
||||||
unique.
|
unique.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description of the role.
|
- `Description` `(string: "")` - Free form human readable description of the role.
|
||||||
|
|
||||||
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
||||||
|
|
@ -308,30 +296,30 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
||||||
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
|
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
|
||||||
applied to the role. Added in Consul 1.5.0.
|
applied to the role. Added in Consul 1.5.0.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||||
the role to update. If not provided in the JSON body, the value of
|
the role to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
|
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
|
||||||
"Name": "example-two",
|
"Name": "example-two",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "db"
|
"ServiceName": "db"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -347,22 +335,22 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
|
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
|
||||||
"Name": "example-two",
|
"Name": "example-two",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "db"
|
"ServiceName": "db"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||||
"CreateIndex": 14,
|
"CreateIndex": 14,
|
||||||
"ModifyIndex": 28
|
"ModifyIndex": 28
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -370,9 +358,9 @@ $ curl -X PUT \
|
||||||
|
|
||||||
This endpoint deletes an ACL role.
|
This endpoint deletes an ACL role.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ------------------------- | -------------------------- |
|
| -------- | --------------- | ------------------ |
|
||||||
| `DELETE` | `/acl/role/:id` | `application/json` |
|
| `DELETE` | `/acl/role/:id` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or
|
Even though the return type is application/json, the value is either true or
|
||||||
false indicating whether the delete succeeded.
|
false indicating whether the delete succeeded.
|
||||||
|
|
@ -391,9 +379,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
|
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
|
||||||
delete. This is required and is specified as part of the URL path.
|
delete. This is required and is specified as part of the URL path.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
||||||
role to delete. This value can be specified as the `ns` URL query
|
role to delete. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
@ -406,6 +394,7 @@ $ curl -X DELETE \
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
true
|
true
|
||||||
```
|
```
|
||||||
|
|
@ -414,9 +403,9 @@ true
|
||||||
|
|
||||||
This endpoint lists all the ACL roles.
|
This endpoint lists all the ACL roles.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------ | ------------------ |
|
||||||
| `GET` | `/acl/roles` | `application/json` |
|
| `GET` | `/acl/roles` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -432,14 +421,14 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `policy` `(string: "")` - Filters the role list to those roles that are
|
- `policy` `(string: "")` - Filters the role list to those roles that are
|
||||||
linked with the specific policy ID.
|
linked with the specific policy ID.
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
||||||
the roles for. This value can be specified as the `ns` URL query
|
the roles for. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. The namespace may be specified as '*' and then
|
to the `default` namespace. The namespace may be specified as '\*' and then
|
||||||
results will be returned for all namespaces. Added in Consul 1.7.0.
|
results will be returned for all namespaces. Added in Consul 1.7.0.
|
||||||
|
|
||||||
## Sample Request
|
## Sample Request
|
||||||
|
|
@ -452,44 +441,42 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/roles
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"ID": "5e52a099-4c90-c067-5478-980f06be9af5",
|
"ID": "5e52a099-4c90-c067-5478-980f06be9af5",
|
||||||
"Name": "node-read",
|
"Name": "node-read",
|
||||||
"Description": "",
|
"Description": "",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=",
|
"Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=",
|
||||||
"CreateIndex": 50,
|
"CreateIndex": 50,
|
||||||
"ModifyIndex": 50
|
"ModifyIndex": 50
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
|
||||||
"Name": "example-role",
|
"Name": "example-role",
|
||||||
"Description": "Showcases all input parameters",
|
"Description": "Showcases all input parameters",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
"ID": "783beef3-783f-f41f-7422-7087dc272765",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ServiceIdentities": [
|
"ServiceIdentities": [
|
||||||
{
|
{
|
||||||
"ServiceName": "web"
|
"ServiceName": "web"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ServiceName": "db",
|
"ServiceName": "db",
|
||||||
"Datacenters": [
|
"Datacenters": ["dc1"]
|
||||||
"dc1"
|
}
|
||||||
]
|
],
|
||||||
}
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||||
],
|
"CreateIndex": 57,
|
||||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
"ModifyIndex": 57
|
||||||
"CreateIndex": 57,
|
}
|
||||||
"ModifyIndex": 57
|
|
||||||
}
|
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
@ -6,7 +6,7 @@ description: |-
|
||||||
The /acl/token endpoints manage Consul's ACL Tokens.
|
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)
|
-> **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
|
# ACL Token HTTP API
|
||||||
|
|
||||||
|
|
@ -20,9 +20,9 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
||||||
|
|
||||||
This endpoint creates a new ACL token.
|
This endpoint creates a new ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------ | ------------------ |
|
||||||
| `PUT` | `/acl/token` | `application/json` |
|
| `PUT` | `/acl/token` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -37,12 +37,12 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `AccessorID` `(string: "")` - Specifies a UUID to use as the token's Accessor ID.
|
- `AccessorID` `(string: "")` - Specifies a UUID to use as the token's Accessor ID.
|
||||||
If not specified a UUID will be generated for this field. Added in v1.5.0.
|
If not specified a UUID will be generated for this field. Added in v1.5.0.
|
||||||
|
|
||||||
- `SecretID` `(string: "")` - Specifies a UUID to use as the token's Secret ID.
|
- `SecretID` `(string: "")` - Specifies a UUID to use as the token's Secret ID.
|
||||||
If not specified a UUID will be generated for this field. Added in v1.5.0.
|
If not specified a UUID will be generated for this field. Added in v1.5.0.
|
||||||
**Note**: The SecretID is used to authorize operations against Consul and should
|
**Note**: The SecretID is used to authorize operations against Consul and should
|
||||||
be generated from an appropriate cryptographic source.
|
be generated from an appropriate cryptographic source.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description of the token.
|
- `Description` `(string: "")` - Free form human readable description of the token.
|
||||||
|
|
||||||
|
|
@ -63,7 +63,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
||||||
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
|
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
|
||||||
applied to the token. Added in Consul 1.5.0.
|
applied to the token. Added in Consul 1.5.0.
|
||||||
|
|
||||||
- `ServiceName` `(string: <required>)` - The name of the service. The name
|
- `ServiceName` `(string: <required>)` - The name of the service. The name
|
||||||
must be no longer than 256 characters, must start and end with a lowercase
|
must be no longer than 256 characters, must start and end with a lowercase
|
||||||
|
|
@ -84,8 +84,7 @@ The table below shows this endpoint's support for
|
||||||
minute and 24 hours in the future. Added in Consul 1.5.0.
|
minute and 24 hours in the future. Added in Consul 1.5.0.
|
||||||
|
|
||||||
- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set
|
- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set
|
||||||
will initialize the `ExpirationTime` field to a value of `CreateTime +
|
will initialize the `ExpirationTime` field to a value of `CreateTime + ExpirationTTL`. This field is not persisted beyond its initial use. Can be
|
||||||
ExpirationTTL`. This field is not persisted beyond its initial use. Can be
|
|
||||||
specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes,
|
specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes,
|
||||||
respectively). This value must be no smaller than 1 minute and no longer than
|
respectively). This value must be no smaller than 1 minute and no longer than
|
||||||
24 hours. Added in Consul 1.5.0.
|
24 hours. Added in Consul 1.5.0.
|
||||||
|
|
@ -100,16 +99,16 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Description": "Agent token for 'node1'",
|
"Description": "Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7"
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false
|
"Local": false
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -125,35 +124,34 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
||||||
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
||||||
"Description": "Agent token for 'node1'",
|
"Description": "Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
||||||
"Name": "node1-write"
|
"Name": "node1-write"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
||||||
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
||||||
"CreateIndex": 59,
|
"CreateIndex": 59,
|
||||||
"ModifyIndex": 59
|
"ModifyIndex": 59
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Read a Token
|
## Read a Token
|
||||||
|
|
||||||
This endpoint reads an ACL token with the given Accessor ID.
|
This endpoint reads an ACL token with the given Accessor ID.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------ | ------------------ |
|
||||||
| `GET` | `/acl/token/:AccessorID` | `application/json` |
|
| `GET` | `/acl/token/:AccessorID` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -192,24 +190,24 @@ for reading other secrets which given even more permissions.
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
||||||
"SecretID": "<hidden>",
|
"SecretID": "<hidden>",
|
||||||
"Description": "Agent token for 'node1'",
|
"Description": "Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
||||||
"Name": "node1-write"
|
"Name": "node1-write"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
||||||
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
||||||
"CreateIndex": 59,
|
"CreateIndex": 59,
|
||||||
"ModifyIndex": 59
|
"ModifyIndex": 59
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -218,9 +216,9 @@ for reading other secrets which given even more permissions.
|
||||||
This endpoint returns the ACL token details that matches the secret ID
|
This endpoint returns the ACL token details that matches the secret ID
|
||||||
specified with the `X-Consul-Token` header or the `token` query parameter.
|
specified with the `X-Consul-Token` header or the `token` query parameter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `GET` | `/acl/token/self` | `application/json` |
|
| `GET` | `/acl/token/self` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -246,35 +244,34 @@ $ curl -H "X-Consul-Token: 6a1253d2-1785-24fd-91c2-f8e78c745511" \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
||||||
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
||||||
"Description": "Agent token for 'node1'",
|
"Description": "Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
||||||
"Name": "node1-write"
|
"Name": "node1-write"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
||||||
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
||||||
"CreateIndex": 59,
|
"CreateIndex": 59,
|
||||||
"ModifyIndex": 59
|
"ModifyIndex": 59
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Update a Token
|
## Update a Token
|
||||||
|
|
||||||
This endpoint updates an existing ACL token.
|
This endpoint updates an existing ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------ | ------------------ |
|
||||||
| `PUT` | `/acl/token/:AccessorID` | `application/json` |
|
| `PUT` | `/acl/token/:AccessorID` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -289,13 +286,13 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `AccessorID` `(string: "")` - Specifies the accessor ID of the token being updated. This is
|
- `AccessorID` `(string: "")` - Specifies the accessor ID of the token being updated. This is
|
||||||
required in the URL path but may also be specified in the JSON body. If specified
|
required in the URL path but may also be specified in the JSON body. If specified
|
||||||
in both places then they must match exactly. This field is immutable. If not present in
|
in both places then they must match exactly. This field is immutable. If not present in
|
||||||
the body and only in the URL then it will be filled in by Consul.
|
the body and only in the URL then it will be filled in by Consul.
|
||||||
|
|
||||||
- `SecretID` `(string: "")` - Specifies the secret ID of the token being updated. This field is
|
- `SecretID` `(string: "")` - Specifies the secret ID of the token being updated. This field is
|
||||||
immutable so if present in the body then it must match the existing value. If not present
|
immutable so if present in the body then it must match the existing value. If not present
|
||||||
then the value will be filled in by Consul.
|
then the value will be filled in by Consul.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description of this token.
|
- `Description` `(string: "")` - Free form human readable description of this token.
|
||||||
|
|
||||||
|
|
@ -351,19 +348,19 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Description": "Agent token for 'node1'",
|
"Description": "Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7"
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false
|
"Local": false
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -379,28 +376,28 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
||||||
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
||||||
"Description": "Agent token for 'node1'",
|
"Description": "Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
||||||
"Name": "node1-write"
|
"Name": "node1-write"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
|
"ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
||||||
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
||||||
"CreateIndex": 59,
|
"CreateIndex": 59,
|
||||||
"ModifyIndex": 100
|
"ModifyIndex": 100
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -408,9 +405,9 @@ $ curl -X PUT \
|
||||||
|
|
||||||
This endpoint clones an existing ACL token.
|
This endpoint clones an existing ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------ | -------------------------- |
|
| ------ | ------------------------------ | ------------------ |
|
||||||
| `PUT` | `/acl/token/:AccessorID/clone` | `application/json` |
|
| `PUT` | `/acl/token/:AccessorID/clone` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -425,7 +422,7 @@ The table below shows this endpoint's support for
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `AccessorID` `(string: <required>)` - The accessor ID of the token to clone. This is required
|
- `AccessorID` `(string: <required>)` - The accessor ID of the token to clone. This is required
|
||||||
in the URL path
|
in the URL path
|
||||||
|
|
||||||
- `Description` `(string: "")` - Free form human readable description for the cloned token.
|
- `Description` `(string: "")` - Free form human readable description for the cloned token.
|
||||||
|
|
||||||
|
|
@ -439,7 +436,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Description": "Clone of Agent token for 'node1'",
|
"Description": "Clone of Agent token for 'node1'"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -455,28 +452,28 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"AccessorID": "773efe2a-1f6f-451f-878c-71be10712bae",
|
"AccessorID": "773efe2a-1f6f-451f-878c-71be10712bae",
|
||||||
"SecretID": "8b1247ef-d172-4f99-b050-4dbe5d3df0cb",
|
"SecretID": "8b1247ef-d172-4f99-b050-4dbe5d3df0cb",
|
||||||
"Description": "Clone of Agent token for 'node1'",
|
"Description": "Clone of Agent token for 'node1'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
||||||
"Name": "node1-write"
|
"Name": "node1-write"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
|
"ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
||||||
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
||||||
"CreateIndex": 128,
|
"CreateIndex": 128,
|
||||||
"ModifyIndex": 128
|
"ModifyIndex": 128
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -484,9 +481,9 @@ $ curl -X PUT \
|
||||||
|
|
||||||
This endpoint deletes an ACL token.
|
This endpoint deletes an ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ------------------------- | -------------------------- |
|
| -------- | ------------------------ | ------------------ |
|
||||||
| `DELETE` | `/acl/token/:AccessorID` | `application/json` |
|
| `DELETE` | `/acl/token/:AccessorID` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or
|
Even though the return type is application/json, the value is either true or
|
||||||
false, indicating whether the delete succeeded.
|
false, indicating whether the delete succeeded.
|
||||||
|
|
@ -520,6 +517,7 @@ $ curl -X DELETE \
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
true
|
true
|
||||||
```
|
```
|
||||||
|
|
@ -528,9 +526,9 @@ true
|
||||||
|
|
||||||
This endpoint lists all the ACL tokens.
|
This endpoint lists all the ACL tokens.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `GET` | `/acl/tokens` | `application/json` |
|
| `GET` | `/acl/tokens` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -563,7 +561,7 @@ The table below shows this endpoint's support for
|
||||||
the tokens for. This value can be specified as the `ns` URL query
|
the tokens for. This value can be specified as the `ns` URL query
|
||||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. The namespace may be specified as '*' and then
|
to the `default` namespace. The namespace may be specified as '\*' and then
|
||||||
results will be returned for all namespaces. Added in Consul 1.7.0.
|
results will be returned for all namespaces. Added in Consul 1.7.0.
|
||||||
|
|
||||||
## Sample Request
|
## Sample Request
|
||||||
|
|
@ -575,53 +573,53 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/tokens
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
-> **Note** - The token secret IDs are not included in the listing and must be
|
-> **Note** - The token secret IDs are not included in the listing and must be
|
||||||
retrieved by the [token reading endpoint](#read-a-token)
|
retrieved by the [token reading endpoint](#read-a-token)
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
||||||
"Description": "Agent token for 'my-agent'",
|
"Description": "Agent token for 'my-agent'",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
||||||
"Name": "node1-write"
|
"Name": "node1-write"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
||||||
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
||||||
"CreateIndex": 59,
|
"CreateIndex": 59,
|
||||||
"ModifyIndex": 59
|
"ModifyIndex": 59
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"AccessorID": "00000000-0000-0000-0000-000000000002",
|
"AccessorID": "00000000-0000-0000-0000-000000000002",
|
||||||
"Description": "Anonymous Token",
|
"Description": "Anonymous Token",
|
||||||
"Policies": null,
|
"Policies": null,
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "0001-01-01T00:00:00Z",
|
"CreateTime": "0001-01-01T00:00:00Z",
|
||||||
"Hash": "RNVFSWnfd5DUOuB8vplp+imivlIna3fKQVnkUHh21cA=",
|
"Hash": "RNVFSWnfd5DUOuB8vplp+imivlIna3fKQVnkUHh21cA=",
|
||||||
"CreateIndex": 5,
|
"CreateIndex": 5,
|
||||||
"ModifyIndex": 5
|
"ModifyIndex": 5
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"AccessorID": "3328f9a6-433c-02d0-6649-7d07268dfec7",
|
"AccessorID": "3328f9a6-433c-02d0-6649-7d07268dfec7",
|
||||||
"Description": "Bootstrap Token (Global Management)",
|
"Description": "Bootstrap Token (Global Management)",
|
||||||
"Policies": [
|
"Policies": [
|
||||||
{
|
{
|
||||||
"ID": "00000000-0000-0000-0000-000000000001",
|
"ID": "00000000-0000-0000-0000-000000000001",
|
||||||
"Name": "global-management"
|
"Name": "global-management"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Local": false,
|
"Local": false,
|
||||||
"CreateTime": "2018-10-24T11:42:02.6427-04:00",
|
"CreateTime": "2018-10-24T11:42:02.6427-04:00",
|
||||||
"Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
|
"Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
|
||||||
"CreateIndex": 12,
|
"CreateIndex": 12,
|
||||||
"ModifyIndex": 12
|
"ModifyIndex": 12
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
@ -25,9 +25,9 @@ to the nature of gossip, this is eventually consistent: the results may differ
|
||||||
by agent. The strongly consistent view of nodes is instead provided by
|
by agent. The strongly consistent view of nodes is instead provided by
|
||||||
`/v1/catalog/nodes`.
|
`/v1/catalog/nodes`.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `GET` | `/agent/members` | `application/json` |
|
| `GET` | `/agent/members` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -91,9 +91,9 @@ format will not change in a backwards incompatible way between releases.
|
||||||
`DebugConfig` contains the full runtime configuration but its format is subject
|
`DebugConfig` contains the full runtime configuration but its format is subject
|
||||||
to change without notice or deprecation.
|
to change without notice or deprecation.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `GET` | `/agent/self` | `application/json` |
|
| `GET` | `/agent/self` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -171,9 +171,9 @@ Not all configuration options are reloadable. See the
|
||||||
[Reloadable Configuration](/docs/agent/options.html#reloadable-configuration)
|
[Reloadable Configuration](/docs/agent/options.html#reloadable-configuration)
|
||||||
section on the agent options page for details on which options are supported.
|
section on the agent options page for details on which options are supported.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------- | ------------------ |
|
||||||
| `PUT` | `/agent/reload` | `application/json` |
|
| `PUT` | `/agent/reload` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -202,9 +202,9 @@ queries. This API call is idempotent.
|
||||||
Maintenance mode is persistent and will be automatically restored on agent
|
Maintenance mode is persistent and will be automatically restored on agent
|
||||||
restart.
|
restart.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/maintenance` | `application/json` |
|
| `PUT` | `/agent/maintenance` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -277,106 +277,106 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Timestamp": "2017-08-08 02:55:10 +0000 UTC",
|
"Timestamp": "2017-08-08 02:55:10 +0000 UTC",
|
||||||
"Gauges": [
|
"Gauges": [
|
||||||
{
|
{
|
||||||
"Name": "consul.consul.session_ttl.active",
|
"Name": "consul.consul.session_ttl.active",
|
||||||
"Value": 0,
|
"Value": 0,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "consul.runtime.alloc_bytes",
|
"Name": "consul.runtime.alloc_bytes",
|
||||||
"Value": 4704344,
|
"Value": 4704344,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "consul.runtime.free_count",
|
"Name": "consul.runtime.free_count",
|
||||||
"Value": 74063,
|
"Value": 74063,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Points": [],
|
"Points": [],
|
||||||
"Counters": [
|
"Counters": [
|
||||||
{
|
{
|
||||||
"Name": "consul.consul.catalog.service.query",
|
"Name": "consul.consul.catalog.service.query",
|
||||||
"Count": 1,
|
"Count": 1,
|
||||||
"Sum": 1,
|
"Sum": 1,
|
||||||
"Min": 1,
|
"Min": 1,
|
||||||
"Max": 1,
|
"Max": 1,
|
||||||
"Mean": 1,
|
"Mean": 1,
|
||||||
"Stddev": 0,
|
"Stddev": 0,
|
||||||
"Labels": {
|
"Labels": {
|
||||||
"service": "consul"
|
"service": "consul"
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "consul.raft.apply",
|
"Name": "consul.raft.apply",
|
||||||
"Count": 1,
|
"Count": 1,
|
||||||
"Sum": 1,
|
"Sum": 1,
|
||||||
"Min": 1,
|
"Min": 1,
|
||||||
"Max": 1,
|
"Max": 1,
|
||||||
"Mean": 1,
|
"Mean": 1,
|
||||||
"Stddev": 0,
|
"Stddev": 0,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"Samples": [
|
"Samples": [
|
||||||
{
|
{
|
||||||
"Name": "consul.consul.http.GET.v1.agent.metrics",
|
"Name": "consul.consul.http.GET.v1.agent.metrics",
|
||||||
"Count": 1,
|
"Count": 1,
|
||||||
"Sum": 0.1817069947719574,
|
"Sum": 0.1817069947719574,
|
||||||
"Min": 0.1817069947719574,
|
"Min": 0.1817069947719574,
|
||||||
"Max": 0.1817069947719574,
|
"Max": 0.1817069947719574,
|
||||||
"Mean": 0.1817069947719574,
|
"Mean": 0.1817069947719574,
|
||||||
"Stddev": 0,
|
"Stddev": 0,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "consul.consul.http.GET.v1.catalog.service._",
|
"Name": "consul.consul.http.GET.v1.catalog.service._",
|
||||||
"Count": 1,
|
"Count": 1,
|
||||||
"Sum": 0.23342099785804749,
|
"Sum": 0.23342099785804749,
|
||||||
"Min": 0.23342099785804749,
|
"Min": 0.23342099785804749,
|
||||||
"Max": 0.23342099785804749,
|
"Max": 0.23342099785804749,
|
||||||
"Mean": 0.23342099785804749,
|
"Mean": 0.23342099785804749,
|
||||||
"Stddev": 0,
|
"Stddev": 0,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "consul.serf.queue.Query",
|
"Name": "consul.serf.queue.Query",
|
||||||
"Count": 20,
|
"Count": 20,
|
||||||
"Sum": 0,
|
"Sum": 0,
|
||||||
"Min": 0,
|
"Min": 0,
|
||||||
"Max": 0,
|
"Max": 0,
|
||||||
"Mean": 0,
|
"Mean": 0,
|
||||||
"Stddev": 0,
|
"Stddev": 0,
|
||||||
"Labels": {}
|
"Labels": {}
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `Timestamp` is the timestamp of the interval for the displayed metrics. Metrics are
|
- `Timestamp` is the timestamp of the interval for the displayed metrics. Metrics are
|
||||||
aggregated on a ten second interval, so this value (along with the displayed metrics)
|
aggregated on a ten second interval, so this value (along with the displayed metrics)
|
||||||
will change every ten seconds.
|
will change every ten seconds.
|
||||||
|
|
||||||
- `Gauges` is a list of gauges which store one value that is updated as time goes on,
|
- `Gauges` is a list of gauges which store one value that is updated as time goes on,
|
||||||
such as the amount of memory allocated.
|
such as the amount of memory allocated.
|
||||||
|
|
||||||
- `Points` is a list of point metrics, which each store a series of points under a given name.
|
- `Points` is a list of point metrics, which each store a series of points under a given name.
|
||||||
|
|
||||||
- `Counters` is a list of counters, which store info about a metric that is incremented
|
- `Counters` is a list of counters, which store info about a metric that is incremented
|
||||||
over time such as the number of requests to an HTTP endpoint.
|
over time such as the number of requests to an HTTP endpoint.
|
||||||
|
|
||||||
- `Samples` is a list of samples, which store info about the amount of time spent on an
|
- `Samples` is a list of samples, which store info about the amount of time spent on an
|
||||||
operation, such as the time taken to serve a request to a specific http endpoint.
|
operation, such as the time taken to serve a request to a specific http endpoint.
|
||||||
|
|
||||||
## Stream Logs
|
## Stream Logs
|
||||||
|
|
||||||
This endpoint streams logs from the local agent until the connection is closed.
|
This endpoint streams logs from the local agent until the connection is closed.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `GET` | `/agent/monitor` | `application/json` |
|
| `GET` | `/agent/monitor` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -418,9 +418,9 @@ YYYY/MM/DD HH:MM:SS [INFO] consul: Handled member-join event for server "machine
|
||||||
|
|
||||||
This endpoint instructs the agent to attempt to connect to a given address.
|
This endpoint instructs the agent to attempt to connect to a given address.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/join/:address` | `application/json` |
|
| `PUT` | `/agent/join/:address` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -458,9 +458,9 @@ For nodes in server mode, the node is removed from the Raft peer set in a
|
||||||
graceful manner. This is critical, as in certain situations a non-graceful leave
|
graceful manner. This is critical, as in certain situations a non-graceful leave
|
||||||
can affect cluster availability.
|
can affect cluster availability.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------- | ------------------ |
|
||||||
| `PUT` | `/agent/leave` | `application/json` |
|
| `PUT` | `/agent/leave` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -488,17 +488,16 @@ node fails unexpectedly, then it will be in a `failed` state. Once in the
|
||||||
belonging to that node will not be cleaned up. Forcing a node into the `left`
|
belonging to that node will not be cleaned up. Forcing a node into the `left`
|
||||||
state allows its old entries to be removed.
|
state allows its old entries to be removed.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/force-leave/:node` | `application/json` |
|
| `PUT` | `/agent/force-leave/:node` | `application/json` |
|
||||||
|
|
||||||
Additionally, by specifying the `prune` flag, a node can be forcibly removed from
|
Additionally, by specifying the `prune` flag, a node can be forcibly removed from
|
||||||
the list of members entirely.
|
the list of members entirely.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | --------------------------------------- | -------------------------- |
|
| ------ | -------------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/force-leave/:node?prune` | `application/json` |
|
| `PUT` | `/agent/force-leave/:node?prune` | `application/json` |
|
||||||
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -506,8 +505,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------- |
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||||
| `NO` | `none` | `none` | `operator:write` |
|
| `NO` | `none` | `none` | `operator:write` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
@ -531,12 +530,12 @@ only if the [`acl.enable_token_persistence`](/docs/agent/options.html#acl_enable
|
||||||
configuration is `true`. When not being persisted, they will need to be reset if the agent
|
configuration is `true`. When not being persisted, they will need to be reset if the agent
|
||||||
is restarted.
|
is restarted.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | --------------------------- | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/token/default` | `application/json` |
|
| `PUT` | `/agent/token/default` | `application/json` |
|
||||||
| `PUT` | `/agent/token/agent` | `application/json` |
|
| `PUT` | `/agent/token/agent` | `application/json` |
|
||||||
| `PUT` | `/agent/token/agent_master` | `application/json` |
|
| `PUT` | `/agent/token/agent_master` | `application/json` |
|
||||||
| `PUT` | `/agent/token/replication` | `application/json` |
|
| `PUT` | `/agent/token/replication` | `application/json` |
|
||||||
|
|
||||||
The paths above correspond to the token names as found in the agent configuration:
|
The paths above correspond to the token names as found in the agent configuration:
|
||||||
[`default`](/docs/agent/options.html#acl_tokens_default), [`agent`](/docs/agent/options.html#acl_tokens_agent),
|
[`default`](/docs/agent/options.html#acl_tokens_default), [`agent`](/docs/agent/options.html#acl_tokens_agent),
|
||||||
|
|
@ -545,12 +544,12 @@ The paths above correspond to the token names as found in the agent configuratio
|
||||||
|
|
||||||
-> **Deprecation Note:** The following paths were deprecated in version 1.4.3
|
-> **Deprecation Note:** The following paths were deprecated in version 1.4.3
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------------- | -------------------------- |
|
| ------ | ------------------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/token/acl_token` | `application/json` |
|
| `PUT` | `/agent/token/acl_token` | `application/json` |
|
||||||
| `PUT` | `/agent/token/acl_agent_token` | `application/json` |
|
| `PUT` | `/agent/token/acl_agent_token` | `application/json` |
|
||||||
| `PUT` | `/agent/token/acl_agent_master_token` | `application/json` |
|
| `PUT` | `/agent/token/acl_agent_master_token` | `application/json` |
|
||||||
| `PUT` | `/agent/token/acl_replication_token` | `application/json` |
|
| `PUT` | `/agent/token/acl_replication_token` | `application/json` |
|
||||||
|
|
||||||
The paths above correspond to the token names as found in the agent configuration:
|
The paths above correspond to the token names as found in the agent configuration:
|
||||||
[`acl_token`](/docs/agent/options.html#acl_token_legacy), [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy),
|
[`acl_token`](/docs/agent/options.html#acl_token_legacy), [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy),
|
||||||
|
|
@ -23,9 +23,9 @@ there is no leader elected. The agent performs active
|
||||||
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
|
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
|
||||||
everything will be in sync within a few seconds.
|
everything will be in sync within a few seconds.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------- | ------------------ |
|
||||||
| `GET` | `/agent/checks` | `application/json` |
|
| `GET` | `/agent/checks` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -72,9 +72,8 @@ $ curl \
|
||||||
The filter will be executed against each health check value in the results map with
|
The filter will be executed against each health check value in the results map with
|
||||||
the following selectors and filter operations being supported:
|
the following selectors and filter operations being supported:
|
||||||
|
|
||||||
|
|
||||||
| Selector | Supported Operations |
|
| Selector | Supported Operations |
|
||||||
| ------------- | ------------------------------------------------- |
|
| ------------- | -------------------------------------------------- |
|
||||||
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
| `Name` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `Name` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
|
|
@ -91,9 +90,9 @@ This endpoint adds a new check to the local agent. Checks may be of script,
|
||||||
HTTP, TCP, or TTL type. The agent is responsible for managing the status of the
|
HTTP, TCP, or TTL type. The agent is responsible for managing the status of the
|
||||||
check and keeping the Catalog in sync.
|
check and keeping the Catalog in sync.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/check/register` | `application/json` |
|
| `PUT` | `/agent/check/register` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -137,9 +136,9 @@ The table below shows this endpoint's support for
|
||||||
run under a shell, eg. `"args": ["sh", "-c", "..."]`.
|
run under a shell, eg. `"args": ["sh", "-c", "..."]`.
|
||||||
|
|
||||||
-> **Note:** Consul 1.0 shipped with an issue where `Args` was erroneously named
|
-> **Note:** Consul 1.0 shipped with an issue where `Args` was erroneously named
|
||||||
`ScriptArgs` in this API. Please use `ScriptArgs` with Consul 1.0 (that will
|
`ScriptArgs` in this API. Please use `ScriptArgs` with Consul 1.0 (that will
|
||||||
continue to be accepted in future versions of Consul), and `Args` in Consul
|
continue to be accepted in future versions of Consul), and `Args` in Consul
|
||||||
1.0.1 and later.
|
1.0.1 and later.
|
||||||
|
|
||||||
- `AliasNode` `(string: "")` - Specifies the ID of the node for an alias check.
|
- `AliasNode` `(string: "")` - Specifies the ID of the node for an alias check.
|
||||||
If no service is specified, the check will alias the health of the node.
|
If no service is specified, the check will alias the health of the node.
|
||||||
|
|
@ -167,8 +166,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `HTTP` `(string: "")` - Specifies an `HTTP` check to perform a `GET` request
|
- `HTTP` `(string: "")` - Specifies an `HTTP` check to perform a `GET` request
|
||||||
against the value of `HTTP` (expected to be a URL) every `Interval`. If the
|
against the value of `HTTP` (expected to be a URL) every `Interval`. If the
|
||||||
response is any `2xx` code, the check is `passing`. If the response is `429
|
response is any `2xx` code, the check is `passing`. If the response is `429 Too Many Requests`, the check is `warning`. Otherwise, the check is
|
||||||
Too Many Requests`, the check is `warning`. Otherwise, the check is
|
|
||||||
`critical`. HTTP checks also support SSL. By default, a valid SSL certificate
|
`critical`. HTTP checks also support SSL. By default, a valid SSL certificate
|
||||||
is expected. Certificate verification can be controlled using the
|
is expected. Certificate verification can be controlled using the
|
||||||
`TLSSkipVerify`.
|
`TLSSkipVerify`.
|
||||||
|
|
@ -223,7 +221,7 @@ The table below shows this endpoint's support for
|
||||||
"Shell": "/bin/bash",
|
"Shell": "/bin/bash",
|
||||||
"HTTP": "https://example.com",
|
"HTTP": "https://example.com",
|
||||||
"Method": "POST",
|
"Method": "POST",
|
||||||
"Header": {"Content-Type": "application/json"},
|
"Header": { "Content-Type": "application/json" },
|
||||||
"Body": "{\"check\":\"mem\"}",
|
"Body": "{\"check\":\"mem\"}",
|
||||||
"TCP": "example.com:22",
|
"TCP": "example.com:22",
|
||||||
"Interval": "10s",
|
"Interval": "10s",
|
||||||
|
|
@ -247,9 +245,9 @@ This endpoint remove a check from the local agent. The agent will take care of
|
||||||
deregistering the check from the catalog. If the check with the provided ID does
|
deregistering the check from the catalog. If the check with the provided ID does
|
||||||
not exist, no action is taken.
|
not exist, no action is taken.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ----------------------------------- | -------------------------- |
|
| ------ | ----------------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/check/deregister/:check_id` | `application/json` |
|
| `PUT` | `/agent/check/deregister/:check_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -279,9 +277,9 @@ $ curl \
|
||||||
This endpoint is used with a TTL type check to set the status of the check to
|
This endpoint is used with a TTL type check to set the status of the check to
|
||||||
`passing` and to reset the TTL clock.
|
`passing` and to reset the TTL clock.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ----------------------------- | -------------------------- |
|
| ------ | ----------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/check/pass/:check_id` | `application/json` |
|
| `PUT` | `/agent/check/pass/:check_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -313,9 +311,9 @@ $ curl \
|
||||||
This endpoint is used with a TTL type check to set the status of the check to
|
This endpoint is used with a TTL type check to set the status of the check to
|
||||||
`warning` and to reset the TTL clock.
|
`warning` and to reset the TTL clock.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ----------------------------- | -------------------------- |
|
| ------ | ----------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/check/warn/:check_id` | `application/json` |
|
| `PUT` | `/agent/check/warn/:check_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -347,9 +345,9 @@ $ curl \
|
||||||
This endpoint is used with a TTL type check to set the status of the check to
|
This endpoint is used with a TTL type check to set the status of the check to
|
||||||
`critical` and to reset the TTL clock.
|
`critical` and to reset the TTL clock.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ----------------------------- | -------------------------- |
|
| ------ | ----------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/check/fail/:check_id` | `application/json` |
|
| `PUT` | `/agent/check/fail/:check_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -381,9 +379,9 @@ $ curl \
|
||||||
This endpoint is used with a TTL type check to set the status of the check and
|
This endpoint is used with a TTL type check to set the status of the check and
|
||||||
to reset the TTL clock.
|
to reset the TTL clock.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------- | -------------------------- |
|
| ------ | ------------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/check/update/:check_id` | `application/json` |
|
| `PUT` | `/agent/check/update/:check_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -30,9 +30,9 @@ and doesn't require any request forwarding to a server. Therefore, the
|
||||||
response typically occurs in microseconds to impose minimal overhead on the
|
response typically occurs in microseconds to impose minimal overhead on the
|
||||||
connection attempt.
|
connection attempt.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------------- | ------------------ |
|
||||||
| `POST` | `/agent/connect/authorize` | `application/json` |
|
| `POST` | `/agent/connect/authorize` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -56,11 +56,11 @@ The table below shows this endpoint's support for
|
||||||
- `ClientCertSerial` `(string: <required>)` - The colon-hex-encoded serial
|
- `ClientCertSerial` `(string: <required>)` - The colon-hex-encoded serial
|
||||||
number for the requesting client cert. This is used to check against
|
number for the requesting client cert. This is used to check against
|
||||||
revocation lists.
|
revocation lists.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||||
the target service. If not provided in the JSON body, the value of
|
the target service. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
@ -103,9 +103,9 @@ but the response of this request is cached locally at the agent. This allows
|
||||||
for very fast response times and for fail open behavior if the server is
|
for very fast response times and for fail open behavior if the server is
|
||||||
unavailable. This endpoint should be used by proxies and native integrations.
|
unavailable. This endpoint should be used by proxies and native integrations.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------- | ------------------ |
|
||||||
| `GET` | `/agent/connect/ca/roots` | `application/json` |
|
| `GET` | `/agent/connect/ca/roots` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -167,9 +167,9 @@ a new certificate is necessary because the existing certificate will expire
|
||||||
or the root certificate is being rotated. This blocking behavior allows
|
or the root certificate is being rotated. This blocking behavior allows
|
||||||
clients to efficiently wait for certificate rotations.
|
clients to efficiently wait for certificate rotations.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------------- | ------------------ |
|
||||||
| `GET` | `/agent/connect/ca/leaf/:service` | `application/json` |
|
| `GET` | `/agent/connect/ca/leaf/:service` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -24,9 +24,9 @@ while there is no leader elected. The agent performs active
|
||||||
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
|
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
|
||||||
everything will be in sync within a few seconds.
|
everything will be in sync within a few seconds.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `GET` | `/agent/services` | `application/json` |
|
| `GET` | `/agent/services` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -55,29 +55,29 @@ $ curl \
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"redis": {
|
"redis": {
|
||||||
"ID": "redis",
|
"ID": "redis",
|
||||||
"Service": "redis",
|
"Service": "redis",
|
||||||
"Tags": [],
|
"Tags": [],
|
||||||
"TaggedAddresses": {
|
"TaggedAddresses": {
|
||||||
"lan": {
|
"lan": {
|
||||||
"address": "127.0.0.1",
|
"address": "127.0.0.1",
|
||||||
"port": 8000
|
"port": 8000
|
||||||
},
|
|
||||||
"wan": {
|
|
||||||
"address": "198.18.0.53",
|
|
||||||
"port": 80
|
|
||||||
}
|
|
||||||
},
|
},
|
||||||
"Meta": {
|
"wan": {
|
||||||
"redis_version": "4.0"
|
"address": "198.18.0.53",
|
||||||
},
|
"port": 80
|
||||||
"Port": 8000,
|
|
||||||
"Address": "",
|
|
||||||
"EnableTagOverride": false,
|
|
||||||
"Weights": {
|
|
||||||
"Passing": 10,
|
|
||||||
"Warning": 1
|
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"Meta": {
|
||||||
|
"redis_version": "4.0"
|
||||||
|
},
|
||||||
|
"Port": 8000,
|
||||||
|
"Address": "",
|
||||||
|
"EnableTagOverride": false,
|
||||||
|
"Weights": {
|
||||||
|
"Passing": 10,
|
||||||
|
"Warning": 1
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
@ -88,7 +88,7 @@ The filter is executed against each value in the service mapping with the
|
||||||
following selectors and filter operations being supported:
|
following selectors and filter operations being supported:
|
||||||
|
|
||||||
| Selector | Supported Operations |
|
| Selector | Supported Operations |
|
||||||
| -------------------------------------- | ------------------------------------------------- |
|
| -------------------------------------- | -------------------------------------------------- |
|
||||||
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
| `Connect.Native` | Equal, Not Equal |
|
| `Connect.Native` | Equal, Not Equal |
|
||||||
| `EnableTagOverride` | Equal, Not Equal |
|
| `EnableTagOverride` | Equal, Not Equal |
|
||||||
|
|
@ -118,7 +118,6 @@ following selectors and filter operations being supported:
|
||||||
| `Weights.Passing` | Equal, Not Equal |
|
| `Weights.Passing` | Equal, Not Equal |
|
||||||
| `Weights.Warning` | Equal, Not Equal |
|
| `Weights.Warning` | Equal, Not Equal |
|
||||||
|
|
||||||
|
|
||||||
## Get Service Configuration
|
## Get Service Configuration
|
||||||
|
|
||||||
This endpoint was added in Consul 1.3.0 and returns the full service definition
|
This endpoint was added in Consul 1.3.0 and returns the full service definition
|
||||||
|
|
@ -132,9 +131,9 @@ while there is no leader elected. The agent performs active
|
||||||
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
|
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
|
||||||
everything will be in sync within a few seconds.
|
everything will be in sync within a few seconds.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------------- | ------------------ |
|
||||||
| `GET` | `/agent/service/:service_id` | `application/json` |
|
| `GET` | `/agent/service/:service_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -142,9 +141,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | -------------- |
|
| ----------------- | ----------------- | ------------- | -------------- |
|
||||||
| `YES`<sup>1</sup>| `none` | `none` | `service:read` |
|
| `YES`<sup>1</sup> | `none` | `none` | `service:read` |
|
||||||
|
|
||||||
<sup>1</sup> Supports [hash-based
|
<sup>1</sup> Supports [hash-based
|
||||||
blocking](/api/features/blocking.html#hash-based-blocking-queries) only.
|
blocking](/api/features/blocking.html#hash-based-blocking-queries) only.
|
||||||
|
|
@ -165,45 +164,45 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Kind": "connect-proxy",
|
"Kind": "connect-proxy",
|
||||||
"ID": "web-sidecar-proxy",
|
"ID": "web-sidecar-proxy",
|
||||||
"Service": "web-sidecar-proxy",
|
"Service": "web-sidecar-proxy",
|
||||||
"Tags": null,
|
"Tags": null,
|
||||||
"Meta": null,
|
"Meta": null,
|
||||||
"Port": 18080,
|
"Port": 18080,
|
||||||
"Address": "",
|
"Address": "",
|
||||||
"TaggedAddresses": {
|
"TaggedAddresses": {
|
||||||
"lan": {
|
"lan": {
|
||||||
"address": "127.0.0.1",
|
"address": "127.0.0.1",
|
||||||
"port": 8000
|
"port": 8000
|
||||||
},
|
|
||||||
"wan": {
|
|
||||||
"address": "198.18.0.53",
|
|
||||||
"port": 80
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"Weights": {
|
|
||||||
"Passing": 1,
|
|
||||||
"Warning": 1
|
|
||||||
},
|
},
|
||||||
"EnableTagOverride": false,
|
"wan": {
|
||||||
"ContentHash": "4ecd29c7bc647ca8",
|
"address": "198.18.0.53",
|
||||||
"Proxy": {
|
"port": 80
|
||||||
"DestinationServiceName": "web",
|
|
||||||
"DestinationServiceID": "web",
|
|
||||||
"LocalServiceAddress": "127.0.0.1",
|
|
||||||
"LocalServicePort": 8080,
|
|
||||||
"Config": {
|
|
||||||
"foo": "bar"
|
|
||||||
},
|
|
||||||
"Upstreams": [
|
|
||||||
{
|
|
||||||
"DestinationType": "service",
|
|
||||||
"DestinationName": "db",
|
|
||||||
"LocalBindPort": 9191
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"Weights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"EnableTagOverride": false,
|
||||||
|
"ContentHash": "4ecd29c7bc647ca8",
|
||||||
|
"Proxy": {
|
||||||
|
"DestinationServiceName": "web",
|
||||||
|
"DestinationServiceID": "web",
|
||||||
|
"LocalServiceAddress": "127.0.0.1",
|
||||||
|
"LocalServicePort": 8080,
|
||||||
|
"Config": {
|
||||||
|
"foo": "bar"
|
||||||
|
},
|
||||||
|
"Upstreams": [
|
||||||
|
{
|
||||||
|
"DestinationType": "service",
|
||||||
|
"DestinationName": "db",
|
||||||
|
"LocalBindPort": 9191
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -241,7 +240,7 @@ Those endpoints return the aggregated values of all healthchecks for the
|
||||||
service instance(s) and will return the corresponding HTTP codes:
|
service instance(s) and will return the corresponding HTTP codes:
|
||||||
|
|
||||||
| Result | Meaning |
|
| Result | Meaning |
|
||||||
| ------ | ----------------------------------------------------------------|
|
| ------ | --------------------------------------------------------------- |
|
||||||
| `200` | All healthchecks of every matching service instance are passing |
|
| `200` | All healthchecks of every matching service instance are passing |
|
||||||
| `400` | Bad parameter (missing service name of id) |
|
| `400` | Bad parameter (missing service name of id) |
|
||||||
| `404` | No such service id or name |
|
| `404` | No such service id or name |
|
||||||
|
|
@ -250,13 +249,13 @@ service instance(s) and will return the corresponding HTTP codes:
|
||||||
|
|
||||||
Those endpoints might be useful for the following use-cases:
|
Those endpoints might be useful for the following use-cases:
|
||||||
|
|
||||||
* a load-balancer wants to check IP connectivity with an agent and retrieve
|
- a load-balancer wants to check IP connectivity with an agent and retrieve
|
||||||
the aggregated status of given service
|
the aggregated status of given service
|
||||||
* create aliases for a given service (thus, the healthcheck of alias uses
|
- create aliases for a given service (thus, the healthcheck of alias uses
|
||||||
http://localhost:8500/v1/agent/service/id/aliased_service_id healthcheck)
|
http://localhost:8500/v1/agent/service/id/aliased_service_id healthcheck)
|
||||||
|
|
||||||
|
|
||||||
##### Note
|
##### Note
|
||||||
|
|
||||||
If you know the ID of service you want to target, it is recommended to use
|
If you know the ID of service you want to target, it is recommended to use
|
||||||
[`/v1/agent/health/service/id/:service_id`](/api/agent/service.html#get-local-service-health-by-id)
|
[`/v1/agent/health/service/id/:service_id`](/api/agent/service.html#get-local-service-health-by-id)
|
||||||
so you have the result for the service only. When requesting
|
so you have the result for the service only. When requesting
|
||||||
|
|
@ -287,64 +286,60 @@ curl localhost:8500/v1/agent/health/service/name/web
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"critical": [
|
"critical": [
|
||||||
{
|
{
|
||||||
"ID": "web2",
|
"ID": "web2",
|
||||||
"Service": "web",
|
"Service": "web",
|
||||||
"Tags": [
|
"Tags": ["rails"],
|
||||||
"rails"
|
"Address": "",
|
||||||
],
|
"TaggedAddresses": {
|
||||||
"Address": "",
|
"lan": {
|
||||||
"TaggedAddresses": {
|
"address": "127.0.0.1",
|
||||||
"lan": {
|
"port": 8000
|
||||||
"address": "127.0.0.1",
|
},
|
||||||
"port": 8000
|
"wan": {
|
||||||
},
|
"address": "198.18.0.53",
|
||||||
"wan": {
|
"port": 80
|
||||||
"address": "198.18.0.53",
|
|
||||||
"port": 80
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"Meta": null,
|
|
||||||
"Port": 80,
|
|
||||||
"EnableTagOverride": false,
|
|
||||||
"Connect": {
|
|
||||||
"Native": false,
|
|
||||||
"Proxy": null
|
|
||||||
},
|
|
||||||
"CreateIndex": 0,
|
|
||||||
"ModifyIndex": 0
|
|
||||||
}
|
}
|
||||||
],
|
},
|
||||||
"passing": [
|
"Meta": null,
|
||||||
{
|
"Port": 80,
|
||||||
"ID": "web1",
|
"EnableTagOverride": false,
|
||||||
"Service": "web",
|
"Connect": {
|
||||||
"Tags": [
|
"Native": false,
|
||||||
"rails"
|
"Proxy": null
|
||||||
],
|
},
|
||||||
"Address": "",
|
"CreateIndex": 0,
|
||||||
"TaggedAddresses": {
|
"ModifyIndex": 0
|
||||||
"lan": {
|
}
|
||||||
"address": "127.0.0.1",
|
],
|
||||||
"port": 8000
|
"passing": [
|
||||||
},
|
{
|
||||||
"wan": {
|
"ID": "web1",
|
||||||
"address": "198.18.0.53",
|
"Service": "web",
|
||||||
"port": 80
|
"Tags": ["rails"],
|
||||||
}
|
"Address": "",
|
||||||
},
|
"TaggedAddresses": {
|
||||||
"Meta": null,
|
"lan": {
|
||||||
"Port": 80,
|
"address": "127.0.0.1",
|
||||||
"EnableTagOverride": false,
|
"port": 8000
|
||||||
"Connect": {
|
},
|
||||||
"Native": false,
|
"wan": {
|
||||||
"Proxy": null
|
"address": "198.18.0.53",
|
||||||
},
|
"port": 80
|
||||||
"CreateIndex": 0,
|
|
||||||
"ModifyIndex": 0
|
|
||||||
}
|
}
|
||||||
]
|
},
|
||||||
|
"Meta": null,
|
||||||
|
"Port": 80,
|
||||||
|
"EnableTagOverride": false,
|
||||||
|
"Connect": {
|
||||||
|
"Native": false,
|
||||||
|
"Proxy": null
|
||||||
|
},
|
||||||
|
"CreateIndex": 0,
|
||||||
|
"ModifyIndex": 0
|
||||||
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -368,33 +363,31 @@ curl localhost:8500/v1/agent/health/service/id/web2
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"critical": {
|
"critical": {
|
||||||
"ID": "web2",
|
"ID": "web2",
|
||||||
"Service": "web",
|
"Service": "web",
|
||||||
"Tags": [
|
"Tags": ["rails"],
|
||||||
"rails"
|
"Address": "",
|
||||||
],
|
"TaggedAddresses": {
|
||||||
"Address": "",
|
"lan": {
|
||||||
"TaggedAddresses": {
|
"address": "127.0.0.1",
|
||||||
"lan": {
|
"port": 8000
|
||||||
"address": "127.0.0.1",
|
},
|
||||||
"port": 8000
|
"wan": {
|
||||||
},
|
"address": "198.18.0.53",
|
||||||
"wan": {
|
"port": 80
|
||||||
"address": "198.18.0.53",
|
}
|
||||||
"port": 80
|
},
|
||||||
}
|
"Meta": null,
|
||||||
},
|
"Port": 80,
|
||||||
"Meta": null,
|
"EnableTagOverride": false,
|
||||||
"Port": 80,
|
"Connect": {
|
||||||
"EnableTagOverride": false,
|
"Native": false,
|
||||||
"Connect": {
|
"Proxy": null
|
||||||
"Native": false,
|
},
|
||||||
"Proxy": null
|
"CreateIndex": 0,
|
||||||
},
|
"ModifyIndex": 0
|
||||||
"CreateIndex": 0,
|
}
|
||||||
"ModifyIndex": 0
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -415,33 +408,31 @@ curl localhost:8500/v1/agent/health/service/id/web1
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"passing": {
|
"passing": {
|
||||||
"ID": "web1",
|
"ID": "web1",
|
||||||
"Service": "web",
|
"Service": "web",
|
||||||
"Tags": [
|
"Tags": ["rails"],
|
||||||
"rails"
|
"Address": "",
|
||||||
],
|
"TaggedAddresses": {
|
||||||
"Address": "",
|
"lan": {
|
||||||
"TaggedAddresses": {
|
"address": "127.0.0.1",
|
||||||
"lan": {
|
"port": 8000
|
||||||
"address": "127.0.0.1",
|
},
|
||||||
"port": 8000
|
"wan": {
|
||||||
},
|
"address": "198.18.0.53",
|
||||||
"wan": {
|
"port": 80
|
||||||
"address": "198.18.0.53",
|
}
|
||||||
"port": 80
|
},
|
||||||
}
|
"Meta": null,
|
||||||
},
|
"Port": 80,
|
||||||
"Meta": null,
|
"EnableTagOverride": false,
|
||||||
"Port": 80,
|
"Connect": {
|
||||||
"EnableTagOverride": false,
|
"Native": false,
|
||||||
"Connect": {
|
"Proxy": null
|
||||||
"Native": false,
|
},
|
||||||
"Proxy": null
|
"CreateIndex": 0,
|
||||||
},
|
"ModifyIndex": 0
|
||||||
"CreateIndex": 0,
|
}
|
||||||
"ModifyIndex": 0
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -471,9 +462,9 @@ catalog in sync.
|
||||||
For "connect-proxy" kind services, the `service:write` ACL for the
|
For "connect-proxy" kind services, the `service:write` ACL for the
|
||||||
`Proxy.DestinationServiceName` value is also required to register the service.
|
`Proxy.DestinationServiceName` value is also required to register the service.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/service/register` | `application/json` |
|
| `PUT` | `/agent/service/register` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -568,14 +559,14 @@ service definition keys for compatibility with the config file format.
|
||||||
weights. If this field is not provided weights will default to
|
weights. If this field is not provided weights will default to
|
||||||
`{"Passing": 1, "Warning": 1}`.
|
`{"Passing": 1, "Warning": 1}`.
|
||||||
|
|
||||||
It is important to note that this applies only to the locally registered
|
It is important to note that this applies only to the locally registered
|
||||||
service. If you have multiple nodes all registering the same service their
|
service. If you have multiple nodes all registering the same service their
|
||||||
`EnableTagOverride` configuration and all other service configuration items
|
`EnableTagOverride` configuration and all other service configuration items
|
||||||
are independent of one another. Updating the tags for the service registered
|
are independent of one another. Updating the tags for the service registered
|
||||||
on one node is independent of the same service (by name) registered on
|
on one node is independent of the same service (by name) registered on
|
||||||
another node. If `EnableTagOverride` is not specified the default value is
|
another node. If `EnableTagOverride` is not specified the default value is
|
||||||
`false`. See [anti-entropy syncs](/docs/internals/anti-entropy.html) for
|
`false`. See [anti-entropy syncs](/docs/internals/anti-entropy.html) for
|
||||||
more info.
|
more info.
|
||||||
|
|
||||||
#### Connect Structure
|
#### Connect Structure
|
||||||
|
|
||||||
|
|
@ -600,10 +591,7 @@ For the `Connect` field, the parameters are:
|
||||||
{
|
{
|
||||||
"ID": "redis1",
|
"ID": "redis1",
|
||||||
"Name": "redis",
|
"Name": "redis",
|
||||||
"Tags": [
|
"Tags": ["primary", "v1"],
|
||||||
"primary",
|
|
||||||
"v1"
|
|
||||||
],
|
|
||||||
"Address": "127.0.0.1",
|
"Address": "127.0.0.1",
|
||||||
"Port": 8000,
|
"Port": 8000,
|
||||||
"Meta": {
|
"Meta": {
|
||||||
|
|
@ -640,8 +628,8 @@ exist, no action is taken.
|
||||||
The agent will take care of deregistering the service with the catalog. If there
|
The agent will take care of deregistering the service with the catalog. If there
|
||||||
is an associated check, that is also deregistered.
|
is an associated check, that is also deregistered.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/service/deregister/:service_id` | `application/json` |
|
| `PUT` | `/agent/service/deregister/:service_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
|
|
@ -674,9 +662,9 @@ mode, the service will be marked as unavailable and will not be present in DNS
|
||||||
or API queries. This API call is idempotent. Maintenance mode is persistent and
|
or API queries. This API call is idempotent. Maintenance mode is persistent and
|
||||||
will be automatically restored on agent restart.
|
will be automatically restored on agent restart.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------------------------- | ------------------ |
|
||||||
| `PUT` | `/agent/service/maintenance/:service_id` | `application/json` |
|
| `PUT` | `/agent/service/maintenance/:service_id` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -20,9 +20,9 @@ entries in the catalog. It is usually preferable to instead use the
|
||||||
[agent endpoints](/api/agent.html) for registration as they are simpler and
|
[agent endpoints](/api/agent.html) for registration as they are simpler and
|
||||||
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `PUT` | `/catalog/register` | `application/json` |
|
| `PUT` | `/catalog/register` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -30,9 +30,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------------------- |
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
||||||
| `NO` | `none` | `none` |`node:write,service:write` |
|
| `NO` | `none` | `none` | `node:write,service:write` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -67,36 +67,35 @@ The table below shows this endpoint's support for
|
||||||
health check, the check must either be provided in agent configuration or set
|
health check, the check must either be provided in agent configuration or set
|
||||||
via the [agent endpoint](agent.html).
|
via the [agent endpoint](agent.html).
|
||||||
|
|
||||||
The `CheckID` can be omitted and will default to the value of `Name`. As
|
The `CheckID` can be omitted and will default to the value of `Name`. As
|
||||||
with `Service.ID`, the `CheckID` must be unique on this node. `Notes` is an
|
with `Service.ID`, the `CheckID` must be unique on this node. `Notes` is an
|
||||||
opaque field that is meant to hold human-readable text. If a `ServiceID` is
|
opaque field that is meant to hold human-readable text. If a `ServiceID` is
|
||||||
provided that matches the `ID` of a service on that node, the check is
|
provided that matches the `ID` of a service on that node, the check is
|
||||||
treated as a service level health check, instead of a node level health
|
treated as a service level health check, instead of a node level health
|
||||||
check. The `Status` must be one of `passing`, `warning`, or `critical`.
|
check. The `Status` must be one of `passing`, `warning`, or `critical`.
|
||||||
|
|
||||||
The `Definition` field can be provided with details for a TCP or HTTP health
|
The `Definition` field can be provided with details for a TCP or HTTP health
|
||||||
check. For more information, see the [Health Checks](/docs/agent/checks.html) page.
|
check. For more information, see the [Health Checks](/docs/agent/checks.html) page.
|
||||||
|
|
||||||
Multiple checks can be provided by replacing `Check` with `Checks` and
|
Multiple checks can be provided by replacing `Check` with `Checks` and
|
||||||
sending an array of `Check` objects.
|
sending an array of `Check` objects.
|
||||||
|
|
||||||
- `SkipNodeUpdate` `(bool: false)` - Specifies whether to skip updating the
|
- `SkipNodeUpdate` `(bool: false)` - Specifies whether to skip updating the
|
||||||
node's information in the registration. This is useful in the case where
|
node's information in the registration. This is useful in the case where
|
||||||
only a health check or service entry on a node needs to be updated or when
|
only a health check or service entry on a node needs to be updated or when
|
||||||
a register request is intended to update a service entry or health check.
|
a register request is intended to update a service entry or health check.
|
||||||
In both use cases, node information will not be overwritten, if the node is
|
In both use cases, node information will not be overwritten, if the node is
|
||||||
already registered. Note, if the parameter is enabled for a node that doesn't
|
already registered. Note, if the parameter is enabled for a node that doesn't
|
||||||
exist, it will still be created.
|
exist, it will still be created.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace in which the
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace in which the
|
||||||
service and checks will be registered. This value may be provided by either the
|
service and checks will be registered. This value may be provided by either the
|
||||||
`ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally,
|
`ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally,
|
||||||
the namespace may be provided within the `Service` or `Check` fields but if
|
the namespace may be provided within the `Service` or `Check` fields but if
|
||||||
present in multiple places, they must all be the same. If not provided at all,
|
present in multiple places, they must all be the same. If not provided at all,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
||||||
It is important to note that `Check` does not have to be provided with `Service`
|
It is important to note that `Check` does not have to be provided with `Service`
|
||||||
and vice versa. A catalog entry can have either, neither, or both.
|
and vice versa. A catalog entry can have either, neither, or both.
|
||||||
|
|
||||||
|
|
@ -118,10 +117,7 @@ and vice versa. A catalog entry can have either, neither, or both.
|
||||||
"Service": {
|
"Service": {
|
||||||
"ID": "redis1",
|
"ID": "redis1",
|
||||||
"Service": "redis",
|
"Service": "redis",
|
||||||
"Tags": [
|
"Tags": ["primary", "v1"],
|
||||||
"primary",
|
|
||||||
"v1"
|
|
||||||
],
|
|
||||||
"Address": "127.0.0.1",
|
"Address": "127.0.0.1",
|
||||||
"TaggedAddresses": {
|
"TaggedAddresses": {
|
||||||
"lan": {
|
"lan": {
|
||||||
|
|
@ -134,7 +130,7 @@ and vice versa. A catalog entry can have either, neither, or both.
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"redis_version": "4.0"
|
"redis_version": "4.0"
|
||||||
},
|
},
|
||||||
"Port": 8000,
|
"Port": 8000,
|
||||||
"Namespace": "default"
|
"Namespace": "default"
|
||||||
|
|
@ -154,7 +150,7 @@ and vice versa. A catalog entry can have either, neither, or both.
|
||||||
},
|
},
|
||||||
"Namespace": "default"
|
"Namespace": "default"
|
||||||
},
|
},
|
||||||
"SkipNodeUpdate": false,
|
"SkipNodeUpdate": false
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -175,9 +171,9 @@ entries from the Catalog. It is usually preferable to instead use the
|
||||||
[agent endpoints](/api/agent.html) for deregistration as they are simpler and
|
[agent endpoints](/api/agent.html) for deregistration as they are simpler and
|
||||||
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------- | ------------------ |
|
||||||
| `PUT` | `/catalog/deregister` | `application/json` |
|
| `PUT` | `/catalog/deregister` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -204,11 +200,11 @@ The behavior of the endpoint depends on what keys are provided.
|
||||||
|
|
||||||
- `ServiceID` `(string: "")` - Specifies the ID of the service to remove. The
|
- `ServiceID` `(string: "")` - Specifies the ID of the service to remove. The
|
||||||
service and all associated checks will be removed.
|
service and all associated checks will be removed.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace in which the
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace in which the
|
||||||
service and checks will be deregistered. If not provided in the JSON body, the value of
|
service and checks will be deregistered. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided at all, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payloads
|
### Sample Payloads
|
||||||
|
|
@ -257,9 +253,9 @@ This endpoint does not require a cluster leader and will succeed even during an
|
||||||
availability outage. Therefore, it can be used as a simple check to see if any
|
availability outage. Therefore, it can be used as a simple check to see if any
|
||||||
Consul servers are routable.
|
Consul servers are routable.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `GET` | `/catalog/datacenters` | `application/json` |
|
| `GET` | `/catalog/datacenters` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -288,9 +284,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint and returns the nodes registered in a given datacenter.
|
This endpoint and returns the nodes registered in a given datacenter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `GET` | `/catalog/nodes` | `application/json` |
|
| `GET` | `/catalog/nodes` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -377,14 +373,13 @@ the following selectors and filter operations being supported:
|
||||||
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
||||||
| `TaggedAddresses.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `TaggedAddresses.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
|
|
||||||
|
|
||||||
## List Services
|
## List Services
|
||||||
|
|
||||||
This endpoint returns the services registered in a given datacenter.
|
This endpoint returns the services registered in a given datacenter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `GET` | `/catalog/services` | `application/json` |
|
| `GET` | `/catalog/services` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -406,9 +401,9 @@ The table below shows this endpoint's support for
|
||||||
of the form `key:value`. This parameter can be specified multiple times, and
|
of the form `key:value`. This parameter can be specified multiple times, and
|
||||||
will filter the results to nodes with the specified key/value pairs. This is
|
will filter the results to nodes with the specified key/value pairs. This is
|
||||||
specified as part of the URL as a query parameter.
|
specified as part of the URL as a query parameter.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list services.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list services.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
@ -425,10 +420,7 @@ $ curl \
|
||||||
{
|
{
|
||||||
"consul": [],
|
"consul": [],
|
||||||
"redis": [],
|
"redis": [],
|
||||||
"postgresql": [
|
"postgresql": ["primary", "secondary"]
|
||||||
"primary",
|
|
||||||
"secondary"
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -439,9 +431,9 @@ a given service.
|
||||||
|
|
||||||
This endpoint returns the nodes providing a service in a given datacenter.
|
This endpoint returns the nodes providing a service in a given datacenter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `GET` | `/catalog/service/:service` | `application/json` |
|
| `GET` | `/catalog/service/:service` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -478,9 +470,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to use for the
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to use for the
|
||||||
query. This value may be provided by either the `ns` URL query parameter or in the
|
query. This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
@ -515,7 +507,7 @@ $ curl \
|
||||||
"ServiceName": "foobar",
|
"ServiceName": "foobar",
|
||||||
"ServicePort": 5000,
|
"ServicePort": 5000,
|
||||||
"ServiceMeta": {
|
"ServiceMeta": {
|
||||||
"foobar_meta_value": "baz"
|
"foobar_meta_value": "baz"
|
||||||
},
|
},
|
||||||
"ServiceTaggedAddresses": {
|
"ServiceTaggedAddresses": {
|
||||||
"lan": {
|
"lan": {
|
||||||
|
|
@ -527,20 +519,18 @@ $ curl \
|
||||||
"port": 512
|
"port": 512
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"ServiceTags": [
|
"ServiceTags": ["tacos"],
|
||||||
"tacos"
|
|
||||||
],
|
|
||||||
"ServiceProxy": {
|
"ServiceProxy": {
|
||||||
"DestinationServiceName": "",
|
"DestinationServiceName": "",
|
||||||
"DestinationServiceID": "",
|
"DestinationServiceID": "",
|
||||||
"LocalServiceAddress": "",
|
"LocalServiceAddress": "",
|
||||||
"LocalServicePort": 0,
|
"LocalServicePort": 0,
|
||||||
"Config": null,
|
"Config": null,
|
||||||
"Upstreams": null
|
"Upstreams": null
|
||||||
},
|
},
|
||||||
"ServiceConnect": {
|
"ServiceConnect": {
|
||||||
"Native": false,
|
"Native": false,
|
||||||
"Proxy": null
|
"Proxy": null
|
||||||
},
|
},
|
||||||
"Namespace": "default"
|
"Namespace": "default"
|
||||||
}
|
}
|
||||||
|
|
@ -588,12 +578,12 @@ $ curl \
|
||||||
registration API for more information.
|
registration API for more information.
|
||||||
|
|
||||||
- `ServiceProxy` is the proxy config as specified in
|
- `ServiceProxy` is the proxy config as specified in
|
||||||
[Connect Proxies](/docs/connect/proxies.html).
|
[Connect Proxies](/docs/connect/proxies.html).
|
||||||
|
|
||||||
- `ServiceConnect` are the [Connect](/docs/connect/index.html) settings. The
|
- `ServiceConnect` are the [Connect](/docs/connect/index.html) settings. The
|
||||||
value of this struct is equivalent to the `Connect` field for service
|
value of this struct is equivalent to the `Connect` field for service
|
||||||
registration.
|
registration.
|
||||||
|
|
||||||
- `Namespace` is the Consul Enterprise namespace of this service instance
|
- `Namespace` is the Consul Enterprise namespace of this service instance
|
||||||
|
|
||||||
### Filtering
|
### Filtering
|
||||||
|
|
@ -602,7 +592,7 @@ Filtering is executed against each entry in the top level result list with the
|
||||||
following selectors and filter operations being supported:
|
following selectors and filter operations being supported:
|
||||||
|
|
||||||
| Selector | Supported Operations |
|
| Selector | Supported Operations |
|
||||||
| --------------------------------------------- | ------------------------------------------------- |
|
| --------------------------------------------- | -------------------------------------------------- |
|
||||||
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
| `Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
|
|
@ -648,9 +638,9 @@ This will include both proxies and native integrations. A service may
|
||||||
register both Connect-capable and incapable services at the same time,
|
register both Connect-capable and incapable services at the same time,
|
||||||
so this endpoint may be used to filter only the Connect-capable endpoints.
|
so this endpoint may be used to filter only the Connect-capable endpoints.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `GET` | `/catalog/connect/:service` | `application/json` |
|
| `GET` | `/catalog/connect/:service` | `application/json` |
|
||||||
|
|
||||||
Parameters and response format are the same as
|
Parameters and response format are the same as
|
||||||
[`/catalog/service/:service`](/api/catalog.html#list-nodes-for-service).
|
[`/catalog/service/:service`](/api/catalog.html#list-nodes-for-service).
|
||||||
|
|
@ -659,9 +649,9 @@ Parameters and response format are the same as
|
||||||
|
|
||||||
This endpoint returns the node's registered services.
|
This endpoint returns the node's registered services.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------- | ------------------ |
|
||||||
| `GET` | `/catalog/node/:node` | `application/json` |
|
| `GET` | `/catalog/node/:node` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -684,9 +674,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list services.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list services.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
@ -728,16 +718,14 @@ $ curl \
|
||||||
"TaggedAddresses": {
|
"TaggedAddresses": {
|
||||||
"lan": {
|
"lan": {
|
||||||
"address": "10.1.10.12",
|
"address": "10.1.10.12",
|
||||||
"port": 8000,
|
"port": 8000
|
||||||
},
|
},
|
||||||
"wan": {
|
"wan": {
|
||||||
"address": "198.18.1.2",
|
"address": "198.18.1.2",
|
||||||
"port": 80
|
"port": 80
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"Tags": [
|
"Tags": ["v1"],
|
||||||
"v1"
|
|
||||||
],
|
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"redis_version": "4.0"
|
"redis_version": "4.0"
|
||||||
},
|
},
|
||||||
|
|
@ -788,9 +776,9 @@ top level Node object. The following selectors and filter operations are support
|
||||||
|
|
||||||
This endpoint returns the node's registered services.
|
This endpoint returns the node's registered services.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------ | -------------------------- |
|
| ------ | ------------------------------ | ------------------ |
|
||||||
| `GET` | `/catalog/node-services/:node` | `application/json` |
|
| `GET` | `/catalog/node-services/:node` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -813,9 +801,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list services.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list services.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. The `*`
|
from the request's ACL token or will default to the `default` namespace. The `*`
|
||||||
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
|
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
|
||||||
|
|
@ -20,9 +20,9 @@ of the configuration entries content.
|
||||||
|
|
||||||
This endpoint creates or updates the given config entry.
|
This endpoint creates or updates the given config entry.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------- | ------------------ |
|
||||||
| `PUT` | `/config` | `application/json` |
|
| `PUT` | `/config` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -30,8 +30,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------- |
|
| ---------------- | ----------------- | ------------- | ----------------------------------------------- |
|
||||||
| `NO` | `none` | `none` | `service:write`<br>`operator:write`<sup>1</sup> |
|
| `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:
|
<sup>1</sup> The ACL required depends on the config entry kind being updated:
|
||||||
|
|
@ -53,14 +53,13 @@ The table below shows this endpoint's support for
|
||||||
of that entry.
|
of that entry.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace the config
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace the config
|
||||||
entry will apply to. This value may be provided by either the `ns` URL query
|
entry will apply to. This value may be provided by either the `ns` URL query
|
||||||
parameter or in the `X-Consul-Namespace` header. If not provided at all,
|
parameter or in the `X-Consul-Namespace` header. If not provided at all,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
{
|
{
|
||||||
"Kind": "service-defaults",
|
"Kind": "service-defaults",
|
||||||
|
|
@ -82,9 +81,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint returns a specific config entry.
|
This endpoint returns a specific config entry.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------- | ------------------ |
|
||||||
| `GET` | `/config/:kind/:name` | `application/json` |
|
| `GET` | `/config/:kind/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -92,16 +91,16 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------- |
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
||||||
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
||||||
|
|
||||||
| Config Entry Kind | Required ACL |
|
| Config Entry Kind | Required ACL |
|
||||||
| ----------------- | ---------------- |
|
| ----------------- | -------------- |
|
||||||
| service-defaults | `service:read` |
|
| service-defaults | `service:read` |
|
||||||
| proxy-defaults | `<none>` |
|
| proxy-defaults | `<none>` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -115,9 +114,9 @@ The table below shows this endpoint's support for
|
||||||
- `name` `(string: <required>)` - Specifies the name of the entry to read. This
|
- `name` `(string: <required>)` - Specifies the name of the entry to read. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited from
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited from
|
||||||
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
@ -132,11 +131,11 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Kind": "service-defaults",
|
"Kind": "service-defaults",
|
||||||
"Name": "web",
|
"Name": "web",
|
||||||
"Protocol": "http",
|
"Protocol": "http",
|
||||||
"CreateIndex": 15,
|
"CreateIndex": 15,
|
||||||
"ModifyIndex": 35
|
"ModifyIndex": 35
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -144,9 +143,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint returns all config entries of the given kind.
|
This endpoint returns all config entries of the given kind.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------- | ------------------ |
|
||||||
| `GET` | `/config/:kind` | `application/json` |
|
| `GET` | `/config/:kind` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -154,16 +153,16 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------- |
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
||||||
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
||||||
|
|
||||||
| Config Entry Kind | Required ACL |
|
| Config Entry Kind | Required ACL |
|
||||||
| ----------------- | ---------------- |
|
| ----------------- | -------------- |
|
||||||
| service-defaults | `service:read` |
|
| service-defaults | `service:read` |
|
||||||
| proxy-defaults | `<none>` |
|
| proxy-defaults | `<none>` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -174,9 +173,9 @@ The table below shows this endpoint's support for
|
||||||
- `kind` `(string: <required>)` - Specifies the kind of the entry to list. This
|
- `kind` `(string: <required>)` - Specifies the kind of the entry to list. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited from
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited from
|
||||||
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
@ -191,20 +190,20 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"Kind": "service-defaults",
|
"Kind": "service-defaults",
|
||||||
"Name": "db",
|
"Name": "db",
|
||||||
"Protocol": "tcp",
|
"Protocol": "tcp",
|
||||||
"CreateIndex": 16,
|
"CreateIndex": 16,
|
||||||
"ModifyIndex": 16
|
"ModifyIndex": 16
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Kind": "service-defaults",
|
"Kind": "service-defaults",
|
||||||
"Name": "web",
|
"Name": "web",
|
||||||
"Protocol": "http",
|
"Protocol": "http",
|
||||||
"CreateIndex": 13,
|
"CreateIndex": 13,
|
||||||
"ModifyIndex": 13
|
"ModifyIndex": 13
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -212,9 +211,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint deletes the given config entry.
|
This endpoint deletes the given config entry.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ---------------------------- | -------------------------- |
|
| -------- | --------------------- | ------------------ |
|
||||||
| `DELETE` | `/config/:kind/:name` | `application/json` |
|
| `DELETE` | `/config/:kind/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -222,8 +221,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------- |
|
| ---------------- | ----------------- | ------------- | ----------------------------------------------- |
|
||||||
| `NO` | `none` | `none` | `service:write`<br>`operator:write`<sup>1</sup> |
|
| `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:
|
<sup>1</sup> The ACL required depends on the config entry kind being deleted:
|
||||||
|
|
@ -245,8 +244,8 @@ The table below shows this endpoint's support for
|
||||||
- `name` `(string: <required>)` - Specifies the name of the entry to delete. This
|
- `name` `(string: <required>)` - Specifies the name of the entry to delete. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to delete from.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to delete from.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
@ -0,0 +1,165 @@
|
||||||
|
---
|
||||||
|
layout: api
|
||||||
|
page_title: Certificate Authority - Connect - HTTP API
|
||||||
|
sidebar_current: api-connect-ca
|
||||||
|
description: |-
|
||||||
|
The /connect/ca endpoints provide tools for interacting with Connect's
|
||||||
|
Certificate Authority mechanism via Consul's HTTP API.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Certificate Authority (CA) - Connect HTTP API
|
||||||
|
|
||||||
|
The `/connect/ca` endpoints provide tools for interacting with Connect's
|
||||||
|
Certificate Authority mechanism.
|
||||||
|
|
||||||
|
## List CA Root Certificates
|
||||||
|
|
||||||
|
This endpoint returns the current list of trusted CA root certificates in
|
||||||
|
the cluster.
|
||||||
|
|
||||||
|
| Method | Path | Produces |
|
||||||
|
| ------ | ------------------- | ------------------ |
|
||||||
|
| `GET` | `/connect/ca/roots` | `application/json` |
|
||||||
|
|
||||||
|
The table below shows this endpoint's support for
|
||||||
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
[consistency modes](/api/features/consistency.html),
|
||||||
|
[agent caching](/api/features/caching.html), and
|
||||||
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
|
| ---------------- | ----------------- | ------------- | ------------ |
|
||||||
|
| `YES` | `all` | `none` | `none` |
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl \
|
||||||
|
http://127.0.0.1:8500/v1/connect/ca/roots
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"ActiveRootID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
|
||||||
|
"TrustDomain": "7f42f496-fbc7-8692-05ed-334aa5340c1e.consul",
|
||||||
|
"Roots": [
|
||||||
|
{
|
||||||
|
"ID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
|
||||||
|
"Name": "Consul CA Root Cert",
|
||||||
|
"SerialNumber": 7,
|
||||||
|
"SigningKeyID": "2d:09:5d:84:b9:89:4b:dd:e3:88:bb:9c:e2:b2:69:81:1f:4b:a6:fd:4d:df:ee:74:63:f3:74:55:ca:b0:b5:65",
|
||||||
|
"ExternalTrustDomain": "a1499528-fbf6-df7b-05e5-ae81e1873fc4",
|
||||||
|
"NotBefore": "2018-05-25T21:39:23Z",
|
||||||
|
"NotAfter": "2028-05-22T21:39:23Z",
|
||||||
|
"RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjUyMTM5MjNaFw0yODA1MjIyMTM5MjNaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEq4S32Pu0/VL4\nG75gvdyQuAhqMZFsfBRwD3pgvblgZMeJc9KDosxnPR+W34NXtMD/860NNVJIILln\n9lLhIjWPQqOCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDplMzo4ODpiYjo5Yzpl\nMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2MzpmMzo3NDo1NTpj\nYTpiMDpiNTo2NTBqBgNVHSMEYzBhgF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDpl\nMzo4ODpiYjo5YzplMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2\nMzpmMzo3NDo1NTpjYTpiMDpiNTo2NTA/BgNVHREEODA2hjRzcGlmZmU6Ly83ZjQy\nZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgis3ZjQyZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIBBBDOWXWApx4S6bHJ49AW87Nw8uQ/gJ\nJ6lvm3HzEQw2AiEA4PVqWt+z8fsQht0cACM42kghL97SgDSf8rgCqfLYMng=\n-----END CERTIFICATE-----\n",
|
||||||
|
"IntermediateCerts": null,
|
||||||
|
"Active": true,
|
||||||
|
"PrivateKeyType": "ec",
|
||||||
|
"PrivateKeyBits": 256,
|
||||||
|
"CreateIndex": 8,
|
||||||
|
"ModifyIndex": 8
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Get CA Configuration
|
||||||
|
|
||||||
|
This endpoint returns the current CA configuration.
|
||||||
|
|
||||||
|
| Method | Path | Produces |
|
||||||
|
| ------ | --------------------------- | ------------------ |
|
||||||
|
| `GET` | `/connect/ca/configuration` | `application/json` |
|
||||||
|
|
||||||
|
The table below shows this endpoint's support for
|
||||||
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
[consistency modes](/api/features/consistency.html),
|
||||||
|
[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` |
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl \
|
||||||
|
http://127.0.0.1:8500/v1/connect/ca/configuration
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Provider": "consul",
|
||||||
|
"Config": {
|
||||||
|
"LeafCertTTL": "72h",
|
||||||
|
"RotationPeriod": "2160h",
|
||||||
|
"IntermediateCertTTL": "8760h"
|
||||||
|
},
|
||||||
|
"CreateIndex": 5,
|
||||||
|
"ModifyIndex": 5
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Update CA Configuration
|
||||||
|
|
||||||
|
This endpoint updates the configuration for the CA. If this results in a
|
||||||
|
new root certificate being used, the [Root Rotation](/docs/connect/ca.html#root-certificate-rotation) process will be triggered.
|
||||||
|
|
||||||
|
| Method | Path | Produces |
|
||||||
|
| ------ | --------------------------- | ------------------ |
|
||||||
|
| `PUT` | `/connect/ca/configuration` | `application/json` |
|
||||||
|
|
||||||
|
The table below shows this endpoint's support for
|
||||||
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
[consistency modes](/api/features/consistency.html),
|
||||||
|
[agent caching](/api/features/caching.html), and
|
||||||
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||||
|
| `NO` | `none` | `none` | `operator:write` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `Provider` `(string: <required>)` - Specifies the CA provider type to use.
|
||||||
|
|
||||||
|
- `Config` `(map[string]string: <required>)` - The raw configuration to use
|
||||||
|
for the chosen provider. For more information on configuring the Connect CA
|
||||||
|
providers, see [Provider Config](/docs/connect/ca.html).
|
||||||
|
|
||||||
|
- `ForceWithoutCrossSigning` `(bool: <optional>)` - Indicates that the CA change
|
||||||
|
should be force to complete even if the current CA doesn't support cross
|
||||||
|
signing. Changing root without cross-signing may cause temporary connection
|
||||||
|
failures until the rollout completes. See [Forced Rotation Without
|
||||||
|
Cross-Signing](/docs/connect/ca.html#forced-rotation-without-cross-signing)
|
||||||
|
for more detail.
|
||||||
|
|
||||||
|
### Sample Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Provider": "consul",
|
||||||
|
"Config": {
|
||||||
|
"LeafCertTTL": "72h",
|
||||||
|
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----...",
|
||||||
|
"RootCert": "-----BEGIN CERTIFICATE-----...",
|
||||||
|
"RotationPeriod": "2160h",
|
||||||
|
"IntermediateCertTTL": "8760h"
|
||||||
|
},
|
||||||
|
"ForceWithoutCrossSigning": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl \
|
||||||
|
--request PUT \
|
||||||
|
--data @payload.json \
|
||||||
|
http://127.0.0.1:8500/v1/connect/ca/configuration
|
||||||
|
```
|
||||||
|
|
@ -21,9 +21,9 @@ The name and destination pair must be unique. If another intention matches
|
||||||
the name and destination, the creation will fail. You must either update the
|
the name and destination, the creation will fail. You must either update the
|
||||||
existing intention or delete it prior to creating a new one.
|
existing intention or delete it prior to creating a new one.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------- | ------------------ |
|
||||||
| `POST` | `/connect/intentions` | `application/json` |
|
| `POST` | `/connect/intentions` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -31,9 +31,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------------------------- |
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<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.
|
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
|
||||||
|
|
@ -92,9 +92,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint reads a specific intention.
|
This endpoint reads a specific intention.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -102,8 +102,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | --------------- |
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||||
|
|
@ -148,9 +148,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint lists all intentions.
|
This endpoint lists all intentions.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------- | ------------------ |
|
||||||
| `GET` | `/connect/intentions` | `application/json` |
|
| `GET` | `/connect/intentions` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -158,8 +158,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | --------------- |
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||||
|
|
@ -227,9 +227,9 @@ the following selectors and filter operations being supported:
|
||||||
|
|
||||||
This endpoint updates an intention with the given values.
|
This endpoint updates an intention with the given values.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -237,11 +237,10 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<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.
|
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
|
||||||
|
|
||||||
|
|
@ -276,9 +275,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint deletes a specific intention.
|
This endpoint deletes a specific intention.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ---------------------------- | -------------------------- |
|
| -------- | --------------------------- | ------------------ |
|
||||||
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
|
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -286,11 +285,10 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | --------------- |
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<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.
|
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
|
||||||
|
|
||||||
|
|
@ -317,10 +315,9 @@ This endpoint will work even if the destination service has
|
||||||
`intention = "deny"` specifically set, because the resulting API response
|
`intention = "deny"` specifically set, because the resulting API response
|
||||||
does not contain any information about the intention itself.
|
does not contain any information about the intention itself.
|
||||||
|
|
||||||
|
| Method | Path | Produces |
|
||||||
| Method | Path | Produces |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| `GET` | `/connect/intentions/check` | `application/json` |
|
||||||
| `GET` | `/connect/intentions/check` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -328,8 +325,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | -------------- |
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||||
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||||
|
|
@ -365,9 +362,9 @@ $ curl \
|
||||||
This endpoint lists the intentions that match a given source or destination.
|
This endpoint lists the intentions that match a given source or destination.
|
||||||
The intentions in the response are in evaluation order.
|
The intentions in the response are in evaluation order.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------ | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `GET` | `/connect/intentions/match` | `application/json` |
|
| `GET` | `/connect/intentions/match` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -375,8 +372,8 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | -------------- |
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||||
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||||
|
|
@ -25,9 +25,9 @@ organized by datacenters. It serves data out of the server's local Serf data, so
|
||||||
its results may vary as requests are handled by different servers in the
|
its results may vary as requests are handled by different servers in the
|
||||||
cluster.
|
cluster.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------- | ------------------ |
|
||||||
| `GET` | `/coordinate/datacenters` | `application/json` |
|
| `GET` | `/coordinate/datacenters` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -77,9 +77,9 @@ within the same area.
|
||||||
This endpoint returns the LAN network coordinates for all nodes in a given
|
This endpoint returns the LAN network coordinates for all nodes in a given
|
||||||
datacenter.
|
datacenter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `GET` | `/coordinate/nodes` | `application/json` |
|
| `GET` | `/coordinate/nodes` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -134,9 +134,9 @@ segment.
|
||||||
|
|
||||||
This endpoint returns the LAN network coordinates for the given node.
|
This endpoint returns the LAN network coordinates for the given node.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------ | ------------------ |
|
||||||
| `GET` | `/coordinate/node/:node` | `application/json` |
|
| `GET` | `/coordinate/node/:node` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -192,9 +192,9 @@ segment.
|
||||||
This endpoint updates the LAN network coordinates for a node in a given
|
This endpoint updates the LAN network coordinates for a node in a given
|
||||||
datacenter.
|
datacenter.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------- | ------------------ |
|
||||||
| `PUT` | `/coordinate/update` | `application/json` |
|
| `PUT` | `/coordinate/update` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -0,0 +1,563 @@
|
||||||
|
---
|
||||||
|
layout: api
|
||||||
|
page_title: Discovery Chain - HTTP API
|
||||||
|
sidebar_current: api-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.
|
||||||
|
|
||||||
|
# Discovery Chain HTTP Endpoint
|
||||||
|
|
||||||
|
~> This is a low-level API primarily targeted at developers building external
|
||||||
|
[Connect proxy integrations](/docs/connect/proxies/integrate.html). Future
|
||||||
|
high-level proxy integration APIs may obviate the need for this API over time.
|
||||||
|
|
||||||
|
The `/discovery-chain` endpoint returns the compiled [discovery
|
||||||
|
chain](/docs/internals/discovery-chain.html) for a service.
|
||||||
|
|
||||||
|
This will fetch all related [configuration
|
||||||
|
entries](/docs/agent/config_entries.html) and render them into a form suitable
|
||||||
|
for use by a [connect proxy](/docs/connect/proxies.html) implementation. This
|
||||||
|
is a key component of [L7 Traffic
|
||||||
|
Management](/docs/connect/l7-traffic-management.html).
|
||||||
|
|
||||||
|
## Read Compiled Discovery Chain
|
||||||
|
|
||||||
|
If overrides are needed they are passed as the JSON-encoded request body and
|
||||||
|
the `POST` method must be used, otherwise `GET` is sufficient.
|
||||||
|
|
||||||
|
| Method | Path | Produces |
|
||||||
|
| ------------------ | --------------------------- | ------------------ |
|
||||||
|
| `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.
|
||||||
|
|
||||||
|
The table below shows this endpoint's support for
|
||||||
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
[consistency modes](/api/features/consistency.html),
|
||||||
|
[agent caching](/api/features/caching.html), and
|
||||||
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
|
| ---------------- | ----------------- | -------------------- | -------------- |
|
||||||
|
| `YES` | `all` | `background refresh` | `service:read` |
|
||||||
|
|
||||||
|
### URL Parameters
|
||||||
|
|
||||||
|
- `service` `(string: <required>)` - Specifies the service to query when
|
||||||
|
compiling the discovery chain. This is provided as part of the URL.
|
||||||
|
|
||||||
|
- `compile-dc` `(string: "")` - Specifies the datacenter to use as the basis of
|
||||||
|
compilation. This will default to the datacenter of the agent being queried.
|
||||||
|
This is specified as part of the URL as a query parameter.
|
||||||
|
|
||||||
|
This value comes from an [upstream
|
||||||
|
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
|
||||||
|
[`datacenter`](/docs/connect/registration/service-registration.html#datacenter)
|
||||||
|
parameter.
|
||||||
|
|
||||||
|
### POST Body Parameters
|
||||||
|
|
||||||
|
- `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect
|
||||||
|
timeout](/docs/agent/config-entries/service-resolver.html#connecttimeout) for
|
||||||
|
any service resolved in the compiled chain.
|
||||||
|
|
||||||
|
This value comes from the `connect_timeout_ms` key in an [upstream
|
||||||
|
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
|
||||||
|
opaque
|
||||||
|
[`config`](/docs/connect/registration/service-registration.html#config-1)
|
||||||
|
parameter.
|
||||||
|
|
||||||
|
- `OverrideProtocol` `(string: "")` - Overrides the final
|
||||||
|
[protocol](/docs/agent/config-entries/service-defaults.html#protocol) used in
|
||||||
|
the compiled discovery chain.
|
||||||
|
|
||||||
|
If the chain ordinarily would be TCP and an L7 protocol is passed here the
|
||||||
|
chain will still not include Routers or Splitters. If the chain ordinarily
|
||||||
|
would be L7 and TCP is passed here the chain will not include Routers or
|
||||||
|
Splitters.
|
||||||
|
|
||||||
|
This value comes from the `protocol` key in an [upstream
|
||||||
|
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
|
||||||
|
opaque
|
||||||
|
[`config`](/docs/connect/registration/service-registration.html#config-1)
|
||||||
|
parameter.
|
||||||
|
|
||||||
|
- `OverrideMeshGateway` `(MeshGatewayConfig: <optional>)` - Overrides the final
|
||||||
|
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration)
|
||||||
|
for this any service resolved in the compiled chain.
|
||||||
|
|
||||||
|
This value comes from either the [proxy
|
||||||
|
configuration](/docs/connect/registration/service-registration.html#complete-configuration-example)
|
||||||
|
[`mesh_gateway`](/docs/connect/registration/service-registration.html#mesh_gateway)
|
||||||
|
parameter or an [upstream
|
||||||
|
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
|
||||||
|
[`mesh_gateway`](/docs/connect/registration/service-registration.html#mesh_gateway-1)
|
||||||
|
parameter. If both are present the value defined on the upstream is used.
|
||||||
|
|
||||||
|
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
|
||||||
|
|
||||||
|
### Sample Compilations
|
||||||
|
|
||||||
|
Full documentation for the output fields is found on the [discovery chain
|
||||||
|
internals](/docs/internals/discovery-chain.html#compileddiscoverychain)
|
||||||
|
page.
|
||||||
|
|
||||||
|
#### Multi-Datacenter Failover
|
||||||
|
|
||||||
|
Config entries defined:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
kind = "service-resolver"
|
||||||
|
name = "web"
|
||||||
|
connect_timeout = "15s"
|
||||||
|
failover = {
|
||||||
|
"*" = {
|
||||||
|
datacenters = ["dc3", "dc4"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Request:
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl http://127.0.0.1:8500/v1/discovery-chain/web
|
||||||
|
```
|
||||||
|
|
||||||
|
Response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Chain": {
|
||||||
|
"ServiceName": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"Protocol": "tcp",
|
||||||
|
"StartNode": "resolver:web.default.dc1",
|
||||||
|
"Nodes": {
|
||||||
|
"resolver:web.default.dc1": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "web.default.dc1",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "15s",
|
||||||
|
"Target": "web.default.dc1",
|
||||||
|
"Failover": {
|
||||||
|
"Targets": ["web.default.dc3", "web.default.dc4"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Targets": {
|
||||||
|
"web.default.dc1": {
|
||||||
|
"ID": "web.default.dc1",
|
||||||
|
"Service": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {},
|
||||||
|
"SNI": "web.default.dc1.internal.47e25151-6212-ba25-8b7e-81adbbbab461.consul",
|
||||||
|
"Name": "web.default.dc1.internal.47e25151-6212-ba25-8b7e-81adbbbab461.consul"
|
||||||
|
},
|
||||||
|
"web.default.dc3": {
|
||||||
|
"ID": "web.default.dc3",
|
||||||
|
"Service": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc3",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {},
|
||||||
|
"SNI": "web.default.dc3.internal.47e25151-6212-ba25-8b7e-81adbbbab461.consul",
|
||||||
|
"Name": "web.default.dc3.internal.47e25151-6212-ba25-8b7e-81adbbbab461.consul"
|
||||||
|
},
|
||||||
|
"web.default.dc4": {
|
||||||
|
"ID": "web.default.dc4",
|
||||||
|
"Service": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc4",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {},
|
||||||
|
"SNI": "web.default.dc4.internal.47e25151-6212-ba25-8b7e-81adbbbab461.consul",
|
||||||
|
"Name": "web.default.dc4.internal.47e25151-6212-ba25-8b7e-81adbbbab461.consul"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Datacenter Redirect with Overrides
|
||||||
|
|
||||||
|
Config entries defined:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
kind = "service-resolver"
|
||||||
|
name = "web"
|
||||||
|
redirect {
|
||||||
|
datacenter = "dc2"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Request:
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl -X POST \
|
||||||
|
-d'
|
||||||
|
{
|
||||||
|
"OverrideConnectTimeout": "7s",
|
||||||
|
"OverrideProtocol": "grpc",
|
||||||
|
"OverrideMeshGateway": {
|
||||||
|
"Mode": "remote"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
' http://127.0.0.1:8500/v1/discovery-chain/web
|
||||||
|
```
|
||||||
|
|
||||||
|
Response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Chain": {
|
||||||
|
"ServiceName": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"CustomizationHash": "b94f529a",
|
||||||
|
"Protocol": "grpc",
|
||||||
|
"StartNode": "resolver:web.default.dc2",
|
||||||
|
"Nodes": {
|
||||||
|
"resolver:web.default.dc2": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "web.default.dc2",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "7s",
|
||||||
|
"Target": "web.default.dc2"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Targets": {
|
||||||
|
"web.default.dc2": {
|
||||||
|
"ID": "web.default.dc2",
|
||||||
|
"Service": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc2",
|
||||||
|
"MeshGateway": {
|
||||||
|
"Mode": "remote"
|
||||||
|
},
|
||||||
|
"Subset": {},
|
||||||
|
"SNI": "web.default.dc2.internal.59c17fd4-8dfa-f54a-ae71-855b26faf637.consul",
|
||||||
|
"Name": "web.default.dc2.internal.59c17fd4-8dfa-f54a-ae71-855b26faf637.consul"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Version Split For Alternate Datacenter
|
||||||
|
|
||||||
|
Config entries defined:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
kind = "service-resolver"
|
||||||
|
name = "web"
|
||||||
|
default_subset = "v1"
|
||||||
|
subsets = {
|
||||||
|
"v1" = {
|
||||||
|
filter = "Service.Meta.version == v1"
|
||||||
|
}
|
||||||
|
"v2" = {
|
||||||
|
filter = "Service.Meta.version == v2"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
# ---------------------------
|
||||||
|
kind = "service-defaults"
|
||||||
|
name = "web"
|
||||||
|
protocol = "http"
|
||||||
|
# ---------------------------
|
||||||
|
kind = "service-splitter"
|
||||||
|
name = "web"
|
||||||
|
splits = [
|
||||||
|
{
|
||||||
|
weight = 90
|
||||||
|
service_subset = "v1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
weight = 10
|
||||||
|
service_subset = "v2"
|
||||||
|
},
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Request:
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl http://127.0.0.1:8500/v1/discovery-chain/web?compile-dc=dc2
|
||||||
|
```
|
||||||
|
|
||||||
|
Response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Chain": {
|
||||||
|
"ServiceName": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc2",
|
||||||
|
"Protocol": "http",
|
||||||
|
"StartNode": "splitter:web",
|
||||||
|
"Nodes": {
|
||||||
|
"resolver:v1.web.default.dc2": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "v1.web.default.dc2",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "5s",
|
||||||
|
"Target": "v1.web.default.dc2"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"resolver:v2.web.default.dc2": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "v2.web.default.dc2",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "5s",
|
||||||
|
"Target": "v2.web.default.dc2"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"splitter:web": {
|
||||||
|
"Type": "splitter",
|
||||||
|
"Name": "web",
|
||||||
|
"Splits": [
|
||||||
|
{
|
||||||
|
"Weight": 90,
|
||||||
|
"NextNode": "resolver:v1.web.default.dc2"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Weight": 10,
|
||||||
|
"NextNode": "resolver:v2.web.default.dc2"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Targets": {
|
||||||
|
"v1.web.default.dc2": {
|
||||||
|
"ID": "v1.web.default.dc2",
|
||||||
|
"Service": "web",
|
||||||
|
"ServiceSubset": "v1",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc2",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {
|
||||||
|
"Filter": "Service.Meta.version == v1"
|
||||||
|
},
|
||||||
|
"SNI": "v1.web.default.dc2.internal.6c9594ec-d798-28b9-d084-aa03e81cf078.consul",
|
||||||
|
"Name": "v1.web.default.dc2.internal.6c9594ec-d798-28b9-d084-aa03e81cf078.consul"
|
||||||
|
},
|
||||||
|
"v2.web.default.dc2": {
|
||||||
|
"ID": "v2.web.default.dc2",
|
||||||
|
"Service": "web",
|
||||||
|
"ServiceSubset": "v2",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc2",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {
|
||||||
|
"Filter": "Service.Meta.version == v2"
|
||||||
|
},
|
||||||
|
"SNI": "v2.web.default.dc2.internal.6c9594ec-d798-28b9-d084-aa03e81cf078.consul",
|
||||||
|
"Name": "v2.web.default.dc2.internal.6c9594ec-d798-28b9-d084-aa03e81cf078.consul"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### HTTP Path Routing
|
||||||
|
|
||||||
|
Config entries defined:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
kind = "service-resolver"
|
||||||
|
name = "web"
|
||||||
|
subsets = {
|
||||||
|
"canary" = {
|
||||||
|
filter = "Service.Meta.flavor == canary"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
# ---------------------------
|
||||||
|
kind = "proxy-defaults"
|
||||||
|
name = "web"
|
||||||
|
config {
|
||||||
|
protocol = "http"
|
||||||
|
}
|
||||||
|
# ---------------------------
|
||||||
|
kind = "service-router"
|
||||||
|
name = "web"
|
||||||
|
routes = [
|
||||||
|
{
|
||||||
|
match {
|
||||||
|
http {
|
||||||
|
path_prefix = "/admin"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
destination {
|
||||||
|
service = "admin"
|
||||||
|
prefix_rewrite = "/"
|
||||||
|
request_timeout = "15s"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
match {
|
||||||
|
http {
|
||||||
|
header = [
|
||||||
|
{
|
||||||
|
name = "x-debug"
|
||||||
|
exact = "1"
|
||||||
|
},
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
destination {
|
||||||
|
service = "web"
|
||||||
|
service_subset = "canary"
|
||||||
|
num_retries = 5
|
||||||
|
retry_on_connect_failure = true
|
||||||
|
retry_on_status_codes = [401, 409]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Request:
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ curl http://127.0.0.1:8500/v1/discovery-chain/web
|
||||||
|
```
|
||||||
|
|
||||||
|
Response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Chain": {
|
||||||
|
"ServiceName": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"Protocol": "http",
|
||||||
|
"StartNode": "router:web",
|
||||||
|
"Nodes": {
|
||||||
|
"resolver:admin.default.dc1": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "admin.default.dc1",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "5s",
|
||||||
|
"Default": true,
|
||||||
|
"Target": "admin.default.dc1"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"resolver:canary.web.default.dc1": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "canary.web.default.dc1",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "5s",
|
||||||
|
"Target": "canary.web.default.dc1"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"resolver:web.default.dc1": {
|
||||||
|
"Type": "resolver",
|
||||||
|
"Name": "web.default.dc1",
|
||||||
|
"Resolver": {
|
||||||
|
"ConnectTimeout": "5s",
|
||||||
|
"Target": "web.default.dc1"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"router:web": {
|
||||||
|
"Type": "router",
|
||||||
|
"Name": "web",
|
||||||
|
"Routes": [
|
||||||
|
{
|
||||||
|
"Definition": {
|
||||||
|
"Match": {
|
||||||
|
"HTTP": {
|
||||||
|
"PathPrefix": "/admin"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Destination": {
|
||||||
|
"RequestTimeout": "15s",
|
||||||
|
"Service": "admin",
|
||||||
|
"PrefixRewrite": "/"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"NextNode": "resolver:admin.default.dc1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Definition": {
|
||||||
|
"Match": {
|
||||||
|
"HTTP": {
|
||||||
|
"Header": [
|
||||||
|
{
|
||||||
|
"Name": "x-debug",
|
||||||
|
"Exact": "1"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Destination": {
|
||||||
|
"Service": "web",
|
||||||
|
"ServiceSubset": "canary",
|
||||||
|
"NumRetries": 5,
|
||||||
|
"RetryOnConnectFailure": true,
|
||||||
|
"RetryOnStatusCodes": [401, 409]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"NextNode": "resolver:canary.web.default.dc1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Definition": {
|
||||||
|
"Match": {
|
||||||
|
"HTTP": {
|
||||||
|
"PathPrefix": "/"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Destination": {
|
||||||
|
"Service": "web"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"NextNode": "resolver:web.default.dc1"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"Targets": {
|
||||||
|
"admin.default.dc1": {
|
||||||
|
"ID": "admin.default.dc1",
|
||||||
|
"Service": "admin",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {},
|
||||||
|
"SNI": "admin.default.dc1.internal.fce8a058-0981-2c04-d23c-b7375af64ce8.consul",
|
||||||
|
"Name": "admin.default.dc1.internal.fce8a058-0981-2c04-d23c-b7375af64ce8.consul"
|
||||||
|
},
|
||||||
|
"canary.web.default.dc1": {
|
||||||
|
"ID": "canary.web.default.dc1",
|
||||||
|
"Service": "web",
|
||||||
|
"ServiceSubset": "canary",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {
|
||||||
|
"Filter": "Service.Meta.flavor == canary"
|
||||||
|
},
|
||||||
|
"SNI": "canary.web.default.dc1.internal.fce8a058-0981-2c04-d23c-b7375af64ce8.consul",
|
||||||
|
"Name": "canary.web.default.dc1.internal.fce8a058-0981-2c04-d23c-b7375af64ce8.consul"
|
||||||
|
},
|
||||||
|
"web.default.dc1": {
|
||||||
|
"ID": "web.default.dc1",
|
||||||
|
"Service": "web",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"MeshGateway": {},
|
||||||
|
"Subset": {},
|
||||||
|
"SNI": "web.default.dc1.internal.fce8a058-0981-2c04-d23c-b7375af64ce8.consul",
|
||||||
|
"Name": "web.default.dc1.internal.fce8a058-0981-2c04-d23c-b7375af64ce8.consul"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
@ -16,9 +16,9 @@ Consul.
|
||||||
|
|
||||||
This endpoint triggers a new user event.
|
This endpoint triggers a new user event.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `PUT` | `/event/fire/:name` | `application/json` |
|
| `PUT` | `/event/fire/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -92,9 +92,9 @@ agent may have a different view of the events. Events are broadcast using the
|
||||||
[gossip protocol](/docs/internals/gossip.html), so they have no global ordering
|
[gossip protocol](/docs/internals/gossip.html), so they have no global ordering
|
||||||
nor do they make a promise of delivery.
|
nor do they make a promise of delivery.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `GET` | `/event/list` | `application/json` |
|
| `GET` | `/event/list` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -3,11 +3,10 @@ layout: api
|
||||||
page_title: Blocking Queries
|
page_title: Blocking Queries
|
||||||
sidebar_current: api-features-blocking
|
sidebar_current: api-features-blocking
|
||||||
description: |-
|
description: |-
|
||||||
Many endpoints in Consul support a feature known as "blocking queries". A
|
Many endpoints in Consul support a feature known as "blocking queries". A
|
||||||
blocking query is used to wait for a potential change using long polling.
|
blocking query is used to wait for a potential change using long polling.
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
||||||
# Blocking Queries
|
# Blocking Queries
|
||||||
|
|
||||||
Many endpoints in Consul support a feature known as "blocking queries". A
|
Many endpoints in Consul support a feature known as "blocking queries". A
|
||||||
|
|
@ -43,45 +42,46 @@ duration.
|
||||||
While the mechanism is relatively simple to work with, there are a few edge
|
While the mechanism is relatively simple to work with, there are a few edge
|
||||||
cases that must be handled correctly.
|
cases that must be handled correctly.
|
||||||
|
|
||||||
* **Reset the index if it goes backwards**. While indexes in general are
|
- **Reset the index if it goes backwards**. While indexes in general are
|
||||||
monotonically increasing(i.e. they should only ever increase as time passes),
|
monotonically increasing(i.e. they should only ever increase as time passes),
|
||||||
there are several real-world scenarios in
|
there are several real-world scenarios in
|
||||||
which they can go backwards for a given query. Implementations must check
|
which they can go backwards for a given query. Implementations must check
|
||||||
to see if a returned index is lower than the previous value,
|
to see if a returned index is lower than the previous value,
|
||||||
and if it is, should reset index to `0` - effectively restarting their blocking loop.
|
and if it is, should reset index to `0` - effectively restarting their blocking loop.
|
||||||
Failure to do so may cause the client to miss future updates for an unbounded
|
Failure to do so may cause the client to miss future updates for an unbounded
|
||||||
time, or to use an invalid index value that causes no blocking and increases
|
time, or to use an invalid index value that causes no blocking and increases
|
||||||
load on the servers. Cases where this can occur include:
|
load on the servers. Cases where this can occur include:
|
||||||
* If a raft snapshot is restored on the servers with older version of the data.
|
|
||||||
* KV list operations where an item with the highest index is removed.
|
|
||||||
* A Consul upgrade changes the way watches work to optimize them with more
|
|
||||||
granular indexes.
|
|
||||||
|
|
||||||
* **Sanity check index is greater than zero**. After the initial request (or a
|
- If a raft snapshot is restored on the servers with older version of the data.
|
||||||
reset as above) the `X-Consul-Index` returned _should_ always be greater than zero. It
|
- KV list operations where an item with the highest index is removed.
|
||||||
is a bug in Consul if it is not, however this has happened a few times and can
|
- A Consul upgrade changes the way watches work to optimize them with more
|
||||||
still be triggered on some older Consul versions. It's especially bad because it
|
granular indexes.
|
||||||
causes blocking clients that are not aware to enter a busy loop, using excessive
|
|
||||||
client CPU and causing high load on servers. It is _always_ safe to use an
|
|
||||||
index of `1` to wait for updates when the data being requested doesn't exist
|
|
||||||
yet, so clients _should_ sanity check that their index is at least 1 after
|
|
||||||
each blocking response is handled to be sure they actually block on the next
|
|
||||||
request.
|
|
||||||
|
|
||||||
* **Rate limit**. The blocking query mechanism is reasonably efficient when updates
|
- **Sanity check index is greater than zero**. After the initial request (or a
|
||||||
are relatively rare (order of tens of seconds to minutes between updates). In cases
|
reset as above) the `X-Consul-Index` returned _should_ always be greater than zero. It
|
||||||
where a result gets updated very fast however - possibly during an outage or incident
|
is a bug in Consul if it is not, however this has happened a few times and can
|
||||||
with a badly behaved client - blocking query loops degrade into busy loops that
|
still be triggered on some older Consul versions. It's especially bad because it
|
||||||
consume excessive client CPU and cause high server load. While it's possible to just add a sleep
|
causes blocking clients that are not aware to enter a busy loop, using excessive
|
||||||
to every iteration of the loop, this is **not** recommended since it causes update
|
client CPU and causing high load on servers. It is _always_ safe to use an
|
||||||
delivery to be delayed in the happy case, and it can exacerbate the problem since
|
index of `1` to wait for updates when the data being requested doesn't exist
|
||||||
it increases the chance that the index has changed on the next request. Clients
|
yet, so clients _should_ sanity check that their index is at least 1 after
|
||||||
_should_ instead rate limit the loop so that in the happy case they proceed without
|
each blocking response is handled to be sure they actually block on the next
|
||||||
waiting, but when values start to churn quickly they degrade into polling at a
|
request.
|
||||||
reasonable rate (say every 15 seconds). Ideally this is done with an algorithm that
|
|
||||||
allows a couple of quick successive deliveries before it starts to limit rate - a
|
- **Rate limit**. The blocking query mechanism is reasonably efficient when updates
|
||||||
[token bucket](https://en.wikipedia.org/wiki/Token_bucket) with burst of 2 is a simple
|
are relatively rare (order of tens of seconds to minutes between updates). In cases
|
||||||
way to achieve this.
|
where a result gets updated very fast however - possibly during an outage or incident
|
||||||
|
with a badly behaved client - blocking query loops degrade into busy loops that
|
||||||
|
consume excessive client CPU and cause high server load. While it's possible to just add a sleep
|
||||||
|
to every iteration of the loop, this is **not** recommended since it causes update
|
||||||
|
delivery to be delayed in the happy case, and it can exacerbate the problem since
|
||||||
|
it increases the chance that the index has changed on the next request. Clients
|
||||||
|
_should_ instead rate limit the loop so that in the happy case they proceed without
|
||||||
|
waiting, but when values start to churn quickly they degrade into polling at a
|
||||||
|
reasonable rate (say every 15 seconds). Ideally this is done with an algorithm that
|
||||||
|
allows a couple of quick successive deliveries before it starts to limit rate - a
|
||||||
|
[token bucket](https://en.wikipedia.org/wiki/Token_bucket) with burst of 2 is a simple
|
||||||
|
way to achieve this.
|
||||||
|
|
||||||
## Hash-based Blocking Queries
|
## Hash-based Blocking Queries
|
||||||
|
|
||||||
|
|
@ -104,4 +104,4 @@ result is older or newer than another. In general hash-based blocking will not
|
||||||
return too early due to an idempotent update since the hash will remain the same
|
return too early due to an idempotent update since the hash will remain the same
|
||||||
unless the result actually changes, however as with index-based blocking there
|
unless the result actually changes, however as with index-based blocking there
|
||||||
is no strict guarantee that clients will never observe the same result delivered
|
is no strict guarantee that clients will never observe the same result delivered
|
||||||
before the full timeout has elapsed.
|
before the full timeout has elapsed.
|
||||||
|
|
@ -3,8 +3,8 @@ layout: api
|
||||||
page_title: Agent Caching
|
page_title: Agent Caching
|
||||||
sidebar_current: api-features-caching
|
sidebar_current: api-features-caching
|
||||||
description: |-
|
description: |-
|
||||||
Some read endpoints support agent caching. They are clearly marked in the
|
Some read endpoints support agent caching. They are clearly marked in the
|
||||||
documentation.
|
documentation.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Agent Caching
|
# Agent Caching
|
||||||
|
|
@ -3,7 +3,7 @@ layout: api
|
||||||
page_title: Consistency Modes
|
page_title: Consistency Modes
|
||||||
sidebar_current: api-features-consistency
|
sidebar_current: api-features-consistency
|
||||||
description: |-
|
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.
|
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
|
# Consistency Modes
|
||||||
|
|
@ -46,4 +46,4 @@ To support bounding the acceptable staleness of data, responses provide the
|
||||||
`X-Consul-LastContact` header containing the time in milliseconds that a server
|
`X-Consul-LastContact` header containing the time in milliseconds that a server
|
||||||
was last contacted by the leader node. The `X-Consul-KnownLeader` header also
|
was last contacted by the leader node. The `X-Consul-KnownLeader` header also
|
||||||
indicates if there is a known leader. These can be used by clients to gauge the
|
indicates if there is a known leader. These can be used by clients to gauge the
|
||||||
staleness of a result and take appropriate action.
|
staleness of a result and take appropriate action.
|
||||||
|
|
@ -0,0 +1,436 @@
|
||||||
|
---
|
||||||
|
layout: api
|
||||||
|
page_title: Filtering
|
||||||
|
sidebar_current: api-features-filtering
|
||||||
|
description: |-
|
||||||
|
Consul exposes a RESTful HTTP API to control almost every aspect of the
|
||||||
|
Consul agent.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Filtering
|
||||||
|
|
||||||
|
A filter expression is used to refine a data query for some API listing endpoints as notated in the individual API documentation.
|
||||||
|
Filtering will be executed on the Consul server before data is returned, reducing the network load. To pass a
|
||||||
|
filter expression to Consul, with a data query, use the `filter` parameter.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -G <path> --data-urlencode 'filter=<filter expression>'
|
||||||
|
```
|
||||||
|
|
||||||
|
To create a filter expression, you will write one or more expressions using matching operators, selectors, and values.
|
||||||
|
|
||||||
|
## Expression Syntax
|
||||||
|
|
||||||
|
Expressions are written in plain text format. Boolean logic and parenthesization are
|
||||||
|
supported. In general whitespace is ignored, except within literal
|
||||||
|
strings.
|
||||||
|
|
||||||
|
### Expressions
|
||||||
|
|
||||||
|
There are several methods for connecting expressions, including
|
||||||
|
|
||||||
|
- logical `or`
|
||||||
|
- logical `and`
|
||||||
|
- logical `not`
|
||||||
|
- grouping with parenthesis
|
||||||
|
- matching expressions
|
||||||
|
|
||||||
|
```text
|
||||||
|
// Logical Or - evaluates to true if either sub-expression does
|
||||||
|
<Expression 1> or <Expression 2>
|
||||||
|
|
||||||
|
// Logical And - evaluates to true if both sub-expressions do
|
||||||
|
<Expression 1 > and <Expression 2>
|
||||||
|
|
||||||
|
// Logical Not - evaluates to true if the sub-expression does not
|
||||||
|
not <Expression 1>
|
||||||
|
|
||||||
|
// Grouping - Overrides normal precedence rules
|
||||||
|
( <Expression 1> )
|
||||||
|
|
||||||
|
// Inspects data to check for a match
|
||||||
|
<Matching Expression 1>
|
||||||
|
```
|
||||||
|
|
||||||
|
Standard operator precedence can be expected for the various forms. For
|
||||||
|
example, the following two expressions would be equivalent.
|
||||||
|
|
||||||
|
```text
|
||||||
|
<Expression 1> and not <Expression 2> or <Expression 3>
|
||||||
|
|
||||||
|
( <Expression 1> and (not <Expression 2> )) or <Expression 3>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Matching Operators
|
||||||
|
|
||||||
|
Matching operators are used to create an expression. All matching operators use a selector or value to choose what data should be
|
||||||
|
matched. Each endpoint that supports filtering accepts a potentially
|
||||||
|
different list of selectors and is detailed in the API documentation for
|
||||||
|
those endpoints.
|
||||||
|
|
||||||
|
```text
|
||||||
|
// Equality & Inequality checks
|
||||||
|
<Selector> == <Value>
|
||||||
|
<Selector> != <Value>
|
||||||
|
|
||||||
|
// Emptiness checks
|
||||||
|
<Selector> is empty
|
||||||
|
<Selector> is not empty
|
||||||
|
|
||||||
|
// Contains checks or Substring Matching
|
||||||
|
<Value> in <Selector>
|
||||||
|
<Value> not in <Selector>
|
||||||
|
<Selector> contains <Value>
|
||||||
|
<Selector> not contains <Value>
|
||||||
|
|
||||||
|
// Regular Expression Matching
|
||||||
|
<Selector> matches <Value>
|
||||||
|
<Selector> not matches <Value>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Selectors
|
||||||
|
|
||||||
|
Selectors are used by matching operators to create an expression. They are
|
||||||
|
defined by a `.` separated list of names. Each name must start with
|
||||||
|
a an ASCII letter and can contain ASCII letters, numbers, and underscores. When
|
||||||
|
part of the selector references a map value it may be expressed using the form
|
||||||
|
`["<map key name>"]` instead of `.<map key name>`. This allows the possibility
|
||||||
|
of using map keys that are not valid selectors in and of themselves.
|
||||||
|
|
||||||
|
```text
|
||||||
|
// selects the foo key within the ServiceMeta mapping for the
|
||||||
|
// /catalog/service/:service endpoint
|
||||||
|
ServiceMeta.foo
|
||||||
|
|
||||||
|
// Also selects the foo key for the same endpoint
|
||||||
|
ServiceMeta["foo"]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Values
|
||||||
|
|
||||||
|
Values are used by matching operators to create an expression. Values can be any valid selector, a number, or a quoted string. For numbers any
|
||||||
|
base 10 integers and floating point numbers are possible. For quoted strings,
|
||||||
|
they may either be enclosed in double quotes or backticks. When enclosed in
|
||||||
|
backticks they are treated as raw strings and escape sequences such as `\n`
|
||||||
|
will not be expanded.
|
||||||
|
|
||||||
|
## Filter Utilization
|
||||||
|
|
||||||
|
Generally, only the main object is filtered. When filtering for
|
||||||
|
an item within an array that is not at the top level, the entire array that contains the item
|
||||||
|
will be returned. This is usually the outermost object of a response,
|
||||||
|
but in some cases such the [`/catalog/node/:node`](/api/catalog.html#list-services-for-node)
|
||||||
|
endpoint the filtering is performed on a object embedded within the results.
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
|
||||||
|
Filters are executed on the servers and therefore will consume some amount
|
||||||
|
of CPU time on the server. For non-stale queries this means that the filter
|
||||||
|
is executed on the leader.
|
||||||
|
|
||||||
|
### Filtering Examples
|
||||||
|
|
||||||
|
#### Agent API
|
||||||
|
|
||||||
|
**Command - Unfiltered**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -X GET localhost:8500/v1/agent/services
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response - Unfiltered**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"redis1": {
|
||||||
|
"ID": "redis1",
|
||||||
|
"Service": "redis",
|
||||||
|
"Tags": ["primary", "production"],
|
||||||
|
"Meta": {
|
||||||
|
"env": "production",
|
||||||
|
"foo": "bar"
|
||||||
|
},
|
||||||
|
"Port": 1234,
|
||||||
|
"Address": "",
|
||||||
|
"Weights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"EnableTagOverride": false
|
||||||
|
},
|
||||||
|
"redis2": {
|
||||||
|
"ID": "redis2",
|
||||||
|
"Service": "redis",
|
||||||
|
"Tags": ["secondary", "production"],
|
||||||
|
"Meta": {
|
||||||
|
"env": "production",
|
||||||
|
"foo": "bar"
|
||||||
|
},
|
||||||
|
"Port": 1235,
|
||||||
|
"Address": "",
|
||||||
|
"Weights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"EnableTagOverride": false
|
||||||
|
},
|
||||||
|
"redis3": {
|
||||||
|
"ID": "redis3",
|
||||||
|
"Service": "redis",
|
||||||
|
"Tags": ["primary", "qa"],
|
||||||
|
"Meta": {
|
||||||
|
"env": "qa"
|
||||||
|
},
|
||||||
|
"Port": 1234,
|
||||||
|
"Address": "",
|
||||||
|
"Weights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"EnableTagOverride": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Command - Filtered**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -G localhost:8500/v1/agent/services --data-urlencode 'filter=Meta.env == qa'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response - Filtered**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"redis3": {
|
||||||
|
"ID": "redis3",
|
||||||
|
"Service": "redis",
|
||||||
|
"Tags": ["primary", "qa"],
|
||||||
|
"Meta": {
|
||||||
|
"env": "qa"
|
||||||
|
},
|
||||||
|
"Port": 1234,
|
||||||
|
"Address": "",
|
||||||
|
"Weights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"EnableTagOverride": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Catalog API
|
||||||
|
|
||||||
|
**Command - Unfiltered**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -X GET localhost:8500/v1/catalog/service/api-internal
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response - Unfiltered**
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"ID": "b4f64e8c-5c7d-11e9-bf68-8c8590bd0966",
|
||||||
|
"Node": "node-1",
|
||||||
|
"Address": "198.18.0.1",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"TaggedAddresses": null,
|
||||||
|
"NodeMeta": {
|
||||||
|
"agent": "true",
|
||||||
|
"arch": "i386",
|
||||||
|
"os": "darwin"
|
||||||
|
},
|
||||||
|
"ServiceKind": "",
|
||||||
|
"ServiceID": "api-internal",
|
||||||
|
"ServiceName": "api-internal",
|
||||||
|
"ServiceTags": ["tag"],
|
||||||
|
"ServiceAddress": "",
|
||||||
|
"ServiceWeights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"ServiceMeta": {
|
||||||
|
"environment": "qa"
|
||||||
|
},
|
||||||
|
"ServicePort": 9090,
|
||||||
|
"ServiceEnableTagOverride": false,
|
||||||
|
"ServiceProxy": {},
|
||||||
|
"ServiceConnect": {},
|
||||||
|
"CreateIndex": 30,
|
||||||
|
"ModifyIndex": 30
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"ID": "b4faf93a-5c7d-11e9-840d-8c8590bd0966",
|
||||||
|
"Node": "node-2",
|
||||||
|
"Address": "198.18.0.2",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"TaggedAddresses": null,
|
||||||
|
"NodeMeta": {
|
||||||
|
"arch": "arm",
|
||||||
|
"os": "linux"
|
||||||
|
},
|
||||||
|
"ServiceKind": "",
|
||||||
|
"ServiceID": "api-internal",
|
||||||
|
"ServiceName": "api-internal",
|
||||||
|
"ServiceTags": ["test", "tag"],
|
||||||
|
"ServiceAddress": "",
|
||||||
|
"ServiceWeights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"ServiceMeta": {
|
||||||
|
"environment": "production"
|
||||||
|
},
|
||||||
|
"ServicePort": 9090,
|
||||||
|
"ServiceEnableTagOverride": false,
|
||||||
|
"ServiceProxy": {},
|
||||||
|
"ServiceConnect": {},
|
||||||
|
"CreateIndex": 29,
|
||||||
|
"ModifyIndex": 29
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"ID": "b4fbe7f4-5c7d-11e9-ac82-8c8590bd0966",
|
||||||
|
"Node": "node-4",
|
||||||
|
"Address": "198.18.0.4",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"TaggedAddresses": null,
|
||||||
|
"NodeMeta": {
|
||||||
|
"arch": "i386",
|
||||||
|
"os": "freebsd"
|
||||||
|
},
|
||||||
|
"ServiceKind": "",
|
||||||
|
"ServiceID": "api-internal",
|
||||||
|
"ServiceName": "api-internal",
|
||||||
|
"ServiceTags": [],
|
||||||
|
"ServiceAddress": "",
|
||||||
|
"ServiceWeights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"ServiceMeta": {
|
||||||
|
"environment": "qa"
|
||||||
|
},
|
||||||
|
"ServicePort": 9090,
|
||||||
|
"ServiceEnableTagOverride": false,
|
||||||
|
"ServiceProxy": {},
|
||||||
|
"ServiceConnect": {},
|
||||||
|
"CreateIndex": 28,
|
||||||
|
"ModifyIndex": 28
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Command - Filtered**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -G localhost:8500/v1/catalog/service/api-internal --data-urlencode 'filter=NodeMeta.os == linux'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response - Filtered**
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"ID": "b4faf93a-5c7d-11e9-840d-8c8590bd0966",
|
||||||
|
"Node": "node-2",
|
||||||
|
"Address": "198.18.0.2",
|
||||||
|
"Datacenter": "dc1",
|
||||||
|
"TaggedAddresses": null,
|
||||||
|
"NodeMeta": {
|
||||||
|
"arch": "arm",
|
||||||
|
"os": "linux"
|
||||||
|
},
|
||||||
|
"ServiceKind": "",
|
||||||
|
"ServiceID": "api-internal",
|
||||||
|
"ServiceName": "api-internal",
|
||||||
|
"ServiceTags": ["test", "tag"],
|
||||||
|
"ServiceAddress": "",
|
||||||
|
"ServiceWeights": {
|
||||||
|
"Passing": 1,
|
||||||
|
"Warning": 1
|
||||||
|
},
|
||||||
|
"ServiceMeta": {
|
||||||
|
"environment": "production"
|
||||||
|
},
|
||||||
|
"ServicePort": 9090,
|
||||||
|
"ServiceEnableTagOverride": false,
|
||||||
|
"ServiceProxy": {},
|
||||||
|
"ServiceConnect": {},
|
||||||
|
"CreateIndex": 29,
|
||||||
|
"ModifyIndex": 29
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Health API
|
||||||
|
|
||||||
|
**Command - Unfiltered**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -X GET localhost:8500/v1/health/node/node-1
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response - Unfiltered**
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"Node": "node-1",
|
||||||
|
"CheckID": "node-health",
|
||||||
|
"Name": "Node level check",
|
||||||
|
"Status": "critical",
|
||||||
|
"Notes": "",
|
||||||
|
"Output": "",
|
||||||
|
"ServiceID": "",
|
||||||
|
"ServiceName": "",
|
||||||
|
"ServiceTags": [],
|
||||||
|
"Definition": {},
|
||||||
|
"CreateIndex": 13,
|
||||||
|
"ModifyIndex": 13
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Node": "node-1",
|
||||||
|
"CheckID": "svc-web-health",
|
||||||
|
"Name": "Service level check - web",
|
||||||
|
"Status": "warning",
|
||||||
|
"Notes": "",
|
||||||
|
"Output": "",
|
||||||
|
"ServiceID": "",
|
||||||
|
"ServiceName": "web",
|
||||||
|
"ServiceTags": [],
|
||||||
|
"Definition": {},
|
||||||
|
"CreateIndex": 18,
|
||||||
|
"ModifyIndex": 18
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Command - Filtered**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -G localhost:8500/v1/health/node/node-1 --data-urlencode 'filter=ServiceName != ""'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response - Filtered**
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"Node": "node-1",
|
||||||
|
"CheckID": "svc-web-health",
|
||||||
|
"Name": "Service level check - web",
|
||||||
|
"Status": "warning",
|
||||||
|
"Notes": "",
|
||||||
|
"Output": "",
|
||||||
|
"ServiceID": "",
|
||||||
|
"ServiceName": "web",
|
||||||
|
"ServiceTags": [],
|
||||||
|
"Definition": {},
|
||||||
|
"CreateIndex": 18,
|
||||||
|
"ModifyIndex": 18
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
@ -19,9 +19,9 @@ raw entries.
|
||||||
|
|
||||||
This endpoint returns the checks specific to the node provided on the path.
|
This endpoint returns the checks specific to the node provided on the path.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------- | ------------------ |
|
||||||
| `GET` | `/health/node/:node` | `application/json` |
|
| `GET` | `/health/node/:node` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -44,9 +44,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list checks.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list checks.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. To view
|
from the request's ACL token or will default to the `default` namespace. To view
|
||||||
checks for multiple namespaces the `*` wildcard namespace may be used. Added in Consul 1.7.0.
|
checks for multiple namespaces the `*` wildcard namespace may be used. Added in Consul 1.7.0.
|
||||||
|
|
@ -114,9 +114,9 @@ the following selectors and filter operations being supported:
|
||||||
This endpoint returns the checks associated with the service provided on the
|
This endpoint returns the checks associated with the service provided on the
|
||||||
path.
|
path.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------------- | ------------------ |
|
||||||
| `GET` | `/health/checks/:service` | `application/json` |
|
| `GET` | `/health/checks/:service` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -149,9 +149,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the service.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the service.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
@ -175,7 +175,7 @@ $ curl \
|
||||||
"Output": "",
|
"Output": "",
|
||||||
"ServiceID": "redis",
|
"ServiceID": "redis",
|
||||||
"ServiceName": "redis",
|
"ServiceName": "redis",
|
||||||
"ServiceTags": ["primary"],
|
"ServiceTags": ["primary"],
|
||||||
"Namespace": "default"
|
"Namespace": "default"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
|
|
@ -186,7 +186,6 @@ $ curl \
|
||||||
The filter will be executed against each health check in the results list with
|
The filter will be executed against each health check in the results list with
|
||||||
the following selectors and filter operations being supported:
|
the following selectors and filter operations being supported:
|
||||||
|
|
||||||
|
|
||||||
| Selector | Supported Operations |
|
| Selector | Supported Operations |
|
||||||
| ------------- | -------------------------------------------------- |
|
| ------------- | -------------------------------------------------- |
|
||||||
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
|
|
@ -205,9 +204,9 @@ This endpoint returns the nodes providing the service indicated on the path.
|
||||||
Users can also build in support for dynamic load balancing and other features by
|
Users can also build in support for dynamic load balancing and other features by
|
||||||
incorporating the use of health checks.
|
incorporating the use of health checks.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------------- | ------------------ |
|
||||||
| `GET` | `/health/service/:service` | `application/json` |
|
| `GET` | `/health/service/:service` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -249,11 +248,11 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the service.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the service.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
||||||
|
|
@ -397,9 +396,9 @@ This will include both proxies and native integrations. A service may
|
||||||
register both Connect-capable and incapable services at the same time,
|
register both Connect-capable and incapable services at the same time,
|
||||||
so this endpoint may be used to filter only the Connect-capable endpoints.
|
so this endpoint may be used to filter only the Connect-capable endpoints.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------------------- | ------------------ |
|
||||||
| `GET` | `/health/connect/:service` | `application/json` |
|
| `GET` | `/health/connect/:service` | `application/json` |
|
||||||
|
|
||||||
Parameters and response format are the same as
|
Parameters and response format are the same as
|
||||||
[`/health/service/:service`](/api/health.html#list-nodes-for-service).
|
[`/health/service/:service`](/api/health.html#list-nodes-for-service).
|
||||||
|
|
@ -408,9 +407,9 @@ Parameters and response format are the same as
|
||||||
|
|
||||||
This endpoint returns the checks in the state provided on the path.
|
This endpoint returns the checks in the state provided on the path.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `GET` | `/health/state/:state` | `application/json` |
|
| `GET` | `/health/state/:state` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -444,9 +443,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `filter` `(string: "")` - Specifies the expression used to filter the
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
||||||
queries results prior to returning the data.
|
queries results prior to returning the data.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
@ -482,7 +481,7 @@ $ curl \
|
||||||
"Output": "",
|
"Output": "",
|
||||||
"ServiceID": "redis",
|
"ServiceID": "redis",
|
||||||
"ServiceName": "redis",
|
"ServiceName": "redis",
|
||||||
"ServiceTags": ["primary"],
|
"ServiceTags": ["primary"],
|
||||||
"Namespace": "default"
|
"Namespace": "default"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
|
|
@ -493,7 +492,6 @@ $ curl \
|
||||||
The filter will be executed against each health check in the results list with
|
The filter will be executed against each health check in the results list with
|
||||||
the following selectors and filter operations being supported:
|
the following selectors and filter operations being supported:
|
||||||
|
|
||||||
|
|
||||||
| Selector | Supported Operations |
|
| Selector | Supported Operations |
|
||||||
| ------------- | -------------------------------------------------- |
|
| ------------- | -------------------------------------------------- |
|
||||||
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
|
|
@ -16,12 +16,11 @@ CRUD operations on nodes, services, checks, configuration, and more.
|
||||||
|
|
||||||
When authentication is enabled, a Consul token should be provided to API
|
When authentication is enabled, a Consul token should be provided to API
|
||||||
requests using the `X-Consul-Token` header or with the
|
requests using the `X-Consul-Token` header or with the
|
||||||
Bearer scheme in the authorization header.
|
Bearer scheme in the authorization header.
|
||||||
This reduces the probability of the
|
This reduces the probability of the
|
||||||
token accidentally getting logged or exposed. When using authentication,
|
token accidentally getting logged or exposed. When using authentication,
|
||||||
clients should communicate via TLS. If you don’t provide a token in the request, then the agent default token will be used.
|
clients should communicate via TLS. If you don’t provide a token in the request, then the agent default token will be used.
|
||||||
|
|
||||||
|
|
||||||
Below is an example using `curl` with `X-Consul-Token`.
|
Below is an example using `curl` with `X-Consul-Token`.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
|
@ -95,6 +94,3 @@ UUID-format identifiers generated by the Consul API use the
|
||||||
These UUID-format strings are generated using high quality, purely random bytes.
|
These UUID-format strings are generated using high quality, purely random bytes.
|
||||||
It is not intended to be RFC compliant, merely to use a well-understood string
|
It is not intended to be RFC compliant, merely to use a well-understood string
|
||||||
representation of a 128-bit value.
|
representation of a 128-bit value.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -28,9 +28,9 @@ This endpoint returns the specified key. If no key exists at the given path, a
|
||||||
|
|
||||||
For multi-key reads, please consider using [transaction](/api/txn.html).
|
For multi-key reads, please consider using [transaction](/api/txn.html).
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------- | ------------------ |
|
||||||
| `GET` | `/kv/:key` | `application/json` |
|
| `GET` | `/kv/:key` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -63,15 +63,15 @@ The table below shows this endpoint's support for
|
||||||
URL as a query parameter.
|
URL as a query parameter.
|
||||||
|
|
||||||
- `separator` `(string: "")` - Specifies the string to use as a separator
|
- `separator` `(string: "")` - Specifies the string to use as a separator
|
||||||
for recursive key lookups. This option is only used when paired with the `keys`
|
for recursive key lookups. This option is only used when paired with the `keys`
|
||||||
parameter to limit the prefix of keys returned, only up to the given separator.
|
parameter to limit the prefix of keys returned, only up to the given separator.
|
||||||
This is specified as part of the URL as a query parameter.
|
This is specified as part of the URL as a query parameter.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
If not provided, the namespace will be inferred from the request's ACL token,
|
If not provided, the namespace will be inferred from the request's ACL token,
|
||||||
or will default to the `default` namespace. This is specified as part of the
|
or will default to the `default` namespace. This is specified as part of the
|
||||||
This is specified as part of the URL as a query parameter.
|
This is specified as part of the URL as a query parameter.
|
||||||
For recursive lookups, the namespace may be specified as '*' and then results
|
For recursive lookups, the namespace may be specified as '\*' and then results
|
||||||
will be returned for all namespaces. Added in Consul 1.7.0.
|
will be returned for all namespaces. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
@ -128,11 +128,7 @@ array of strings instead of an array of JSON objects. Listing `/web/` with a `/`
|
||||||
separator may return:
|
separator may return:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
["/web/bar", "/web/foo", "/web/subdir/"]
|
||||||
"/web/bar",
|
|
||||||
"/web/foo",
|
|
||||||
"/web/subdir/"
|
|
||||||
]
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Using the key listing method may be suitable when you do not need the values or
|
Using the key listing method may be suitable when you do not need the values or
|
||||||
|
|
@ -155,9 +151,9 @@ response)
|
||||||
This endpoint updates the value of the specified key. If no key exists at the given
|
This endpoint updates the value of the specified key. If no key exists at the given
|
||||||
path, the key will be created.
|
path, the key will be created.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------- | ------------------ |
|
||||||
| `PUT` | `/kv/:key` | `application/json` |
|
| `PUT` | `/kv/:key` | `application/json` |
|
||||||
|
|
||||||
Even though the return type is `application/json`, the value is either `true` or
|
Even though the return type is `application/json`, the value is either `true` or
|
||||||
`false`, indicating whether the create/update succeeded.
|
`false`, indicating whether the create/update succeeded.
|
||||||
|
|
@ -201,8 +197,7 @@ The table below shows this endpoint's support for
|
||||||
that does not include the acquire parameter will proceed normally even if another
|
that does not include the acquire parameter will proceed normally even if another
|
||||||
session has locked the key.**
|
session has locked the key.**
|
||||||
|
|
||||||
For an example of how to use the lock feature, see the [Leader Election Guide]
|
For an example of how to use the lock feature, see the [Leader Election Guide](https://learn.hashicorp.com/consul/developer-configuration/elections).
|
||||||
(https://learn.hashicorp.com/consul/developer-configuration/elections).
|
|
||||||
|
|
||||||
- `release` `(string: "")` - Supply a session ID to use in a release operation. This is
|
- `release` `(string: "")` - Supply a session ID to use in a release operation. This is
|
||||||
useful when paired with `?acquire=` as it allows clients to yield a lock. This
|
useful when paired with `?acquire=` as it allows clients to yield a lock. This
|
||||||
|
|
@ -244,9 +239,9 @@ true
|
||||||
|
|
||||||
This endpoint deletes a single key or all keys sharing a prefix.
|
This endpoint deletes a single key or all keys sharing a prefix.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ---------------------------- | -------------------------- |
|
| -------- | ---------- | ------------------ |
|
||||||
| `DELETE` | `/kv/:key` | `application/json` |
|
| `DELETE` | `/kv/:key` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -3,7 +3,7 @@ layout: api
|
||||||
page_title: Namespace - HTTP API
|
page_title: Namespace - HTTP API
|
||||||
sidebar_current: api-namespaces
|
sidebar_current: api-namespaces
|
||||||
description: |-
|
description: |-
|
||||||
The /namespace endpoints allow for managing Consul Enterprise Namespaces.
|
The /namespace endpoints allow for managing Consul Enterprise Namespaces.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Namespace - HTTP API
|
# Namespace - HTTP API
|
||||||
|
|
@ -18,9 +18,9 @@ The functionality described here is available only in
|
||||||
|
|
||||||
This endpoint creates a new ACL token.
|
This endpoint creates a new ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------ | ------------------ |
|
||||||
| `PUT` | `/namespace` | `application/json` |
|
| `PUT` | `/namespace` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -28,9 +28,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ----------------- |
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||||
| `NO` | `none` | `none` | `operator:write` |
|
| `NO` | `none` | `none` | `operator:write` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -42,8 +42,8 @@ The table below shows this endpoint's support for
|
||||||
- `ACLs` `(object: <optional>)` - ACL configurations for this namespace. Rules from
|
- `ACLs` `(object: <optional>)` - ACL configurations for this namespace. Rules from
|
||||||
default policies and roles will be used only when there are no rules from directly linked
|
default policies and roles will be used only when there are no rules from directly linked
|
||||||
policies, roles and service identities that are for the target resource and segment.
|
policies, roles and service identities that are for the target resource and segment.
|
||||||
Therefore if a directly linked policy grants read access to some resource and a
|
Therefore if a directly linked policy grants read access to some resource and a
|
||||||
default policy grants write access, the effective access for the token will be read
|
default policy grants write access, the effective access for the token will be read
|
||||||
due to the default policies not being checked. When there is no rule concerning
|
due to the default policies not being checked. When there is no rule concerning
|
||||||
the resource in either the directly linked policies, roles and service identities
|
the resource in either the directly linked policies, roles and service identities
|
||||||
nor in those linked by the defaults, then the agents default policy configuration
|
nor in those linked by the defaults, then the agents default policy configuration
|
||||||
|
|
@ -51,13 +51,13 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `PolicyDefaults` `(array<ACLLink>)` - This is the list of default policies
|
- `PolicyDefaults` `(array<ACLLink>)` - This is the list of default policies
|
||||||
that should be applied to all tokens created in this namespace. The ACLLink
|
that should be applied to all tokens created in this namespace. The ACLLink
|
||||||
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
||||||
When a name is used instead of an ID, Consul will resolve the name to an ID
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
||||||
and store that internally.
|
and store that internally.
|
||||||
|
|
||||||
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
|
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
|
||||||
that should be applied to all tokens created in this namespace. The ACLLink
|
that should be applied to all tokens created in this namespace. The ACLLink
|
||||||
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
||||||
When a name is used instead of an ID, Consul will resolve the name to an ID
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
||||||
and store that internally.
|
and store that internally.
|
||||||
|
|
||||||
|
|
@ -68,29 +68,29 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "team-1",
|
"Name": "team-1",
|
||||||
"Description": "Namespace for Team 1",
|
"Description": "Namespace for Team 1",
|
||||||
"ACLs": {
|
"ACLs": {
|
||||||
"PolicyDefaults": [
|
"PolicyDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"RoleDefaults": [
|
"RoleDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "ns-team-2-read"
|
"Name": "ns-team-2-read"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"foo": "bar"
|
"foo": "bar"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -107,35 +107,35 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "team-1",
|
"Name": "team-1",
|
||||||
"Description": "Namespace for Team 1",
|
"Description": "Namespace for Team 1",
|
||||||
"ACLs": {
|
"ACLs": {
|
||||||
"PolicyDefaults": [
|
"PolicyDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"RoleDefaults": [
|
"RoleDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
||||||
"Name": "service-discovery"
|
"Name": "service-discovery"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
||||||
"Name": "ns-team-2-read"
|
"Name": "ns-team-2-read"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"foo": "bar"
|
"foo": "bar"
|
||||||
},
|
},
|
||||||
"CreateIndex": 55,
|
"CreateIndex": 55,
|
||||||
"ModifyIndex": 55
|
"ModifyIndex": 55
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -143,9 +143,9 @@ $ curl -X PUT \
|
||||||
|
|
||||||
This endpoint reads a Namespace with the given name.
|
This endpoint reads a Namespace with the given name.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `GET` | `/namespace/:name` | `application/json` |
|
| `GET` | `/namespace/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -153,11 +153,11 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
| ---------------- | ----------------- | ------------- | ------------------------------------------------ |
|
||||||
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1<sup> |
|
| `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
|
<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).
|
the request has been granted any access in the namespace (read, list or write).
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
@ -176,35 +176,35 @@ $ curl -H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "team-1",
|
"Name": "team-1",
|
||||||
"Description": "Namespace for Team 1",
|
"Description": "Namespace for Team 1",
|
||||||
"ACLs": {
|
"ACLs": {
|
||||||
"PolicyDefaults": [
|
"PolicyDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"RoleDefaults": [
|
"RoleDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
||||||
"Name": "service-discovery"
|
"Name": "service-discovery"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
||||||
"Name": "ns-team-2-read"
|
"Name": "ns-team-2-read"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"foo": "bar"
|
"foo": "bar"
|
||||||
},
|
},
|
||||||
"CreateIndex": 55,
|
"CreateIndex": 55,
|
||||||
"ModifyIndex": 55
|
"ModifyIndex": 55
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -212,9 +212,9 @@ $ curl -H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
||||||
|
|
||||||
This endpoint updates a new ACL token.
|
This endpoint updates a new ACL token.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------ | ------------------ |
|
||||||
| `PUT` | `/namespace/:name` | `application/json` |
|
| `PUT` | `/namespace/:name` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -222,9 +222,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ----------------- |
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||||
| `NO` | `none` | `none` | `operator:write` |
|
| `NO` | `none` | `none` | `operator:write` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -237,8 +237,8 @@ The table below shows this endpoint's support for
|
||||||
- `ACLs` `(object: <optional>)` - ACL configurations for this Namespace. Rules from
|
- `ACLs` `(object: <optional>)` - ACL configurations for this Namespace. Rules from
|
||||||
default policies and roles will be used only when there are no rules from directly linked
|
default policies and roles will be used only when there are no rules from directly linked
|
||||||
policies, roles and service identities that are for the target resource and segment.
|
policies, roles and service identities that are for the target resource and segment.
|
||||||
Therefore if a directly linked policy grants read access to some resource and a
|
Therefore if a directly linked policy grants read access to some resource and a
|
||||||
default policy grants write access, the effective access for the token will be read
|
default policy grants write access, the effective access for the token will be read
|
||||||
due to the default policies not being checked. When there is no rule concerning
|
due to the default policies not being checked. When there is no rule concerning
|
||||||
the resource in either the directly linked policies, roles and service identities
|
the resource in either the directly linked policies, roles and service identities
|
||||||
nor in those linked by the defaults, then the agents default policy configuration
|
nor in those linked by the defaults, then the agents default policy configuration
|
||||||
|
|
@ -246,13 +246,13 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `PolicyDefaults` `(array<ACLLink>)` - This is the list of default policies
|
- `PolicyDefaults` `(array<ACLLink>)` - This is the list of default policies
|
||||||
that should be applied to all tokens created in this namespace. The ACLLink
|
that should be applied to all tokens created in this namespace. The ACLLink
|
||||||
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
||||||
When a name is used instead of an ID, Consul will resolve the name to an ID
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
||||||
and store that internally.
|
and store that internally.
|
||||||
|
|
||||||
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
|
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
|
||||||
that should be applied to all tokens created in this namespace. The ACLLink
|
that should be applied to all tokens created in this namespace. The ACLLink
|
||||||
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
||||||
When a name is used instead of an ID, Consul will resolve the name to an ID
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
||||||
and store that internally.
|
and store that internally.
|
||||||
|
|
||||||
|
|
@ -263,28 +263,28 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Description": "Namespace for Team 1",
|
"Description": "Namespace for Team 1",
|
||||||
"ACLs": {
|
"ACLs": {
|
||||||
"PolicyDefaults": [
|
"PolicyDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"RoleDefaults": [
|
"RoleDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Name": "ns-team-2-read"
|
"Name": "ns-team-2-read"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"foo": "bar"
|
"foo": "bar"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -301,35 +301,35 @@ $ curl -X PUT \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "team-1",
|
"Name": "team-1",
|
||||||
"Description": "Namespace for Team 1",
|
"Description": "Namespace for Team 1",
|
||||||
"ACLs": {
|
"ACLs": {
|
||||||
"PolicyDefaults": [
|
"PolicyDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"RoleDefaults": [
|
"RoleDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
||||||
"Name": "service-discovery"
|
"Name": "service-discovery"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
||||||
"Name": "ns-team-2-read"
|
"Name": "ns-team-2-read"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"foo": "bar"
|
"foo": "bar"
|
||||||
},
|
},
|
||||||
"CreateIndex": 55,
|
"CreateIndex": 55,
|
||||||
"ModifyIndex": 55
|
"ModifyIndex": 55
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -342,9 +342,9 @@ Until then, further reads can be performed on the namespace and a `DeletedAt`
|
||||||
field will now be populated with the timestamp of when the Namespace was
|
field will now be populated with the timestamp of when the Namespace was
|
||||||
marked for deletion.
|
marked for deletion.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ------------------------- | -------------------------- |
|
| -------- | ------------------ | -------- |
|
||||||
| `DELETE` | `/namespace/:name` | N/A |
|
| `DELETE` | `/namespace/:name` | N/A |
|
||||||
|
|
||||||
This endpoint will return no data. Success or failure is indicated by the status
|
This endpoint will return no data. Success or failure is indicated by the status
|
||||||
code returned.
|
code returned.
|
||||||
|
|
@ -355,9 +355,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||||
| `NO` | `none` | `none` | `operator:write` |
|
| `NO` | `none` | `none` | `operator:write` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -376,47 +376,47 @@ $ curl -X DELETE \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "team-1",
|
"Name": "team-1",
|
||||||
"Description": "Namespace for Team 1",
|
"Description": "Namespace for Team 1",
|
||||||
"ACLs": {
|
"ACLs": {
|
||||||
"PolicyDefaults": [
|
"PolicyDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
||||||
"Name": "service-read"
|
"Name": "service-read"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
||||||
"Name": "node-read"
|
"Name": "node-read"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"RoleDefaults": [
|
"RoleDefaults": [
|
||||||
{
|
{
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
||||||
"Name": "service-discovery"
|
"Name": "service-discovery"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
||||||
"Name": "ns-team-2-read"
|
"Name": "ns-team-2-read"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"Meta": {
|
"Meta": {
|
||||||
"foo": "bar"
|
"foo": "bar"
|
||||||
},
|
},
|
||||||
"DeletedAt": "2019-12-02T23:00:00Z",
|
"DeletedAt": "2019-12-02T23:00:00Z",
|
||||||
"CreateIndex": 55,
|
"CreateIndex": 55,
|
||||||
"ModifyIndex": 100
|
"ModifyIndex": 100
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## List all Namespaces
|
## List all Namespaces
|
||||||
|
|
||||||
This endpoint lists all the Namespaces. The output will be filtered based on the
|
This endpoint lists all the Namespaces. The output will be filtered based on the
|
||||||
privileges of the ACL token used for the request.
|
privileges of the ACL token used for the request.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------- | ------------------ |
|
||||||
| `GET` | `/namespaces` | `application/json` |
|
| `GET` | `/namespaces` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -424,11 +424,11 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
|
||||||
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1</sup> |
|
| `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
|
<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).
|
the request has been granted any access in the namespace (read, list or write).
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
@ -442,42 +442,42 @@ $ curl -H "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"Name": "default",
|
"Name": "default",
|
||||||
"Description": "Builtin Default Namespace",
|
"Description": "Builtin Default Namespace",
|
||||||
"CreateIndex": 6,
|
"CreateIndex": 6,
|
||||||
"ModifyIndex": 6
|
"ModifyIndex": 6
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Name": "team-1",
|
||||||
|
"Description": "Namespace for Team 1",
|
||||||
|
"ACLs": {
|
||||||
|
"PolicyDefaults": [
|
||||||
|
{
|
||||||
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
||||||
|
"Name": "service-read"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
||||||
|
"Name": "node-read"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"RoleDefaults": [
|
||||||
|
{
|
||||||
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
||||||
|
"Name": "service-discovery"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
||||||
|
"Name": "ns-team-2-read"
|
||||||
|
}
|
||||||
|
]
|
||||||
},
|
},
|
||||||
{
|
"Meta": {
|
||||||
"Name": "team-1",
|
"foo": "bar"
|
||||||
"Description": "Namespace for Team 1",
|
},
|
||||||
"ACLs": {
|
"CreateIndex": 55,
|
||||||
"PolicyDefaults": [
|
"ModifyIndex": 55
|
||||||
{
|
}
|
||||||
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
|
||||||
"Name": "service-read"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
|
||||||
"Name": "node-read"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"RoleDefaults": [
|
|
||||||
{
|
|
||||||
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
|
||||||
"Name": "service-discovery"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
|
||||||
"Name": "ns-team-2-read"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"Meta": {
|
|
||||||
"foo": "bar"
|
|
||||||
},
|
|
||||||
"CreateIndex": 55,
|
|
||||||
"ModifyIndex": 55
|
|
||||||
}
|
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
@ -33,9 +33,9 @@ Please see the [Network Areas Guide](https://learn.hashicorp.com/consul/day-2-op
|
||||||
This endpoint creates a new network area and returns its ID if it is created
|
This endpoint creates a new network area and returns its ID if it is created
|
||||||
successfully.
|
successfully.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `POST` | `/operator/area` | `application/json` |
|
| `POST` | `/operator/area` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -73,7 +73,7 @@ The table below shows this endpoint's support for
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"PeerDatacenter": "dc2",
|
"PeerDatacenter": "dc2",
|
||||||
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ],
|
"RetryJoin": ["10.1.2.3", "10.1.2.4", "10.1.2.5"],
|
||||||
"UseTLS": false
|
"UseTLS": false
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
@ -99,9 +99,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint lists all network areas.
|
This endpoint lists all network areas.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------- | ------------------ |
|
||||||
| `GET` | `/operator/area` | `application/json` |
|
| `GET` | `/operator/area` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -142,9 +142,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint updates a network area to the given configuration.
|
This endpoint updates a network area to the given configuration.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `PUT` | `/operator/area/:uuid` | `application/json` |
|
| `PUT` | `/operator/area/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -186,9 +186,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint lists a specific network area.
|
This endpoint lists a specific network area.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `GET` | `/operator/area/:uuid` | `application/json` |
|
| `GET` | `/operator/area/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -232,9 +232,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint deletes a specific network area.
|
This endpoint deletes a specific network area.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ---------------------------- | -------------------------- |
|
| -------- | ---------------------- | ------------------ |
|
||||||
| `DELETE` | `/operator/area/:uuid` | `application/json` |
|
| `DELETE` | `/operator/area/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -268,9 +268,9 @@ $ curl \
|
||||||
This endpoint attempts to join the given Consul servers into a specific network
|
This endpoint attempts to join the given Consul servers into a specific network
|
||||||
area.
|
area.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `PUT` | `/operator/area/:uuid/join` | `application/json` |
|
| `PUT` | `/operator/area/:uuid/join` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -341,9 +341,9 @@ $ curl \
|
||||||
This endpoint provides a listing of the Consul servers present in a specific
|
This endpoint provides a listing of the Consul servers present in a specific
|
||||||
network area.
|
network area.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------ | -------------------------- |
|
| ------ | ------------------------------ | ------------------ |
|
||||||
| `GET` | `/operator/area/:uuid/members` | `application/json` |
|
| `GET` | `/operator/area/:uuid/members` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -386,7 +386,7 @@ $ curl \
|
||||||
"Protocol": 2,
|
"Protocol": 2,
|
||||||
"Status": "alive",
|
"Status": "alive",
|
||||||
"RTT": 256478
|
"RTT": 256478
|
||||||
},
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -20,8 +20,8 @@ Please see the [Autopilot Guide](https://learn.hashicorp.com/consul/day-2-operat
|
||||||
|
|
||||||
This endpoint retrieves its latest Autopilot configuration.
|
This endpoint retrieves its latest Autopilot configuration.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------------------------- | ------------------ |
|
||||||
| `GET` | `/operator/autopilot/configuration` | `application/json` |
|
| `GET` | `/operator/autopilot/configuration` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
|
|
@ -74,8 +74,8 @@ For more information about the Autopilot configuration options, see the
|
||||||
|
|
||||||
This endpoint updates the Autopilot configuration of the cluster.
|
This endpoint updates the Autopilot configuration of the cluster.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------------------------- | ------------------ |
|
||||||
| `PUT` | `/operator/autopilot/configuration` | `application/json` |
|
| `PUT` | `/operator/autopilot/configuration` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
|
|
@ -151,9 +151,9 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
This endpoint queries the health of the autopilot status.
|
This endpoint queries the health of the autopilot status.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------------- | ------------------ |
|
||||||
| `GET` | `/operator/autopilot/health` | `application/json` |
|
| `GET` | `/operator/autopilot/health` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -16,15 +16,15 @@ more details on the gossip protocol and its use.
|
||||||
## List Gossip Encryption Keys
|
## List Gossip Encryption Keys
|
||||||
|
|
||||||
This endpoint lists the gossip encryption keys installed on both the WAN and LAN
|
This endpoint lists the gossip encryption keys installed on both the WAN and LAN
|
||||||
rings of every known datacenter, unless otherwise specified with the `local-only`
|
rings of every known datacenter, unless otherwise specified with the `local-only`
|
||||||
query parameter (see below).
|
query parameter (see below).
|
||||||
|
|
||||||
If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
|
If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
|
||||||
read privileges.
|
read privileges.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `GET` | `/operator/keyring` | `application/json` |
|
| `GET` | `/operator/keyring` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -42,7 +42,7 @@ The table below shows this endpoint's support for
|
||||||
non-zero value will cause nodes to relay their responses through this many
|
non-zero value will cause nodes to relay their responses through this many
|
||||||
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
|
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
|
||||||
This is specified as part of the URL as a query parameter.
|
This is specified as part of the URL as a query parameter.
|
||||||
- `local-only` `(bool: false)` - Setting `local-only` to true will force keyring
|
- `local-only` `(bool: false)` - Setting `local-only` to true will force keyring
|
||||||
list queries to only hit local servers (no WAN traffic). This flag can only be set
|
list queries to only hit local servers (no WAN traffic). This flag can only be set
|
||||||
for list queries. It is specified as part of the URL as a query parameter.
|
for list queries. It is specified as part of the URL as a query parameter.
|
||||||
|
|
||||||
|
|
@ -83,7 +83,7 @@ $ curl \
|
||||||
```
|
```
|
||||||
|
|
||||||
- `WAN` is true if the block refers to the WAN ring of that datacenter (rather
|
- `WAN` is true if the block refers to the WAN ring of that datacenter (rather
|
||||||
than LAN).
|
than LAN).
|
||||||
|
|
||||||
- `Datacenter` is the datacenter the block refers to.
|
- `Datacenter` is the datacenter the block refers to.
|
||||||
|
|
||||||
|
|
@ -98,9 +98,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint installs a new gossip encryption key into the cluster.
|
This endpoint installs a new gossip encryption key into the cluster.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `POST` | `/operator/keyring` | `application/json` |
|
| `POST` | `/operator/keyring` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -144,9 +144,9 @@ $ curl \
|
||||||
This endpoint changes the primary gossip encryption key. The key must already be
|
This endpoint changes the primary gossip encryption key. The key must already be
|
||||||
installed before this operation can succeed.
|
installed before this operation can succeed.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `PUT` | `/operator/keyring` | `application/json` |
|
| `PUT` | `/operator/keyring` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -172,7 +172,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
|
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -190,9 +190,9 @@ $ curl \
|
||||||
This endpoint removes a gossip encryption key from the cluster. This operation
|
This endpoint removes a gossip encryption key from the cluster. This operation
|
||||||
may only be performed on keys which are not currently the primary key.
|
may only be performed on keys which are not currently the primary key.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------- | ---------------------------- | -------------------------- |
|
| -------- | ------------------- | ------------------ |
|
||||||
| `DELETE`| `/operator/keyring` | `application/json` |
|
| `DELETE` | `/operator/keyring` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -217,7 +217,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
|
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -19,9 +19,9 @@ The licensing functionality described here is available only in
|
||||||
|
|
||||||
This endpoint gets information about the current license.
|
This endpoint gets information about the current license.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `GET` | `/operator/license` | `application/json` |
|
| `GET` | `/operator/license` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -29,9 +29,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
| ---------------- | ----------------- | ------------- | ------------ |
|
||||||
| `NO` | `all` | `none` | `none` |
|
| `NO` | `all` | `none` | `none` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
|
@ -50,29 +50,29 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Valid": true,
|
"Valid": true,
|
||||||
"License": {
|
"License": {
|
||||||
"license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c",
|
"license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c",
|
||||||
"customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b",
|
"customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b",
|
||||||
"installation_id": "*",
|
"installation_id": "*",
|
||||||
"issue_time": "2018-05-21T20:03:35.911567355Z",
|
"issue_time": "2018-05-21T20:03:35.911567355Z",
|
||||||
"start_time": "2018-05-21T04:00:00Z",
|
"start_time": "2018-05-21T04:00:00Z",
|
||||||
"expiration_time": "2019-05-22T03:59:59.999Z",
|
"expiration_time": "2019-05-22T03:59:59.999Z",
|
||||||
"product": "consul",
|
"product": "consul",
|
||||||
"flags": {
|
"flags": {
|
||||||
"package": "premium"
|
"package": "premium"
|
||||||
},
|
|
||||||
"features": [
|
|
||||||
"Automated Backups",
|
|
||||||
"Automated Upgrades",
|
|
||||||
"Enhanced Read Scalability",
|
|
||||||
"Network Segments",
|
|
||||||
"Redundancy Zone",
|
|
||||||
"Advanced Network Federation"
|
|
||||||
],
|
|
||||||
"temporary": false
|
|
||||||
},
|
},
|
||||||
"Warnings": []
|
"features": [
|
||||||
|
"Automated Backups",
|
||||||
|
"Automated Upgrades",
|
||||||
|
"Enhanced Read Scalability",
|
||||||
|
"Network Segments",
|
||||||
|
"Redundancy Zone",
|
||||||
|
"Advanced Network Federation"
|
||||||
|
],
|
||||||
|
"temporary": false
|
||||||
|
},
|
||||||
|
"Warnings": []
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -81,9 +81,9 @@ $ curl \
|
||||||
This endpoint updates the Consul license and returns some of the
|
This endpoint updates the Consul license and returns some of the
|
||||||
license contents as well as any warning messages regarding its validity.
|
license contents as well as any warning messages regarding its validity.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `PUT` | `/operator/license` | `application/json` |
|
| `PUT` | `/operator/license` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -118,29 +118,29 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Valid": true,
|
"Valid": true,
|
||||||
"License": {
|
"License": {
|
||||||
"license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c",
|
"license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c",
|
||||||
"customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b",
|
"customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b",
|
||||||
"installation_id": "*",
|
"installation_id": "*",
|
||||||
"issue_time": "2018-05-21T20:03:35.911567355Z",
|
"issue_time": "2018-05-21T20:03:35.911567355Z",
|
||||||
"start_time": "2018-05-21T04:00:00Z",
|
"start_time": "2018-05-21T04:00:00Z",
|
||||||
"expiration_time": "2019-05-22T03:59:59.999Z",
|
"expiration_time": "2019-05-22T03:59:59.999Z",
|
||||||
"product": "consul",
|
"product": "consul",
|
||||||
"flags": {
|
"flags": {
|
||||||
"package": "premium"
|
"package": "premium"
|
||||||
},
|
|
||||||
"features": [
|
|
||||||
"Automated Backups",
|
|
||||||
"Automated Upgrades",
|
|
||||||
"Enhanced Read Scalability",
|
|
||||||
"Network Segments",
|
|
||||||
"Redundancy Zone",
|
|
||||||
"Advanced Network Federation"
|
|
||||||
],
|
|
||||||
"temporary": false
|
|
||||||
},
|
},
|
||||||
"Warnings": []
|
"features": [
|
||||||
|
"Automated Backups",
|
||||||
|
"Automated Upgrades",
|
||||||
|
"Enhanced Read Scalability",
|
||||||
|
"Network Segments",
|
||||||
|
"Redundancy Zone",
|
||||||
|
"Advanced Network Federation"
|
||||||
|
],
|
||||||
|
"temporary": false
|
||||||
|
},
|
||||||
|
"Warnings": []
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -148,9 +148,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint resets the Consul license to the license included in the Enterprise binary. If the included license is not valid, the replace will fail.
|
This endpoint resets the Consul license to the license included in the Enterprise binary. If the included license is not valid, the replace will fail.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ---------------------------- | -------------------------- |
|
| -------- | ------------------- | ------------------ |
|
||||||
| `DELETE` | `/operator/license` | `application/json` |
|
| `DELETE` | `/operator/license` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -180,28 +180,28 @@ $ curl \
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Valid": true,
|
"Valid": true,
|
||||||
"License": {
|
"License": {
|
||||||
"license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c",
|
"license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c",
|
||||||
"customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b",
|
"customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b",
|
||||||
"installation_id": "*",
|
"installation_id": "*",
|
||||||
"issue_time": "2018-05-21T20:03:35.911567355Z",
|
"issue_time": "2018-05-21T20:03:35.911567355Z",
|
||||||
"start_time": "2018-05-21T04:00:00Z",
|
"start_time": "2018-05-21T04:00:00Z",
|
||||||
"expiration_time": "2019-05-22T03:59:59.999Z",
|
"expiration_time": "2019-05-22T03:59:59.999Z",
|
||||||
"product": "consul",
|
"product": "consul",
|
||||||
"flags": {
|
"flags": {
|
||||||
"package": "premium"
|
"package": "premium"
|
||||||
},
|
|
||||||
"features": [
|
|
||||||
"Automated Backups",
|
|
||||||
"Automated Upgrades",
|
|
||||||
"Enhanced Read Scalability",
|
|
||||||
"Network Segments",
|
|
||||||
"Redundancy Zone",
|
|
||||||
"Advanced Network Federation"
|
|
||||||
],
|
|
||||||
"temporary": false
|
|
||||||
},
|
},
|
||||||
"Warnings": []
|
"features": [
|
||||||
|
"Automated Backups",
|
||||||
|
"Automated Upgrades",
|
||||||
|
"Enhanced Read Scalability",
|
||||||
|
"Network Segments",
|
||||||
|
"Redundancy Zone",
|
||||||
|
"Advanced Network Federation"
|
||||||
|
],
|
||||||
|
"temporary": false
|
||||||
|
},
|
||||||
|
"Warnings": []
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
@ -19,9 +19,9 @@ more information about Raft consensus protocol and its use.
|
||||||
|
|
||||||
This endpoint reads the current raft configuration.
|
This endpoint reads the current raft configuration.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ------------------------------ | -------------------------- |
|
| ------ | ------------------------------ | ------------------ |
|
||||||
| `GET` | `/operator/raft/configuration` | `application/json` |
|
| `GET` | `/operator/raft/configuration` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -117,9 +117,9 @@ the Raft quorum.
|
||||||
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
|
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
|
||||||
write privileges.
|
write privileges.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| -------- | ---------------------------- | -------------------------- |
|
| -------- | --------------------- | ------------------ |
|
||||||
| `DELETE` | `/operator/raft/peer` | `application/json` |
|
| `DELETE` | `/operator/raft/peer` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -26,9 +26,9 @@ Please see the [Network Segments Guide](https://learn.hashicorp.com/consul/day-2
|
||||||
|
|
||||||
This endpoint lists all network areas.
|
This endpoint lists all network areas.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------------------- | ------------------ |
|
||||||
| `GET` | `/operator/segment` | `application/json` |
|
| `GET` | `/operator/segment` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -56,5 +56,5 @@ $ curl \
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
["","alpha","beta"]
|
["", "alpha", "beta"]
|
||||||
```
|
```
|
||||||
|
|
@ -92,18 +92,19 @@ populate the query before it is executed. All of the string fields inside the
|
||||||
initiated the query. This can be used with the `NodeMeta` field to limit the results
|
initiated the query. This can be used with the `NodeMeta` field to limit the results
|
||||||
of a query to service instances within its own network segment:
|
of a query to service instances within its own network segment:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"Name": "",
|
"Name": "",
|
||||||
"Template": {
|
"Template": {
|
||||||
"Type": "name_prefix_match"
|
"Type": "name_prefix_match"
|
||||||
},
|
},
|
||||||
"Service": {
|
"Service": {
|
||||||
"Service": "${name.full}",
|
"Service": "${name.full}",
|
||||||
"NodeMeta": {"consul-network-segment": "${agent.segment}"}
|
"NodeMeta": { "consul-network-segment": "${agent.segment}" }
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
}
|
||||||
|
```
|
||||||
|
|
||||||
This will map all names of the form `<service>.query.consul` over DNS to a query
|
This will map all names of the form `<service>.query.consul` over DNS to a query
|
||||||
that will select an instance of the service in the agent's own network segment.
|
that will select an instance of the service in the agent's own network segment.
|
||||||
|
|
||||||
|
|
@ -137,9 +138,9 @@ only a single catch-all template can be registered at any time.
|
||||||
This endpoint creates a new prepared query and returns its ID if it is created
|
This endpoint creates a new prepared query and returns its ID if it is created
|
||||||
successfully.
|
successfully.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------- | ------------------ |
|
||||||
| `POST` | `/query` | `application/json` |
|
| `POST` | `/query` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -183,21 +184,21 @@ The table below shows this endpoint's support for
|
||||||
the query is executed. It allows the use of nodes in other datacenters with
|
the query is executed. It allows the use of nodes in other datacenters with
|
||||||
very little configuration.
|
very little configuration.
|
||||||
|
|
||||||
- `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up
|
- `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up
|
||||||
to `NearestN` other datacenters based on their estimated network round
|
to `NearestN` other datacenters based on their estimated network round
|
||||||
trip time using [Network Coordinates](/docs/internals/coordinates.html)
|
trip time using [Network Coordinates](/docs/internals/coordinates.html)
|
||||||
from the WAN gossip pool. The median round trip time from the server
|
from the WAN gossip pool. The median round trip time from the server
|
||||||
handling the query to the servers in the remote datacenter is used to
|
handling the query to the servers in the remote datacenter is used to
|
||||||
determine the priority.
|
determine the priority.
|
||||||
|
|
||||||
- `Datacenters` `(array<string>: nil)` - Specifies a fixed list of remote
|
- `Datacenters` `(array<string>: nil)` - Specifies a fixed list of remote
|
||||||
datacenters to forward the query to if there are no healthy nodes in the
|
datacenters to forward the query to if there are no healthy nodes in the
|
||||||
local datacenter. Datacenters are queried in the order given in the
|
local datacenter. Datacenters are queried in the order given in the
|
||||||
list. If this option is combined with `NearestN`, then the `NearestN`
|
list. If this option is combined with `NearestN`, then the `NearestN`
|
||||||
queries will be performed first, followed by the list given by
|
queries will be performed first, followed by the list given by
|
||||||
`Datacenters`. A given datacenter will only be queried one time during a
|
`Datacenters`. A given datacenter will only be queried one time during a
|
||||||
failover, even if it is selected by both `NearestN` and is listed in
|
failover, even if it is selected by both `NearestN` and is listed in
|
||||||
`Datacenters`.
|
`Datacenters`.
|
||||||
|
|
||||||
- `IgnoreCheckIDs` `(array<string>: nil)` - Specifies a list of check IDs that
|
- `IgnoreCheckIDs` `(array<string>: nil)` - Specifies a list of check IDs that
|
||||||
should be ignored when filtering unhealthy instances. This is mostly useful
|
should be ignored when filtering unhealthy instances. This is mostly useful
|
||||||
|
|
@ -212,41 +213,40 @@ The table below shows this endpoint's support for
|
||||||
true, only nodes with checks in the passing state will be returned.
|
true, only nodes with checks in the passing state will be returned.
|
||||||
|
|
||||||
- `Near` `(string: "")` - Specifies a node to sort near based on distance
|
- `Near` `(string: "")` - Specifies a node to sort near based on distance
|
||||||
sorting using [Network Coordinates](/docs/internals/coordinates.html). The
|
sorting using [Network Coordinates](/docs/internals/coordinates.html). The
|
||||||
nearest instance to the specified node will be returned first, and subsequent
|
nearest instance to the specified node will be returned first, and subsequent
|
||||||
nodes in the response will be sorted in ascending order of estimated
|
nodes in the response will be sorted in ascending order of estimated
|
||||||
round-trip times. If the node given does not exist, the nodes in the response
|
round-trip times. If the node given does not exist, the nodes in the response
|
||||||
will be shuffled. If unspecified, the response will be shuffled by default.
|
will be shuffled. If unspecified, the response will be shuffled by default.
|
||||||
|
|
||||||
- `_agent` - Returns results nearest the agent servicing the request.
|
- `_agent` - Returns results nearest the agent servicing the request.
|
||||||
- `_ip` - Returns results nearest to the node associated with the source IP
|
- `_ip` - Returns results nearest to the node associated with the source IP
|
||||||
where the query was executed from. For HTTP the source IP is the remote
|
where the query was executed from. For HTTP the source IP is the remote
|
||||||
peer's IP address or the value of the X-Forwarded-For header with the
|
peer's IP address or the value of the X-Forwarded-For header with the
|
||||||
header taking precedence. For DNS the source IP is the remote peer's IP
|
header taking precedence. For DNS the source IP is the remote peer's IP
|
||||||
address or the value of the EDNS client IP with the EDNS client IP
|
address or the value of the EDNS client IP with the EDNS client IP
|
||||||
taking precedence.
|
taking precedence.
|
||||||
|
|
||||||
|
* `Tags` `(array<string>: nil)` - Specifies a list of service tags to filter
|
||||||
|
the query results. For a service to pass the tag filter it must have _all_
|
||||||
|
of the required tags, and _none_ of the excluded tags (prefixed with `!`).
|
||||||
|
|
||||||
- `Tags` `(array<string>: nil)` - Specifies a list of service tags to filter
|
* `NodeMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
|
||||||
the query results. For a service to pass the tag filter it must have *all*
|
key/value pairs that will be used for filtering the query results to nodes
|
||||||
of the required tags, and *none* of the excluded tags (prefixed with `!`).
|
with the given metadata values present.
|
||||||
|
|
||||||
- `NodeMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
|
* `ServiceMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
|
||||||
key/value pairs that will be used for filtering the query results to nodes
|
key/value pairs that will be used for filtering the query results to services
|
||||||
with the given metadata values present.
|
with the given metadata values present.
|
||||||
|
|
||||||
- `ServiceMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
|
* `Connect` `(bool: false)` - If true, only [Connect-capable](/docs/connect/index.html) services
|
||||||
key/value pairs that will be used for filtering the query results to services
|
for the specified service name will be returned. This includes both
|
||||||
with the given metadata values present.
|
natively integrated services and proxies. For proxies, the proxy name
|
||||||
|
may not match `Service`, because the proxy destination will. Any
|
||||||
|
constrains beyond the service name such as `Near`, `Tags`, and `NodeMeta`
|
||||||
|
are applied to Connect-capable service.
|
||||||
|
|
||||||
- `Connect` `(bool: false)` - If true, only [Connect-capable](/docs/connect/index.html) services
|
* `DNS` `(DNS: nil)` - Specifies DNS configuration
|
||||||
for the specified service name will be returned. This includes both
|
|
||||||
natively integrated services and proxies. For proxies, the proxy name
|
|
||||||
may not match `Service`, because the proxy destination will. Any
|
|
||||||
constrains beyond the service name such as `Near`, `Tags`, and `NodeMeta`
|
|
||||||
are applied to Connect-capable service.
|
|
||||||
|
|
||||||
- `DNS` `(DNS: nil)` - Specifies DNS configuration
|
|
||||||
|
|
||||||
- `TTL` `(string: "")` - Specifies the TTL duration when query results are
|
- `TTL` `(string: "")` - Specifies the TTL duration when query results are
|
||||||
served over DNS. If this is specified, it will take precedence over any
|
served over DNS. If this is specified, it will take precedence over any
|
||||||
|
|
@ -268,8 +268,8 @@ The table below shows this endpoint's support for
|
||||||
"Near": "node1",
|
"Near": "node1",
|
||||||
"OnlyPassing": false,
|
"OnlyPassing": false,
|
||||||
"Tags": ["primary", "!experimental"],
|
"Tags": ["primary", "!experimental"],
|
||||||
"NodeMeta": {"instance_type": "m3.large"},
|
"NodeMeta": { "instance_type": "m3.large" },
|
||||||
"ServiceMeta": {"environment": "production"}
|
"ServiceMeta": { "environment": "production" }
|
||||||
},
|
},
|
||||||
"DNS": {
|
"DNS": {
|
||||||
"TTL": "10s"
|
"TTL": "10s"
|
||||||
|
|
@ -298,9 +298,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint returns a list of all prepared queries.
|
This endpoint returns a list of all prepared queries.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------- | ------------------ |
|
||||||
| `GET` | `/query` | `application/json` |
|
| `GET` | `/query` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -342,8 +342,8 @@ $ curl \
|
||||||
},
|
},
|
||||||
"OnlyPassing": false,
|
"OnlyPassing": false,
|
||||||
"Tags": ["primary", "!experimental"],
|
"Tags": ["primary", "!experimental"],
|
||||||
"NodeMeta": {"instance_type": "m3.large"},
|
"NodeMeta": { "instance_type": "m3.large" },
|
||||||
"ServiceMeta": {"environment": "production"}
|
"ServiceMeta": { "environment": "production" }
|
||||||
},
|
},
|
||||||
"DNS": {
|
"DNS": {
|
||||||
"TTL": "10s"
|
"TTL": "10s"
|
||||||
|
|
@ -361,9 +361,9 @@ $ curl \
|
||||||
This endpoint updates an existing prepared query. If no query exists by the
|
This endpoint updates an existing prepared query. If no query exists by the
|
||||||
given ID, an error is returned.
|
given ID, an error is returned.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------- | ------------------ |
|
||||||
| `PUT` | `/query/:uuid` | `application/json` |
|
| `PUT` | `/query/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -401,9 +401,9 @@ $ curl \
|
||||||
This endpoint reads an existing prepared query. If no query exists by the
|
This endpoint reads an existing prepared query. If no query exists by the
|
||||||
given ID, an error is returned.
|
given ID, an error is returned.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | -------------- | ------------------ |
|
||||||
| `GET` | `/query/:uuid` | `application/json` |
|
| `GET` | `/query/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -441,9 +441,9 @@ with a single item present.
|
||||||
This endpoint deletes an existing prepared query. If no query exists by the
|
This endpoint deletes an existing prepared query. If no query exists by the
|
||||||
given ID, an error is returned.
|
given ID, an error is returned.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| --------- | ---------------------------- | -------------------------- |
|
| -------- | -------------- | ------------------ |
|
||||||
| `DELETE` | `/query/:uuid` | `application/json` |
|
| `DELETE` | `/query/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -477,9 +477,9 @@ $ curl \
|
||||||
This endpoint executes an existing prepared query. If no query exists by the
|
This endpoint executes an existing prepared query. If no query exists by the
|
||||||
given ID, an error is returned.
|
given ID, an error is returned.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `GET` | `/query/:uuid/execute` | `application/json` |
|
| `GET` | `/query/:uuid/execute` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -487,9 +487,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
| ---------------- | ----------------- | ------------- | --------------------- |
|
||||||
| `NO` | `none` | `simple` | `depends`<sup>1</sup> |
|
| `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
|
<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
|
will be used when executing the request. Otherwise, the client's supplied ACL
|
||||||
|
|
@ -545,13 +545,13 @@ $ curl \
|
||||||
"lan": "10.1.10.12",
|
"lan": "10.1.10.12",
|
||||||
"wan": "10.1.10.12"
|
"wan": "10.1.10.12"
|
||||||
},
|
},
|
||||||
"NodeMeta": {"instance_type": "m3.large"}
|
"NodeMeta": { "instance_type": "m3.large" }
|
||||||
},
|
},
|
||||||
"Service": {
|
"Service": {
|
||||||
"ID": "redis",
|
"ID": "redis",
|
||||||
"Service": "redis",
|
"Service": "redis",
|
||||||
"Tags": null,
|
"Tags": null,
|
||||||
"Meta": {"redis_version": "4.0"},
|
"Meta": { "redis_version": "4.0" },
|
||||||
"Port": 8000
|
"Port": 8000
|
||||||
},
|
},
|
||||||
"Checks": [
|
"Checks": [
|
||||||
|
|
@ -576,12 +576,13 @@ $ curl \
|
||||||
"ServiceName": ""
|
"ServiceName": ""
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"DNS": {
|
"DNS": {
|
||||||
"TTL": "10s"
|
"TTL": "10s"
|
||||||
},
|
},
|
||||||
"Datacenter": "dc3",
|
"Datacenter": "dc3",
|
||||||
"Failovers": 2
|
"Failovers": 2
|
||||||
}]
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -605,9 +606,9 @@ $ curl \
|
||||||
This endpoint generates a fully-rendered query for a given name, post
|
This endpoint generates a fully-rendered query for a given name, post
|
||||||
interpolation.
|
interpolation.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ---------------------- | ------------------ |
|
||||||
| `GET` | `/query/:uuid/explain` | `application/json` |
|
| `GET` | `/query/:uuid/explain` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -660,7 +661,7 @@ $ curl \
|
||||||
"OnlyPassing": true,
|
"OnlyPassing": true,
|
||||||
"Tags": ["primary"],
|
"Tags": ["primary"],
|
||||||
"Meta": { "mysql_version": "5.7.20" },
|
"Meta": { "mysql_version": "5.7.20" },
|
||||||
"NodeMeta": {"instance_type": "m3.large"}
|
"NodeMeta": { "instance_type": "m3.large" }
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
@ -15,9 +15,9 @@ The `/session` endpoints create, destroy, and query sessions in Consul.
|
||||||
This endpoint initializes a new session. Sessions must be associated with a
|
This endpoint initializes a new session. Sessions must be associated with a
|
||||||
node and may be associated with any number of checks.
|
node and may be associated with any number of checks.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ----------------- | ------------------ |
|
||||||
| `PUT` | `/session/create` | `application/json` |
|
| `PUT` | `/session/create` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -104,9 +104,9 @@ This endpoint destroys the session with the given name. If the session UUID is
|
||||||
malformed, an error is returned. If the session UUID does not exist or already
|
malformed, an error is returned. If the session UUID does not exist or already
|
||||||
expired, a 200 is still returned (the operation is idempotent).
|
expired, a 200 is still returned (the operation is idempotent).
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | -------------------------- |
|
| :----- | :----------------------- | ------------------ |
|
||||||
| `PUT` | `/session/destroy/:uuid` | `application/json` |
|
| `PUT` | `/session/destroy/:uuid` | `application/json` |
|
||||||
|
|
||||||
Even though the Content-Type is `application/json`, the response is
|
Even though the Content-Type is `application/json`, the response is
|
||||||
either a literal `true` or `false`, indicating of whether the destroy was
|
either a literal `true` or `false`, indicating of whether the destroy was
|
||||||
|
|
@ -130,7 +130,7 @@ The table below shows this endpoint's support for
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
||||||
the datacenter of the agent being queried. This is specified as part of the
|
the datacenter of the agent being queried. This is specified as part of the
|
||||||
URL as a query parameter. Using this across datacenters is not recommended.
|
URL as a query parameter. Using this across datacenters is not recommended.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
If not provided, the namespace will be inferred from the request's ACL token,
|
If not provided, the namespace will be inferred from the request's ACL token,
|
||||||
or will default to the `default` namespace. This is specified as part of the
|
or will default to the `default` namespace. This is specified as part of the
|
||||||
|
|
@ -154,9 +154,9 @@ true
|
||||||
|
|
||||||
This endpoint returns the requested session information.
|
This endpoint returns the requested session information.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | -------------------------- |
|
| :----- | :-------------------- | ------------------ |
|
||||||
| `GET` | `/session/info/:uuid` | `application/json` |
|
| `GET` | `/session/info/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -176,7 +176,7 @@ The table below shows this endpoint's support for
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
||||||
the datacenter of the agent being queried. This is specified as part of the
|
the datacenter of the agent being queried. This is specified as part of the
|
||||||
URL as a query parameter. Using this across datacenters is not recommended.
|
URL as a query parameter. Using this across datacenters is not recommended.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
If not provided, the namespace will be inferred from the request's ACL token,
|
If not provided, the namespace will be inferred from the request's ACL token,
|
||||||
or will default to the `default` namespace. This is specified as part of the
|
or will default to the `default` namespace. This is specified as part of the
|
||||||
|
|
@ -196,11 +196,9 @@ $ curl \
|
||||||
{
|
{
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||||
"Name": "test-session",
|
"Name": "test-session",
|
||||||
"Node": "raja-laptop-02",
|
"Node": "raja-laptop-02",
|
||||||
"Checks": [
|
"Checks": ["serfHealth"],
|
||||||
"serfHealth"
|
"LockDelay": 1.5e10,
|
||||||
],
|
|
||||||
"LockDelay": 1.5e+10,
|
|
||||||
"Behavior": "release",
|
"Behavior": "release",
|
||||||
"TTL": "30s",
|
"TTL": "30s",
|
||||||
"CreateIndex": 1086449,
|
"CreateIndex": 1086449,
|
||||||
|
|
@ -215,9 +213,9 @@ If the session does not exist, an empty JSON list `[]` is returned.
|
||||||
|
|
||||||
This endpoint returns the active sessions for a given node.
|
This endpoint returns the active sessions for a given node.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | -------------------------- |
|
| :----- | :-------------------- | ------------------ |
|
||||||
| `GET` | `/session/node/:node` | `application/json` |
|
| `GET` | `/session/node/:node` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -237,12 +235,12 @@ The table below shows this endpoint's support for
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
||||||
the datacenter of the agent being queried. This is specified as part of the
|
the datacenter of the agent being queried. This is specified as part of the
|
||||||
URL as a query parameter. Using this across datacenters is not recommended.
|
URL as a query parameter. Using this across datacenters is not recommended.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
If not provided, the namespace will be inferred from the request's ACL token,
|
If not provided, the namespace will be inferred from the request's ACL token,
|
||||||
or will default to the `default` namespace. This is specified as part of the
|
or will default to the `default` namespace. This is specified as part of the
|
||||||
URL as a query parameter
|
URL as a query parameter
|
||||||
The namespace may be specified as '*' and then results will be returned for all namespaces.
|
The namespace may be specified as '\*' and then results will be returned for all namespaces.
|
||||||
Added in Consul 1.7.0.
|
Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
@ -259,11 +257,9 @@ $ curl \
|
||||||
{
|
{
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||||
"Name": "test-session",
|
"Name": "test-session",
|
||||||
"Node": "raja-laptop-02",
|
"Node": "raja-laptop-02",
|
||||||
"Checks": [
|
"Checks": ["serfHealth"],
|
||||||
"serfHealth"
|
"LockDelay": 1.5e10,
|
||||||
],
|
|
||||||
"LockDelay": 1.5e+10,
|
|
||||||
"Behavior": "release",
|
"Behavior": "release",
|
||||||
"TTL": "30s",
|
"TTL": "30s",
|
||||||
"CreateIndex": 1086449,
|
"CreateIndex": 1086449,
|
||||||
|
|
@ -276,9 +272,9 @@ $ curl \
|
||||||
|
|
||||||
This endpoint returns the list of active sessions.
|
This endpoint returns the list of active sessions.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | -------------------------- |
|
| :----- | :-------------- | ------------------ |
|
||||||
| `GET` | `/session/list` | `application/json` |
|
| `GET` | `/session/list` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -295,11 +291,11 @@ The table below shows this endpoint's support for
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
||||||
the datacenter of the agent being queried. This is specified as part of the
|
the datacenter of the agent being queried. This is specified as part of the
|
||||||
URL as a query parameter. Using this across datacenters is not recommended.
|
URL as a query parameter. Using this across datacenters is not recommended.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
If not provided, the namespace will be inferred from the request's ACL token,
|
If not provided, the namespace will be inferred from the request's ACL token,
|
||||||
or will default to the `default` namespace. This is specified as part of the URL as a query parameter.
|
or will default to the `default` namespace. This is specified as part of the URL as a query parameter.
|
||||||
The namespace may be specified as '*' and then results will be returned for all namespaces.
|
The namespace may be specified as '\*' and then results will be returned for all namespaces.
|
||||||
Added in Consul 1.7.0.
|
Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
@ -316,11 +312,9 @@ $ curl \
|
||||||
{
|
{
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||||
"Name": "test-session",
|
"Name": "test-session",
|
||||||
"Node": "raja-laptop-02",
|
"Node": "raja-laptop-02",
|
||||||
"Checks": [
|
"Checks": ["serfHealth"],
|
||||||
"serfHealth"
|
"LockDelay": 1.5e10,
|
||||||
],
|
|
||||||
"LockDelay": 1.5e+10,
|
|
||||||
"Behavior": "release",
|
"Behavior": "release",
|
||||||
"TTL": "30s",
|
"TTL": "30s",
|
||||||
"CreateIndex": 1086449,
|
"CreateIndex": 1086449,
|
||||||
|
|
@ -334,9 +328,9 @@ $ curl \
|
||||||
This endpoint renews the given session. This is used with sessions that have a
|
This endpoint renews the given session. This is used with sessions that have a
|
||||||
TTL, and it extends the expiration by the TTL.
|
TTL, and it extends the expiration by the TTL.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | -------------------------- |
|
| :----- | :--------------------- | ------------------ |
|
||||||
| `PUT` | `/session/renew/:uuid` | `application/json` |
|
| `PUT` | `/session/renew/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -356,7 +350,7 @@ The table below shows this endpoint's support for
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
||||||
the datacenter of the agent being queried. This is specified as part of the
|
the datacenter of the agent being queried. This is specified as part of the
|
||||||
URL as a query parameter. Using this across datacenters is not recommended.
|
URL as a query parameter. Using this across datacenters is not recommended.
|
||||||
|
|
||||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||||
If not provided, the namespace will be inferred from the request's ACL token,
|
If not provided, the namespace will be inferred from the request's ACL token,
|
||||||
or will default to the `default` namespace. This is specified as part of the
|
or will default to the `default` namespace. This is specified as part of the
|
||||||
|
|
@ -377,11 +371,9 @@ $ curl \
|
||||||
{
|
{
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||||
"Name": "test-session",
|
"Name": "test-session",
|
||||||
"Node": "raja-laptop-02",
|
"Node": "raja-laptop-02",
|
||||||
"Checks": [
|
"Checks": ["serfHealth"],
|
||||||
"serfHealth"
|
"LockDelay": 1.5e10,
|
||||||
],
|
|
||||||
"LockDelay": 1.5e+10,
|
|
||||||
"Behavior": "release",
|
"Behavior": "release",
|
||||||
"TTL": "15s",
|
"TTL": "15s",
|
||||||
"CreateIndex": 1086449,
|
"CreateIndex": 1086449,
|
||||||
|
|
@ -26,9 +26,9 @@ the archive is internal to Consul and not intended to be used other than for
|
||||||
restore operations. The archives are not designed to be modified before a
|
restore operations. The archives are not designed to be modified before a
|
||||||
restore.
|
restore.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | -------------------------- |
|
| :----- | :---------- | ------------------------ |
|
||||||
| `GET` | `/snapshot` | `200 application/x-gzip` |
|
| `GET` | `/snapshot` | `200 application/x-gzip` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -81,9 +81,9 @@ cluster of Consul servers.
|
||||||
The body of the request should be a snapshot archive returned from a previous
|
The body of the request should be a snapshot archive returned from a previous
|
||||||
call to the `GET` method.
|
call to the `GET` method.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | ----------------------------- |
|
| :----- | :---------- | ----------------------------- |
|
||||||
| `PUT` | `/snapshot` | `200 text/plain (empty body)` |
|
| `PUT` | `/snapshot` | `200 text/plain (empty body)` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -94,6 +94,7 @@ The table below shows this endpoint's support for
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
| ---------------- | ----------------- | ------------- | ------------ |
|
||||||
| `NO` | `none` | `none` | `management` |
|
| `NO` | `none` | `none` | `management` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default
|
||||||
|
|
@ -19,9 +19,9 @@ clients.
|
||||||
This endpoint returns the Raft leader for the datacenter in which the agent is
|
This endpoint returns the Raft leader for the datacenter in which the agent is
|
||||||
running.
|
running.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | ---------------------- |
|
| :----- | :--------------- | ------------------ |
|
||||||
| `GET` | `/status/leader` | `application/json` |
|
| `GET` | `/status/leader` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -57,9 +57,9 @@ This endpoint retrieves the Raft peers for the datacenter in which the the agent
|
||||||
is running. This list of peers is strongly consistent and can be useful in
|
is running. This list of peers is strongly consistent and can be useful in
|
||||||
determining when a given server has successfully joined the cluster.
|
determining when a given server has successfully joined the cluster.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| :----- | :--------------------------- | ---------------------- |
|
| :----- | :-------------- | ------------------ |
|
||||||
| `GET` | `/status/peers` | `application/json` |
|
| `GET` | `/status/peers` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -86,9 +86,5 @@ $ curl http://127.0.0.1:8500/v1/status/peers
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
["10.1.10.12:8300", "10.1.10.11:8300", "10.1.10.10:8300"]
|
||||||
"10.1.10.12:8300",
|
|
||||||
"10.1.10.11:8300",
|
|
||||||
"10.1.10.10:8300"
|
|
||||||
]
|
|
||||||
```
|
```
|
||||||
|
|
@ -9,7 +9,7 @@ description: |-
|
||||||
# Transactions HTTP API
|
# Transactions HTTP API
|
||||||
|
|
||||||
The `/txn` endpoint manages multiple operations in Consul, including catalog
|
The `/txn` endpoint manages multiple operations in Consul, including catalog
|
||||||
updates and fetches of multiple KV entries inside a single, atomic
|
updates and fetches of multiple KV entries inside a single, atomic
|
||||||
transaction.
|
transaction.
|
||||||
|
|
||||||
## Create Transaction
|
## Create Transaction
|
||||||
|
|
@ -30,9 +30,9 @@ won't be present if the transaction contains any write operations, and any
|
||||||
consistency query parameters will be ignored, since writes are always managed by
|
consistency query parameters will be ignored, since writes are always managed by
|
||||||
the leader via the Raft consensus protocol.
|
the leader via the Raft consensus protocol.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | ---------------------------- | -------------------------- |
|
| ------ | ------ | ------------------ |
|
||||||
| `PUT` | `/txn` | `application/json` |
|
| `PUT` | `/txn` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking.html),
|
[blocking queries](/api/features/blocking.html),
|
||||||
|
|
@ -40,9 +40,9 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching.html), and
|
[agent caching](/api/features/caching.html), and
|
||||||
[required ACLs](/api/index.html#authentication).
|
[required ACLs](/api/index.html#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| 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>
|
| `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
|
<sup>1</sup> For read-only transactions
|
||||||
<br>
|
<br>
|
||||||
|
|
@ -73,36 +73,37 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `Session` `(string: "")` - Specifies a session. See the table below for more
|
- `Session` `(string: "")` - Specifies a session. See the table below for more
|
||||||
information.
|
information.
|
||||||
|
|
||||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||||
create the KV data If not provided, the namespace will be inherited from the
|
create the KV data If not provided, the namespace will be inherited from the
|
||||||
request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
- `Node` operations have the following fields:
|
- `Node` operations have the following fields:
|
||||||
|
|
||||||
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
|
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
|
||||||
|
|
||||||
- `Node` `(Node: <required>)` - Specifies the node information to use
|
- `Node` `(Node: <required>)` - Specifies the node information to use
|
||||||
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those.
|
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those.
|
||||||
|
|
||||||
- `Service` operations have the following fields:
|
- `Service` operations have the following fields:
|
||||||
|
|
||||||
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
|
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
|
||||||
|
|
||||||
- `Node` `(string: <required>)` = Specifies the name of the node to use for
|
- `Node` `(string: <required>)` = Specifies the name of the node to use for
|
||||||
this service operation.
|
this service operation.
|
||||||
|
|
||||||
- `Service` `(Service: <required>)` - Specifies the service instance information to use
|
- `Service` `(Service: <required>)` - Specifies the service instance information to use
|
||||||
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object.
|
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object.
|
||||||
|
|
||||||
- `Check` operations have the following fields:
|
- `Check` operations have the following fields:
|
||||||
|
|
||||||
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
|
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
|
||||||
|
|
||||||
- `Check` `(Service: <required>)` - Specifies the check to use
|
- `Check` `(Service: <required>)` - Specifies the check to use
|
||||||
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object.
|
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object.
|
||||||
|
|
||||||
Please see the table below for available verbs.
|
Please see the table below for available verbs.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
The body of the request should be a list of operations to perform inside the
|
The body of the request should be a list of operations to perform inside the
|
||||||
|
|
@ -241,7 +242,7 @@ look like this:
|
||||||
- `Results` has entries for some operations if the transaction was successful.
|
- `Results` has entries for some operations if the transaction was successful.
|
||||||
To save space, the `Value` for KV results will be `null` for any `Verb` other than "get" or
|
To save space, the `Value` for KV results will be `null` for any `Verb` other than "get" or
|
||||||
"get-tree". Like the `/v1/kv/<key>` endpoint, `Value` will be Base64-encoded
|
"get-tree". Like the `/v1/kv/<key>` endpoint, `Value` will be Base64-encoded
|
||||||
if it is present. Also, no result entries will be added for verbs that delete
|
if it is present. Also, no result entries will be added for verbs that delete
|
||||||
keys.
|
keys.
|
||||||
|
|
||||||
- `Errors` has entries describing which operations failed if the transaction was
|
- `Errors` has entries describing which operations failed if the transaction was
|
||||||
|
|
@ -256,56 +257,56 @@ look like this:
|
||||||
The following tables summarize the available verbs and the fields that apply to
|
The following tables summarize the available verbs and the fields that apply to
|
||||||
those operations ("X" means a field is required and "O" means it is optional):
|
those operations ("X" means a field is required and "O" means it is optional):
|
||||||
|
|
||||||
| Verb | Operation | Key | Value | Flags | Index | Session |
|
| Verb | Operation | Key | Value | Flags | Index | Session |
|
||||||
| ------------------ | -------------------------------------------- | :--: | :---: | :---: | :---: | :-----: |
|
| ------------------ | --------------------------------------- | :-: | :---: | :---: | :---: | :-----: |
|
||||||
| `set` | Sets the `Key` to the given `Value` | `x` | `x` | `o` | | |
|
| `set` | Sets the `Key` to the given `Value` | `x` | `x` | `o` | | |
|
||||||
| `cas` | Sets, but with CAS semantics | `x` | `x` | `o` | `x` | |
|
| `cas` | Sets, but with CAS semantics | `x` | `x` | `o` | `x` | |
|
||||||
| `lock` | Lock with the given `Session` | `x` | `x` | `o` | | `x` |
|
| `lock` | Lock with the given `Session` | `x` | `x` | `o` | | `x` |
|
||||||
| `unlock` | Unlock with the given `Session` | `x` | `x` | `o` | | `x` |
|
| `unlock` | Unlock with the given `Session` | `x` | `x` | `o` | | `x` |
|
||||||
| `get` | Get the key, fails if it does not exist | `x` | | | | |
|
| `get` | Get the key, fails if it does not exist | `x` | | | | |
|
||||||
| `get-tree` | Gets all keys with the prefix | `x` | | | | |
|
| `get-tree` | Gets all keys with the prefix | `x` | | | | |
|
||||||
| `check-index` | Fail if modify index != index | `x` | | | `x` | |
|
| `check-index` | Fail if modify index != index | `x` | | | `x` | |
|
||||||
| `check-session` | Fail if not locked by session | `x` | | | | `x` |
|
| `check-session` | Fail if not locked by session | `x` | | | | `x` |
|
||||||
| `check-not-exists` | Fail if key exists | `x` | | | | |
|
| `check-not-exists` | Fail if key exists | `x` | | | | |
|
||||||
| `delete` | Delete the key | `x` | | | | |
|
| `delete` | Delete the key | `x` | | | | |
|
||||||
| `delete-tree` | Delete all keys with a prefix | `x` | | | | |
|
| `delete-tree` | Delete all keys with a prefix | `x` | | | | |
|
||||||
| `delete-cas` | Delete, but with CAS semantics | `x` | | | `x` | |
|
| `delete-cas` | Delete, but with CAS semantics | `x` | | | `x` | |
|
||||||
|
|
||||||
#### Node Operations
|
#### Node Operations
|
||||||
|
|
||||||
Node operations act on an individual node and require either a Node ID or name, giving precedence
|
Node operations act on an individual node and require either a Node ID or name, giving precedence
|
||||||
to the ID if both are set. Delete operations will not return a result on success.
|
to the ID if both are set. Delete operations will not return a result on success.
|
||||||
|
|
||||||
| Verb | Operation |
|
| Verb | Operation |
|
||||||
| ------------------ | -------------------------------------------- |
|
| ------------ | -------------------------------------------------------- |
|
||||||
| `set` | Sets the node to the given state |
|
| `set` | Sets the node to the given state |
|
||||||
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
||||||
| `get` | Get the node, fails if it does not exist |
|
| `get` | Get the node, fails if it does not exist |
|
||||||
| `delete` | Delete the node |
|
| `delete` | Delete the node |
|
||||||
| `delete-cas` | Delete, but with CAS semantics |
|
| `delete-cas` | Delete, but with CAS semantics |
|
||||||
|
|
||||||
#### Service Operations
|
#### Service Operations
|
||||||
|
|
||||||
Service operations act on an individual service instance on the given node name. Both a node name
|
Service operations act on an individual service instance on the given node name. Both a node name
|
||||||
and valid service name are required. Delete operations will not return a result on success.
|
and valid service name are required. Delete operations will not return a result on success.
|
||||||
|
|
||||||
| Verb | Operation |
|
| Verb | Operation |
|
||||||
| ------------------ | -------------------------------------------- |
|
| ------------ | -------------------------------------------------------- |
|
||||||
| `set` | Sets the service to the given state |
|
| `set` | Sets the service to the given state |
|
||||||
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
||||||
| `get` | Get the service, fails if it does not exist |
|
| `get` | Get the service, fails if it does not exist |
|
||||||
| `delete` | Delete the service |
|
| `delete` | Delete the service |
|
||||||
| `delete-cas` | Delete, but with CAS semantics |
|
| `delete-cas` | Delete, but with CAS semantics |
|
||||||
|
|
||||||
#### Check Operations
|
#### Check Operations
|
||||||
|
|
||||||
Check operations act on an individual health check instance on the given node name. Both a node name
|
Check operations act on an individual health check instance on the given node name. Both a node name
|
||||||
and valid check ID are required. Delete operations will not return a result on success.
|
and valid check ID are required. Delete operations will not return a result on success.
|
||||||
|
|
||||||
| Verb | Operation |
|
| Verb | Operation |
|
||||||
| ------------------ | -------------------------------------------- |
|
| ------------ | -------------------------------------------------------- |
|
||||||
| `set` | Sets the health check to the given state |
|
| `set` | Sets the health check to the given state |
|
||||||
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
||||||
| `get` | Get the check, fails if it does not exist |
|
| `get` | Get the check, fails if it does not exist |
|
||||||
| `delete` | Delete the check |
|
| `delete` | Delete the check |
|
||||||
| `delete-cas` | Delete, but with CAS semantics |
|
| `delete-cas` | Delete, but with CAS semantics |
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "ACL Auth Methods"
|
page_title: 'ACL Auth Methods'
|
||||||
sidebar_current: "docs-acl-auth-methods"
|
sidebar_current: 'docs-acl-auth-methods'
|
||||||
description: |-
|
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.
|
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.
|
-> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer.
|
||||||
|
|
||||||
# ACL Auth Methods
|
# ACL Auth Methods
|
||||||
|
|
||||||
|
|
@ -39,16 +39,15 @@ service mesh with minimal operator intervention.
|
||||||
An operator needs to configure each auth method that is to be trusted by
|
An operator needs to configure each auth method that is to be trusted by
|
||||||
using the API or command line before they can be used by applications.
|
using the API or command line before they can be used by applications.
|
||||||
|
|
||||||
* **Authentication** - One or more **auth methods** should be configured with
|
- **Authentication** - One or more **auth methods** should be configured with
|
||||||
details about how to authenticate application credentials. Successful
|
details about how to authenticate application credentials. Successful
|
||||||
validation of application credentials will return a set of trusted identity
|
validation of application credentials will return a set of trusted identity
|
||||||
attributes (such as a username). These can be managed with the `consul acl
|
attributes (such as a username). These can be managed with the `consul acl auth-method` subcommands or the corresponding [API
|
||||||
auth-method` subcommands or the corresponding [API
|
endpoints](/api/acl/auth-methods.html). The specific details of
|
||||||
endpoints](/api/acl/auth-methods.html). The specific details of
|
|
||||||
configuration are type dependent and described in their own documentation
|
configuration are type dependent and described in their own documentation
|
||||||
pages.
|
pages.
|
||||||
|
|
||||||
* **Authorization** - One or more **binding rules** must be configured to define
|
- **Authorization** - One or more **binding rules** must be configured to define
|
||||||
how to translate trusted identity attributes from each auth method into
|
how to translate trusted identity attributes from each auth method into
|
||||||
privileges assigned to the ACL token that is created. These can be managed
|
privileges assigned to the ACL token that is created. These can be managed
|
||||||
with the `consul acl binding-rule` subcommands or the corresponding [API
|
with the `consul acl binding-rule` subcommands or the corresponding [API
|
||||||
|
|
@ -56,7 +55,7 @@ using the API or command line before they can be used by applications.
|
||||||
|
|
||||||
-> **Note** - To configure auth methods in any connected secondary datacenter,
|
-> **Note** - To configure auth methods in any connected secondary datacenter,
|
||||||
[ACL token replication](/docs/agent/options.html#acl_enable_token_replication)
|
[ACL token replication](/docs/agent/options.html#acl_enable_token_replication)
|
||||||
must be enabled. Auth methods require the ability to create local tokens which
|
must be enabled. Auth methods require the ability to create local tokens which
|
||||||
is restricted to the primary datacenter and any secondary datacenters with ACL
|
is restricted to the primary datacenter and any secondary datacenters with ACL
|
||||||
token replication enabled.
|
token replication enabled.
|
||||||
|
|
||||||
|
|
@ -68,7 +67,7 @@ identities](/docs/acl/acl-system.html#acl-service-identities) to newly created
|
||||||
tokens without operator intervention.
|
tokens without operator intervention.
|
||||||
|
|
||||||
Successful authentication with an auth method returns a set of trusted
|
Successful authentication with an auth method returns a set of trusted
|
||||||
identity attributes corresponding to the authenticated identity. Those
|
identity attributes corresponding to the authenticated identity. Those
|
||||||
attributes are matched against all configured binding rules for that auth
|
attributes are matched against all configured binding rules for that auth
|
||||||
method to determine what privileges to grant the the Consul ACL token it will
|
method to determine what privileges to grant the the Consul ACL token it will
|
||||||
ultimately create.
|
ultimately create.
|
||||||
|
|
@ -78,7 +77,7 @@ Each binding rule is composed of two portions:
|
||||||
- **Selector** - A logical query that must match the trusted identity
|
- **Selector** - A logical query that must match the trusted identity
|
||||||
attributes for the binding rule to be applicable to a given login attempt.
|
attributes for the binding rule to be applicable to a given login attempt.
|
||||||
The syntax uses github.com/hashicorp/go-bexpr which is shared with the [API
|
The syntax uses github.com/hashicorp/go-bexpr which is shared with the [API
|
||||||
filtering feature](/api/features/filtering.html). For example:
|
filtering feature](/api/features/filtering.html). For example:
|
||||||
`"serviceaccount.namespace==default and serviceaccount.name!=vault"`
|
`"serviceaccount.namespace==default and serviceaccount.name!=vault"`
|
||||||
|
|
||||||
- **Bind Type and Name** - A binding rule can bind a token to a
|
- **Bind Type and Name** - A binding rule can bind a token to a
|
||||||
|
|
@ -108,7 +107,7 @@ bearer token for a Consul ACL token by using the login process:
|
||||||
|
|
||||||
3. The Consul leader then uses auth method specific mechanisms to validate the
|
3. The Consul leader then uses auth method specific mechanisms to validate the
|
||||||
provided bearer token credentials.
|
provided bearer token credentials.
|
||||||
|
|
||||||
4. Successful validation returns trusted identity attributes to the Consul
|
4. Successful validation returns trusted identity attributes to the Consul
|
||||||
leader.
|
leader.
|
||||||
|
|
||||||
|
|
@ -119,7 +118,7 @@ bearer token for a Consul ACL token by using the login process:
|
||||||
6. The Consul leader uses the matching binding rules to generate a list of
|
6. The Consul leader uses the matching binding rules to generate a list of
|
||||||
roles and service identities and assigns them to a token created exclusively
|
roles and service identities and assigns them to a token created exclusively
|
||||||
in the _local_ datacenter. If none are generated the login attempt fails.
|
in the _local_ datacenter. If none are generated the login attempt fails.
|
||||||
|
|
||||||
7. The relevant `SecretID` and remaining details about the token are returned to
|
7. The relevant `SecretID` and remaining details about the token are returned to
|
||||||
the originating Consul client.
|
the originating Consul client.
|
||||||
|
|
||||||
|
|
@ -1,12 +1,11 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "ACL System (Legacy Mode)"
|
page_title: 'ACL System (Legacy Mode)'
|
||||||
sidebar_current: "docs-acl-legacy"
|
sidebar_current: 'docs-acl-legacy'
|
||||||
description: |-
|
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.
|
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)
|
-> **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)
|
||||||
|
|
||||||
# ACL System in Legacy Mode
|
# ACL System in Legacy Mode
|
||||||
|
|
@ -15,13 +14,12 @@ description: |-
|
||||||
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
|
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
|
||||||
the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system.html).
|
the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system.html).
|
||||||
|
|
||||||
|
|
||||||
The legacy documentation has two sections.
|
The legacy documentation has two sections.
|
||||||
|
|
||||||
- The [New ACL System Differences](#new-acl-system-differences) section
|
- The [New ACL System Differences](#new-acl-system-differences) section
|
||||||
details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/acl/acl-migrate-tokens.html) tokens.
|
details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/acl/acl-migrate-tokens.html) tokens.
|
||||||
- The [Legacy ACL System documentation](#legacy-acl-system) section details the
|
- The [Legacy ACL System documentation](#legacy-acl-system) section details the
|
||||||
ACL system in Consul 1.3.0 and older.
|
ACL system in Consul 1.3.0 and older.
|
||||||
|
|
||||||
# New ACL System Differences
|
# New ACL System Differences
|
||||||
|
|
||||||
|
|
@ -84,12 +82,11 @@ The new ACL system includes new API endpoints to manage
|
||||||
the [ACL System](/api/acl/acl.html), [Tokens](/api/acl/tokens.html)
|
the [ACL System](/api/acl/acl.html), [Tokens](/api/acl/tokens.html)
|
||||||
and [Policies](/api/acl/policies.html).
|
and [Policies](/api/acl/policies.html).
|
||||||
|
|
||||||
|
# Legacy ACL System
|
||||||
# Legacy ACL System
|
|
||||||
|
|
||||||
~> **Warning**: In this document we use the deprecated
|
~> **Warning**: In this document we use the deprecated
|
||||||
configuration parameter `acl_datacenter`. In Consul 1.4 and newer the
|
configuration parameter `acl_datacenter`. In Consul 1.4 and newer the
|
||||||
parameter has been updated to [`primary_datacenter`](https://www.consul.io/docs/agent/options.html#primary_datacenter).
|
parameter has been updated to [`primary_datacenter`](https://www.consul.io/docs/agent/options.html#primary_datacenter).
|
||||||
|
|
||||||
Consul provides an optional Access Control List (ACL) system which can be used to control
|
Consul provides an optional Access Control List (ACL) system which can be used to control
|
||||||
access to data and APIs. The ACL is
|
access to data and APIs. The ACL is
|
||||||
|
|
@ -137,17 +134,17 @@ are used to prohibit actions. By default, Consul will allow all actions.
|
||||||
The following table summarizes the ACL policies that are available for constructing
|
The following table summarizes the ACL policies that are available for constructing
|
||||||
rules:
|
rules:
|
||||||
|
|
||||||
| Policy | Scope |
|
| Policy | Scope |
|
||||||
| ------------------------ | ----- |
|
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||||
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration |
|
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration |
|
||||||
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
|
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
|
||||||
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) |
|
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) |
|
||||||
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) |
|
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) |
|
||||||
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) |
|
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) |
|
||||||
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) |
|
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) |
|
||||||
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html)
|
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html) |
|
||||||
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) |
|
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) |
|
||||||
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
||||||
|
|
||||||
Since Consul snapshots actually contain ACL tokens, the
|
Since Consul snapshots actually contain ACL tokens, the
|
||||||
[Snapshot API](/api/snapshot.html) requires a management token for snapshot operations
|
[Snapshot API](/api/snapshot.html) requires a management token for snapshot operations
|
||||||
|
|
@ -156,12 +153,12 @@ and does not use a special policy.
|
||||||
The following resources are not covered by ACL policies:
|
The following resources are not covered by ACL policies:
|
||||||
|
|
||||||
1. The [Status API](/api/status.html) is used by servers when bootstrapping and exposes
|
1. The [Status API](/api/status.html) is used by servers when bootstrapping and exposes
|
||||||
basic IP and port information about the servers, and does not allow modification
|
basic IP and port information about the servers, and does not allow modification
|
||||||
of any state.
|
of any state.
|
||||||
|
|
||||||
2. The datacenter listing operation of the
|
2. The datacenter listing operation of the
|
||||||
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known
|
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known
|
||||||
Consul datacenters, and does not allow modification of any state.
|
Consul datacenters, and does not allow modification of any state.
|
||||||
|
|
||||||
Constructing rules from these policies is covered in detail in the
|
Constructing rules from these policies is covered in detail in the
|
||||||
[Rule Specification](#rule-specification) section below.
|
[Rule Specification](#rule-specification) section below.
|
||||||
|
|
@ -196,12 +193,12 @@ tokens to be replicated for use during an outage.
|
||||||
ACLs are configured using several different configuration options. These are marked
|
ACLs are configured using several different configuration options. These are marked
|
||||||
as to whether they are set on servers, clients, or both.
|
as to whether they are set on servers, clients, or both.
|
||||||
|
|
||||||
| Configuration Option | Servers | Clients | Purpose |
|
| Configuration Option | Servers | Clients | Purpose |
|
||||||
| -------------------- | ------- | ------- | ------- |
|
| -------------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- |
|
||||||
| [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs |
|
| [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs |
|
||||||
| [`acl_default_policy`](/docs/agent/options.html#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
|
| [`acl_default_policy`](/docs/agent/options.html#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
|
||||||
| [`acl_down_policy`](/docs/agent/options.html#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline |
|
| [`acl_down_policy`](/docs/agent/options.html#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline |
|
||||||
| [`acl_ttl`](/docs/agent/options.html#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs |
|
| [`acl_ttl`](/docs/agent/options.html#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs |
|
||||||
|
|
||||||
There are some additional configuration items related to [ACL replication](#replication) and
|
There are some additional configuration items related to [ACL replication](#replication) and
|
||||||
[Version 8 ACL support](#version_8_acls). These are discussed in those respective sections
|
[Version 8 ACL support](#version_8_acls). These are discussed in those respective sections
|
||||||
|
|
@ -210,12 +207,12 @@ below.
|
||||||
A number of special tokens can also be configured which allow for bootstrapping the ACL
|
A number of special tokens can also be configured which allow for bootstrapping the ACL
|
||||||
system, or accessing Consul in special situations:
|
system, or accessing Consul in special situations:
|
||||||
|
|
||||||
| Special Token | Servers | Clients | Purpose |
|
| Special Token | Servers | Clients | Purpose |
|
||||||
| ------------- | ------- | ------- | ------- |
|
| ---------------------------------------------------------------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
| [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details |
|
| [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details |
|
||||||
| [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details |
|
| [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details |
|
||||||
| [`acl_master_token`](/docs/agent/options.html#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details |
|
| [`acl_master_token`](/docs/agent/options.html#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details |
|
||||||
| [`acl_token`](/docs/agent/options.html#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
|
| [`acl_token`](/docs/agent/options.html#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
|
||||||
|
|
||||||
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
|
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
|
||||||
[/v1/agent/token API](/api/agent.html#update-acl-tokens).
|
[/v1/agent/token API](/api/agent.html#update-acl-tokens).
|
||||||
|
|
@ -607,9 +604,9 @@ define different namespaces within Consul's resource areas like the catalog and
|
||||||
store, in order to delegate responsibility for these namespaces. Policies can have several
|
store, in order to delegate responsibility for these namespaces. Policies can have several
|
||||||
dispositions:
|
dispositions:
|
||||||
|
|
||||||
* `read`: allow the resource to be read but not modified
|
- `read`: allow the resource to be read but not modified
|
||||||
* `write`: allow the resource to be read and modified
|
- `write`: allow the resource to be read and modified
|
||||||
* `deny`: do not allow the resource to be read or modified
|
- `deny`: do not allow the resource to be read or modified
|
||||||
|
|
||||||
With prefix-based rules, the most specific prefix match determines the action. This
|
With 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
|
allows for flexible rules like an empty prefix to allow read-only access to all
|
||||||
|
|
@ -750,7 +747,7 @@ Event rules are keyed by the event name prefix they apply to, using the longest
|
||||||
In the example above, the rules allow read-only access to any event, and firing of any event that
|
In the example above, the rules allow read-only access to any event, and firing of any event that
|
||||||
starts with "deploy".
|
starts with "deploy".
|
||||||
|
|
||||||
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
|
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
|
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`.
|
[`disable_remote_exec`](/docs/agent/options.html#disable_remote_exec) to `false`.
|
||||||
|
|
@ -935,7 +932,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
|
ways: open, protected by unguessable IDs or closed, managed by ACL policies. These variations are covered
|
||||||
here, with examples:
|
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
|
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
|
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
|
these IDs are generated using the same random ID scheme as ACL Tokens, it is
|
||||||
|
|
@ -945,7 +942,7 @@ here, with examples:
|
||||||
startup script, tied to a session, and written to a configuration file for a
|
startup script, tied to a session, and written to a configuration file for a
|
||||||
process to use via DNS.
|
process to use via DNS.
|
||||||
|
|
||||||
* Static queries with a `Name` defined are controlled by the `query` ACL policy.
|
- Static queries with a `Name` defined are controlled by the `query` ACL policy.
|
||||||
Clients are required to have an ACL token with a prefix sufficient to cover
|
Clients are required to have an ACL token with a prefix sufficient to cover
|
||||||
the name they are trying to manage, with a longest prefix match providing a
|
the name they are trying to manage, with a longest prefix match providing a
|
||||||
way to define more specific policies. Clients can list or read queries for
|
way to define more specific policies. Clients can list or read queries for
|
||||||
|
|
@ -955,7 +952,7 @@ here, with examples:
|
||||||
that is used and known by many clients to provide geo-failover behavior for
|
that is used and known by many clients to provide geo-failover behavior for
|
||||||
a database.
|
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
|
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
|
template with an empty `Name` requires an ACL token that can write to any query
|
||||||
prefix.
|
prefix.
|
||||||
|
|
@ -965,14 +962,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
|
other service lookups. There are several ways the ACL token is selected for this
|
||||||
check:
|
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
|
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.
|
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.
|
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.
|
anonymous token will be used to perform the service lookup.
|
||||||
|
|
||||||
In the common case, the ACL Token of the invoker is used
|
In the common case, the ACL Token of the invoker is used
|
||||||
|
|
@ -1085,7 +1082,6 @@ In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured wit
|
||||||
[`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks)
|
[`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks)
|
||||||
set to `true` in order to enable script checks.
|
set to `true` in order to enable script checks.
|
||||||
|
|
||||||
|
|
||||||
#### Session Rules
|
#### Session Rules
|
||||||
|
|
||||||
The `session` policy controls access to [Session API](/api/session.html) operations.
|
The `session` policy controls access to [Session API](/api/session.html) operations.
|
||||||
|
|
@ -1112,6 +1108,7 @@ name that starts with "admin".
|
||||||
## Advanced Topics
|
## Advanced Topics
|
||||||
|
|
||||||
<a name="replication"></a>
|
<a name="replication"></a>
|
||||||
|
|
||||||
#### Outages and ACL Replication
|
#### Outages and ACL Replication
|
||||||
|
|
||||||
The Consul ACL system is designed with flexible rules to accommodate for an outage
|
The Consul ACL system is designed with flexible rules to accommodate for an outage
|
||||||
|
|
@ -1162,19 +1159,20 @@ ACL replication can also be used to migrate ACLs from one datacenter to another
|
||||||
using a process like this:
|
using a process like this:
|
||||||
|
|
||||||
1. Enable ACL replication in all datacenters to allow continuation of service
|
1. Enable ACL replication in all datacenters to allow continuation of service
|
||||||
during the migration, and to populate the target datacenter. Verify replication
|
during the migration, and to populate the target datacenter. Verify replication
|
||||||
is healthy and caught up to the current ACL index in the target datacenter
|
is healthy and caught up to the current ACL index in the target datacenter
|
||||||
using the [ACL replication status](/api/acl/acl.html#acl_replication_status)
|
using the [ACL replication status](/api/acl/acl.html#acl_replication_status)
|
||||||
endpoint.
|
endpoint.
|
||||||
2. Turn down the old authoritative datacenter servers.
|
2. Turn down the old authoritative datacenter servers.
|
||||||
3. Rolling restart the agents in the target datacenter and change the
|
3. Rolling restart the agents in the target datacenter and change the
|
||||||
`acl_datacenter` servers to itself. This will automatically turn off
|
`acl_datacenter` servers to itself. This will automatically turn off
|
||||||
replication and will enable the datacenter to start acting as the authoritative
|
replication and will enable the datacenter to start acting as the authoritative
|
||||||
datacenter, using its replicated ACLs from before.
|
datacenter, using its replicated ACLs from before.
|
||||||
3. Rolling restart the agents in other datacenters and change their `acl_datacenter`
|
4. Rolling restart the agents in other datacenters and change their `acl_datacenter`
|
||||||
configuration to the target datacenter.
|
configuration to the target datacenter.
|
||||||
|
|
||||||
<a name="version_8_acls"></a>
|
<a name="version_8_acls"></a>
|
||||||
|
|
||||||
#### Complete ACL Coverage in Consul 0.8
|
#### Complete ACL Coverage in Consul 0.8
|
||||||
|
|
||||||
Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consul
|
Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consul
|
||||||
|
|
@ -1186,30 +1184,30 @@ option to `false` on Consul clients and servers.
|
||||||
|
|
||||||
Here's a summary of the new features:
|
Here's a summary of the new features:
|
||||||
|
|
||||||
* Agents now check [`node`](#node-rules) and [`service`](#service-rules) ACL policies
|
- Agents now check [`node`](#node-rules) and [`service`](#service-rules) ACL policies
|
||||||
for catalog-related operations in `/v1/agent` endpoints, such as service and check
|
for catalog-related operations in `/v1/agent` endpoints, such as service and check
|
||||||
registration and health check updates.
|
registration and health check updates.
|
||||||
* Agents enforce a new [`agent`](#agent-rules) ACL policy for utility operations in
|
- Agents enforce a new [`agent`](#agent-rules) ACL policy for utility operations in
|
||||||
`/v1/agent` endpoints, such as joins and leaves.
|
`/v1/agent` endpoints, such as joins and leaves.
|
||||||
* A new [`node`](#node-rules) ACL policy is enforced throughout Consul, providing a
|
- A new [`node`](#node-rules) ACL policy is enforced throughout Consul, providing a
|
||||||
mechanism to restrict registration and discovery of nodes by name. This also applies
|
mechanism to restrict registration and discovery of nodes by name. This also applies
|
||||||
to service discovery, so provides an additional dimension for controlling access to
|
to service discovery, so provides an additional dimension for controlling access to
|
||||||
services.
|
services.
|
||||||
* A new [`session`](#session-rules) ACL policy controls the ability to create session
|
- A new [`session`](#session-rules) ACL policy controls the ability to create session
|
||||||
objects by node name.
|
objects by node name.
|
||||||
* Anonymous prepared queries (non-templates without a `Name`) now require a valid
|
- Anonymous prepared queries (non-templates without a `Name`) now require a valid
|
||||||
session, which ties their creation to the new [`session`](#session-rules) ACL policy.
|
session, which ties their creation to the new [`session`](#session-rules) ACL policy.
|
||||||
* The existing [`event`](#event-rules) ACL policy has been applied to the
|
- The existing [`event`](#event-rules) ACL policy has been applied to the
|
||||||
`/v1/event/list` endpoint.
|
`/v1/event/list` endpoint.
|
||||||
|
|
||||||
Two new configuration options are used once version 8 ACLs are enabled:
|
Two new configuration options are used once version 8 ACLs are enabled:
|
||||||
|
|
||||||
* [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) is used as
|
- [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) is used as
|
||||||
a special access token that has `agent` ACL policy `write` privileges on each agent where
|
a special access token that has `agent` ACL policy `write` privileges on each agent where
|
||||||
it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token
|
it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token
|
||||||
should only be used by operators during outages when Consul servers aren't available to
|
should only be used by operators during outages when Consul servers aren't available to
|
||||||
resolve ACL tokens. Applications should use regular ACL tokens during normal operation.
|
resolve ACL tokens. Applications should use regular ACL tokens during normal operation.
|
||||||
* [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is used internally by
|
- [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is used internally by
|
||||||
Consul agents to perform operations to the service catalog when registering themselves
|
Consul agents to perform operations to the service catalog when registering themselves
|
||||||
or sending network coordinates to the servers. This token must at least have `node` ACL
|
or sending network coordinates to the servers. This token must at least have `node` ACL
|
||||||
policy `write` access to the node name it will register as in order to register any
|
policy `write` access to the node name it will register as in order to register any
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "ACL Token Migration"
|
page_title: 'ACL Token Migration'
|
||||||
sidebar_current: "docs-acl-migrate-tokens"
|
sidebar_current: 'docs-acl-migrate-tokens'
|
||||||
description: |-
|
description: |-
|
||||||
Consul 1.4.0 introduces a new ACL system with improvements for the security and
|
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
|
management of ACL tokens and policies. This guide documents how to upgrade
|
||||||
|
|
@ -20,11 +20,11 @@ the new ACL system features. Tooling is provided to help automate this and this
|
||||||
guide describes the overall process.
|
guide describes the overall process.
|
||||||
|
|
||||||
~> **Note**: Before starting the token migration process all Consul agents, servers
|
~> **Note**: Before starting the token migration process all Consul agents, servers
|
||||||
and clients, must be running at least version 1.4.0. Additionally, you
|
and clients, must be running at least version 1.4.0. Additionally, you
|
||||||
must ensure the cluster is in a healthy state including a functioning leader. Once
|
must ensure the cluster is in a healthy state including a functioning leader. Once
|
||||||
the leader has determined that all servers in the cluster are capable of using the
|
the leader has determined that all servers in the cluster are capable of using the
|
||||||
new ACL system, the leader will transition itself. Then, the other servers will
|
new ACL system, the leader will transition itself. Then, the other servers will
|
||||||
transition themselves to the new system, followed by the client agents. You can
|
transition themselves to the new system, followed by the client agents. You can
|
||||||
use `consul info` to investigate the cluster health.
|
use `consul info` to investigate the cluster health.
|
||||||
|
|
||||||
Consul 1.4.0 retains full support for "legacy" ACL tokens so upgrades
|
Consul 1.4.0 retains full support for "legacy" ACL tokens so upgrades
|
||||||
|
|
@ -44,8 +44,8 @@ re-issuing all the secrets in use.
|
||||||
|
|
||||||
The high-level process for migrating a legacy token is as follows:
|
The high-level process for migrating a legacy token is as follows:
|
||||||
|
|
||||||
1. Create a new policy or policies that grant the required access
|
1. Create a new policy or policies that grant the required access
|
||||||
2. Update the existing token to use those policies
|
2. Update the existing token to use those policies
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
|
||||||
|
|
@ -81,14 +81,13 @@ have.
|
||||||
The simplest and most automatic strategy is to create one new policy for every
|
The simplest and most automatic strategy is to create one new policy for every
|
||||||
existing token. This is easy to automate, but may result in a lot of policies
|
existing token. This is easy to automate, but may result in a lot of policies
|
||||||
with exactly the same rules and with non-human-readable names which will make
|
with exactly the same rules and with non-human-readable names which will make
|
||||||
managing policies harder. This approach can be accomplished using the [`consul
|
managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/docs/commands/acl/policy/create.html) command with
|
||||||
acl policy create`](/docs/commands/acl/policy/create.html) command with
|
|
||||||
`-from-token` option.
|
`-from-token` option.
|
||||||
|
|
||||||
| Pros | Cons |
|
| Pros | Cons |
|
||||||
| ---- | ---- |
|
| ------------------------ | ------------------------------------------- |
|
||||||
| ✅ Simple | ❌ May leave many duplicated policies |
|
| ✅ Simple | ❌ May leave many duplicated policies |
|
||||||
| ✅ Easy to automate | ❌ Policy names not human-readable |
|
| ✅ Easy to automate | ❌ Policy names not human-readable |
|
||||||
|
|
||||||
A detailed example of using this approach is [given
|
A detailed example of using this approach is [given
|
||||||
below](#simple-policy-mapping).
|
below](#simple-policy-mapping).
|
||||||
|
|
@ -111,15 +110,14 @@ semantics of the old ACL system.
|
||||||
|
|
||||||
To assist with this approach, there is a CLI tool and corresponding API that can
|
To assist with this approach, there is a CLI tool and corresponding API that can
|
||||||
translate a legacy ACL token's rules into a new ACL policy that is exactly
|
translate a legacy ACL token's rules into a new ACL policy that is exactly
|
||||||
equivalent. See [`consul acl
|
equivalent. See [`consul acl translate-rules`](/docs/commands/acl/translate-rules.html).
|
||||||
translate-rules`](/docs/commands/acl/translate-rules.html).
|
|
||||||
|
|
||||||
| Pros | Cons |
|
| Pros | Cons |
|
||||||
| ---- | ---- |
|
| ------------------------------------------------- | ------------------------------------------------------------------ |
|
||||||
| ✅ Clearer, more manageable policies | ❌ Requires more manual effort |
|
| ✅ Clearer, more manageable policies | ❌ Requires more manual effort |
|
||||||
| ✅ Policies can be re-used by new ACL tokens | ❌ May take longer for large or complex existing policy sets |
|
| ✅ Policies can be re-used by new ACL tokens | ❌ May take longer for large or complex existing policy sets |
|
||||||
|
|
||||||
A detailed example of using this approach is [given below](#combining-policies).
|
A detailed example of using this approach is [given below](#combining-policies).
|
||||||
|
|
||||||
### Updating Existing Tokens
|
### Updating Existing Tokens
|
||||||
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "ACL System"
|
page_title: 'ACL System'
|
||||||
sidebar_current: "docs-acl-system"
|
sidebar_current: 'docs-acl-system'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -13,7 +13,7 @@ description: |-
|
||||||
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
|
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
|
||||||
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
|
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
|
||||||
are associated with policies to determine which fine grained rules can be applied. Consul's capability based
|
are associated with policies to determine which fine grained rules can be applied. Consul's capability based
|
||||||
ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/).
|
ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/).
|
||||||
|
|
||||||
To learn how to setup the ACL system on an existing Consul datacenter, use the [Bootstrapping The ACL System guide](https://learn.hashicorp.com/consul/day-0/acl-guide?utm_source=consul.io&utm_medium=docs).
|
To learn how to setup the ACL system on an existing Consul datacenter, use the [Bootstrapping The ACL System guide](https://learn.hashicorp.com/consul/day-0/acl-guide?utm_source=consul.io&utm_medium=docs).
|
||||||
|
|
||||||
|
|
@ -22,59 +22,59 @@ To learn how to setup the ACL system on an existing Consul datacenter, use the [
|
||||||
The ACL system is designed to be easy to use and fast to enforce while providing administrative insight.
|
The ACL system is designed to be easy to use and fast to enforce while providing administrative insight.
|
||||||
At the highest level, there are two major components to the ACL system:
|
At the highest level, there are two major components to the ACL system:
|
||||||
|
|
||||||
* **ACL Policies** - Policies allow the grouping of a set of rules into a logical unit that can be reused and linked with
|
- **ACL Policies** - Policies allow the grouping of a set of rules into a logical unit that can be reused and linked with
|
||||||
many tokens.
|
many tokens.
|
||||||
|
|
||||||
* **ACL Tokens** - Requests to Consul are authorized by using bearer token. Each ACL token has a public
|
- **ACL Tokens** - Requests to Consul are authorized by using bearer token. Each ACL token has a public
|
||||||
Accessor ID which is used to name a token, and a Secret ID which is used as the bearer token used to
|
Accessor ID which is used to name a token, and a Secret ID which is used as the bearer token used to
|
||||||
make requests to Consul.
|
make requests to Consul.
|
||||||
|
|
||||||
For many scenarios policies and tokens are sufficient, but more advanced setups
|
For many scenarios policies and tokens are sufficient, but more advanced setups
|
||||||
may benefit from additional components in the ACL system:
|
may benefit from additional components in the ACL system:
|
||||||
|
|
||||||
* **ACL Roles** - Roles allow for the grouping of a set of policies and service
|
- **ACL Roles** - Roles allow for the grouping of a set of policies and service
|
||||||
identities into a reusable higher-level entity that can be applied to many
|
identities into a reusable higher-level entity that can be applied to many
|
||||||
tokens. (Added in Consul 1.5.0)
|
tokens. (Added in Consul 1.5.0)
|
||||||
|
|
||||||
* **ACL Service Identities** - Service identities are a policy template for
|
- **ACL Service Identities** - Service identities are a policy template for
|
||||||
expressing a link to a policy suitable for use in [Consul
|
expressing a link to a policy suitable for use in [Consul
|
||||||
Connect](/docs/connect/index.html). At authorization time this acts like an
|
Connect](/docs/connect/index.html). At authorization time this acts like an
|
||||||
additional policy was attached, the contents of which are described further
|
additional policy was attached, the contents of which are described further
|
||||||
below. These are directly attached to tokens and roles and are not
|
below. These are directly attached to tokens and roles and are not
|
||||||
independently configured. (Added in Consul 1.5.0)
|
independently configured. (Added in Consul 1.5.0)
|
||||||
|
|
||||||
* **ACL Auth Methods and Binding Rules** - To learn more about these topics,
|
- **ACL Auth Methods and Binding Rules** - To learn more about these topics,
|
||||||
see the [dedicated auth methods documentation page](/docs/acl/acl-auth-methods.html).
|
see the [dedicated auth methods documentation page](/docs/acl/acl-auth-methods.html).
|
||||||
|
|
||||||
ACL tokens, policies, roles, auth methods, and binding rules are managed by
|
ACL tokens, policies, roles, auth methods, and binding rules are managed by
|
||||||
Consul operators via Consul's [ACL API](/api/acl/acl.html),
|
Consul operators via Consul's [ACL API](/api/acl/acl.html),
|
||||||
[ACL CLI](/docs/commands/acl.html), or systems like
|
[ACL CLI](/docs/commands/acl.html), or systems like
|
||||||
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul/index.html).
|
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul/index.html).
|
||||||
|
|
||||||
If the ACL system becomes inoperable, you can follow the
|
If the ACL system becomes inoperable, you can follow the
|
||||||
[reset procedure](https://learn.hashicorp.com/consul/security-networking/acl-troubleshooting?utm_source=consul.io&utm_medium=docs) at any time.
|
[reset procedure](https://learn.hashicorp.com/consul/security-networking/acl-troubleshooting?utm_source=consul.io&utm_medium=docs) at any time.
|
||||||
|
|
||||||
### ACL Policies
|
### ACL Policies
|
||||||
|
|
||||||
An ACL policy is a named set of rules and is composed of the following elements:
|
An ACL policy is a named set of rules and is composed of the following elements:
|
||||||
|
|
||||||
* **ID** - The policy's auto-generated public identifier.
|
- **ID** - The policy's auto-generated public identifier.
|
||||||
* **Name** - A unique meaningful name for the policy.
|
- **Name** - A unique meaningful name for the policy.
|
||||||
* **Description** - A human readable description of the policy. (Optional)
|
- **Description** - A human readable description of the policy. (Optional)
|
||||||
* **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules.html#rule-specification) documentation for more details.
|
- **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules.html#rule-specification) documentation for more details.
|
||||||
* **Datacenters** - A list of datacenters the policy is valid within.
|
- **Datacenters** - A list of datacenters the policy is valid within.
|
||||||
* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
- **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
||||||
|
|
||||||
-> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules.html#namespace-rules-enterprise) to being able to grant a subset of the overall privileges and only affecting that single namespace.
|
-> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules.html#namespace-rules-enterprise) to being able to grant a subset of the overall privileges and only affecting that single namespace.
|
||||||
|
|
||||||
#### Builtin Policies
|
#### Builtin Policies
|
||||||
|
|
||||||
* **Global Management** - Grants unrestricted privileges to any token that uses it. When created it will be named `global-management`
|
- **Global Management** - Grants unrestricted privileges to any token that uses it. When created it will be named `global-management`
|
||||||
and will be assigned the reserved ID of `00000000-0000-0000-0000-000000000001`. This policy can be renamed but modification
|
and will be assigned the reserved ID of `00000000-0000-0000-0000-000000000001`. This policy can be renamed but modification
|
||||||
of anything else including the rule set and datacenter scoping will be prevented by Consul.
|
of anything else including the rule set and datacenter scoping will be prevented by Consul.
|
||||||
|
|
||||||
* **Namespace Management** - **Enterprise Only** - Every namespace created will have a policy injected with the name `namespace-management`. This policy gets injected with a randomized UUID and may be managed like any other user-defined policy
|
- **Namespace Management** - **Enterprise Only** - Every namespace created will have a policy injected with the name `namespace-management`. This policy gets injected with a randomized UUID and may be managed like any other user-defined policy
|
||||||
within the Namespace. (Added in Consul Enterprise 1.7.0)
|
within the Namespace. (Added in Consul Enterprise 1.7.0)
|
||||||
|
|
||||||
### ACL Service Identities
|
### ACL Service Identities
|
||||||
|
|
||||||
|
|
@ -84,8 +84,8 @@ An ACL service identity is an [ACL policy](/docs/acl/acl-system.html#acl-policie
|
||||||
suitable for use in [Consul Connect](/docs/connect/index.html). They are usable
|
suitable for use in [Consul Connect](/docs/connect/index.html). They are usable
|
||||||
on both tokens and roles and are composed of the following elements:
|
on both tokens and roles and are composed of the following elements:
|
||||||
|
|
||||||
* **Service Name** - The name of the service.
|
- **Service Name** - The name of the service.
|
||||||
* **Datacenters** - A list of datacenters the effective policy is valid within. (Optional)
|
- **Datacenters** - A list of datacenters the effective policy is valid within. (Optional)
|
||||||
|
|
||||||
Services participating in the service mesh will need privileges to both _be
|
Services participating in the service mesh will need privileges to both _be
|
||||||
discovered_ and to _discover other healthy service instances_. Suitable
|
discovered_ and to _discover other healthy service instances_. Suitable
|
||||||
|
|
@ -117,7 +117,7 @@ node_prefix "" {
|
||||||
The [API documentation for roles](/api/acl/roles.html#sample-payload) has some
|
The [API documentation for roles](/api/acl/roles.html#sample-payload) has some
|
||||||
examples of using a service identity.
|
examples of using a service identity.
|
||||||
|
|
||||||
-> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single namespace that
|
-> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single namespace that
|
||||||
the corresponding ACL Token or Role resides within.
|
the corresponding ACL Token or Role resides within.
|
||||||
|
|
||||||
### ACL Roles
|
### ACL Roles
|
||||||
|
|
@ -127,12 +127,12 @@ the corresponding ACL Token or Role resides within.
|
||||||
An ACL role is a named set of policies and service identities and is composed
|
An ACL role is a named set of policies and service identities and is composed
|
||||||
of the following elements:
|
of the following elements:
|
||||||
|
|
||||||
* **ID** - The role's auto-generated public identifier.
|
- **ID** - The role's auto-generated public identifier.
|
||||||
* **Name** - A unique meaningful name for the role.
|
- **Name** - A unique meaningful name for the role.
|
||||||
* **Description** - A human readable description of the role. (Optional)
|
- **Description** - A human readable description of the role. (Optional)
|
||||||
* **Policy Set** - The list of policies that are applicable for the role.
|
- **Policy Set** - The list of policies that are applicable for the role.
|
||||||
* **Service Identity Set** - The list of service identities that are applicable for the role.
|
- **Service Identity Set** - The list of service identities that are applicable for the role.
|
||||||
* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
- **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
||||||
|
|
||||||
-> **Consul Enterprise Namespacing** - Roles may only link to policies defined in the same namespace as the role itself.
|
-> **Consul Enterprise Namespacing** - Roles may only link to policies defined in the same namespace as the role itself.
|
||||||
|
|
||||||
|
|
@ -141,16 +141,16 @@ of the following elements:
|
||||||
ACL tokens are used to determine if the caller is authorized to perform an action. An ACL token is composed of the following
|
ACL tokens are used to determine if the caller is authorized to perform an action. An ACL token is composed of the following
|
||||||
elements:
|
elements:
|
||||||
|
|
||||||
* **Accessor ID** - The token's public identifier.
|
- **Accessor ID** - The token's public identifier.
|
||||||
* **Secret ID** -The bearer token used when making requests to Consul.
|
- **Secret ID** -The bearer token used when making requests to Consul.
|
||||||
* **Description** - A human readable description of the token. (Optional)
|
- **Description** - A human readable description of the token. (Optional)
|
||||||
* **Policy Set** - The list of policies that are applicable for the token.
|
- **Policy Set** - The list of policies that are applicable for the token.
|
||||||
* **Role Set** - The list of roles that are applicable for the token. (Added in Consul 1.5.0)
|
- **Role Set** - The list of roles that are applicable for the token. (Added in Consul 1.5.0)
|
||||||
* **Service Identity Set** - The list of service identities that are applicable for the token. (Added in Consul 1.5.0)
|
- **Service Identity Set** - The list of service identities that are applicable for the token. (Added in Consul 1.5.0)
|
||||||
* **Locality** - Indicates whether the token should be local to the datacenter it was created within or created in
|
- **Locality** - Indicates whether the token should be local to the datacenter it was created within or created in
|
||||||
the primary datacenter and globally replicated.
|
the primary datacenter and globally replicated.
|
||||||
* **Expiration Time** - The time at which this token is revoked. (Optional; Added in Consul 1.5.0)
|
- **Expiration Time** - The time at which this token is revoked. (Optional; Added in Consul 1.5.0)
|
||||||
* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
- **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
||||||
|
|
||||||
-> **Consul Enterprise Namespacing** - Tokens may only link to policies and roles defined in the same namespace as
|
-> **Consul Enterprise Namespacing** - Tokens may only link to policies and roles defined in the same namespace as
|
||||||
the token itself.
|
the token itself.
|
||||||
|
|
@ -160,19 +160,19 @@ the token itself.
|
||||||
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `master` token will be
|
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `master` token will be
|
||||||
injected.
|
injected.
|
||||||
|
|
||||||
* **Anonymous Token** - The anonymous token is used when a request is made to Consul without specifying a bearer token.
|
- **Anonymous Token** - The anonymous token is used when a request is made to Consul without specifying a bearer token.
|
||||||
The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created,
|
The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created,
|
||||||
it will be assigned `00000000-0000-0000-0000-000000000002` for its Accessor ID and `anonymous` for its Secret ID.
|
it will be assigned `00000000-0000-0000-0000-000000000002` for its Accessor ID and `anonymous` for its Secret ID.
|
||||||
|
|
||||||
* **Master Token** - When a master token is present within the Consul configuration, it is created and will be linked
|
- **Master Token** - When a master token is present within the Consul configuration, it is created and will be linked
|
||||||
With the builtin Global Management policy giving it unrestricted privileges. The master token is created with the Secret ID
|
With the builtin Global Management policy giving it unrestricted privileges. The master token is created with the Secret ID
|
||||||
set to the value of the configuration entry.
|
set to the value of the configuration entry.
|
||||||
|
|
||||||
#### Authorization
|
#### Authorization
|
||||||
|
|
||||||
The token Secret ID is passed along with each RPC request to the servers. Consul's
|
The token Secret ID is passed along with each RPC request to the servers. Consul's
|
||||||
[HTTP endpoints](/api/index.html) can accept tokens via the `token`
|
[HTTP endpoints](/api/index.html) can accept tokens via the `token`
|
||||||
query string parameter, the `X-Consul-Token` request header, or an
|
query string parameter, the `X-Consul-Token` request header, or an
|
||||||
[RFC6750](https://tools.ietf.org/html/rfc6750) authorization bearer token. Consul's
|
[RFC6750](https://tools.ietf.org/html/rfc6750) authorization bearer token. Consul's
|
||||||
[CLI commands](/docs/commands/index.html) can accept tokens via the
|
[CLI commands](/docs/commands/index.html) can accept tokens via the
|
||||||
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. The CLI
|
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. The CLI
|
||||||
|
|
@ -195,18 +195,18 @@ be used to explicitly deny access to resources.
|
||||||
The following table summarizes the ACL resources that are available for constructing
|
The following table summarizes the ACL resources that are available for constructing
|
||||||
rules:
|
rules:
|
||||||
|
|
||||||
| Resource | Scope |
|
| Resource | Scope |
|
||||||
| ------------------------ | ----- |
|
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||||
| [`acl`](#acl-rules) | Operations for managing the ACL system [ACL API](/api/acl/acl.html) |
|
| [`acl`](#acl-rules) | Operations for managing the ACL system [ACL API](/api/acl/acl.html) |
|
||||||
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration |
|
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration |
|
||||||
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
|
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
|
||||||
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) |
|
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) |
|
||||||
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) |
|
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) |
|
||||||
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) |
|
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) |
|
||||||
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) |
|
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) |
|
||||||
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html)
|
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html) |
|
||||||
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) |
|
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) |
|
||||||
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
||||||
|
|
||||||
Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot.html)
|
Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot.html)
|
||||||
requires a token with "write" privileges for the ACL system.
|
requires a token with "write" privileges for the ACL system.
|
||||||
|
|
@ -214,12 +214,12 @@ requires a token with "write" privileges for the ACL system.
|
||||||
The following resources are not covered by ACL policies:
|
The following resources are not covered by ACL policies:
|
||||||
|
|
||||||
1. The [Status API](/api/status.html) is used by servers when bootstrapping and exposes
|
1. The [Status API](/api/status.html) is used by servers when bootstrapping and exposes
|
||||||
basic IP and port information about the servers, and does not allow modification
|
basic IP and port information about the servers, and does not allow modification
|
||||||
of any state.
|
of any state.
|
||||||
|
|
||||||
2. The datacenter listing operation of the
|
2. The datacenter listing operation of the
|
||||||
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known
|
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known
|
||||||
Consul datacenters, and does not allow modification of any state.
|
Consul datacenters, and does not allow modification of any state.
|
||||||
|
|
||||||
3. The [connect CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul.
|
3. The [connect CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul.
|
||||||
|
|
||||||
|
|
@ -234,24 +234,24 @@ will include the ACL policies and roles defined in the [Namespaces definition](/
|
||||||
ACLs are configured using several different configuration options. These are marked
|
ACLs are configured using several different configuration options. These are marked
|
||||||
as to whether they are set on servers, clients, or both.
|
as to whether they are set on servers, clients, or both.
|
||||||
|
|
||||||
| Configuration Option | Servers | Clients | Purpose |
|
| Configuration Option | Servers | Clients | Purpose |
|
||||||
| -------------------- | ------- | ------- | ------- |
|
| ------------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- |
|
||||||
| [`acl.enabled`](/docs/agent/options.html#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled |
|
| [`acl.enabled`](/docs/agent/options.html#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled |
|
||||||
| [`acl.default_policy`](/docs/agent/options.html#acl_default_policy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
|
| [`acl.default_policy`](/docs/agent/options.html#acl_default_policy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
|
||||||
| [`acl.down_policy`](/docs/agent/options.html#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
|
| [`acl.down_policy`](/docs/agent/options.html#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
|
||||||
| [`acl.role_ttl`](/docs/agent/options.html#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles |
|
| [`acl.role_ttl`](/docs/agent/options.html#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles |
|
||||||
| [`acl.policy_ttl`](/docs/agent/options.html#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies |
|
| [`acl.policy_ttl`](/docs/agent/options.html#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies |
|
||||||
| [`acl.token_ttl`](/docs/agent/options.html#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens |
|
| [`acl.token_ttl`](/docs/agent/options.html#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens |
|
||||||
|
|
||||||
A number of special tokens can also be configured which allow for bootstrapping the ACL
|
A number of special tokens can also be configured which allow for bootstrapping the ACL
|
||||||
system, or accessing Consul in special situations:
|
system, or accessing Consul in special situations:
|
||||||
|
|
||||||
| Special Token | Servers | Clients | Purpose |
|
| Special Token | Servers | Clients | Purpose |
|
||||||
| ------------- | ------- | ------- | ------- |
|
| ----------------------------------------------------------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
| [`acl.tokens.agent_master`](/docs/agent/options.html#acl_tokens_agent_master) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details |
|
| [`acl.tokens.agent_master`](/docs/agent/options.html#acl_tokens_agent_master) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details |
|
||||||
| [`acl.tokens.agent`](/docs/agent/options.html#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details |
|
| [`acl.tokens.agent`](/docs/agent/options.html#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details |
|
||||||
| [`acl.tokens.master`](/docs/agent/options.html#acl_tokens_master) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) guide for more details |
|
| [`acl.tokens.master`](/docs/agent/options.html#acl_tokens_master) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) guide for more details |
|
||||||
| [`acl.tokens.default`](/docs/agent/options.html#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
|
| [`acl.tokens.default`](/docs/agent/options.html#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
|
||||||
|
|
||||||
All of these tokens except the `master` token can all be introduced or updated via the [/v1/agent/token API](/api/agent.html#update-acl-tokens).
|
All of these tokens except the `master` token can all be introduced or updated via the [/v1/agent/token API](/api/agent.html#update-acl-tokens).
|
||||||
|
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Kubernetes Auth Method"
|
page_title: 'Kubernetes Auth Method'
|
||||||
sidebar_current: "docs-acl-auth-methods-kubernetes"
|
sidebar_current: 'docs-acl-auth-methods-kubernetes'
|
||||||
description: |-
|
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.
|
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.
|
-> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer.
|
||||||
|
|
||||||
# Kubernetes Auth Method
|
# Kubernetes Auth Method
|
||||||
|
|
||||||
|
|
@ -25,22 +25,22 @@ parameters are required to properly configure an auth method of type
|
||||||
`kubernetes`:
|
`kubernetes`:
|
||||||
|
|
||||||
- `Host` `(string: <required>)` - Must be a host string, a host:port pair, or a
|
- `Host` `(string: <required>)` - Must be a host string, a host:port pair, or a
|
||||||
URL to the base of the Kubernetes API server.
|
URL to the base of the Kubernetes API server.
|
||||||
|
|
||||||
- `CACert` `(string: <required>)` - PEM encoded CA cert for use by the TLS
|
- `CACert` `(string: <required>)` - PEM encoded CA cert for use by the TLS
|
||||||
client used to talk with the Kubernetes API. NOTE: Every line must end with a
|
client used to talk with the Kubernetes API. NOTE: Every line must end with a
|
||||||
newline (`\n`).
|
newline (`\n`).
|
||||||
|
|
||||||
- `ServiceAccountJWT` `(string: <required>)` - A Service Account Token
|
- `ServiceAccountJWT` `(string: <required>)` - A Service Account Token
|
||||||
([JWT](https://jwt.io/ "JSON Web Token")) used by the Consul leader to
|
([JWT](https://jwt.io/ 'JSON Web Token')) used by the Consul leader to
|
||||||
validate application JWTs during login.
|
validate application JWTs during login.
|
||||||
|
|
||||||
- `MapNamespaces` `(bool: <false>)` - **(Enterprise Only)** Indicates whether
|
- `MapNamespaces` `(bool: <false>)` - **(Enterprise Only)** Indicates whether
|
||||||
the auth method should attempt to map the Kubernetes namespace to a Consul
|
the auth method should attempt to map the Kubernetes namespace to a Consul
|
||||||
namespace instead of creating tokens in the auth methods own namespace. Note
|
namespace instead of creating tokens in the auth methods own namespace. Note
|
||||||
that mapping namespaces requires the auth method to reside within the
|
that mapping namespaces requires the auth method to reside within the
|
||||||
`default` namespace.
|
`default` namespace.
|
||||||
|
|
||||||
- `ConsulNamespacePrefix` `(string: <optional>)` - **(Enterprise Only)** When
|
- `ConsulNamespacePrefix` `(string: <optional>)` - **(Enterprise Only)** When
|
||||||
`MapNamespaces` is enabled, this value will be prefixed to the Kubernetes
|
`MapNamespaces` is enabled, this value will be prefixed to the Kubernetes
|
||||||
namespace to determine the Consul namespace to create the new token within.
|
namespace to determine the Consul namespace to create the new token within.
|
||||||
|
|
@ -75,7 +75,7 @@ needs to have access to two Kubernetes APIs:
|
||||||
|
|
||||||
-> Kubernetes should be running with `--service-account-lookup`. This is
|
-> Kubernetes should be running with `--service-account-lookup`. This is
|
||||||
defaulted to true in Kubernetes 1.7, but any versions prior should ensure
|
defaulted to true in Kubernetes 1.7, but any versions prior should ensure
|
||||||
the Kubernetes API server is started with this setting.
|
the Kubernetes API server is started with this setting.
|
||||||
|
|
||||||
- [**ServiceAccount**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#read-serviceaccount-v1-core)
|
- [**ServiceAccount**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#read-serviceaccount-v1-core)
|
||||||
(`get`)
|
(`get`)
|
||||||
|
|
@ -93,9 +93,9 @@ metadata:
|
||||||
name: review-tokens
|
name: review-tokens
|
||||||
namespace: default
|
namespace: default
|
||||||
subjects:
|
subjects:
|
||||||
- kind: ServiceAccount
|
- kind: ServiceAccount
|
||||||
name: consul-auth-method-example
|
name: consul-auth-method-example
|
||||||
namespace: default
|
namespace: default
|
||||||
roleRef:
|
roleRef:
|
||||||
kind: ClusterRole
|
kind: ClusterRole
|
||||||
name: system:auth-delegator
|
name: system:auth-delegator
|
||||||
|
|
@ -107,9 +107,9 @@ metadata:
|
||||||
name: service-account-getter
|
name: service-account-getter
|
||||||
namespace: default
|
namespace: default
|
||||||
rules:
|
rules:
|
||||||
- apiGroups: [""]
|
- apiGroups: ['']
|
||||||
resources: ["serviceaccounts"]
|
resources: ['serviceaccounts']
|
||||||
verbs: ["get"]
|
verbs: ['get']
|
||||||
---
|
---
|
||||||
kind: ClusterRoleBinding
|
kind: ClusterRoleBinding
|
||||||
apiVersion: rbac.authorization.k8s.io/v1
|
apiVersion: rbac.authorization.k8s.io/v1
|
||||||
|
|
@ -117,9 +117,9 @@ metadata:
|
||||||
name: get-service-accounts
|
name: get-service-accounts
|
||||||
namespace: default
|
namespace: default
|
||||||
subjects:
|
subjects:
|
||||||
- kind: ServiceAccount
|
- kind: ServiceAccount
|
||||||
name: consul-auth-method-example
|
name: consul-auth-method-example
|
||||||
namespace: default
|
namespace: default
|
||||||
roleRef:
|
roleRef:
|
||||||
kind: ClusterRole
|
kind: ClusterRole
|
||||||
name: service-account-getter
|
name: service-account-getter
|
||||||
|
|
@ -128,14 +128,14 @@ roleRef:
|
||||||
|
|
||||||
## Trusted Identity Attributes
|
## Trusted Identity Attributes
|
||||||
|
|
||||||
The authentication step returns the following trusted identity attributes for
|
The authentication step returns the following trusted identity attributes for
|
||||||
use in binding rule selectors and bind name interpolation.
|
use in binding rule selectors and bind name interpolation.
|
||||||
|
|
||||||
| Attributes | Supported Selector Operations | Can be Interpolated |
|
| Attributes | Supported Selector Operations | Can be Interpolated |
|
||||||
| -------------------------- | ---------------------------------- | ------------------- |
|
| -------------------------- | ----------------------------- | ------------------- |
|
||||||
| `serviceaccount.namespace` | Equal, Not Equal | yes |
|
| `serviceaccount.namespace` | Equal, Not Equal | yes |
|
||||||
| `serviceaccount.name` | Equal, Not Equal | yes |
|
| `serviceaccount.name` | Equal, Not Equal | yes |
|
||||||
| `serviceaccount.uid` | Equal, Not Equal | yes |
|
| `serviceaccount.uid` | Equal, Not Equal | yes |
|
||||||
|
|
||||||
## Kubernetes Authentication Details
|
## Kubernetes Authentication Details
|
||||||
|
|
||||||
|
|
@ -151,4 +151,3 @@ API to check for the existence of an annotation of
|
||||||
`consul.hashicorp.com/service-name` on the ServiceAccount object. If one is
|
`consul.hashicorp.com/service-name` on the ServiceAccount object. If one is
|
||||||
found its value will override the trusted attribute of `serviceaccount.name`
|
found its value will override the trusted attribute of `serviceaccount.name`
|
||||||
for the purposes of evaluating any binding rules.
|
for the purposes of evaluating any binding rules.
|
||||||
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "ACL Guides"
|
page_title: 'ACL Guides'
|
||||||
sidebar_current: "docs-acl-index"
|
sidebar_current: 'docs-acl-index'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -29,7 +29,7 @@ of Consul ACLs.
|
||||||
|
|
||||||
A core part of the ACL system is the rule language, which is used to describe
|
A core part of the ACL system is the rule language, which is used to describe
|
||||||
the policy that must be enforced. Read the ACL rules
|
the policy that must be enforced. Read the ACL rules
|
||||||
[documentation](/docs/acl/acl-rules.html) to learn about rule specifications.
|
[documentation](/docs/acl/acl-rules.html) to learn about rule specifications.
|
||||||
|
|
||||||
### ACL Auth Methods
|
### ACL Auth Methods
|
||||||
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Agent"
|
page_title: 'Agent'
|
||||||
sidebar_current: "docs-agent-running"
|
sidebar_current: 'docs-agent-running'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -49,30 +49,30 @@ $ consul agent -data-dir=/tmp/consul
|
||||||
|
|
||||||
There are several important messages that [`consul agent`](/docs/commands/agent.html) outputs:
|
There are several important messages that [`consul agent`](/docs/commands/agent.html) outputs:
|
||||||
|
|
||||||
* **Node name**: This is a unique name for the agent. By default, this
|
- **Node name**: This is a unique name for the agent. By default, this
|
||||||
is the hostname of the machine, but you may customize it using the
|
is the hostname of the machine, but you may customize it using the
|
||||||
[`-node`](/docs/agent/options.html#_node) flag.
|
[`-node`](/docs/agent/options.html#_node) flag.
|
||||||
|
|
||||||
* **Datacenter**: This is the datacenter in which the agent is configured to run.
|
- **Datacenter**: This is the datacenter in which the agent is configured to run.
|
||||||
Consul has first-class support for multiple datacenters; however, to work efficiently,
|
Consul has first-class support for multiple datacenters; however, to work efficiently,
|
||||||
each node must be configured to report its datacenter. The [`-datacenter`](/docs/agent/options.html#_datacenter)
|
each node must be configured to report its datacenter. The [`-datacenter`](/docs/agent/options.html#_datacenter)
|
||||||
flag can be used to set the datacenter. For single-DC configurations, the agent
|
flag can be used to set the datacenter. For single-DC configurations, the agent
|
||||||
will default to "dc1".
|
will default to "dc1".
|
||||||
|
|
||||||
* **Server**: This indicates whether the agent is running in server or client mode.
|
- **Server**: This indicates whether the agent is running in server or client mode.
|
||||||
Server nodes have the extra burden of participating in the consensus quorum,
|
Server nodes have the extra burden of participating in the consensus quorum,
|
||||||
storing cluster state, and handling queries. Additionally, a server may be
|
storing cluster state, and handling queries. Additionally, a server may be
|
||||||
in ["bootstrap"](/docs/agent/options.html#_bootstrap_expect) mode. Multiple servers
|
in ["bootstrap"](/docs/agent/options.html#_bootstrap_expect) mode. Multiple servers
|
||||||
cannot be in bootstrap mode as that would put the cluster in an inconsistent state.
|
cannot be in bootstrap mode as that would put the cluster in an inconsistent state.
|
||||||
|
|
||||||
* **Client Addr**: This is the address used for client interfaces to the agent.
|
- **Client Addr**: This is the address used for client interfaces to the agent.
|
||||||
This includes the ports for the HTTP and DNS interfaces. By default, this binds only
|
This includes the ports for the HTTP and DNS interfaces. By default, this binds only
|
||||||
to localhost. If you change this address or port, you'll have to specify a `-http-addr`
|
to localhost. If you change this address or port, you'll have to specify a `-http-addr`
|
||||||
whenever you run commands such as [`consul members`](/docs/commands/members.html) to
|
whenever you run commands such as [`consul members`](/docs/commands/members.html) to
|
||||||
indicate how to reach the agent. Other applications can also use the HTTP address and port
|
indicate how to reach the agent. Other applications can also use the HTTP address and port
|
||||||
[to control Consul](/api/index.html).
|
[to control Consul](/api/index.html).
|
||||||
|
|
||||||
* **Cluster Addr**: This is the address and set of ports used for communication between
|
- **Cluster Addr**: This is the address and set of ports used for communication between
|
||||||
Consul agents in a cluster. Not all Consul agents in a cluster have to
|
Consul agents in a cluster. Not all Consul agents in a cluster have to
|
||||||
use the same port, but this address **MUST** be reachable by all other nodes.
|
use the same port, but this address **MUST** be reachable by all other nodes.
|
||||||
|
|
||||||
|
|
@ -132,6 +132,6 @@ a server, replication to it will stop.
|
||||||
To prevent an accumulation of dead nodes (nodes in either _failed_ or _left_
|
To prevent an accumulation of dead nodes (nodes in either _failed_ or _left_
|
||||||
states), Consul will automatically remove dead nodes out of the catalog. This
|
states), Consul will automatically remove dead nodes out of the catalog. This
|
||||||
process is called _reaping_. This is currently done on a configurable
|
process is called _reaping_. This is currently done on a configurable
|
||||||
interval of 72 hours (changing the reap interval is *not* recommended due to
|
interval of 72 hours (changing the reap interval is _not_ recommended due to
|
||||||
its consequences during outage situations). Reaping is similar to leaving,
|
its consequences during outage situations). Reaping is similar to leaving,
|
||||||
causing all associated services to be deregistered.
|
causing all associated services to be deregistered.
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Check Definition"
|
page_title: 'Check Definition'
|
||||||
sidebar_current: "docs-agent-checks"
|
sidebar_current: 'docs-agent-checks'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -18,7 +18,7 @@ created via the HTTP interface persist with that node.
|
||||||
|
|
||||||
There are several different kinds of checks:
|
There are several different kinds of checks:
|
||||||
|
|
||||||
* Script + Interval - These checks depend on invoking an external application
|
- Script + Interval - These checks depend on invoking an external application
|
||||||
that performs the health check, exits with an appropriate exit code, and potentially
|
that performs the health check, exits with an appropriate exit code, and potentially
|
||||||
generates some output. A script is paired with an invocation interval (e.g.
|
generates some output. A script is paired with an invocation interval (e.g.
|
||||||
every 30 seconds). This is similar to the Nagios plugin system. The output of
|
every 30 seconds). This is similar to the Nagios plugin system. The output of
|
||||||
|
|
@ -31,10 +31,11 @@ There are several different kinds of checks:
|
||||||
it has spawned once the timeout has passed.
|
it has spawned once the timeout has passed.
|
||||||
In Consul 0.9.0 and later, script checks are not enabled by default. To use them you
|
In Consul 0.9.0 and later, script checks are not enabled by default. To use them you
|
||||||
can either use :
|
can either use :
|
||||||
* [`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks):
|
|
||||||
|
- [`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks):
|
||||||
enable script checks defined in local config files. Script checks defined via the HTTP
|
enable script checks defined in local config files. Script checks defined via the HTTP
|
||||||
API will not be allowed.
|
API will not be allowed.
|
||||||
* [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks): enable
|
- [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks): enable
|
||||||
script checks regardless of how they are defined.
|
script checks regardless of how they are defined.
|
||||||
|
|
||||||
~> **Security Warning:** Enabling script checks in some configurations may
|
~> **Security Warning:** Enabling script checks in some configurations may
|
||||||
|
|
@ -43,9 +44,9 @@ There are several different kinds of checks:
|
||||||
blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations)
|
blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations)
|
||||||
for more details.
|
for more details.
|
||||||
|
|
||||||
* HTTP + Interval - These checks make an HTTP `GET` request to the specified URL,
|
- HTTP + Interval - These checks make an HTTP `GET` request to the specified URL,
|
||||||
waiting the specified `interval` amount of time between requests (eg. 30 seconds).
|
waiting the specified `interval` amount of time between requests (eg. 30 seconds).
|
||||||
The status of the service depends on the HTTP response code: any `2xx` code is
|
The status of the service depends on the HTTP response code: any `2xx` code is
|
||||||
considered passing, a `429 Too ManyRequests` is a warning, and anything else is
|
considered passing, a `429 Too ManyRequests` is a warning, and anything else is
|
||||||
a failure. This type of check
|
a failure. This type of check
|
||||||
should be preferred over a script that uses `curl` or another external process
|
should be preferred over a script that uses `curl` or another external process
|
||||||
|
|
@ -61,8 +62,8 @@ There are several different kinds of checks:
|
||||||
Certificate verification can be turned off by setting the `tls_skip_verify`
|
Certificate verification can be turned off by setting the `tls_skip_verify`
|
||||||
field to `true` in the check definition.
|
field to `true` in the check definition.
|
||||||
|
|
||||||
* TCP + Interval - These checks make a TCP connection attempt to the specified
|
- TCP + Interval - These checks make a TCP connection attempt to the specified
|
||||||
IP/hostname and port, waiting `interval` amount of time between attempts
|
IP/hostname and port, waiting `interval` amount of time between attempts
|
||||||
(e.g. 30 seconds). If no hostname
|
(e.g. 30 seconds). If no hostname
|
||||||
is specified, it defaults to "localhost". The status of the service depends on
|
is specified, it defaults to "localhost". The status of the service depends on
|
||||||
whether the connection attempt is successful (ie - the port is currently
|
whether the connection attempt is successful (ie - the port is currently
|
||||||
|
|
@ -72,12 +73,12 @@ There are several different kinds of checks:
|
||||||
addresses, and the first successful connection attempt will result in a
|
addresses, and the first successful connection attempt will result in a
|
||||||
successful check. This type of check should be preferred over a script that
|
successful check. This type of check should be preferred over a script that
|
||||||
uses `netcat` or another external process to check a simple socket operation.
|
uses `netcat` or another external process to check a simple socket operation.
|
||||||
By default, TCP checks will be configured with a request timeout of 10 seconds.
|
By default, TCP checks will be configured with a request timeout of 10 seconds.
|
||||||
It is possible to configure a custom TCP check timeout value by specifying the
|
It is possible to configure a custom TCP check timeout value by specifying the
|
||||||
`timeout` field in the check definition.
|
`timeout` field in the check definition.
|
||||||
|
|
||||||
* <a name="TTL"></a>Time to Live (TTL) - These checks retain their last known
|
- <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
|
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
|
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,
|
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
|
conceptually similar to a dead man's switch, relies on the application to
|
||||||
|
|
@ -88,16 +89,16 @@ There are several different kinds of checks:
|
||||||
[pass](/api/agent/check.html#ttl-check-pass),
|
[pass](/api/agent/check.html#ttl-check-pass),
|
||||||
[warn](/api/agent/check.html#ttl-check-warn),
|
[warn](/api/agent/check.html#ttl-check-warn),
|
||||||
[fail](/api/agent/check.html#ttl-check-fail), and
|
[fail](/api/agent/check.html#ttl-check-fail), and
|
||||||
[update](/api/agent/check.html#ttl-check-update). TTL
|
[update](/api/agent/check.html#ttl-check-update). TTL
|
||||||
checks also persist their last known status to disk. This allows the Consul
|
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
|
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 status is valid through the end of the TTL from the time of the last
|
||||||
check.
|
check.
|
||||||
|
|
||||||
* Docker + Interval - These checks depend on invoking an external application which
|
- Docker + Interval - These checks depend on invoking an external application which
|
||||||
is packaged within a Docker Container. The application is triggered within the running
|
is packaged within a Docker Container. The application is triggered within the running
|
||||||
container via the Docker Exec API. We expect that the Consul agent user has access
|
container via the Docker Exec API. We expect that the Consul agent user has access
|
||||||
to either the Docker HTTP API or the unix socket. Consul uses ```$DOCKER_HOST``` to
|
to either the Docker HTTP API or the unix socket. Consul uses `$DOCKER_HOST` to
|
||||||
determine the Docker API endpoint. The application is expected to run, perform a health
|
determine the Docker API endpoint. The application is expected to run, perform a health
|
||||||
check of the service running inside the container, and exit with an appropriate exit code.
|
check of the service running inside the container, and exit with an appropriate exit code.
|
||||||
The check should be paired with an invocation interval. The shell on which the check
|
The check should be paired with an invocation interval. The shell on which the check
|
||||||
|
|
@ -107,10 +108,10 @@ There are several different kinds of checks:
|
||||||
must be configured with [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks)
|
must be configured with [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks)
|
||||||
set to `true` in order to enable Docker health checks.
|
set to `true` in order to enable Docker health checks.
|
||||||
|
|
||||||
* gRPC + Interval - These checks are intended for applications that support the standard
|
- gRPC + Interval - These checks are intended for applications that support the standard
|
||||||
[gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
|
[gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
|
||||||
The state of the check will be updated by probing the configured endpoint, waiting `interval`
|
The state of the check will be updated by probing the configured endpoint, waiting `interval`
|
||||||
amount of time between probes (eg. 30 seconds). By default, gRPC checks will be configured
|
amount of time between probes (eg. 30 seconds). By default, gRPC checks will be configured
|
||||||
with a default timeout of 10 seconds.
|
with a default timeout of 10 seconds.
|
||||||
It is possible to configure a custom timeout value by specifying the `timeout` field in
|
It is possible to configure a custom timeout value by specifying the `timeout` field in
|
||||||
the check definition. gRPC checks will default to not using TLS, but TLS can be enabled by
|
the check definition. gRPC checks will default to not using TLS, but TLS can be enabled by
|
||||||
|
|
@ -119,7 +120,7 @@ There are several different kinds of checks:
|
||||||
`tls_skip_verify` field to `true` in the check definition.
|
`tls_skip_verify` field to `true` in the check definition.
|
||||||
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`.
|
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
|
- <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,
|
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
|
but is nearly instant. For aliased services on the same agent, the local
|
||||||
state is monitored and no additional network resources are consumed. For
|
state is monitored and no additional network resources are consumed. For
|
||||||
|
|
@ -265,6 +266,7 @@ to watch the state of the aliased node or service.
|
||||||
Script, TCP, HTTP, Docker, and gRPC checks must include an `interval` field. This
|
Script, TCP, HTTP, Docker, and gRPC checks must include an `interval` field. This
|
||||||
field is parsed by Go's `time` package, and has the following
|
field is parsed by Go's `time` package, and has the following
|
||||||
[formatting specification](https://golang.org/pkg/time/#ParseDuration):
|
[formatting specification](https://golang.org/pkg/time/#ParseDuration):
|
||||||
|
|
||||||
> A duration string is a possibly signed sequence of decimal numbers, each with
|
> A duration string is a possibly signed sequence of decimal numbers, each with
|
||||||
> optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
|
> optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
|
||||||
> Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
|
> Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
|
||||||
|
|
@ -291,9 +293,9 @@ A check script is generally free to do anything to determine the status
|
||||||
of the check. The only limitations placed are that the exit codes must obey
|
of the check. The only limitations placed are that the exit codes must obey
|
||||||
this convention:
|
this convention:
|
||||||
|
|
||||||
* Exit code 0 - Check is passing
|
- Exit code 0 - Check is passing
|
||||||
* Exit code 1 - Check is warning
|
- Exit code 1 - Check is warning
|
||||||
* Any other code - Check is failing
|
- Any other code - Check is failing
|
||||||
|
|
||||||
This is the only convention that Consul depends on. Any output of the script
|
This is the only convention that Consul depends on. Any output of the script
|
||||||
will be captured and stored in the `output` field.
|
will be captured and stored in the `output` field.
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Cloud Auto-join"
|
page_title: 'Cloud Auto-join'
|
||||||
sidebar_current: "docs-agent-cloud-auto-join"
|
sidebar_current: 'docs-agent-cloud-auto-join'
|
||||||
description: |-
|
description: |-
|
||||||
Consul supports automatically joining a Consul datacenter using cloud metadata on various providers.
|
Consul supports automatically joining a Consul datacenter using cloud metadata on various providers.
|
||||||
---
|
---
|
||||||
|
|
@ -9,7 +9,7 @@ description: |-
|
||||||
# Cloud Auto-join
|
# Cloud Auto-join
|
||||||
|
|
||||||
As of Consul 0.9.1, `retry-join` accepts a unified interface using the
|
As of Consul 0.9.1, `retry-join` accepts a unified interface using the
|
||||||
[go-discover](https://github.com/hashicorp/go-discover) library for
|
[go-discover](https://github.com/hashicorp/go-discover) library for
|
||||||
automatically joining a Consul datacenter using cloud metadata. To use `retry-join` with a
|
automatically joining a Consul datacenter using cloud metadata. To use `retry-join` with a
|
||||||
supported cloud provider, specify the configuration on the command line or
|
supported cloud provider, specify the configuration on the command line or
|
||||||
configuration file as a `key=value key=value ...` string.
|
configuration file as a `key=value key=value ...` string.
|
||||||
|
|
@ -29,7 +29,7 @@ or via a configuration file:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=my-cloud config=val config2=\"some other val\" ..."]
|
"retry_join": ["provider=my-cloud config=val config2=\"some other val\" ..."]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -55,7 +55,7 @@ $ consul agent -retry-join "provider=aws tag_key=... tag_value=..."
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=aws tag_key=... tag_value=..."]
|
"retry_join": ["provider=aws tag_key=... tag_value=..."]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -93,7 +93,9 @@ $ consul agent -retry-join "provider=azure tag_name=... tag_value=... tenant_id=
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."]
|
"retry_join": [
|
||||||
|
"provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -104,10 +106,10 @@ $ consul agent -retry-join "provider=azure tag_name=... tag_value=... tenant_id=
|
||||||
|
|
||||||
Variables can also be provided by environmental variables:
|
Variables can also be provided by environmental variables:
|
||||||
|
|
||||||
* `ARM_SUBSCRIPTION_ID` for subscription
|
- `ARM_SUBSCRIPTION_ID` for subscription
|
||||||
* `ARM_TENANT_ID` for tenant
|
- `ARM_TENANT_ID` for tenant
|
||||||
* `ARM_CLIENT_ID` for client
|
- `ARM_CLIENT_ID` for client
|
||||||
* `ARM_CLIENT_SECRET` for secret access key
|
- `ARM_CLIENT_SECRET` for secret access key
|
||||||
|
|
||||||
Use these configuration parameters when using tags:
|
Use these configuration parameters when using tags:
|
||||||
|
|
||||||
|
|
@ -136,7 +138,7 @@ $ consul agent -retry-join "provider=gce project_name=... tag_value=..."
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=gce project_name=... tag_value=..."]
|
"retry_join": ["provider=gce project_name=... tag_value=..."]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -155,10 +157,10 @@ Credentials are searched using the following paths, in order of precedence.
|
||||||
- Use credentials from `credentials_file`, if provided.
|
- Use credentials from `credentials_file`, if provided.
|
||||||
- Use JSON file from `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
|
- Use JSON file from `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
|
||||||
- Use JSON file in a location known to the gcloud command-line tool.
|
- Use JSON file in a location known to the gcloud command-line tool.
|
||||||
- On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`.
|
- On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`.
|
||||||
- On other systems, `$HOME/.config/gcloud/application_default_credentials.json`.
|
- On other systems, `$HOME/.config/gcloud/application_default_credentials.json`.
|
||||||
- On Google Compute Engine, use credentials from the metadata
|
- On Google Compute Engine, use credentials from the metadata
|
||||||
server. In this final case any provided scopes are ignored.
|
server. In this final case any provided scopes are ignored.
|
||||||
|
|
||||||
### IBM SoftLayer
|
### IBM SoftLayer
|
||||||
|
|
||||||
|
|
@ -171,7 +173,9 @@ $ consul agent -retry-join "provider=softlayer datacenter=... tag_value=... user
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=softlayer datacenter=... tag_value=... username=... api_key=..."]
|
"retry_join": [
|
||||||
|
"provider=softlayer datacenter=... tag_value=... username=... api_key=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -192,7 +196,9 @@ $ consul agent -retry-join "provider=aliyun region=... tag_key=consul tag_value=
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=aliyun region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."]
|
"retry_join": [
|
||||||
|
"provider=aliyun region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -217,7 +223,7 @@ $ consul agent -retry-join "provider=digitalocean region=... tag_name=... api_to
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=digitalocean region=... tag_name=... api_token=..."]
|
"retry_join": ["provider=digitalocean region=... tag_name=... api_token=..."]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -237,7 +243,9 @@ $ consul agent -retry-join "provider=os tag_key=consul tag_value=server username
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=os tag_key=consul tag_value=server username=... password=... auth_url=..."]
|
"retry_join": [
|
||||||
|
"provider=os tag_key=consul tag_value=server username=... password=... auth_url=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -267,7 +275,9 @@ $ consul agent -retry-join "provider=scaleway organization=my-org tag_name=consu
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=scaleway organization=my-org tag_name=consul-server token=... region=..."]
|
"retry_join": [
|
||||||
|
"provider=scaleway organization=my-org tag_name=consul-server token=... region=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -277,7 +287,6 @@ $ consul agent -retry-join "provider=scaleway organization=my-org tag_name=consu
|
||||||
- `organization` (required) - the organization access key to use for auth (equal to access key).
|
- `organization` (required) - the organization access key to use for auth (equal to access key).
|
||||||
- `token` (required) - the token to use for auth.
|
- `token` (required) - the token to use for auth.
|
||||||
|
|
||||||
|
|
||||||
### TencentCloud
|
### TencentCloud
|
||||||
|
|
||||||
This returns the first IP address of all servers for the given `region` with the given `tag_key` and `tag_value`.
|
This returns the first IP address of all servers for the given `region` with the given `tag_key` and `tag_value`.
|
||||||
|
|
@ -288,7 +297,9 @@ $ consul agent -retry-join "provider=tencentcloud region=... tag_key=consul tag_
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=tencentcloud region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."]
|
"retry_join": [
|
||||||
|
"provider=tencentcloud region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -303,7 +314,6 @@ $ consul agent -retry-join "provider=tencentcloud region=... tag_key=consul tag_
|
||||||
This required permission to 'cvm:DescribeInstances'.
|
This required permission to 'cvm:DescribeInstances'.
|
||||||
It is recommended you make a dedicated key used to auto-join the Consul datacenter.
|
It is recommended you make a dedicated key used to auto-join the Consul datacenter.
|
||||||
|
|
||||||
|
|
||||||
### Joyent Triton
|
### Joyent Triton
|
||||||
|
|
||||||
This returns the first PrimaryIP addresses for all servers with the given `tag_key` and `tag_value`.
|
This returns the first PrimaryIP addresses for all servers with the given `tag_key` and `tag_value`.
|
||||||
|
|
@ -314,7 +324,9 @@ $ consul agent -retry-join "provider=triton account=testaccount url=https://us-s
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry_join": ["provider=triton account=testaccount url=https://us-sw-1.api.joyentcloud.com key_id=... tag_key=consul-role tag_value=server"]
|
"retry_join": [
|
||||||
|
"provider=triton account=testaccount url=https://us-sw-1.api.joyentcloud.com key_id=... tag_key=consul-role tag_value=server"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -325,7 +337,6 @@ $ consul agent -retry-join "provider=triton account=testaccount url=https://us-s
|
||||||
- `tag_key` (optional) - the instance tag key to use.
|
- `tag_key` (optional) - the instance tag key to use.
|
||||||
- `tag_value` (optional) - the tag value to use.
|
- `tag_value` (optional) - the tag value to use.
|
||||||
|
|
||||||
|
|
||||||
### vSphere
|
### vSphere
|
||||||
|
|
||||||
This returns the first private IP address of all servers for the given region with the given `tag_name` and `category_name`.
|
This returns the first private IP address of all servers for the given region with the given `tag_name` and `category_name`.
|
||||||
|
|
@ -336,18 +347,20 @@ $ consul agent -retry-join "provider=vsphere category_name=consul-role tag_name=
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry-join": ["provider=vsphere category_name=consul-role tag_name=consul-server host=... user=... password=... insecure_ssl=[true|false]"]
|
"retry-join": [
|
||||||
|
"provider=vsphere category_name=consul-role tag_name=consul-server host=... user=... password=... insecure_ssl=[true|false]"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `provider` (required) - the name of the provider ("vsphere" is the provider here)
|
- `provider` (required) - the name of the provider ("vsphere" is the provider here)
|
||||||
- `tag_name` (required) - The name of the tag to look up.
|
- `tag_name` (required) - The name of the tag to look up.
|
||||||
- `category_name` (required) - The category of the tag to look up.
|
- `category_name` (required) - The category of the tag to look up.
|
||||||
- `host` (required) - The host of the vSphere server to connect to.
|
- `host` (required) - The host of the vSphere server to connect to.
|
||||||
- `user` (required) - The username to connect as.
|
- `user` (required) - The username to connect as.
|
||||||
- `password` (required) - The password of the user to connect to vSphere as.
|
- `password` (required) - The password of the user to connect to vSphere as.
|
||||||
- `insecure_ssl` (optional) - Whether or not to skip SSL certificate validation.
|
- `insecure_ssl` (optional) - Whether or not to skip SSL certificate validation.
|
||||||
- `timeout` (optional) - Discovery context timeout (default: 10m)
|
- `timeout` (optional) - Discovery context timeout (default: 10m)
|
||||||
|
|
||||||
### Packet
|
### Packet
|
||||||
|
|
||||||
|
|
@ -359,15 +372,17 @@ $ consul agent -retry-join "provider=packet auth_token=token project=uuid url=..
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry-join": ["provider=packet auth_token=token project=uuid url=... address_type=..."]
|
"retry-join": [
|
||||||
|
"provider=packet auth_token=token project=uuid url=... address_type=..."
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `provider` (required) - the name of the provider ("packet" is the provider here)
|
- `provider` (required) - the name of the provider ("packet" is the provider here)
|
||||||
- `project` (required) - the UUID of packet project
|
- `project` (required) - the UUID of packet project
|
||||||
- `auth_token` (required) - the authentication token for packet
|
- `auth_token` (required) - the authentication token for packet
|
||||||
- `url` (optional) - a REST URL for packet
|
- `url` (optional) - a REST URL for packet
|
||||||
- `address_type` (optional) - the type of address to check for in this provider ("private_v4", "public_v4" or "public_v6". Defaults to "private_v4")
|
- `address_type` (optional) - the type of address to check for in this provider ("private_v4", "public_v4" or "public_v6". Defaults to "private_v4")
|
||||||
|
|
||||||
### Linode
|
### Linode
|
||||||
|
|
||||||
|
|
@ -379,7 +394,7 @@ $ consul agent -retry-join "provider=linode region=us-east tag_name=consul-serve
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry-join": ["provider=linode region=us-east tag_name=consul-server"]
|
"retry-join": ["provider=linode region=us-east tag_name=consul-server"]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -416,15 +431,15 @@ $ consul agent -retry-join "provider=k8s label_selector=\"app=consul,component=s
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"retry-join": ["provider=k8s label_selector=..."]
|
"retry-join": ["provider=k8s label_selector=..."]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- `provider` (required) - the name of the provider ("k8s" is the provider here)
|
- `provider` (required) - the name of the provider ("k8s" is the provider here)
|
||||||
- `kubeconfig` (optional) - path to the kubeconfig file. If this isn't
|
- `kubeconfig` (optional) - path to the kubeconfig file. If this isn't
|
||||||
set, then in-cluster auth will be attempted. If that fails, the default
|
set, then in-cluster auth will be attempted. If that fails, the default
|
||||||
kubeconfig paths are tried (`$HOME/.kube/config`).
|
kubeconfig paths are tried (`$HOME/.kube/config`).
|
||||||
- `namespace` (optional) - the namespace to search for pods. If this isn't
|
- `namespace` (optional) - the namespace to search for pods. If this isn't
|
||||||
set, it defaults to all namespaces.
|
set, it defaults to all namespaces.
|
||||||
- `label_selector` (optional) - the label selector for matching pods.
|
- `label_selector` (optional) - the label selector for matching pods.
|
||||||
- `field_selector` (optional) - the field selector for matching pods.
|
- `field_selector` (optional) - the field selector for matching pods.
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Configuration Entry Kind: Proxy Defaults"
|
page_title: 'Configuration Entry Kind: Proxy Defaults'
|
||||||
sidebar_current: "docs-agent-cfg_entries-proxy_defaults"
|
sidebar_current: 'docs-agent-cfg_entries-proxy_defaults'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -49,36 +49,36 @@ config {
|
||||||
that your proxy allows can be configured globally here. To
|
that your proxy allows can be configured globally here. To
|
||||||
explore these options please see the documentation for your chosen proxy.
|
explore these options please see the documentation for your chosen proxy.
|
||||||
|
|
||||||
* [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
|
- [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
|
||||||
* [Consul's built-in proxy](/docs/connect/proxies/built-in.html)
|
- [Consul's built-in proxy](/docs/connect/proxies/built-in.html)
|
||||||
|
|
||||||
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
|
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
|
||||||
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration)
|
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration)
|
||||||
for all proxies. Added in v1.6.0.
|
for all proxies. Added in v1.6.0.
|
||||||
|
|
||||||
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
|
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
|
||||||
|
|
||||||
- `Expose` `(ExposeConfig: <optional>)` - Controls the default
|
- `Expose` `(ExposeConfig: <optional>)` - Controls the default
|
||||||
[expose path configuration](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference)
|
[expose path configuration](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference)
|
||||||
for Envoy. Added in v1.6.2.
|
for Envoy. Added in v1.6.2.
|
||||||
|
|
||||||
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
|
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
|
||||||
non-Connect-enabled applications to contact an HTTP endpoint.
|
non-Connect-enabled applications to contact an HTTP endpoint.
|
||||||
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks.
|
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks.
|
||||||
|
|
||||||
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
|
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
|
||||||
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
|
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
|
||||||
[advertise address](/docs/agent/options.html#advertise). The port for these listeners are dynamically allocated from
|
[advertise address](/docs/agent/options.html#advertise). The port for these listeners are dynamically allocated from
|
||||||
[expose_min_port](/docs/agent/options.html#expose_min_port) to [expose_max_port](/docs/agent/options.html#expose_max_port).
|
[expose_min_port](/docs/agent/options.html#expose_min_port) to [expose_max_port](/docs/agent/options.html#expose_max_port).
|
||||||
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
|
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
|
||||||
Consul on Kubernetes, and Consul agents run in their own pods.
|
Consul on Kubernetes, and Consul agents run in their own pods.
|
||||||
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy.
|
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy.
|
||||||
- `Path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.
|
- `Path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.
|
||||||
- `LocalPathPort` `(int: 0)` - The port where the local service is listening for connections to the path.
|
- `LocalPathPort` `(int: 0)` - The port where the local service is listening for connections to the path.
|
||||||
- `ListenerPort` `(int: 0)` - The port where the proxy will listen for connections. This port must be available
|
- `ListenerPort` `(int: 0)` - The port where the proxy will listen for connections. This port must be available
|
||||||
for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
|
for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
|
||||||
but the proxy registration will not fail.
|
but the proxy registration will not fail.
|
||||||
- `Protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.
|
- `Protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Configuration Entry Kind: Service Defaults"
|
page_title: 'Configuration Entry Kind: Service Defaults'
|
||||||
sidebar_current: "docs-agent-cfg_entries-service_defaults"
|
sidebar_current: 'docs-agent-cfg_entries-service_defaults'
|
||||||
description: |-
|
description: |-
|
||||||
The service-defaults config entry kind controls default global values for a service, such as its protocol.
|
The service-defaults config entry kind controls default global values for a service, such as its protocol.
|
||||||
---
|
---
|
||||||
|
|
@ -46,28 +46,28 @@ Protocol = "http"
|
||||||
the TLS [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value to
|
the TLS [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value to
|
||||||
be changed to a non-connect value when federating with an external system.
|
be changed to a non-connect value when federating with an external system.
|
||||||
Added in v1.6.0.
|
Added in v1.6.0.
|
||||||
|
|
||||||
- `Expose` `(ExposeConfig: <optional>)` - Controls the default
|
- `Expose` `(ExposeConfig: <optional>)` - Controls the default
|
||||||
[expose path configuration](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference)
|
[expose path configuration](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference)
|
||||||
for Envoy. Added in v1.6.2.
|
for Envoy. Added in v1.6.2.
|
||||||
|
|
||||||
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
|
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
|
||||||
non-Connect-enabled applications to contact an HTTP endpoint.
|
non-Connect-enabled applications to contact an HTTP endpoint.
|
||||||
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks.
|
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks.
|
||||||
|
|
||||||
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
|
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
|
||||||
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
|
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
|
||||||
[advertise address](/docs/agent/options.html#advertise). The port for these listeners are dynamically allocated from
|
[advertise address](/docs/agent/options.html#advertise). The port for these listeners are dynamically allocated from
|
||||||
[expose_min_port](/docs/agent/options.html#expose_min_port) to [expose_max_port](/docs/agent/options.html#expose_max_port).
|
[expose_min_port](/docs/agent/options.html#expose_min_port) to [expose_max_port](/docs/agent/options.html#expose_max_port).
|
||||||
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
|
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
|
||||||
Consul on Kubernetes, and Consul agents run in their own pods.
|
Consul on Kubernetes, and Consul agents run in their own pods.
|
||||||
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy.
|
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy.
|
||||||
- `Path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.
|
- `Path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.
|
||||||
- `LocalPathPort` `(int: 0)` - The port where the local service is listening for connections to the path.
|
- `LocalPathPort` `(int: 0)` - The port where the local service is listening for connections to the path.
|
||||||
- `ListenerPort` `(int: 0)` - The port where the proxy will listen for connections. This port must be available for
|
- `ListenerPort` `(int: 0)` - The port where the proxy will listen for connections. This port must be available for
|
||||||
the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
|
the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
|
||||||
but the proxy registration will not fail.
|
but the proxy registration will not fail.
|
||||||
- `Protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.
|
- `Protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Configuration Entry Kind: Service Resolver"
|
page_title: 'Configuration Entry Kind: Service Resolver'
|
||||||
sidebar_current: "docs-agent-cfg_entries-service_resolver"
|
sidebar_current: 'docs-agent-cfg_entries-service_resolver'
|
||||||
description: |-
|
description: |-
|
||||||
The `service-resolver` config entry kind controls which service instances should satisfy Connect upstream discovery requests for a given service name.
|
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.
|
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.
|
||||||
|
|
||||||
# Service Resolver
|
# Service Resolver
|
||||||
|
|
||||||
|
|
@ -87,10 +87,10 @@ name = "web"
|
||||||
subset definition for all usable named subsets of this service. The map key
|
subset definition for all usable named subsets of this service. The map key
|
||||||
is the name of the subset and all names must be valid DNS subdomain elements.
|
is the name of the subset and all names must be valid DNS subdomain elements.
|
||||||
|
|
||||||
This may be empty, in which case only the unnamed default subset will be
|
This may be empty, in which case only the unnamed default subset will be
|
||||||
usable.
|
usable.
|
||||||
|
|
||||||
- `Filter` `(string: "")` - The
|
- `Filter` `(string: "")` - The
|
||||||
[filter expression](/api/features/filtering.html) to be used for selecting
|
[filter expression](/api/features/filtering.html) to be used for selecting
|
||||||
instances of the requested service. If empty all healthy instances are
|
instances of the requested service. If empty all healthy instances are
|
||||||
returned. This expression can filter on the same selectors as the
|
returned. This expression can filter on the same selectors as the
|
||||||
|
|
@ -106,8 +106,8 @@ name = "web"
|
||||||
attempts to resolve the service this resolver defines will be substituted for
|
attempts to resolve the service this resolver defines will be substituted for
|
||||||
the supplied redirect EXCEPT when the redirect has already been applied.
|
the supplied redirect EXCEPT when the redirect has already been applied.
|
||||||
|
|
||||||
When substituting the supplied redirect into the all other fields besides
|
When substituting the supplied redirect into the all other fields besides
|
||||||
`Kind`, `Name`, and `Redirect` will be ignored.
|
`Kind`, `Name`, and `Redirect` will be ignored.
|
||||||
|
|
||||||
- `Service` `(string: "")` - A service to resolve instead of the current
|
- `Service` `(string: "")` - A service to resolve instead of the current
|
||||||
service.
|
service.
|
||||||
|
|
@ -128,12 +128,12 @@ name = "web"
|
||||||
- `Failover` `(map[string]ServiceResolverFailover`) - Controls when and how to
|
- `Failover` `(map[string]ServiceResolverFailover`) - Controls when and how to
|
||||||
reroute traffic to an alternate pool of service instances.
|
reroute traffic to an alternate pool of service instances.
|
||||||
|
|
||||||
The map is keyed by the service subset it applies to and the special
|
The map is keyed by the service subset it applies to and the special
|
||||||
string `"*"` is a wildcard that applies to any subset not otherwise
|
string `"*"` is a wildcard that applies to any subset not otherwise
|
||||||
specified here.
|
specified here.
|
||||||
|
|
||||||
`Service`, `ServiceSubset`, `Namespace`, and `Datacenters` cannot all be
|
`Service`, `ServiceSubset`, `Namespace`, and `Datacenters` cannot all be
|
||||||
empty at once.
|
empty at once.
|
||||||
|
|
||||||
- `Service` `(string: "")` - The service to resolve instead of the default as
|
- `Service` `(string: "")` - The service to resolve instead of the default as
|
||||||
the failover group of instances during failover.
|
the failover group of instances during failover.
|
||||||
|
|
@ -177,4 +177,3 @@ name in these fields:
|
||||||
- [`Redirect.Service`](#service)
|
- [`Redirect.Service`](#service)
|
||||||
|
|
||||||
- [`Failover[].Service`](#service-1)
|
- [`Failover[].Service`](#service-1)
|
||||||
|
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Configuration Entry Kind: Service Router"
|
page_title: 'Configuration Entry Kind: Service Router'
|
||||||
sidebar_current: "docs-agent-cfg_entries-service_router"
|
sidebar_current: 'docs-agent-cfg_entries-service_router'
|
||||||
description: |-
|
description: |-
|
||||||
The service-router config entry kind controls Connect traffic routing and manipulation at networking layer 7 (e.g. HTTP).
|
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.
|
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.
|
||||||
|
|
||||||
# Service Router
|
# Service Router
|
||||||
|
|
||||||
|
|
@ -133,21 +133,21 @@ routes = [
|
||||||
stops further evaluation. Traffic that fails to match any of the provided
|
stops further evaluation. Traffic that fails to match any of the provided
|
||||||
routes will be routed to the default service.
|
routes will be routed to the default service.
|
||||||
|
|
||||||
- `Match` `(ServiceRouteMatch: <optional>)` - A set of criteria that can
|
- `Match` `(ServiceRouteMatch: <optional>)` - A set of criteria that can
|
||||||
match incoming L7 requests. If empty or omitted it acts as a catch-all.
|
match incoming L7 requests. If empty or omitted it acts as a catch-all.
|
||||||
|
|
||||||
- `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of
|
- `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of
|
||||||
[http-specific match criteria](#serviceroutehttpmatch).
|
[http-specific match criteria](#serviceroutehttpmatch).
|
||||||
|
|
||||||
- `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to
|
- `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to
|
||||||
proxy](#serviceroutedestination) the matching request(s) to a
|
proxy](#serviceroutedestination) the matching request(s) to a
|
||||||
service.
|
service.
|
||||||
|
|
||||||
### `ServiceRouteHTTPMatch`
|
### `ServiceRouteHTTPMatch`
|
||||||
|
|
||||||
- `PathExact` `(string: "")` - Exact path to match on the HTTP request path.
|
- `PathExact` `(string: "")` - Exact path to match on the HTTP request path.
|
||||||
|
|
||||||
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
||||||
|
|
||||||
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
|
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
|
||||||
|
|
||||||
|
|
@ -164,64 +164,64 @@ routes = [
|
||||||
match on HTTP request headers. If more than one is configured all must match
|
match on HTTP request headers. If more than one is configured all must match
|
||||||
for the overall match to apply.
|
for the overall match to apply.
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - Name of the header to match.
|
- `Name` `(string: <required>)` - Name of the header to match.
|
||||||
|
|
||||||
- `Present` `(bool: false)` - Match if the header with the given name is
|
- `Present` `(bool: false)` - Match if the header with the given name is
|
||||||
present with any value.
|
present with any value.
|
||||||
|
|
||||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
may be configured.
|
may be configured.
|
||||||
|
|
||||||
- `Exact` `(string: "")` - Match if the header with the given name is this
|
- `Exact` `(string: "")` - Match if the header with the given name is this
|
||||||
value.
|
value.
|
||||||
|
|
||||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
may be configured.
|
may be configured.
|
||||||
|
|
||||||
- `Prefix` `(string: "")` - Match if the header with the given name has
|
- `Prefix` `(string: "")` - Match if the header with the given name has
|
||||||
this prefix.
|
this prefix.
|
||||||
|
|
||||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
may be configured.
|
may be configured.
|
||||||
|
|
||||||
- `Suffix` `(string: "")` - Match if the header with the given name has
|
- `Suffix` `(string: "")` - Match if the header with the given name has
|
||||||
this suffix.
|
this suffix.
|
||||||
|
|
||||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
may be configured.
|
may be configured.
|
||||||
|
|
||||||
- `Regex` `(string: "")` - Match if the header with the given name matches
|
- `Regex` `(string: "")` - Match if the header with the given name matches
|
||||||
this pattern.
|
this pattern.
|
||||||
|
|
||||||
The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript).
|
The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript).
|
||||||
|
|
||||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
may be configured.
|
may be configured.
|
||||||
|
|
||||||
- `Invert` `(bool: false)` - Inverts the logic of the match.
|
- `Invert` `(bool: false)` - Inverts the logic of the match.
|
||||||
|
|
||||||
- `QueryParam` `(array<ServiceRouteHTTPMatchQueryParam>)` - A set of criteria
|
- `QueryParam` `(array<ServiceRouteHTTPMatchQueryParam>)` - A set of criteria
|
||||||
that can match on HTTP query parameters. If more than one is configured all
|
that can match on HTTP query parameters. If more than one is configured all
|
||||||
must match for the overall match to apply.
|
must match for the overall match to apply.
|
||||||
|
|
||||||
- `Name` `(string: <required>)` - The name of the query parameter to match on.
|
- `Name` `(string: <required>)` - The name of the query parameter to match on.
|
||||||
|
|
||||||
- `Present` `(bool: false)` - Match if the query parameter with the given
|
- `Present` `(bool: false)` - Match if the query parameter with the given
|
||||||
name is present with any value.
|
name is present with any value.
|
||||||
|
|
||||||
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
||||||
|
|
||||||
- `Exact` `(string: "")` - Match if the query parameter with the given name
|
- `Exact` `(string: "")` - Match if the query parameter with the given name
|
||||||
is this value.
|
is this value.
|
||||||
|
|
||||||
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
||||||
|
|
||||||
- `Regex` `(string: "")` - Match if the query parameter with the given name
|
- `Regex` `(string: "")` - Match if the query parameter with the given name
|
||||||
matches this pattern.
|
matches this pattern.
|
||||||
|
|
||||||
The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript).
|
The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript).
|
||||||
|
|
||||||
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
||||||
|
|
||||||
- `Methods` `(array<string>)` - A list of HTTP methods for which this match
|
- `Methods` `(array<string>)` - A list of HTTP methods for which this match
|
||||||
applies. If unspecified all http methods are matched.
|
applies. If unspecified all http methods are matched.
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Configuration Entry Kind: Service Splitter"
|
page_title: 'Configuration Entry Kind: Service Splitter'
|
||||||
sidebar_current: "docs-agent-cfg_entries-service_splitter"
|
sidebar_current: 'docs-agent-cfg_entries-service_splitter'
|
||||||
description: |-
|
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).
|
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.
|
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.
|
||||||
|
|
||||||
# Service Splitter
|
# Service Splitter
|
||||||
|
|
||||||
|
|
@ -79,7 +79,7 @@ splits = [
|
||||||
- `Name` `(string: <required>)` - Set to the name of the service being configured.
|
- `Name` `(string: <required>)` - Set to the name of the service being configured.
|
||||||
|
|
||||||
- `Splits` `(array<ServiceSplit>)` - Defines how much traffic to send to which
|
- `Splits` `(array<ServiceSplit>)` - Defines how much traffic to send to which
|
||||||
set of service instances during a traffic split. The sum of weights across
|
set of service instances during a traffic split. The sum of weights across
|
||||||
all splits must add up to 100.
|
all splits must add up to 100.
|
||||||
|
|
||||||
- `Weight` `(float32: 0)` - A value between 0 and 100 reflecting what portion
|
- `Weight` `(float32: 0)` - A value between 0 and 100 reflecting what portion
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Configuration Entry Definitions"
|
page_title: 'Configuration Entry Definitions'
|
||||||
sidebar_current: "docs-agent-cfg_entries"
|
sidebar_current: 'docs-agent-cfg_entries'
|
||||||
description: |-
|
description: |-
|
||||||
Consul allows storing configuration entries centrally to be used as defaults for configuring other aspects of Consul.
|
Consul allows storing configuration entries centrally to be used as defaults for configuring other aspects of Consul.
|
||||||
---
|
---
|
||||||
|
|
@ -24,20 +24,20 @@ Name = "<name of entry>"
|
||||||
|
|
||||||
The supported `Kind` names for configuration entries are:
|
The supported `Kind` names for configuration entries are:
|
||||||
|
|
||||||
* [`service-router`](/docs/agent/config-entries/service-router.html) - defines
|
- [`service-router`](/docs/agent/config-entries/service-router.html) - defines
|
||||||
where to send layer 7 traffic based on the HTTP route
|
where to send layer 7 traffic based on the HTTP route
|
||||||
|
|
||||||
* [`service-splitter`](/docs/agent/config-entries/service-splitter.html) - defines
|
- [`service-splitter`](/docs/agent/config-entries/service-splitter.html) - defines
|
||||||
how to divide requests for a single HTTP route based on percentages
|
how to divide requests for a single HTTP route based on percentages
|
||||||
|
|
||||||
* [`service-resolver`](/docs/agent/config-entries/service-resolver.html) - matches
|
- [`service-resolver`](/docs/agent/config-entries/service-resolver.html) - matches
|
||||||
service instances with a specific Connect upstream discovery requests
|
service instances with a specific Connect upstream discovery requests
|
||||||
|
|
||||||
* [`service-defaults`](/docs/agent/config-entries/service-defaults.html) - configures
|
- [`service-defaults`](/docs/agent/config-entries/service-defaults.html) - configures
|
||||||
defaults for all the instances of a given service
|
defaults for all the instances of a given service
|
||||||
|
|
||||||
* [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) - controls
|
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) - controls
|
||||||
proxy configuration
|
proxy configuration
|
||||||
|
|
||||||
## Managing Configuration Entries
|
## Managing Configuration Entries
|
||||||
|
|
||||||
|
|
@ -111,7 +111,6 @@ api
|
||||||
db
|
db
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
#### Deleting Configuration Entries
|
#### Deleting Configuration Entries
|
||||||
|
|
||||||
The [`consul config delete`](/docs/commands/config/delete.html) command is used
|
The [`consul config delete`](/docs/commands/config/delete.html) command is used
|
||||||
|
|
@ -131,7 +130,7 @@ This command will not output anything when the deletion is successful.
|
||||||
order to isolate the entry to affect only operations within that namespace. This was
|
order to isolate the entry to affect only operations within that namespace. This was
|
||||||
added in Consul 1.7.0.
|
added in Consul 1.7.0.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ consul config write service-defaults.hcl -namespace foo
|
$ consul config write service-defaults.hcl -namespace foo
|
||||||
|
|
@ -145,7 +144,6 @@ api
|
||||||
|
|
||||||
### Bootstrapping From A Configuration File
|
### Bootstrapping From A Configuration File
|
||||||
|
|
||||||
|
|
||||||
Configuration entries can be bootstrapped by adding them [inline to each Consul
|
Configuration entries can be bootstrapped by adding them [inline to each Consul
|
||||||
server's configuration file](/docs/agent/options.html#config_entries). When a
|
server's configuration file](/docs/agent/options.html#config_entries). When a
|
||||||
server gains leadership, it will attempt to initialize the configuration entries.
|
server gains leadership, it will attempt to initialize the configuration entries.
|
||||||
|
|
@ -153,7 +151,6 @@ If a configuration entry does not already exist outside of the servers
|
||||||
configuration, then it will create it. If a configuration entry does exist, that
|
configuration, then it will create it. If a configuration entry does exist, that
|
||||||
matches both `kind` and `name`, then the server will do nothing.
|
matches both `kind` and `name`, then the server will do nothing.
|
||||||
|
|
||||||
|
|
||||||
## Using Configuration Entries For Service Defaults
|
## Using Configuration Entries For Service Defaults
|
||||||
|
|
||||||
When the agent is
|
When the agent is
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "DNS Interface"
|
page_title: 'DNS Interface'
|
||||||
sidebar_current: "docs-agent-dns"
|
sidebar_current: 'docs-agent-dns'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -33,8 +33,8 @@ DNS resolver library and point it at Consul. Another option is to set Consul
|
||||||
as the DNS server for a node and provide a
|
as the DNS server for a node and provide a
|
||||||
[`recursors`](/docs/agent/options.html#recursors) configuration so that non-Consul queries
|
[`recursors`](/docs/agent/options.html#recursors) configuration so that non-Consul queries
|
||||||
can also be resolved. The last method is to forward all queries for the "consul."
|
can also be resolved. The last method is to forward all queries for the "consul."
|
||||||
domain to a Consul agent from the existing DNS server. Review the
|
domain to a Consul agent from the existing DNS server. Review the
|
||||||
[DNS Forwarding guide](https://learn.hashicorp.com/consul/security-networking/forwarding?utm_source=consul.io&utm_medium=docs) for examples.
|
[DNS Forwarding guide](https://learn.hashicorp.com/consul/security-networking/forwarding?utm_source=consul.io&utm_medium=docs) for examples.
|
||||||
|
|
||||||
You can experiment with Consul's DNS server on the command line using tools such as `dig`:
|
You can experiment with Consul's DNS server on the command line using tools such as `dig`:
|
||||||
|
|
||||||
|
|
@ -102,13 +102,13 @@ By default, SRV weights are all set at 1, but changing weights is supported usin
|
||||||
Note that DNS is limited in size per request, even when performing DNS TCP
|
Note that DNS is limited in size per request, even when performing DNS TCP
|
||||||
queries.
|
queries.
|
||||||
|
|
||||||
For services having many instances (more than 500), it might not be possible to
|
For services having many instances (more than 500), it might not be possible to
|
||||||
retrieve the complete list of instances for the service.
|
retrieve the complete list of instances for the service.
|
||||||
|
|
||||||
When DNS SRV response are sent, order is randomized, but weights are not
|
When DNS SRV response are sent, order is randomized, but weights are not
|
||||||
taken into account. In the case of truncation different clients using weighted SRV
|
taken into account. In the case of truncation different clients using weighted SRV
|
||||||
responses will have partial and inconsistent views of instances weights so the
|
responses will have partial and inconsistent views of instances weights so the
|
||||||
request distribution could be skewed from the intended weights. In that case,
|
request distribution could be skewed from the intended weights. In that case,
|
||||||
it is recommended to use the HTTP API to retrieve the list of nodes.
|
it is recommended to use the HTTP API to retrieve the list of nodes.
|
||||||
|
|
||||||
### Standard Lookup
|
### Standard Lookup
|
||||||
|
|
@ -275,7 +275,7 @@ and these will resolve services within the `default` namespace. However, for res
|
||||||
services from other namespaces the following form can be used:
|
services from other namespaces the following form can be used:
|
||||||
|
|
||||||
[tag.]<service>.service.<namespace>.<datacenter>.<domain>
|
[tag.]<service>.service.<namespace>.<datacenter>.<domain>
|
||||||
|
|
||||||
This is the canonical name of a Consul Enterprise service with all parts present. Like
|
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
|
Consul OSS some parts may be omitted but which parts depend on the value of the
|
||||||
[`prefer_namespace` configuration](https://deploy-preview-6909--consul-docs-preview.netlify.com/docs/agent/options.html#dns_prefer_namespace).
|
[`prefer_namespace` configuration](https://deploy-preview-6909--consul-docs-preview.netlify.com/docs/agent/options.html#dns_prefer_namespace).
|
||||||
|
|
@ -284,11 +284,11 @@ With `prefer_namespace` set to `true` the datacenter may be omitted and will be
|
||||||
to the local agents datacenter:
|
to the local agents datacenter:
|
||||||
|
|
||||||
[tag.]<service>.service.<namespace>.<domain>
|
[tag.]<service>.service.<namespace>.<domain>
|
||||||
|
|
||||||
With `prefer_namespace` set to `false` the namespace may be omitted and will be defaulted
|
With `prefer_namespace` set to `false` the namespace may be omitted and will be defaulted
|
||||||
to the `default` namespace:
|
to the `default` namespace:
|
||||||
|
|
||||||
[tag.]<service>.service.<datacenter>
|
[tag.]<service>.service.<datacenter>
|
||||||
|
|
||||||
Finally, both the namespace and datacenter may be omitted and the service will be resolved
|
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.
|
in the `default` namespace and in the datacenter of the local agent.
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Encryption"
|
page_title: 'Encryption'
|
||||||
sidebar_current: "docs-agent-encryption"
|
sidebar_current: 'docs-agent-encryption'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -13,7 +13,7 @@ method of encryption is described on the [encryption internals page](/docs/inter
|
||||||
There are two separate encryption systems, one for gossip traffic and one for RPC.
|
There are two separate encryption systems, one for gossip traffic and one for RPC.
|
||||||
|
|
||||||
To configure the encryption systems on a new cluster, review this following guides to
|
To configure the encryption systems on a new cluster, review this following guides to
|
||||||
[enable gossip encryption](https://learn.hashicorp.com/consul/security-networking/agent-encryption?utm_source=consul.io&utm_medium=docs) and
|
[enable gossip encryption](https://learn.hashicorp.com/consul/security-networking/agent-encryption?utm_source=consul.io&utm_medium=docs) and
|
||||||
[TLS encryption for agent communication](https://learn.hashicorp.com/consul/security-networking/certificates?utm_source=consul.io&utm_medium=docs).
|
[TLS encryption for agent communication](https://learn.hashicorp.com/consul/security-networking/certificates?utm_source=consul.io&utm_medium=docs).
|
||||||
|
|
||||||
## Gossip Encryption
|
## Gossip Encryption
|
||||||
|
|
@ -60,7 +60,7 @@ order to send and receive cluster information.
|
||||||
## Configuring Gossip Encryption on an existing cluster
|
## Configuring Gossip Encryption on an existing cluster
|
||||||
|
|
||||||
As of version 0.8.4, Consul supports upshifting to encrypted gossip on a running cluster
|
As of version 0.8.4, Consul supports upshifting to encrypted gossip on a running cluster
|
||||||
through the following process. Review this [step-by-step guide](https://learn.hashicorp.com/consul/security-networking/agent-encryption#enable-gossip-encryption-existing-cluster)
|
through the following process. Review this [step-by-step guide](https://learn.hashicorp.com/consul/security-networking/agent-encryption#enable-gossip-encryption-existing-cluster)
|
||||||
to encrypt gossip on an existing cluster.
|
to encrypt gossip on an existing cluster.
|
||||||
|
|
||||||
## RPC Encryption with TLS
|
## RPC Encryption with TLS
|
||||||
|
|
@ -69,7 +69,7 @@ Consul supports using TLS to verify the authenticity of servers and clients. To
|
||||||
Consul requires that all clients and servers have key pairs that are generated by a single
|
Consul requires that all clients and servers have key pairs that are generated by a single
|
||||||
Certificate Authority. This can be a private CA, used only internally. The
|
Certificate Authority. This can be a private CA, used only internally. The
|
||||||
CA then signs keys for each of the agents, as in
|
CA then signs keys for each of the agents, as in
|
||||||
[this tutorial on generating both a CA and signing keys](https://learn.hashicorp.com/consul/security-networking/certificates).
|
[this tutorial on generating both a CA and signing keys](https://learn.hashicorp.com/consul/security-networking/certificates).
|
||||||
|
|
||||||
TLS can be used to verify the authenticity of the servers or verify the authenticity of clients.
|
TLS can be used to verify the authenticity of the servers or verify the authenticity of clients.
|
||||||
These modes are controlled by the [`verify_outgoing`](/docs/agent/options.html#verify_outgoing),
|
These modes are controlled by the [`verify_outgoing`](/docs/agent/options.html#verify_outgoing),
|
||||||
|
|
@ -80,8 +80,7 @@ If [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) is set, agents
|
||||||
authenticity of Consul for outgoing connections. Server nodes must present a certificate signed
|
authenticity of Consul for outgoing connections. Server nodes must present a certificate signed
|
||||||
by a common certificate authority present on all agents, set via the agent's
|
by a common certificate authority present on all agents, set via the agent's
|
||||||
[`ca_file`](/docs/agent/options.html#ca_file) and [`ca_path`](/docs/agent/options.html#ca_path)
|
[`ca_file`](/docs/agent/options.html#ca_file) and [`ca_path`](/docs/agent/options.html#ca_path)
|
||||||
options. All server nodes must have an appropriate key pair set using [`cert_file`]
|
options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/options.html#cert_file) and [`key_file`](/docs/agent/options.html#key_file).
|
||||||
(/docs/agent/options.html#cert_file) and [`key_file`](/docs/agent/options.html#key_file).
|
|
||||||
|
|
||||||
If [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname) is set, then
|
If [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname) is set, then
|
||||||
outgoing connections perform hostname verification. All servers must have a certificate
|
outgoing connections perform hostname verification. All servers must have a certificate
|
||||||
|
|
@ -108,5 +107,4 @@ without downtime. This process assumes a starting point with no TLS settings con
|
||||||
an intermediate step in order to get to full TLS encryption. Review the
|
an intermediate step in order to get to full TLS encryption. Review the
|
||||||
[Securing RPC Communication with TLS Encryption guide](https://learn.hashicorp.com/consul/security-networking/certificates)
|
[Securing RPC Communication with TLS Encryption guide](https://learn.hashicorp.com/consul/security-networking/certificates)
|
||||||
for the step-by-step process to configure TLS on a new or existing cluster. Note the call outs there
|
for the step-by-step process to configure TLS on a new or existing cluster. Note the call outs there
|
||||||
for existing cluster configuration.
|
for existing cluster configuration.
|
||||||
|
|
||||||
|
|
@ -1,19 +1,19 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Consul KV"
|
page_title: 'Consul KV'
|
||||||
sidebar_current: "docs-agent-kv"
|
sidebar_current: 'docs-agent-kv'
|
||||||
description: |-
|
description: |-
|
||||||
Consul KV is a core feature of Consul and is installed with the Consul agent.
|
Consul KV is a core feature of Consul and is installed with the Consul agent.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Consul KV
|
# Consul KV
|
||||||
|
|
||||||
Consul KV is a core feature of Consul and is installed with the Consul agent.
|
Consul KV is a core feature of Consul and is installed with the Consul agent.
|
||||||
Once installed with the agent, it will have sane defaults. Consul KV allows
|
Once installed with the agent, it will have sane defaults. Consul KV allows
|
||||||
users to store indexed objects, though its main uses are storing configuration
|
users to store indexed objects, though its main uses are storing configuration
|
||||||
parameters and metadata. Please note that it is a simple KV store and is not
|
parameters and metadata. Please note that it is a simple KV store and is not
|
||||||
intended to be a full featured datastore (such as DynamoDB) but has some
|
intended to be a full featured datastore (such as DynamoDB) but has some
|
||||||
similarities to one.
|
similarities to one.
|
||||||
|
|
||||||
The Consul KV datastore is located on the servers, but can be accessed by any
|
The Consul KV datastore is located on the servers, but can be accessed by any
|
||||||
agent (client or server). The natively integrated [RPC
|
agent (client or server). The natively integrated [RPC
|
||||||
|
|
@ -25,7 +25,7 @@ occurs.
|
||||||
|
|
||||||
If you have not used Consul KV, check out this [Getting Started
|
If you have not used Consul KV, check out this [Getting Started
|
||||||
guide](https://learn.hashicorp.com/consul/getting-started/kv?utm_source=consul.io&utm_medium=docs) on HashiCorp
|
guide](https://learn.hashicorp.com/consul/getting-started/kv?utm_source=consul.io&utm_medium=docs) on HashiCorp
|
||||||
Learn.
|
Learn.
|
||||||
|
|
||||||
## Accessing the KV store
|
## Accessing the KV store
|
||||||
|
|
||||||
|
|
@ -35,16 +35,14 @@ To restrict access, enable and configure
|
||||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
||||||
Once the ACL system has been bootstrapped, users and services, will need a
|
Once the ACL system has been bootstrapped, users and services, will need a
|
||||||
valid token with KV [privileges](/docs/agent/acl-rules.html#key-value-rules) to
|
valid token with KV [privileges](/docs/agent/acl-rules.html#key-value-rules) to
|
||||||
access the the data store, this includes even reads. We recommend creating a
|
access the the data store, this includes even reads. We recommend creating a
|
||||||
token with limited privileges, for example, you could create a token with write
|
token with limited privileges, for example, you could create a token with write
|
||||||
privileges on one key for developers to update the value related to their
|
privileges on one key for developers to update the value related to their
|
||||||
application.
|
application.
|
||||||
|
|
||||||
The datastore itself is located on the Consul servers in the [data
|
The datastore itself is located on the Consul servers in the [data
|
||||||
directory](/docs/agent/options.html#_data_dir). To ensure data is not lost in
|
directory](/docs/agent/options.html#_data_dir). To ensure data is not lost in
|
||||||
the event of a complete outage, use the [`consul
|
the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore.html) feature to backup the data.
|
||||||
snapshot`](/docs/commands/snapshot/restore.html) feature to backup the data.
|
|
||||||
|
|
||||||
|
|
||||||
## Using Consul KV
|
## Using Consul KV
|
||||||
|
|
||||||
|
|
@ -52,18 +50,17 @@ Objects are opaque to Consul, meaning there are no restrictions on the type of
|
||||||
object stored in a key/value entry. The main restriction on an object is size -
|
object stored in a key/value entry. The main restriction on an object is size -
|
||||||
the maximum is 512 KB. Due to the maximum object size and main use cases, you
|
the maximum is 512 KB. Due to the maximum object size and main use cases, you
|
||||||
should not need extra storage; the general [sizing
|
should not need extra storage; the general [sizing
|
||||||
recommendations](/docs/commands/snapshot/restore.html) are usually sufficient.
|
recommendations](/docs/commands/snapshot/restore.html) are usually sufficient.
|
||||||
|
|
||||||
Keys, like objects are not restricted by type and can include any character.
|
Keys, like objects are not restricted by type and can include any character.
|
||||||
However, we recommend using URL-safe chars - `[a-zA-Z0-9-_]` with the
|
However, we recommend using URL-safe chars - `[a-zA-Z0-9-_]` with the
|
||||||
exception of `/`, which can be used to help organize data. Note, `/` will be
|
exception of `/`, which can be used to help organize data. Note, `/` will be
|
||||||
treated like any other character and is not fixed to the file system. Meaning,
|
treated like any other character and is not fixed to the file system. Meaning,
|
||||||
including `/` in a key does not fix it to a directory structure. This model is
|
including `/` in a key does not fix it to a directory structure. This model is
|
||||||
similar to Amazon S3 buckets. However, `/` is still useful for organizing data
|
similar to Amazon S3 buckets. However, `/` is still useful for organizing data
|
||||||
and when recursively searching within the data store. We also recommend that
|
and when recursively searching within the data store. We also recommend that
|
||||||
you avoid the use of `*`, `?`, `'`, and `%` because they can cause issues when
|
you avoid the use of `*`, `?`, `'`, and `%` because they can cause issues when
|
||||||
using the API and in shell scripts.
|
using the API and in shell scripts.
|
||||||
|
|
||||||
|
|
||||||
## Extending Consul KV
|
## Extending Consul KV
|
||||||
|
|
||||||
|
|
@ -74,14 +71,14 @@ review the [Consul
|
||||||
Template](https://learn.hashicorp.com/consul/developer-configuration/consul-template)
|
Template](https://learn.hashicorp.com/consul/developer-configuration/consul-template)
|
||||||
guide on how to update configuration based on value updates in the KV. Consul
|
guide on how to update configuration based on value updates in the KV. Consul
|
||||||
Template is based on Go Templates and allows for a series of scripted actions
|
Template is based on Go Templates and allows for a series of scripted actions
|
||||||
to be initiated on value changes to a Consul key.
|
to be initiated on value changes to a Consul key.
|
||||||
|
|
||||||
### Watches
|
### Watches
|
||||||
|
|
||||||
Consul KV can also be extended with the use of watches.
|
Consul KV can also be extended with the use of watches.
|
||||||
[Watches](/docs/agent/watches.html) are a way to monitor data for updates. When
|
[Watches](/docs/agent/watches.html) are a way to monitor data for updates. When
|
||||||
an update is detected, an external handler is invoked. To use watches with the
|
an update is detected, an external handler is invoked. To use watches with the
|
||||||
KV store the [key](/docs/agent/watches.html#key) watch type should be used.
|
KV store the [key](/docs/agent/watches.html#key) watch type should be used.
|
||||||
|
|
||||||
### Consul Sessions
|
### Consul Sessions
|
||||||
|
|
||||||
|
|
@ -91,9 +88,9 @@ API supports an `acquire` and `release` operation. The `acquire` operation acts
|
||||||
like a Check-And-Set operation. On success, there is a key update and an
|
like a Check-And-Set operation. On success, there is a key update and an
|
||||||
increment to the `LockIndex` and the session value is updated to reflect the
|
increment to the `LockIndex` and the session value is updated to reflect the
|
||||||
session holding the lock. Review the session documentation for more information
|
session holding the lock. Review the session documentation for more information
|
||||||
on the [integration](/docs/internals/sessions.html#k-v-integration).
|
on the [integration](/docs/internals/sessions.html#k-v-integration).
|
||||||
|
|
||||||
Review the following guides to learn how to use Consul sessions for [application leader election](https://learn.hashicorp.com/consul/developer-configuration/elections) and
|
Review the following guides to learn how to use Consul sessions for [application leader election](https://learn.hashicorp.com/consul/developer-configuration/elections) and
|
||||||
to [build distributed semaphores](https://learn.hashicorp.com/consul/developer-configuration/semaphore).
|
to [build distributed semaphores](https://learn.hashicorp.com/consul/developer-configuration/semaphore).
|
||||||
|
|
||||||
### Vault
|
### Vault
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "RPC"
|
page_title: 'RPC'
|
||||||
sidebar_current: "docs-agent-rpc"
|
sidebar_current: 'docs-agent-rpc'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -9,8 +9,8 @@ description: |-
|
||||||
# RPC Protocol
|
# RPC Protocol
|
||||||
|
|
||||||
~> The RPC Protocol is deprecated and support was removed in Consul
|
~> The RPC Protocol is deprecated and support was removed in Consul
|
||||||
0.8. Please use the [HTTP API](/api/index.html), which has
|
0.8. Please use the [HTTP API](/api/index.html), which has
|
||||||
support for all features of the RPC Protocol.
|
support for all features of the RPC Protocol.
|
||||||
|
|
||||||
The Consul agent provides a complete RPC mechanism that can
|
The Consul agent provides a complete RPC mechanism that can
|
||||||
be used to control the agent programmatically. This RPC
|
be used to control the agent programmatically. This RPC
|
||||||
|
|
@ -57,16 +57,16 @@ All responses may be accompanied by an error.
|
||||||
|
|
||||||
Possible commands include:
|
Possible commands include:
|
||||||
|
|
||||||
* handshake - Initializes the connection and sets the version
|
- handshake - Initializes the connection and sets the version
|
||||||
* force-leave - Removes a failed node from the cluster
|
- force-leave - Removes a failed node from the cluster
|
||||||
* join - Requests Consul join another node
|
- join - Requests Consul join another node
|
||||||
* members-lan - Returns the list of LAN members
|
- members-lan - Returns the list of LAN members
|
||||||
* members-wan - Returns the list of WAN members
|
- members-wan - Returns the list of WAN members
|
||||||
* monitor - Starts streaming logs over the connection
|
- monitor - Starts streaming logs over the connection
|
||||||
* stop - Stops streaming logs
|
- stop - Stops streaming logs
|
||||||
* leave - Instructs the Consul agent to perform a graceful leave and shutdown
|
- leave - Instructs the Consul agent to perform a graceful leave and shutdown
|
||||||
* stats - Provides various debugging statistics
|
- stats - Provides various debugging statistics
|
||||||
* reload - Triggers a configuration reload
|
- reload - Triggers a configuration reload
|
||||||
|
|
||||||
Each command is documented below along with any request or
|
Each command is documented below along with any request or
|
||||||
response body that is applicable.
|
response body that is applicable.
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Service Definition"
|
page_title: 'Service Definition'
|
||||||
sidebar_current: "docs-agent-services"
|
sidebar_current: 'docs-agent-services'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -100,7 +100,7 @@ example shows all possible fields, but note that only a few are required.
|
||||||
```
|
```
|
||||||
|
|
||||||
A service definition must include a `name` and may optionally provide an
|
A service definition must include a `name` and may optionally provide an
|
||||||
`id`, `tags`, `address`, `meta`, `port`, `enable_tag_override`, and `check`.
|
`id`, `tags`, `address`, `meta`, `port`, `enable_tag_override`, and `check`.
|
||||||
The `id` is set to the `name` if not provided. It is required that all
|
The `id` is set to the `name` if not provided. It is required that all
|
||||||
services have a unique ID per node, so if names might conflict then
|
services have a unique ID per node, so if names might conflict then
|
||||||
unique IDs should be provided.
|
unique IDs should be provided.
|
||||||
|
|
@ -141,7 +141,7 @@ sync cycle the service's port would revert to the original value but the
|
||||||
tags would maintain the updated value. As a counter example: If an
|
tags would maintain the updated value. As a counter example: If an
|
||||||
external agent modified both the tags and port for this service and
|
external agent modified both the tags and port for this service and
|
||||||
`enable_tag_override` was set to `FALSE` then after the next sync cycle the
|
`enable_tag_override` was set to `FALSE` then after the next sync cycle the
|
||||||
service's port *and* the tags would revert to the original value and all
|
service's port _and_ the tags would revert to the original value and all
|
||||||
modifications would be lost.
|
modifications would be lost.
|
||||||
|
|
||||||
It's important to note that this applies only to the locally registered
|
It's important to note that this applies only to the locally registered
|
||||||
|
|
@ -177,9 +177,9 @@ registered, the ID will be generated as `service:<service-id>:<num>` where
|
||||||
### Proxy
|
### Proxy
|
||||||
|
|
||||||
Service definitions allow for an optional proxy registration. Proxies used with Connect
|
Service definitions allow for an optional proxy registration. Proxies used with Connect
|
||||||
are registered as services in Consul's catalog.
|
are registered as services in Consul's catalog.
|
||||||
See the [Proxy Service Registration](/docs/connect/registration/service-registration.html) reference
|
See the [Proxy Service Registration](/docs/connect/registration/service-registration.html) reference
|
||||||
for the available configuration options.
|
for the available configuration options.
|
||||||
|
|
||||||
### Connect
|
### Connect
|
||||||
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Telemetry"
|
page_title: 'Telemetry'
|
||||||
sidebar_current: "docs-agent-telemetry"
|
sidebar_current: 'docs-agent-telemetry'
|
||||||
description: |-
|
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.
|
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.
|
||||||
---
|
---
|
||||||
|
|
@ -23,9 +23,8 @@ Metrics guide](https://learn.hashicorp.com/consul/day-2-operations/monitoring?ut
|
||||||
Additionally, if the [`telemetry` configuration options](/docs/agent/options.html#telemetry)
|
Additionally, if the [`telemetry` configuration options](/docs/agent/options.html#telemetry)
|
||||||
are provided, the telemetry information will be streamed to a
|
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
|
[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.
|
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).
|
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
|
This
|
||||||
information can also be viewed with the [metrics endpoint](/api/agent.html#view-metrics) in JSON
|
information can also be viewed with the [metrics endpoint](/api/agent.html#view-metrics) in JSON
|
||||||
|
|
@ -57,11 +56,11 @@ These are some metrics emitted that can help you understand the health of your c
|
||||||
|
|
||||||
### Transaction timing
|
### Transaction timing
|
||||||
|
|
||||||
| Metric Name | Description |
|
| Metric Name | Description |
|
||||||
| :----------------------- | :---------- |
|
| :----------------------- | :----------------------------------------------------------------------------------- |
|
||||||
| `consul.kvs.apply` | This measures the time it takes to complete an update to the KV store. |
|
| `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.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.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. |
|
| `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.
|
**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.
|
||||||
|
|
@ -70,11 +69,11 @@ These are some metrics emitted that can help you understand the health of your c
|
||||||
|
|
||||||
### Leadership changes
|
### Leadership changes
|
||||||
|
|
||||||
| Metric Name | Description |
|
| 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.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.candidate` | This increments whenever a Consul server starts an election. |
|
||||||
| `consul.raft.state.leader` | This increments whenever a Consul server becomes a leader. |
|
| `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.
|
**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.
|
||||||
|
|
||||||
|
|
@ -82,8 +81,8 @@ These are some metrics emitted that can help you understand the health of your c
|
||||||
|
|
||||||
### Autopilot
|
### Autopilot
|
||||||
|
|
||||||
| Metric Name | Description |
|
| 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. |
|
| `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.
|
**Why it's important:** Obviously, you want your cluster to be healthy.
|
||||||
|
|
@ -92,8 +91,8 @@ These are some metrics emitted that can help you understand the health of your c
|
||||||
|
|
||||||
### Memory usage
|
### Memory usage
|
||||||
|
|
||||||
| Metric Name | Description |
|
| Metric Name | Description |
|
||||||
| :---------- | :---------- |
|
| :--------------------------- | :----------------------------------------------------------------- |
|
||||||
| `consul.runtime.alloc_bytes` | This measures the number of bytes allocated by the Consul process. |
|
| `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. |
|
| `consul.runtime.sys_bytes` | This is the total number of bytes of memory obtained from the OS. |
|
||||||
|
|
||||||
|
|
@ -103,8 +102,8 @@ These are some metrics emitted that can help you understand the health of your c
|
||||||
|
|
||||||
### Garbage collection
|
### Garbage collection
|
||||||
|
|
||||||
| Metric Name | Description |
|
| Metric Name | Description |
|
||||||
| :---------- | :---------- |
|
| :--------------------------------- | :---------------------------------------------------------------------------------------------------- |
|
||||||
| `consul.runtime.total_gc_pause_ns` | Number of nanoseconds consumed by stop-the-world garbage collection (GC) pauses since Consul started. |
|
| `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.
|
**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.
|
||||||
|
|
@ -116,11 +115,11 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference()
|
||||||
|
|
||||||
### Network activity - RPC Count
|
### Network activity - RPC Count
|
||||||
|
|
||||||
| Metric Name | Description |
|
| 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` | 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.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. |
|
| `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.
|
**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.
|
||||||
|
|
||||||
|
|
@ -1018,7 +1017,6 @@ These metrics give insight into the health of the cluster as a whole.
|
||||||
</tr>
|
</tr>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
|
||||||
## Connect Built-in Proxy Metrics
|
## Connect Built-in Proxy Metrics
|
||||||
|
|
||||||
Consul Connect's built-in proxy is by default configured to log metrics to the
|
Consul Connect's built-in proxy is by default configured to log metrics to the
|
||||||
|
|
@ -1045,7 +1043,6 @@ 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
|
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.
|
out of a given service or the total number of connections between two services.
|
||||||
|
|
||||||
|
|
||||||
### Metrics Reference
|
### Metrics Reference
|
||||||
|
|
||||||
The standard go runtime metrics are exported by `go-metrics` as with Consul
|
The standard go runtime metrics are exported by `go-metrics` as with Consul
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: 'docs'
|
||||||
page_title: "Watches"
|
page_title: 'Watches'
|
||||||
sidebar_current: "docs-agent-watches"
|
sidebar_current: 'docs-agent-watches'
|
||||||
description: |-
|
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 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.
|
||||||
---
|
---
|
||||||
|
|
@ -38,7 +38,7 @@ with invocation info, following a format that depends on the type of the watch.
|
||||||
Each watch type documents the format type. Because they map directly to an HTTP
|
Each watch type documents the format type. Because they map directly to an HTTP
|
||||||
API, handlers should expect the input to match the format of the API. A Consul
|
API, handlers should expect the input to match the format of the API. A Consul
|
||||||
index is also given, corresponding to the responses from the
|
index is also given, corresponding to the responses from the
|
||||||
[HTTP API](/api/index.html).
|
[HTTP API](/api/index.html).
|
||||||
|
|
||||||
### Executable
|
### Executable
|
||||||
|
|
||||||
|
|
@ -97,23 +97,22 @@ Here is an example configuration:
|
||||||
In addition to the parameters supported by each option type, there
|
In addition to the parameters supported by each option type, there
|
||||||
are a few global parameters that all watches support:
|
are a few global parameters that all watches support:
|
||||||
|
|
||||||
* `datacenter` - Can be provided to override the agent's default datacenter.
|
- `datacenter` - Can be provided to override the agent's default datacenter.
|
||||||
* `token` - Can be provided to override the agent's default ACL token.
|
- `token` - Can be provided to override the agent's default ACL token.
|
||||||
* `args` - The handler subprocess and arguments to invoke when the data view updates.
|
- `args` - The handler subprocess and arguments to invoke when the data view updates.
|
||||||
* `handler` - The handler shell command to invoke when the data view updates.
|
- `handler` - The handler shell command to invoke when the data view updates.
|
||||||
|
|
||||||
## Watch Types
|
## Watch Types
|
||||||
|
|
||||||
The following types are supported. Detailed documentation on each is below:
|
The following types are supported. Detailed documentation on each is below:
|
||||||
|
|
||||||
* [`key`](#key) - Watch a specific KV pair
|
- [`key`](#key) - Watch a specific KV pair
|
||||||
* [`keyprefix`](#keyprefix) - Watch a prefix in the KV store
|
- [`keyprefix`](#keyprefix) - Watch a prefix in the KV store
|
||||||
* [`services`](#services) - Watch the list of available services
|
- [`services`](#services) - Watch the list of available services
|
||||||
* [`nodes`](#nodes) - Watch the list of nodes
|
- [`nodes`](#nodes) - Watch the list of nodes
|
||||||
* [`service`](#service)- Watch the instances of a service
|
- [`service`](#service)- Watch the instances of a service
|
||||||
* [`checks`](#checks) - Watch the value of health checks
|
- [`checks`](#checks) - Watch the value of health checks
|
||||||
* [`event`](#event) - Watch for custom user events
|
- [`event`](#event) - Watch for custom user events
|
||||||
|
|
||||||
|
|
||||||
### <a name="key"></a>Type: key
|
### <a name="key"></a>Type: key
|
||||||
|
|
||||||
|
|
@ -154,7 +153,7 @@ An example of the output of this command:
|
||||||
|
|
||||||
The "keyprefix" watch type is used to watch a prefix of keys in the KV store.
|
The "keyprefix" watch type is used to watch a prefix of keys in the KV store.
|
||||||
It requires that the "prefix" parameter be specified. This watch
|
It requires that the "prefix" parameter be specified. This watch
|
||||||
returns *all* keys matching the prefix whenever *any* key matching the prefix
|
returns _all_ keys matching the prefix whenever _any_ key matching the prefix
|
||||||
changes.
|
changes.
|
||||||
|
|
||||||
This maps to the `/v1/kv/` API internally.
|
This maps to the `/v1/kv/` API internally.
|
||||||
|
|
@ -176,34 +175,34 @@ Or, using the watch command:
|
||||||
An example of the output of this command:
|
An example of the output of this command:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
[
|
;[
|
||||||
{
|
{
|
||||||
"Key": "foo/bar",
|
Key: 'foo/bar',
|
||||||
"CreateIndex": 1796,
|
CreateIndex: 1796,
|
||||||
"ModifyIndex": 1796,
|
ModifyIndex: 1796,
|
||||||
"LockIndex": 0,
|
LockIndex: 0,
|
||||||
"Flags": 0,
|
Flags: 0,
|
||||||
"Value": "TU9BUg==",
|
Value: 'TU9BUg==',
|
||||||
"Session": ""
|
Session: '',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Key": "foo/baz",
|
Key: 'foo/baz',
|
||||||
"CreateIndex": 1795,
|
CreateIndex: 1795,
|
||||||
"ModifyIndex": 1795,
|
ModifyIndex: 1795,
|
||||||
"LockIndex": 0,
|
LockIndex: 0,
|
||||||
"Flags": 0,
|
Flags: 0,
|
||||||
"Value": "YXNkZg==",
|
Value: 'YXNkZg==',
|
||||||
"Session": ""
|
Session: '',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Key": "foo/test",
|
Key: 'foo/test',
|
||||||
"CreateIndex": 1793,
|
CreateIndex: 1793,
|
||||||
"ModifyIndex": 1793,
|
ModifyIndex: 1793,
|
||||||
"LockIndex": 0,
|
LockIndex: 0,
|
||||||
"Flags": 0,
|
Flags: 0,
|
||||||
"Value": "aGV5",
|
Value: 'aGV5',
|
||||||
"Session": ""
|
Session: '',
|
||||||
}
|
},
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -234,31 +233,31 @@ This maps to the `/v1/catalog/nodes` API internally.
|
||||||
An example of the output of this command:
|
An example of the output of this command:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
[
|
;[
|
||||||
{
|
{
|
||||||
"Node": "nyc1-consul-1",
|
Node: 'nyc1-consul-1',
|
||||||
"Address": "192.241.159.115"
|
Address: '192.241.159.115',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Node": "nyc1-consul-2",
|
Node: 'nyc1-consul-2',
|
||||||
"Address": "192.241.158.205"
|
Address: '192.241.158.205',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Node": "nyc1-consul-3",
|
Node: 'nyc1-consul-3',
|
||||||
"Address": "198.199.77.133"
|
Address: '198.199.77.133',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Node": "nyc1-worker-1",
|
Node: 'nyc1-worker-1',
|
||||||
"Address": "162.243.162.228"
|
Address: '162.243.162.228',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Node": "nyc1-worker-2",
|
Node: 'nyc1-worker-2',
|
||||||
"Address": "162.243.162.226"
|
Address: '162.243.162.226',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Node": "nyc1-worker-3",
|
Node: 'nyc1-worker-3',
|
||||||
"Address": "162.243.162.229"
|
Address: '162.243.162.229',
|
||||||
}
|
},
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -266,10 +265,10 @@ An example of the output of this command:
|
||||||
|
|
||||||
The "service" watch type is used to monitor the providers
|
The "service" watch type is used to monitor the providers
|
||||||
of a single service. It requires the "service" parameter
|
of a single service. It requires the "service" parameter
|
||||||
and optionally takes the parameters "tag" and
|
and optionally takes the parameters "tag" and
|
||||||
"passingonly". The "tag" parameter will filter by one or more tags.
|
"passingonly". The "tag" parameter will filter by one or more tags.
|
||||||
It may be either a single string value or a slice of strings.
|
It may be either a single string value or a slice of strings.
|
||||||
The "passingonly" is a boolean that will filter to only the
|
The "passingonly" is a boolean that will filter to only the
|
||||||
instances passing all health checks.
|
instances passing all health checks.
|
||||||
|
|
||||||
This maps to the `/v1/health/service` API internally.
|
This maps to the `/v1/health/service` API internally.
|
||||||
|
|
@ -309,44 +308,41 @@ Multiple tag:
|
||||||
An example of the output of this command:
|
An example of the output of this command:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
[
|
;[
|
||||||
{
|
{
|
||||||
"Node": {
|
Node: {
|
||||||
"Node": "foobar",
|
Node: 'foobar',
|
||||||
"Address": "10.1.10.12"
|
Address: '10.1.10.12',
|
||||||
},
|
},
|
||||||
"Service": {
|
Service: {
|
||||||
"ID": "redis",
|
ID: 'redis',
|
||||||
"Service": "redis",
|
Service: 'redis',
|
||||||
"Tags": [
|
Tags: ['bar', 'foo'],
|
||||||
"bar",
|
Port: 8000,
|
||||||
"foo"
|
|
||||||
],
|
|
||||||
"Port": 8000
|
|
||||||
},
|
},
|
||||||
"Checks": [
|
Checks: [
|
||||||
{
|
{
|
||||||
"Node": "foobar",
|
Node: 'foobar',
|
||||||
"CheckID": "service:redis",
|
CheckID: 'service:redis',
|
||||||
"Name": "Service 'redis' check",
|
Name: "Service 'redis' check",
|
||||||
"Status": "passing",
|
Status: 'passing',
|
||||||
"Notes": "",
|
Notes: '',
|
||||||
"Output": "",
|
Output: '',
|
||||||
"ServiceID": "redis",
|
ServiceID: 'redis',
|
||||||
"ServiceName": "redis"
|
ServiceName: 'redis',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"Node": "foobar",
|
Node: 'foobar',
|
||||||
"CheckID": "serfHealth",
|
CheckID: 'serfHealth',
|
||||||
"Name": "Serf Health Status",
|
Name: 'Serf Health Status',
|
||||||
"Status": "passing",
|
Status: 'passing',
|
||||||
"Notes": "",
|
Notes: '',
|
||||||
"Output": "",
|
Output: '',
|
||||||
"ServiceID": "",
|
ServiceID: '',
|
||||||
"ServiceName": ""
|
ServiceName: '',
|
||||||
}
|
},
|
||||||
]
|
],
|
||||||
}
|
},
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue