consul/website/content/docs/connect/proxies/deploy-sidecar-services.mdx

---
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 configuration 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.