130 lines
6.7 KiB
Plaintext
130 lines
6.7 KiB
Plaintext
---
|
|
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 `<key>=<value>`. This flag may be passed multiple times.
|
|
- `-login-namespace` <EnterpriseAlert inline /> - The Consul Enterprise namespace containing the auth method.
|
|
- `-login-partition` <EnterpriseAlert inline /> - 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` <EnterpriseAlert inline /> - 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` <EnterpriseAlert inline /> - 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 <method> \
|
|
-login-bearer-token <token> \ ## Or -login-bearer-token-path
|
|
-login-datacenter <datacenter> \
|
|
-login-meta key1=val1 -login-meta key2=val2 \
|
|
-login-namespace <namespace> \
|
|
-login-partition <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. |