Consul on AWS Elastic Container Service (ECS) Configuration Reference

This topic describes configuration options for the JSON configuration 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 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 for a complete reference of supported input variables for the mesh-task module.

Terraform Input Variable	Consul ECS Config Field
`upstreams`	`proxy.upstreams`
`checks`	`service.checks`
`consul_service_name`	`service.name`
`consul_service_tags`	`service.tags`
`consul_service_meta`	`service.meta`
`consul_namespace`	`service.namespace`
`consul_partition`	`service.partition`

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`	`object`	optional	Configuration for logging into the AWS IAM auth method.
`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`	`object`	optional	Configuration for the sidecar proxy registration with Consul.
`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`	`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	Enterprise Consul namespace in which the gateway will be registered.
`partition`	`string`	optional	Enterprise Consul admin partition in which the gateway will be registered.
`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`	`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`	`object`	optional	Specifies the mesh gateway configuration for the 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	Enterprise Specifies the namespace containing the upstream service.
`destinationPartition`	`string`	optional	Enterprise 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`	`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`	`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	Enterprise The Consul namespace where the service will be registered.
`partition`	`string`	optional	Enterprise 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`	`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. 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.
`os_service`	`string`	optional	Specifies the name of a service on which to perform an OS service check. The check runs according the frequency specified in the `interval` parameter.
`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`.
`tcpUseTls`	`boolean`	optional	Specifies whether to use TLS for this `TCP` health check. If TLS is enabled, then by default, a valid TLS certificate is expected. Certificate verification can be disabled by setting `TLSSkipVerify` to `true`.
`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 check should verify the chain and hostname of the certificate presented by the server being checked. Set to `true` to disable verification. We recommend setting to `false` for production use. Default is `false`. Supported check types: `HTTP`, `H2Ping`, `gRPC`, and `TCP`
`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.