From 074e165442d84484d49f2658f05a6838b0ef9683 Mon Sep 17 00:00:00 2001 From: Karl Cardenas Date: Tue, 30 Nov 2021 14:10:22 -0700 Subject: [PATCH 1/2] adding manual cherry picks from previous failed merges --- .../config-entries/partition-exports.mdx | 210 +++++++++++ .../docs/connect/proxies/integrate.mdx | 41 +- .../registration/service-registration.mdx | 350 +++++++++++------- .../docs/enterprise/admin-partitions.mdx | 244 ++++++++++++ website/content/docs/k8s/crds/index.mdx | 24 +- website/data/docs-nav-data.json | 8 + 6 files changed, 724 insertions(+), 153 deletions(-) create mode 100644 website/content/docs/connect/config-entries/partition-exports.mdx create mode 100644 website/content/docs/enterprise/admin-partitions.mdx diff --git a/website/content/docs/connect/config-entries/partition-exports.mdx b/website/content/docs/connect/config-entries/partition-exports.mdx new file mode 100644 index 000000000000..94a61569d77c --- /dev/null +++ b/website/content/docs/connect/config-entries/partition-exports.mdx @@ -0,0 +1,210 @@ +--- +layout: docs +page_title: 'Configuration Entry Kind: Partition Exports' +description: >- + The partition-exports configuration entry enables you to export services from a single file. + Settings in this configuration entry can apply to services in any namespace of the specified partition. Write access to the mesh resource is required. +--- + +# Partition Exports + +This topic describes the `partition-exports` configuration entry type. The `partition-exports` configuration entry enables Consul to export service instances to other admin partitions from a single file. This enables your services to be networked across admin partitions. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. + +-> **v1.11.0+:** This config entry is supported in Consul versions 1.11.0+. + +## Introduction + +You can configure Consul to export services contained in an admin partition to one or more additional partitions by declaring the `partition-exports` configuration entry in the `kind` field. This enables you to route traffic between services in different clusters that share a single set of Consul servers. + +You can configure the settings defined in the `partition-exports` configuration entry to apply to all namespaces and federated datacenters. + +## Requirements + +* A Consul Enterprise binary +* A partition that corresponds to the configuration entry. As in, the partition exports config entry for partition "frontend" requires that the "frontend" partition exists + + +## Usage + +1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). +1. Specify the `partition-exports` configuration in the agent configuration file (see [`config_entries`](/docs/agent/options#config_entries)) as described in [Configuration](#configuration). +1. Apply the configuration using one of the following methods: + * Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. + * Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. + +## Configuration + +Configure the following parameters to define a `partition-exports` configuration entry: + + + + +```hcl +Kind = "partition-exports" +Partition = "" +Services = [ + { + Name = "" + Namespace = "" + Consumers = [ + { + Partition = "" + }, + ] + } +] +``` + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +Kind: PartitionExports +Partition: +Services: +- Consumers: + - Partition: + Name: + Namespace: +``` + + + +```json +"Kind": "partition-exports", +"Partition": "", +"Services": [ + { + "Consumers": [ + { + "Partition": "" + } + ], + "Name": "", + "Namespace": "" + } +] +``` + + + +### Configuration Parameters + +The following table describes the parameters associated with the `partition-exports` configuration entry. + +| Parameter | Description | Required | Default | +| --- | --- | --- | --- | +| `Kind` | String value that enables the configuration entry. The value should always be `partition-exports` (HCL and JSON) or `PartitionExports` (YAML) | Required | None | +| `Partition` | String value that specifies the name of the partition that contains the services you want to export. | Required | None | +| `Services` | List of objects that specify which services to export. See [`Services`](#services) for details. | Required | None| +| `Meta` | Object that defines a map of the max 64 key/value pairs. | Optional | None | + +#### `Services` + +The `Services` parameter contains one or more lists of parameters that specify which services to export, which namespaces the services reside, and the destination partition for the exported services. Each list in the `Services` block must contain the following parameters: + +* `Name`: Specifies the name of the service to export. You can use a asterisk wildcard (`*`) to include all services in the namespace. +* `Namespace`: Specifies the namespace containing the services to export. You can use a asterisk wildcard (`*`) to include all namespaces in the partition. +* `Consumers`: Specifies one ore more objects that identify a destination partition for the exported services. + +## Example + +The following example configures the agent to export the `billing` service from the `default` namespace of the `finance` admin partition to the `frontend` and `backend` partitions. Additionally, all services in all namespaces within the `finance` partition will be exported to the `monitoring` partition. + + + + +```hcl +Kind = "partition-exports" +Partition = "finance" + +Services = [ + { + Name = "billing" + Namespace = "default" + Consumers = [ + { + Partition = "frontend" + }, + { + Partition = "backend" + } + ] + }, + { + Name = "*" + Namespace = "*" + Consumers = [ + { + Partition = "monitoring" + } + ] + } +] +``` + + + + +```yaml +Kind: partition-exports +Partition: finance +Services: +- Consumers: + - Partition: frontend + - Partition: backend + Name: billing + Namespace: default +- Consumers: + - Partition: monitoring + Name: '*' + Namespace: '*' +``` + + + + +```json +"Kind": "partition-exports", + "Partition": "finance", + "Services": [ + { + "Consumers": [ + { + "Partition": "frontend" + }, + { + "Partition": "backend" + } + ], + "Name": "billing", + "Namespace": "default" + }, + { + "Consumers": [ + { + "Partition": "monitoring" + } + ], + "Name": "*", + "Namespace": "*" + } + ] +``` + + + + +## Reading Services + +When an exported service has been imported to another partition, you can use the `health` REST API endpoint to query the service on the consumer partition. The following example queries the `finance` partition for the imported `billing` service: + +```shell-session +$ curl 'localhost:8500/v1/health/connect/billing?partition=finance' +``` + +An ACL token with `service:write` permissions is required for the partition from which the query is made. If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request will require a token with `write` permissions to `web` in the `frontend` partition. + +Exports are available to all services in the consumer partition. In the previous example, any service with `write` permissions for the `frontend` partition will be able to read exports. + +See [Health HTTP Endpoint](/api-docs/health) for additional information. \ No newline at end of file diff --git a/website/content/docs/connect/proxies/integrate.mdx b/website/content/docs/connect/proxies/integrate.mdx index cd31114f5cca..7a6e0574d2e8 100644 --- a/website/content/docs/connect/proxies/integrate.mdx +++ b/website/content/docs/connect/proxies/integrate.mdx @@ -32,20 +32,24 @@ The proxy must accept TLS connections on some port to accept inbound connections Call the [`/v1/agent/connect/ca/leaf/`] API endpoint to obtain the client certificate, e.g.: -```shell-session - -curl http://:8500/v1/agent/connect/ca/leaf/ + +```shell +$ curl http://:8500/v1/agent/connect/ca/leaf/ ``` -The client certificate from the inbound connection must be validated against the Connect CA root certificates. Call the [`/v1/agent/connect/ca/roots`] endpoint to obtain the root certificates from the Connect CA, e.g.: + -```shell-session +The client certificate from the inbound connection must be validated against the Connect CA root certificates. Call the [`/v1/agent/connect/ca/roots`] endpoint to obtain the root certificates from the Connect CA, e.g.: -curl http://:8500/v1/agent/connect/ca/roots + +```shell +$ curl http://:8500/v1/agent/connect/ca/roots ``` + + ### Authorizing the connection After validating the client certificate from the caller, the proxy can authorize the entire connection (L4) or each request (L7). Depending upon the [protocol] of the proxied service, authorization is performed either on a per-connection (L4) or per-request (L7) basis. Authentication is based on "service identity" (TLS), and is implemented at the @@ -169,18 +173,43 @@ to read configurations for that service. If you use the Go [`api` package], then the environment variables will be read and the client configured for you automatically. +Alternatively, you may also use the flags `-token` or `-token-file` to provide the Consul ACL token. + + + + + +```shell +$ consul connect envoy -sidecar-for "web" -token-file=/etc/consul.d/consul.token +``` + + + + + +```shell +$ consul connect proxy -sidecar-for "web" -token-file=/etc/consul.d/consul.token +``` + + + + + If TLS is enabled on Consul, you will also need to add the following environment variables _prior_ to starting the proxy: - [`CONSUL_CACERT`](/commands#consul_cacert) - [`CONSUL_CLIENT_CERT`](/commands#consul_client_cert) - [`CONSUL_CLIENT_KEY`](/commands#consul_client_key) +The `CONSUL_CACERT`, `CONSUL_CLIENT_CERT` and `CONSUL_CLIENT_KEY` can also be provided as CLI flags. Refer to the [`consul connect proxy` documentation](/commands/connect/proxy) for details. + The proxy service ID comes from the user. See [`consul connect envoy`](/commands/connect/envoy#examples) for an example. You can use the `-proxy-id` flag to specify the ID of the proxy service you have already registered with the local agent. Alternatively, you can start the service using the `-sidecar-for=` option. This option queries Consul for a proxy that is registered as a sidecar for the specified ``. If exactly one service associated with the proxy is returned, the ID will be used to start the proxy. Your controller only needs to accept `-proxy-id` as an argument; the Consul CLI will resolve the ID for the name specified in `-sidecar-for` flag. + [`/v1/agent/connect/ca/leaf/`]: /api/agent/connect#service-leaf-certificate [`/v1/agent/connect/ca/roots`]: /api/agent/connect#certificate-authority-ca-roots [`/v1/health/connect/:service_id`]: /api/health#list-nodes-for-connect-capable-service diff --git a/website/content/docs/connect/registration/service-registration.mdx b/website/content/docs/connect/registration/service-registration.mdx index a40708f76bbf..92bcb1a93e19 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/registration/service-registration.mdx @@ -3,36 +3,77 @@ layout: docs page_title: Connect - Service Registration description: >- A per-service proxy sidecar transparently handles inbound and outbound service - connections. You can register these sidecars with sane defaults by nesting + connections. You can register these sidecars with reasonable defaults by nesting their definitions in the service definition. --- # Proxy Service Registration -To function as a Connect proxy, proxies must be declared as a proxy types in -their service definitions, and provide information about the service they -represent. +This topic describes how to declare a proxy as a `connect-proxy` in service definitions. The `kind` must be declared and information about the service they represent must be provided to function as a Consul service mesh proxy. -To declare a service as a proxy, the service definition must contain -the following fields: +## Configuration -- `kind` `(string)` must be set to `connect-proxy`. This declares that the - service is a proxy type. +Configure a service mesh proxy using the following syntax: -- `proxy.destination_service_name` `(string)` must be set to the service that - this proxy is representing. Note that this replaces `proxy_destination` in - versions 1.2.0 to 1.3.0. + + - ~> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was - specified using `proxy_destination` at the top level. This will continue to work - until at least 1.5.0 but it's highly recommended to switch to using - `proxy.destination_service_name`. +```hcl +name = +kind = "connect-proxy" +proxy = { + destination_service_name = "" + = "" +} +port = +``` + + + + +```json +{ + "name": "", + "kind": "connect-proxy", + "proxy": { + "destination_service_name": "", + "" : "" + }, + "port": +} +``` + + + + +The following table describes the parameters that must be added to the service definition to declare the service as a proxy. + +| Parameter | Description | Required | Default | +| --- | --- | --- | --- | +| `kind` | String value that declares the type for the service. This should always be set to `connect-proxy` to declare the services as a service mesh proxy. | Required | None | +| `proxy` | Object that contains the [proxies parameters](#proxy-parameters).
The `destination_service_name` parameter must be included in the `proxy` configuration. The `destination_service_name` parameter specifies the name of the services that the proxy represents.
This parameter replaces `proxy_destination` used in Consul 1.2.0 to 1.3.0. The `proxy_destination` parameter was deprecated in 1.5.0. | Required | None | +| `port` | Integer value that specifies the port where other services in the mesh can discover and connect to proxied services. | Required | None | +| `address` | Specifies the IP address of the proxy. | Optional
The address will be inherited from the node configuration. | `address` specified in the node configuration. | + +You can specify several additional parameters to configure the proxy to meet your requirements. See [Proxy Parameters](#proxy-parameters) for additional information. -- `port` `(int)` must be set so that other Connect services can discover the - exact address for connections. `address` is optional if the service is being - registered against an agent, since it'll inherit the node address. +### Example -Minimal Example: +In the following example, a proxy named `redis-proxy` is registered as a service mesh proxy. It proxies to the `redis` service and is available at port `8181`. As a result, any service mesh clients searching for a Connect-capable endpoint for `redis` will find this proxy. + + + + +```hcl +kind = "connect-proxy" +name = "redis-proxy" +port = 8181 +proxy = { + destination_service_name = "redis" +} +``` + + ```json { @@ -44,33 +85,50 @@ Minimal Example: "port": 8181 } ``` + + -With this service registered, any Connect clients searching for a -Connect-capable endpoint for "redis" will find this proxy. -### Sidecar Proxy Fields +### Sidecar Proxy Configuration -Most Connect proxies are deployed as "sidecars" which means they are co-located -with a single service instance which they represent and proxy all inbound -traffic to. In this case the following fields should also be set if you are deploying your proxy as a sidecar but defining it in its own service registration: +Many service mesh proxies are deployed as sidecars. +Sidecar proxies are co-located with the single service instance they represent and proxy all inbound traffic to. -- `proxy.destination_service_id` `(string: )` is set to the _id_ - (and not the _name_ if they are different) of the specific service instance - that is being proxied. The proxied service is assumed to be registered on - the same agent although it's not strictly validated to allow for - un-coordinated registrations. +Specify the following parameters in the `proxy` code block to configure a sidecar proxy in its own service registration: -- `proxy.local_service_port` `(int: )` must specify the port the - proxy should use to connect to the _local_ service instance. +* `destination_service_id`: String value that specifies the ID of the service being proxied. Refer to the [proxy parameters reference](#destination-service-id) for details. +* `local_service_port`: Integer value that specifes the port that the proxy should use to connect to the _local_ service instance. Refer to the [proxy parameters reference](#local-service-port) for details. +* `local_service_address`: String value that specifies the IP address or hostname that the proxy should use to connect to the _local_ service. Refer to the [proxy parameters reference](#local-service-address) for details. -- `proxy.local_service_address` `(string: "")` can be set to override the IP or - hostname the proxy should use to connect to the _local_ service. Defaults to - `127.0.0.1`. +See (Sidecar Service Registration)[/docs/connect/registration/sidecar-service] for additional information about configuring service mesh proxies as sidecars. ### Complete Configuration Example -The following is a complete example showing all the options available when -registering a proxy instance. +The following example includes values for all availble options when registering a proxy instance. + + + + +```hcl +kind = "connect-proxy" +name = "redis-proxy" +port = 8181 +proxy = { + config = {} + destination_service_id = "redis1" + destination_service_name = "redis" + expose = {} + local_service_address = "127.0.0.1" + local_service_port = 9090 + local_service_socket_path = "/tmp/redis.sock" + mesh_gateway = {} + mode = "transparent" + transparent_proxy = {} + upstreams = [] +``` + + + ```json { @@ -92,77 +150,68 @@ registering a proxy instance. "port": 8181 } ``` + + + +### Proxy Parameters -#### Proxy Parameters - -- `destination_service_name` `(string: )` - Specifies the _name_ of the - service this instance is proxying. Both side-car and centralized - load-balancing proxies must specify this. It is used during service - discovery to find the correct proxy instances to route to for a given service - name. - -- `destination_service_id` `(string: "")` - Specifies the _ID_ of a single - specific service instance that this proxy is representing. This is only valid - for side-car style proxies that run on the same node. It is assumed that the - service instance is registered via the same Consul agent so the ID is unique - and has no node qualifier. This is useful to show in tooling which proxy - instance is a side-car for which application instance and will enable - fine-grained analysis of the metrics coming from the proxy. - -- `local_service_address` `(string: "")` - Specifies the address a side-car - proxy should attempt to connect to the local application instance on. - Defaults to 127.0.0.1. - -- `local_service_port` `(int: )` - Specifies the port a side-car - proxy should attempt to connect to the local application instance on. - Defaults to the port advertised by the service instance identified by - `destination_service_id` if it exists otherwise it may be empty in responses. - -- `local_service_socket_path` - The path of a Unix domain socket to connect to the local application - instance. This is created by the application. This conflicts with `local_service_address` - and `local_service_port`. This is only supported when using Envoy for the proxy. - -- `mode` `(string: "")` Beta - One of \`direct\` or \`transparent\`. Added in v1.10.0. - - `"transparent"` - represents that inbound and outbound application traffic is being - captured and redirected through the proxy. This mode does not enable the traffic redirection - itself. Instead it signals Consul to configure Envoy as if traffic is already being redirected. - - `"direct"` - represents that the proxy's listeners must be dialed directly by the local - application and other proxies. - - `""` - Default mode. The default mode will be `"direct"` if no other configuration - applies. The order of precedence for setting the mode is - 1. Proxy Service's `Proxy` configuration - 2. The `service-defaults` configuration for the service. - 3. The `global` `proxy-defaults`. - -- `transparent_proxy` `(object: {})` Beta - Specifies the configuration specific to proxies in `transparent` mode. - The format is defined in the [Transparent Proxy Configuration Reference](#transparent-proxy-configuration-reference). - Added in v1.10.0. - -- `config` `(object: {})` - Specifies opaque config JSON that will be - stored and returned along with the service instance from future API calls. - -- `upstreams` `(array: [])` - Specifies the upstream services - this proxy should create listeners for. The format is defined in - [Upstream Configuration Reference](#upstream-configuration-reference). - -- `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration - for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference). - -- `expose` `(object: {})` - Specifies the configuration to expose HTTP paths through this proxy. - The format is defined in the [Expose Paths Configuration Reference](#expose-paths-configuration-reference), - and is only compatible with an Envoy proxy. +The following table describes all parameters that can be defined in the `proxy` block. + +| Parameter | Description | Required | Default | +| --- | --- | --- | --- | +| `destination_service_id` | String value that specifies the ID of a single service instance represented by the proxy.
This parameter is only applicable for sidecar proxies that run on the same node as the service.
Consul checks for the proxied service on the same agent.
The ID is unique and may differ from its `name` value.
Specifying this parameter helps tools identify which sidecar proxy instances are associated with which application instance, as well as enable fine-grained analysis of the metrics coming from the proxy.| Required when registering proxy as a sidecar | None | +| `local_service_port` | Integer value that specifes the port that a sidecar proxy should use to connect to the _local_ service instance. | Required when registering proxy as a sidecar | Port advertised by the service instance configured in `destination_service_id` | +| `local_service_address` | String value that specifies the IP address or hostname that a sidecar proxy should use to connect to the _local_ service. | Optional | `127.0.0.1` | +| `destination_service_name` | String value that specifies the _name_ of the service the instance is proxying. The name is used during service discovery to route to the correct proxy instances for a given service name. | Required | None | +| `local_service_socket_path` | String value that specifies the path of a Unix domain socket for connecting to the local application instance.
This parameter value is created by the application and conflicts with `local_service_address` and `local_service_port`.
Supported when using Envoy for the proxy. | Optional | None | +| `mode` | String value that specifies the proxy mode. See [Proxy Modes](#proxy-modes) for additional information. | Optional | `direct` | +| `transparent_proxy` | Object value that specifies the configuration specific to proxies in `transparent` mode.
See [Proxy Modes](#proxy-modes) and [Transparent Proxy Configuration Reference](#transparent-proxy-configuration-reference) for additional information.
This parameter was added in Consul 1.10.0. | Optional | None | +| `config` | Object value that specifies an opaque JSON configuration. The JSON is stored and returned along with the service instance when called from the API. | Optional | None | +| `upstreams` | An array of objects that specify the upstream services that the proxy should create listeners for. Refer to [Upstream Configuration Reference](#upstream-configuration-reference) for details. | Optional | None | +| `mesh_gateway` | Object value that specifies the mesh gateway configuration for the proxy. Refer to [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference) for details. | Optional | None | +| `expose` | Object value that specifies a configuration for exposing HTTP paths through the proxy.
This parameter is only compatible with Envoy proxies.
Refer to [Expose Paths Configuration Reference](#expose-paths-configuration-reference) for details. | Optional | None | ### Upstream Configuration Reference -The following examples show all possible upstream configuration parameters. +You can configure the service mesh proxy to create listeners for upstream services. The listeners enable the upstream service to accept requests. You can specify the following parameters to configure upstream service listeners. --> Note that `snake_case` is used here as it works in both [config file and API -registrations](/docs/agent/services#service-definition-parameter-case). +| Parameter | Description | Required | Defautl | +| --- | --- | --- | --- | +|`destination_name` | String value that specifies the name of the service or prepared query to route the service mesh to. The prepared query should be the name or the ID of the prepared query. | Required | None | +| `destination_namespace` | String value that specifies the namespace containing the upstream service. | Optional | `default` | +| `destination_partition` | String value that specifies the name of the admin partition containing the upstream service. | Optional | `default` | +| `local_bind_port` | Integer value that specifies the port to bind a local listener to. The application will make outbound connections to the upstream from the local port. | Required | None | +| `local_bind_address` | String value that specifies the address to bind a local listener to. The application will make outbound connecttions to the upstream service from the local bind address. | Optional | `127.0.0.1` | +| `local_bind_socket_path` | String value that specifies the path at which to bind a Unix domain socket listener. The application will make outbound connections to the upstream from the local bind socket path.
This parameter conflicts with the `local_bind_port` or `local_bind_address` parameters.
Supported when using Envoy as a proxy. | Optional | None| +| `local_bind_socket_mode` | String value that specifies a Unix octal that configures file permissions for the socket. | Optional | None | +| `destination_type` | String value that specifies the type of discovery query the proxy should use for finding service mesh instances. The following values are supported:
  • `service`: Queries for upstream `service` types.
  • `prepared_query`: Queries for upstream prepared queries.
    • | Optional | `service` | +| `datacenter` | String value that specifies the datacenter to issue the discovery query to. | Optional | Defaults to the local datacenter. | +| `config` | Object value that specifies opaque configuration options that will be provided to the proxy instance for the upstream.
    Valid JSON objects are also suppported.
    The `config` parameter can specify timeouts, retries, and other proxy-specific features for the given upstream.
    See the [built-in proxy configuration reference](/docs/connect/proxies/built-in#proxy-upstream-config-key-reference) for configuration options when using the built-in proxy.
    If using Envoy as a proxy, see [Envoy configuration reference](/docs/connect/proxies/envoy#proxy-upstream-config-options) | Optional | None | +| `mesh_gateway` | Object that defines the mesh gateway configuration for the proxy. Refer to the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference) for configuration details. | Optional | None | + +### Upstream Configuration Examples + +Upstreams support multiple destination types. The following examples include information about each implmentation. -Upstreams support multiple destination types. Both examples are shown below -followed by documentation for each attribute. +-> **Snake case**: The examples in this topic use `snake_case` because the syntax is supported in configuration files and API registrations. See [Service Definition Parameter Case](/docs/agent/services#service-definition-parameter-case) for additional information. -#### Service Destination + + + +```hcl +destination_type = "service" +destination_name = "redis" +datacenter = "dc1" +local_bind_address = "127.0.0.1" +local_bind_port = 1234 +local_bind_socket_path = "/tmp/redis_5678.sock" +local_bind_socket_mode = "0700" +mesh_gateway = { + mode = "local" + } +``` + + ```json { @@ -173,14 +222,28 @@ followed by documentation for each attribute. "local_bind_port": 1234, "local_bind_socket_path": "/tmp/redis_5678.sock", "local_bind_socket_mode": "0700", - "config": {}, "mesh_gateway": { "mode": "local" } }, ``` -#### Prepared Query Destination + + + + + + +```hcl +destination_type = "prepared_query" +destination_name = "database" +local_bind_address = "127.0.0.1" +local_bind_port = 1234 +config = {} +``` + + + ```json { @@ -191,41 +254,52 @@ followed by documentation for each attribute. "config": {} }, ``` + + + + + + + +```hcl +destination_partition = "finance" +destination_namespace = "default" +destination_type = "service" +destination_name = "billing" +local_bind_port = 9090 +``` + + + +```json +{ + "destination_partition": "finance", + "destination_namespace": "default", + "destination_type": "service", + "destination_name": "billing", + "local_bind_port": 9090 +} +``` + + + + +## Proxy Modes + +You can configure which mode a proxy operates in by specifying `"direct"` or `"transparent"` in the `mode` parameter. The proxy mode determines the how proxies direct traffic. This feature was added in Consul 1.10.0. + +* `transparent`: In this mode, inbound and outbound application traffic is captured and redirected through the proxy. This mode does not enable the traffic redirection. It directs Consul to configure Envoy as if traffic is already being redirected. +* `direct`: In this mode, the proxy's listeners must be dialed directly by the local application and other proxies. + +You can also specify an empty string (`""`), which configures the proxy to operate in the default mode. The default mode is inherited from parent parameters in the following order of precedence: + +1. Proxy service's `Proxy` configuration +1. The `service-defaults` configuration for the service. +1. The `global` `proxy-defaults`. + +The proxy will default to `direct` mode if a mode cannot be determined from the parent parameters. -- `destination_name` `(string: )` - Specifies the name of the service - or prepared query to route connect to. The prepared query should be the name - or the ID of the prepared query. -- `destination_namespace` `(string: "")` - - Specifies the namespace of the upstream service. -- `local_bind_port` `(int: )` - Specifies the port to bind a local - listener to for the application to make outbound connections to this upstream. -- `local_bind_address` `(string: "")` - Specifies the address to bind a - local listener to for the application to make outbound connections to this - upstream. Defaults to `127.0.0.1`. -- `local_bind_socket_path` `(string: "")` - Specifies the path at which to bind a Unix - domain socket listener for the application to make outbound connections to - this upstream. This conflicts with specifying the local_bind_port - or local_bind_address. This is only supported when using Envoy as a proxy. -- `local_bind_socket_mode` `(string: "")` - Specifies the (optional) Unix octal - file permissions to use for the socket. -- `destination_type` `(string: "")` - Specifies the type of discovery - query to use to find an instance to connect to. Valid values are `service` or - `prepared_query`. Defaults to `service`. -- `datacenter` `(string: "")` - Specifies the datacenter to issue the - discovery query to. Defaults to the local datacenter. -- `config` `(object: {})` - Specifies opaque configuration options that - will be provided to the proxy instance for this specific upstream. Can contain - any valid JSON object. This might be used to configure proxy-specific features - like timeouts or retries for the given upstream. See the [built-in proxy - configuration - reference](/docs/connect/proxies/built-in#proxy-upstream-config-key-reference) for - options available when using the built-in proxy. If using Envoy as a proxy, - see [Envoy configuration - reference](/docs/connect/proxies/envoy#proxy-upstream-config-options) -- `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration - for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference). - -### Transparent Proxy Configuration Reference Beta +### Transparent Proxy Configuration Reference The following examples show additional configuration for transparent proxies. @@ -375,7 +449,7 @@ registrations](/docs/agent/services#service-definition-parameter-case). but the proxy registration will not fail. - `protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`. -### Unix Domain Sockets Beta +### Unix Domain Sockets The following examples show additional configuration for Unix domain sockets. diff --git a/website/content/docs/enterprise/admin-partitions.mdx b/website/content/docs/enterprise/admin-partitions.mdx new file mode 100644 index 000000000000..b00ac189fc0d --- /dev/null +++ b/website/content/docs/enterprise/admin-partitions.mdx @@ -0,0 +1,244 @@ +--- +layout: docs +page_title: Consul Enterprise Admin Partitions +description: Consul Enterprise enables you to create paritions that can be administrated across namespaces. +--- + +# Consul Enterprise Admin Partitions + + + This feature requires{' '} +     Consul Enterprise{' '} + with the Governance and Policy module. + + +This topic provides and overview of admin partitions, which are entities that define one or more administrative boundaries for single Consul deployments. + +## Introduction + +Admin partitions exist a level above namespaces in the identity hierarchy. They contain one or more namespaces and allow multiple independent tenants to share a Consul server cluster. As a result, admin partitions enable you to define administrative and communication boundaries between services managed by separate teams or belonging to separate stakeholders. They can also segment production and non-production services within the Consul deployment. + +-> **Preexisting resource nodes and namespaces**: Admin partitions were introduced in Consul 1.11. Resource nodes were not namespaced prior to 1.11. After upgrading to Consul 1.11 or later, all resource nodes will be namespaced. + +### Default Admin Partition + +Each Consul cluster will have at least one default admin partition (named `default`). Any resource created without specifying an admin partition will inherit the partition of the ACL token. + +The `default` admin partition is special in that it may contain namespaces and other entities that are replicated between datacenters. The `default` partition must also contain the Consul servers. + +-> **Preexisting resources and the `default` partition**: Admin partitions were introduced in Consul 1.11. After upgrading to Consul 1.11 or later, the `default` partition will contain all resources created in previous versions. + +### Naming Admin Partitions + +Only characters that are valid in DNS names can be used to name admin partitions. +Names must also start with a letter. + +### Namespaces + +When an admin partition is created, it will include a `default` namespace. You can create additional namespaces within the partition. + +All namespaces must exist within an admin partition. By extension, the partition will also contain all namespaced resources. + +Within a single datacenter, a namespace in one admin partition is logically separate from any other namespace with the same name in other admin partitions. + +### Cross-datacenter Replication + +Only resources in the default admin partition will be replicated to secondary datacenters. Non-default partitions are currently not supported in secondary datacenters. + +### DNS Queries + +Client agents will be configured to operate within a specific admin partition. The DNS interface will only return results for the admin partition within the scope of the client. + +### Service Mesh Configurations + +Values specified for [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) configurations are scoped to a specific partition. Services registered in the partition will use the partition's `proxy-defaults` values. + +### Cross-partition Networking + +You can configure services to be discoverable and accessible by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the `partition-exports` configuration entry in the partition where the services are registered. Refer to the [`partition-exports` documentation](/docs/connect/config-entries/partition-exports) for details. + +Additionally, the `upstreams` configuration for proxies in the source partition must specify the name of the destination partition so that listeners can be created. Refer to the [Upstream Configuration Reference](/docs/connect/registration/service-registration#upstream-configuration-reference) for additional information. + +## Requirements + +Your Consul configuration must meet the following requirements to use admin partitions. + +### Versions + +* Consul 1.11.0 and newer + +### Security Configurations + +* The agent token used by the client agent will need to allow `node:write` in the admin partition. +* The `write` permission for `proxy-defaults` requires `mesh:write`. See [Admin Partition Rules](/docs/security/acl/acl-rules#admin-partition-rules) for additional information. +* The `write` permissions for ingress and terminating gateways require `mesh:write` privileges. +* Wildcards (`*`) are not supported when creating intentions for admin partitions, but you can use a wildcard to specify services within a partition. +* With the exception of the `default` admin partition, ACL rules configured for admin partitions are isolated, so policies defined in partitions outside of the `default` partition can only reference their local partition. + +### Agent Configurations + +* In client agent configurations, the admin partition name should be specified in the agent configuration: + + ```hcl + partition = "" + ``` +* The anti-entropy sync will use the configured admin partition name when registering the node. + +### Kubernetes Requirements + +One of the primary use cases for admin partitions is for enabling a service mesh on Kubernetes clusters. The following requirements must be met to create admin partitions on Kubernetes: + +* Two or more Kubernetes clusters. Consul servers must be deployed on one of the clusters. The other clusters should run Consul clients. +* A Consul Enterprise license must be installed on each instance of Consul. +* The helm chart for consul-k8s v0.34.1 or greater. +* Consul 1.11.0-ent-alpha or greater. +* All Consul clients in the VPC must be able to communicate with the Consul servers. +* VPC firewall rules should be implemented that enable clients to communicate with the Consul servers in the `default` partition. The server nodes should be deployed to a single cluster. + +## Usage + +This section describes how to deploy Consul admin partitions to Kubernetes clusters, as well as directs you to the CLI reference for interacting with the admin partitions API on the command line. + +### Deploying Consul with Admin Partitions on Kubernetes + +The expected use case is to create admin partitions on Kubernetes clusters. This is because many organizations prefer to use cloud-managed Kubernetes offerings to provision separate Kubernetes clusters for individual teams, business units, or environments. This is opposed to deploying a single, large Kubernetes cluster. When these organizations attempt to use a service mesh to enable cross-cluster activities, such as administration tasks and communication between nodes, they encounter problems. + +The following procedure will result in a different admin partition in each Kubernetes cluster. The Consul clients running in the cluster with servers will be in the `default` partition. Another partition called `clients` will also be created. + +Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernetes-requirements) before proceeding. + +1. Update the firewall rules so that pods containing Consul clients and pods containing Consul servers can send and receive traffic. Refer to your virtual cloud provider's documentation for instructions on how to configure firewall rules. +1. Create the license secret in each cluster, e.g.: + + ```shell-session + kubectl create secret generic license --from-file=key=[license file path i.e. ./license.hclic] + ``` + This step must also be completed for each workload cluster. + +1. Create a server configuration file to override the default Consul Helm chart settings: + + + + + ```yaml + global: + enableConsulNamespaces: true + tls: + enabled: true + image: hashicorp/consul-enterprise:1.11.0-ent-beta3 + adminPartitions: + enabled: true + enterpriseLicense: + secretName: consul-ent-license + secretKey: key + server: + exposeGossipAndRPCPorts: true + connectInject: + enabled: true + transparentProxy: + defaultEnabled: false + consulNamespaces: + mirroringK8S: true + controller: + enabled: true + ``` + + + + Note that the `transparentProxy` configuration is disabled. This is to enable multi-cluster networking. + +1. Start the Consul server(s) using the custom configuration file: + ```shell-session + helm install server hashicorp/consul -f server.yaml + ``` +1. After the server starts, get the external IP address for partition service so that it can be added to the client configuration. The partition service is a `LoadBalancer` type. The IP address is where clients that across your partitions will communicate with servers in this cluster. + + ```shell-session + kubectl get service + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + kubernetes ClusterIP 10.8.0.1 443/TCP 77m + server-consul-connect-injector-svc ClusterIP 10.8.13.188 443/TCP 76s + server-consul-controller-webhook ClusterIP 10.8.14.178 443/TCP 77s + server-consul-dns ClusterIP 10.8.6.6 53/TCP,53/UDP 77s + server-consul-partition-service LoadBalancer 10.8.1.186 34.135.103.67 8501:31130/TCP,8301:31587/TCP,8300:30378/TCP 76s + server-consul-server ClusterIP None 8501/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP 76s + server-consul-ui ClusterIP 10.8.0.218 443/TCP 77s + ``` +1. Get the Kubernetes authentication method URL for the workload cluster: + + ```shell-session + kubectl config view -o "jsonpath={.clusters[?(@.name=='')].cluster.server}" + ``` + Use the IP address printed to the console to configure the `k8sAuthMethodHost` parameter in the workload configuration file for your client nodes. + +1. Create the workload configuration for client nodes in your cluster. Create a configuration for each admin partition. In the following example, the external IP address and the Kubernetes authentication method IP address from the previous steps have been applied: + + + + + ```yaml + global: + enabled: false + enableConsulNamespaces: true + image: hashicorp/consul-enterprise:1.11.0-ent-beta3 + adminPartitions: + enabled: true + name: "clients" + tls: + enabled: true + caCert: + secretName: consul-consul-ca-cert + secretKey: tls.crt + caKey: + secretName: consul-consul-ca-key + secretKey: tls.key + enterpriseLicense: + secretName: license + secretKey: key + externalServers: + enabled: true + hosts: [ "34.135.103.67" ] + tlsServerName: server.dc1.consul + k8sAuthMethodHost: "104.154.156.146" + client: + enabled: true + exposeGossipPorts: true + join: [ "34.135.103.67" ] + connectInject: + enabled: true + consulNamespaces: + mirroringK8S: true + controller: + enabled: true + meshGateway: + enabled: true + ``` + + + +1. Copy the server certificate to the workload cluster. + + ```shell-session + kubectl get secret server-consul-ca-cert --context -o yaml | kubectl apply --context -f - + ``` + +1. Copy the server key to the workload cluster. + + ```shell-session + kubectl get secret server-consul-ca-key --context -o yaml | kubectl apply --context -f - + ``` +1. Start the workload client clusters: + + ```shell-session + helm install client hashicorp/consul -f client.yaml + ``` + +### CLI Usage + +You can use create and manage admin partitions through the CLI. Refer to the [admin partition CLI documentation](/commands/admin-partition) for details. + +## Known Limitations + +* Gossip between nodes in different admin partitions must be constrained. You can accomplish this with through the use of [network segments](network-segments). +* Cross-partition communication is not currently supported. +* Partitions can only be created in the primary datacenter. diff --git a/website/content/docs/k8s/crds/index.mdx b/website/content/docs/k8s/crds/index.mdx index 4711c2d3a81e..8364c22d327a 100644 --- a/website/content/docs/k8s/crds/index.mdx +++ b/website/content/docs/k8s/crds/index.mdx @@ -9,27 +9,33 @@ description: >- # Custom Resource Definitions --> This feature requires consul-helm >= 0.28.0, consul-k8s >= 0.22.0 and consul >= 1.8.4. +This topic describes how to manage Consul [configuration entries](/docs/agent/config-entries) +via Kubernetes Custom Resources. Configuration entries provide cluster-wide defaults for the service mesh. -We support managing Consul [configuration entries](/docs/agent/config-entries) -via Kubernetes Custom Resources. Configuration entries are used to provide -cluster-wide defaults for the service mesh. +## Requirements -We currently support the follow configuration entry kinds: +* consul-helm 0.28.0 or later +* consul-k8s 0.22.0 or later +* consul 1.8.4 or later; some configuration entries require a newer version of Consul -- [`Mesh`](/docs/connect/config-entries/mesh) (requires Consul >= 1.10.0) +## Supported Configuration Entries + +You can specify the following values in the `kind` field. Click on a configuration entry to view its documentation: + +- [`Mesh`](/docs/connect/config-entries/mesh) (requires Consul 1.10.0+) +- [`PartitionExports`](/docs/connect/config-entries/partition-exports) - [`ProxyDefaults`](/docs/connect/config-entries/proxy-defaults) - [`ServiceDefaults`](/docs/connect/config-entries/service-defaults) - [`ServiceSplitter`](/docs/connect/config-entries/service-splitter) - [`ServiceRouter`](/docs/connect/config-entries/service-router) - [`ServiceResolver`](/docs/connect/config-entries/service-resolver) -- [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) (requires Consul >= 1.9.0) +- [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) (requires Consul 1.9.0+) - [`IngressGateway`](/docs/connect/config-entries/ingress-gateway) - [`TerminatingGateway`](/docs/connect/config-entries/terminating-gateway) ## Installation -Ensure you have at least version `0.28.0` of the helm chart: +Verify that the minimum version of the helm chart (`0.28.0`) is installed: ```shell-session $ helm search repo hashicorp/consul @@ -37,7 +43,7 @@ NAME CHART VERSION APP VERSION DESCRIPTION hashicorp/consul 0.28.0 1.9.1 Official HashiCorp Consul Chart ``` -If you don't have `0.28.0`, you will need to update your helm repository cache: +Update your helm repository cache if necessary: ```shell-session $ helm repo update diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 9e511fc19fe0..c081d0fbfcd1 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -150,6 +150,10 @@ "title": "Mesh", "path": "connect/config-entries/mesh" }, + { + "title": "Partition Exports", + "path": "connect/config-entries/partition-exports" + }, { "title": "Proxy Defaults", "path": "connect/config-entries/proxy-defaults" @@ -842,6 +846,10 @@ "title": "Overview", "path": "enterprise" }, + { + "title": "Admin Partitions BETA", + "path": "enterprise/admin-partitions" + }, { "title": "Audit Logging", "path": "enterprise/audit-logging" From f912dba24609899c0f4e2ac1fff747e22c371b90 Mon Sep 17 00:00:00 2001 From: Karl Cardenas Date: Tue, 30 Nov 2021 14:37:43 -0700 Subject: [PATCH 2/2] fix: removed acl-legacy.mdx from the root of api-docs folder as it's not needed --- website/content/api-docs/acl-legacy.mdx | 421 ------------------------ 1 file changed, 421 deletions(-) delete mode 100644 website/content/api-docs/acl-legacy.mdx diff --git a/website/content/api-docs/acl-legacy.mdx b/website/content/api-docs/acl-legacy.mdx deleted file mode 100644 index 678b60ce3238..000000000000 --- a/website/content/api-docs/acl-legacy.mdx +++ /dev/null @@ -1,421 +0,0 @@ ---- -layout: api -page_title: Legacy ACLs - HTTP API -description: >- - The /acl endpoints create, update, destroy, and query Legacy ACL tokens in - Consul. ---- - --> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_ -recommended you do not build anything using the legacy system and consider using -the new ACL [Token](/docs/api/acl-token) and [Policy](/docs/api/acl-policy) APIs instead. - -# ACL HTTP API - -These `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. For more information about ACLs, please check the -[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). - -## Bootstrap ACLs - -This endpoint does a special one-time bootstrap of the ACL system, making the first -management token if the [`acl_master_token`](/docs/agent/options#acl_master_token) -is not specified in the Consul server configuration, and if the cluster has not been -bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all -Consul servers to be upgraded in order to operate. - -This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's -configuration files. - -| Method | Path | Produces | -| ------ | ---------------- | ------------------ | -| `PUT` | `/acl/bootstrap` | `application/json` | - -The table below shows this endpoint's support for -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `NO` | `none` | `none` | `none` | - -### Sample Request - -```shell-session -$ curl \ - --request PUT \ - http://127.0.0.1:8500/v1/acl/bootstrap -``` - -### Sample Response - -```json -{ - "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" -} -``` - -You can detect if something has interfered with the ACL bootstrapping process by -checking the response code. A 200 response means that the bootstrap was a success, and -a 403 means that the cluster has already been bootstrapped, at which point you should -consider the cluster in a potentially compromised state. - -The returned token will be a management token which can be used to further configure the -ACL system. Please check the -[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details. - -## Create ACL Token - -This endpoint makes a new ACL token. - -| Method | Path | Produces | -| ------ | ------------- | ------------------ | -| `PUT` | `/acl/create` | `application/json` | - -The table below shows this endpoint's support for -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `NO` | `none` | `none` | `management` | - -### Parameters - -- `ID` `(string: "")` - Specifies the ID of the ACL. If not provided, a UUID is - generated. - -- `Name` `(string: "")` - Specifies a human-friendly name for the ACL token. - -- `Type` `(string: "client")` - Specifies the type of ACL token. Valid values - are: `client` and `management`. - -- `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the - `Rules` property is documented in the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). - -### Sample Payload - -```json -{ - "Name": "my-app-token", - "Type": "client", - "Rules": "" -} -``` - -### Sample Request - -```shell-session -$ curl \ - --request PUT \ - --data @payload.json \ - http://127.0.0.1:8500/v1/acl/create -``` - -### Sample Response - -```json -{ - "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" -} -``` - -## Update ACL Token - -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 -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `NO` | `none` | `none` | `management` | - -### Parameters - -The parameters are the same as the _create_ endpoint, except the `ID` field is -required. - -### Sample Payload - -```json -{ - "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", - "Name": "my-app-token-updated", - "Type": "client", - "Rules": "# New Rules" -} -``` - -### Sample Request - -```shell-session -$ curl \ - --request PUT \ - --data @payload.json \ - http://127.0.0.1:8500/v1/acl/update -``` - -### 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 false, indicating whether the delete succeeded. - -The table below shows this endpoint's support for -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `NO` | `none` | `none` | `management` | - -### Parameters - -- `uuid` `(string: )` - Specifies the UUID of the ACL token to - destroy. This is required and is specified as part of the URL path. - -### Sample Request - -```shell-session -$ curl \ - --request PUT \ - http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 -``` - -### Sample Response - -```text -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 -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `YES` | `all` | `none` | `none` | - -Note: No ACL is required because the ACL is specified in the URL path. - -### Parameters - -- `uuid` `(string: )` - Specifies the UUID of the ACL token to - read. This is required and is specified as part of the URL path. - -### Sample Request - -```shell-session -$ curl \ - http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 -``` - -### Sample Response - -```json -[ - { - "CreateIndex": 3, - "ModifyIndex": 3, - "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05", - "Name": "Client Token", - "Type": "client", - "Rules": "..." - } -] -``` - -## Clone ACL Token - -This endpoint clones an ACL and returns a new token `ID`. This allows a token to -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 -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `NO` | `none` | `none` | `management` | - -### Parameters - -- `uuid` `(string: )` - Specifies the UUID of the ACL token to - be cloned. This is required and is specified as part of the URL path. - -### Sample Request - -```shell-session -$ curl \ - --request PUT \ - http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 -``` - -### Sample Response - -```json -{ - "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" -} -``` - -## List ACLs - -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 -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `YES` | `all` | `none` | `management` | - -### Sample Request - -```shell-session -$ curl \ - http://127.0.0.1:8500/v1/acl/list -``` - -### Sample Response - -```json -[ - { - "CreateIndex": 3, - "ModifyIndex": 3, - "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05", - "Name": "Client Token", - "Type": "client", - "Rules": "..." - } -] -``` - -## Check ACL Replication - -This endpoint returns the status of the ACL replication process in the -datacenter. This is intended to be used by operators, or by automation checking -the health of ACL replication. - -Please check the [ACL Replication tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters) -for more details. - -| Method | Path | Produces | -| ------ | ------------------ | ------------------ | -| `GET` | `/acl/replication` | `application/json` | - -The table below shows this endpoint's support for -[blocking queries](/api/features/blocking), -[consistency modes](/api/features/consistency), -[agent caching](/api/features/caching), and -[required ACLs](/api#authentication). - -| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | -| ---------------- | ----------------- | ------------- | ------------ | -| `NO` | `consistent` | `none` | `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. - -### Sample Request - -```shell-session -$ curl \ - http://127.0.0.1:8500/v1/acl/replication -``` - -### Sample Response - -```json -{ - "Enabled": true, - "Running": true, - "SourceDatacenter": "dc1", - "ReplicatedIndex": 1976, - "LastSuccess": "2016-08-05T06:28:58Z", - "LastError": "2016-08-05T06:28:28Z" -} -``` - -- `Enabled` reports whether ACL replication is enabled for the datacenter. - -- `Running` reports whether the ACL replication process is running. The process - may take approximately 60 seconds to begin running after a leader election - occurs. - -- `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being - replicated from, and will match the - [`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration. - -- `ReplicatedIndex` is the last index that was successfully replicated. You can - compare this to the `X-Consul-Index` header returned by the - [`/v1/acl/list`](#list-acls) endpoint to determine if the replication process - has gotten all available ACLs. Replication runs as a background process - approximately every 30 seconds, and that local updates are rate limited to 100 - updates/second, so so it may take several minutes to perform the initial sync - of a large set of ACLs. After the initial sync, replica lag should be on the - order of about 30 seconds. - -- `LastSuccess` is the UTC time of the last successful sync operation. Since ACL - replication is done with a blocking query, this may not update for up to 5 - minutes if there have been no ACL changes to replicate. A zero value of - "0001-01-01T00:00:00Z" will be present if no sync has been successful. - -- `LastError` is the UTC time of the last error encountered during a sync - operation. If this time is later than `LastSuccess`, you can assume the - replication process is not in a good state. A zero value of - "0001-01-01T00:00:00Z" will be present if no sync has resulted in an error.