June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • Overview
      • Overview
      • What is a Service Mesh?
      • Overview
      • Chef, Puppet, etc.
      • Nagios
      • SkyDNS
      • SmartStack
      • Serf
      • Eureka
      • Istio
      • Envoy and Other Proxies
      • Custom Solutions
    • Overview
    • Manual Bootstrap
    • Consul Agent
    • Glossary
    • Required Ports
    • Bootstrapping a Datacenter
    • Cloud Auto-join
    • Server Performance
    • Kubernetes
  • API
  • Commands (CLI)
    • Register Services - Service Definitions
    • Find Services - DNS Interface
    • Monitor Services - Check Definitions
    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
      • Overview
      • Envoy
      • Built-in Proxy
      • Proxy Integration
      • Managed (Deprecated)
      • Overview
      • Proxy Service Registration
      • Sidecar Service Registration
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
      • Overview
      • UI Visualization
      • Overview
      • Discovery Chain
    • Connectivity Tasks
    • Distributed Tracing
      • Overview
        • WAN Federation
        • Enabling Service-to-service Traffic Across Datacenters
        • Enabling Service-to-service Traffic Across Admin Partitions
      • Ingress Gateways
      • Terminating Gateways
    • Nomad
    • Kubernetes
      • Overview
      • Go Integration
      • Overview
      • Built-In CA
      • Vault
      • ACM Private CA
    • Develop and Debug
    • Security
    • Overview
    • Installation
    • Technical Specifications
    • Common Errors
    • Upgrades
    • Overview
    • Architecture
      • Installing Consul on Kubernetes
      • Installing Consul K8s CLI
        • Minikube
        • Kind
        • AKS (Azure)
        • EKS (AWS)
        • GKE (Google Cloud)
        • Red Hat OpenShift
        • Self Hosted Kubernetes
        • Consul Clients Outside Kubernetes
        • Consul Servers Outside Kubernetes
        • Single Consul Datacenter in Multiple Kubernetes Clusters
        • Consul Enterprise
        • Overview
        • Federation Between Kubernetes Clusters
        • Federation Between VMs and Kubernetes
        • Overview
        • Systems Integration
          • Overview
          • Bootstrap Token
          • Enterprise License
          • Gossip Encryption Key
          • Partition Token
          • Replication Token
          • Server TLS
          • Service Mesh Certificates
          • Snapshot Agent Config
        • WAN Federation
      • Compatibility Matrix
      • Overview
      • Transparent Proxy
      • Ingress Gateways
      • Terminating Gateways
      • Ingress Controllers
      • Configuring a Connect CA Provider
      • Health Checks
        • Metrics
    • Service Sync
      • Overview
      • Upgrade An Existing Cluster to CRDs
    • Annotations and Labels
    • Consul DNS
      • Upgrading Consul on Kubernetes
      • Upgrading Consul K8s CLI
      • Uninstall
      • Certificate Rotation
      • Gossip Encryption Key Rotation
      • Configure TLS on an Existing Cluster
      • Common Error Messages
      • FAQ
    • Helm Chart Configuration
    • Consul K8s CLI Reference
    • Overview
    • Requirements
    • Task Resource Usage
      • Installation
      • Secure Configuration
      • Migrate Existing Tasks
      • Installation
      • Secure Configuration
      • ACL Controller
    • Architecture
    • Consul Enterprise
    • Configuration Reference
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Overview
      • task
    • Configuration
    • Tasks
    • Terraform Modules
      • Overview
      • License
      • Terraform Cloud Driver
      • Overview
      • Terraform
      • Terraform Cloud
    • Compatibility
    • Consul KV
    • Sessions
    • Watches
    • Overview
      • General
      • CLI Reference
      • Configuration Reference
    • Configuration Entries
    • Telemetry
    • Sentinel
    • RPC
    • Overview
      • ACL System Overview
      • Tokens
      • Policies
      • Roles
      • Rules Reference
      • Legacy Mode
      • Token Migration
      • ACLs in Federated Datacenters
        • Overview
        • Kubernetes
        • JWT
        • OIDC
        • AWS IAM
    • Encryption
      • Overview
      • Core
      • Network Infrastructure Automation
    • Overview
    • Admin Partitions
    • Audit Logging
    • Automated Backups
    • Automated Upgrades
    • Enhanced Read Scalability
    • Single sign-on - OIDC
    • Redundancy Zones
    • Advanced Federation
    • Network Segments
    • Namespaces
    • NIA with TFE
    • Sentinel
      • Overview
      • FAQ
    • Overview
    • Improving Consul Resilience
    • Anti-Entropy
    • Consensus Protocol
    • Gossip Protocol
    • Jepsen Testing
    • Network Coordinates
    • Consul Integration Program
    • NIA Integration Program
    • Vault Integration
    • Proxy Integration
  • Consul Tools
    • Overview
    • Compatibility Promise
    • Specific Version Details
      • Overview
      • General Process
      • Upgrading to 1.2.4
      • Upgrading to 1.6.9
      • Upgrading to 1.8.13
      • Upgrading to 1.10.0
    • Common Error Messages
    • FAQ
    • Overview
      • v1.11.x
      • v1.10.x
      • v1.9.x
      • v0.1.x
      • v0.2.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.5.x
      • v0.6.0-beta
    • Overview
    • ACL
  • Guides
Type '/' to Search

»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 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 VariableConsul ECS Config Field
upstreamsproxy.upstreams
checksservice.checks
consul_service_nameservice.name
consul_service_tagsservice.tags
consul_service_metaservice.meta
consul_namespaceservice.namespace
consul_partitionservice.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.

FieldTypeRequiredDescription
bootstrapDirstringrequiredThe directory at which to mount the shared volume where Envoy bootstrap configuration is written by consul-ecs mesh-init.
healthSyncContainersarrayoptionalThe names of containers that will have health check status synced from ECS into Consul. Cannot be specified with service.checks.
proxyobjectoptionalConfiguration for the sidecar proxy registration with Consul.
serviceobjectrequiredConfiguration for Consul service registration.

»service

Configuration for Consul service registration.

FieldTypeRequiredDescription
checksarrayoptionalThe list of Consul checks for the service. Cannot be specified with healthSyncContainers.
enableTagOverridebooleanoptionalDetermines if the anti-entropy feature for the service is enabled
metaobjectoptionalKey-value pairs of metadata to include for the Consul service.
namestringoptionalThe name the service will be registered as in Consul. Defaults to the Task family name if empty or null.
namespacestringoptionalThe Consul namespace where the service will be registered [Consul Enterprise].
partitionstringoptionalThe Consul admin partition where the service will be registered [Consul Enterprise].
portintegerrequiredPort the application listens on, if any.
tagsarrayoptionalList of string values that can be used to add service-level labels.
weightsobjectoptionalConfigures 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.

FieldTypeRequiredDescription
aliasNodestringoptionalSpecifies the ID of the node for an alias check.
aliasServicestringoptionalSpecifies the ID of a service for an alias check.
argsarrayoptionalCommand arguments to run to update the status of the check.
bodystringoptionalSpecifies a body that should be sent with HTTP checks.
checkIdstringoptionalThe unique ID for this check on the node. Defaults to the check name.
failuresBeforeCriticalintegeroptionalSpecifies the number of consecutive unsuccessful results required before check status transitions to critical.
grpcstringoptionalSpecifies a gRPC check. Must be an endpoint that supports the standard gRPC health checking protocol. The endpoint will be probed every interval.
grpcUseTlsbooleanoptionalSpecifies whether to use TLS for this gRPC health check.
h2pingstringoptionalSpecifies this is an h2ping check. Must be an address, which will be pinged every interval.
h2pingUseTlsbooleanoptionalSpecifies whether TLS is used for an h2ping check.
headerobjectoptionalSpecifies a set of headers that should be set for HTTP checks. Each header can have multiple values.
httpstringoptionalSpecifies this is an HTTP check. Must be a URL against which request is performed every interval.
intervalstringoptionalSpecifies the frequency at which to run this check. Required for HTTP and TCP checks.
methodstringoptionalSpecifies the HTTP method to be used for an HTTP check. When no value is specified, GET is used.
namestringoptionalThe name of the check.
notesstringoptionalSpecifies arbitrary information for humans. This is not used by Consul internally.
statusstringoptionalSpecifies the initial status the health check. Must be one of passing, warning, critical, maintenance, ornull.
successBeforePassingintegeroptionalSpecifies the number of consecutive successful results required before check status transitions to passing.
tcpstringoptionalSpecifies this is a TCP check. Must be an IP/hostname plus port to which a TCP connection is made every interval.
timeoutstringoptionalSpecifies 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.
tlsServerNamestringoptionalSpecifies an optional string used to set the SNI host when connecting via TLS.
tlsSkipVerifybooleanoptionalSpecifies if the certificate for an HTTPS check should not be verified.
ttlstringoptionalSpecifies 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.

FieldTypeRequiredDescription
passingintegerrequiredWeight for the service when its health checks are passing.
warningintegerrequiredWeight for the service when it has health checks in warning status.

»proxy

Configuration for the sidecar proxy registration with Consul.

FieldTypeRequiredDescription
configobjectoptionalObject value that specifies an opaque JSON configuration. The JSON is stored and returned along with the service instance when called from the API.
meshGatewayobjectoptionalSpecifies the mesh gateway configuration for the proxy.
upstreamsarrayoptionalThe 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.

FieldTypeRequiredDescription
configobjectoptionalSpecifies opaque configuration options that will be provided to the proxy instance for the upstream.
datacenterstringoptionalSpecifies the datacenter to issue the discovery query to.
destinationNamestringrequiredSpecifies the name of the upstream service or prepared query to route the service mesh to.
destinationNamespacestringoptionalSpecifies the namespace containing the upstream service [Consul Enterprise].
destinationPartitionstringoptionalSpecifies the name of the admin partition containing the upstream service [Consul Enterprise].
destinationTypestringoptionalSpecifies the type of discovery query the proxy should use for finding service mesh instances. Must be one of service, prepared_query, ornull.
localBindAddressstringoptionalSpecifies the address to bind a local listener to.
localBindPortintegerrequiredSpecifies the port to bind a local listener to. The application will make outbound connections to the upstream from the local port.
meshGatewayobjectoptionalSpecifies the mesh gateway configuration for the proxy for this upstream.

»proxy.upstreams.meshGateway

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

FieldTypeRequiredDescription
modestringrequiredSpecifies how the upstream with a remote destination datacenter gets resolved. Must be one of none, local, orremote.

»proxy.meshGateway

Specifies the mesh gateway configuration for the proxy.

FieldTypeRequiredDescription
modestringrequiredSpecifies how upstreams with a remote destination datacenter get resolved. Must be one of none, local, orremote.
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager