Skip to content

Config Entry docs #5734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pearkes merged 7 commits into from
May 1, 2019
Merged

Config Entry docs #5734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c24bc1c
Add api docs for the config entry endpoints
kyhavlov Apr 29, 2019
6d9df49
Add enable_central_service_config field to agent docs
kyhavlov Apr 29, 2019
9f391f8
Add docs for config entry CLI operations
kyhavlov Apr 29, 2019
96595b6
Fix wording and links in config entry docs
kyhavlov Apr 30, 2019
4c26464
Merge branch 'master' into config-entry-docs
kyhavlov Apr 30, 2019
c8c4b9a
Add links to the central service config option
kyhavlov Apr 30, 2019
6a58359
Update the central service config setting description.
kyhavlov Apr 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 249 additions & 0 deletions website/source/api/config.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,249 @@
---
layout: api
page_title: Config - HTTP API
sidebar_current: api-config
description: |-
The /config endpoints are for managing centralized configuration
in Consul.
---

# Config HTTP Endpoint

The `/config` endpoints create, update, delete and query central configuration
entries registered with Consul. See the
[agent configuration](/docs/agent/options.html#enable_central_service_config)
for more information on how to enable this functionality for centrally
configuring services.

## Apply Configuration

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
[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` | `service:write`<br>`operator:write`<sup>1</sup> |

<sup>1</sup> The ACL required depends on the config entry kind being updated:

| Config Entry Kind | Required ACL |
| ----------------- | ---------------- |
| service-defaults | `service:write` |
| proxy-defaults | `operator:write` |

### Parameters

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.

- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. If the index is
0, Consul will only store the entry if it does not already exist. If the index is
non-zero, the entry is only set if the current index matches the `ModifyIndex`
of that entry.

### Sample Payload


```javascript
{
"Kind": "service-defaults",
"Name": "web",
"Protocol": "http",
"Connect": {
"SidecarProxy": false
}
}
```

### Sample Request

```sh
$ curl \
--request PUT \
--data @payload \
http://127.0.0.1:8500/v1/config
```

## Get Configuration

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

### Parameters

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.

- `kind` `(string: <required>)` - Specifies the kind of the entry to read. This
is specified as part of the URL.

- `name` `(string: <required>)` - Specifies the name of the entry to read. This
is specified as part of the URL.

### Sample Request

```sh
$ curl \
--request GET \
http://127.0.0.1:8500/v1/config/service-defaults/web
```

### Sample Response

```json
{
"Kind": "service-defaults",
"Name": "web",
"Protocol": "http",
"Connect": {
"SidecarProxy": true
},
"CreateIndex": 15,
"ModifyIndex": 35
}
```

## List Configurations

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

### Parameters

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.

- `kind` `(string: <required>)` - Specifies the kind of the entry to list. This
is specified as part of the URL.

### Sample Request

```sh
$ curl \
--request GET \
http://127.0.0.1:8500/v1/config/service-defaults
```

### Sample Response

```json
[
{
"Kind": "service-defaults",
"Name": "db",
"Protocol": "tcp",
"Connect": {
"SidecarProxy": false
},
"CreateIndex": 16,
"ModifyIndex": 16
},
{
"Kind": "service-defaults",
"Name": "web",
"Protocol": "http",
"Connect": {
"SidecarProxy": true
},
"CreateIndex": 13,
"ModifyIndex": 13
}
]
```

## Delete Configuration

This endpoint creates or updates the given config entry.

| Method | Path | Produces |
| -------- | ---------------------------- | -------------------------- |
| `DELETE` | `/config/:kind/:name` | `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` | `service:write`<br>`operator:write`<sup>1</sup> |

<sup>1</sup> The ACL required depends on the config entry kind being deleted:

| Config Entry Kind | Required ACL |
| ----------------- | ---------------- |
| service-defaults | `service:write` |
| proxy-defaults | `operator:write` |

### Parameters

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.

- `kind` `(string: <required>)` - Specifies the kind of the entry to delete. This
is specified as part of the URL.

- `name` `(string: <required>)` - Specifies the name of the entry to delete. This
is specified as part of the URL.

### Sample Request

```sh
$ curl \
--request DELETE \
http://127.0.0.1:8500/v1/config/service-defaults/web
```
8 changes: 8 additions & 0 deletions website/source/docs/agent/options.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1110,6 +1110,14 @@ default will automatically work with some tooling.
`server_name`) to set up the client for HTTP or gRPC health checks. This allows services requiring 2-way TLS to
be checked using the agent's credentials. This was added in Consul 1.0.1 and defaults to false.

* <a name="enable_central_service_config"></a><a href="#enable_central_service_config">`enable_central_service_config`</a>
When set, the Consul agent will look for any centralized service configurations that match a registering service instance.
If it finds any, the agent will merge the centralized defaults with the service instance configuration. This allows for
things like service protocol or proxy configuration to be defined centrally and inherited by any
affected service registrations.



* <a name="enable_debug"></a><a href="#enable_debug">`enable_debug`</a> When set, enables some
additional debugging features. Currently, this is only used to access runtime profiling HTTP endpoints, which
are available with an `operator:read` ACL regardles of the value of `enable_debug`.
Expand Down
52 changes: 52 additions & 0 deletions website/source/docs/commands/config.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
layout: "docs"
page_title: "Commands: Config"
sidebar_current: "docs-commands-config"
---

# Consul Config

Command: `consul config`

The `config` command is used to interact with Consul's central configuration
system. It exposes commands for creating, updating, reading, and deleting
different kinds of config entries. See the
[agent configuration](/docs/agent/options.html#enable_central_service_config)
for more information on how to enable this functionality for centrally
configuring services.

## Usage

Usage: `consul config <subcommand>`

For the exact documentation for your Consul version, run `consul config -h` to view
the complete list of subcommands.

```text
Usage: consul config <subcommand> [options] [args]

This command has subcommands for interacting with Consul's centralized
configuration system. Here are some simple examples, and more detailed
examples are available in the subcommands or the documentation.

Write a config:

$ consul config write web.serviceconf.hcl

Read a config:

$ consul config read -kind service-defaults -name web

List all configs for a type:

$ consul config list -kind service-defaults

Delete a config:

$ consul config delete -kind service-defaults -name web

For more examples, ask for subcommand help or view the documentation.
```

For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.
33 changes: 33 additions & 0 deletions website/source/docs/commands/config/delete.html.md.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
layout: "docs"
page_title: "Commands: Config Delete"
sidebar_current: "docs-commands-config-delete"
---

# Consul Config Delete

Command: `consul config delete`

The `config delete` command deletes the configuration entry
specified by the kind and name. See the
[agent configuration](/docs/agent/options.html#enable_central_service_config)
for more information on how to enable this functionality for centrally
configuring services.

## Usage

Usage: `consul config delete [options]`

#### API Options

<%= partial "docs/commands/http_api_options_client" %>

#### Config Delete Options

* `-kind` - Specifies the kind of the config entry to read.

* `-name` - Specifies the name of the config entry to read.

## Examples

$ consul config delete -kind service-defaults -name web
36 changes: 36 additions & 0 deletions website/source/docs/commands/config/list.html.md.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
layout: "docs"
page_title: "Commands: Config List"
sidebar_current: "docs-commands-config-list"
---

# Consul Config List

Command: `consul config list`

The `config list` command lists all given config entries of the given kind.
See the
[agent configuration](/docs/agent/options.html#enable_central_service_config)
for more information on how to enable this functionality for centrally
configuring services.

## Usage

Usage: `consul config list [options]`

#### API Options

<%= partial "docs/commands/http_api_options_client" %>

#### Config List Options

* `-kind` - Specifies the kind of the config entry to read.

## Examples

$ consul config list -kind service-defaults
billing
db
web


Loading