From 1de73ff037eefa9d04b328ada796fadfe7a70381 Mon Sep 17 00:00:00 2001 From: Kyle Havlovitz Date: Wed, 1 May 2019 11:21:11 -0700 Subject: [PATCH] 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. --- website/source/api/config.html.md | 249 ++++++++++++++++++ website/source/docs/agent/options.html.md | 8 + website/source/docs/commands/config.html.md | 52 ++++ .../docs/commands/config/delete.html.md.erb | 33 +++ .../docs/commands/config/list.html.md.erb | 36 +++ .../docs/commands/config/read.html.md.erb | 45 ++++ .../docs/commands/config/write.html.md.erb | 94 +++++++ website/source/layouts/api.erb | 3 + website/source/layouts/docs.erb | 17 ++ 9 files changed, 537 insertions(+) create mode 100644 website/source/api/config.html.md create mode 100644 website/source/docs/commands/config.html.md create mode 100644 website/source/docs/commands/config/delete.html.md.erb create mode 100644 website/source/docs/commands/config/list.html.md.erb create mode 100644 website/source/docs/commands/config/read.html.md.erb create mode 100644 website/source/docs/commands/config/write.html.md.erb diff --git a/website/source/api/config.html.md b/website/source/api/config.html.md new file mode 100644 index 000000000..d377fc79a --- /dev/null +++ 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`
`operator:write`1 | + +1 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`1 | + +1 The ACL required depends on the config entry kind being read: + +| Config Entry Kind | Required ACL | +| ----------------- | ---------------- | +| service-defaults | `service:read` | +| proxy-defaults | `` | + +### 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: )` - Specifies the kind of the entry to read. This + is specified as part of the URL. + +- `name` `(string: )` - 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`1 | + +1 The ACL required depends on the config entry kind being read: + +| Config Entry Kind | Required ACL | +| ----------------- | ---------------- | +| service-defaults | `service:read` | +| proxy-defaults | `` | + +### 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: )` - 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`
`operator:write`1 | + +1 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: )` - Specifies the kind of the entry to delete. This + is specified as part of the URL. + +- `name` `(string: )` - 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 index d9cf95cc4..b798c099e 100644 --- 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. +* `enable_central_service_config` + 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. + + + * `enable_debug` 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 new file mode 100644 index 000000000..aa64f830d --- /dev/null +++ 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 ` + +For the exact documentation for your Consul version, run `consul config -h` to view +the complete list of subcommands. + +```text +Usage: consul config [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. \ No newline at end of file diff --git a/website/source/docs/commands/config/delete.html.md.erb b/website/source/docs/commands/config/delete.html.md.erb new file mode 100644 index 000000000..240cdf7e6 --- /dev/null +++ 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 new file mode 100644 index 000000000..4091a6435 --- /dev/null +++ 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 + + diff --git a/website/source/docs/commands/config/read.html.md.erb b/website/source/docs/commands/config/read.html.md.erb new file mode 100644 index 000000000..8db78190c --- /dev/null +++ b/website/source/docs/commands/config/read.html.md.erb @@ -0,0 +1,45 @@ +--- +layout: "docs" +page_title: "Commands: Config Read" +sidebar_current: "docs-commands-config-read" +--- + +# Consul Config Read + +Command: `consul config read` + +The `config read` command reads the config entry specified by the given +kind and name and outputs its JSON representation. 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 read [options]` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> + +#### Config Read Options + +* `-kind` - Specifies the kind of the config entry to read. + +* `-name` - Specifies the name of the config entry to read. + +## Examples + + $ consul config read -kind service-defaults -name web + { + "Kind": "service-defaults", + "Name": "web", + "Protocol": "http", + "Connect": { + "SidecarProxy": false + }, + "CreateIndex": 13, + "ModifyIndex": 13 + } + + diff --git a/website/source/docs/commands/config/write.html.md.erb b/website/source/docs/commands/config/write.html.md.erb new file mode 100644 index 000000000..c65c26468 --- /dev/null +++ b/website/source/docs/commands/config/write.html.md.erb @@ -0,0 +1,94 @@ +--- +layout: "docs" +page_title: "Commands: Config Write" +sidebar_current: "docs-commands-config-write" +--- + +# Consul Config Write + +Command: `consul config write` + +The `config write` command creates or updates a centralized config entry. +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 write [options] FILE` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> + +#### Config Write Options + +* `-cas` - 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. + +## Examples + +From file: + + $ consul config write web-defaults.json + +From stdin: + + $ consul config write - + + +### Config Entry examples + +All config entries must have a `Kind` when registered. Currently, the only +supported types are `service-defaults` and `proxy-defaults`. + +#### Service defaults + +Service defaults control default global values for a service, such as the +protocol and Connect fields. + +```json +{ + "Kind": "service-defaults", + "Name": "web", + "Protocol": "http", + "Connect": { + "SidecarProxy": false + } +} +``` + +* `Name` - Sets the name of the config entry. For service defaults, this must be + the name of the service being configured. + +* `Protocol` - Sets the protocol of the service. This is used by Connect proxies + for things like observability features. + +* `Connect` - This block contains Connect-related fields for the service. + + * `SidecarProxy` - Sets whether or not instances of this service should get a + sidecar proxy by default. + +#### Proxy defaults + +Proxy defaults allow for configuring global config defaults across all services +for Connect proxy config. Currently, only one global entry is supported. + +```json +{ + "Kind": "proxy-defaults", + "Name": "global", + "Config": { + "foo": 1 + } +} +``` + +* `Name` - Sets the name of the config entry. Currently, only a single `proxy-defaults` + entry with the name `global` is supported. + + +* `Config` - An arbitrary map of configuration values used by Connect proxies. diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index de091b002..ad8c2a380 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -55,6 +55,9 @@ > Catalog + > + Config + > Connect
    diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 752456ac8..27bfb28af 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -101,6 +101,23 @@
+ > + config + + > connect