mirror of
https://github.com/status-im/consul.git
synced 2025-02-06 19:04:59 +00:00
eab88bf92a
This commit fixes numerous spelling errors across the site and also removes unnecessary whitespace that was present in the edited files.
182 lines
12 KiB
Plaintext
182 lines
12 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/connect/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](https://www.hashicorp.com/official-release-channels).
|
|
|
|
### Startup
|
|
|
|
The following options are required when starting `consul-dataplane` with the CLI:
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
- `-addresses`
|
|
- `-service-node-name`
|
|
- `-proxy-service-id`
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
- `-addresses`
|
|
- `-service-node-name`
|
|
- `-service-namespace`
|
|
- `-service-partition`
|
|
- `-proxy-service-id`
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
### 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](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. 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` <EnterpriseAlert inline /> - The Consul Enterprise namespace containing the auth method. Accepted environment variable is `DP_CREDENTIAL_LOGIN_NAMESPACE`.
|
|
- `-login-partition` <EnterpriseAlert inline /> - 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` <EnterpriseAlert inline /> - 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` <EnterpriseAlert inline /> - 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`](/consul/docs/agent/config/config-files#telemetry-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.
|
|
|
|
```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).
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
```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 \
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
```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>
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### 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.
|