consul/website/content/docs/ecs/configuration-reference.mdx

---
layout: docs
page_title: Consul on AWS Elastic Container Service (ECS) Configuration Reference
description: >-
  Use the `consul-ecs` reference guide to manually configure Consul for deployment on Amazon Web Services ECS. Learn how the config values correspond to Terraform module input variables and review JSON configuration models for `consulLogin`, `gateway`, `proxy`, and `service` fields.
---

# Consul on AWS Elastic Container Service (ECS) Configuration Reference

This pages details the configuration options for the JSON config format used
by the `consul-ecs` binary. This configuration is passed to the `consul-ecs`
binary as a string using the `CONSUL_ECS_CONFIG_JSON` environment variable.

This configuration format follows a [JSON schema](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json)
that can be used for validation.

## Terraform Mesh Task Module Configuration

The `mesh-task` Terraform module provides input variables for commonly used fields.
The following table shows which Terraform input variables correspond to each field
of the Consul ECS configuration. Refer to the
[Terraform registry documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs)
for a complete reference of supported input variables for the `mesh-task` module.

| Terraform Input Variable | Consul ECS Config Field               |
| ------------------------ | ------------------------------------- |
| `upstreams`              | [`proxy.upstreams`](#proxy-upstreams) |
| `checks`                 | [`service.checks`](#service-checks)   |
| `consul_service_name`    | [`service.name`](#service)            |
| `consul_service_tags`    | [`service.tags`](#service)            |
| `consul_service_meta`    | [`service.meta`](#service)            |
| `consul_namespace`       | [`service.namespace`](#service)       |
| `consul_partition`       | [`service.partition`](#service)       |

Each of these Terraform input variables follow the Consul ECS config schema.
The remaining fields of the Consul ECS configuration not listed in this table can be passed
using the `consul_ecs_config` input variable.

# Top-level fields

These are the top-level fields for the Consul ECS configuration format.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `bootstrapDir` | `string` | required | The directory at which to mount the shared volume where Envoy bootstrap configuration is written by `consul-ecs mesh-init`.  |
| `consulCACertFile` | `string` | optional | The file path of the Consul server CA certificate.  |
| `consulHTTPAddr` | `string` | optional | The HTTP(S) URL of the Consul server. Required when `authMethod.enabled` is set  |
| [`consulLogin`](#consullogin) | `object` | optional | Configuration for logging into the AWS IAM auth method.  |
| [`gateway`](#gateway) | `object` | optional | Configuration for the gateway proxy registration.  |
| `healthSyncContainers` | `array` | optional | The names of containers that will have health check status synced from ECS into Consul. Cannot be specified with `service.checks`.  |
| `logLevel` | `string` | optional | Sets the log level for the `consul-ecs mesh-init` and `consul-ecs health-sync` commands. Defaults to `INFO`. Must be one of `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `null`. |
| [`proxy`](#proxy) | `object` | optional | Configuration for the sidecar proxy registration with Consul.  |
| [`service`](#service) | `object` | optional | Configuration for Consul service registration.  |

# `consulLogin`

Configuration for logging into the AWS IAM auth method.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `enabled` | `boolean` | optional | Enables logging into Consul's AWS IAM auth method to obtain an ACL token. The auth method must be configured on the Consul server and the ECS task role must be trusted by the auth method. After logging in, the token is written to the file `<bootstrapDir>/service-token`.  |
| `extraLoginFlags` | `array` | optional | Additional CLI flags to pass to the `consul login` command. These are appended to the command `consul login -type aws -method <name> -token-sink-file <file> -aws-auto-bearer-token -aws-include-identity`.  |
| `includeEntity` | `boolean` | optional | Adds the `-aws-include-entity` flag to the `consul login` command. Defaults to `true`. Set to `false` to remove the flag from the command. The `-aws-include-entity` flag should only be passed if the Consul AWS IAM auth method is configured with `EnableIAMEntityDetails=true`.  |
| `method` | `string` | optional | The name of Consul auth method. This is passed as the `-method` option to the `consul login` command. Defaults to `iam-ecs-service-token`.  |

# `gateway`

Configuration for the gateway proxy registration.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `kind` | `string` | required | Specifies the type of gateway to register. Must be `mesh-gateway`. |
| [`lanAddress`](#gateway-lanaddress) | `object` | optional | LAN address and port for the gateway. If not specified, defaults to the task/node address.  |
| `meta` | `object` | optional | Key-value pairs of metadata to include for the gateway.  |
| `name` | `string` | optional | The name the gateway will be registered as in Consul. Defaults to the Task family name.  |
| `namespace` | `string` | optional | <EnterpriseAlert inline /> Consul namespace in which the gateway will be registered.  |
| `partition` | `string` | optional | <EnterpriseAlert inline /> Consul admin partition in which the gateway will be registered.  |
| [`proxy`](#gateway-proxy) | `object` | optional | Object that contains the proxy parameters.  |
| `tags` | `array` | optional | List of string values that can be used to add labels to the gateway.  |
| [`wanAddress`](#gateway-wanaddress) | `object` | optional | WAN address and port for the gateway. If not specified, defaults to the task/node address.  |

# `gateway.lanAddress`

LAN address and port for the gateway. If not specified, defaults to the task/node address.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `address` | `string` | optional |   |
| `port` | `integer` | optional |   |

# `gateway.proxy`

Object that contains the proxy parameters.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `config` | `object` | optional |   |

# `gateway.wanAddress`

WAN address and port for the gateway. If not specified, defaults to the task/node address.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `address` | `string` | optional |   |
| `port` | `integer` | optional |   |

# `proxy`

Configuration for the sidecar proxy registration with Consul.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `config` | `object` | optional | Object value that specifies an opaque JSON configuration. The JSON is stored and returned along with the service instance when called from the API.  |
| [`meshGateway`](#proxy-meshgateway) | `object` | optional | Specifies the mesh gateway configuration for the proxy.  |
| [`upstreams`](#proxy-upstreams) | `array` | optional | The list of the upstream services that the proxy should create listeners for.  |

# `proxy.meshGateway`

Specifies the mesh gateway configuration for the proxy.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `mode` | `string` | required | Specifies how upstreams with a remote destination datacenter are resolved. Must be one of `none`, `local`, or `remote`. |

# `proxy.upstreams`

The list of the upstream services that the proxy should create listeners for. Each `upstream` object may contain the following fields.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `config` | `object` | optional | Specifies opaque configuration options that will be provided to the proxy instance for the upstream.  |
| `datacenter` | `string` | optional | Specifies the datacenter to issue the discovery query to.  |
| `destinationName` | `string` | required | Specifies the name of the upstream service or prepared query to route the service mesh to.  |
| `destinationNamespace` | `string` | optional | <EnterpriseAlert inline /> Specifies the namespace containing the upstream service.  |
| `destinationPartition` | `string` | optional | <EnterpriseAlert inline /> Specifies the name of the admin partition containing the upstream service.  |
| `destinationType` | `string` | optional | Specifies the type of discovery query the proxy should use for finding service mesh instances. Must be one of `service`, `prepared_query`, or `null`. |
| `localBindAddress` | `string` | optional | Specifies the address to bind a local listener to.  |
| `localBindPort` | `integer` | required | Specifies the port to bind a local listener to. The application will make outbound connections to the upstream from the local port.  |
| [`meshGateway`](#proxy-upstreams-meshgateway) | `object` | optional | Specifies the mesh gateway configuration for the proxy for this upstream.  |

## `proxy.upstreams.meshGateway`

Specifies the mesh gateway configuration for the proxy for this upstream.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `mode` | `string` | required | Specifies how the upstream with a remote destination datacenter gets resolved. Must be one of `none`, `local`, or `remote`. |

# `service`

Configuration for Consul service registration.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| [`checks`](#service-checks) | `array` | optional | The list of Consul checks for the service. Cannot be specified with `healthSyncContainers`.  |
| `enableTagOverride` | `boolean` | optional | Determines if the anti-entropy feature for the service is enabled  |
| `meta` | `object` | optional | Key-value pairs of metadata to include for the Consul service.  |
| `name` | `string` | optional | The name the service will be registered as in Consul. Defaults to the Task family name if empty or null.  |
| `namespace` | `string` | optional | <EnterpriseAlert inline /> The Consul namespace where the service will be registered.  |
| `partition` | `string` | optional | <EnterpriseAlert inline /> The Consul admin partition where the service will be registered.  |
| `port` | `integer` | required | Port the application listens on, if any.  |
| `tags` | `array` | optional | List of string values that can be used to add service-level labels.  |
| [`weights`](#service-weights) | `object` | optional | Configures the weight of the service in terms of its DNS service (SRV) response.  |

# `service.checks`

Defines the Consul checks for the service. Each `check` object may contain the following fields.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `aliasNode` | `string` | optional | Specifies the ID of the node for an alias check.  |
| `aliasService` | `string` | optional | Specifies the ID of a service for an alias check.  |
| `args` | `array` | optional | Command arguments to run to update the status of the check.  |
| `body` | `string` | optional | Specifies a body that should be sent with `HTTP` checks.  |
| `checkId` | `string` | optional | The unique ID for this check on the node. Defaults to the check `name`.  |
| `failuresBeforeCritical` | `integer` | optional | Specifies the number of consecutive unsuccessful results required before check status transitions to critical.  |
| `grpc` | `string` | optional | Specifies a `gRPC` check. Must be an endpoint that supports the [standard gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). The endpoint will be probed every `interval`.  |
| `grpcUseTls` | `boolean` | optional | Specifies whether to use TLS for this gRPC health check.  |
| `h2ping` | `string` | optional | Specifies this is an h2ping check. Must be an address, which will be pinged every `interval`.  |
| `h2pingUseTls` | `boolean` | optional | Specifies whether TLS is used for an h2ping check.  |
| `header` | `object` | optional | Specifies a set of headers that should be set for HTTP checks. Each header can have multiple values.  |
| `http` | `string` | optional | Specifies this is an HTTP check. Must be a URL against which request is performed every `interval`.  |
| `interval` | `string` | optional | Specifies the frequency at which to run this check. Required for HTTP, TCP, and UDP checks.  |
| `method` | `string` | optional | Specifies the HTTP method to be used for an HTTP check. When no value is specified, `GET` is used.  |
| `name` | `string` | optional | The name of the check.  |
| `notes` | `string` | optional | Specifies arbitrary information for humans. This is not used by Consul internally.  |
| `status` | `string` | optional | Specifies the initial status the health check. Must be one of `passing`, `warning`, `critical`, `maintenance`, or `null`. |
| `successBeforePassing` | `integer` | optional | Specifies the number of consecutive successful results required before check status transitions to passing.  |
| `tcp` | `string` | optional | Specifies this is a TCP check. Must be an IP/hostname plus port to which a TCP connection is made every `interval`.  |
| `timeout` | `string` | optional | Specifies a timeout for outgoing connections. Applies to script, HTTP, TCP, UDP, and gRPC checks. Must be a duration string, such as `10s` or `5m`.  |
| `tlsServerName` | `string` | optional | Specifies an optional string used to set the SNI host when connecting via TLS.  |
| `tlsSkipVerify` | `boolean` | optional | Specifies if the certificate for an HTTPS check should not be verified.  |
| `ttl` | `string` | optional | Specifies this is a TTL check. Must be a duration string, such as `10s` or `5m`.  |
| `udp` | `string` | optional | Specifies this is a UDP check. Must be an IP/hostname plus port to which UDP datagrams are sent every `interval`.  |

# `service.weights`

Configures the weight of the service in terms of its DNS service (SRV) response.

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `passing` | `integer` | required | Weight for the service when its health checks are passing.  |
| `warning` | `integer` | required | Weight for the service when it has health checks in `warning` status.  |