|
| 1 | +--- |
| 2 | +layout: docs |
| 3 | +page_title: Deploy proxies as sidecar services |
| 4 | +description: >- |
| 5 | + 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. |
| 6 | +--- |
| 7 | + |
| 8 | +# Deploy sidecar services |
| 9 | + |
| 10 | +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 functionalities. For information about deploying service mesh proxies, refer to [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies). |
| 11 | + |
| 12 | +## Overview |
| 13 | + |
| 14 | +Sidecar proxies run on the same node as the single service instance that they handle traffic for. |
| 15 | +They may be on the same VM or running as a separate container in the same network namespace. |
| 16 | + |
| 17 | +You can attach a sidecar proxy to a service you want to deploy to your mesh: |
| 18 | + |
| 19 | +1. It is not required, but you can create a proxy defaults configuration entry that contains global passthrough settings for all Envoy proxies. |
| 20 | +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. |
| 21 | +1. Register the service using either the API or CLI. |
| 22 | +1. Start the sidecar proxy service. |
| 23 | + |
| 24 | +## Requirements |
| 25 | + |
| 26 | +If [ACLs](/consul/docs/security/acl) 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. |
| 27 | + |
| 28 | +## Configure global Envoy passthrough settings |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +1. Create a proxy defaults configuration entry and specify the following parameters: |
| 33 | + - `Kind`: Must be set to `proxy-defaults` |
| 34 | + - `Name`: Must be set to `global` |
| 35 | +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. |
| 36 | +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: |
| 37 | + |
| 38 | +```shell-session |
| 39 | +$ consul config write proxy-defaults.hcl |
| 40 | +``` |
| 41 | + |
| 42 | +## Define service mesh proxy |
| 43 | + |
| 44 | +Create a service definition and configure the following fields: |
| 45 | + |
| 46 | +1. 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. |
| 47 | +1. 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. |
| 48 | +1. 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. |
| 49 | +1. Configure any additional options for your service. Refer to [Services configuration reference](/consul/docs/services/configuration/services-configuration-reference) for details. |
| 50 | + |
| 51 | +In the following example, a service named `web` is configured with a sidecar proxy: |
| 52 | + |
| 53 | +<Tabs> |
| 54 | + |
| 55 | +<Tab heading="HCL" group="hcl"> |
| 56 | + |
| 57 | +```hcl |
| 58 | +service = { |
| 59 | + name = "web" |
| 60 | + port = 8080 |
| 61 | + connect = { sidecar_service = {} } |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +</Tab> |
| 66 | + |
| 67 | +<Tab heading="JSON" group="json"> |
| 68 | + |
| 69 | +```json |
| 70 | + |
| 71 | +{ |
| 72 | + "service": { |
| 73 | + "name": "web", |
| 74 | + "port": 8080, |
| 75 | + "connect": { "sidecar_service": {} } |
| 76 | + } |
| 77 | +} |
| 78 | + |
| 79 | +``` |
| 80 | + |
| 81 | +</Tab> |
| 82 | + |
| 83 | +</Tabs> |
| 84 | + |
| 85 | +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: |
| 86 | + |
| 87 | +<Tabs> |
| 88 | + |
| 89 | +<Tab heading="HCL" group="hcl"> |
| 90 | + |
| 91 | +```hcl |
| 92 | +services = [ |
| 93 | + { |
| 94 | + name = "web" |
| 95 | + port = 8080 |
| 96 | + } |
| 97 | + checks = { |
| 98 | + Interval = "10s" |
| 99 | + Name = "Connect Sidecar Listening" |
| 100 | + TCP = "127.0.0.1:20000" |
| 101 | + } |
| 102 | + checks = { |
| 103 | + alias_service = "web" |
| 104 | + name = "Connect Sidecar Aliasing web" |
| 105 | + } |
| 106 | + kind = "connect-proxy" |
| 107 | + name = "web-sidecar-proxy" |
| 108 | + port = 20000 |
| 109 | + proxy = { |
| 110 | + destination_service_id = "web" |
| 111 | + destination_service_name = "web" |
| 112 | + local_service_address = "127.0.0.1" |
| 113 | + local_service_port = 8080 |
| 114 | + } |
| 115 | +] |
| 116 | +
|
| 117 | +``` |
| 118 | + |
| 119 | +</Tab> |
| 120 | + |
| 121 | +<Tab heading="JSON" group="json"> |
| 122 | + |
| 123 | +```json |
| 124 | +{ |
| 125 | + "services": [ |
| 126 | + { |
| 127 | + "name": "web", |
| 128 | + "port": 8080 |
| 129 | + }, |
| 130 | + { |
| 131 | + "name": "web-sidecar-proxy", |
| 132 | + "port": 20000, |
| 133 | + "kind": "connect-proxy", |
| 134 | + "checks": [ |
| 135 | + { |
| 136 | + "Name": "Connect Sidecar Listening", |
| 137 | + "TCP": "127.0.0.1:20000", |
| 138 | + "Interval": "10s" |
| 139 | + }, |
| 140 | + { |
| 141 | + "name": "Connect Sidecar Aliasing web", |
| 142 | + "alias_service": "web" |
| 143 | + } |
| 144 | + ], |
| 145 | + "proxy": { |
| 146 | + "destination_service_name": "web", |
| 147 | + "destination_service_id": "web", |
| 148 | + "local_service_address": "127.0.0.1", |
| 149 | + "local_service_port": 8080 |
| 150 | + } |
| 151 | + } |
| 152 | + ] |
| 153 | +} |
| 154 | + |
| 155 | +``` |
| 156 | + |
| 157 | +</Tab> |
| 158 | + |
| 159 | +</Tabs> |
| 160 | + |
| 161 | +## Register the service |
| 162 | + |
| 163 | +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: |
| 164 | + |
| 165 | +- 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. |
| 166 | +- Use the `consul services register` command to register the proxy service with a running Consul agent. |
| 167 | +- Call the `/agent/service/register` HTTP API endpoint to register the proxy service with a running Consul agent. |
| 168 | + |
| 169 | +Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions. |
| 170 | + |
| 171 | +In the following example, the `consul services register` command registers a proxy service stored in `proxy.hcl`: |
| 172 | + |
| 173 | +```shell-session |
| 174 | +$ consul services register proxy.hcl |
| 175 | +``` |
| 176 | + |
| 177 | +## Start the proxy |
| 178 | + |
| 179 | +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. |
| 180 | + |
| 181 | +The following example command starts an Envoy sidecar proxy for the `web` service: |
| 182 | + |
| 183 | +```shell-session |
| 184 | +$ consul connect envoy -sidecar-for=web |
| 185 | +``` |
| 186 | + |
| 187 | +For details about operating an Envoy proxy in Consul, refer to [](/consul/docs/connect/proxies/envoy) |
| 188 | + |
| 189 | +## Configuration reference |
| 190 | + |
| 191 | +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. |
| 192 | + |
| 193 | +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. |
| 194 | + |
| 195 | +## Sidecar service defaults |
| 196 | + |
| 197 | +The following fields are set by default on a sidecar service registration. With |
| 198 | +[the exceptions noted](#limitations) any field may be overridden explicitly in |
| 199 | +the `connect.sidecar_service` definition to customize the proxy registration. |
| 200 | +The "parent" service refers to the service definition that embeds the sidecar |
| 201 | +proxy. |
| 202 | + |
| 203 | +- `id` - ID defaults to being `<parent-service-id>-sidecar-proxy`. This can't |
| 204 | + be overridden as it is used to [manage the lifecycle](#lifecycle) of the |
| 205 | + registration. |
| 206 | +- `name` - Defaults to being `<parent-service-name>-sidecar-proxy`. |
| 207 | +- `tags` - Defaults to the tags of the parent service. |
| 208 | +- `meta` - Defaults to the service metadata of the parent service. |
| 209 | +- `port` - Defaults to being auto-assigned from a configurable |
| 210 | + range specified by [`sidecar_min_port`](/consul/docs/agent/config/config-files#sidecar_min_port) |
| 211 | + and [`sidecar_max_port`](/consul/docs/agent/config/config-files#sidecar_max_port). |
| 212 | +- `kind` - Defaults to `connect-proxy`. This can't be overridden currently. |
| 213 | +- `check`, `checks` - By default we add a TCP check on the local address and |
| 214 | + port for the proxy, and a [service alias |
| 215 | + check](/consul/docs/services/usage/checks#alias-checks) for the parent service. If either |
| 216 | + `check` or `checks` fields are set, only the provided checks are registered. |
| 217 | +- `proxy.destination_service_name` - Defaults to the parent service name. |
| 218 | +- `proxy.destination_service_id` - Defaults to the parent service ID. |
| 219 | +- `proxy.local_service_address` - Defaults to `127.0.0.1`. |
| 220 | +- `proxy.local_service_port` - Defaults to the parent service port. |
| 221 | + |
| 222 | +### Example with overwritten configurations |
| 223 | + |
| 224 | +In the following example, but the `sidecar_service` macro sets baselines configurations for the proxy, but the [proxy |
| 225 | +upstreams](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) |
| 226 | +and [built-in proxy |
| 227 | +configuration](/consul/docs/connect/proxies/built-in) fields contain custom values: |
| 228 | + |
| 229 | +```json |
| 230 | +{ |
| 231 | + "name": "web", |
| 232 | + "port": 8080, |
| 233 | + "connect": { |
| 234 | + "sidecar_service": { |
| 235 | + "proxy": { |
| 236 | + "upstreams": [ |
| 237 | + { |
| 238 | + "destination_name": "db", |
| 239 | + "local_bind_port": 9191 |
| 240 | + } |
| 241 | + ], |
| 242 | + "config": { |
| 243 | + "handshake_timeout_ms": 1000 |
| 244 | + } |
| 245 | + } |
| 246 | + } |
| 247 | + } |
| 248 | +} |
| 249 | +``` |
| 250 | + |
| 251 | +## Limitations |
| 252 | + |
| 253 | +The following fields are not supported in the `connect.sidecar_service` block: |
| 254 | + |
| 255 | +- `id` - Sidecar services get an ID assigned and it is an error to override |
| 256 | + this. This ensures the agent can correctly deregister the sidecar service |
| 257 | + later when the parent service is removed. |
| 258 | +- `kind` - Kind defaults to `connect-proxy` and there is currently no way to |
| 259 | + unset this to make the registration be for a regular non-connect-proxy |
| 260 | + service. |
| 261 | +- `connect.sidecar_service` - Service definitions can't be nested recursively. |
| 262 | +- `connect.native` - Currently the `kind` is fixed to `connect-proxy` and it's |
| 263 | + an error to register a `connect-proxy` that is also service mesh-native. |
| 264 | + |
| 265 | +## Lifecycle |
| 266 | + |
| 267 | +Sidecar service registration is mostly a configuration syntax helper to avoid |
| 268 | +adding lots of boiler plate for basic sidecar options, however the agent does |
| 269 | +have some specific behavior around their lifecycle that makes them easier to |
| 270 | +work with. |
| 271 | + |
| 272 | +The agent fixes the ID of the sidecar service to be based on the parent |
| 273 | +service's ID. This enables the following behavior. |
| 274 | + |
| 275 | +- A service instance can _only ever have one_ sidecar service registered. |
| 276 | +- When re-registering via API or reloading from configuration file: |
| 277 | + - If something changes in the nested sidecar service definition, the change |
| 278 | + will _update_ the current sidecar registration instead of creating a new |
| 279 | + one. |
| 280 | + - If a service registration removes the nested `sidecar_service` then the |
| 281 | + previously registered sidecar for that service will be deregistered |
| 282 | + automatically. |
| 283 | +- When reloading the configuration files, if a service definition changes its |
| 284 | + ID, then a new service instance _and_ a new sidecar instance will be |
| 285 | + registered. The old ones will be removed since they are no longer found in |
| 286 | + the config files. |
0 commit comments