mirror of https://github.com/status-im/consul.git
284 lines
12 KiB
Plaintext
284 lines
12 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Deploy proxies as sidecar services
|
|
description: >-
|
|
You can register a service instance and its sidecar proxy at the same time. Learn about default settings, customizable parameters, limitations, and lifecycle behaviors of the sidecar proxy.
|
|
---
|
|
|
|
# Deploy sidecar services
|
|
|
|
This topic describes how to create, register, and start sidecar proxy services in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul's functions and operations. For information about deploying service mesh proxies, refer to [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies).
|
|
|
|
## Overview
|
|
|
|
Sidecar proxies run on the same node as the single service instance that they handle traffic for.
|
|
They may be on the same VM or running as a separate container in the same network namespace.
|
|
|
|
You can attach a sidecar proxy to a service you want to deploy to your mesh:
|
|
|
|
1. It is not required, but you can create a proxy defaults configuration entry that contains global passthrough settings for all Envoy proxies.
|
|
1. Create the service definition and include the `connect` block. The `connect` block contains the sidecar proxy configurations that allow the service to interact with other services in the mesh.
|
|
1. Register the service using either the API or CLI.
|
|
1. Start the sidecar proxy service.
|
|
|
|
## Requirements
|
|
|
|
If ACLs are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information.
|
|
|
|
## Configure global Envoy passthrough settings
|
|
|
|
If you want to define global passthrough settings for all Envoy proxies, create a proxy defaults configuration entry and specify default settings, such as access log configuration. [Service defaults configuration entries](/consul/docs/connect/config-entries/service-defaults) override proxy defaults and individual service configurations override both configuration entries.
|
|
|
|
1. Create a proxy defaults configuration entry and specify the following parameters:
|
|
- `Kind`: Must be set to `proxy-defaults`
|
|
- `Name`: Must be set to `global`
|
|
1. Configure any additional settings you want to apply to all proxies. Refer to [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) for details about all settings available in the configuraiton entry.
|
|
1. Apply the configuration by either calling the [`/config` API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). The following example writes a proxy defaults configuration entry from a local HCL file using the CLI:
|
|
|
|
```shell-session
|
|
$ consul config write proxy-defaults.hcl
|
|
```
|
|
|
|
## Define service mesh proxy
|
|
|
|
Create a service definition and configure the following fields:
|
|
|
|
1. `name`: Specify a name for the service you want to attach a sidecar proxy to in the `name` field. This field is required for all services you want to register in Consul.
|
|
1. `port`: Specify a port number where other services registered with Consul can discover and connect to the service in the `port` field. This field is required for all services you want to register in Consul.
|
|
1. `connect`: Set the `connect` field to `{ sidecar_service: {} }`. The `{ sidecar_service: {} }` value is a macro that applies a set of default configurations that enable you to quickly implement a sidecar. Refer to [Sidecar service defaults](#sidecar-service-defaults) for additional information.
|
|
1. Configure any additional options for your service. Refer to [Services configuration reference](/consul/docs/services/configuration/services-configuration-reference) for details.
|
|
|
|
In the following example, a service named `web` is configured with a sidecar proxy:
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="HCL" group="hcl">
|
|
|
|
```hcl
|
|
service = {
|
|
name = "web"
|
|
port = 8080
|
|
connect = { sidecar_service = {} }
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="JSON" group="json">
|
|
|
|
```json
|
|
|
|
{
|
|
"service": {
|
|
"name": "web",
|
|
"port": 8080,
|
|
"connect": { "sidecar_service": {} }
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
When Consul processes the service definition, it generates the following configuration in place of the `sidecar_service` macro. Note that sidecar proxies services are based on the `connect-proxy` type:
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="HCL" group="hcl">
|
|
|
|
```hcl
|
|
services = [
|
|
{
|
|
name = "web"
|
|
port = 8080
|
|
}
|
|
checks = {
|
|
Interval = "10s"
|
|
Name = "Connect Sidecar Listening"
|
|
TCP = "127.0.0.1:20000"
|
|
}
|
|
checks = {
|
|
alias_service = "web"
|
|
name = "Connect Sidecar Aliasing web"
|
|
}
|
|
kind = "connect-proxy"
|
|
name = "web-sidecar-proxy"
|
|
port = 20000
|
|
proxy = {
|
|
destination_service_id = "web"
|
|
destination_service_name = "web"
|
|
local_service_address = "127.0.0.1"
|
|
local_service_port = 8080
|
|
}
|
|
]
|
|
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="JSON" group="json">
|
|
|
|
```json
|
|
{
|
|
"services": [
|
|
{
|
|
"name": "web",
|
|
"port": 8080
|
|
},
|
|
{
|
|
"name": "web-sidecar-proxy",
|
|
"port": 20000,
|
|
"kind": "connect-proxy",
|
|
"checks": [
|
|
{
|
|
"Name": "Connect Sidecar Listening",
|
|
"TCP": "127.0.0.1:20000",
|
|
"Interval": "10s"
|
|
},
|
|
{
|
|
"name": "Connect Sidecar Aliasing web",
|
|
"alias_service": "web"
|
|
}
|
|
],
|
|
"proxy": {
|
|
"destination_service_name": "web",
|
|
"destination_service_id": "web",
|
|
"local_service_address": "127.0.0.1",
|
|
"local_service_port": 8080
|
|
}
|
|
}
|
|
]
|
|
}
|
|
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
## Register the service
|
|
|
|
Provide the service definition to the Consul agent to register your proxy service. You can use the same methods for registering proxy services as you do for registering application services:
|
|
|
|
- Place the service definition in a Consul agent's configuration directory and start, restart, or reload the agent. Use this method when implementing changes to an existing proxy service.
|
|
- Use the `consul services register` command to register the proxy service with a running Consul agent.
|
|
- Call the `/agent/service/register` HTTP API endpoint to register the proxy service with a running Consul agent.
|
|
|
|
Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions.
|
|
|
|
In the following example, the `consul services register` command registers a proxy service stored in `proxy.hcl`:
|
|
|
|
```shell-session
|
|
$ consul services register proxy.hcl
|
|
```
|
|
|
|
## Start the proxy
|
|
|
|
Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the proxy service. Specify the name of the service with the attached proxy with the `-sidecar-for` option.
|
|
|
|
The following example command starts an Envoy sidecar proxy for the `web` service:
|
|
|
|
```shell-session
|
|
$ consul connect envoy -sidecar-for=web
|
|
```
|
|
|
|
For details about operating an Envoy proxy in Consul, refer to [](/consul/docs/connect/proxies/envoy)
|
|
|
|
## Configuration reference
|
|
|
|
The `sidecar_service` block is a service definition that can contain most regular service definition fields. Refer to [Limitations](#limitations) for information about unsupported service definition fields for sidecar proxies.
|
|
|
|
Consul treats sidecar proxy service definitions as a root-level service definition. All fields are optional in nested definitions, which default to opinionated settings that are intended to reduce burden of setting up a sidecar proxy.
|
|
|
|
## Sidecar service defaults
|
|
|
|
The following fields are set by default on a sidecar service registration. With
|
|
[the exceptions noted](#limitations) any field may be overridden explicitly in
|
|
the `connect.sidecar_service` definition to customize the proxy registration.
|
|
The "parent" service refers to the service definition that embeds the sidecar
|
|
proxy.
|
|
|
|
- `id` - ID defaults to `<parent-service-id>-sidecar-proxy`. This value cannot
|
|
be overridden as it is used to [manage the lifecycle](#lifecycle) of the
|
|
registration.
|
|
- `name` - Defaults to `<parent-service-name>-sidecar-proxy`.
|
|
- `tags` - Defaults to the tags of the parent service.
|
|
- `meta` - Defaults to the service metadata of the parent service.
|
|
- `port` - Defaults to being auto-assigned from a configurable
|
|
range specified by [`sidecar_min_port`](/consul/docs/agent/config/config-files#sidecar_min_port)
|
|
and [`sidecar_max_port`](/consul/docs/agent/config/config-files#sidecar_max_port).
|
|
- `kind` - Defaults to `connect-proxy`. This value cannot be overridden.
|
|
- `check`, `checks` - By default we add a TCP check on the local address and
|
|
port for the proxy, and a [service alias
|
|
check](/consul/docs/services/usage/checks#alias-checks) for the parent service. If either
|
|
`check` or `checks` fields are set, only the provided checks are registered.
|
|
- `proxy.destination_service_name` - Defaults to the parent service name.
|
|
- `proxy.destination_service_id` - Defaults to the parent service ID.
|
|
- `proxy.local_service_address` - Defaults to `127.0.0.1`.
|
|
- `proxy.local_service_port` - Defaults to the parent service port.
|
|
|
|
### Example with overwritten configurations
|
|
|
|
In the following example, the `sidecar_service` macro sets baselines configurations for the proxy, but the [proxy
|
|
upstreams](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference)
|
|
and [built-in proxy
|
|
configuration](/consul/docs/connect/proxies/built-in) fields contain custom values:
|
|
|
|
```json
|
|
{
|
|
"name": "web",
|
|
"port": 8080,
|
|
"connect": {
|
|
"sidecar_service": {
|
|
"proxy": {
|
|
"upstreams": [
|
|
{
|
|
"destination_name": "db",
|
|
"local_bind_port": 9191
|
|
}
|
|
],
|
|
"config": {
|
|
"handshake_timeout_ms": 1000
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Limitations
|
|
|
|
The following fields are not supported in the `connect.sidecar_service` block:
|
|
|
|
- `id` - Sidecar services get an ID assigned and it is an error to override
|
|
this value. This ID is required to ensure that the agent can correctly deregister the sidecar service
|
|
later when the parent service is removed.
|
|
- `kind` - Kind defaults to `connect-proxy` and there is no way to
|
|
unset this behavior.
|
|
- `connect.sidecar_service` - Service definitions cannot be nested recursively.
|
|
- `connect.native` - The `kind` is fixed to `connect-proxy` and it is
|
|
an error to register a `connect-proxy` that is also service mesh-native.
|
|
|
|
## Lifecycle
|
|
|
|
Sidecar service registration is mostly a configuration syntax helper to avoid
|
|
adding lots of boiler plate for basic sidecar options, however the agent does
|
|
have some specific behavior around their lifecycle that makes them easier to
|
|
work with.
|
|
|
|
The agent fixes the ID of the sidecar service to be based on the parent
|
|
service's ID, which enables the following behavior.
|
|
|
|
- A service instance can only ever have one sidecar service registered.
|
|
- When re-registering through the HTTP API or reloading from configuration file:
|
|
- If something changes in the nested sidecar service definition, the update is applied to the current sidecar registration instead of creating a new
|
|
one.
|
|
- If a service registration removes the nested `sidecar_service` then the
|
|
previously registered sidecar for that service is deregistered
|
|
automatically.
|
|
- When reloading the configuration files, if a service definition changes its
|
|
ID, then a new service instance and a new sidecar instance are
|
|
registered. The old instance and proxy are removed because they are no longer found in
|
|
the configuration files. |