status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

[docs] Reorganize connect documentation for clarity (#5864) 

* clarify possibilities for centralized proxy configuration

* add line breaks to config entries file

* add info about centralized config to built in proxy doc

* mondify connect landing page to help with navigation

* move internals details to its own page

* link fixes and shortening text on main page

* put built-in proxy options on its own page

* add configuration details for connect

* clarify security title and add observability page

* reorganize menu

* remove observability from configuration section

* Update website/source/docs/connect/configuration.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* Update website/source/docs/connect/index.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* Update website/source/docs/agent/config_entries.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* Update website/source/docs/connect/configuration.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* rename connect section to include service mesh

* reorganize sections per suggestions from paul

* add configuration edits from paul

* add internals edits from paul

* add observability edits from paul

* reorganize pages and menu

* Update website/source/docs/connect/configuration.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* menu corrections and edits

* incorporate some of pauls comments

* incorporate more of pauls comments

* Update website/source/docs/connect/configuration.html.md

Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>

* Update website/source/docs/connect/index.html.md

Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>

* Update website/source/docs/connect/index.html.md

Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>

* Update website/source/docs/connect/registration.html.md

Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>

* incorporate kaitlin and pavanni feedback

* add redirect

* fix conflicts in index file

* Resolve conflicts in index file

* correct links for new organization

* Update website/source/docs/connect/proxies.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* Update website/source/docs/connect/registration.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* Update website/source/docs/connect/registration.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* Update website/source/docs/connect/registration.html.md

Co-Authored-By: Paul Banks <banks@banksco.de>

* add title to service registration page
This commit is contained in:
Judith Malnick 2019-06-13 22:52:50 -07:00 committed by GitHub
parent dce847a97a
commit 9915e22bc2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 746 additions and 524 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
website/source/api/agent/connect.html.md
View File

@ -316,6 +316,6 @@ $ curl \
is a map of primitive values (including arrays and maps) that is set by the
user.
- `Upstreams` `(array<Upstream>)` - The configured upstreams for the proxy. See
[Upstream Configuration Reference](/docs/connect/proxies.html#upstream-configuration-reference)
- `Upstreams` `(array<Upstream>)` - The configured upstreams for the proxy. See
[Upstream Configuration Reference](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
for more details on the format.

5
website/source/api/agent/service.html.md
View File

@ -461,7 +461,8 @@ service definition keys for compatibility with the config file format.
- `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a
Connect proxy instance. This is only valid if `Kind == "connect-proxy"`. See
the [Proxy documentation](/docs/connect/proxies.html) for full details.
the [Proxy documentation](/docs/connect/registration/service-registration.html)
for full details.
- `Connect` `(Connect: nil)` - Specifies the
[configuration for Connect](/docs/connect/configuration.html). See the
@ -524,7 +525,7 @@ For the `Connect` field, the parameters are:
in [Managed Proxy Deprecation](/docs/connect/proxies/managed-deprecated.html).
- `SidecarService` `(ServiceDefinition: nil)` - Specifies an optional nested
service definition to register. For more information see
[Sidecar Service Registration](/docs/connect/proxies/sidecar-service.html).
[Sidecar Service Registration](/docs/connect/registration/sidecar-service.html).
### Sample Payload

85
website/source/docs/agent/config_entries.html.md
View File

@ -8,9 +8,11 @@ description: |-
# Configuration Entries
Configuration entries can be created to provide cluster-wide defaults for various aspects of Consul. Every configuration
entry has at least two fields: `Kind` and `Name`. Those two fields are used to uniquely identify a configuration entry.
When put into configuration files, configuration entries can be specified as HCL or JSON objects.
Configuration entries can be created to provide cluster-wide defaults for
various aspects of Consul. Every configuration entry has at least two fields:
`Kind` and `Name`. Those two fields are used to uniquely identify a
configuration entry. When put into configuration files, configuration entries
can be specified as HCL or JSON objects.
Example:
@ -25,8 +27,8 @@ The two supported `Kind` configuration entries are detailed below.
### Proxy Defaults - `proxy-defaults`
Proxy defaults allow for configuring global config defaults across all services for Connect proxy configuration. Currently,
only one global entry is supported.
Proxy defaults allow for configuring global config defaults across all services
for Connect proxy configuration. Currently, only one global entry is supported.
```hcl
Kind = "proxy-defaults"
@ -41,16 +43,18 @@ Config {
* `Name` - Must be set to `global`
* `Config` - An arbitrary map of configuration values used by Connect proxies. See
* `Config` - An arbitrary map of configuration values used by Connect proxies.
The available configurations depend on the Connect proxy you use. Any values
that your proxy allows can be configured globally here. To
explore these options please see the documentation for your chosen proxy.
#### Proxy Configuration References
* [Consul's Builtin Proxy](/docs/connect/configuration.html#built-in-proxy-options)
* [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
* [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
* [Consul's Builtin Proxy](/docs/connect/proxies/built-in.html)
### Service Defaults - `service-defaults`
Service defaults control default global values for a service, such as its protocol.
Service defaults control default global values for a service, such as its
protocol.
```hcl
Kind = "service-defaults"
@ -62,20 +66,25 @@ Protocol = "http"
* `Name` - Set to 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.
* `Protocol` - Sets the protocol of the service. This is used by Connect proxies
for things like observability features.
## Managing Configuration Entries
Configuration entries should be managed with the Consul [CLI](/docs/commands/config.html) or [API](/api/config.html). Additionally,
as a convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's
Configuration entries should be managed with the Consul
[CLI](/docs/commands/config.html) or [API](/api/config.html). Additionally, as a
convenience for initial cluster bootstrapping, configuration entries can be
specified in all of the Consul servers's
[configuration files](/docs/agent/options.html#config_entries_bootstrap)
### Managing Configuration Entries with the CLI
#### Creating or Updating a Configuration Entry
The [`consul config write`](/docs/commands/config/write.html) command is used to create and update configuration entries. This command
will load either a JSON or HCL file holding the configuration entry definition and then will push this configuration to Consul.
The [`consul config write`](/docs/commands/config/write.html) command is used to
create and update configuration entries. This command will load either a JSON or
HCL file holding the configuration entry definition and then will push this
configuration to Consul.
Example HCL Configuration File - `proxy-defaults.hcl`:
@ -94,15 +103,18 @@ Then to apply this configuration, run:
$ consul config write proxy-defaults.hcl
```
If you need to make changes to a configuration entry, simple edit that file and then rerun the command.
This command will not output anything unless there is an error in applying the configuration entry.
The `write` command also supports a `-cas` option to enable performing a compare-and-swap operation to
prevent overwriting other unknown modifications.
If you need to make changes to a configuration entry, simple edit that file and
then rerun the command. This command will not output anything unless there is an
error in applying the configuration entry. The `write` command also supports a
`-cas` option to enable performing a compare-and-swap operation to prevent
overwriting other unknown modifications.
#### Reading a Configuration Entry
The [`consul config read`](/docs/commands/config/read.html) command is used to read the current value of a configuration entry. The
configuration entry will be displayed in JSON form which is how its transmitted between the CLI client and Consul's HTTP API.
The [`consul config read`](/docs/commands/config/read.html) command is used to
read the current value of a configuration entry. The configuration entry will be
displayed in JSON form which is how its transmitted between the CLI client and
Consul's HTTP API.
Example:
@ -117,8 +129,8 @@ $ consul config read -kind service-defaults -name web
#### Listing Configuration Entries
The [`consul config list`](/docs/commands/config/list.html) command is used to list out all the configuration entries for a
given kind.
The [`consul config list`](/docs/commands/config/list.html) command is used to
list out all the configuration entries for a given kind.
Example:
@ -132,8 +144,8 @@ db
#### Deleting Configuration Entries
The [`consul config delete`](/docs/commands/config/delete.html) command is used to delete an entry by specifying both its
`kind` and `name`.
The [`consul config delete`](/docs/commands/config/delete.html) command is used
to delete an entry by specifying both its `kind` and `name`.
Example:
@ -146,15 +158,20 @@ This command will not output anything when the deletion is successful.
### Bootstrapping From A Configuration File
Configuration entries can be bootstrapped by adding them inline to each Consul server’s configuration file. When a server
gains leadership, it will attempt to initialize the configuration entries. If a configuration entry does not already exist
outside of the servers configuration, then it will create it. If a configuration entry does exist, that matches both `kind`
and `name`, then the server will do nothing.
Configuration entries can be bootstrapped by adding them inline to each Consul
server’s configuration file. When a server gains leadership, it will attempt to
initialize the configuration entries. If a configuration entry does not already
exist outside of the servers configuration, then it will create it. If a
configuration entry does exist, that matches both `kind` and `name`, then the
server will do nothing.
## Using Configuration Entries For Service Defaults
When the agent is [configured](/docs/agent/options.html#enable_central_service_config) to enable central service configurations,
it will look for service configuration defaults that match a registering service instance. If it finds any, the agent will merge
those defaults with the service instance configuration. This allows for things like service protocol or proxy configuration to
be defined globally and inherited by any affected service registrations.
When the agent is
[configured](/docs/agent/options.html#enable_central_service_config) to enable
central service configurations, it will look for service configuration defaults
that match a registering service instance. If it finds any, the agent will merge
those defaults with the service instance configuration. This allows for things
like service protocol or proxy configuration to be defined globally and
inherited by any affected service registrations.

18
website/source/docs/agent/options.html.md
View File

@ -660,7 +660,7 @@ default will automatically work with some tooling.
or write privileges, or node read privileges, even if Consul servers aren't present to validate
any tokens. This should only be used by operators during outages, regular ACL tokens should normally
be used by applications. This was added in Consul 0.7.2 and is only used when
<a href="#acl_enforce_version_8">`acl_enforce_version_8`</a> is set to true.
<a href="#acl_enforce_version_8">`acl_enforce_version_8`</a> is set to true.
* <a name="acl_agent_token_legacy"></a><a href="#acl_agent_token_legacy">`acl_agent_token`</a> -
**Deprecated in Consul 1.4.0. See the [`acl.tokens.agent`](#acl_tokens_agent) field instead.**
@ -668,7 +668,7 @@ default will automatically work with some tooling.
<a href="#acl_token">`acl_token`</a> will be used. This was added in Consul 0.7.2.
This token must at least have write access to the node name it will register as in order to set any
of the node-level information in the catalog such as metadata, or the node's tagged addresses.
of the node-level information in the catalog such as metadata, or the node's tagged addresses.
* <a name="acl_enforce_version_8"></a><a href="#acl_enforce_version_8">`acl_enforce_version_8`</a> -
**Deprecated in Consul 1.4.0**
@ -704,7 +704,7 @@ default will automatically work with some tooling.
If there's a partition or other outage affecting the authoritative datacenter, and the
[`acl_down_policy`](/docs/agent/options.html#acl_down_policy) is set to "extend-cache", tokens not
in the cache can be resolved during the outage using the replicated set of ACLs.
in the cache can be resolved during the outage using the replicated set of ACLs.
* <a name="acl_token_legacy"></a><a href="#acl_token_legacy">`acl_token`</a> -
**Deprecated in Consul 1.4.0. See the [`acl.tokens.default`](#acl_tokens_default) field instead.**
@ -1387,12 +1387,12 @@ default will automatically work with some tooling.
* <a name="sidecar_min_port"></a><a
href="#sidecar_min_port">`sidecar_min_port`</a> - Inclusive minimum port
number to use for automatically assigned [sidecar service
registrations](/docs/connect/proxies/sidecar-service.html). Default 21000.
registrations](/docs/connect/registration/sidecar-service.html). Default 21000.
Set to `0` to disable automatic port assignment.
* <a name="sidecar_max_port"></a><a
href="#sidecar_max_port">`sidecar_max_port`</a> - Inclusive maximum port
number to use for automatically assigned [sidecar service
registrations](/docs/connect/proxies/sidecar-service.html). Default 21255.
registrations](/docs/connect/registration/sidecar-service.html). Default 21255.
Set to `0` to disable automatic port assignment.
* <a name="protocol"></a><a href="#protocol">`protocol`</a> Equivalent to the
@ -1402,7 +1402,7 @@ default will automatically work with some tooling.
designates the datacenter which is authoritative for ACL information, intentions and is the root
Certificate Authority for Connect. It must be provided to enable ACLs. All servers and datacenters
must agree on the primary datacenter. Setting it on the servers is all you need for cluster-level enforcement, but for the APIs to forward properly from the clients, it must be set on them too. In
Consul 0.8 and later, this also enables agent-level enforcement of ACLs.
Consul 0.8 and later, this also enables agent-level enforcement of ACLs.
* <a name="raft_protocol"></a><a href="#raft_protocol">`raft_protocol`</a> Equivalent to the
[`-raft-protocol` command-line flag](#_raft_protocol).
@ -1744,10 +1744,10 @@ default will automatically work with some tooling.
## <a id="ports-used"></a>Ports Used
Consul requires up to 6 different ports to work properly, some on
TCP, UDP, or both protocols.
TCP, UDP, or both protocols.
Review the [required ports](/docs/install/ports.html) table for a list of
required ports and their default settings.
Review the [required ports](/docs/install/ports.html) table for a list of
required ports and their default settings.
## <a id="reloadable-configuration"></a>Reloadable Configuration

6
website/source/docs/agent/services.html.md
View File

@ -135,7 +135,7 @@ typical non-proxy instances the `kind` field must be omitted. The `proxy` field
is also required for Connect proxy registrations and is only valid if `kind` is
`connect-proxy`. The only required `proxy` field is `destination_service_name`.
For more detail please see [complete proxy configuration
example](/docs/connect/proxies.html#complete-configuration-example)
example](/docs/connect/registration/service-registration.html#complete-configuration-example)
-> **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
@ -148,7 +148,7 @@ Consul 1.2.0 and later. The `native` value can be set to true to advertise the
service as [Connect-native](/docs/connect/native.html). The `sidecar_service`
field is an optional nested service definition its behavior and defaults are
described in [Sidecar Service
Registration](/docs/connect/proxies/sidecar-service.html). If `native` is true,
Registration](/docs/connect/registration/sidecar-service.html). If `native` is true,
it is an error to also specify a sidecar service registration.
-> **Deprecation Notice:** From version 1.2.0 to 1.3.0 during beta, Connect
@ -280,7 +280,7 @@ For historical reasons Consul's API uses `CamelCased` parameter names in
responses, however it's configuration file uses `snake_case` for both HCL and
JSON representations. For this reason the registration _HTTP APIs_ accept both
name styles for service definition parameters although APIs will return the
listings using `CamelCase`.
listings using `CamelCase`.
Note though that **all config file formats require
`snake_case` fields**. We always document service definition examples using

6
website/source/docs/commands/connect/envoy.html.md.erb
View File

@ -56,13 +56,13 @@ proxy configuration needed.
* `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
this proxy will represent. The target service doesn't need to exist on the
local agent yet but a [sidecar proxy
registration](/docs/connect/proxies.html#sidecar-proxy-fields) with
registration](/docs/connect/registration/service-registration.html) with
`proxy.destination_service_id` equal to the passed value must be present. If
multiple proxy registrations targeting the same local service instance are
present the command will error and `-proxy-id` should be used instead.
* `-proxy-id` - The [proxy
service](/docs/connect/proxies.html#proxy-service-definitions) ID on the
service](/docs/connect/registration/service-registration.html) ID on the
local agent. This must already be present on the local agent.
-> **Note:** If ACLs are enabled, a token granting `service:write` for the
@ -98,7 +98,7 @@ allowed to access by [Connect intentions](/docs/connect/intentions.html).
Assume a local service instance is registered on the local agent with a
sidecar proxy (using the [sidecar service
registration](/docs/connect/proxies/sidecar-service.html) helper) as below.
registration](/docs/connect/registration/service-registration.html) helper) as below.
```hcl
service {

4
website/source/docs/commands/connect/proxy.html.md.erb
View File

@ -30,13 +30,13 @@ Usage: `consul connect proxy [options]`
* `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
this proxy will represent. The target service doesn't need to exist on the
local agent yet but a [sidecar proxy
registration](/docs/connect/proxies.html#sidecar-proxy-fields) with
registration](/docs/connect/registration/service-registration.html) with
`proxy.destination_service_id` equal to the passed value must be present. If
multiple proxy registrations targeting the same local service instance are
present the command will error and `-proxy-id` should be used instead.
* `-proxy-id` - The [proxy
service](/docs/connect/proxies.html#proxy-service-definitions) ID on the
service](/docs/connect/registration/service-registration.html) ID on the
local agent. This must already be present on the local agent.
* `-log-level` - Specifies the log level.

154
website/source/docs/connect/configuration.html.md
View File

@ -12,7 +12,10 @@ There are many configuration options exposed for Connect. The only option
that must be set is the "enabled" option on Consul Servers to enable Connect.
All other configurations are optional and have reasonable defaults.
## Enable Connect on the Cluster
-> **Tip:** Connect is enabled by default when running Consul in
dev mode with `consul agent -dev`.
## Agent Configuration
The first step to use Connect is to enable Connect for your Consul
cluster. By default, Connect is disabled. Enabling Connect requires changing
@ -32,117 +35,68 @@ You may also configure Consul to use an external
[certificate management system](/docs/connect/ca.html), such as
[Vault](https://vaultproject.io).
No agent-wide configuration is necessary for non-server agents. Services
and proxies may always register with Connect settings, but they will fail to
retrieve or verify any TLS certificates. This causes all Connect-based
Services and proxies may always register with Connect settings, but they will
fail to retrieve or verify any TLS certificates. This causes all Connect-based
connection attempts to fail until Connect is enabled on the server agents.
-> **Note:** Connect is enabled by default when running Consul in
dev mode with `consul agent -dev`.
Other optional Connect configurations that you can set in the server
configuration file include:
~> **Security note:** Enabling Connect is enough to try the feature but doesn't
- [certificate authority settings](/docs/agent/options.html#connect)
- [token replication](/docs/agent/options.html#acl_tokens_replication)
- [dev mode](/docs/agent/options.html#_dev)
- [server host name verification](/docs/agent/options.html#verify_server_hostname)
If you would like to use Envoy as your Connect proxy you will need to [enable
gRPC](/docs/agent/options.html#grpc_port).
Additionally if you plan on using the observability features of Connect, it can
be convenient to configure your proxies and services using [configuration
entries](/docs/agent/config_entries.html) which you can interact with using the
CLI or API, or by creating configuration entry files. You will want to enable
[centralized service
configuration](/docs/agent/options.html#enable_central_service_config) on
clients, which allows each service's proxy configuration to be managed centrally
via API.
!> **Security note:** Enabling Connect is enough to try the feature but doesn't
automatically ensure complete security. Please read the [Connect production
guide](https://learn.hashicorp.com/consul/developer-segmentation/connect-production) to understand the additional steps
needed for a secure deployment.
## Built-In Proxy Options
## Centralized Proxy and Service Configuration
This is a complete example of all the configuration options available for the
built-in proxy. Note that only the `service.connect.proxy.config` and
`service.connect.proxy.upsteams[].config` maps are being described here, the
rest of the service definition is shown for context but is [described
elsewhere](/docs/connect/proxies.html#managed-proxies).
To account for common Connect use cases where you have many instances of the
same service, and many colocated sidecar proxies, Consul allows you to customize
the settings for all of your proxies or all the instances of a given service at
once using [Configuration Entries](/docs/agent/config_entries.html).
```javascript
{
"service": {
...
"connect": {
"proxy": {
"config": {
"bind_address": "0.0.0.0",
"bind_port": 20000,
"tcp_check_address": "192.168.0.1",
"disable_tcp_check": false,
"local_service_address": "127.0.0.1:1234",
"local_connect_timeout_ms": 1000,
"handshake_timeout_ms": 10000,
"upstreams": [...]
},
"upstreams": [
{
...
"config": {
"connect_timeout_ms": 1000
}
}
]
}
}
}
}
```
You can override centralized configurations for individual proxy instances in
their
[sidecar service definitions](/docs/connect/registration/sidecar-service.html),
and the default protocols for service instances in their [service
registrations](/docs/agent/services.html).
#### Proxy Config Key Reference
## Schedulers
All fields are optional with a sane default.
Consul Connect is especially useful if you are using an orchestrator like Nomad
or Kubernetes, because these orchestrators can deploy thousands of service instances
which frequently move hosts. Sidecars for each service can be configured through
these schedulers, and in some cases they can automate Consul configuration,
sidecar deployment, and service registration.
* <a name="bind_address"></a><a href="#bind_address">`bind_address`</a> -
The address the proxy will bind it's _public_ mTLS listener to. It
defaults to the same address the agent binds to.
### Nomad
* <a name="bind_port"></a><a href="#bind_port">`bind_port`</a> - The
port the proxy will bind it's _public_ mTLS listener to. If not provided, the
agent will attempt to assign one from its [configured proxy port
range](/docs/agent/options.html#proxy_min_port) if available. By default the
range is [20000, 20255] and the port is selected at random from that range.
Connect can be used with Nomad to provide secure service-to-service
communication between Nomad jobs and task groups. The ability to use the dynamic
port feature of Nomad makes Connect particularly easy to use. Learn about how to
configure Connect on Nomad by reading the
[integration documentation](/docs/connect/platform/nomad.html)
* <a name="tcp_check_address"></a><a
href="#tcp_check_address">`tcp_check_address`</a> - The address the agent will
run a [TCP health check](/docs/agent/checks.html) against. By default this is
the same as the proxy's [bind address](#bind_address) except if the
bind_address is `0.0.0.0` or `[::]` in which case this defaults to `127.0.0.1`
and assumes the agent can dial the proxy over loopback. For more complex
configurations where agent and proxy communicate over a bridge for example,
this configuration can be used to specify a different _address_ (but not port)
for the agent to use for health checks if it can't talk to the proxy over
localhost or it's publicly advertised port. The check always uses the same
port that the proxy is bound to.
### Kubernetes
* <a name="disable_tcp_check"></a><a
href="#disable_tcp_check">`disable_tcp_check`</a> - If true, this disables a
TCP check being setup for the proxy. Default is false.
* <a name="local_service_address"></a><a href="#local_service_address">`local_service_address`</a> - The
`[address]:port` that the proxy should use to connect to the local application
instance. By default it assumes `127.0.0.1` as the address and takes the port
from the service definition's `port` field. Note that allowing the application
to listen on any non-loopback address may expose it externally and bypass
Connect's access enforcement. It may be useful though to allow non-standard
loopback addresses or where an alternative known-private IP is available for
example when using internal networking between containers.
* <a name="local_connect_timeout_ms"></a><a href="#local_connect_timeout_ms">`local_connect_timeout_ms`</a> - The number
of milliseconds the proxy will wait to establish a connection to the _local
application_ before giving up. Defaults to `1000` or 1 second.
* <a name="handshake_timeout_ms"></a><a href="#handshake_timeout_ms">`handshake_timeout_ms`</a> - The
number of milliseconds the proxy will wait for _incoming_ mTLS connections to
complete the TLS handshake. Defaults to `10000` or 10 seconds.
* <a name="upstreams"></a><a href="#upstreams">`upstreams`</a> - **Deprecated**
Upstreams are now specified in the `connect.proxy` definition. Upstreams
specified in the opaque config map here will continue to work for
compatibility but it's strongly recommended that you move to using the higher
level [upstream
configuration](/docs/connect/proxies.html#upstream-configuration).
#### Proxy Upstream Config Key Reference
All fields are optional with a sane default.
* <a name="connect_timeout_ms"></a><a
href="#connect_timeout_ms">`connect_timeout_ms`</a> - The number of
milliseconds the proxy will wait to establish a TLS connection to the
discovered upstream instance before giving up. Defaults to `10000` or 10
seconds.
The Consul Helm chart can automate much of Consul Connect's configuration, and
makes it easy to automatically inject Envoy sidecars into new pods when they are
deployed. Learn about the [Helm chart](/docs/platform/k8s/helm.html) in general,
or if you are already familiar with it, check out it's
[connect specific configurations](/docs/platform/k8s/connect.html).

102
website/source/docs/connect/connect-internals.html.md Normal file
View File

@ -0,0 +1,102 @@
---
layout: "docs"
page_title: "Connect - Architecture"
sidebar_current: "docs-connect-internals"
description: |-
This page details the internals of Consul Connect: mutual TLS, agent caching and performance, and multi-datacenter Enterprise functionality.
---
# How Connect Works
This page details the inner workings of some of Connect's core features.
Understanding how these features work isn't a prerequisite for using Connect,
but will help you build a mental model of what's going on under the hood, which
may help you reason about Connect's behavior in more complex deployment
scenarios.
## Mutual Transport Layer Security (mTLS)
The core of Connect is based on [mutual TLS](https://en.wikipedia.org/wiki/Mutual_authentication).
Connect provides each service with an identity encoded as a TLS certificate.
This certificate is used to establish and accept connections to and from other
services. The identity is encoded in the TLS certificate in compliance with
the [SPIFFE X.509 Identity Document](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md).
This enables Connect services to establish and accept connections with
other SPIFFE-compliant systems.
The client service verifies the destination service certificate
against the [public CA bundle](/api/connect/ca.html#list-ca-root-certificates).
This is very similar to a typical HTTPS web browser connection. In addition
to this, the client provides its own client certificate to show its
identity to the destination service. If the connection handshake succeeds,
the connection is encrypted and authorized.
The destination service verifies the client certificate
against the [public CA bundle](/api/connect/ca.html#list-ca-root-certificates).
After verifying the certificate, it must also call the
[authorization API](/api/agent/connect.html#authorize) to authorize
the connection against the configured set of Consul intentions.
If the authorization API responds successfully, the connection is established.
Otherwise, the connection is rejected.
To generate and distribute certificates, Consul has a built-in CA that
requires no other dependencies, and
also ships with built-in support for [Vault](/docs/connect/ca/vault.html). The PKI system is designed to be pluggable
and can be extended to support any system by adding additional CA providers.
All APIs required for Connect typically respond in microseconds and impose
minimal overhead to existing services. This is because the Connect-related APIs
are all made to the local Consul agent over a loopback interface, and all [agent
Connect endpoints](/api/agent/connect.html) implement local caching, background
updating, and support blocking queries. Most API calls operate on purely local
in-memory data.
## Agent Caching and Performance
To enable fast responses on [agent Connect API
endpoints](/api/agent/connect.html), the Consul agent locally caches most
Connect-related data and sets up background [blocking
queries](/api/features/blocking.html) against the server to update the cache in
the background. This allows most API calls such as retrieving certificates or
authorizing connections to use in-memory data and respond very quickly.
All data cached locally by the agent is populated on demand. Therefore, if
Connect is not used at all, the cache does not store any data. On first request,
the data is loaded from the server and cached. The set of data cached is: public
CA root certificates, leaf certificates, intentions, and service discovery
results for upstreams. For leaf certificates and intentions, only data related
to the service requested is cached, not the full set of data.
Further, the cache is partitioned by ACL token and datacenters. This is done
to minimize the complexity of the cache and prevent bugs where an ACL token
may see data it shouldn't from the cache. This results in higher memory usage
for cached data since it is duplicated per ACL token, but with the benefit
of simplicity and security.
With Connect enabled, you'll likely see increased memory usage by the
local Consul agent. The total memory is dependent on the number of intentions
related to the services registered with the agent accepting Connect-based
connections. The other data (leaf certificates and public CA certificates)
is a relatively fixed size per service. In most cases, the overhead per
service should be relatively small: single digit kilobytes at most.
The cache does not evict entries due to memory pressure. If memory capacity
is reached, the process will attempt to swap. If swap is disabled, the Consul
agent may begin failing and eventually crash. Cache entries do have TTLs
associated with them and will evict their entries if they're not used. Given
a long period of inactivity (3 days by default), the cache will empty itself.
## Multi-Datacenter
Using Connect for service-to-service communications across multiple datacenters
requires Consul Enterprise.
With Open Source Consul, Connect may be enabled on multiple Consul datacenters,
but only services within the same datacenter can establish Connect-based,
Authenticated and Authorized connections. In this version, Certificate Authority
configurations and intentions are both local to their respective datacenters;
they are not replicated across datacenters.
Full multi-datacenter support for Connect is available in
[Consul Enterprise](/docs/enterprise/connect-multi-datacenter/index.html).

154
website/source/docs/connect/index.html.md
View File

@ -3,132 +3,60 @@ layout: "docs"
page_title: "Connect (Service Segmentation)"
sidebar_current: "docs-connect-index"
description: |-
Consul Connect provides service-to-service connection authorization and encryption using mutual TLS.
Consul Connect provides service-to-service connection authorization and
encryption using mutual TLS.
---
# Connect
Consul Connect provides service-to-service connection authorization
and encryption using mutual TLS. Applications can use
[sidecar proxies](/docs/connect/proxies.html)
to automatically establish TLS connections for inbound and outbound connections
without being aware of Connect at all. Applications may also
[natively integrate with Connect](/docs/connect/native.html)
for optimal performance and security.
Consul Connect provides service-to-service connection authorization and
encryption using mutual Transport Layer Security (TLS). Applications can use
[sidecar proxies](/docs/connect/proxies.html) in a service mesh configuration to
automatically establish TLS connections for inbound and outbound connections
without being aware of Connect at all. Applications may also [natively integrate
with Connect](/docs/connect/native.html) for optimal performance and security.
Connect can help you secure your services and provide data about service-to-service
communications.
Connect enables deployment best-practices with service-to-service encryption
everywhere and identity-based authorization. Rather than authorizing host-based
access with IP address access rules, Connect uses the registered service
identity to enforce access control with [intentions](/docs/connect/intentions.html).
This makes it much easier to reason about access control and also enables
services to freely move, such as in a scheduled environment with software
such as Kubernetes or Nomad. Additionally, intention enforcement can be done
regardless of the underlying network, so Connect works with physical networks,
cloud networks, software-defined networks, cross-cloud, and more.
## Application Security
## How it Works
Connect enables secure deployment best-practices with automatic
service-to-service encryption, and identity-based authorization.
Connect uses the registered service identity (rather than IP addresses) to
enforce access control with [intentions](/docs/connect/intentions.html). This
makes it easier to reason about access control and enables services to be
rescheduled by orchestrators including Kubernetes and Nomad. Intention
enforcement is network agnostic, so Connect works with physical networks, cloud
networks, software-defined networks, cross-cloud, and more.
The core of Connect is based on [mutual TLS](https://en.wikipedia.org/wiki/Mutual_authentication).
## Observability
Connect provides each service with an identity encoded as a TLS certificate.
This certificate is used to establish and accept connections to and from other
services. The identity is encoded in the TLS certificate in compliance with
the [SPIFFE X.509 Identity Document](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md).
This enables Connect services to establish and accept connections with
other SPIFFE-compliant systems.
The client service verifies the destination service certificate
against the [public CA bundle](/api/connect/ca.html#list-ca-root-certificates).
This is very similar to a typical HTTPS web browser connection. In addition
to this, the client provides its own client certificate to show its
identity to the destination service. If the connection handshake succeeds,
the connection is encrypted and authorized.
The destination service verifies the client certificate
against the [public CA bundle](/api/connect/ca.html#list-ca-root-certificates).
After verifying the certificate, it must also call the
[authorization API](/api/agent/connect.html#authorize) to authorize
the connection against the configured set of Consul intentions.
If the authorization API responds successfully, the connection is established.
Otherwise, the connection is rejected.
To generate and distribute certificates, Consul has a built-in CA that
requires no other dependencies, and
also ships with built-in support for [Vault](/docs/connect/ca/vault.html). The PKI system is designed to be pluggable
and can be extended to support any system by adding additional CA providers.
All APIs required for Connect typically respond in microseconds and impose
minimal overhead to existing services. This is because the Connect-related
APIs are all made to the local Consul agent over a loopback interface, and all
[agent Connect endpoints](/api/agent/connect.html) implement
local caching, background updating, and support blocking queries. As a result,
most API calls operate on purely local in-memory data and can respond
in microseconds.
One of the key benefits Consul Connect is the uniform and consistent view it can
provide of all the services on your network, irrespective of their different
programming languages and frameworks. When you configure Consul Connect to use
sidecar proxies, those proxies "see" all service-to-service traffic and can
collect data about it. Consul Connect can configure Envoy proxies to collect
layer 7 metrics and export them to tools like Prometheus. Correctly instrumented
application can also send open tracing data through Envoy.
## Getting Started With Connect
There are several ways to try Connect in different environments.
* The [Connect introduction](https://learn.hashicorp.com/consul/getting-started/connect) in the
Getting Started guide provides a simple walk through of getting two services
to communicate via Connect using only Consul directly on your local machine.
- The [Connect introduction guide](https://learn.hashicorp.com/consul/getting-started/connect)
is a simple walk through of connecting two services on your local machine
using only Consul Connect, and configuring your first intention.
* The [Envoy guide](https://learn.hashicorp.com/consul/developer-segmentation/connect-envoy) walks through getting
started with Envoy as a proxy, and uses Docker to run components locally
without installing anything else.
- The [Envoy guide](https://learn.hashicorp.com/consul/developer-segmentation/connect-envoy)
walks through using Envoy as a proxy. It uses Docker to run components
locally without installing anything else.
* The [Kubernetes documentation](/docs/platform/k8s/run.html) shows how to get
from an empty Kubernetes cluster to having Consul installed and Envoy
configured to proxy application traffic automatically using the official helm
chart.
## Agent Caching and Performance
To enable microsecond-speed responses on
[agent Connect API endpoints](/api/agent/connect.html), the Consul agent
locally caches most Connect-related data and sets up background
[blocking queries](/api/features/blocking.html) against the server
to update the cache in the background. This allows most API calls such
as retrieving certificates or authorizing connections to use in-memory
data and respond very quickly.
All data cached locally by the agent is populated on demand. Therefore,
if Connect is not used at all, the cache does not store any data. On first
request, the data is loaded from the server and cached. The set of data cached
is: public CA root certificates, leaf certificates, and intentions. For
leaf certificates and intentions, only data related to the service requested
is cached, not the full set of data.
Further, the cache is partitioned by ACL token and datacenters. This is done
to minimize the complexity of the cache and prevent bugs where an ACL token
may see data it shouldn't from the cache. This results in higher memory usage
for cached data since it is duplicated per ACL token, but with the benefit
of simplicity and security.
With Connect enabled, you'll likely see increased memory usage by the
local Consul agent. The total memory is dependent on the number of intentions
related to the services registered with the agent accepting Connect-based
connections. The other data (leaf certificates and public CA certificates)
is a relatively fixed size per service. In most cases, the overhead per
service should be relatively small: single digit kilobytes at most.
The cache does not evict entries due to memory pressure. If memory capacity
is reached, the process will attempt to swap. If swap is disabled, the Consul
agent may begin failing and eventually crash. Cache entries do have TTLs
associated with them and will evict their entries if they're not used. Given
a long period of inactivity (3 days by default), the cache will empty itself.
## Multi-Datacenter
Using Connect for service-to-service communications across multiple datacenters
requires Consul Enterprise.
With Open Source Consul, Connect may be enabled on multiple Consul datacenters,
but only services within the same datacenter can establish Connect-based,
Authenticated and Authorized connections. In this version, Certificate Authority
configurations and intentions are both local to their respective datacenters;
they are not replicated across datacenters.
Full multi-datacenter support for Connect is available in
[Consul Enterprise](/docs/enterprise/connect-multi-datacenter/index.html).
- The [Kubernetes guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube)
walks you though configuring Consul Connect in Kubernetes using the Helm
chart, and using intentions. You can run the guide on Minikube or an extant
Kubernets cluster.
- The [observability guide](https://learn.hashicorp.com/consul/getting-started-k8s/l7-observability-k8s)
shows how to deploy a basic metrics collection and visualization pipeline on
a Minikube or Kubernetes cluster using the official Helm charts for Consul,
Prometheus, and Grafana.

15
website/source/docs/connect/native.html.md
View File

@ -8,13 +8,14 @@ description: |-
# Connect-Native App Integration
Applications can natively integrate with the Connect API to support
accepting and establishing connections to other Connect services without
the overhead of a [proxy sidecar](/docs/connect/proxies.html). This option
is especially useful for applications that may be experiencing performance issues
with the proxy sidecar deployment. This page will cover the high-level overview
of integration, registering the service, etc. For language-specific examples,
see the sidebar navigation to the left.
Applications can natively integrate with the Connect API to support accepting
and establishing connections to other Connect services without the overhead of a
[proxy sidecar](/docs/connect/proxies.html). This option is especially useful
for applications that may be experiencing performance issues with the proxy
sidecar deployment. This page will cover the high-level overview of
integration, registering the service, etc. For language-specific examples, see
the sidebar navigation to the left. It is also required if your service uses
relies on a dynamic set of upstream services.
Connect is just basic mutual TLS. This means that almost any application
can easily integrate with Connect. There is no custom protocol in use;

59
website/source/docs/connect/observability.html.md Normal file
View File

@ -0,0 +1,59 @@
---
layout: "docs"
page_title: "Connect - Observability"
sidebar_current: "docs-connect-observability"
description: |-
This page documents the configurations necessary for L7 observability using
Consul Connect.
---
## Observability
In order to take advantage of Connect's L7 observability features you will need
to:
- Deploy sidecar proxies that are capable of emitting metrics with each of your
services. We have first class support for Envoy.
- Define where your proxies should send metrics that they collect.
- Define the protocols for each of your services.
- Define the upstreams for each of your services.
If you are using Envoy as your sidecar proxy, you will need to enable [enable
gRPC](/docs/agent/options.html#grpc_port) on your client agents. To define the
metrics destination and service protocol you may want to enable [configuration
entries](/docs/agent/options.html#config_entries) and [centralized service
configuration](/docs/agent/options.html#enable_central_service_config). If you
are using Kubernetes, the Helm chart can simpify much of the necessary
configuration, which you can learn about in the [observability
guide](https://learn.hashicorp.com/consul/getting-started-k8s/l7-observability-k8s).
### Metrics Destination
For Envoy the metrics destination can be configured in the proxy configuration
entry's `config` section.
```
kind = "proxy-defaults"
name = "global"
config {
"envoy_dogstatsd_url": "udp://127.0.0.1:9125"
}
```
Find other possible metrics syncs in the [Connect Envoy documentation](/docs/connect/proxies/envoy.html#bootstrap-configuration).
### Service Protocol
You can specify the [service protocol](/docs/agent/config_entries.html#protocol)
in the `service-defaults` configuration entry. You can override it in the
[service registration](/docs/agent/services.html). By default, proxies only give
you L4 metrics. This protocol allows proxies to handle requests at the right L7
protocol and emit richer L7 metrics. It also allows proxies to make per-request
load balancing and routing decisions.
### Service Upstreams
You can set the upstream for each service using the proxy's
[`upstreams`](/docs/connect/registration/service-registration.html#upstreams)
sidecar parameter, which can be defined in a service's [sidecar
registration](/docs/connect/registration/sidecar-service.html).

224
website/source/docs/connect/proxies.html.md
View File

@ -3,220 +3,34 @@ layout: "docs"
page_title: "Connect - Proxies"
sidebar_current: "docs-connect-proxies"
description: |-
A Connect-aware proxy enables unmodified applications to use Connect. A per-service proxy sidecar transparently handles inbound and outbound service connections, automatically wrapping and verifying TLS connections.
A Connect-aware proxy enables unmodified applications to use Connect. This section details how to use either Envoy or Consul's built-in L4 proxy, and describes how you can plug in a proxy of your choice.
---
# Connect Proxies
A Connect-aware proxy enables unmodified applications to use Connect.
A per-service proxy sidecar transparently handles inbound and outbound
service connections, automatically wrapping and verifying TLS connections.
A Connect-aware proxy enables unmodified applications to use Connect. A
per-service proxy sidecar transparently handles inbound and outbound service
connections, automatically wrapping and verifying TLS connections. Consul
includes its own built-in L4 proxy and has first class support for Envoy. You
can chose other proxies to plug in as well. This section describes how to
configure Envoy or the built-in proxy using Connect, and how to integrate the
proxy of your choice.
When a proxy is used, the actual service being proxied should only accept
connections on a loopback address. This requires all external connections
to be established via the Connect protocol to provide authentication and
authorization.
To ensure that services only meke allow external connections are established via
the Connect protocol they should only accept connections on a loopback address.
-> **Deprecation Note:** Managed Proxies are deprecated as of Consul 1.3. See
[managed proxy deprecation](/docs/connect/proxies/managed-deprecated.html) for
more information. It's strongly recommended to switch to one of the approaches
listed on this page as soon as possible.
~> **Deprecation Note:** Managed Proxies are a deprecated method for deploying
sidecar proxies, as of Consul 1.3. See [managed proxy
deprecation](/docs/connect/proxies/managed-deprecated.html) for more
information. If you are using managed proxies we strongly recommend that you
switch service definitions for registering proxies.
## Proxy Service Definitions
Connect proxies are registered using regular [service
definitions](/docs/agent/services.html). They can be registered both in config
files or via the API just like any other service.
Additionally, to reduce the amount of boilerplate needed for a sidecar proxy,
application service definitions may define inline [sidecar service
registrations](/docs/connect/proxies/sidecar-service.html) which are an
opinionated shorthand for a separate full proxy registration as described here.
To function as a Connect proxy, they must be declared as a proxy type and
provide information about the service they represent.
To declare a service as a proxy, the service definition must contain
the following fields:
* `kind` `(string)` must be set to `connect-proxy`. This declares that the
service is a proxy type.
* `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.
* `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.
Minimal Example:
```json
{
"name": "redis-proxy",
"kind": "connect-proxy",
"proxy": {
"destination_service_name": "redis"
},
"port": 8181
}
```
With this service registered, any Connect clients searching for a
Connect-capable endpoint for "redis" will find this proxy.
### Sidecar Proxy Fields
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:
* `proxy.destination_service_id` `(string: <required>)` 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.
* `proxy.local_service_port` `(int: <required>)` must specify the port the
proxy should use to connect to the _local_ service instance.
* `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`.
### Complete Configuration Example
The following is a complete example showing all the options available when
registering a proxy instance.
```json
{
"name": "redis-proxy",
"kind": "connect-proxy",
"proxy": {
"destination_service_name": "redis",
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
"config": {},
"upstreams": []
},
"port": 8181
}
```
-> **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`.
#### Proxy Parameters
- `destination_service_name` `(string: <required>)` - 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: <optional>)` - 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.
- `config` `(object: {})` - Specifies opaque config JSON that will be
stored and returned along with the service instance from future API calls.
- `upstreams` `(array<Upstream>: [])` - Specifies the upstream services
this proxy should create listeners for. The format is defined in
[Upstream Configuration Reference](#upstream-configuration-reference).
### Upstream Configuration Reference
The following examples show all possible upstream configuration parameters.
Note that in versions 1.2.0 to 1.3.0, managed proxy upstreams were specified
inside the opaque `connect.proxy.config` map. The format is almost unchanged
however managed proxy upstreams are now defined a level up in the
`connect.proxy.upstreams`. The old location is deprecated and will be
automatically converted into the new for an interim period before support is
dropped in a future major release. The only difference in format between the
upstream definitions is that the field `destination_datacenter` has been renamed
to `datacenter` to reflect that it's the discovery target and not necessarily
the same as the instance that will be returned in the case of a prepared query
that fails over to another datacenter.
Note that `snake_case` is used here as it works in both [config file and API
registrations](/docs/agent/services.html#service-definition-parameter-case).
Upstreams support multiple destination types. Both examples are shown below
followed by documentation for each attribute.
#### Service Destination
```json
{
"destination_type": "service",
"destination_name": "redis",
"datacenter": "dc1",
"local_bind_address": "127.0.0.1",
"local_bind_port": 1234,
"config": {}
},
```
#### Prepared Query Destination
```json
{
"destination_type": "prepared_query",
"destination_name": "database",
"local_bind_address": "127.0.0.1",
"local_bind_port": 1234,
"config": {}
},
```
* `destination_name` `(string: <required>)` - 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.
* `local_bind_port` `(int: <required>)` - 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`.
* `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 too. 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/configuration.html#built-in-proxy-options) for
options available when using the built-in proxy. If using Envoy as a proxy,
see [Envoy configuration
reference](/docs/connect/configuration.html#envoy-options)
### Dynamic Upstreams
## Dynamic Upstreams Require Native Integration
If an application requires dynamic dependencies that are only available
at runtime, it must currently [natively integrate](/docs/connect/native.html)
at runtime, it must [natively integrate](/docs/connect/native.html)
with Connect. After natively integrating, the HTTP API or
[DNS interface](/docs/agent/dns.html#connect-capable-service-lookups)
can be used.
!> Connect proxies do not currently support dynamic upstreams.

116
website/source/docs/connect/proxies/built-in.md Normal file
View File

@ -0,0 +1,116 @@
---
layout: "docs"
page_title: "Connect - Built-in Proxy"
sidebar_current: "docs-connect-proxies-built-in"
description: |-
Consul Connect comes with a built-in proxy for testing and development.
---
# Built-In Proxy Options
Consul comes with a built-in L4 proxy for testing and development with Consul
Connect.
Below is a complete example of all the configuration options available
for the built-in proxy. Note that only the `service.connect.proxy.config` and
`service.connect.proxy.upsteams[].config` maps are being described here, the
rest of the service definition is shown for context but is [described
elsewhere](/docs/connect/proxies.html#managed-proxies).
~> **Note:** Although you can configure the built-in proxy using configuration
entries, it doesn't have the L7 capability necessary for the observability
features released with Consul 1.5.
```javascript
{
"service": {
...
"connect": {
"proxy": {
"config": {
"bind_address": "0.0.0.0",
"bind_port": 20000,
"tcp_check_address": "192.168.0.1",
"disable_tcp_check": false,
"local_service_address": "127.0.0.1:1234",
"local_connect_timeout_ms": 1000,
"handshake_timeout_ms": 10000,
"upstreams": [...]
},
"upstreams": [
{
...
"config": {
"connect_timeout_ms": 1000
}
}
]
}
}
}
}
```
## Proxy Config Key Reference
All fields are optional with a sane default.
* <a name="bind_address"></a><a href="#bind_address">`bind_address`</a> -
The address the proxy will bind it's _public_ mTLS listener to. It
defaults to the same address the agent binds to.
* <a name="bind_port"></a><a href="#bind_port">`bind_port`</a> - The
port the proxy will bind it's _public_ mTLS listener to. If not provided, the
agent will attempt to assign one from its [configured proxy port
range](/docs/agent/options.html#proxy_min_port) if available. By default the
range is [20000, 20255] and the port is selected at random from that range.
* <a name="tcp_check_address"></a><a
href="#tcp_check_address">`tcp_check_address`</a> - The address the agent will
run a [TCP health check](/docs/agent/checks.html) against. By default this is
the same as the proxy's [bind address](#bind_address) except if the
bind_address is `0.0.0.0` or `[::]` in which case this defaults to `127.0.0.1`
and assumes the agent can dial the proxy over loopback. For more complex
configurations where agent and proxy communicate over a bridge for example,
this configuration can be used to specify a different _address_ (but not port)
for the agent to use for health checks if it can't talk to the proxy over
localhost or it's publicly advertised port. The check always uses the same
port that the proxy is bound to.
* <a name="disable_tcp_check"></a><a
href="#disable_tcp_check">`disable_tcp_check`</a> - If true, this disables a
TCP check being setup for the proxy. Default is false.
* <a name="local_service_address"></a><a href="#local_service_address">`local_service_address`</a> - The
`[address]:port` that the proxy should use to connect to the local application
instance. By default it assumes `127.0.0.1` as the address and takes the port
from the service definition's `port` field. Note that allowing the application
to listen on any non-loopback address may expose it externally and bypass
Connect's access enforcement. It may be useful though to allow non-standard
loopback addresses or where an alternative known-private IP is available for
example when using internal networking between containers.
* <a name="local_connect_timeout_ms"></a><a href="#local_connect_timeout_ms">`local_connect_timeout_ms`</a> - The number
of milliseconds the proxy will wait to establish a connection to the _local
application_ before giving up. Defaults to `1000` or 1 second.
* <a name="handshake_timeout_ms"></a><a href="#handshake_timeout_ms">`handshake_timeout_ms`</a> - The
number of milliseconds the proxy will wait for _incoming_ mTLS connections to
complete the TLS handshake. Defaults to `10000` or 10 seconds.
* <a name="upstreams"></a><a href="#upstreams">`upstreams`</a> - **Deprecated**
Upstreams are now specified in the `connect.proxy` definition. Upstreams
specified in the opaque config map here will continue to work for
compatibility but it's strongly recommended that you move to using the higher
level [upstream
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference).
## Proxy Upstream Config Key Reference
All fields are optional with a sane default.
* <a name="connect_timeout_ms"></a><a
href="#connect_timeout_ms">`connect_timeout_ms`</a> - The number of
milliseconds the proxy will wait to establish a TLS connection to the
discovered upstream instance before giving up. Defaults to `10000` or 10
seconds.

26
website/source/docs/connect/proxies/envoy.md
View File

@ -23,7 +23,7 @@ plans to support a wider range of features in the next major release
cycle.
As an interim solution, you can add [custom Envoy configuration](#custom-configuration)
in the [proxy service definition](/docs/connect/proxies.html) allowing
in the [proxy service definition](/docs/connect/registration/service-registration.html) allowing
you to use the more powerful features of Envoy.
## Supported Versions
@ -97,8 +97,8 @@ configuration options.
Users can add the following configuration items to the [global `proxy-defaults`
configuration entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) or override them directly in the `proxy.config` field
of a [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions) or
[`sidecar_service`](/docs/connect/proxies/sidecar-service.html) block.
definition](/docs/connect/registration/service-registration.html) or
[`sidecar_service`](/docs/connect/registration/sidecar-service.html) block.
- `envoy_statsd_url` - A URL in the form `udp://ip:port` identifying a UDP
StatsD listener that Envoy should deliver metrics to. For example, this may be
@ -164,13 +164,13 @@ automatically configure its upstream listeners appropriately too as below.
This automated discovery results in Consul auto-populating the `proxy.config`
and `proxy.upstreams[*].config` fields of the [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions) that is
definition](/docs/connect/registration/service-registration.html) that is
actually registered.
### Proxy Config Options
These fields may also be overridden explicitly in the [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions), or defined in
definition](/docs/connect/registration/service-registration.html), or defined in
the [global `proxy-defaults` configuration
entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) to act as
defaults that are inherited by all services.
@ -205,8 +205,8 @@ defaults that are inherited by all services.
The following configuration items may be overridden directly in the
`proxy.upstreams[].config` field of a [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions) or
[`sidecar_service`](/docs/connect/proxies/sidecar-service.html) block.
definition](/docs/connect/registration/service-registration.html) or
[`sidecar_service`](/docs/connect/registration/sidecar-service.html) block.
- `protocol` - Same as above in main config but affects the listener setup for
the upstream.
@ -256,8 +256,8 @@ Users may add the following configuration items to the [global `proxy-defaults`
configuration
entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) or
override them directly in the `proxy.config` field of a [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions) or
[`sidecar_service`](/docs/connect/proxies/sidecar-service.html) block.
definition](/docs/connect/registration/service-registration.html) or
[`sidecar_service`](/docs/connect/registration/sidecar-service.html) block.
- `envoy_extra_static_clusters_json` - Specifies one or more [Envoy
clusters](https://www.envoyproxy.io/docs/envoy/v1.10.0/api-v2/api/v2/cds.proto#cluster)
@ -292,8 +292,8 @@ Users may add the following configuration items to the [global `proxy-defaults`
configuration
entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) or
override them directly in the `proxy.config` field of a [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions) or
[`sidecar_service`](/docs/connect/proxies/sidecar-service.html) block.
definition](/docs/connect/registration/service-registration.html) or
[`sidecar_service`](/docs/connect/registration/sidecar-service.html) block.
- `envoy_bootstrap_json_tpl` - Specifies a template in Go template syntax that
is used in place of [the default
@ -325,8 +325,8 @@ definition](/docs/connect/proxies.html#proxy-service-definitions) or
The following configuration items may be overridden directly in the
`proxy.upstreams[].config` field of a [proxy service
definition](/docs/connect/proxies.html#proxy-service-definitions) or
[`sidecar_service`](/docs/connect/proxies/sidecar-service.html) block.
definition](/docs/connect/registration/service-registration.html) or
[`sidecar_service`](/docs/connect/registration/sidecar-service.html) block.
- `envoy_listener_json` - Specifies a complete
[Listener](https://www.envoyproxy.io/docs/envoy/v1.10.0/api-v2/api/v2/lds.proto)

24
website/source/docs/connect/registration.html.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: "docs"
page_title: "Connect - Proxy Registration"
sidebar_current: "docs-connect-registration"
description: |-
To make connect aware of proxies you will need to register them as Consul services. This section describes the process and options for proxy registration.
---
# Proxy Registration
To make Connect aware of proxies you will need to register them in a [service
definition](/docs/agent/services.html), just like you would register any other service with Consul. This section outlines your options for registering Connect proxies, either using independent registrations, or in nested sidecar registrations.
## Proxy Service Registration
To register proxies with independent proxy service registrations, you can define them in either in config files or via the API just like any other service. Learn more about all of the options you can define when registering your proxy service in the [proxy registration documentation](/docs/connect/registration/service-registration.html).
## Sidecar Service Registration
To reduce the amount of boilerplate needed for a sidecar proxy,
application service definitions may define an inline sidecar service block. This is an opinionated
shorthand for a separate full proxy registration as described above. For a
description of how to configure the sidecar proxy as well as the opinionated defaults, see the [sidecar service registrations
documentation](/docs/connect/registration/sidecar-service.html).

189
website/source/docs/connect/registration/service-registration.html.md Normal file
View File

@ -0,0 +1,189 @@
---
layout: "docs"
page_title: "Connect - Service Registration"
sidebar_current: "docs-connect-registration-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 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.
To declare a service as a proxy, the service definition must contain
the following fields:
* `kind` `(string)` must be set to `connect-proxy`. This declares that the
service is a proxy type.
* `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`.
* `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.
Minimal Example:
```json
{
"name": "redis-proxy",
"kind": "connect-proxy",
"proxy": {
"destination_service_name": "redis"
},
"port": 8181
}
```
With this service registered, any Connect clients searching for a
Connect-capable endpoint for "redis" will find this proxy.
### Sidecar Proxy Fields
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:
* `proxy.destination_service_id` `(string: <required>)` 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.
* `proxy.local_service_port` `(int: <required>)` must specify the port the
proxy should use to connect to the _local_ service instance.
* `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`.
### Complete Configuration Example
The following is a complete example showing all the options available when
registering a proxy instance.
```json
{
"name": "redis-proxy",
"kind": "connect-proxy",
"proxy": {
"destination_service_name": "redis",
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
"config": {},
"upstreams": []
},
"port": 8181
}
```
#### Proxy Parameters
- `destination_service_name` `(string: <required>)` - 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: <optional>)` - 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.
- `config` `(object: {})` - Specifies opaque config JSON that will be
stored and returned along with the service instance from future API calls.
- `upstreams` `(array<Upstream>: [])` - Specifies the upstream services
this proxy should create listeners for. The format is defined in
[Upstream Configuration Reference](#upstream-configuration-reference).
### Upstream Configuration Reference
The following examples show all possible upstream configuration parameters.
Note that in versions 1.2.0 to 1.3.0, managed proxy upstreams were specified
inside the opaque `connect.proxy.config` map. The format is almost unchanged
however managed proxy upstreams are now defined a level up in the
`connect.proxy.upstreams`. The old location is deprecated and will be
automatically converted into the new for an interim period before support is
dropped in a future major release. The only difference in format between the
upstream definitions is that the field `destination_datacenter` has been renamed
to `datacenter` to reflect that it's the discovery target and not necessarily
the same as the instance that will be returned in the case of a prepared query
that fails over to another datacenter.
Note that `snake_case` is used here as it works in both [config file and API
registrations](/docs/agent/services.html#service-definition-parameter-case).
Upstreams support multiple destination types. Both examples are shown below
followed by documentation for each attribute.
#### Service Destination
```json
{
"destination_type": "service",
"destination_name": "redis",
"datacenter": "dc1",
"local_bind_address": "127.0.0.1",
"local_bind_port": 1234,
"config": {}
},
```
#### Prepared Query Destination
```json
{
"destination_type": "prepared_query",
"destination_name": "database",
"local_bind_address": "127.0.0.1",
"local_bind_port": 1234,
"config": {}
},
```
* `destination_name` `(string: <required>)` - 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.
* `local_bind_port` `(int: <required>)` - 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`.
* `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 too. 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/configuration.html#built-in-proxy-options) for
options available when using the built-in proxy. If using Envoy as a proxy,
see [Envoy configuration
reference](/docs/connect/configuration.html#envoy-options)

7
website/source/docs/connect/proxies/sidecar-service.md → website/source/docs/connect/registration/sidecar-service.md
View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Connect - Sidecar Service Registration"
sidebar_current: "docs-connect-proxies-sidecar-service"
sidebar_current: "docs-connect-registration-sidecar-service"
description: |-
Sidecar service registrations provide a convenient shorthand for registering a
sidecar proxy inline with a regular service definition.
@ -106,9 +106,9 @@ overridden to customize the proxy configuration.
```
This example customizes the [proxy
upstreams](/docs/connect/proxies.html#upstream-configuration-reference)
upstreams](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
and some [built-in proxy
configuration](/docs/connect/configuration.html#built-in-proxy-options).
configuration](/docs/connect/proxies/built-in.html).
## Sidecar Service Defaults
@ -177,4 +177,3 @@ service's ID. This enables the following behavior.
ID, then a new service instance _and_ a new sidecar instance will be
registered. The old ones will be removed since they are no longer found in
the config files.

34
website/source/docs/enterprise/connect-multi-datacenter/index.html.md
View File

@ -12,17 +12,17 @@ description: |-
connections across multiple Consul datacenters. This includes replication of intentions
and federation of Certificate Authority trust.
Sidecar proxy's [upstream configuration](/docs/connect/proxies.html#upstream-configuration-reference)
may specify an alternative datacenter or a prepared query that can address services
Sidecar proxy's [upstream configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference)
may specify an alternative datacenter or a prepared query that can address services
in multiple datacenters (such as the [geo failover](https://learn.hashicorp.com/consul/developer-discovery/geo-failover) pattern).
[Intentions](/docs/connect/intentions.html) verify connections between services by
source and destination name seamlessly across datacenters. Support for constraining Intentions
[Intentions](/docs/connect/intentions.html) verify connections between services by
source and destination name seamlessly across datacenters. Support for constraining Intentions
by source or destination datacenter is planned for the near future.
It is assumed that workloads can communicate between datacenters via existing network
routes and VPN tunnels, potentially using Consul's
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) to ensure remote
It is assumed that workloads can communicate between datacenters via existing network
routes and VPN tunnels, potentially using Consul's
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) to ensure remote
workloads discover an externally routable IP.
# Replication
@ -34,20 +34,20 @@ must also be set in secondary datacenter server's configuration.
# Certificate Authority Federation
The primary datacenter also acts as the root Certificate Authority (CA) for Connect.
The primary datacenter generates a trust-domain UUID and obtains a root certificate
from the configured CA provider which defaults to the built-in one.
The primary datacenter also acts as the root Certificate Authority (CA) for Connect.
The primary datacenter generates a trust-domain UUID and obtains a root certificate
from the configured CA provider which defaults to the built-in one.
Secondary datacenters fetch the root CA public key and trust-domain ID from the primary and
generate their own key and Certificate Signing Request (CSR) for an intermediate CA certificate.
This CSR is signed by the root in the primary datacenter and the certificate is returned.
The secondary datacenter can now use this intermediate to sign new Connect certificates
in the secondary datacenter without WAN communication. CA keys are never replicated between
Secondary datacenters fetch the root CA public key and trust-domain ID from the primary and
generate their own key and Certificate Signing Request (CSR) for an intermediate CA certificate.
This CSR is signed by the root in the primary datacenter and the certificate is returned.
The secondary datacenter can now use this intermediate to sign new Connect certificates
in the secondary datacenter without WAN communication. CA keys are never replicated between
datacenters.
The secondary maintains watches on the root CA certificate in the primary. If the CA root
changes for any reason such as rotation or migration to a new CA, the secondary automatically
generates new keys and has them signed by the primary datacenter's new root before initiating
an automatic rotation of all issued certificates in use throughout the secondary datacenter.
This makes CA root key rotation fully automatic and with zero downtime across multiple data
an automatic rotation of all issued certificates in use throughout the secondary datacenter.
This makes CA root key rotation fully automatic and with zero downtime across multiple data
centers.

37
website/source/layouts/docs.erb
View File

@ -465,28 +465,48 @@
</li>
<li<%= sidebar_current("docs-connect") %>>
<a href="/docs/connect/index.html">Connect</a>
<a href="/docs/connect/index.html">Connect - Service Mesh</a>
<ul class="nav">
<li<%= sidebar_current("docs-connect-config") %>>
<a href="/docs/connect/configuration.html">Configuration</a>
</li>
<li<%= sidebar_current("docs-connect-observability") %>>
<a href="/docs/connect/observability.html">Observability</a>
</li>
</li>
<li<%= sidebar_current("docs-connect-intentions") %>>
<a href="/docs/connect/intentions.html">Intentions - Security Policies</a>
</li>
<li<%= sidebar_current("docs-connect-internals") %>>
<a href="/docs/connect/connect-internals.html">Architecture</a>
</li>
<li<%= sidebar_current("docs-connect-proxies") %>>
<a href="/docs/connect/proxies.html">Proxies</a>
<a href="/docs/connect/proxies.html">Supported Proxies</a>
<ul class="nav">
<li<%= sidebar_current("docs-connect-proxies-sidecar-service") %>>
<a href="/docs/connect/proxies/sidecar-service.html">Sidecar Service Registration</a>
</li>
<li<%= sidebar_current("docs-connect-proxies-envoy") %>>
<a href="/docs/connect/proxies/envoy.html">Envoy</a>
</li>
<li<%= sidebar_current("docs-connect-proxies-built-in") %>>
<a href="/docs/connect/proxies/built-in.html">Built-in Proxy</a>
</li>
<li<%= sidebar_current("docs-connect-proxies-integrate") %>>
<a href="/docs/connect/proxies/integrate.html">Proxy Integration</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-connect-intentions") %>>
<a href="/docs/connect/intentions.html">Intentions</a>
<li<%= sidebar_current("docs-connect-registration") %>>
<a href="/docs/connect/registration.html">Registering Proxies</a>
<ul class="nav">
<li<%= sidebar_current("docs-connect-registration-service-registration") %>>
<a href="/docs/connect/registration/service-registration.html">Proxy Service Registration</a>
</li>
<li<%= sidebar_current("docs-connect-registration-sidecar-service") %>>
<a href="/docs/connect/registration/sidecar-service.html">Sidecar Service Registration</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-connect-security") %>>
<a href="/docs/connect/security.html">Securing Connect</a>
</li>
<li<%= sidebar_current("docs-connect-ca") %>>
<a href="/docs/connect/ca.html">Certificate Management</a>
@ -516,9 +536,6 @@
<li<%= sidebar_current("docs-connect-platform-k8s") %>>
<a href="/docs/platform/k8s/connect.html">Kubernetes</a>
</li>
<li<%= sidebar_current("docs-connect-security") %>>
<a href="/docs/connect/security.html">Security</a>
</li>
</ul>
</li>

1
website/source/redirects.txt
View File

@ -48,6 +48,7 @@
/docs/guides/acl-migrate-tokens.html https://www.consul.io/docs/acl/acl-migrate-tokens.html
/docs/guides/bootstrapping.html https://www.consul.io/docs/install/bootstrapping.html
/docs/guides/sentinel.html https://www.consul.io/docs/agent/sentinel.html
/docs/connect/proxies/sidecar-service.html https://www.consul.io/docs/connect/registration/sidecar-service.html
# CLI renames
/docs/commands/acl/acl-bootstrap.html https://www.consul.io/docs/commands/acl/bootstrap.html