HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul
Consul Home

You are viewing documentation for version v1.20.x. View latest version.

Consul Dataplane CLI Reference

The consul-dataplane command interacts with the binary for simplified service mesh with Consul Dataplane. Use this command to install Consul Dataplane, configure its Envoy proxies, and secure Dataplane deployments.

Usage

Usage: consul-dataplane [options]

Requirements

Consul Dataplane requires servers running Consul version v1.14+. To find a specific version of Consul, refer to HashiCorp's Official Release Channels.

Startup

The following options are required when starting consul-dataplane with the CLI:

Command Options

  • -addresses - Consul server gRPC addresses. Can be a DNS name or an executable command. Accepted environment variable is DP_CONSUL_ADDRESSES. Refer to go-netaddrs for details and examples.
  • -ca-certs - The path to a file or directory containing CA certificates used to verify the server's certificate. Accepted environment variable is DP_CA_CERTS.
  • -consul-dns-bind-addr - The address bound to the Consul DNS proxy. Default is "127.0.0.1". Accepted environment variable is DP_CONSUL_DNS_BIND_ADDR.
  • -consul-dns-bind-port - The port that the Consul DNS proxy listens on. Default is -1, which disables the DNS proxy. Accepted environment variable is DP_CONSUL_DNS_BIND_PORT.
  • -credential-type - The type of credentials used to authenticate with Consul servers, either "static" or "login". Accepted environment variable is DP_CREDENTIAL_TYPE.
  • -envoy-admin-bind-address - The address the Envoy admin server is available on. Default is "127.0.0.1". Accepted environment variable is DP_ENVOY_ADMIN_BIND_ADDRESS.
  • -envoy-admin-bind-port - The port the Envoy admin server is available on. Default is 19000. Accepted environment variable is DP_ENVOY_ADMIN_BIND_PORT.
  • -envoy-concurrency - The number of worker threads that Envoy uses. Default is 2. Accepted environment variable is DP_ENVOY_CONCURRENCY.
  • -envoy-ready-bind-address - The address Envoy's readiness probe is available on. Accepted environment variable is DP_ENVOY_READY_BIND_ADDRESS.
  • -envoy-ready-bind-port - The port Envoy's readiness probe is available on. Accepted environment variable is DP_ENVOY_READY_BIND_PORT.
  • -graceful-port - The port to serve HTTP endpoints for graceful operations. Accepted environment variable is DP_GRACEFUL_PORT.
  • -graceful-shutdown-path - The HTTP path to serve the graceful shutdown endpoint. Accepted environment variable is DP_GRACEFUL_SHUTDOWN_PATH.
  • -grpc-port - The Consul server gRPC port to which consul-dataplane connects. Default is 8502. Accepted environment variable is DP_CONSUL_GRPC_PORT.
  • -log-json - Enables log messages in JSON format. Default is false. Accepted environment variable is DP_LOG_JSON.
  • -log-level - Log level of the messages to print. Available log levels are "trace", "debug", "info", "warn", and "error". Default is "info". Accepted environment variable is DP_LOG_LEVEL.
  • -login-auth-method - The auth method used to log in. Accepted environment variable is DP_CREDENTIAL_LOGIN_AUTH_METHOD.
  • -login-bearer-token - The bearer token presented to the auth method. Accepted environment variable is DP_CREDENTIAL_LOGIN_BEARER_TOKEN.
  • -login-bearer-token-path - The path to a file containing the bearer token presented to the auth method. Accepted environment variable is DP_CREDENTIAL_LOGIN_BEARER_TOKEN_PATH.
  • -login-datacenter - The datacenter containing the auth method. Accepted environment variable is DP_CREDENTIAL_LOGIN_DATACENTER.
  • -login-meta - A set of key/value pairs to attach to the ACL token. Each pair is formatted as <key>=<value>. This flag may be passed multiple times. Accepted environment variables are DP_CREDENTIAL_LOGIN_META{1..9}.
  • -login-namespace Enterprise - The Consul Enterprise namespace containing the auth method. Accepted environment variable is DP_CREDENTIAL_LOGIN_NAMESPACE.
  • -login-partition Enterprise - The Consul Enterprise partition containing the auth method. Accepted environment variable is DP_CREDENTIAL_LOGIN_PARTITION.
  • -proxy-service-id - The proxy service instance's ID. Accepted environment variable is DP_PROXY_SERVICE_ID.
  • -proxy-service-id-path - The path to a file containing the proxy service instance's ID. Accepted environment variable is DP_PROXY_SERVICE_ID_PATH.
  • -server-watch-disabled - Prevent consul-dataplane from consuming the server update stream. Use this flag when Consul servers are behind a load balancer. Default is false. Accepted environment variable is DP_SERVER_WATCH_DISABLED.
  • -service-namespace Enterprise - The Consul Enterprise namespace in which the proxy service instance is registered. Accepted environment variable is DP_SERVICE_NAMESPACE.
  • -service-node-id - The ID of the Consul node to which the proxy service instance is registered. Accepted environment variable is DP_SERVICE_NODE_ID.
  • -service-node-name - The name of the Consul node to which the proxy service instance is registered. Accepted environment variable is DP_SERVICE_NODE_NAME.
  • -service-partition Enterprise - The Consul Enterprise partition in which the proxy service instance is registered. Accepted environment variable is DP_SERVICE_PARTITION.
  • -shutdown-drain-listeners - Wait for proxy listeners to drain before terminating the proxy container. Accepted environment variable is DP_SHUTDOWN_DRAIN_LISTENERS.
  • -shutdown-grace-period-seconds - Amount of time to wait after receiving a SIGTERM signal before terminating the proxy. Accepted environment variable is DP_SHUTDOWN_GRACE_PERIOD_SECONDS.
  • -static-token - The ACL token used to authenticate requests to Consul servers when -credential-type is set to "static". Accepted environment variable is DP_CREDENTIAL_STATIC_TOKEN.
  • -telemetry-prom-ca-certs-path - The path to a file or directory containing CA certificates used to verify the Prometheus server's certificate. Accepted environment variable is DP_TELEMETRY_PROM_CA_CERTS_PATH.
  • -telemetry-prom-cert-file - The path to the client certificate used to serve Prometheus metrics. Accepted environment variable is DP_TELEMETRY_PROM_CERT_FILE.
  • -telemetry-prom-key-file - The path to the client private key used to serve Prometheus metrics. Accepted environment variable is DP_TELEMETRY_PROM_KEY_FILE.
  • -telemetry-prom-merge-port - The local port used to serve merged Prometheus metrics. Default is 20100. If your service instance uses the same default port, this flag must be set to a different port in order to avoid a port conflict. Accepted environment variable is DP_TELEMETRY_PROM_MERGE_PORT.
  • -telemetry-prom-retention-time - The duration for Prometheus metrics aggregation. Default is 1m0s. Accepted environment variable is DP_TELEMETRY_PROM_RETENTION_TIME. Refer to prometheus_retention_time for details on setting this value.
  • -telemetry-prom-scrape-path - The URL path where Envoy serves Prometheus metrics. Default is "/metrics". Accepted environment variable is DP_TELEMETRY_PROM_SCRAPE_PATH.
  • -telemetry-prom-service-metrics-url - The URL where your service instance serves Prometheus metrics. If this is set, the metrics at this URL are included in Consul Dataplane's merged Prometheus metrics. Accepted environment variable is DP_TELEMETRY_PROM_SERVICE_METRICS_URL.
  • -telemetry-use-central-config - Controls whether the proxy applies the central telemetry configuration. Default is true. Accepted environment variable is DP_TELEMETRY_USE_CENTRAL_CONFIG.
  • -tls-cert - The path to a client certificate file. This flag is required if tls.grpc.verify_incoming is enabled on the server. Accepted environment variable is DP_TLS_CERT.
  • -tls-disabled - Communicate with Consul servers over a plaintext connection. Useful for testing, but not recommended for production. Default is false. Accepted environment variable is DP_TLS_DISABLED.
  • -tls-insecure-skip-verify - Do not verify the server's certificate. Useful for testing, but not recommended for production. Default is false. DP_TLS_INSECURE_SKIP_VERIFY.
  • -tls-key - The path to a client private key file. This flag is required if tls.grpc.verify_incoming is enabled on the server. Accepted environment variable is DP_TLS_KEY.
  • -tls-server-name - The hostname to expect in the server certificate's subject. This flag is required if -addresses is not a DNS name. Accepted environment variable is DP_TLS_SERVER_NAME.
  • -version - Print the current version of consul-dataplane.
  • -xds-bind-addr - The address the Envoy xDS server is available on. Default is "127.0.0.1". Accepted environment variable is DP_XDS_BIND_ADDR.
  • -xds-bind-port - The port on which the Envoy xDS server is available. Default is 0. When set to 0, an available port is selected at random. Accepted environment variable is DP_XDS_BIND_PORT.

Examples

DNS

Consul Dataplane resolves a domain name to discover Consul server IP addresses.

$ consul-dataplane -addresses my.consul.example.com

Executable Command

Consul Dataplane runs a script that, on success, returns one or more IP addresses separated by whitespace.

$ ./my-script.sh
172.20.0.1
172.20.0.2
172.20.0.3

$ consul-dataplane -addresses "exec=./my-script.sh"

Go Discover Nodes for Cloud Providers

The go-discover binary is included in the hashicorp/consul-dataplane image for use with this mode of server discovery, which functions in a way similar to Cloud Auto-join. The following example demonstrates how to use the go-discover binary with Consul Dataplane.

$ consul-dataplane -addresses "exec=discover -q addrs provider=aws region=us-west-2 tag_key=consul-server tag_value=true"

Static token

A static ACL token is passed to Consul Dataplane.

$ consul-dataplane -credential-type "static"` -static-token "12345678-90ab-cdef-0000-12345678abcd"

Auth method login

Consul Dataplane logs in to one of Consul's supported auth methods.

$ consul-dataplane -credential-type "login"
  -login-auth-method <method> \
  -login-bearer-token <token> \  ## Or -login-bearer-token-path
  -login-datacenter <datacenter> \
  -login-meta key1=val1 -login-meta key2=val2 \

Consul Servers Behind a Load Balancer

When Consul servers are behind a load balancer, you must pass -server-watch-disabled to Consul Dataplane.

$ consul-dataplane -server-watch-disabled

By default, Consul Dataplane opens a server watch stream to a Consul server, which enables the server to inform Consul Dataplane of new or different Consul server addresses. However, if Consul Dataplane is connecting through a load balancer, then it must ignore the Consul server addresses that are returned from the server watch stream.