Deploy sidecar services

This topic describes how to create, register, and start sidecar proxy services in Consul. Refer to Service mesh proxies overview 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.

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:

It is not required, but you can create a proxy defaults configuration entry that contains global passthrough settings for all Envoy proxies.
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.
Register the service using either the API or CLI.
Start the sidecar proxy service.

Requirements

If ACLs are enabled and you want to configure global Envoy settings in the proxy defaults configuration entry, you must present a token with operator:write permissions. Refer to 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 override proxy defaults and individual service configurations override both configuration entries.

Create a proxy defaults configuration entry and specify the following parameters:
- Kind: Must be set to proxy-defaults
- Name: Must be set to global
Configure any additional settings you want to apply to all proxies. Refer to Proxy defaults configuration entry reference for details about all settings available in the configuraiton entry.
Apply the configuration by either calling the /config API endpoint or running the consul config write CLI command. The following example writes a proxy defaults configuration entry from a local HCL file using the CLI:

$ consul config write proxy-defaults.hcl

Define service mesh proxy

Create a service definition and configure the following fields:

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.
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.
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 for additional information.
Configure any additional options for your service. Refer to Services configuration reference for details.

In the following example, a service named web is configured with a sidecar proxy:

service = {
  name = "web"
  port = 8080
  connect = { sidecar_service = {} }
}

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:

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
    }
]

{
  "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
      }
    }
  ]
}

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 for instructions.

In the following example, the consul services register command registers a proxy service stored in proxy.hcl:

$ consul services register proxy.hcl

Start the proxy

Envoy requires a bootstrap configuration file before it can start. Use the consul connect envoy command 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:

$ consul connect envoy -sidecar-for=web

For details about operating an Envoy proxy in Consul, refer to

Configuration reference

The sidecar_service block is a service definition that can contain most regular service definition fields. Refer to 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 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 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 and 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 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 and built-in proxy configuration fields contain custom values:

{
  "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.