From 8d2834fb1288365033168cb642d2260aed91e49a Mon Sep 17 00:00:00 2001 From: Ryan Uber Date: Tue, 28 Apr 2015 14:26:22 -0700 Subject: [PATCH] website: document service and check acl options --- .../source/docs/agent/checks.html.markdown | 4 ++++ .../docs/agent/http/agent.html.markdown | 14 ++++++++++++++ .../source/docs/agent/services.html.markdown | 4 ++++ .../source/docs/internals/acl.html.markdown | 19 +++++++++++++++++++ 4 files changed, 41 insertions(+) diff --git a/website/source/docs/agent/checks.html.markdown b/website/source/docs/agent/checks.html.markdown index 8f8e2342e8..13f4d06f99 100644 --- a/website/source/docs/agent/checks.html.markdown +++ b/website/source/docs/agent/checks.html.markdown @@ -91,6 +91,10 @@ description of the current state of the check. With a script check, the field is set to any output generated by the script. Similarly, an external process updating a TTL check via the HTTP interface can set the `notes` value. +Checks may also contain a `token` field to provide an ACL token. This token is +used for any interaction with the catalog for the check, including +[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. + To configure a check, either provide it as a `-config-file` option to the agent or place it inside the `-config-dir` of the agent. The file must end in the ".json" extension to be loaded by Consul. Check definitions can diff --git a/website/source/docs/agent/http/agent.html.markdown b/website/source/docs/agent/http/agent.html.markdown index d23c50ab95..4c13e85baf 100644 --- a/website/source/docs/agent/http/agent.html.markdown +++ b/website/source/docs/agent/http/agent.html.markdown @@ -263,6 +263,13 @@ the state of the check. Optionally, a `ServiceID` can be provided to associate the registered check with an existing service provided by the agent. +This endpoint supports [ACL tokens](/docs/internals/acl.html). If the query +string includes a `?token=`, the registration will use the provided +token to authorize the request. The token is also persisted in the agent's +local configuration to enable periodic +[anti-entropy](/docs/internal/anti-entropy.html) syncs and seamless agent +restarts. + The return code is 200 on success. ### /v1/agent/check/deregister/\ @@ -346,6 +353,13 @@ If `Check` is provided, only one of `Script`, `HTTP`, or `TTL` should be specifi `Script` and `HTTP` also require `Interval`. The created check will be named "service:\". There is more information about checks [here](/docs/agent/checks.html). +This endpoint supports [ACL tokens](/docs/internals/acl.html). If the query +string includes a `?token=`, the registration will use the provided +token to authorize the request. The token is also persisted in the agent's +local configuration to enable periodic +[anti-entropy](/docs/internal/anti-entropy.html) syncs and seamless agent +restarts. + The return code is 200 on success. ### /v1/agent/service/deregister/\ diff --git a/website/source/docs/agent/services.html.markdown b/website/source/docs/agent/services.html.markdown index ab9c18dac9..241ef10c2f 100644 --- a/website/source/docs/agent/services.html.markdown +++ b/website/source/docs/agent/services.html.markdown @@ -51,6 +51,10 @@ The `port` field can be used as well to make a service-oriented architecture simpler to configure; this way, the address and port of a service can be discovered. +Services may also contain a `token` field to provide an ACL token. This token is +used for any interaction with the catalog for the service, including +[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. + A service can have an associated health check. This is a powerful feature as it allows a web balancer to gracefully remove failing nodes, a database to replace a failed slave, etc. The health check is strongly integrated in diff --git a/website/source/docs/internals/acl.html.markdown b/website/source/docs/internals/acl.html.markdown index 53b3857205..7750905445 100644 --- a/website/source/docs/internals/acl.html.markdown +++ b/website/source/docs/internals/acl.html.markdown @@ -189,3 +189,22 @@ This is equivalent to the following JSON input: } ``` +## Services and Checks with ACLs + +Consul allows configuring ACL policies which may control access to service and +check registration. In order to successfully register a service or check with +these types of policies in place, a token with sufficient privileges must be +provided to perform the registration into the global catalog. Consul also +performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which +may require an ACL token to complete. To accommodate this, Consul provides two +methods of configuring ACL tokens to use for registration events: + +1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration + directive. This allows a single token to be configured globally and used + during all service and check registration operations. +2. Providing an ACL token with service and check definitions at + registration time. This allows for greater flexibility and enables the use + of multiple tokens on the same agent. Examples of what this looks like are + available for both [services](/docs/agent/services.html) and + [checks](/docs/agent/checks.html). Tokens may also be passed to the + [HTTP API](/docs/agent/http.html) for operations that require them.