docs: Update consul-dataplane docs for post-beta (#15177)
* Update Consul Dataplane CLI reference * Add new page for Consul Dataplane telemetry * Add `server_type` label to agent grpc metrics * Callout Consul Dataplane in Envoy bootstrap configuration section * Update consul-dataplane unsupported features Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Riddhi Shah <riddhi@hashicorp.com>
This commit is contained in:
Paul Glass
GitHub
parent
befefe42ee
commit
8cac6c36fe
|
|
@ -531,14 +531,14 @@ These metrics are used to monitor the health of the Consul servers.
|
|||
| `consul.session_ttl.invalidate` | Measures the time spent invalidating an expired session. | ms | timer |
|
||||
| `consul.txn.apply` | Measures the time spent applying a transaction operation. | ms | timer |
|
||||
| `consul.txn.read` | Measures the time spent returning a read transaction. | ms | timer |
|
||||
| `consul.grpc.client.request.count` | Counts the number of gRPC requests made by the client agent to a Consul server. | requests | counter |
|
||||
| `consul.grpc.client.connection.count` | Counts the number of new gRPC connections opened by the client agent to a Consul server. | connections | counter |
|
||||
| `consul.grpc.client.connections` | Measures the number of active gRPC connections open from the client agent to any Consul servers. | connections | gauge |
|
||||
| `consul.grpc.server.request.count` | Counts the number of gRPC requests received by the server. | requests | counter |
|
||||
| `consul.grpc.server.connection.count` | Counts the number of new gRPC connections received by the server. | connections | counter |
|
||||
| `consul.grpc.server.connections` | Measures the number of active gRPC connections open on the server. | connections | gauge |
|
||||
| `consul.grpc.server.stream.count` | Counts the number of new gRPC streams received by the server. | streams | counter |
|
||||
| `consul.grpc.server.streams` | Measures the number of active gRPC streams handled by the server. | streams | gauge |
|
||||
| `consul.grpc.client.request.count` | Counts the number of gRPC requests made by the client agent to a Consul server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | requests | counter |
|
||||
| `consul.grpc.client.connection.count` | Counts the number of new gRPC connections opened by the client agent to a Consul server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | connections | counter |
|
||||
| `consul.grpc.client.connections` | Measures the number of active gRPC connections open from the client agent to any Consul servers. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | connections | gauge |
|
||||
| `consul.grpc.server.request.count` | Counts the number of gRPC requests received by the server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | requests | counter |
|
||||
| `consul.grpc.server.connection.count` | Counts the number of new gRPC connections received by the server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | connections | counter |
|
||||
| `consul.grpc.server.connections` | Measures the number of active gRPC connections open on the server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | connections | gauge |
|
||||
| `consul.grpc.server.stream.count` | Counts the number of new gRPC streams received by the server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | streams | counter |
|
||||
| `consul.grpc.server.streams` | Measures the number of active gRPC streams handled by the server. Includes a `server_type` label indicating either the `internal` or `external` gRPC server. | streams | gauge |
|
||||
| `consul.xds.server.streams` | Measures the number of active xDS streams handled by the server split by protocol version. | streams | gauge |
|
||||
| `consul.xds.server.idealStreamsMax` | The maximum number of xDS streams per server, chosen to achieve a roughly even spread of load across servers. | streams | gauge |
|
||||
| `consul.xds.server.streamDrained` | Counts the number of xDS streams that are drained when rebalancing the load between servers. | streams | counter |
|
||||
|
|
|
|||
|
|
@ -15,29 +15,49 @@ 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).
|
||||
Consul Dataplane requires servers running Consul version `v1.14-beta1+`. 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. 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.
|
||||
- `-consul-dns-bind-addr` - The address bound to the Consul DNS proxy. Default is `"127.0.0.1"`.
|
||||
- `-consul-dns-bind-port` - The port that the Consul DNS proxy listens on. Default is `-1`, which disables the DNS proxy.
|
||||
- `-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`.
|
||||
- `-envoy-ready-bind-port` - The port 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-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.
|
||||
|
|
@ -46,11 +66,18 @@ The following options are required when starting `consul-dataplane` with the CLI
|
|||
- `-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-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-prom-ca-certs-path` - The path to a file or directory containing CA certificates used to verify the Prometheus server's certificate.
|
||||
- `-telemetry-prom-cert-file` - The path to the client certificate used to serve Prometheus metrics.
|
||||
- `-telemetry-prom-key-file` - The path to the client private key used to serve Prometheus metrics.
|
||||
- `-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.
|
||||
- `-telemetry-prom-retention-time` - The duration for Prometheus metrics aggregation. Default is `1m0s`. Refer to [`prometheus_retention_time`](/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"`.
|
||||
- `-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.
|
||||
- `-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`.
|
||||
|
|
@ -59,6 +86,8 @@ The following options are required when starting `consul-dataplane` with the CLI
|
|||
- `-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"`.
|
||||
- `-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.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -105,6 +134,21 @@ A static ACL token is passed to Consul Dataplane.
|
|||
|
||||
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> \
|
||||
|
|
@ -115,6 +159,9 @@ Consul Dataplane logs in to one of Consul's supported [auth methods](/consul/doc
|
|||
-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
|
||||
|
|
@ -127,4 +174,4 @@ $ 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.
|
||||
returned from the server watch stream.
|
||||
|
|
|
|||
|
|
@ -71,8 +71,6 @@ Integration with HCP Consul is being tested in an invitation-only closed beta. H
|
|||
|
||||
Be aware of the following limitations and recommendations for Consul Dataplane:
|
||||
|
||||
- Metrics and telemetry are not currently available for services deployed with Dataplane.
|
||||
- Consul API Gateway is not currently supported.
|
||||
- Transparent proxies are not supported.
|
||||
- Using `proxy-defaults` and `service-defaults` to configure default proxy behavior is not supported.
|
||||
- Consul Dataplane is not supported on Windows.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Consul Dataplane - Enable Telemetry Metrics
|
||||
description: >-
|
||||
Configure telemetry to collect metrics you can use to debug and observe Consul Dataplane behavior and performance.
|
||||
---
|
||||
|
||||
# Consul Dataplane Telemetry
|
||||
|
||||
Consul Dataplane collects metrics about its own status and performance.
|
||||
The following external metrics stores are supported:
|
||||
|
||||
- [DogstatsD](https://docs.datadoghq.com/developers/dogstatsd/)
|
||||
- [Prometheus](https://prometheus.io/docs/prometheus/latest/)
|
||||
- [StatsD](https://github.com/statsd/statsd)
|
||||
|
||||
Consul Dataplane uses the same external metrics store that is configured for Envoy. To enable
|
||||
telemetry for Consul Dataplane, enable telemetry for Envoy by specifying an external metrics store
|
||||
in the proxy-defaults configuration entry or directly in the proxy.config field of the proxy service
|
||||
definition. Refer to the [Envoy bootstrap
|
||||
configuration](/docs/connect/proxies/envoy#bootstrap-configuration) for details.
|
||||
|
||||
## Prometheus Metrics Merging
|
||||
|
||||
When Prometheus metrics are used, Consul Dataplane configures Envoy to serve merged metrics through
|
||||
a single endpoint. Metrics from the following sources are collected and merged:
|
||||
|
||||
- Consul Dataplane
|
||||
- The Envoy process managed by Consul Dataplane
|
||||
- (optionally) Your service instance running alongside Consul Dataplane
|
||||
|
||||
## Metrics Reference
|
||||
|
||||
Consul Dataplane supports the following metrics:
|
||||
|
||||
| Metric Name | Description | Unit | Type |
|
||||
| :------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------- | :------ |
|
||||
| `consul_dataplane.connect_duration` | Measures the time `consul-dataplane` spends connecting to a Consul server, including the time to discover Consul server addresses and to complete other setup prior to Envoy opening the xDS stream. | ms | timer |
|
||||
| `consul_dataplane.connected` | Indicates whether `consul-dataplane` is currently connected to a Consul server. | 1 or 0 | gauge |
|
||||
| `consul_dataplane.connection_errors` | Measures the number of errors encountered on gRPC streams. This is labeled with the gRPC error status code. | number of errors | gauge |
|
||||
| `consul_dataplane.discover_servers_duration` | Measures the time `consul-dataplane` spends discovering Consul server IP addresses. | ms | timer |
|
||||
| `consul_dataplane.envoy_connected` | Indicates whether Envoy is currently connected to `consul-dataplane` and able to receive xDS updates. | 1 or 0 | gauge |
|
||||
| `consul_dataplane.login_duration` | Measures the time `consul-dataplane` spends logging in to an ACL auth method. | ms | timer |
|
||||
|
|
@ -120,21 +120,25 @@ If TLS is enabled on Consul, you will also need to add the following environment
|
|||
|
||||
## Bootstrap Configuration
|
||||
|
||||
Envoy requires an initial bootstrap configuration file. The easiest way to
|
||||
create this is using the [`consul connect envoy`
|
||||
command](/commands/connect/envoy). The command can either output the
|
||||
bootstrap configuration directly to stdout, or generate the configuration and issue an `exec` command
|
||||
to the Envoy binary as a convenience wrapper. For more information about using `exec` to bootstrap Envoy, refer to [Exec Security Details](/consul/commands/connect/envoy#exec-security-details).
|
||||
Envoy requires an initial bootstrap configuration file. You can either create the file manually using the Consul command line or configure Consul Dataplane to generate the file.
|
||||
|
||||
Because some Envoy configuration options, such as metrics and tracing sinks, can only be
|
||||
specified via the bootstrap configuration, Connect as of Consul 1.5.0 adds
|
||||
the ability to control some parts of the bootstrap config via proxy configuration options.
|
||||
### Generate the bootstrap file on the Consul CLI
|
||||
|
||||
Add the following configuration items to the [global `proxy-defaults`
|
||||
configuration entry](/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` field
|
||||
of a [proxy service
|
||||
definition](/docs/connect/registration/service-registration) or
|
||||
[`sidecar_service`](/docs/connect/registration/sidecar-service) block.
|
||||
Connect to a local Consul client agent and run the [`consul connect envoy` command](/commands/connect/envoy) to create the Envoy bootstrap configuration. The command either outputs the bootstrap configuration directly to stdout or generates the configuration and issues an `exec` command to the Envoy binary as a convenience wrapper. For more information about using `exec` to bootstrap Envoy, refer to [Exec Security Details](/consul/commands/connect/envoy#exec-security-details).
|
||||
|
||||
### Generate the bootstrap file from Consul Dataplane
|
||||
|
||||
Consul Dataplane automatically configures and manages an Envoy process. Consul Dataplane generates the Envoy bootstrap configuration file prior to starting Envoy. To configure how Consul Dataplane starts Envoy, refer to the [Consul Dataplane CLI reference](/docs/connect/dataplane/consul-dataplane).
|
||||
|
||||
### Control bootstrap configuration from proxy configuration
|
||||
|
||||
Consul service mesh can control some parts of the bootstrap configuration by specifying Envoy proxy configuration options.
|
||||
|
||||
Add the following configuration items to the [global `proxy-defaults` configuration
|
||||
entry](/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config`
|
||||
field of a [proxy service definition](/docs/connect/registration/service-registration). When
|
||||
connected to a Consul client agent, you can place the configuration in the `proxy.config` field of
|
||||
the [`sidecar_service`](/docs/connect/registration/sidecar-service) block.
|
||||
|
||||
- `envoy_statsd_url` - A URL in the form `udp://ip:port` identifying a UDP
|
||||
StatsD listener that Envoy should deliver metrics to. For example, this may be
|
||||
|
|
@ -331,7 +335,7 @@ defaults that are inherited by all services.
|
|||
across Envoy worker threads. Consul service mesh Envoy integration supports the
|
||||
following `balance_inbound_connections` values:
|
||||
|
||||
- `""` - Empty string (default). No connection balancing strategy is used. Consul does not balance inbound connections.
|
||||
- `""` - Empty string (default). No connection balancing strategy is used. Consul does not balance inbound connections.
|
||||
- `exact_balance` - Inbound connections to the service use the
|
||||
[Envoy Exact Balance Strategy.](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig-exactbalance)
|
||||
|
||||
|
|
@ -398,7 +402,7 @@ definition](/docs/connect/registration/service-registration) or
|
|||
across Envoy worker threads. Consul service mesh Envoy integration supports the
|
||||
following `balance_outbound_connections` values:
|
||||
|
||||
- `""` - Empty string (default). No connection balancing strategy is used. Consul does not balance outbound connections.
|
||||
- `""` - Empty string (default). No connection balancing strategy is used. Consul does not balance outbound connections.
|
||||
- `exact_balance` - Outbound connections from the upstream use the
|
||||
[Envoy Exact Balance Strategy.](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig-exactbalance)
|
||||
|
||||
|
|
|
|||
|
|
@ -572,6 +572,10 @@
|
|||
{
|
||||
"title": "CLI Reference",
|
||||
"path": "connect/dataplane/consul-dataplane"
|
||||
},
|
||||
{
|
||||
"title": "Telemetry",
|
||||
"path": "connect/dataplane/telemetry"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -1145,7 +1149,7 @@
|
|||
},
|
||||
{
|
||||
"title": "Register Lambda Functions",
|
||||
"routes":[
|
||||
"routes": [
|
||||
{
|
||||
"title": "Requirements",
|
||||
"path": "lambda/registration"
|
||||
|
|
@ -1171,7 +1175,7 @@
|
|||
"text": "BETA",
|
||||
"type": "outlined",
|
||||
"color": "neutral"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue