Config Entry docs (#5734)

* Add api docs for the config entry endpoints * Add enable_central_service_config field to agent docs * Add docs for config entry CLI operations * Fix wording and links in config entry docs * Add links to the central service config option * Update the central service config setting description.
hashicorp · May 1, 2019 · 7b16fe3 · 7b16fe3
1 parent 69f9026
commit 7b16fe3
Show file tree

Hide file tree

Showing 9 changed files with 537 additions and 0 deletions.
diff --git a/website/source/api/config.html.md b/website/source/api/config.html.md
@@ -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
+```
diff --git a/website/source/docs/agent/options.html.md b/website/source/docs/agent/options.html.md
@@ -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`.

diff --git a/website/source/docs/commands/config.html.md b/website/source/docs/commands/config.html.md
@@ -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.
diff --git a/website/source/docs/commands/config/delete.html.md.erb b/website/source/docs/commands/config/delete.html.md.erb
@@ -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
diff --git a/website/source/docs/commands/config/list.html.md.erb b/website/source/docs/commands/config/list.html.md.erb
@@ -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
+
+