schema.json

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "$id": "https://hashicorp.com/schemas/consul-ecs",
  "title": "Consul ECS Configuration",
  "description": "These are the top-level fields for the Consul ECS configuration format.",
  "type": "object",
  "properties": {
    "logLevel": {
      "description": "Sets the log level for the `consul-ecs mesh-init` and `consul-ecs health-sync` commands. Defaults to `INFO`.",
      "type": ["string", "null"],
      "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", null]
    },
    "bootstrapDir": {
      "description": "The directory at which to mount the shared volume where Envoy bootstrap configuration is written by `consul-ecs mesh-init`.",
      "type": "string",
      "minLength": 1
    },
    "consulHTTPAddr": {
      "description": "The HTTP(S) URL of the Consul server. Required when `authMethod.enabled` is set",
      "type": ["string", "null"]
    },
    "consulCACertFile": {
      "description": "The file path of the Consul server CA certificate.",
      "type": ["string", "null"]
    },
    "consulLogin": {
      "description": "Configuration for logging into the AWS IAM auth method.",
      "type": ["object", "null"],
      "properties": {
        "enabled": {
          "description": "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`.",
          "type": ["boolean", "null"]
        },
        "method": {
          "description": "The name of Consul auth method used in the login request. Defaults to `iam-ecs-service-token`.",
          "type": ["string", "null"]
        },
        "includeEntity": {
          "description": "Enables IAM role details to be available to the login decision, such as the IAM role path and role tags. Defaults to `true`. This should only be set if the Consul AWS IAM auth method is configured with `EnableIAMEntityDetails=true`.",
          "type": ["boolean", "null"]
        },
        "meta": {
          "description": "Optional key-value pairs to be passed as metadata in the auth method login request. The keys `consul.hashicorp.com/task-id` and `consul.hashicorp.com/cluster` are always included as metadata.",
          "type": ["object", "null"],
          "patternProperties": {
            ".*": {
              "type": "string"
            }
          }
        },
        "region": {
          "description": "Optional region used for AWS API calls. This should match the region of the URL in the `stsEndpoint` field, if set. If not set, the region will be discovered from the task metadata.",
          "type": ["string", "null"]
        },
        "stsEndpoint": {
          "description": "Optional URL used for signing `sts:GetCallerIdentity` requests. This can be used to send requests to a private endpoint or through a network proxy. By default, this is unset. This must match the `STSEndpoint` setting of the AWS IAM auth method on the Consul servers.",
          "type": ["string", "null"]
        },
        "serverIdHeaderValue": {
          "description": "Optional value to include in the `X-Consul-IAM-ServerID` header in the login request. This can be used to protect against certain types of replay attacks. This must match the `ServerIDHeaderValue` field of the AWS IAM auth method on the Consul servers.",
          "type": ["string", "null"]
        }
      },
      "additionalProperties": false
    },
    "healthSyncContainers": {
      "description": "The names of containers that will have health check status synced from ECS into Consul. Cannot be specified with `service.checks`.",
      "type": ["array", "null"],
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "service": {
      "description": "Configuration for Consul service registration.",
      "type": "object",
      "properties": {
        "name": {
          "description": "The name the service will be registered as in Consul. Defaults to the Task family name if empty or null.",
          "type": ["string", "null"],
          "pattern": "(^$)|(^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$)"
        },
        "tags": {
          "description": "List of string values that can be used to add service-level labels.",
          "type": ["array", "null"],
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "port": {
          "description": "Port the application listens on, if any.",
          "type": "integer"
        },
        "enableTagOverride": {
          "description": "Determines if the anti-entropy feature for the service is enabled",
          "type": ["boolean", "null"]
        },
        "meta": {
          "description": "Key-value pairs of metadata to include for the Consul service.",
          "type": ["object", "null"],
          "patternProperties": {
            ".*": {
              "type": "string"
            }
          }
        },
        "weights": {
          "description": "Configures the weight of the service in terms of its DNS service (SRV) response.",
          "type": ["object", "null"],
          "properties": {
            "passing": {
              "description": "Weight for the service when its health checks are passing.",
              "type": "integer"
            },
            "warning": {
              "description": "Weight for the service when it has health checks in `warning` status.",
              "type": "integer"
            }
          },
          "required": ["passing", "warning"],
          "additionalProperties": false
        },
        "checks": {
          "description": "The list of Consul checks for the service. Cannot be specified with `healthSyncContainers`.",
          "type": ["array", "null"],
          "items": {
            "description": "Defines the Consul checks for the service. Each `check` object may contain the following fields.",
            "type": "object",
            "properties": {
              "checkId": {
                "description": "The unique ID for this check on the node. Defaults to the check `name`.",
                "type": ["string", "null"]
              },
              "name": {
                "description": "The name of the check.",
                "type": "string"
              },
              "args": {
                "description": "Command arguments to run to update the status of the check.",
                "type": ["array", "null"],
                "items": {
                  "type": "string"
                }
              },
              "interval": {
                "description": "Specifies the frequency at which to run this check. Required for HTTP, TCP, and UDP checks.",
                "type": ["string", "null"]
              },
              "timeout": {
                "description": "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`.",
                "type": ["string", "null"]
              },
              "ttl": {
                "description": "Specifies this is a TTL check. Must be a duration string, such as `10s` or `5m`.",
                "type": ["string", "null"]
              },
              "http": {
                "description": "Specifies this is an HTTP check. Must be a URL against which request is performed every `interval`.",
                "type": ["string", "null"]
              },
              "header": {
                "description": "Specifies a set of headers that should be set for HTTP checks. Each header can have multiple values.",
                "type": ["object", "null"],
                "patternProperties": {
                  ".*": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "method": {
                "description": "Specifies the HTTP method to be used for an HTTP check. When no value is specified, `GET` is used.",
                "type": ["string", "null"]
              },
              "body": {
                "description": "Specifies a body that should be sent with `HTTP` checks.",
                "type": ["string", "null"]
              },
              "tcp": {
                "description": "Specifies this is a TCP check. Must be an IP/hostname plus port to which a TCP connection is made every `interval`.",
                "type": ["string", "null"]
              },
              "udp": {
                "description": "Specifies this is a UDP check. Must be an IP/hostname plus port to which UDP datagrams are sent every `interval`.",
                "type": ["string", "null"]
              },
              "status": {
                "description": "Specifies the initial status the health check.",
                "type": ["string", "null"],
                "enum": ["passing", "warning", "critical", "maintenance", null]
              },
              "notes": {
                "description": "Specifies arbitrary information for humans. This is not used by Consul internally.",
                "type": ["string", "null"]
              },
              "tlsServerName": {
                "description": "Specifies an optional string used to set the SNI host when connecting via TLS.",
                "type": ["string", "null"]
              },
              "tlsSkipVerify": {
                "description": "Specifies if the certificate for an HTTPS check should not be verified.",
                "type": ["boolean", "null"]
              },
              "grpc": {
                "description": "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`.",
                "type": ["string", "null"]
              },
              "grpcUseTls": {
                "description": "Specifies whether to use TLS for this gRPC health check.",
                "type": ["boolean", "null"]
              },
              "h2ping": {
                "description": "Specifies this is an h2ping check. Must be an address, which will be pinged every `interval`.",
                "type": ["string", "null"]
              },
              "h2pingUseTls": {
                "description": "Specifies whether TLS is used for an h2ping check.",
                "type": ["boolean", "null"]
              },
              "aliasNode": {
                "description": "Specifies the ID of the node for an alias check.",
                "type": ["string", "null"]
              },
              "aliasService": {
                "description": "Specifies the ID of a service for an alias check.",
                "type": ["string", "null"]
              },
              "successBeforePassing": {
                "description": "Specifies the number of consecutive successful results required before check status transitions to passing.",
                "type": ["integer", "null"]
              },
              "failuresBeforeCritical": {
                "description": "Specifies the number of consecutive unsuccessful results required before check status transitions to critical.",
                "type": ["integer", "null"]
              }
            },
            "additionalProperties": false
          }
        },
        "namespace": {
          "description": "The Consul namespace where the service will be registered [Consul Enterprise].",
          "type": ["string", "null"]
        },
        "partition": {
          "description": "The Consul admin partition where the service will be registered [Consul Enterprise].",
          "type": ["string", "null"]
        }
      },
      "required": ["port"],
      "additionalProperties": true
    },
    "proxy": {
      "description": "Configuration for the sidecar proxy registration with Consul.",
      "type": ["object", "null"],
      "properties": {
        "config": {
          "description": "Object value that specifies an opaque JSON configuration. The JSON is stored and returned along with the service instance when called from the API.",
          "type": ["object", "null"]
        },
        "publicListenerPort": {
          "description": "The public listener port for Envoy used for service-to-service communication. Defaults to 20000.",
          "type": ["integer", "null"]
        },
        "upstreams": {
          "description": "The list of the upstream services that the proxy should create listeners for.",
          "type": ["array", "null"],
          "items": {
            "description": "The list of the upstream services that the proxy should create listeners for. Each `upstream` object may contain the following fields.",
            "type": "object",
            "properties": {
              "destinationType": {
                "description": "Specifies the type of discovery query the proxy should use for finding service mesh instances.",
                "type": ["string", "null"],
                "enum": ["service", "prepared_query", null]
              },
              "destinationNamespace": {
                "description": "Specifies the namespace containing the upstream service [Consul Enterprise].",
                "type": ["string", "null"]
              },
              "destinationPartition": {
                "description": "Specifies the name of the admin partition containing the upstream service [Consul Enterprise].",
                "type": ["string", "null"]
              },
              "destinationName": {
                "description": "Specifies the name of the upstream service or prepared query to route the service mesh to.",
                "type": "string"
              },
              "datacenter": {
                "description": "Specifies the datacenter to issue the discovery query to.",
                "type": ["string", "null"]
              },
              "localBindAddress": {
                "description": "Specifies the address to bind a local listener to.",
                "type": ["string", "null"]
              },
              "localBindPort": {
                "description": "Specifies the port to bind a local listener to. The application will make outbound connections to the upstream from the local port.",
                "type": "integer"
              },
              "config": {
                "description": "Specifies opaque configuration options that will be provided to the proxy instance for the upstream.",
                "type": ["object", "null"]
              },
              "meshGateway": {
                "description": "Specifies the mesh gateway configuration for the proxy for this upstream.",
                "type": ["object", "null"],
                "properties": {
                  "mode": {
                    "description": "Specifies how the upstream with a remote destination datacenter gets resolved.",
                    "type": "string",
                    "enum": ["none", "local", "remote"]
                  }
                },
                "required": ["mode"]
              }
            },
            "required": ["destinationName", "localBindPort"],
            "additionalProperties": false
          }
        },
        "meshGateway": {
          "description": "Specifies the mesh gateway configuration for the proxy.",
          "type": ["object", "null"],
          "properties": {
            "mode": {
              "description": "Specifies how upstreams with a remote destination datacenter are resolved.",
              "type": "string",
              "enum": ["none", "local", "remote"]
            }
          },
          "required": ["mode"]
        }
      },
      "expose": {
        "description": "Specifies a configuration for exposing HTTP paths through the proxy.",
        "type": ["object", "null"],
        "properties": {
          "checks": {
            "description": "If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.",
            "type": "boolean"
          },
          "paths": {
            "description": "A list of paths to expose through Envoy.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "listenerPort": {
                  "description": "The port where the proxy will listen for connections.",
                  "type": "integer"
                },
                "path": {
                  "description": "The HTTP path to expose. The path must be prefixed by a slash.",
                  "type": "string"
                },
                "localPathPort": {
                  "description": "The port where the local service is listening for connections to the path.",
                  "type": "integer"
                },
                "protocol": {
                  "description": "Sets the protocol of the listener.",
                  "enum": ["http", "http2"]
                }
              }
            }
          }
        }
      }
    },
    "gateway": {
      "description": "Configuration for the gateway proxy registration.",
      "type": "object",
      "properties": {
        "kind": {
          "description": "Specifies the type of gateway to register.",
          "type": "string",
          "enum": ["mesh-gateway"]
        },
        "lanAddress": {
          "description": "LAN address and port for the gateway. If not specified, defaults to the task/node address.",
          "type": ["object", "null"],
          "properties": {
            "address": {
              "type": ["string", "null"]
            },
            "port": {
              "type": ["integer", "null"]
            }
          },
          "additionalProperties": false
        },
        "wanAddress": {
          "description": "WAN address and port for the gateway. If not specified, defaults to the task/node address.",
          "type": ["object", "null"],
          "properties": {
            "address": {
              "type": ["string", "null"]
            },
            "port": {
              "type": ["integer", "null"]
            }
          },
          "additionalProperties": false
        },
        "name": {
          "description": "The name the gateway will be registered as in Consul. Defaults to the Task family name.",
          "type": ["string", "null"],
          "pattern": "(^$)|(^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$)"
        },
        "tags": {
          "description": "List of string values that can be used to add labels to the gateway.",
          "type": ["array", "null"],
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "meta": {
          "description": "Key-value pairs of metadata to include for the gateway.",
          "type": ["object", "null"],
          "patternProperties": {
            ".*": {
              "type": "string"
            }
          }
        },
        "namespace": {
          "description": "Consul namespace in which the gateway will be registered [Consul Enterprise].",
          "type": ["string", "null"]
        },
        "partition": {
          "description": "Consul admin partition in which the gateway will be registered [Consul Enterprise].",
          "type": ["string", "null"]
        },
        "proxy": {
          "description": "Object that contains the proxy parameters.",
          "type": ["object", "null"],
          "properties": {
            "config": {
              "type": ["object", "null"]
            }
          }
        }
      },
      "required": ["kind"],
      "additionalProperties": false
    }
  },
  "required": ["bootstrapDir"],
  "additionalProperties": false
}