--- layout: docs page_title: Consul Dataplane CLI Reference description: >- Consul Dataplane runs as a separate binary controlled with the `consul-dataplane` CLI command. Learn how to use this command to configure your dataplane on Kubernetes with this reference guide and example code. --- # Consul Dataplane CLI Reference The `consul-dataplane` command interacts with the binary for [simplified service mesh with Consul Dataplane](/consul/docs/k8s/dataplane/index). 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-beta+`. To find a specific version of Consul, refer to [Hashicorp's Official Release Channels](https://www.hashicorp.com/official-release-channels). ### Startup The following options are required when starting `consul-dataplane` with the CLI: - `-addresses` - `-service-node-name` - `-proxy-service-id` ### Command Options - `-addresses` - Consul server gRPC addresses. Can be a DNS name or an executable command. Refer to [go-netaddrs](https://github.com/hashicorp/go-netaddrs#summary) for details and examples. - `-ca-certs` - The path to a file or directory containing CA certificates used to verify the server's certificate. - `-credential-type` - The type of credentials used to authenticate with Consul servers, either `"static"` or `"login"`. - `-envoy-admin-bind-address` - The address the Envoy admin server is available on. Default is `"127.0.0.1"`. - `-envoy-admin-bind-port` - The port the Envoy admin server is available on. Default is `19000`. - `-envoy-concurrency` - The number of worker threads that Envoy uses. Default is `2`. - `-envoy-ready-bind-address` - The address Envoy's readiness probe is available on. - `-grpc-port` - The Consul server gRPC port to which consul-dataplane connects. Default is `8502`. - `-log-json` - Enables log messages in JSON format. Default is `false`. - `-log-level` - Log level of the messages to print. Available log levels are `"trace"`, `"debug"`, `"info"`, `"warn"`, and `"error"`. Default is `"info"`. - `-login-auth-method` - The auth method used to log in. - `-login-bearer-token` - The bearer token presented to the auth method. - `-login-bearer-token-path` - The path to a file containing the bearer token presented to the auth method. - `-login-datacenter` - The datacenter containing the auth method. - `-login-meta` - A set of key/value pairs to attach to the ACL token. Each pair is formatted as `=`. This flag may be passed multiple times. - `-login-namespace` - The Consul Enterprise namespace containing the auth method. - `-login-partition` - The Consul Enterprise partition containing the auth method. - `-proxy-service-id` - The proxy service instance's ID. - `-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`. - `-service-namespace` - The Consul Enterprise namespace in which the proxy service instance is registered. - `-service-node-id` - The ID of the Consul node to which the proxy service instance is registered. - `-service-node-name` - The name of the Consul node to which the proxy service instance is registered. - `-service-partition` - The Consul Enterprise partition in which the proxy service instance is registered. - `-static-token` - The ACL token used to authenticate requests to Consul servers when `-credential-type` is set to `"static"`. - `-telemetry-use-central-config` - Controls whether the proxy applies the central telemetry configuration. Default is `true`. - `-tls-cert` - The path to a client certificate file. This flag is required if `tls.grpc.verify_incoming` is enabled on the server. - `-tls-disabled` - Communicate with Consul servers over a plaintext connection. Useful for testing, but not recommended for production. Default is `false`. - `-tls-insecure-skip-verify` - Do not verify the server's certificate. Useful for testing, but not recommended for production. Default is `false`. - `-tls-key` - The path to a client private key file. This flag is required if `tls.grpc.verify_incoming` is enabled on the server. - `-tls-server-name` - The hostname to expect in the server certificate's subject. This flag is required if `-addresses` is not a DNS 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"`. ## Examples ### DNS Consul Dataplane resolves a domain name to discover Consul server IP addresses. ```shell-session $ 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. ```shell-session $ ./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`](https://github.com/hashicorp/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](/consul/docs/install/cloud-auto-join). The following example demonstrates how to use the `go-discover` binary with Consul Dataplane. ```shell-session $ 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. ```shell-session $ 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/docs/security/acl/auth-methods). ```shell-session $ consul-dataplane -credential-type "login" -login-auth-method \ -login-bearer-token \ ## Or -login-bearer-token-path -login-datacenter \ -login-meta key1=val1 -login-meta key2=val2 \ -login-namespace \ -login-partition ``` ### Consul Servers Behind a Load Balancer When Consul servers are behind a load balancer, you must pass `-server-watch-disabled` to Consul Dataplane. ```shell-session $ 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.