luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/docs/ecs/configuration-reference.mdx

148 lines
10 KiB
Plaintext
Raw Normal View History

docs: Add configuration reference for ECS
2022-01-25 20:30:27 +00:00
---
layout: docs
page_title: AWS ECS
description: >-
Configuration Reference for Consul on AWS ECS (Elastic Container Service).
Do not modify by hand! This is automatically generated documentation.
---
# 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`. |
| `healthSyncContainers` | `array` | optional | The names of containers that will have health check status synced from ECS into Consul. Cannot be specified with `service.checks`. |
| [`proxy`](#proxy) | `object` | optional | Configuration for the sidecar proxy registration with Consul. |
| [`service`](#service) | `object` | required | Configuration for Consul service registration. |
# `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 | The Consul namespace where the service will be registered [Consul Enterprise]. |
| `partition` | `string` | optional | The Consul admin partition where the service will be registered [Consul Enterprise]. |
| `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 may contain these 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 and TCP 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 in the case of a Script, HTTP, TCP, or gRPC check. 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`. |
# `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. |
# `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.upstreams`
The list of the upstream services that the proxy should create listeners for. Each upstream may contain these 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 | Specifies the namespace containing the upstream service [Consul Enterprise]. |
| `destinationPartition` | `string` | optional | Specifies the name of the admin partition containing the upstream service [Consul Enterprise]. |
| `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`. |
# `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 get resolved. Must be one of `none`, `local`, or`remote`. |