initial
This commit is contained in:
Jeff Escalante
parent
e53b5d2d10
commit
0d9e72f1dc
|
|
@ -0,0 +1,18 @@
|
|||
# This file is for unifying the coding style for different editors and IDEs
|
||||
# editorconfig.org
|
||||
|
||||
root = true
|
||||
|
||||
[*]
|
||||
end_of_line = lf
|
||||
charset = utf-8
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
|
||||
[Makefile]
|
||||
indent_style = tab
|
||||
|
||||
[{*.md,*.json}]
|
||||
max_line_length = null
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
module.exports = {
|
||||
...require('@hashicorp/nextjs-scripts/.eslintrc.js'),
|
||||
ignorePatterns: ['public/'],
|
||||
}
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
node_modules
|
||||
.DS_Store
|
||||
.next
|
||||
out
|
||||
.mdx-data
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"ignore": {
|
||||
"marked": {
|
||||
"versions": "0.8.2",
|
||||
"reason": "IE breaks"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
FROM node:10.16.3-alpine
|
||||
RUN apk add --update --no-cache git make g++ automake autoconf libtool nasm libpng-dev
|
||||
|
||||
COPY ./package.json /website/package.json
|
||||
COPY ./package-lock.json /website/package-lock.json
|
||||
WORKDIR /website
|
||||
RUN npm install
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
source "https://rubygems.org"
|
||||
|
||||
gem "middleman-hashicorp", "0.3.44"
|
||||
|
|
@ -1,161 +0,0 @@
|
|||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
activesupport (4.2.11.1)
|
||||
i18n (~> 0.7)
|
||||
minitest (~> 5.1)
|
||||
thread_safe (~> 0.3, >= 0.3.4)
|
||||
tzinfo (~> 1.1)
|
||||
autoprefixer-rails (9.7.4)
|
||||
execjs
|
||||
bootstrap-sass (3.4.1)
|
||||
autoprefixer-rails (>= 5.2.1)
|
||||
sassc (>= 2.0.0)
|
||||
builder (3.2.4)
|
||||
capybara (2.4.4)
|
||||
mime-types (>= 1.16)
|
||||
nokogiri (>= 1.3.3)
|
||||
rack (>= 1.0.0)
|
||||
rack-test (>= 0.5.4)
|
||||
xpath (~> 2.0)
|
||||
chunky_png (1.3.11)
|
||||
coffee-script (2.4.1)
|
||||
coffee-script-source
|
||||
execjs
|
||||
coffee-script-source (1.12.2)
|
||||
compass (1.0.3)
|
||||
chunky_png (~> 1.2)
|
||||
compass-core (~> 1.0.2)
|
||||
compass-import-once (~> 1.0.5)
|
||||
rb-fsevent (>= 0.9.3)
|
||||
rb-inotify (>= 0.9)
|
||||
sass (>= 3.3.13, < 3.5)
|
||||
compass-core (1.0.3)
|
||||
multi_json (~> 1.0)
|
||||
sass (>= 3.3.0, < 3.5)
|
||||
compass-import-once (1.0.5)
|
||||
sass (>= 3.2, < 3.5)
|
||||
em-websocket (0.5.1)
|
||||
eventmachine (>= 0.12.9)
|
||||
http_parser.rb (~> 0.6.0)
|
||||
erubis (2.7.0)
|
||||
eventmachine (1.2.7)
|
||||
execjs (2.7.0)
|
||||
ffi (1.12.2)
|
||||
haml (5.1.2)
|
||||
temple (>= 0.8.0)
|
||||
tilt
|
||||
hike (1.2.3)
|
||||
hooks (0.4.1)
|
||||
uber (~> 0.0.14)
|
||||
http_parser.rb (0.6.0)
|
||||
i18n (0.7.0)
|
||||
json (2.3.0)
|
||||
kramdown (1.17.0)
|
||||
listen (3.0.8)
|
||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
||||
rb-inotify (~> 0.9, >= 0.9.7)
|
||||
middleman (3.4.1)
|
||||
coffee-script (~> 2.2)
|
||||
compass (>= 1.0.0, < 2.0.0)
|
||||
compass-import-once (= 1.0.5)
|
||||
execjs (~> 2.0)
|
||||
haml (>= 4.0.5)
|
||||
kramdown (~> 1.2)
|
||||
middleman-core (= 3.4.1)
|
||||
middleman-sprockets (>= 3.1.2)
|
||||
sass (>= 3.4.0, < 4.0)
|
||||
uglifier (~> 2.5)
|
||||
middleman-core (3.4.1)
|
||||
activesupport (~> 4.1)
|
||||
bundler (~> 1.1)
|
||||
capybara (~> 2.4.4)
|
||||
erubis
|
||||
hooks (~> 0.3)
|
||||
i18n (~> 0.7.0)
|
||||
listen (~> 3.0.3)
|
||||
padrino-helpers (~> 0.12.3)
|
||||
rack (>= 1.4.5, < 2.0)
|
||||
thor (>= 0.15.2, < 2.0)
|
||||
tilt (~> 1.4.1, < 2.0)
|
||||
middleman-hashicorp (0.3.44)
|
||||
bootstrap-sass (~> 3.3)
|
||||
builder (~> 3.2)
|
||||
middleman (~> 3.4)
|
||||
middleman-livereload (~> 3.4)
|
||||
middleman-syntax (~> 3.0)
|
||||
redcarpet (~> 3.3)
|
||||
turbolinks (~> 5.0)
|
||||
middleman-livereload (3.4.6)
|
||||
em-websocket (~> 0.5.1)
|
||||
middleman-core (>= 3.3)
|
||||
rack-livereload (~> 0.3.15)
|
||||
middleman-sprockets (3.5.0)
|
||||
middleman-core (>= 3.3)
|
||||
sprockets (~> 2.12.1)
|
||||
sprockets-helpers (~> 1.1.0)
|
||||
sprockets-sass (~> 1.3.0)
|
||||
middleman-syntax (3.2.0)
|
||||
middleman-core (>= 3.2)
|
||||
rouge (~> 3.2)
|
||||
mime-types (3.3.1)
|
||||
mime-types-data (~> 3.2015)
|
||||
mime-types-data (3.2019.1009)
|
||||
mini_portile2 (2.4.0)
|
||||
minitest (5.14.0)
|
||||
multi_json (1.14.1)
|
||||
nokogiri (1.10.9)
|
||||
mini_portile2 (~> 2.4.0)
|
||||
padrino-helpers (0.12.9)
|
||||
i18n (~> 0.6, >= 0.6.7)
|
||||
padrino-support (= 0.12.9)
|
||||
tilt (>= 1.4.1, < 3)
|
||||
padrino-support (0.12.9)
|
||||
activesupport (>= 3.1)
|
||||
rack (1.6.13)
|
||||
rack-livereload (0.3.17)
|
||||
rack
|
||||
rack-test (1.1.0)
|
||||
rack (>= 1.0, < 3)
|
||||
rb-fsevent (0.10.3)
|
||||
rb-inotify (0.10.1)
|
||||
ffi (~> 1.0)
|
||||
redcarpet (3.5.0)
|
||||
rouge (3.16.0)
|
||||
sass (3.4.25)
|
||||
sassc (2.2.1)
|
||||
ffi (~> 1.9)
|
||||
sprockets (2.12.5)
|
||||
hike (~> 1.2)
|
||||
multi_json (~> 1.0)
|
||||
rack (~> 1.0)
|
||||
tilt (~> 1.1, != 1.3.0)
|
||||
sprockets-helpers (1.1.0)
|
||||
sprockets (~> 2.0)
|
||||
sprockets-sass (1.3.1)
|
||||
sprockets (~> 2.0)
|
||||
tilt (~> 1.1)
|
||||
temple (0.8.2)
|
||||
thor (1.0.1)
|
||||
thread_safe (0.3.6)
|
||||
tilt (1.4.1)
|
||||
turbolinks (5.2.1)
|
||||
turbolinks-source (~> 5.2)
|
||||
turbolinks-source (5.2.0)
|
||||
tzinfo (1.2.6)
|
||||
thread_safe (~> 0.1)
|
||||
uber (0.0.15)
|
||||
uglifier (2.7.2)
|
||||
execjs (>= 0.3.0)
|
||||
json (>= 1.8.0)
|
||||
xpath (2.1.0)
|
||||
nokogiri (~> 1.3)
|
||||
|
||||
PLATFORMS
|
||||
ruby
|
||||
|
||||
DEPENDENCIES
|
||||
middleman-hashicorp (= 0.3.44)
|
||||
|
||||
BUNDLED WITH
|
||||
1.17.3
|
||||
|
|
@ -1,33 +1,54 @@
|
|||
VERSION?="0.3.44"
|
||||
|
||||
# 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
|
||||
|
||||
# Default: run this if working on the website locally to run in watch mode.
|
||||
website:
|
||||
@echo "==> Downloading latest Docker image..."
|
||||
@docker pull hashicorp/consul-website
|
||||
@echo "==> Starting website in Docker..."
|
||||
@docker run \
|
||||
--interactive \
|
||||
--rm \
|
||||
--tty \
|
||||
--publish "4567:4567" \
|
||||
--publish "35729:35729" \
|
||||
--workdir "/website" \
|
||||
--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" \
|
||||
hashicorp/middleman-hashicorp:${VERSION}
|
||||
--volume "/website/node_modules" \
|
||||
--publish "3000:3000" \
|
||||
hashicorp/consul-website \
|
||||
npm start
|
||||
|
||||
.PHONY: build website
|
||||
# This command will generate a static version of the website to the "out" folder.
|
||||
build:
|
||||
@echo "==> Downloading latest Docker image..."
|
||||
@docker pull hashicorp/consul-website
|
||||
@echo "==> Starting build in Docker..."
|
||||
@docker run \
|
||||
--interactive \
|
||||
--rm \
|
||||
--tty \
|
||||
--workdir "/website" \
|
||||
--volume "$(shell pwd):/website" \
|
||||
--volume "/website/node_modules" \
|
||||
hashicorp/consul-website \
|
||||
npm run static
|
||||
|
||||
# If you are changing node dependencies locally, run this to generate a new
|
||||
# local Docker image with the dependency changes included.
|
||||
build-image:
|
||||
@echo "==> Building Docker image..."
|
||||
@docker build -t hashicorp-consul-website-local .
|
||||
|
||||
# Use this if you have run `build-image` to use the locally built image
|
||||
# rather than our CI-generated image to test dependency changes.
|
||||
website-local:
|
||||
@echo "==> Starting website in Docker..."
|
||||
@docker run \
|
||||
--interactive \
|
||||
--rm \
|
||||
--tty \
|
||||
--workdir "/website" \
|
||||
--volume "$(shell pwd):/website" \
|
||||
--volume "/website/node_modules" \
|
||||
--publish "3000:3000" \
|
||||
hashicorp-consul-website-local \
|
||||
npm start
|
||||
|
||||
.DEFAULT_GOAL := website
|
||||
.PHONY: build build-image website website-local
|
||||
|
|
|
|||
|
|
@ -1,21 +1,192 @@
|
|||
# Consul Website
|
||||
|
||||
This subdirectory contains the entire source for the [Consul Website][consul].
|
||||
This is a [Middleman][middleman] project, which builds a static site from these
|
||||
source files.
|
||||
[](https://app.netlify.com/sites/consul-docs-platform/deploys)
|
||||
|
||||
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!
|
||||
|
||||
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.
|
||||
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 🚀
|
||||
|
||||
## 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
|
||||
".html" to make them work (in the navigation).
|
||||
### With Docker
|
||||
|
||||
[middleman]: https://www.middlemanapp.com
|
||||
[consul]: https://www.consul.io
|
||||
Running the site locally is simple. Provided you have Docker installed, clone this repo, run `make`, and then visit `http://localhost:3000`.
|
||||
|
||||
The docker image is pre-built with all the website dependencies installed, which is what makes it so quick and simple, but also means if you need to change dependencies and test the changes within Docker, you'll need a new image. If this is something you need to do, you can run `make build-image` to generate a local Docker image with updated dependencies, then `make website-local` to use that image and preview.
|
||||
|
||||
### With Node
|
||||
|
||||
If your local development environment has a supported version (v10.0.0+) of [node installed](https://nodejs.org/en/) you can run:
|
||||
|
||||
- `npm install`
|
||||
- `npm start`
|
||||
|
||||
and then visit `http://localhost:3000`.
|
||||
|
||||
If you pull down new code from github, you should run `npm install` again. Otherwise, there's no need to re-run `npm install` each time the site is run, you can just run `npm start` to get it going.
|
||||
|
||||
## Editing Content
|
||||
|
||||
Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/pages` directory.
|
||||
|
||||
To create a new page with Markdown, create a file ending in `.mdx` in the `pages/` directory. The path in the pages directory will be the URL route. For example, `pages/hello/world.mdx` will be served from the `/hello/world` URL.
|
||||
|
||||
This file can be standard Markdown and also supports [YAML frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is optional, there are defaults for all keys.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: 'My Title'
|
||||
description: "A thorough, yet succinct description of the page's contents"
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
The significant keys in the YAML frontmatter are:
|
||||
|
||||
- `title` `(string)` - This is the title of the page that will be set in the HTML title.
|
||||
- `description` `(string)` - This is a description of the page that will be set in the HTML description.
|
||||
|
||||
> ⚠️Since `api` is a reserved directory within NextJS, all `/api/**` pages are listed under the `/pages/api-docs` path.
|
||||
|
||||
### Editing Sidebars
|
||||
|
||||
The structure of the sidebars are controlled by files in the [`/data` directory](data).
|
||||
|
||||
- Edit [this file](data/docs-navigation.js) to change the **docs** sidebar
|
||||
- Edit [this file](data/guides-navigation.js) to change the **guides** sidebar
|
||||
- Edit [this file](data/intro-navigation.js) to change the **intro** sidebar
|
||||
|
||||
To nest sidebar items, you'll want to add a new `category` key/value accompanied by the appropriate embedded `content` values.
|
||||
|
||||
- `category` values will be **directory names** within the `pages` directory
|
||||
- `content` values will be **file names** within their appropriately nested directory.
|
||||
|
||||
### Creating New Pages
|
||||
|
||||
There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server.
|
||||
|
||||
### Changing the Release Version
|
||||
|
||||
To change the version of Consul displayed for download on the website, head over to `data/version.js` and change the number there. It's important to note that the version number must match a version that has been released and is live on `releases.hashicorp.com` -- if it does not, the website will be unable to fetch links to the binaries and will not compile. So this version number should be changed _only after a release_.
|
||||
|
||||
#### Displaying a Prerelease
|
||||
|
||||
If there is a prerelease of any type that should be displayed on the downloads page, this can be done by editing `pages/downloads/index.jsx`. By default, the download component might look something like this:
|
||||
|
||||
```jsx
|
||||
<ProductDownloader
|
||||
product="Consul"
|
||||
version={VERSION}
|
||||
downloads={downloadData}
|
||||
community="/resources"
|
||||
/>
|
||||
```
|
||||
|
||||
To add a prerelease, an extra `prerelease` property can be added to the component as such:
|
||||
|
||||
```jsx
|
||||
<ProductDownloader
|
||||
product="Consul"
|
||||
version={VERSION}
|
||||
downloads={downloadData}
|
||||
community="/resources"
|
||||
prerelease={{
|
||||
type: 'release candidate', // the type of prerelease: beta, release candidate, etc.
|
||||
name: 'v1.0.0', // the name displayed in text on the website
|
||||
version: '1.0.0-rc1', // the actual version tag that was pushed to releases.hashicorp.com
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
This configuration would display something like the following text on the website, emphasis added to the configurable parameters:
|
||||
|
||||
```
|
||||
A {{ release candidate }} for Consul {{ v1.0.0 }} is available! The release can be <a href='https://releases.hashicorp.com/consul/{{ 1.0.0-rc1 }}'>downloaded here</a>.
|
||||
```
|
||||
|
||||
You may customize the parameters in any way you'd like. To remove a prerelease from the website, simply delete the `prerelease` paremeter from the above component.
|
||||
|
||||
### Markdown Enhancements
|
||||
|
||||
There are several custom markdown plugins that are available by default that enhance standard markdown to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below:
|
||||
|
||||
- If you see the symbols `~>`, `->`, `=>`, or `!>`, these represent [custom alerts](https://github.com/hashicorp/remark-plugins/tree/master/plugins/paragraph-custom-alerts#paragraph-custom-alerts). These render as colored boxes to draw the user's attention to some type of aside.
|
||||
- If you see `@include '/some/path.mdx'`, this is a [markdown include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). It's worth noting as well that all includes resolve from `website/pages/partials` by default.
|
||||
- If you see `# Headline ((#slug))`, this is an example of an [anchor link alias](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-link-aliases). It adds an extra permalink to a headline for compatibility and is removed from the output.
|
||||
- Due to [automatically generated permalinks](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-links), any text changes to _headlines_ or _list items that begin with inline code_ can and will break existing permalinks. Be very cautious when changing either of these two text items.
|
||||
|
||||
Headlines are fairly self-explanitory, but here's an example of how list items that begin with inline code look.
|
||||
|
||||
```markdown
|
||||
- this is a normal list item
|
||||
- `this` is a list item that begins with inline code
|
||||
```
|
||||
|
||||
Its worth noting that _only the inline code at the beginning of the list item_ will cause problems if changed. So if you changed the above markup to...
|
||||
|
||||
```markdown
|
||||
- lsdhfhksdjf
|
||||
- `this` jsdhfkdsjhkdsfjh
|
||||
```
|
||||
|
||||
...while it perhaps would not be an improved user experience, no links would break because of it. The best approach is to **avoid changing headlines and inline code at the start of a list item**. If you must change one of these items, make sure to tag someone from the digital marketing development team on your pull request, they will help to ensure as much compatibility as possible.
|
||||
|
||||
### Redirects
|
||||
|
||||
This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects.
|
||||
|
||||
To add a redirect, head over to the `_redirects` file - the format is fairly simple. On the left is the current path, and on the right is the path that should be redirected to. It's important to note that if there are links to a `.html` version of a page, that must also be explicitly redirected. For example:
|
||||
|
||||
```
|
||||
/foo /bar
|
||||
/foo.html /bar
|
||||
```
|
||||
|
||||
This redirect rule will send all incoming links to `/foo` and `/foo.html` to `/bar`. For more details on the redirects file format, [check out the docs on netlify](https://docs.netlify.com/routing/redirects/rewrites-proxies).
|
||||
|
||||
There are a couple important caveats with redirects. First, redirects are applied at the hosting layer, and therefore will not work by default in local dev mode. To test in local dev mode, you can use [`netlify dev`](https://www.netlify.com/products/dev/), or just push a commit and check using the deploy preview.
|
||||
|
||||
Second, redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly.
|
||||
|
||||
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such:
|
||||
|
||||
```
|
||||
/foo /nested/foo
|
||||
/foo.html /nested/foo
|
||||
```
|
||||
|
||||
Finally, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
|
||||
|
||||
One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-navigation` file. If previously the structure looked like:
|
||||
|
||||
```js
|
||||
{
|
||||
category: 'docs',
|
||||
content: [
|
||||
'foo'
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destnation, we need to slightly change the structure as such:
|
||||
|
||||
```js
|
||||
{
|
||||
category: 'docs',
|
||||
content: [
|
||||
{ title: 'Foo Title', href: 'https://learn.hashicorp.com/vault/foo' }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
As the majority of items in the side nav are internal links, the structure makes it as easy as possible to represent these links. This alternate syntax is the most concise manner than an external link can be represented. External links can be used anywhere within the docs sidenav.
|
||||
|
||||
It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the `_redirects` file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first.
|
||||
|
||||
### Deployment
|
||||
|
||||
This website is hosted on Netlify and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
# REDIRECTS FILE
|
||||
#
|
||||
# See https://www.netlify.com/docs/redirects/ for documentation. Please do not
|
||||
# modify or delete existing redirects without first verifying internally.
|
||||
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
module.exports = {
|
||||
presets: ['next/babel'],
|
||||
plugins: ['import-glob-array'],
|
||||
}
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
import Link from 'next/link'
|
||||
|
||||
export default function Footer({ openConsentManager }) {
|
||||
return (
|
||||
<footer className="g-footer">
|
||||
<div className="g-container">
|
||||
<div className="left">
|
||||
<Link href="/intro">
|
||||
<a>Intro</a>
|
||||
</Link>
|
||||
<Link href="/guides">
|
||||
<a>Guides</a>
|
||||
</Link>
|
||||
<Link href="/docs">
|
||||
<a>Docs</a>
|
||||
</Link>
|
||||
<Link href="/community">
|
||||
<a>Community</a>
|
||||
</Link>
|
||||
<a href="https://hashicorp.com/privacy">Privacy</a>
|
||||
<Link href="/security">
|
||||
<a>Security</a>
|
||||
</Link>
|
||||
<Link href="/files/press-kit.zip">
|
||||
<a>Press Kit</a>
|
||||
</Link>
|
||||
<a onClick={openConsentManager}>Consent Manager</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
)
|
||||
}
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
.g-footer {
|
||||
padding: 25px 0 17px 0;
|
||||
flex-shrink: 0;
|
||||
display: flex;
|
||||
|
||||
& .g-container {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
& a {
|
||||
color: black;
|
||||
opacity: 0.5;
|
||||
transition: opacity 0.25s ease;
|
||||
cursor: pointer;
|
||||
display: inline-block;
|
||||
|
||||
&:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
}
|
||||
|
||||
& .left > a {
|
||||
margin-right: 20px;
|
||||
margin-bottom: 8px;
|
||||
|
||||
&:last-child {
|
||||
margin-right: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
import Subnav from '@hashicorp/react-subnav'
|
||||
import subnavItems from '../../data/subnav'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function ConsulSubnav() {
|
||||
const router = useRouter()
|
||||
return (
|
||||
<Subnav
|
||||
titleLink={{
|
||||
text: 'consul',
|
||||
url: '/',
|
||||
}}
|
||||
ctaLinks={[
|
||||
{ text: 'GitHub', url: 'https://www.github.com/hashicorp/consul' },
|
||||
{ text: 'Download', url: '/downloads' },
|
||||
]}
|
||||
currentPath={router.pathname}
|
||||
menuItemsAlign="right"
|
||||
menuItems={subnavItems}
|
||||
constrainWidth
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
|
@ -1,113 +0,0 @@
|
|||
set :base_url, "https://www.consul.io/"
|
||||
|
||||
activate :hashicorp do |h|
|
||||
h.name = "consul"
|
||||
h.version = "1.7.2"
|
||||
h.github_slug = "hashicorp/consul"
|
||||
end
|
||||
|
||||
# Netlify redirects/headers
|
||||
proxy '_redirects', 'redirects.txt', ignore: true
|
||||
|
||||
helpers do
|
||||
# Returns a segment tracking ID such that local development is not
|
||||
# tracked to production systems.
|
||||
def segmentId()
|
||||
if (ENV['ENV'] == 'production')
|
||||
'IyzLrqXkox5KJ8XL4fo8vTYNGfiKlTCm'
|
||||
else
|
||||
'0EXTgkNx0Ydje2PGXVbRhpKKoe5wtzcE'
|
||||
end
|
||||
end
|
||||
|
||||
# Returns the FQDN of the image URL.
|
||||
#
|
||||
# @param [String] path
|
||||
#
|
||||
# @return [String]
|
||||
def image_url(path)
|
||||
File.join(base_url, image_path(path))
|
||||
end
|
||||
|
||||
# Get the title for the page.
|
||||
#
|
||||
# @param [Middleman::Page] page
|
||||
#
|
||||
# @return [String]
|
||||
def title_for(page)
|
||||
if page && page.data.page_title
|
||||
return "#{page.data.page_title} - Consul by HashiCorp"
|
||||
end
|
||||
|
||||
"Consul by HashiCorp"
|
||||
end
|
||||
|
||||
# Get the description for the page
|
||||
#
|
||||
# @param [Middleman::Page] page
|
||||
#
|
||||
# @return [String]
|
||||
def description_for(page)
|
||||
description = (page.data.description || "Consul by HashiCorp")
|
||||
.gsub('"', '')
|
||||
.gsub(/\n+/, ' ')
|
||||
.squeeze(' ')
|
||||
|
||||
return escape_html(description)
|
||||
end
|
||||
|
||||
# This helps by setting the "active" class for sidebar nav elements
|
||||
# if the YAML frontmatter matches the expected value.
|
||||
def sidebar_current(expected)
|
||||
current = current_page.data.sidebar_current || ""
|
||||
if current.start_with?(expected)
|
||||
return " class=\"active\""
|
||||
else
|
||||
return ""
|
||||
end
|
||||
end
|
||||
|
||||
# Returns the id for this page.
|
||||
# @return [String]
|
||||
def body_id_for(page)
|
||||
if !(name = page.data.sidebar_current).blank?
|
||||
return "page-#{name.strip}"
|
||||
end
|
||||
if page.url == "/" || page.url == "/index.html"
|
||||
return "page-home"
|
||||
end
|
||||
if !(title = page.data.page_title).blank?
|
||||
return title
|
||||
.downcase
|
||||
.gsub('"', '')
|
||||
.gsub(/[^\w]+/, '-')
|
||||
.gsub(/_+/, '-')
|
||||
.squeeze('-')
|
||||
.squeeze(' ')
|
||||
end
|
||||
return ""
|
||||
end
|
||||
|
||||
# Returns the list of classes for this page.
|
||||
# @return [String]
|
||||
def body_classes_for(page)
|
||||
classes = []
|
||||
|
||||
if !(layout = page.data.layout).blank?
|
||||
classes << "layout-#{page.data.layout}"
|
||||
end
|
||||
|
||||
if !(title = page.data.page_title).blank?
|
||||
title = title
|
||||
.downcase
|
||||
.gsub('"', '')
|
||||
.gsub(/[^\w]+/, '-')
|
||||
.gsub(/_+/, '-')
|
||||
.squeeze('-')
|
||||
.squeeze(' ')
|
||||
classes << "page-#{title}"
|
||||
end
|
||||
|
||||
return classes.join(" ")
|
||||
end
|
||||
end
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
// The root folder for this documentation category is `pages/docs`
|
||||
//
|
||||
// - A string refers to the name of a file
|
||||
// - A "category" value refers to the name of a directory
|
||||
// - All directories must have an "index.mdx" file to serve as
|
||||
// the landing page for the category
|
||||
|
||||
export default []
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
// The root folder for this documentation category is `pages/guides`
|
||||
//
|
||||
// - A string refers to the name of a file
|
||||
// - A "category" value refers to the name of a directory
|
||||
// - All directories must have an "index.mdx" file to serve as
|
||||
// the landing page for the category
|
||||
|
||||
export default []
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
// The root folder for this documentation category is `pages/intro`
|
||||
//
|
||||
// - A string refers to the name of a file
|
||||
// - A "category" value refers to the name of a directory
|
||||
// - All directories must have an "index.mdx" file to serve as
|
||||
// the landing page for the category
|
||||
|
||||
export default []
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
export default [
|
||||
{
|
||||
text: 'Intro',
|
||||
url: '/intro',
|
||||
type: 'inbound',
|
||||
},
|
||||
{
|
||||
text: 'Learn',
|
||||
url: 'https://learn.hashicorp.com/consul',
|
||||
type: 'outbound',
|
||||
},
|
||||
{
|
||||
text: 'Docs',
|
||||
url: '/docs',
|
||||
type: 'inbound',
|
||||
},
|
||||
{
|
||||
text: 'API',
|
||||
url: '/api-docs',
|
||||
type: 'inbound',
|
||||
},
|
||||
{
|
||||
text: 'Community',
|
||||
url: '/community',
|
||||
type: 'inbound',
|
||||
},
|
||||
{
|
||||
text: 'Enterprise',
|
||||
url:
|
||||
'https://www.hashicorp.com/products/consul/?utm_source=oss&utm_medium=header-nav&utm_campaign=consul',
|
||||
type: 'outbound',
|
||||
},
|
||||
]
|
||||
|
|
@ -0,0 +1 @@
|
|||
export default '1.7.2'
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/api-docs-navigation.js'
|
||||
import { frontMatter as data } from '../pages/api-docs/**/*.mdx'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
|
||||
function ApiDocsLayoutWrapper(pageMeta) {
|
||||
function ApiDocsLayout(props) {
|
||||
return (
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="consul"
|
||||
head={{
|
||||
is: Head,
|
||||
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||
description: pageMeta.description,
|
||||
siteName: 'Consul by HashiCorp',
|
||||
}}
|
||||
sidenav={{
|
||||
Link,
|
||||
category: 'api-docs',
|
||||
currentPage: props.path,
|
||||
data,
|
||||
order,
|
||||
}}
|
||||
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
ApiDocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||
|
||||
return ApiDocsLayout
|
||||
}
|
||||
|
||||
export default ApiDocsLayoutWrapper
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/docs-navigation.js'
|
||||
import { frontMatter as data } from '../pages/docs/**/*.mdx'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
|
||||
function DocsLayoutWrapper(pageMeta) {
|
||||
function DocsLayout(props) {
|
||||
return (
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="consul"
|
||||
head={{
|
||||
is: Head,
|
||||
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||
description: pageMeta.description,
|
||||
siteName: 'Consul by HashiCorp',
|
||||
}}
|
||||
sidenav={{
|
||||
Link,
|
||||
category: 'docs',
|
||||
currentPage: props.path,
|
||||
data,
|
||||
order,
|
||||
}}
|
||||
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
DocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||
|
||||
return DocsLayout
|
||||
}
|
||||
|
||||
export default DocsLayoutWrapper
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
|
||||
function DocsLayoutWrapper(pageMeta) {
|
||||
function DocsLayout(props) {
|
||||
return (
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="consul"
|
||||
head={{
|
||||
is: Head,
|
||||
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||
description: pageMeta.description,
|
||||
siteName: 'Consul by HashiCorp',
|
||||
}}
|
||||
sidenav={{
|
||||
Link,
|
||||
category: 'docs',
|
||||
currentPage: props.path,
|
||||
data: [],
|
||||
order: [],
|
||||
disableFilter: true,
|
||||
}}
|
||||
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
DocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||
|
||||
return DocsLayout
|
||||
}
|
||||
|
||||
export default DocsLayoutWrapper
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/intro-navigation.js'
|
||||
import { frontMatter as data } from '../pages/intro/**/*.mdx'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
|
||||
function IntroLayoutWrapper(pageMeta) {
|
||||
function IntroLayout(props) {
|
||||
return (
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="consul"
|
||||
head={{
|
||||
is: Head,
|
||||
title: `${pageMeta.page_title} | Consul by HashiCorp`,
|
||||
description: pageMeta.description,
|
||||
siteName: 'Consul by HashiCorp',
|
||||
}}
|
||||
sidenav={{
|
||||
Link,
|
||||
category: 'intro',
|
||||
currentPage: props.path,
|
||||
data,
|
||||
order,
|
||||
}}
|
||||
resourceURL={`https://github.com/hashicorp/consul/blob/master/website/pages/${pageMeta.__resourcePath}`}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
IntroLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
|
||||
|
||||
return IntroLayout
|
||||
}
|
||||
|
||||
export default IntroLayoutWrapper
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
import React from 'react'
|
||||
import bugsnag from '@bugsnag/js'
|
||||
import bugsnagReact from '@bugsnag/plugin-react'
|
||||
|
||||
const apiKey =
|
||||
typeof window === 'undefined'
|
||||
? 'b6c57b27a37e531a5de94f065dd98bc0'
|
||||
: 'de0b822b269aa57b620efd8927e03744'
|
||||
|
||||
const bugsnagClient = bugsnag({
|
||||
apiKey,
|
||||
releaseStage: process.env.NODE_ENV || 'development',
|
||||
})
|
||||
|
||||
bugsnagClient.use(bugsnagReact, React)
|
||||
|
||||
export default bugsnagClient
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
const isProd = process.env.NODE_ENV === 'production'
|
||||
|
||||
const segmentWriteKey = isProd
|
||||
? 'AjXdfmTTk1I9q9dfyePuDFHBrz1tCO3l'
|
||||
: '0EXTgkNx0Ydje2PGXVbRhpKKoe5wtzcE'
|
||||
|
||||
// TODO: refactor into web components
|
||||
let utilityServerRoot = isProd
|
||||
? 'https://util.hashicorp.com'
|
||||
: 'https://hashicorp-web-util-staging.herokuapp.com'
|
||||
|
||||
if (process.env.UTIL_SERVER) {
|
||||
utilityServerRoot = process.env.UTIL_SERVER.replace(/\/$/, '')
|
||||
}
|
||||
|
||||
// Consent manager configuration
|
||||
export default {
|
||||
version: 3,
|
||||
container: '#consent-manager',
|
||||
companyName: 'HashiCorp',
|
||||
privacyPolicyLink: '/privacy',
|
||||
segmentWriteKey: segmentWriteKey,
|
||||
utilServerRoot: utilityServerRoot,
|
||||
segmentServices: [
|
||||
{
|
||||
key: 'googleanalytics',
|
||||
name: 'Google Analytics',
|
||||
description:
|
||||
'Google Analytics is a popular service for tracking web traffic. We use this data to determine what content our users find important so that we can dedicate more resources toward it.',
|
||||
category: 'Analytics',
|
||||
},
|
||||
{
|
||||
name: 'Hotjar',
|
||||
description:
|
||||
'Hotjar is a service that generates heatmaps of where users click on our sites. We use this information to ensure that our site is not confusing, and simple to use and navigate.',
|
||||
category: 'Analytics',
|
||||
},
|
||||
{
|
||||
name: 'LinkedIn Insight Tag',
|
||||
description:
|
||||
'This small script allows us to see how effective our linkedin campaigns are by showing which users have clicked through to our site.',
|
||||
category: 'Analytics',
|
||||
},
|
||||
{
|
||||
name: 'Marketo V2',
|
||||
description:
|
||||
'Marketo is a marketing automation tool that allows us to segment users into different categories based off of their behaviors. We use this information to provide tailored information to users in our email campaigns.',
|
||||
},
|
||||
],
|
||||
categories: [
|
||||
{
|
||||
name: 'Functional',
|
||||
description:
|
||||
'Functional services provide a utility to the website, such as the ability to log in, or to get live support. Disabling any of these scripts will cause that utility to be missing from the site.',
|
||||
},
|
||||
{
|
||||
name: 'Analytics',
|
||||
description:
|
||||
'Analytics services keep track of page traffic and user behavior while browsing the site. We use this data internally to improve the usability and performance of the site. Disabling any of these scripts makes it more difficult for us to understand how our site is being used, and slower to improve it.',
|
||||
},
|
||||
{
|
||||
name: 'Email Marketing',
|
||||
description:
|
||||
'Email Marketing services track user behavior while browsing the site. We use this data internally in our marketing efforts to provide users contextually relevant information based off of their behaviors. Disabling any of these scripts makes it more difficult for us to provide you contextually relevant information.',
|
||||
},
|
||||
],
|
||||
additionalServices: [
|
||||
{
|
||||
name: 'OptinMonster',
|
||||
description:
|
||||
"OptinMonster is a service that we use to show a prompt to sign up for our newsletter if it's perceived that you are interested in our content.",
|
||||
category: 'Functional',
|
||||
body: `var om598c8e3a6e43d,om598c8e3a6e43d_poll=function(){var r=0;return function(n,l){clearInterval(r),r=setInterval(n,l)}}();!function(e,t,n){if(e.getElementById(n)){om598c8e3a6e43d_poll(function(){if(window['om_loaded']){if(!om598c8e3a6e43d){om598c8e3a6e43d=new OptinMonsterApp();return om598c8e3a6e43d.init({"s":"35109.598c8e3a6e43d","staging":0,"dev":0,"beta":0});}}},25);return;}var d=false,o=e.createElement(t);o.id=n,o.src="https://a.optnmstr.com/app/js/api.min.js",o.async=true,o.onload=o.onreadystatechange=function(){if(!d){if(!this.readyState||this.readyState==="loaded"||this.readyState==="complete"){try{d=om_loaded=true;om598c8e3a6e43d=new OptinMonsterApp();om598c8e3a6e43d.init({"s":"35109.598c8e3a6e43d","staging":0,"dev":0,"beta":0});o.onload=o.onreadystatechange=null;}catch(t){}}}};(document.getElementsByTagName("head")[0]||document.documentElement).appendChild(o)}(document,"script","omapi-script");`,
|
||||
},
|
||||
],
|
||||
}
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
|
||||
# This file sets configuration for Netlify
|
||||
# ref: https://www.netlify.com/docs/netlify-toml-reference/
|
||||
|
||||
[build]
|
||||
publish = "out"
|
||||
command = "npm run static"
|
||||
|
||||
[context.production]
|
||||
environment = { HASHI_ENV = "production", NODE_ENV = "production"}
|
||||
|
||||
[context.deploy-preview]
|
||||
environment = { HASHI_ENV = "staging" }
|
||||
|
||||
[[headers]]
|
||||
for = "/*"
|
||||
[headers.values]
|
||||
X-Frame-Options = "SAMEORIGIN"
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
const withHashicorp = require('@hashicorp/nextjs-scripts')
|
||||
const path = require('path')
|
||||
|
||||
module.exports = withHashicorp({
|
||||
defaultLayout: true,
|
||||
transpileModules: ['is-absolute-url', '@hashicorp/react-mega-nav'],
|
||||
mdx: { resolveIncludes: path.join(__dirname, 'pages/partials') },
|
||||
})({
|
||||
experimental: {
|
||||
css: true,
|
||||
modern: true,
|
||||
rewrites: () => [
|
||||
{
|
||||
source: '/api/:path*',
|
||||
destination: '/api-docs/:path*',
|
||||
},
|
||||
],
|
||||
},
|
||||
exportTrailingSlash: true,
|
||||
env: {
|
||||
HASHI_ENV: process.env.HASHI_ENV,
|
||||
},
|
||||
})
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,72 @@
|
|||
{
|
||||
"name": "consul-docs",
|
||||
"description": "Description of your website",
|
||||
"version": "0.0.1",
|
||||
"author": "HashiCorp",
|
||||
"dependencies": {
|
||||
"@bugsnag/js": "^6.5.2",
|
||||
"@bugsnag/plugin-react": "^6.5.0",
|
||||
"@hashicorp/nextjs-scripts": "^6.2.0-9",
|
||||
"@hashicorp/react-alert": "^2.0.0",
|
||||
"@hashicorp/react-button": "^2.1.7",
|
||||
"@hashicorp/react-consent-manager": "^2.0.7",
|
||||
"@hashicorp/react-content": "^3.0.0-0",
|
||||
"@hashicorp/react-docs-page": "^1.0.2",
|
||||
"@hashicorp/react-docs-sidenav": "^3.0.5",
|
||||
"@hashicorp/react-docs-sitemap": "^1.0.0",
|
||||
"@hashicorp/react-footer": "^3.1.12",
|
||||
"@hashicorp/react-global-styles": "^4.1.0",
|
||||
"@hashicorp/react-head": "^0.1.1",
|
||||
"@hashicorp/react-hero": "^3.0.5",
|
||||
"@hashicorp/react-image": "^2.0.1",
|
||||
"@hashicorp/react-inline-svg": "^1.0.0",
|
||||
"@hashicorp/react-mega-nav": "^4.0.1-2",
|
||||
"@hashicorp/react-product-downloader": "^3.0.5",
|
||||
"@hashicorp/react-section-header": "^2.0.0",
|
||||
"@hashicorp/react-subnav": "^3.0.1",
|
||||
"@hashicorp/react-text-and-content": "^4.0.7",
|
||||
"@hashicorp/react-text-split": "^0.2.4",
|
||||
"@hashicorp/react-text-split-with-code": "0.0.7",
|
||||
"@hashicorp/react-text-split-with-image": "^1.2.4",
|
||||
"@hashicorp/react-vertical-text-block-list": "^2.0.1",
|
||||
"babel-plugin-import-glob-array": "^0.2.0",
|
||||
"highlight.js": "^9.18.1",
|
||||
"imagemin-mozjpeg": "^8.0.0",
|
||||
"imagemin-optipng": "^7.1.0",
|
||||
"imagemin-svgo": "^7.1.0",
|
||||
"isomorphic-unfetch": "^3.0.0",
|
||||
"marked": "^0.7.0",
|
||||
"next": "9.3.4",
|
||||
"nprogress": "^0.2.0",
|
||||
"nuka-carousel": "^4.6.6",
|
||||
"react": "^16.13.1",
|
||||
"react-device-detect": "^1.11.14",
|
||||
"react-dom": "^16.13.1",
|
||||
"slugify": "^1.4.0",
|
||||
"stringify-object": "^3.3.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"dart-linkcheck": "^2.0.15",
|
||||
"glob": "^7.1.6",
|
||||
"husky": "^4.2.3",
|
||||
"inquirer": "^7.1.0",
|
||||
"prettier": "^2.0.2"
|
||||
},
|
||||
"husky": {
|
||||
"hooks": {
|
||||
"pre-commit": "next-hashicorp precommit"
|
||||
}
|
||||
},
|
||||
"main": "index.js",
|
||||
"scripts": {
|
||||
"build": "node --max-old-space-size=2048 ./node_modules/.bin/next build",
|
||||
"dynamic": "NODE_ENV=production next build && next start",
|
||||
"export": "node --max-old-space-size=2048 ./node_modules/.bin/next export",
|
||||
"format": "next-hashicorp format",
|
||||
"generate:component": "next-hashicorp generate component",
|
||||
"lint": "next-hashicorp lint",
|
||||
"start": "rm -rf .next/cache/next-babel-loader/ && next dev",
|
||||
"static": "npm run build && npm run export && cp _redirects out/.",
|
||||
"linkcheck": "linkcheck https://consul.io"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
import './style.css'
|
||||
import App from 'next/app'
|
||||
import NProgress from 'nprogress'
|
||||
import Router from 'next/router'
|
||||
import ProductSubnav from '../components/subnav'
|
||||
import MegaNav from '@hashicorp/react-mega-nav'
|
||||
import Footer from '../components/footer'
|
||||
import { ConsentManager, open } from '@hashicorp/react-consent-manager'
|
||||
import consentManagerConfig from '../lib/consent-manager-config'
|
||||
import bugsnagClient from '../lib/bugsnag'
|
||||
import Error from './_error'
|
||||
import Head from 'next/head'
|
||||
import HashiHead from '@hashicorp/react-head'
|
||||
|
||||
Router.events.on('routeChangeStart', NProgress.start)
|
||||
Router.events.on('routeChangeError', NProgress.done)
|
||||
Router.events.on('routeChangeComplete', (url) => {
|
||||
setTimeout(() => window.analytics.page(url), 0)
|
||||
NProgress.done()
|
||||
})
|
||||
|
||||
// Bugsnag
|
||||
const ErrorBoundary = bugsnagClient.getPlugin('react')
|
||||
|
||||
class NextApp extends App {
|
||||
static async getInitialProps({ Component, ctx }) {
|
||||
let pageProps = {}
|
||||
|
||||
if (Component.getInitialProps) {
|
||||
pageProps = await Component.getInitialProps(ctx)
|
||||
} else if (Component.isMDXComponent) {
|
||||
// fix for https://github.com/mdx-js/mdx/issues/382
|
||||
const mdxLayoutComponent = Component({}).props.originalType
|
||||
if (mdxLayoutComponent.getInitialProps) {
|
||||
pageProps = await mdxLayoutComponent.getInitialProps(ctx)
|
||||
}
|
||||
}
|
||||
|
||||
return { pageProps }
|
||||
}
|
||||
|
||||
render() {
|
||||
const { Component, pageProps } = this.props
|
||||
|
||||
return (
|
||||
<ErrorBoundary FallbackComponent={Error}>
|
||||
<HashiHead
|
||||
is={Head}
|
||||
title="Consul by HashiCorp"
|
||||
siteName="Consul by HashiCorp"
|
||||
description="Consul is a free and open source tool for creating golden images for multiple
|
||||
platforms from a single source configuration."
|
||||
image="https://www.consul.io/img/og-image.png"
|
||||
stylesheet={[
|
||||
{ href: '/css/nprogress.css' },
|
||||
{
|
||||
href:
|
||||
'https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700&display=swap',
|
||||
},
|
||||
]}
|
||||
icon={[{ href: '/favicon.ico' }]}
|
||||
preload={[
|
||||
{ href: '/fonts/klavika/medium.woff2', as: 'font' },
|
||||
{ href: '/fonts/gilmer/light.woff2', as: 'font' },
|
||||
{ href: '/fonts/gilmer/regular.woff2', as: 'font' },
|
||||
{ href: '/fonts/gilmer/medium.woff2', as: 'font' },
|
||||
{ href: '/fonts/gilmer/bold.woff2', as: 'font' },
|
||||
{ href: '/fonts/metro-sans/book.woff2', as: 'font' },
|
||||
{ href: '/fonts/metro-sans/regular.woff2', as: 'font' },
|
||||
{ href: '/fonts/metro-sans/semi-bold.woff2', as: 'font' },
|
||||
{ href: '/fonts/metro-sans/bold.woff2', as: 'font' },
|
||||
{ href: '/fonts/dejavu/mono.woff2', as: 'font' },
|
||||
]}
|
||||
/>
|
||||
<MegaNav product="Consul" />
|
||||
<ProductSubnav />
|
||||
<div className="content">
|
||||
<Component {...pageProps} />
|
||||
</div>
|
||||
<Footer openConsentManager={open} />
|
||||
<ConsentManager {...consentManagerConfig} />
|
||||
</ErrorBoundary>
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
export default NextApp
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
import Document, { Head, Main, NextScript } from 'next/document'
|
||||
import HashiHead from '@hashicorp/react-head'
|
||||
|
||||
export default class MyDocument extends Document {
|
||||
static async getInitialProps(ctx) {
|
||||
const initialProps = await Document.getInitialProps(ctx)
|
||||
return { ...initialProps }
|
||||
}
|
||||
|
||||
render() {
|
||||
return (
|
||||
<html>
|
||||
<HashiHead is={Head} />
|
||||
<body>
|
||||
<Main />
|
||||
<NextScript />
|
||||
<script
|
||||
noModule
|
||||
dangerouslySetInnerHTML={{
|
||||
__html: `window.MSInputMethodContext && document.documentMode && document.write('<script src="/ie-custom-properties.js"><\\x2fscript>');`,
|
||||
}}
|
||||
/>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
import React from 'react'
|
||||
import ErrorPage from 'next/error'
|
||||
import bugsnagClient from '../lib/bugsnag'
|
||||
|
||||
export default class Page extends React.Component {
|
||||
static async getInitialProps(ctx) {
|
||||
if (ctx.err) bugsnagClient.notify(ctx.err)
|
||||
return ErrorPage.getInitialProps(ctx)
|
||||
}
|
||||
render() {
|
||||
return <ErrorPage statusCode={this.props.statusCode || '¯\\_(ツ)_/¯'} />
|
||||
}
|
||||
}
|
||||
|
|
@ -27,7 +27,7 @@ This provides a mechanism to bootstrap ACLs without having any secrets present i
|
|||
configuration files.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `PUT` | `/acl/bootstrap` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -70,7 +70,7 @@ ACL system. Please see the
|
|||
This endpoint makes a new ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `PUT` | `/acl/create` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -129,7 +129,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `PUT` | `/acl/update` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -154,7 +154,7 @@ required.
|
|||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||
"Name": "my-app-token-updated",
|
||||
"Type": "client",
|
||||
"Rules": "# New Rules",
|
||||
"Rules": "# New Rules"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -180,7 +180,7 @@ $ curl \
|
|||
This endpoint deletes an ACL token with the given ID.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------- | ------------------ |
|
||||
| `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.
|
||||
|
|
@ -214,13 +214,12 @@ $ curl \
|
|||
true
|
||||
```
|
||||
|
||||
|
||||
## Read ACL Token
|
||||
|
||||
This endpoint reads an ACL token with the given ID.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `GET` | `/acl/info/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -269,7 +268,7 @@ serve as a template for others, making it simple to generate new tokens without
|
|||
complex rule management.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -308,7 +307,7 @@ $ curl \
|
|||
This endpoint lists all the active ACL tokens.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------- | ------------------ |
|
||||
| `GET` | `/acl/list` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -353,7 +352,7 @@ Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-
|
|||
for more details.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `GET` | `/acl/replication` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -27,7 +27,7 @@ This provides a mechanism to bootstrap ACLs without having any secrets present i
|
|||
configuration files.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `PUT` | `/acl/bootstrap` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -92,7 +92,7 @@ Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-
|
|||
for more details.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `GET` | `/acl/replication` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -191,7 +191,7 @@ to be used by operators managing Consul's ACLs and performing legacy token to ne
|
|||
migrations.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | --------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------ |
|
||||
| `POST` | `/acl/rules/translate` | `text/plain` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -238,7 +238,7 @@ Accessor ID of the legacy token. This ID can be retrieved using the
|
|||
[`/v1/acl/token/self`](/api/acl/tokens.html#self) endpoint.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------------- | ------------ |
|
||||
| `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -272,7 +272,7 @@ method](/docs/acl/acl-auth-methods.html) bearer token for a newly-created
|
|||
Consul ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------ | ------------------ |
|
||||
| `POST` | `/acl/login` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -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
|
||||
replication enabled.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login.
|
||||
|
|
@ -363,7 +362,7 @@ via the [login endpoint](#login-to-auth-method). The token deleted is specified
|
|||
with the `X-Consul-Token` header or the `token` query parameter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `POST` | `/acl/logout` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -23,7 +23,7 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
|||
This endpoint creates a new ACL auth method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `PUT` | `/acl/auth-method` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -41,7 +41,6 @@ The table below shows this endpoint's support for
|
|||
- `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The
|
||||
name can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
||||
This field is immutable and must be unique.
|
||||
|
||||
- `Type` `(string: <required>)` - The type of auth method being configured.
|
||||
The only allowed value in Consul 1.5.0 is `"kubernetes"`. This field is
|
||||
immutable.
|
||||
|
|
@ -107,7 +106,7 @@ auth method exists with the given name, a 404 is returned instead of a
|
|||
200 response.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------ | ------------------ |
|
||||
| `GET` | `/acl/auth-method/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -159,7 +158,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube
|
|||
This endpoint updates an existing ACL auth method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------ | ------------------ |
|
||||
| `PUT` | `/acl/auth-method/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -245,7 +244,7 @@ This endpoint deletes an ACL auth method.
|
|||
outstanding [tokens](/api/acl/tokens.html) created from this auth method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------------- | -------------------------- |
|
||||
| -------- | ------------------------ | ------------------ |
|
||||
| `DELETE` | `/acl/auth-method/:name` | `application/json` |
|
||||
|
||||
Even though the return type is application/json, the value is either true or
|
||||
|
|
@ -290,7 +289,7 @@ true
|
|||
This endpoint lists all the ACL auth methods.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/acl/auth-methods` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -309,10 +308,9 @@ The table below shows this endpoint's support for
|
|||
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,
|
||||
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.
|
||||
|
||||
|
||||
## Sample Request
|
||||
|
||||
```sh
|
||||
|
|
@ -23,7 +23,7 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
|||
This endpoint creates a new ACL binding rule.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `PUT` | `/acl/binding-rule` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -136,7 +136,7 @@ binding rule exists with the given ID, a 404 is returned instead of a 200
|
|||
response.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------------- | ------------------ |
|
||||
| `GET` | `/acl/binding-rule/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -160,7 +160,6 @@ The table below shows this endpoint's support for
|
|||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
|
||||
### Sample Request
|
||||
|
||||
```sh
|
||||
|
|
@ -187,7 +186,7 @@ $ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------------- | ------------------ |
|
||||
| `PUT` | `/acl/binding-rule/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -303,7 +302,7 @@ $ curl -X PUT \
|
|||
This endpoint deletes an ACL binding rule.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------------- | -------------------------- |
|
||||
| -------- | ----------------------- | ------------------ |
|
||||
| `DELETE` | `/acl/binding-rule/:id` | `application/json` |
|
||||
|
||||
Even though the return type is application/json, the value is either true or
|
||||
|
|
@ -338,6 +337,7 @@ $ curl -X DELETE \
|
|||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
true
|
||||
```
|
||||
|
|
@ -347,7 +347,7 @@ true
|
|||
This endpoint lists all the ACL binding rules.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------- | ------------------ |
|
||||
| `GET` | `/acl/binding-rules` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -369,7 +369,7 @@ The table below shows this endpoint's support for
|
|||
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,
|
||||
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.
|
||||
|
||||
## Sample Request
|
||||
|
|
@ -21,7 +21,7 @@ For more information about ACLs, please see the [ACL Guide](https://learn.hashic
|
|||
This endpoint makes a new ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `PUT` | `/acl/create` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -80,7 +80,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `PUT` | `/acl/update` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -105,7 +105,7 @@ required.
|
|||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||
"Name": "my-app-token-updated",
|
||||
"Type": "client",
|
||||
"Rules": "# New Rules",
|
||||
"Rules": "# New Rules"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -119,19 +119,19 @@ $ curl \
|
|||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Delete ACL Token
|
||||
|
||||
This endpoint deletes an ACL token with the given ID.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------- | ------------------ |
|
||||
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
|
||||
|
||||
Even though the return type is application/json, the value is either true or
|
||||
|
|
@ -161,6 +161,7 @@ $ curl \
|
|||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
true
|
||||
```
|
||||
|
|
@ -170,7 +171,7 @@ true
|
|||
This endpoint reads an ACL token with the given ID.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `GET` | `/acl/info/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -219,7 +220,7 @@ serve as a template for others, making it simple to generate new tokens without
|
|||
complex rule management.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -258,7 +259,7 @@ $ curl \
|
|||
This endpoint lists all the active ACL tokens.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------- | ------------------ |
|
||||
| `GET` | `/acl/list` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -293,8 +294,6 @@ $ curl \
|
|||
]
|
||||
```
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
|||
This endpoint creates a new ACL policy.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `PUT` | `/acl/policy` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -83,14 +83,11 @@ $ curl -X PUT \
|
|||
"Name": "node-read",
|
||||
"Description": "Grants read access to all node information",
|
||||
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
],
|
||||
"Datacenters": ["dc1"],
|
||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||
"CreateIndex": 14,
|
||||
"ModifyIndex": 14
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Read a Policy
|
||||
|
|
@ -98,7 +95,7 @@ $ curl -X PUT \
|
|||
This endpoint reads an ACL policy with the given ID.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `GET` | `/acl/policy/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -136,9 +133,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9f
|
|||
"Name": "node-read",
|
||||
"Description": "Grants read access to all node information",
|
||||
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
],
|
||||
"Datacenters": ["dc1"],
|
||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||
"CreateIndex": 14,
|
||||
"ModifyIndex": 14
|
||||
|
|
@ -150,7 +145,7 @@ $ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------ | ------------------ |
|
||||
| `GET` | `/acl/policy/name/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -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
|
||||
to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
|
||||
### Sample Request
|
||||
|
||||
```sh
|
||||
|
|
@ -189,9 +183,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/name/node-read
|
|||
"Name": "node-read",
|
||||
"Description": "Grants read access to all node information",
|
||||
"Rules": "node_prefix \"\" { policy = \"read\"}",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
],
|
||||
"Datacenters": ["dc1"],
|
||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||
"CreateIndex": 14,
|
||||
"ModifyIndex": 14
|
||||
|
|
@ -203,7 +195,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policy/name/node-read
|
|||
This endpoint updates an existing ACL policy.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `PUT` | `/acl/policy/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -248,7 +240,7 @@ The table below shows this endpoint's support for
|
|||
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
|
||||
"Name": "register-app-service",
|
||||
"Description": "Grants write permissions necessary to register the 'app' service",
|
||||
"Rules": "service \"app\" { policy = \"write\"}",
|
||||
"Rules": "service \"app\" { policy = \"write\"}"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -279,7 +271,7 @@ $ curl -X PUT \
|
|||
This endpoint deletes an ACL policy.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------------- | -------------------------- |
|
||||
| -------- | ----------------- | ------------------ |
|
||||
| `DELETE` | `/acl/policy/:id` | `application/json` |
|
||||
|
||||
Even though the return type is application/json, the value is either true or
|
||||
|
|
@ -314,6 +306,7 @@ $ curl -X DELETE \
|
|||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
true
|
||||
```
|
||||
|
|
@ -323,7 +316,7 @@ true
|
|||
This endpoint lists all the ACL policies.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------- | ------------------ |
|
||||
| `GET` | `/acl/policies` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
## Sample Request
|
||||
|
|
@ -369,9 +362,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policies
|
|||
},
|
||||
{
|
||||
"CreateIndex": 14,
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
],
|
||||
"Datacenters": ["dc1"],
|
||||
"Description": "Grants read access to all node information",
|
||||
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
|
||||
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
||||
|
|
@ -379,5 +370,4 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/policies
|
|||
"Name": "node-read"
|
||||
}
|
||||
]
|
||||
|
||||
```
|
||||
|
|
@ -21,7 +21,7 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
|||
This endpoint creates a new ACL role.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------- | ------------------ |
|
||||
| `PUT` | `/acl/role` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -39,7 +39,6 @@ The table below shows this endpoint's support for
|
|||
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
|
||||
can contain alphanumeric characters, dashes `-`, and underscores `_`.
|
||||
This name must be unique.
|
||||
|
||||
- `Description` `(string: "")` - Free form human readable description of the role.
|
||||
|
||||
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
||||
|
|
@ -90,9 +89,7 @@ The table below shows this endpoint's support for
|
|||
},
|
||||
{
|
||||
"ServiceName": "db",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
]
|
||||
"Datacenters": ["dc1"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -125,9 +122,7 @@ $ curl -X PUT \
|
|||
},
|
||||
{
|
||||
"ServiceName": "db",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
]
|
||||
"Datacenters": ["dc1"]
|
||||
}
|
||||
],
|
||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||
|
|
@ -142,7 +137,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------- | ------------------ |
|
||||
| `GET` | `/acl/role/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -159,7 +154,6 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
|
||||
read. This is required and is specified as part of the URL path.
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||
the role. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
|
|
@ -191,9 +185,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc3
|
|||
},
|
||||
{
|
||||
"ServiceName": "db",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
]
|
||||
"Datacenters": ["dc1"]
|
||||
}
|
||||
],
|
||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||
|
|
@ -208,7 +200,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `GET` | `/acl/role/name/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -225,7 +217,6 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `name` `(string: <required>)` - Specifies the Name of the ACL role to
|
||||
read. This is required and is specified as part of the URL path.
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||
the role. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
|
|
@ -257,9 +248,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
|
|||
},
|
||||
{
|
||||
"ServiceName": "db",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
]
|
||||
"Datacenters": ["dc1"]
|
||||
}
|
||||
],
|
||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||
|
|
@ -273,7 +262,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
|
|||
This endpoint updates an existing ACL role.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------- | ------------------ |
|
||||
| `PUT` | `/acl/role/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -295,7 +284,6 @@ The table below shows this endpoint's support for
|
|||
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
|
||||
can only contain alphanumeric characters as well as `-` and `_` and must be
|
||||
unique.
|
||||
|
||||
- `Description` `(string: "")` - Free form human readable description of the role.
|
||||
|
||||
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
||||
|
|
@ -371,7 +359,7 @@ $ curl -X PUT \
|
|||
This endpoint deletes an ACL role.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------------- | -------------------------- |
|
||||
| -------- | --------------- | ------------------ |
|
||||
| `DELETE` | `/acl/role/:id` | `application/json` |
|
||||
|
||||
Even though the return type is application/json, the value is either true or
|
||||
|
|
@ -406,6 +394,7 @@ $ curl -X DELETE \
|
|||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
true
|
||||
```
|
||||
|
|
@ -415,7 +404,7 @@ true
|
|||
This endpoint lists all the ACL roles.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------ | ------------------ |
|
||||
| `GET` | `/acl/roles` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -439,7 +428,7 @@ The table below shows this endpoint's support for
|
|||
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,
|
||||
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.
|
||||
|
||||
## Sample Request
|
||||
|
|
@ -482,9 +471,7 @@ $ curl -X GET http://127.0.0.1:8500/v1/acl/roles
|
|||
},
|
||||
{
|
||||
"ServiceName": "db",
|
||||
"Datacenters": [
|
||||
"dc1"
|
||||
]
|
||||
"Datacenters": ["dc1"]
|
||||
}
|
||||
],
|
||||
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
|
||||
|
|
@ -21,7 +21,7 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
|
|||
This endpoint creates a new ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------ | ------------------ |
|
||||
| `PUT` | `/acl/token` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -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.
|
||||
|
||||
- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set
|
||||
will initialize the `ExpirationTime` field to a value of `CreateTime +
|
||||
ExpirationTTL`. This field is not persisted beyond its initial use. Can be
|
||||
will initialize the `ExpirationTime` field to a value of `CreateTime + 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,
|
||||
respectively). This value must be no smaller than 1 minute and no longer than
|
||||
24 hours. Added in Consul 1.5.0.
|
||||
|
|
@ -146,13 +145,12 @@ $ curl -X PUT \
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
## Read a Token
|
||||
|
||||
This endpoint reads an ACL token with the given Accessor ID.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------ | ------------------ |
|
||||
| `GET` | `/acl/token/:AccessorID` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -219,7 +217,7 @@ This endpoint returns the ACL token details that matches the secret ID
|
|||
specified with the `X-Consul-Token` header or the `token` query parameter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `GET` | `/acl/token/self` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -267,13 +265,12 @@ $ curl -H "X-Consul-Token: 6a1253d2-1785-24fd-91c2-f8e78c745511" \
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
## Update a Token
|
||||
|
||||
This endpoint updates an existing ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------ | ------------------ |
|
||||
| `PUT` | `/acl/token/:AccessorID` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -409,7 +406,7 @@ $ curl -X PUT \
|
|||
This endpoint clones an existing ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------ | -------------------------- |
|
||||
| ------ | ------------------------------ | ------------------ |
|
||||
| `PUT` | `/acl/token/:AccessorID/clone` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -439,7 +436,7 @@ The table below shows this endpoint's support for
|
|||
|
||||
```json
|
||||
{
|
||||
"Description": "Clone of Agent token for 'node1'",
|
||||
"Description": "Clone of Agent token for 'node1'"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -485,7 +482,7 @@ $ curl -X PUT \
|
|||
This endpoint deletes an ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------------- | -------------------------- |
|
||||
| -------- | ------------------------ | ------------------ |
|
||||
| `DELETE` | `/acl/token/:AccessorID` | `application/json` |
|
||||
|
||||
Even though the return type is application/json, the value is either true or
|
||||
|
|
@ -520,6 +517,7 @@ $ curl -X DELETE \
|
|||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
true
|
||||
```
|
||||
|
|
@ -529,7 +527,7 @@ true
|
|||
This endpoint lists all the ACL tokens.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `GET` | `/acl/tokens` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
## Sample Request
|
||||
|
|
@ -26,7 +26,7 @@ by agent. The strongly consistent view of nodes is instead provided by
|
|||
`/v1/catalog/nodes`.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `GET` | `/agent/members` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -92,7 +92,7 @@ format will not change in a backwards incompatible way between releases.
|
|||
to change without notice or deprecation.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `GET` | `/agent/self` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -172,7 +172,7 @@ Not all configuration options are reloadable. See the
|
|||
section on the agent options page for details on which options are supported.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------- | ------------------ |
|
||||
| `PUT` | `/agent/reload` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -203,7 +203,7 @@ Maintenance mode is persistent and will be automatically restored on agent
|
|||
restart.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------- | ------------------ |
|
||||
| `PUT` | `/agent/maintenance` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -375,7 +375,7 @@ operation, such as the time taken to serve a request to a specific http endpoint
|
|||
This endpoint streams logs from the local agent until the connection is closed.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `GET` | `/agent/monitor` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -419,7 +419,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `PUT` | `/agent/join/:address` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -459,7 +459,7 @@ graceful manner. This is critical, as in certain situations a non-graceful leave
|
|||
can affect cluster availability.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------- | ------------------ |
|
||||
| `PUT` | `/agent/leave` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -489,17 +489,16 @@ belonging to that node will not be cleaned up. Forcing a node into the `left`
|
|||
state allows its old entries to be removed.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/force-leave/:node` | `application/json` |
|
||||
|
||||
Additionally, by specifying the `prune` flag, a node can be forcibly removed from
|
||||
the list of members entirely.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | --------------------------------------- | -------------------------- |
|
||||
| ------ | -------------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/force-leave/:node?prune` | `application/json` |
|
||||
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/features/blocking.html),
|
||||
[consistency modes](/api/features/consistency.html),
|
||||
|
|
@ -507,7 +506,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------- |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
|
@ -532,7 +531,7 @@ configuration is `true`. When not being persisted, they will need to be reset if
|
|||
is restarted.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | --------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/token/default` | `application/json` |
|
||||
| `PUT` | `/agent/token/agent` | `application/json` |
|
||||
| `PUT` | `/agent/token/agent_master` | `application/json` |
|
||||
|
|
@ -546,7 +545,7 @@ 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
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------------- | -------------------------- |
|
||||
| ------ | ------------------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/token/acl_token` | `application/json` |
|
||||
| `PUT` | `/agent/token/acl_agent_token` | `application/json` |
|
||||
| `PUT` | `/agent/token/acl_agent_master_token` | `application/json` |
|
||||
|
|
@ -24,7 +24,7 @@ there is no leader elected. The agent performs active
|
|||
everything will be in sync within a few seconds.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------- | ------------------ |
|
||||
| `GET` | `/agent/checks` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -72,9 +72,8 @@ $ curl \
|
|||
The filter will be executed against each health check value in the results map with
|
||||
the following selectors and filter operations being supported:
|
||||
|
||||
|
||||
| Selector | Supported Operations |
|
||||
| ------------- | ------------------------------------------------- |
|
||||
| ------------- | -------------------------------------------------- |
|
||||
| `CheckID` | 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 |
|
||||
|
|
@ -92,7 +91,7 @@ HTTP, TCP, or TTL type. The agent is responsible for managing the status of the
|
|||
check and keeping the Catalog in sync.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------------- | ------------------ |
|
||||
| `PUT` | `/agent/check/register` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -167,8 +166,7 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `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
|
||||
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
|
||||
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
|
||||
`critical`. HTTP checks also support SSL. By default, a valid SSL certificate
|
||||
is expected. Certificate verification can be controlled using the
|
||||
`TLSSkipVerify`.
|
||||
|
|
@ -248,7 +246,7 @@ deregistering the check from the catalog. If the check with the provided ID does
|
|||
not exist, no action is taken.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/check/deregister/:check_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -280,7 +278,7 @@ This endpoint is used with a TTL type check to set the status of the check to
|
|||
`passing` and to reset the TTL clock.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/check/pass/:check_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -314,7 +312,7 @@ This endpoint is used with a TTL type check to set the status of the check to
|
|||
`warning` and to reset the TTL clock.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/check/warn/:check_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -348,7 +346,7 @@ This endpoint is used with a TTL type check to set the status of the check to
|
|||
`critical` and to reset the TTL clock.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/check/fail/:check_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -382,7 +380,7 @@ This endpoint is used with a TTL type check to set the status of the check and
|
|||
to reset the TTL clock.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------- | -------------------------- |
|
||||
| ------ | ------------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/check/update/:check_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -31,7 +31,7 @@ response typically occurs in microseconds to impose minimal overhead on the
|
|||
connection attempt.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------------- | ------------------ |
|
||||
| `POST` | `/agent/connect/authorize` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -104,7 +104,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------- | ------------------ |
|
||||
| `GET` | `/agent/connect/ca/roots` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -168,7 +168,7 @@ or the root certificate is being rotated. This blocking behavior allows
|
|||
clients to efficiently wait for certificate rotations.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------------- | ------------------ |
|
||||
| `GET` | `/agent/connect/ca/leaf/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -25,7 +25,7 @@ while there is no leader elected. The agent performs active
|
|||
everything will be in sync within a few seconds.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `GET` | `/agent/services` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -88,7 +88,7 @@ The filter is executed against each value in the service mapping with the
|
|||
following selectors and filter operations being supported:
|
||||
|
||||
| Selector | Supported Operations |
|
||||
| -------------------------------------- | ------------------------------------------------- |
|
||||
| -------------------------------------- | -------------------------------------------------- |
|
||||
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||
| `Connect.Native` | Equal, Not Equal |
|
||||
| `EnableTagOverride` | Equal, Not Equal |
|
||||
|
|
@ -118,7 +118,6 @@ following selectors and filter operations being supported:
|
|||
| `Weights.Passing` | Equal, Not Equal |
|
||||
| `Weights.Warning` | Equal, Not Equal |
|
||||
|
||||
|
||||
## Get Service Configuration
|
||||
|
||||
This endpoint was added in Consul 1.3.0 and returns the full service definition
|
||||
|
|
@ -133,7 +132,7 @@ while there is no leader elected. The agent performs active
|
|||
everything will be in sync within a few seconds.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------------- | ------------------ |
|
||||
| `GET` | `/agent/service/:service_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -143,7 +142,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | -------------- |
|
||||
| ----------------- | ----------------- | ------------- | -------------- |
|
||||
| `YES`<sup>1</sup> | `none` | `none` | `service:read` |
|
||||
|
||||
<sup>1</sup> Supports [hash-based
|
||||
|
|
@ -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:
|
||||
|
||||
| Result | Meaning |
|
||||
| ------ | ----------------------------------------------------------------|
|
||||
| ------ | --------------------------------------------------------------- |
|
||||
| `200` | All healthchecks of every matching service instance are passing |
|
||||
| `400` | Bad parameter (missing service name of id) |
|
||||
| `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:
|
||||
|
||||
* 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
|
||||
* 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)
|
||||
|
||||
|
||||
##### Note
|
||||
|
||||
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)
|
||||
so you have the result for the service only. When requesting
|
||||
|
|
@ -291,9 +290,7 @@ curl localhost:8500/v1/agent/health/service/name/web
|
|||
{
|
||||
"ID": "web2",
|
||||
"Service": "web",
|
||||
"Tags": [
|
||||
"rails"
|
||||
],
|
||||
"Tags": ["rails"],
|
||||
"Address": "",
|
||||
"TaggedAddresses": {
|
||||
"lan": {
|
||||
|
|
@ -320,9 +317,7 @@ curl localhost:8500/v1/agent/health/service/name/web
|
|||
{
|
||||
"ID": "web1",
|
||||
"Service": "web",
|
||||
"Tags": [
|
||||
"rails"
|
||||
],
|
||||
"Tags": ["rails"],
|
||||
"Address": "",
|
||||
"TaggedAddresses": {
|
||||
"lan": {
|
||||
|
|
@ -371,9 +366,7 @@ curl localhost:8500/v1/agent/health/service/id/web2
|
|||
"critical": {
|
||||
"ID": "web2",
|
||||
"Service": "web",
|
||||
"Tags": [
|
||||
"rails"
|
||||
],
|
||||
"Tags": ["rails"],
|
||||
"Address": "",
|
||||
"TaggedAddresses": {
|
||||
"lan": {
|
||||
|
|
@ -418,9 +411,7 @@ curl localhost:8500/v1/agent/health/service/id/web1
|
|||
"passing": {
|
||||
"ID": "web1",
|
||||
"Service": "web",
|
||||
"Tags": [
|
||||
"rails"
|
||||
],
|
||||
"Tags": ["rails"],
|
||||
"Address": "",
|
||||
"TaggedAddresses": {
|
||||
"lan": {
|
||||
|
|
@ -472,7 +463,7 @@ For "connect-proxy" kind services, the `service:write` ACL for the
|
|||
`Proxy.DestinationServiceName` value is also required to register the service.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/service/register` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -600,10 +591,7 @@ For the `Connect` field, the parameters are:
|
|||
{
|
||||
"ID": "redis1",
|
||||
"Name": "redis",
|
||||
"Tags": [
|
||||
"primary",
|
||||
"v1"
|
||||
],
|
||||
"Tags": ["primary", "v1"],
|
||||
"Address": "127.0.0.1",
|
||||
"Port": 8000,
|
||||
"Meta": {
|
||||
|
|
@ -641,7 +629,7 @@ The agent will take care of deregistering the service with the catalog. If there
|
|||
is an associated check, that is also deregistered.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/service/deregister/:service_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -675,7 +663,7 @@ or API queries. This API call is idempotent. Maintenance mode is persistent and
|
|||
will be automatically restored on agent restart.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------------------------- | ------------------ |
|
||||
| `PUT` | `/agent/service/maintenance/:service_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -21,7 +21,7 @@ entries in the catalog. It is usually preferable to instead use the
|
|||
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `PUT` | `/catalog/register` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -31,7 +31,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------- |
|
||||
| ---------------- | ----------------- | ------------- | -------------------------- |
|
||||
| `NO` | `none` | `none` | `node:write,service:write` |
|
||||
|
||||
### Parameters
|
||||
|
|
@ -96,7 +96,6 @@ The table below shows this endpoint's support for
|
|||
the namespace will be inherited from the request's ACL token or will default
|
||||
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`
|
||||
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": {
|
||||
"ID": "redis1",
|
||||
"Service": "redis",
|
||||
"Tags": [
|
||||
"primary",
|
||||
"v1"
|
||||
],
|
||||
"Tags": ["primary", "v1"],
|
||||
"Address": "127.0.0.1",
|
||||
"TaggedAddresses": {
|
||||
"lan": {
|
||||
|
|
@ -154,7 +150,7 @@ and vice versa. A catalog entry can have either, neither, or both.
|
|||
},
|
||||
"Namespace": "default"
|
||||
},
|
||||
"SkipNodeUpdate": false,
|
||||
"SkipNodeUpdate": false
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -176,7 +172,7 @@ entries from the Catalog. It is usually preferable to instead use the
|
|||
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------- | ------------------ |
|
||||
| `PUT` | `/catalog/deregister` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -258,7 +254,7 @@ availability outage. Therefore, it can be used as a simple check to see if any
|
|||
Consul servers are routable.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `GET` | `/catalog/datacenters` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -289,7 +285,7 @@ $ curl \
|
|||
This endpoint and returns the nodes registered in a given datacenter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `GET` | `/catalog/nodes` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -377,13 +373,12 @@ the following selectors and filter operations being supported:
|
|||
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
||||
| `TaggedAddresses.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||
|
||||
|
||||
## List Services
|
||||
|
||||
This endpoint returns the services registered in a given datacenter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/catalog/services` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -425,10 +420,7 @@ $ curl \
|
|||
{
|
||||
"consul": [],
|
||||
"redis": [],
|
||||
"postgresql": [
|
||||
"primary",
|
||||
"secondary"
|
||||
]
|
||||
"postgresql": ["primary", "secondary"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -440,7 +432,7 @@ a given service.
|
|||
This endpoint returns the nodes providing a service in a given datacenter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `GET` | `/catalog/service/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -527,9 +519,7 @@ $ curl \
|
|||
"port": 512
|
||||
}
|
||||
},
|
||||
"ServiceTags": [
|
||||
"tacos"
|
||||
],
|
||||
"ServiceTags": ["tacos"],
|
||||
"ServiceProxy": {
|
||||
"DestinationServiceName": "",
|
||||
"DestinationServiceID": "",
|
||||
|
|
@ -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:
|
||||
|
||||
| Selector | Supported Operations |
|
||||
| --------------------------------------------- | ------------------------------------------------- |
|
||||
| --------------------------------------------- | -------------------------------------------------- |
|
||||
| `Address` | 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 |
|
||||
|
|
@ -649,7 +639,7 @@ register both Connect-capable and incapable services at the same time,
|
|||
so this endpoint may be used to filter only the Connect-capable endpoints.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `GET` | `/catalog/connect/:service` | `application/json` |
|
||||
|
||||
Parameters and response format are the same as
|
||||
|
|
@ -660,7 +650,7 @@ Parameters and response format are the same as
|
|||
This endpoint returns the node's registered services.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------- | ------------------ |
|
||||
| `GET` | `/catalog/node/:node` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -728,16 +718,14 @@ $ curl \
|
|||
"TaggedAddresses": {
|
||||
"lan": {
|
||||
"address": "10.1.10.12",
|
||||
"port": 8000,
|
||||
"port": 8000
|
||||
},
|
||||
"wan": {
|
||||
"address": "198.18.1.2",
|
||||
"port": 80
|
||||
}
|
||||
},
|
||||
"Tags": [
|
||||
"v1"
|
||||
],
|
||||
"Tags": ["v1"],
|
||||
"Meta": {
|
||||
"redis_version": "4.0"
|
||||
},
|
||||
|
|
@ -789,7 +777,7 @@ top level Node object. The following selectors and filter operations are support
|
|||
This endpoint returns the node's registered services.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------ | -------------------------- |
|
||||
| ------ | ------------------------------ | ------------------ |
|
||||
| `GET` | `/catalog/node-services/:node` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -21,7 +21,7 @@ of the configuration entries content.
|
|||
This endpoint creates or updates the given config entry.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------- | ------------------ |
|
||||
| `PUT` | `/config` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -31,7 +31,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------- |
|
||||
| ---------------- | ----------------- | ------------- | ----------------------------------------------- |
|
||||
| `NO` | `none` | `none` | `service:write`<br>`operator:write`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> The ACL required depends on the config entry kind being updated:
|
||||
|
|
@ -60,7 +60,6 @@ The table below shows this endpoint's support for
|
|||
|
||||
### Sample Payload
|
||||
|
||||
|
||||
```javascript
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
|
|
@ -83,7 +82,7 @@ $ curl \
|
|||
This endpoint returns a specific config entry.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------- | ------------------ |
|
||||
| `GET` | `/config/:kind/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -93,13 +92,13 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------- |
|
||||
| ---------------- | ----------------- | ------------- | -------------------------- |
|
||||
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
||||
|
||||
| Config Entry Kind | Required ACL |
|
||||
| ----------------- | ---------------- |
|
||||
| ----------------- | -------------- |
|
||||
| service-defaults | `service:read` |
|
||||
| proxy-defaults | `<none>` |
|
||||
|
||||
|
|
@ -145,7 +144,7 @@ $ curl \
|
|||
This endpoint returns all config entries of the given kind.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------- | ------------------ |
|
||||
| `GET` | `/config/:kind` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -155,13 +154,13 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------- |
|
||||
| ---------------- | ----------------- | ------------- | -------------------------- |
|
||||
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
||||
|
||||
| Config Entry Kind | Required ACL |
|
||||
| ----------------- | ---------------- |
|
||||
| ----------------- | -------------- |
|
||||
| service-defaults | `service:read` |
|
||||
| proxy-defaults | `<none>` |
|
||||
|
||||
|
|
@ -213,7 +212,7 @@ $ curl \
|
|||
This endpoint deletes the given config entry.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| -------- | --------------------- | ------------------ |
|
||||
| `DELETE` | `/config/:kind/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -223,7 +222,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------- |
|
||||
| ---------------- | ----------------- | ------------- | ----------------------------------------------- |
|
||||
| `NO` | `none` | `none` | `service:write`<br>`operator:write`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> The ACL required depends on the config entry kind being deleted:
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -22,7 +22,7 @@ the name and destination, the creation will fail. You must either update the
|
|||
existing intention or delete it prior to creating a new one.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------- | ------------------ |
|
||||
| `POST` | `/connect/intentions` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -32,7 +32,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------- |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
|
|
@ -93,7 +93,7 @@ $ curl \
|
|||
This endpoint reads a specific intention.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -103,7 +103,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | --------------- |
|
||||
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
|
|
@ -149,7 +149,7 @@ $ curl \
|
|||
This endpoint lists all intentions.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------- | ------------------ |
|
||||
| `GET` | `/connect/intentions` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -159,7 +159,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | --------------- |
|
||||
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
|
|
@ -228,7 +228,7 @@ the following selectors and filter operations being supported:
|
|||
This endpoint updates an intention with the given values.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -238,10 +238,9 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
|
||||
|
||||
|
|
@ -277,7 +276,7 @@ $ curl \
|
|||
This endpoint deletes a specific intention.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| -------- | --------------------------- | ------------------ |
|
||||
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -287,10 +286,9 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | --------------- |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
See [Intention Management Permissions](/docs/connect/intentions.html#intention-management-permissions) for more details.
|
||||
|
||||
|
|
@ -317,9 +315,8 @@ This endpoint will work even if the destination service has
|
|||
`intention = "deny"` specifically set, because the resulting API response
|
||||
does not contain any information about the intention itself.
|
||||
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `GET` | `/connect/intentions/check` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -329,7 +326,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | -------------- |
|
||||
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
|
|
@ -366,7 +363,7 @@ This endpoint lists the intentions that match a given source or destination.
|
|||
The intentions in the response are in evaluation order.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------ | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `GET` | `/connect/intentions/match` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -376,7 +373,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | -------------- |
|
||||
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
||||
|
|
@ -26,7 +26,7 @@ its results may vary as requests are handled by different servers in the
|
|||
cluster.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------- | ------------------ |
|
||||
| `GET` | `/coordinate/datacenters` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -78,7 +78,7 @@ This endpoint returns the LAN network coordinates for all nodes in a given
|
|||
datacenter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/coordinate/nodes` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -135,7 +135,7 @@ segment.
|
|||
This endpoint returns the LAN network coordinates for the given node.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------ | ------------------ |
|
||||
| `GET` | `/coordinate/node/:node` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -193,7 +193,7 @@ This endpoint updates the LAN network coordinates for a node in a given
|
|||
datacenter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------- | ------------------ |
|
||||
| `PUT` | `/coordinate/update` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -17,7 +17,7 @@ Consul.
|
|||
This endpoint triggers a new user event.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `PUT` | `/event/fire/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -93,7 +93,7 @@ agent may have a different view of the events. Events are broadcast using the
|
|||
nor do they make a promise of delivery.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `GET` | `/event/list` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -7,7 +7,6 @@ description: |-
|
|||
blocking query is used to wait for a potential change using long polling.
|
||||
---
|
||||
|
||||
|
||||
# Blocking Queries
|
||||
|
||||
Many endpoints in Consul support a feature known as "blocking queries". A
|
||||
|
|
@ -43,7 +42,7 @@ duration.
|
|||
While the mechanism is relatively simple to work with, there are a few edge
|
||||
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),
|
||||
there are several real-world scenarios in
|
||||
which they can go backwards for a given query. Implementations must check
|
||||
|
|
@ -52,12 +51,13 @@ cases that must be handled correctly.
|
|||
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
|
||||
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
|
||||
|
||||
- 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
|
||||
- **Sanity check index is greater than zero**. After the initial request (or a
|
||||
reset as above) the `X-Consul-Index` returned _should_ always be greater than zero. It
|
||||
is a bug in Consul if it is not, however this has happened a few times and can
|
||||
still be triggered on some older Consul versions. It's especially bad because it
|
||||
|
|
@ -68,7 +68,7 @@ cases that must be handled correctly.
|
|||
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
|
||||
- **Rate limit**. The blocking query mechanism is reasonably efficient when updates
|
||||
are relatively rare (order of tens of seconds to minutes between updates). In cases
|
||||
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
|
||||
|
|
@ -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
|
||||
}
|
||||
]
|
||||
```
|
||||
|
|
@ -20,7 +20,7 @@ raw entries.
|
|||
This endpoint returns the checks specific to the node provided on the path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------- | ------------------ |
|
||||
| `GET` | `/health/node/:node` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -115,7 +115,7 @@ This endpoint returns the checks associated with the service provided on the
|
|||
path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------------- | ------------------ |
|
||||
| `GET` | `/health/checks/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -186,7 +186,6 @@ $ curl \
|
|||
The filter will be executed against each health check in the results list with
|
||||
the following selectors and filter operations being supported:
|
||||
|
||||
|
||||
| Selector | Supported Operations |
|
||||
| ------------- | -------------------------------------------------- |
|
||||
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||
|
|
@ -206,7 +205,7 @@ Users can also build in support for dynamic load balancing and other features by
|
|||
incorporating the use of health checks.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------------- | ------------------ |
|
||||
| `GET` | `/health/service/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -398,7 +397,7 @@ register both Connect-capable and incapable services at the same time,
|
|||
so this endpoint may be used to filter only the Connect-capable endpoints.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------------------- | ------------------ |
|
||||
| `GET` | `/health/connect/:service` | `application/json` |
|
||||
|
||||
Parameters and response format are the same as
|
||||
|
|
@ -409,7 +408,7 @@ Parameters and response format are the same as
|
|||
This endpoint returns the checks in the state provided on the path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `GET` | `/health/state/:state` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -493,7 +492,6 @@ $ curl \
|
|||
The filter will be executed against each health check in the results list with
|
||||
the following selectors and filter operations being supported:
|
||||
|
||||
|
||||
| Selector | Supported Operations |
|
||||
| ------------- | -------------------------------------------------- |
|
||||
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||
|
|
@ -21,7 +21,6 @@ This reduces the probability of the
|
|||
token accidentally getting logged or exposed. When using authentication,
|
||||
clients should communicate via TLS. If you don’t provide a token in the request, then the agent default token will be used.
|
||||
|
||||
|
||||
Below is an example using `curl` with `X-Consul-Token`.
|
||||
|
||||
```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.
|
||||
It is not intended to be RFC compliant, merely to use a well-understood string
|
||||
representation of a 128-bit value.
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ 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).
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------- | ------------------ |
|
||||
| `GET` | `/kv/:key` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -71,7 +71,7 @@ The table below shows this endpoint's support for
|
|||
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
|
||||
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.
|
||||
|
||||
### Sample Request
|
||||
|
|
@ -128,11 +128,7 @@ array of strings instead of an array of JSON objects. Listing `/web/` with a `/`
|
|||
separator may return:
|
||||
|
||||
```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
|
||||
|
|
@ -156,7 +152,7 @@ This endpoint updates the value of the specified key. If no key exists at the gi
|
|||
path, the key will be created.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------- | ------------------ |
|
||||
| `PUT` | `/kv/:key` | `application/json` |
|
||||
|
||||
Even though the return type is `application/json`, the value is either `true` or
|
||||
|
|
@ -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
|
||||
session has locked the key.**
|
||||
|
||||
For an example of how to use the lock feature, see the [Leader Election Guide]
|
||||
(https://learn.hashicorp.com/consul/developer-configuration/elections).
|
||||
For an example of how to use the lock feature, see the [Leader Election Guide](https://learn.hashicorp.com/consul/developer-configuration/elections).
|
||||
|
||||
- `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
|
||||
|
|
@ -245,7 +240,7 @@ true
|
|||
This endpoint deletes a single key or all keys sharing a prefix.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| -------- | ---------- | ------------------ |
|
||||
| `DELETE` | `/kv/:key` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -19,7 +19,7 @@ The functionality described here is available only in
|
|||
This endpoint creates a new ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------ | ------------------ |
|
||||
| `PUT` | `/namespace` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -29,7 +29,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ----------------- |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
|
@ -144,7 +144,7 @@ $ curl -X PUT \
|
|||
This endpoint reads a Namespace with the given name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `GET` | `/namespace/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -154,7 +154,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------------------------ |
|
||||
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1<sup> |
|
||||
|
||||
<sup>1</sup> Access can be granted to list the Namespace if the token used when making
|
||||
|
|
@ -213,7 +213,7 @@ $ curl -H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
|||
This endpoint updates a new ACL token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `PUT` | `/namespace/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -223,7 +223,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ----------------- |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
|
@ -343,7 +343,7 @@ field will now be populated with the timestamp of when the Namespace was
|
|||
marked for deletion.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------------- | -------------------------- |
|
||||
| -------- | ------------------ | -------- |
|
||||
| `DELETE` | `/namespace/:name` | N/A |
|
||||
|
||||
This endpoint will return no data. Success or failure is indicated by the status
|
||||
|
|
@ -356,7 +356,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
|
@ -415,7 +415,7 @@ This endpoint lists all the Namespaces. The output will be filtered based on the
|
|||
privileges of the ACL token used for the request.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `GET` | `/namespaces` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -425,7 +425,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
|
||||
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> Access can be granted to list the Namespace if the token used when making
|
||||
|
|
@ -34,7 +34,7 @@ This endpoint creates a new network area and returns its ID if it is created
|
|||
successfully.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `POST` | `/operator/area` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -100,7 +100,7 @@ $ curl \
|
|||
This endpoint lists all network areas.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------- | ------------------ |
|
||||
| `GET` | `/operator/area` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -143,7 +143,7 @@ $ curl \
|
|||
This endpoint updates a network area to the given configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `PUT` | `/operator/area/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -187,7 +187,7 @@ $ curl \
|
|||
This endpoint lists a specific network area.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `GET` | `/operator/area/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -233,7 +233,7 @@ $ curl \
|
|||
This endpoint deletes a specific network area.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| -------- | ---------------------- | ------------------ |
|
||||
| `DELETE` | `/operator/area/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -269,7 +269,7 @@ This endpoint attempts to join the given Consul servers into a specific network
|
|||
area.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `PUT` | `/operator/area/:uuid/join` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -342,7 +342,7 @@ This endpoint provides a listing of the Consul servers present in a specific
|
|||
network area.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------ | -------------------------- |
|
||||
| ------ | ------------------------------ | ------------------ |
|
||||
| `GET` | `/operator/area/:uuid/members` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -386,7 +386,7 @@ $ curl \
|
|||
"Protocol": 2,
|
||||
"Status": "alive",
|
||||
"RTT": 256478
|
||||
},
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ Please see the [Autopilot Guide](https://learn.hashicorp.com/consul/day-2-operat
|
|||
This endpoint retrieves its latest Autopilot configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------------- | ------------------ |
|
||||
| `GET` | `/operator/autopilot/configuration` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -75,7 +75,7 @@ For more information about the Autopilot configuration options, see the
|
|||
This endpoint updates the Autopilot configuration of the cluster.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------------------------- | ------------------ |
|
||||
| `PUT` | `/operator/autopilot/configuration` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -152,7 +152,7 @@ The table below shows this endpoint's support for
|
|||
This endpoint queries the health of the autopilot status.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------------- | ------------------ |
|
||||
| `GET` | `/operator/autopilot/health` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -23,7 +23,7 @@ If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
|
|||
read privileges.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/operator/keyring` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -99,7 +99,7 @@ $ curl \
|
|||
This endpoint installs a new gossip encryption key into the cluster.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `POST` | `/operator/keyring` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -145,7 +145,7 @@ This endpoint changes the primary gossip encryption key. The key must already be
|
|||
installed before this operation can succeed.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `PUT` | `/operator/keyring` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -191,7 +191,7 @@ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------- | ---------------------------- | -------------------------- |
|
||||
| -------- | ------------------- | ------------------ |
|
||||
| `DELETE` | `/operator/keyring` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -20,7 +20,7 @@ The licensing functionality described here is available only in
|
|||
This endpoint gets information about the current license.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/operator/license` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -30,7 +30,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| `NO` | `all` | `none` | `none` |
|
||||
|
||||
### Parameters
|
||||
|
|
@ -82,7 +82,7 @@ This endpoint updates the Consul license and returns some of the
|
|||
license contents as well as any warning messages regarding its validity.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `PUT` | `/operator/license` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -149,7 +149,7 @@ $ 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| -------- | ------------------- | ------------------ |
|
||||
| `DELETE` | `/operator/license` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -20,7 +20,7 @@ more information about Raft consensus protocol and its use.
|
|||
This endpoint reads the current raft configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------ | -------------------------- |
|
||||
| ------ | ------------------------------ | ------------------ |
|
||||
| `GET` | `/operator/raft/configuration` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -118,7 +118,7 @@ If ACLs are enabled, the client will need to supply an ACL Token with `operator`
|
|||
write privileges.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| -------- | --------------------- | ------------------ |
|
||||
| `DELETE` | `/operator/raft/peer` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -27,7 +27,7 @@ Please see the [Network Segments Guide](https://learn.hashicorp.com/consul/day-2
|
|||
This endpoint lists all network areas.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/operator/segment` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -104,6 +104,7 @@ populate the query before it is executed. All of the string fields inside the
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -138,7 +139,7 @@ This endpoint creates a new prepared query and returns its ID if it is created
|
|||
successfully.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------- | ------------------ |
|
||||
| `POST` | `/query` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -226,27 +227,26 @@ The table below shows this endpoint's support for
|
|||
address or the value of the EDNS client IP with the EDNS client IP
|
||||
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
|
||||
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 `!`).
|
||||
|
||||
- `NodeMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
|
||||
* `NodeMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
|
||||
key/value pairs that will be used for filtering the query results to nodes
|
||||
with the given metadata values present.
|
||||
|
||||
- `ServiceMeta` `(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 services
|
||||
with the given metadata values present.
|
||||
|
||||
- `Connect` `(bool: false)` - If true, only [Connect-capable](/docs/connect/index.html) services
|
||||
* `Connect` `(bool: false)` - If true, only [Connect-capable](/docs/connect/index.html) services
|
||||
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
|
||||
* `DNS` `(DNS: nil)` - Specifies DNS configuration
|
||||
|
||||
- `TTL` `(string: "")` - Specifies the TTL duration when query results are
|
||||
served over DNS. If this is specified, it will take precedence over any
|
||||
|
|
@ -299,7 +299,7 @@ $ curl \
|
|||
This endpoint returns a list of all prepared queries.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------- | ------------------ |
|
||||
| `GET` | `/query` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -362,7 +362,7 @@ This endpoint updates an existing prepared query. If no query exists by the
|
|||
given ID, an error is returned.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------- | ------------------ |
|
||||
| `PUT` | `/query/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -402,7 +402,7 @@ This endpoint reads an existing prepared query. If no query exists by the
|
|||
given ID, an error is returned.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | -------------- | ------------------ |
|
||||
| `GET` | `/query/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -442,7 +442,7 @@ This endpoint deletes an existing prepared query. If no query exists by the
|
|||
given ID, an error is returned.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| --------- | ---------------------------- | -------------------------- |
|
||||
| -------- | -------------- | ------------------ |
|
||||
| `DELETE` | `/query/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -478,7 +478,7 @@ This endpoint executes an existing prepared query. If no query exists by the
|
|||
given ID, an error is returned.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `GET` | `/query/:uuid/execute` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -488,7 +488,7 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| ---------------- | ----------------- | ------------- | --------------------- |
|
||||
| `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
|
||||
|
|
@ -581,7 +581,8 @@ $ curl \
|
|||
},
|
||||
"Datacenter": "dc3",
|
||||
"Failovers": 2
|
||||
}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -606,7 +607,7 @@ This endpoint generates a fully-rendered query for a given name, post
|
|||
interpolation.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ---------------------- | ------------------ |
|
||||
| `GET` | `/query/:uuid/explain` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -16,7 +16,7 @@ This endpoint initializes a new session. Sessions must be associated with a
|
|||
node and may be associated with any number of checks.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ----------------- | ------------------ |
|
||||
| `PUT` | `/session/create` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -105,7 +105,7 @@ malformed, an error is returned. If the session UUID does not exist or already
|
|||
expired, a 200 is still returned (the operation is idempotent).
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | -------------------------- |
|
||||
| :----- | :----------------------- | ------------------ |
|
||||
| `PUT` | `/session/destroy/:uuid` | `application/json` |
|
||||
|
||||
Even though the Content-Type is `application/json`, the response is
|
||||
|
|
@ -155,7 +155,7 @@ true
|
|||
This endpoint returns the requested session information.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | -------------------------- |
|
||||
| :----- | :-------------------- | ------------------ |
|
||||
| `GET` | `/session/info/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -197,10 +197,8 @@ $ curl \
|
|||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||
"Name": "test-session",
|
||||
"Node": "raja-laptop-02",
|
||||
"Checks": [
|
||||
"serfHealth"
|
||||
],
|
||||
"LockDelay": 1.5e+10,
|
||||
"Checks": ["serfHealth"],
|
||||
"LockDelay": 1.5e10,
|
||||
"Behavior": "release",
|
||||
"TTL": "30s",
|
||||
"CreateIndex": 1086449,
|
||||
|
|
@ -216,7 +214,7 @@ If the session does not exist, an empty JSON list `[]` is returned.
|
|||
This endpoint returns the active sessions for a given node.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | -------------------------- |
|
||||
| :----- | :-------------------- | ------------------ |
|
||||
| `GET` | `/session/node/:node` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -242,7 +240,7 @@ The table below shows this endpoint's support for
|
|||
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
|
||||
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.
|
||||
|
||||
### Sample Request
|
||||
|
|
@ -260,10 +258,8 @@ $ curl \
|
|||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||
"Name": "test-session",
|
||||
"Node": "raja-laptop-02",
|
||||
"Checks": [
|
||||
"serfHealth"
|
||||
],
|
||||
"LockDelay": 1.5e+10,
|
||||
"Checks": ["serfHealth"],
|
||||
"LockDelay": 1.5e10,
|
||||
"Behavior": "release",
|
||||
"TTL": "30s",
|
||||
"CreateIndex": 1086449,
|
||||
|
|
@ -277,7 +273,7 @@ $ curl \
|
|||
This endpoint returns the list of active sessions.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | -------------------------- |
|
||||
| :----- | :-------------- | ------------------ |
|
||||
| `GET` | `/session/list` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -299,7 +295,7 @@ The table below shows this endpoint's support for
|
|||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to query.
|
||||
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.
|
||||
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.
|
||||
|
||||
### Sample Request
|
||||
|
|
@ -317,10 +313,8 @@ $ curl \
|
|||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||
"Name": "test-session",
|
||||
"Node": "raja-laptop-02",
|
||||
"Checks": [
|
||||
"serfHealth"
|
||||
],
|
||||
"LockDelay": 1.5e+10,
|
||||
"Checks": ["serfHealth"],
|
||||
"LockDelay": 1.5e10,
|
||||
"Behavior": "release",
|
||||
"TTL": "30s",
|
||||
"CreateIndex": 1086449,
|
||||
|
|
@ -335,7 +329,7 @@ This endpoint renews the given session. This is used with sessions that have a
|
|||
TTL, and it extends the expiration by the TTL.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | -------------------------- |
|
||||
| :----- | :--------------------- | ------------------ |
|
||||
| `PUT` | `/session/renew/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -378,10 +372,8 @@ $ curl \
|
|||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
||||
"Name": "test-session",
|
||||
"Node": "raja-laptop-02",
|
||||
"Checks": [
|
||||
"serfHealth"
|
||||
],
|
||||
"LockDelay": 1.5e+10,
|
||||
"Checks": ["serfHealth"],
|
||||
"LockDelay": 1.5e10,
|
||||
"Behavior": "release",
|
||||
"TTL": "15s",
|
||||
"CreateIndex": 1086449,
|
||||
|
|
@ -27,7 +27,7 @@ restore operations. The archives are not designed to be modified before a
|
|||
restore.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | -------------------------- |
|
||||
| :----- | :---------- | ------------------------ |
|
||||
| `GET` | `/snapshot` | `200 application/x-gzip` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -82,7 +82,7 @@ The body of the request should be a snapshot archive returned from a previous
|
|||
call to the `GET` method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | ----------------------------- |
|
||||
| :----- | :---------- | ----------------------------- |
|
||||
| `PUT` | `/snapshot` | `200 text/plain (empty body)` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -94,6 +94,7 @@ The table below shows this endpoint's support for
|
|||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| `NO` | `none` | `none` | `management` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default
|
||||
|
|
@ -20,7 +20,7 @@ This endpoint returns the Raft leader for the datacenter in which the agent is
|
|||
running.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | ---------------------- |
|
||||
| :----- | :--------------- | ------------------ |
|
||||
| `GET` | `/status/leader` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -58,7 +58,7 @@ is running. This list of peers is strongly consistent and can be useful in
|
|||
determining when a given server has successfully joined the cluster.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :----- | :--------------------------- | ---------------------- |
|
||||
| :----- | :-------------- | ------------------ |
|
||||
| `GET` | `/status/peers` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -86,9 +86,5 @@ $ curl http://127.0.0.1:8500/v1/status/peers
|
|||
### Sample Response
|
||||
|
||||
```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"]
|
||||
```
|
||||
|
|
@ -31,7 +31,7 @@ consistency query parameters will be ignored, since writes are always managed by
|
|||
the leader via the Raft consensus protocol.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| ------ | ------ | ------------------ |
|
||||
| `PUT` | `/txn` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
|
|
@ -41,8 +41,8 @@ The table below shows this endpoint's support for
|
|||
[required ACLs](/api/index.html#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------ |
|
||||
| `NO` | `all`<sup>1</sup> | `none` | `key:read,key:write`<br>`node:read,node:write`<br>`service:read,service:write`<sup>2</sup>
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `NO` | `all`<sup>1</sup> | `none` | `key:read,key:write`<br>`node:read,node:write`<br>`service:read,service:write`<sup>2</sup> |
|
||||
|
||||
<sup>1</sup> For read-only transactions
|
||||
<br>
|
||||
|
|
@ -103,6 +103,7 @@ The table below shows this endpoint's support for
|
|||
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.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
The body of the request should be a list of operations to perform inside the
|
||||
|
|
@ -257,7 +258,7 @@ 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):
|
||||
|
||||
| Verb | Operation | Key | Value | Flags | Index | Session |
|
||||
| ------------------ | -------------------------------------------- | :--: | :---: | :---: | :---: | :-----: |
|
||||
| ------------------ | --------------------------------------- | :-: | :---: | :---: | :---: | :-----: |
|
||||
| `set` | Sets the `Key` to the given `Value` | `x` | `x` | `o` | | |
|
||||
| `cas` | Sets, but with CAS semantics | `x` | `x` | `o` | `x` | |
|
||||
| `lock` | Lock with the given `Session` | `x` | `x` | `o` | | `x` |
|
||||
|
|
@ -277,7 +278,7 @@ Node operations act on an individual node and require either a Node ID or name,
|
|||
to the ID if both are set. Delete operations will not return a result on success.
|
||||
|
||||
| Verb | Operation |
|
||||
| ------------------ | -------------------------------------------- |
|
||||
| ------------ | -------------------------------------------------------- |
|
||||
| `set` | Sets the node to the given state |
|
||||
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
||||
| `get` | Get the node, fails if it does not exist |
|
||||
|
|
@ -290,7 +291,7 @@ Service operations act on an individual service instance on the given node name.
|
|||
and valid service name are required. Delete operations will not return a result on success.
|
||||
|
||||
| Verb | Operation |
|
||||
| ------------------ | -------------------------------------------- |
|
||||
| ------------ | -------------------------------------------------------- |
|
||||
| `set` | Sets the service to the given state |
|
||||
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
||||
| `get` | Get the service, fails if it does not exist |
|
||||
|
|
@ -303,7 +304,7 @@ Check operations act on an individual health check instance on the given node na
|
|||
and valid check ID are required. Delete operations will not return a result on success.
|
||||
|
||||
| Verb | Operation |
|
||||
| ------------------ | -------------------------------------------- |
|
||||
| ------------ | -------------------------------------------------------- |
|
||||
| `set` | Sets the health check to the given state |
|
||||
| `cas` | Sets, but with CAS semantics using the given ModifyIndex |
|
||||
| `get` | Get the check, fails if it does not exist |
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "ACL Auth Methods"
|
||||
sidebar_current: "docs-acl-auth-methods"
|
||||
layout: 'docs'
|
||||
page_title: 'ACL Auth Methods'
|
||||
sidebar_current: 'docs-acl-auth-methods'
|
||||
description: |-
|
||||
An auth method is a component in Consul that performs authentication against a trusted external party to authorize the creation of an ACL tokens usable within the local datacenter.
|
||||
---
|
||||
|
|
@ -39,16 +39,15 @@ service mesh with minimal operator intervention.
|
|||
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.
|
||||
|
||||
* **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
|
||||
validation of application credentials will return a set of trusted identity
|
||||
attributes (such as a username). These can be managed with the `consul acl
|
||||
auth-method` subcommands or the corresponding [API
|
||||
attributes (such as a username). These can be managed with the `consul acl auth-method` subcommands or the corresponding [API
|
||||
endpoints](/api/acl/auth-methods.html). The specific details of
|
||||
configuration are type dependent and described in their own documentation
|
||||
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
|
||||
privileges assigned to the ACL token that is created. These can be managed
|
||||
with the `consul acl binding-rule` subcommands or the corresponding [API
|
||||
|
|
@ -1,12 +1,11 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "ACL System (Legacy Mode)"
|
||||
sidebar_current: "docs-acl-legacy"
|
||||
layout: 'docs'
|
||||
page_title: 'ACL System (Legacy Mode)'
|
||||
sidebar_current: 'docs-acl-legacy'
|
||||
description: |-
|
||||
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
|
||||
---
|
||||
|
||||
|
||||
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system.html)
|
||||
|
||||
# ACL System in Legacy Mode
|
||||
|
|
@ -15,7 +14,6 @@ description: |-
|
|||
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 legacy documentation has two sections.
|
||||
|
||||
- The [New ACL System Differences](#new-acl-system-differences) section
|
||||
|
|
@ -84,7 +82,6 @@ The new ACL system includes new API endpoints to manage
|
|||
the [ACL System](/api/acl/acl.html), [Tokens](/api/acl/tokens.html)
|
||||
and [Policies](/api/acl/policies.html).
|
||||
|
||||
|
||||
# Legacy ACL System
|
||||
|
||||
~> **Warning**: In this document we use the deprecated
|
||||
|
|
@ -138,14 +135,14 @@ The following table summarizes the ACL policies that are available for construct
|
|||
rules:
|
||||
|
||||
| Policy | Scope |
|
||||
| ------------------------ | ----- |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [`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) |
|
||||
| [`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) |
|
||||
| [`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) |
|
||||
| [`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) |
|
||||
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
||||
|
||||
|
|
@ -197,7 +194,7 @@ ACLs are configured using several different configuration options. These are mar
|
|||
as to whether they are set on servers, clients, or both.
|
||||
|
||||
| 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_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 |
|
||||
|
|
@ -211,7 +208,7 @@ A number of special tokens can also be configured which allow for bootstrapping
|
|||
system, or accessing Consul in special situations:
|
||||
|
||||
| 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_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 |
|
||||
|
|
@ -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
|
||||
dispositions:
|
||||
|
||||
* `read`: allow the resource to be read but not modified
|
||||
* `write`: allow the resource to be read and modified
|
||||
* `deny`: do not allow the resource to be read or modified
|
||||
- `read`: allow the resource to be read but not modified
|
||||
- `write`: allow the resource to be read and modified
|
||||
- `deny`: do not allow the resource to be read or modified
|
||||
|
||||
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
|
||||
|
|
@ -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
|
||||
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
|
||||
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`.
|
||||
|
|
@ -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
|
||||
here, with examples:
|
||||
|
||||
* Static queries with no `Name` defined are not controlled by any ACL policies.
|
||||
- Static queries with no `Name` defined are not controlled by any ACL policies.
|
||||
These types of queries are meant to be ephemeral and not shared to untrusted
|
||||
clients, and they are only reachable if the prepared query ID is known. Since
|
||||
these IDs are generated using the same random ID scheme as ACL Tokens, it is
|
||||
|
|
@ -945,7 +942,7 @@ here, with examples:
|
|||
startup script, tied to a session, and written to a configuration file for a
|
||||
process to use via DNS.
|
||||
|
||||
* Static queries with a `Name` defined are controlled by the `query` 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
|
||||
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
|
||||
|
|
@ -955,7 +952,7 @@ here, with examples:
|
|||
that is used and known by many clients to provide geo-failover behavior for
|
||||
a database.
|
||||
|
||||
* [Template queries](/api/query.html#templates)
|
||||
- [Template queries](/api/query.html#templates)
|
||||
queries work like static queries with a `Name` defined, except that a catch-all
|
||||
template with an empty `Name` requires an ACL token that can write to any query
|
||||
prefix.
|
||||
|
|
@ -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
|
||||
check:
|
||||
|
||||
* If an ACL Token was captured when the prepared query was defined, it will be
|
||||
- If an ACL Token was captured when the prepared query was defined, it will be
|
||||
used to perform the service lookup. This allows queries to be executed by
|
||||
clients with lesser or even no ACL Token, so this should be used with care.
|
||||
|
||||
* If no ACL Token was captured, then the client's ACL Token will be used to
|
||||
- If no ACL Token was captured, then the client's ACL Token will be used to
|
||||
perform the service lookup.
|
||||
|
||||
* If no ACL Token was captured and the client has no ACL Token, then the
|
||||
- If no ACL Token was captured and the client has no ACL Token, then the
|
||||
anonymous token will be used to perform the service lookup.
|
||||
|
||||
In the common case, the ACL Token of the invoker is used
|
||||
|
|
@ -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)
|
||||
set to `true` in order to enable script checks.
|
||||
|
||||
|
||||
#### Session Rules
|
||||
|
||||
The `session` policy controls access to [Session API](/api/session.html) operations.
|
||||
|
|
@ -1112,6 +1108,7 @@ name that starts with "admin".
|
|||
## Advanced Topics
|
||||
|
||||
<a name="replication"></a>
|
||||
|
||||
#### Outages and ACL Replication
|
||||
|
||||
The Consul ACL system is designed with flexible rules to accommodate for an outage
|
||||
|
|
@ -1171,10 +1168,11 @@ endpoint.
|
|||
`acl_datacenter` servers to itself. This will automatically turn off
|
||||
replication and will enable the datacenter to start acting as the authoritative
|
||||
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.
|
||||
|
||||
<a name="version_8_acls"></a>
|
||||
|
||||
#### Complete ACL Coverage in Consul 0.8
|
||||
|
||||
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:
|
||||
|
||||
* 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
|
||||
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.
|
||||
* 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
|
||||
to service discovery, so provides an additional dimension for controlling access to
|
||||
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.
|
||||
* 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.
|
||||
* 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.
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "ACL Token Migration"
|
||||
sidebar_current: "docs-acl-migrate-tokens"
|
||||
layout: 'docs'
|
||||
page_title: 'ACL Token Migration'
|
||||
sidebar_current: 'docs-acl-migrate-tokens'
|
||||
description: |-
|
||||
Consul 1.4.0 introduces a new ACL system with improvements for the security and
|
||||
management of ACL tokens and policies. This guide documents how to upgrade
|
||||
|
|
@ -81,12 +81,11 @@ have.
|
|||
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
|
||||
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
|
||||
acl policy create`](/docs/commands/acl/policy/create.html) command with
|
||||
managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/docs/commands/acl/policy/create.html) command with
|
||||
`-from-token` option.
|
||||
|
||||
| Pros | Cons |
|
||||
| ---- | ---- |
|
||||
| ------------------------ | ------------------------------------------- |
|
||||
| ✅ Simple | ❌ May leave many duplicated policies |
|
||||
| ✅ Easy to automate | ❌ Policy names not human-readable |
|
||||
|
||||
|
|
@ -111,11 +110,10 @@ semantics of the old ACL system.
|
|||
|
||||
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
|
||||
equivalent. See [`consul acl
|
||||
translate-rules`](/docs/commands/acl/translate-rules.html).
|
||||
equivalent. See [`consul acl translate-rules`](/docs/commands/acl/translate-rules.html).
|
||||
|
||||
| Pros | Cons |
|
||||
| ---- | ---- |
|
||||
| ------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| ✅ Clearer, more manageable policies | ❌ Requires more manual effort |
|
||||
| ✅ Policies can be re-used by new ACL tokens | ❌ May take longer for large or complex existing policy sets |
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "ACL System"
|
||||
sidebar_current: "docs-acl-system"
|
||||
layout: 'docs'
|
||||
page_title: 'ACL System'
|
||||
sidebar_current: 'docs-acl-system'
|
||||
description: |-
|
||||
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
|
||||
---
|
||||
|
|
@ -22,28 +22,28 @@ 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.
|
||||
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.
|
||||
|
||||
* **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
|
||||
make requests to Consul.
|
||||
|
||||
For many scenarios policies and tokens are sufficient, but more advanced setups
|
||||
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
|
||||
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
|
||||
Connect](/docs/connect/index.html). At authorization time this acts like an
|
||||
additional policy was attached, the contents of which are described further
|
||||
below. These are directly attached to tokens and roles and are not
|
||||
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).
|
||||
|
||||
ACL tokens, policies, roles, auth methods, and binding rules are managed by
|
||||
|
|
@ -58,22 +58,22 @@ If the ACL system becomes inoperable, you can follow the
|
|||
|
||||
An ACL policy is a named set of rules and is composed of the following elements:
|
||||
|
||||
* **ID** - The policy's auto-generated public identifier.
|
||||
* **Name** - A unique meaningful name for the policy.
|
||||
* **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.
|
||||
* **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)
|
||||
- **ID** - The policy's auto-generated public identifier.
|
||||
- **Name** - A unique meaningful name for the policy.
|
||||
- **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.
|
||||
- **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)
|
||||
|
||||
-> **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
|
||||
|
||||
* **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
|
||||
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)
|
||||
|
||||
### 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
|
||||
on both tokens and roles and are composed of the following elements:
|
||||
|
||||
* **Service Name** - The name of the service.
|
||||
* **Datacenters** - A list of datacenters the effective policy is valid within. (Optional)
|
||||
- **Service Name** - The name of the service.
|
||||
- **Datacenters** - A list of datacenters the effective policy is valid within. (Optional)
|
||||
|
||||
Services participating in the service mesh will need privileges to both _be
|
||||
discovered_ and to _discover other healthy service instances_. Suitable
|
||||
|
|
@ -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
|
||||
of the following elements:
|
||||
|
||||
* **ID** - The role's auto-generated public identifier.
|
||||
* **Name** - A unique meaningful name for the role.
|
||||
* **Description** - A human readable description of the role. (Optional)
|
||||
* **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.
|
||||
* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
|
||||
- **ID** - The role's auto-generated public identifier.
|
||||
- **Name** - A unique meaningful name for the role.
|
||||
- **Description** - A human readable description of the role. (Optional)
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
|
|
@ -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
|
||||
elements:
|
||||
|
||||
* **Accessor ID** - The token's public identifier.
|
||||
* **Secret ID** -The bearer token used when making requests to Consul.
|
||||
* **Description** - A human readable description of the token. (Optional)
|
||||
* **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)
|
||||
* **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
|
||||
- **Accessor ID** - The token's public identifier.
|
||||
- **Secret ID** -The bearer token used when making requests to Consul.
|
||||
- **Description** - A human readable description of the token. (Optional)
|
||||
- **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)
|
||||
- **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
|
||||
the primary datacenter and globally replicated.
|
||||
* **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)
|
||||
- **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)
|
||||
|
||||
-> **Consul Enterprise Namespacing** - Tokens may only link to policies and roles defined in the same namespace as
|
||||
the token itself.
|
||||
|
|
@ -160,11 +160,11 @@ the token itself.
|
|||
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `master` token will be
|
||||
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,
|
||||
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
|
||||
set to the value of the configuration entry.
|
||||
|
||||
|
|
@ -196,7 +196,7 @@ The following table summarizes the ACL resources that are available for construc
|
|||
rules:
|
||||
|
||||
| Resource | Scope |
|
||||
| ------------------------ | ----- |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [`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 |
|
||||
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
|
||||
|
|
@ -204,7 +204,7 @@ rules:
|
|||
| [`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) |
|
||||
| [`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) |
|
||||
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
||||
|
||||
|
|
@ -235,7 +235,7 @@ ACLs are configured using several different configuration options. These are mar
|
|||
as to whether they are set on servers, clients, or both.
|
||||
|
||||
| Configuration Option | Servers | Clients | Purpose |
|
||||
| -------------------- | ------- | ------- | ------- |
|
||||
| ------------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- |
|
||||
| [`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.down_policy`](/docs/agent/options.html#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
|
||||
|
|
@ -247,7 +247,7 @@ A number of special tokens can also be configured which allow for bootstrapping
|
|||
system, or accessing Consul in special situations:
|
||||
|
||||
| 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`](/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 |
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Kubernetes Auth Method"
|
||||
sidebar_current: "docs-acl-auth-methods-kubernetes"
|
||||
layout: 'docs'
|
||||
page_title: 'Kubernetes Auth Method'
|
||||
sidebar_current: 'docs-acl-auth-methods-kubernetes'
|
||||
description: |-
|
||||
The Kubernetes auth method type allows for a Kubernetes service account token to be used to authenticate to Consul. This method of authentication makes it easy to introduce a Consul token into a Kubernetes pod.
|
||||
---
|
||||
|
|
@ -32,7 +32,7 @@ parameters are required to properly configure an auth method of type
|
|||
newline (`\n`).
|
||||
|
||||
- `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.
|
||||
|
||||
- `MapNamespaces` `(bool: <false>)` - **(Enterprise Only)** Indicates whether
|
||||
|
|
@ -107,9 +107,9 @@ metadata:
|
|||
name: service-account-getter
|
||||
namespace: default
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["serviceaccounts"]
|
||||
verbs: ["get"]
|
||||
- apiGroups: ['']
|
||||
resources: ['serviceaccounts']
|
||||
verbs: ['get']
|
||||
---
|
||||
kind: ClusterRoleBinding
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
|
|
@ -132,7 +132,7 @@ The authentication step returns the following trusted identity attributes for
|
|||
use in binding rule selectors and bind name interpolation.
|
||||
|
||||
| Attributes | Supported Selector Operations | Can be Interpolated |
|
||||
| -------------------------- | ---------------------------------- | ------------------- |
|
||||
| -------------------------- | ----------------------------- | ------------------- |
|
||||
| `serviceaccount.namespace` | Equal, Not Equal | yes |
|
||||
| `serviceaccount.name` | Equal, Not Equal | yes |
|
||||
| `serviceaccount.uid` | Equal, Not Equal | yes |
|
||||
|
|
@ -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
|
||||
found its value will override the trusted attribute of `serviceaccount.name`
|
||||
for the purposes of evaluating any binding rules.
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "ACL Guides"
|
||||
sidebar_current: "docs-acl-index"
|
||||
layout: 'docs'
|
||||
page_title: 'ACL Guides'
|
||||
sidebar_current: 'docs-acl-index'
|
||||
description: |-
|
||||
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. Select the following guide for your use case.
|
||||
---
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Agent"
|
||||
sidebar_current: "docs-agent-running"
|
||||
layout: 'docs'
|
||||
page_title: 'Agent'
|
||||
sidebar_current: 'docs-agent-running'
|
||||
description: |-
|
||||
The Consul agent is the core process of Consul. The agent maintains membership information, registers services, runs checks, responds to queries, and more. The agent must run on every node that is part of a Consul cluster.
|
||||
---
|
||||
|
|
@ -49,30 +49,30 @@ $ consul agent -data-dir=/tmp/consul
|
|||
|
||||
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
|
||||
[`-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,
|
||||
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
|
||||
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,
|
||||
storing cluster state, and handling queries. Additionally, a server may be
|
||||
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.
|
||||
|
||||
* **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
|
||||
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
|
||||
indicate how to reach the agent. Other applications can also use the HTTP address and port
|
||||
[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
|
||||
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_
|
||||
states), Consul will automatically remove dead nodes out of the catalog. This
|
||||
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,
|
||||
causing all associated services to be deregistered.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Check Definition"
|
||||
sidebar_current: "docs-agent-checks"
|
||||
layout: 'docs'
|
||||
page_title: 'Check Definition'
|
||||
sidebar_current: 'docs-agent-checks'
|
||||
description: |-
|
||||
One of the primary roles of the agent is management of system- and application-level health checks. A health check is considered to be application-level if it is associated with a service. A check is defined in a configuration file or added at runtime over the HTTP interface.
|
||||
---
|
||||
|
|
@ -18,7 +18,7 @@ created via the HTTP interface persist with that node.
|
|||
|
||||
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
|
||||
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
|
||||
|
|
@ -31,10 +31,11 @@ There are several different kinds of checks:
|
|||
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
|
||||
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
|
||||
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.
|
||||
|
||||
~> **Security Warning:** Enabling script checks in some configurations may
|
||||
|
|
@ -43,7 +44,7 @@ There are several different kinds of checks:
|
|||
blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations)
|
||||
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).
|
||||
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
|
||||
|
|
@ -61,7 +62,7 @@ There are several different kinds of checks:
|
|||
Certificate verification can be turned off by setting the `tls_skip_verify`
|
||||
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
|
||||
(e.g. 30 seconds). If no hostname
|
||||
is specified, it defaults to "localhost". The status of the service depends on
|
||||
|
|
@ -76,7 +77,7 @@ There are several different kinds of checks:
|
|||
It is possible to configure a custom TCP check timeout value by specifying the
|
||||
`timeout` field in the check definition.
|
||||
|
||||
* <a name="TTL"></a>Time to Live (TTL) - These checks retain their last known
|
||||
- <a name="TTL"></a>Time to Live (TTL) - These checks retain their last known
|
||||
state for a given TTL. The state of the check must be updated periodically
|
||||
over the HTTP interface. If an external system fails to update the status
|
||||
within a given TTL, the check is set to the failed state. This mechanism,
|
||||
|
|
@ -94,10 +95,10 @@ There are several different kinds of checks:
|
|||
check status is valid through the end of the TTL from the time of the last
|
||||
check.
|
||||
|
||||
* Docker + Interval - These checks depend on invoking an external application which
|
||||
- Docker + Interval - These checks depend on invoking an external application which
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
@ -107,7 +108,7 @@ There are several different kinds of 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.
|
||||
|
||||
* 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).
|
||||
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
|
||||
|
|
@ -119,7 +120,7 @@ There are several different kinds of checks:
|
|||
`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`.
|
||||
|
||||
* <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,
|
||||
but is nearly instant. For aliased services on the same agent, the local
|
||||
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
|
||||
field is parsed by Go's `time` package, and has the following
|
||||
[formatting specification](https://golang.org/pkg/time/#ParseDuration):
|
||||
|
||||
> 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".
|
||||
> 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
|
||||
this convention:
|
||||
|
||||
* Exit code 0 - Check is passing
|
||||
* Exit code 1 - Check is warning
|
||||
* Any other code - Check is failing
|
||||
- Exit code 0 - Check is passing
|
||||
- Exit code 1 - Check is warning
|
||||
- Any other code - Check is failing
|
||||
|
||||
This is the only convention that Consul depends on. Any output of the script
|
||||
will be captured and stored in the `output` field.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Cloud Auto-join"
|
||||
sidebar_current: "docs-agent-cloud-auto-join"
|
||||
layout: 'docs'
|
||||
page_title: 'Cloud Auto-join'
|
||||
sidebar_current: 'docs-agent-cloud-auto-join'
|
||||
description: |-
|
||||
Consul supports automatically joining a Consul datacenter using cloud metadata on various providers.
|
||||
---
|
||||
|
|
@ -93,7 +93,9 @@ $ consul agent -retry-join "provider=azure tag_name=... tag_value=... tenant_id=
|
|||
|
||||
```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:
|
||||
|
||||
* `ARM_SUBSCRIPTION_ID` for subscription
|
||||
* `ARM_TENANT_ID` for tenant
|
||||
* `ARM_CLIENT_ID` for client
|
||||
* `ARM_CLIENT_SECRET` for secret access key
|
||||
- `ARM_SUBSCRIPTION_ID` for subscription
|
||||
- `ARM_TENANT_ID` for tenant
|
||||
- `ARM_CLIENT_ID` for client
|
||||
- `ARM_CLIENT_SECRET` for secret access key
|
||||
|
||||
Use these configuration parameters when using tags:
|
||||
|
||||
|
|
@ -171,7 +173,9 @@ $ consul agent -retry-join "provider=softlayer datacenter=... tag_value=... user
|
|||
|
||||
```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
|
||||
{
|
||||
"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=..."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -237,7 +243,9 @@ $ consul agent -retry-join "provider=os tag_key=consul tag_value=server username
|
|||
|
||||
```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
|
||||
{
|
||||
"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).
|
||||
- `token` (required) - the token to use for auth.
|
||||
|
||||
|
||||
### TencentCloud
|
||||
|
||||
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
|
||||
{
|
||||
"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'.
|
||||
It is recommended you make a dedicated key used to auto-join the Consul datacenter.
|
||||
|
||||
|
||||
### Joyent Triton
|
||||
|
||||
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
|
||||
{
|
||||
"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_value` (optional) - the tag value to use.
|
||||
|
||||
|
||||
### vSphere
|
||||
|
||||
This returns the first private IP address of all servers for the given region with the given `tag_name` and `category_name`.
|
||||
|
|
@ -336,7 +347,9 @@ $ consul agent -retry-join "provider=vsphere category_name=consul-role tag_name=
|
|||
|
||||
```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]"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -359,7 +372,9 @@ $ consul agent -retry-join "provider=packet auth_token=token project=uuid url=..
|
|||
|
||||
```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=..."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Kind: Proxy Defaults"
|
||||
sidebar_current: "docs-agent-cfg_entries-proxy_defaults"
|
||||
layout: 'docs'
|
||||
page_title: 'Configuration Entry Kind: Proxy Defaults'
|
||||
sidebar_current: 'docs-agent-cfg_entries-proxy_defaults'
|
||||
description: |-
|
||||
The proxy-defaults config entry kind allows for configuring global config defaults across all services for Connect proxy configuration. Currently, only one global entry is supported.
|
||||
---
|
||||
|
|
@ -49,8 +49,8 @@ config {
|
|||
that your proxy allows can be configured globally here. To
|
||||
explore these options please see the documentation for your chosen proxy.
|
||||
|
||||
* [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
|
||||
* [Consul's built-in proxy](/docs/connect/proxies/built-in.html)
|
||||
- [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
|
||||
- [Consul's built-in proxy](/docs/connect/proxies/built-in.html)
|
||||
|
||||
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
|
||||
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration)
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Kind: Service Defaults"
|
||||
sidebar_current: "docs-agent-cfg_entries-service_defaults"
|
||||
layout: 'docs'
|
||||
page_title: 'Configuration Entry Kind: Service Defaults'
|
||||
sidebar_current: 'docs-agent-cfg_entries-service_defaults'
|
||||
description: |-
|
||||
The service-defaults config entry kind controls default global values for a service, such as its protocol.
|
||||
---
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Kind: Service Resolver"
|
||||
sidebar_current: "docs-agent-cfg_entries-service_resolver"
|
||||
layout: 'docs'
|
||||
page_title: 'Configuration Entry Kind: Service Resolver'
|
||||
sidebar_current: 'docs-agent-cfg_entries-service_resolver'
|
||||
description: |-
|
||||
The `service-resolver` config entry kind controls which service instances should satisfy Connect upstream discovery requests for a given service name.
|
||||
---
|
||||
|
|
@ -177,4 +177,3 @@ name in these fields:
|
|||
- [`Redirect.Service`](#service)
|
||||
|
||||
- [`Failover[].Service`](#service-1)
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Kind: Service Router"
|
||||
sidebar_current: "docs-agent-cfg_entries-service_router"
|
||||
layout: 'docs'
|
||||
page_title: 'Configuration Entry Kind: Service Router'
|
||||
sidebar_current: 'docs-agent-cfg_entries-service_router'
|
||||
description: |-
|
||||
The service-router config entry kind controls Connect traffic routing and manipulation at networking layer 7 (e.g. HTTP).
|
||||
---
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Kind: Service Splitter"
|
||||
sidebar_current: "docs-agent-cfg_entries-service_splitter"
|
||||
layout: 'docs'
|
||||
page_title: 'Configuration Entry Kind: Service Splitter'
|
||||
sidebar_current: 'docs-agent-cfg_entries-service_splitter'
|
||||
description: |-
|
||||
The service-splitter config entry kind controls how to split incoming Connect requests across different subsets of a single service (like during staged canary rollouts), or perhaps across different services (like during a v2 rewrite or other type of codebase migration).
|
||||
---
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Definitions"
|
||||
sidebar_current: "docs-agent-cfg_entries"
|
||||
layout: 'docs'
|
||||
page_title: 'Configuration Entry Definitions'
|
||||
sidebar_current: 'docs-agent-cfg_entries'
|
||||
description: |-
|
||||
Consul allows storing configuration entries centrally to be used as defaults for configuring other aspects of Consul.
|
||||
---
|
||||
|
|
@ -24,19 +24,19 @@ Name = "<name of entry>"
|
|||
|
||||
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
|
||||
|
||||
* [`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
|
||||
|
||||
* [`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-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
|
||||
|
||||
* [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) - controls
|
||||
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) - controls
|
||||
proxy configuration
|
||||
|
||||
## Managing Configuration Entries
|
||||
|
|
@ -111,7 +111,6 @@ api
|
|||
db
|
||||
```
|
||||
|
||||
|
||||
#### Deleting Configuration Entries
|
||||
|
||||
The [`consul config delete`](/docs/commands/config/delete.html) command is used
|
||||
|
|
@ -145,7 +144,6 @@ api
|
|||
|
||||
### Bootstrapping From A Configuration File
|
||||
|
||||
|
||||
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 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
|
||||
matches both `kind` and `name`, then the server will do nothing.
|
||||
|
||||
|
||||
## Using Configuration Entries For Service Defaults
|
||||
|
||||
When the agent is
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "DNS Interface"
|
||||
sidebar_current: "docs-agent-dns"
|
||||
layout: 'docs'
|
||||
page_title: 'DNS Interface'
|
||||
sidebar_current: 'docs-agent-dns'
|
||||
description: |-
|
||||
One of the primary query interfaces for Consul is DNS. The DNS interface allows applications to make use of service discovery without any high-touch integration with Consul.
|
||||
---
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Encryption"
|
||||
sidebar_current: "docs-agent-encryption"
|
||||
layout: 'docs'
|
||||
page_title: 'Encryption'
|
||||
sidebar_current: 'docs-agent-encryption'
|
||||
description: |-
|
||||
The Consul agent supports encrypting all of its network traffic. The exact method of encryption is described on the encryption internals page. There are two separate encryption systems, one for gossip traffic and one for RPC.
|
||||
---
|
||||
|
|
@ -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
|
||||
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)
|
||||
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).
|
||||
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).
|
||||
|
||||
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
|
||||
|
|
@ -109,4 +108,3 @@ 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)
|
||||
for the step-by-step process to configure TLS on a new or existing cluster. Note the call outs there
|
||||
for existing cluster configuration.
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Consul KV"
|
||||
sidebar_current: "docs-agent-kv"
|
||||
layout: 'docs'
|
||||
page_title: 'Consul KV'
|
||||
sidebar_current: 'docs-agent-kv'
|
||||
description: |-
|
||||
Consul KV is a core feature of Consul and is installed with the Consul agent.
|
||||
---
|
||||
|
|
@ -42,9 +42,7 @@ application.
|
|||
|
||||
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
|
||||
the event of a complete outage, use the [`consul
|
||||
snapshot`](/docs/commands/snapshot/restore.html) feature to backup the data.
|
||||
|
||||
the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore.html) feature to backup the data.
|
||||
|
||||
## Using Consul KV
|
||||
|
||||
|
|
@ -64,7 +62,6 @@ and when recursively searching within the data store. We also recommend that
|
|||
you avoid the use of `*`, `?`, `'`, and `%` because they can cause issues when
|
||||
using the API and in shell scripts.
|
||||
|
||||
|
||||
## Extending Consul KV
|
||||
|
||||
### Consul Template
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "RPC"
|
||||
sidebar_current: "docs-agent-rpc"
|
||||
layout: 'docs'
|
||||
page_title: 'RPC'
|
||||
sidebar_current: 'docs-agent-rpc'
|
||||
description: |-
|
||||
The Consul agent provides a complete RPC mechanism that can be used to control the agent programmatically. This RPC mechanism is the same one used by the CLI but can be used by other applications to easily leverage the power of Consul without directly embedding.
|
||||
---
|
||||
|
|
@ -57,16 +57,16 @@ All responses may be accompanied by an error.
|
|||
|
||||
Possible commands include:
|
||||
|
||||
* handshake - Initializes the connection and sets the version
|
||||
* force-leave - Removes a failed node from the cluster
|
||||
* join - Requests Consul join another node
|
||||
* members-lan - Returns the list of LAN members
|
||||
* members-wan - Returns the list of WAN members
|
||||
* monitor - Starts streaming logs over the connection
|
||||
* stop - Stops streaming logs
|
||||
* leave - Instructs the Consul agent to perform a graceful leave and shutdown
|
||||
* stats - Provides various debugging statistics
|
||||
* reload - Triggers a configuration reload
|
||||
- handshake - Initializes the connection and sets the version
|
||||
- force-leave - Removes a failed node from the cluster
|
||||
- join - Requests Consul join another node
|
||||
- members-lan - Returns the list of LAN members
|
||||
- members-wan - Returns the list of WAN members
|
||||
- monitor - Starts streaming logs over the connection
|
||||
- stop - Stops streaming logs
|
||||
- leave - Instructs the Consul agent to perform a graceful leave and shutdown
|
||||
- stats - Provides various debugging statistics
|
||||
- reload - Triggers a configuration reload
|
||||
|
||||
Each command is documented below along with any request or
|
||||
response body that is applicable.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Service Definition"
|
||||
sidebar_current: "docs-agent-services"
|
||||
layout: 'docs'
|
||||
page_title: 'Service Definition'
|
||||
sidebar_current: 'docs-agent-services'
|
||||
description: |-
|
||||
One of the main goals of service discovery is to provide a catalog of available services. To that end, the agent provides a simple service definition format to declare the availability of a service and to potentially associate it with a health check. A health check is considered to be application level if it is associated with a service. A service is defined in a configuration file or added at runtime over the HTTP interface.
|
||||
---
|
||||
|
|
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
It's important to note that this applies only to the locally registered
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Telemetry"
|
||||
sidebar_current: "docs-agent-telemetry"
|
||||
layout: 'docs'
|
||||
page_title: 'Telemetry'
|
||||
sidebar_current: 'docs-agent-telemetry'
|
||||
description: |-
|
||||
The Consul agent collects various runtime metrics about the performance of different libraries and subsystems. These metrics are aggregated on a ten second interval and are retained for one minute.
|
||||
---
|
||||
|
|
@ -26,7 +26,6 @@ are provided, the telemetry information will be streamed to a
|
|||
it can be aggregated and flushed to Graphite or any other metrics store.
|
||||
For a configuration example for Telegraf, review the [Monitoring with Telegraf guide](https://learn.hashicorp.com/consul/integrations/telegraf?utm_source=consul.io&utm_medium=docs).
|
||||
|
||||
|
||||
This
|
||||
information can also be viewed with the [metrics endpoint](/api/agent.html#view-metrics) in JSON
|
||||
format or using [Prometheus](https://prometheus.io/) format.
|
||||
|
|
@ -58,7 +57,7 @@ These are some metrics emitted that can help you understand the health of your c
|
|||
### Transaction timing
|
||||
|
||||
| Metric Name | Description |
|
||||
| :----------------------- | :---------- |
|
||||
| :----------------------- | :----------------------------------------------------------------------------------- |
|
||||
| `consul.kvs.apply` | This measures the time it takes to complete an update to the KV store. |
|
||||
| `consul.txn.apply` | This measures the time spent applying a transaction operation. |
|
||||
| `consul.raft.apply` | This counts the number of Raft transactions occurring over the interval. |
|
||||
|
|
@ -71,7 +70,7 @@ These are some metrics emitted that can help you understand the health of your c
|
|||
### Leadership changes
|
||||
|
||||
| Metric Name | Description |
|
||||
| :---------- | :---------- |
|
||||
| :------------------------------- | :------------------------------------------------------------------------------------------------------------- |
|
||||
| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. |
|
||||
| `consul.raft.state.candidate` | This increments whenever a Consul server starts an election. |
|
||||
| `consul.raft.state.leader` | This increments whenever a Consul server becomes a leader. |
|
||||
|
|
@ -83,7 +82,7 @@ These are some metrics emitted that can help you understand the health of your c
|
|||
### Autopilot
|
||||
|
||||
| Metric Name | Description |
|
||||
| :---------- | :---------- |
|
||||
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. |
|
||||
|
||||
**Why it's important:** Obviously, you want your cluster to be healthy.
|
||||
|
|
@ -93,7 +92,7 @@ These are some metrics emitted that can help you understand the health of your c
|
|||
### Memory usage
|
||||
|
||||
| Metric Name | Description |
|
||||
| :---------- | :---------- |
|
||||
| :--------------------------- | :----------------------------------------------------------------- |
|
||||
| `consul.runtime.alloc_bytes` | This measures the number of bytes allocated by the Consul process. |
|
||||
| `consul.runtime.sys_bytes` | This is the total number of bytes of memory obtained from the OS. |
|
||||
|
||||
|
|
@ -104,7 +103,7 @@ These are some metrics emitted that can help you understand the health of your c
|
|||
### Garbage collection
|
||||
|
||||
| Metric Name | Description |
|
||||
| :---------- | :---------- |
|
||||
| :--------------------------------- | :---------------------------------------------------------------------------------------------------- |
|
||||
| `consul.runtime.total_gc_pause_ns` | Number of nanoseconds consumed by stop-the-world garbage collection (GC) pauses since Consul started. |
|
||||
|
||||
**Why it's important:** GC pause is a "stop-the-world" event, meaning that all runtime threads are blocked until GC completes. Normally these pauses last only a few nanoseconds. But if memory usage is high, the Go runtime may GC so frequently that it starts to slow down Consul.
|
||||
|
|
@ -117,7 +116,7 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference()
|
|||
### Network activity - RPC Count
|
||||
|
||||
| Metric Name | Description |
|
||||
| :---------- | :---------- |
|
||||
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server |
|
||||
| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options.html#limits) configuration. |
|
||||
| `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. |
|
||||
|
|
@ -1018,7 +1017,6 @@ These metrics give insight into the health of the cluster as a whole.
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
## Connect Built-in Proxy Metrics
|
||||
|
||||
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
|
||||
out of a given service or the total number of connections between two services.
|
||||
|
||||
|
||||
### Metrics Reference
|
||||
|
||||
The standard go runtime metrics are exported by `go-metrics` as with Consul
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Watches"
|
||||
sidebar_current: "docs-agent-watches"
|
||||
layout: 'docs'
|
||||
page_title: 'Watches'
|
||||
sidebar_current: 'docs-agent-watches'
|
||||
description: |-
|
||||
Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs, health checks) which is monitored for updates. When an update is detected, an external handler is invoked. A handler can be any executable. As an example, you could watch the status of health checks and notify an external system when a check is critical.
|
||||
---
|
||||
|
|
@ -97,23 +97,22 @@ Here is an example configuration:
|
|||
In addition to the parameters supported by each option type, there
|
||||
are a few global parameters that all watches support:
|
||||
|
||||
* `datacenter` - Can be provided to override the agent's default datacenter.
|
||||
* `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.
|
||||
* `handler` - The handler shell command to invoke when the data view updates.
|
||||
- `datacenter` - Can be provided to override the agent's default datacenter.
|
||||
- `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.
|
||||
- `handler` - The handler shell command to invoke when the data view updates.
|
||||
|
||||
## Watch Types
|
||||
|
||||
The following types are supported. Detailed documentation on each is below:
|
||||
|
||||
* [`key`](#key) - Watch a specific KV pair
|
||||
* [`keyprefix`](#keyprefix) - Watch a prefix in the KV store
|
||||
* [`services`](#services) - Watch the list of available services
|
||||
* [`nodes`](#nodes) - Watch the list of nodes
|
||||
* [`service`](#service)- Watch the instances of a service
|
||||
* [`checks`](#checks) - Watch the value of health checks
|
||||
* [`event`](#event) - Watch for custom user events
|
||||
|
||||
- [`key`](#key) - Watch a specific KV pair
|
||||
- [`keyprefix`](#keyprefix) - Watch a prefix in the KV store
|
||||
- [`services`](#services) - Watch the list of available services
|
||||
- [`nodes`](#nodes) - Watch the list of nodes
|
||||
- [`service`](#service)- Watch the instances of a service
|
||||
- [`checks`](#checks) - Watch the value of health checks
|
||||
- [`event`](#event) - Watch for custom user events
|
||||
|
||||
### <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.
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```javascript
|
||||
[
|
||||
;[
|
||||
{
|
||||
"Key": "foo/bar",
|
||||
"CreateIndex": 1796,
|
||||
"ModifyIndex": 1796,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "TU9BUg==",
|
||||
"Session": ""
|
||||
Key: 'foo/bar',
|
||||
CreateIndex: 1796,
|
||||
ModifyIndex: 1796,
|
||||
LockIndex: 0,
|
||||
Flags: 0,
|
||||
Value: 'TU9BUg==',
|
||||
Session: '',
|
||||
},
|
||||
{
|
||||
"Key": "foo/baz",
|
||||
"CreateIndex": 1795,
|
||||
"ModifyIndex": 1795,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "YXNkZg==",
|
||||
"Session": ""
|
||||
Key: 'foo/baz',
|
||||
CreateIndex: 1795,
|
||||
ModifyIndex: 1795,
|
||||
LockIndex: 0,
|
||||
Flags: 0,
|
||||
Value: 'YXNkZg==',
|
||||
Session: '',
|
||||
},
|
||||
{
|
||||
"Key": "foo/test",
|
||||
"CreateIndex": 1793,
|
||||
"ModifyIndex": 1793,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "aGV5",
|
||||
"Session": ""
|
||||
}
|
||||
Key: 'foo/test',
|
||||
CreateIndex: 1793,
|
||||
ModifyIndex: 1793,
|
||||
LockIndex: 0,
|
||||
Flags: 0,
|
||||
Value: 'aGV5',
|
||||
Session: '',
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
|
|
@ -234,31 +233,31 @@ This maps to the `/v1/catalog/nodes` API internally.
|
|||
An example of the output of this command:
|
||||
|
||||
```javascript
|
||||
[
|
||||
;[
|
||||
{
|
||||
"Node": "nyc1-consul-1",
|
||||
"Address": "192.241.159.115"
|
||||
Node: 'nyc1-consul-1',
|
||||
Address: '192.241.159.115',
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-consul-2",
|
||||
"Address": "192.241.158.205"
|
||||
Node: 'nyc1-consul-2',
|
||||
Address: '192.241.158.205',
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-consul-3",
|
||||
"Address": "198.199.77.133"
|
||||
Node: 'nyc1-consul-3',
|
||||
Address: '198.199.77.133',
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-worker-1",
|
||||
"Address": "162.243.162.228"
|
||||
Node: 'nyc1-worker-1',
|
||||
Address: '162.243.162.228',
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-worker-2",
|
||||
"Address": "162.243.162.226"
|
||||
Node: 'nyc1-worker-2',
|
||||
Address: '162.243.162.226',
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-worker-3",
|
||||
"Address": "162.243.162.229"
|
||||
}
|
||||
Node: 'nyc1-worker-3',
|
||||
Address: '162.243.162.229',
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
|
|
@ -309,44 +308,41 @@ Multiple tag:
|
|||
An example of the output of this command:
|
||||
|
||||
```javascript
|
||||
[
|
||||
;[
|
||||
{
|
||||
"Node": {
|
||||
"Node": "foobar",
|
||||
"Address": "10.1.10.12"
|
||||
Node: {
|
||||
Node: 'foobar',
|
||||
Address: '10.1.10.12',
|
||||
},
|
||||
Service: {
|
||||
ID: 'redis',
|
||||
Service: 'redis',
|
||||
Tags: ['bar', 'foo'],
|
||||
Port: 8000,
|
||||
},
|
||||
Checks: [
|
||||
{
|
||||
Node: 'foobar',
|
||||
CheckID: 'service:redis',
|
||||
Name: "Service 'redis' check",
|
||||
Status: 'passing',
|
||||
Notes: '',
|
||||
Output: '',
|
||||
ServiceID: 'redis',
|
||||
ServiceName: 'redis',
|
||||
},
|
||||
{
|
||||
Node: 'foobar',
|
||||
CheckID: 'serfHealth',
|
||||
Name: 'Serf Health Status',
|
||||
Status: 'passing',
|
||||
Notes: '',
|
||||
Output: '',
|
||||
ServiceID: '',
|
||||
ServiceName: '',
|
||||
},
|
||||
"Service": {
|
||||
"ID": "redis",
|
||||
"Service": "redis",
|
||||
"Tags": [
|
||||
"bar",
|
||||
"foo"
|
||||
],
|
||||
"Port": 8000
|
||||
},
|
||||
"Checks": [
|
||||
{
|
||||
"Node": "foobar",
|
||||
"CheckID": "service:redis",
|
||||
"Name": "Service 'redis' check",
|
||||
"Status": "passing",
|
||||
"Notes": "",
|
||||
"Output": "",
|
||||
"ServiceID": "redis",
|
||||
"ServiceName": "redis"
|
||||
},
|
||||
{
|
||||
"Node": "foobar",
|
||||
"CheckID": "serfHealth",
|
||||
"Name": "Serf Health Status",
|
||||
"Status": "passing",
|
||||
"Notes": "",
|
||||
"Output": "",
|
||||
"ServiceID": "",
|
||||
"ServiceName": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue