From acef0e816e1053e0e9d99b2ad64cfd76ecf5c7cf Mon Sep 17 00:00:00 2001
From: "R.B. Boyer" <4903+rboyer@users.noreply.github.com>
Date: Thu, 20 Jan 2022 15:35:27 -0600
Subject: [PATCH] docs: update config entry docs for proxy-defaults to follow
new template (#12011)
---
.../connect/config-entries/proxy-defaults.mdx | 460 ++++++++++++++----
1 file changed, 366 insertions(+), 94 deletions(-)
diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx
index cd87af7fc..699c2d133 100644
--- a/website/content/docs/connect/config-entries/proxy-defaults.mdx
+++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx
@@ -9,54 +9,141 @@ description: >-
# Proxy Defaults
--> **v1.8.4+:** On Kubernetes, the `ProxyDefaults` custom resource is supported in Consul versions 1.8.4+.
-**v1.5.0+:** On other platforms, this config entry is supported in Consul versions 1.5.0+.
-The `proxy-defaults` config entry kind (`ProxyDefaults` on Kubernetes) allows for configuring global config
-defaults across all services for Connect proxy configuration. Currently, only
-one global entry is supported.
+The `proxy-defaults` configuration entry (`ProxyDefaults` on Kubernetes) allows you
+to configure global defaults across all services for Connect proxy
+configurations. Only one global entry is supported.
-## Sample Config Entries
+## Introduction
-### Default protocol
+You can customize some service registration settings for service mesh sidecar
+proxies centrally using the `proxy-defaults` configuration entry in the `kind`
+field.
-Set the default protocol for all sidecar proxies:
+You can still override this centralized configuration for specific services
+with the [`service-defaults`](/docs/connect/config-entries/service-defaults)
+configuration entry `kind` or for individual proxy instances in their [sidecar
+service definitions](/docs/connect/registration/sidecar-service).
+
+## Requirements
+
+The following Consul binaries are supported:
+* Consul 1.8.4+ on Kubernetes.
+* Consul 1.5.0+ on other platforms.
+
+## Usage
+
+1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements).
+1. Determine the settings you want to implement (see [Configuration](#configuration)). You can create a file containing the configuration or pass them to the state store directly to apply the configuration.
+1. Apply the configuration using one of the following methods:
+ - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details.
+ - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details.
+
+## Configuration
+
+Configure the following parameters to define a `proxy-defaults` configuration entry:
-Set the default protocol for all sidecar proxies:
-
-
+
+
```hcl
Kind = "proxy-defaults"
Name = "global"
+Meta {
+ = ""
+}
Config {
- protocol = "http"
+ =
+}
+Mode = ""
+TransparentProxy {
+ OutboundListenerPort =
+ DialedDirectly =
+}
+MeshGateway {
+ Mode = ""
+}
+Expose {
+ Checks =
+
+ Paths = [
+ {
+ Path = ""
+ LocalPathPort =
+ ListenerPort =
+ Protocol = ""
+ }
+ ]
}
```
+
+
+
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
+ meta:
+ :
config:
- protocol: http
+ :
+ mode:
+ transparentProxy:
+ outboundListenerPort:
+ dialedDirectly:
+ meshGateway:
+ mode:
+ expose:
+ checks:
+ paths:
+ - path:
+ localPathPort:
+ listenerPort:
+ protocol:=
```
+
+
+
```json
{
"Kind": "proxy-defaults",
"Name": "global",
+ "Meta": {
+ "": ""
+ },
"Config": {
- "protocol": "http"
+ "":
+ },
+ "Mode": "",
+ "TransparentProxy": {
+ "OutboundListenerPort": ,
+ "DialedDirectly":
+ },
+ "MeshGateway": {
+ "Mode": = ""
+ },
+ "Expose": {
+ "Checks": ,
+ "Paths": [
+ {
+ "Path": "",
+ "LocalPathPort": ,
+ "ListenerPort": ,
+ "Protocol": ""
+ }
+ ]
}
}
```
+
@@ -65,17 +152,44 @@ spec:
-> **NOTE:** The `proxy-defaults` config entry can only be created in the `default`
namespace and it will configure proxies in **all** namespaces.
-
+
+
```hcl
Kind = "proxy-defaults"
Name = "global"
Namespace = "default" # Can only be set to "default".
+Meta {
+ = ""
+}
Config {
- protocol = "http"
+ =
+}
+Mode = ""
+TransparentProxy {
+ OutboundListenerPort =
+ DialedDirectly =
+}
+MeshGateway {
+ Mode = ""
+}
+Expose {
+ Checks =
+
+ Paths = [
+ {
+ Path = ""
+ LocalPathPort =
+ ListenerPort =
+ Protocol = ""
+ }
+ ]
}
```
+
+
+
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
@@ -83,102 +197,68 @@ metadata:
name: global
namespace: default
spec:
+ meta:
+ :
config:
- protocol: http
+ :
+ mode:
+ transparentProxy:
+ outboundListenerPort:
+ dialedDirectly:
+ meshGateway:
+ mode:
+ expose:
+ checks:
+ paths:
+ - path:
+ localPathPort:
+ listenerPort:
+ protocol:=
```
+
+
+
```json
{
"Kind": "proxy-defaults",
"Name": "global",
"Namespace": "default",
+ "Meta": {
+ "": ""
+ },
"Config": {
- "protocol": "http"
+ "":
+ },
+ "Mode": "",
+ "TransparentProxy": {
+ "OutboundListenerPort": ,
+ "DialedDirectly":
+ },
+ "MeshGateway": {
+ "Mode": = ""
+ },
+ "Expose": {
+ "Checks": ,
+ "Paths": [
+ {
+ "Path": "",
+ "LocalPathPort": ,
+ "ListenerPort": ,
+ "Protocol": ""
+ }
+ ]
}
}
```
+
-### Prometheus
-
-Expose prometheus metrics:
-
-
-
-```hcl
-Kind = "proxy-defaults"
-Name = "global"
-Config {
- envoy_prometheus_bind_addr = "0.0.0.0:9102"
-}
-```
-
-```yaml
-apiVersion: consul.hashicorp.com/v1alpha1
-kind: ProxyDefaults
-metadata:
- name: global
-spec:
- config:
- envoy_prometheus_bind_addr: '0.0.0.0:9102'
-```
-
-```json
-{
- "Kind": "proxy-defaults",
- "Name": "global",
- "Config": {
- "envoy_prometheus_bind_addr": "0.0.0.0:9102"
- }
-}
-```
-
-
-
-### Proxy-specific defaults
-
-Set proxy-specific defaults:
-
-
-
-```hcl
-Kind = "proxy-defaults"
-Name = "global"
-Config {
- local_connect_timeout_ms = 1000
- handshake_timeout_ms = 10000
-}
-```
-
-```yaml
-apiVersion: consul.hashicorp.com/v1alpha1
-kind: ProxyDefaults
-metadata:
- name: global
-spec:
- config:
- local_connect_timeout_ms: 1000
- handshake_timeout_ms: 10000
-```
-
-```json
-{
- "Kind": "proxy-defaults",
- "Name": "global",
- "Config": {
- "local_connect_timeout_ms": 1000,
- "handshake_timeout_ms": 10000
- }
-}
-```
-
-
-
-## Available Fields
+### Configuration Parameters
+## Examples
+
+### Default protocol
+
+The following example configures the default protocol for all sidecar proxies.
+
+
+
+
+
+
+
+```hcl
+Kind = "proxy-defaults"
+Name = "global"
+Config {
+ protocol = "http"
+}
+```
+
+
+
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ProxyDefaults
+metadata:
+ name: global
+spec:
+ config:
+ protocol: http
+```
+
+
+
+
+```json
+{
+ "Kind": "proxy-defaults",
+ "Name": "global",
+ "Config": {
+ "protocol": "http"
+ }
+}
+```
+
+
+
+
+
+
+
+-> **NOTE:** The `proxy-defaults` config entry can only be created in the `default`
+namespace and it will configure proxies in **all** namespaces.
+
+
+
+
+```hcl
+Kind = "proxy-defaults"
+Name = "global"
+Namespace = "default" # Can only be set to "default".
+Config {
+ protocol = "http"
+}
+```
+
+
+
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ProxyDefaults
+metadata:
+ name: global
+ namespace: default
+spec:
+ config:
+ protocol: http
+```
+
+
+
+
+```json
+{
+ "Kind": "proxy-defaults",
+ "Name": "global",
+ "Namespace": "default",
+ "Config": {
+ "protocol": "http"
+ }
+}
+```
+
+
+
+
+
+
+
+### Prometheus
+
+The following example configures all sidecar proxies to expose Prometheus metrics.
+
+
+
+
+```hcl
+Kind = "proxy-defaults"
+Name = "global"
+Config {
+ envoy_prometheus_bind_addr = "0.0.0.0:9102"
+}
+```
+
+
+
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ProxyDefaults
+metadata:
+ name: global
+spec:
+ config:
+ envoy_prometheus_bind_addr: '0.0.0.0:9102'
+```
+
+
+
+
+```json
+{
+ "Kind": "proxy-defaults",
+ "Name": "global",
+ "Config": {
+ "envoy_prometheus_bind_addr": "0.0.0.0:9102"
+ }
+}
+```
+
+
+
+
+### Proxy-specific defaults
+
+The following example configures some custom default values for all sidecar proxies.
+
+
+
+
+```hcl
+Kind = "proxy-defaults"
+Name = "global"
+Config {
+ local_connect_timeout_ms = 1000
+ handshake_timeout_ms = 10000
+}
+```
+
+
+
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ProxyDefaults
+metadata:
+ name: global
+spec:
+ config:
+ local_connect_timeout_ms: 1000
+ handshake_timeout_ms: 10000
+```
+
+
+
+
+```json
+{
+ "Kind": "proxy-defaults",
+ "Name": "global",
+ "Config": {
+ "local_connect_timeout_ms": 1000,
+ "handshake_timeout_ms": 10000
+ }
+}
+```
+
+
+
+
## ACLs
Configuration entries may be protected by [ACLs](/docs/security/acl).