This commit is contained in:
Jeff Escalante 2020-04-06 16:27:35 -04:00
parent e53b5d2d10
commit 0d9e72f1dc
No known key found for this signature in database
GPG Key ID: 32D23C61AB5450DB
605 changed files with 29419 additions and 15945 deletions

18
website/.editorconfig Normal file
View File

@ -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

4
website/.eslintrc.js Normal file
View File

@ -0,0 +1,4 @@
module.exports = {
...require('@hashicorp/nextjs-scripts/.eslintrc.js'),
ignorePatterns: ['public/'],
}

5
website/.gitignore vendored Normal file
View File

@ -0,0 +1,5 @@
node_modules
.DS_Store
.next
out
.mdx-data

View File

@ -0,0 +1,8 @@
{
"ignore": {
"marked": {
"versions": "0.8.2",
"reason": "IE breaks"
}
}
}

7
website/Dockerfile Normal file
View File

@ -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

View File

@ -1,3 +0,0 @@
source "https://rubygems.org"
gem "middleman-hashicorp", "0.3.44"

View File

@ -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

View File

@ -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

View File

@ -1,21 +1,192 @@
# Consul Website # Consul Website
This subdirectory contains the entire source for the [Consul Website][consul]. [![Netlify Status](https://img.shields.io/netlify/f7fa8963-0022-4a0e-9ccf-f5385355906b?style=flat-square)](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.

5
website/_redirects Normal file
View File

@ -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.

4
website/babel.config.js Normal file
View File

@ -0,0 +1,4 @@
module.exports = {
presets: ['next/babel'],
plugins: ['import-glob-array'],
}

View File

@ -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>
)
}

View File

@ -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;
}
}
}

View File

@ -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
/>
)
}

View File

@ -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

View File

@ -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 []

View File

@ -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 []

View File

@ -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 []

33
website/data/subnav.js Normal file
View File

@ -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',
},
]

1
website/data/version.js Normal file
View File

@ -0,0 +1 @@
export default '1.7.2'

View File

@ -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

36
website/layouts/docs.jsx Normal file
View File

@ -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

35
website/layouts/index.jsx Normal file
View File

@ -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

36
website/layouts/intro.jsx Normal file
View File

@ -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

17
website/lib/bugsnag.js Normal file
View File

@ -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

View File

@ -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");`,
},
],
}

18
website/netlify.toml Normal file
View File

@ -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"

23
website/next.config.js Normal file
View File

@ -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,
},
})

18467
website/package-lock.json generated Normal file

File diff suppressed because it is too large Load Diff

72
website/package.json Normal file
View File

@ -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"
}
}

87
website/pages/_app.js Normal file
View File

@ -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

View File

@ -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>
)
}
}

13
website/pages/_error.jsx Normal file
View File

@ -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 || '¯\\_(ツ)_/¯'} />
}
}

View File

@ -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),

View File

@ -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),

View File

@ -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
} }
] ]
``` ```

View File

@ -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
} }
] ]
``` ```

View File

@ -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.

View File

@ -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"
}
] ]
``` ```

View File

@ -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
}
] ]
``` ```

View File

@ -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
} }
] ]
``` ```

View File

@ -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),

View File

@ -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),

View File

@ -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),

View File

@ -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),

View File

@ -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.

View File

@ -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.

View File

@ -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
```

View File

@ -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.

View File

@ -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),

View File

@ -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"
}
}
}
}
```

View File

@ -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),

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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
}
]
```

View File

@ -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 |

View File

@ -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 dont provide a token in the request, then the agent default token will be used. clients should communicate via TLS. If you dont 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.

View File

@ -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),

View File

@ -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
}
] ]
``` ```

View File

@ -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
}, }
] ]
``` ```

View File

@ -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),

View File

@ -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="
} }
``` ```

View File

@ -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": []
} }
``` ```

View File

@ -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),

View File

@ -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"]
``` ```

View File

@ -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" }
} }
} }
} }

View File

@ -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,

View File

@ -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

View File

@ -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"
]
``` ```

View File

@ -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 |

View File

@ -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.

View File

@ -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

View File

@ -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 |
| ---- | ---- | | ------------------------ | ------------------------------------------- |
| &#9989; Simple | &#10060; May leave many duplicated policies | | &#9989; Simple | &#10060; May leave many duplicated policies |
| &#9989; Easy to automate | &#10060; Policy names not human-readable | | &#9989; Easy to automate | &#10060; 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 |
| ---- | ---- | | ------------------------------------------------- | ------------------------------------------------------------------ |
| &#9989; Clearer, more manageable policies | &#10060; Requires more manual effort | | &#9989; Clearer, more manageable policies | &#10060; Requires more manual effort |
| &#9989; Policies can be re-used by new ACL tokens | &#10060; May take longer for large or complex existing policy sets | | &#9989; Policies can be re-used by new ACL tokens | &#10060; 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

View File

@ -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).

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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)

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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