From 068703b836ad40a73e64ff34f2b2beac53a624b7 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 31 Oct 2023 14:11:42 -0700 Subject: [PATCH] Proxyconfiguration code review changes --- .../k8s/multiport/reference/grpcroute.mdx | 48 +++++++------- .../k8s/multiport/reference/httproute.mdx | 16 ++--- .../reference/proxyconfiguration.mdx | 62 +++++++------------ .../docs/k8s/multiport/reference/tcproute.mdx | 6 +- 4 files changed, 58 insertions(+), 74 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index c52e1a4027bc..bd6f730ade9b 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -1,14 +1,14 @@ --- layout: docs page_title: GRPCRoute resource configuration reference -description: The GRPCRoute resource CRD configures L7 GRPC traffic behavior within the service mesh. GRPCRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the GRPCRoute CRD with specifications and example configurations. +description: The GRPCRoute resource CRD configures L7 gRPC traffic behavior within the service mesh. GRPCRoute requires the v2 catalog API. Learn how to configure the GRPCRoute CRD with specifications and example configurations. --- # GRPCRoute resource configuration reference -This page provides reference information for the GRPCRoute resource, which defines L7 GRPC traffic within the service mesh. +This page provides reference information for the gRPC route resource, which defines L7 gRPC traffic within the service mesh. -This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). +This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). ## Configuration model @@ -20,10 +20,10 @@ The following list outlines field hierarchy, language-specific data types, and r - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1` - [`kind`](#kind): string | required | must be set to `GRPCRoute` -- [`metadata`](#metadata): object | required +- [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional -- [`spec`](#spec): object | required +- [`spec`](#spec): map | required - [`parentRefs`](#spec-parentrefs): map | required - [`port`](#spec-parentrefs-port): string - [`ref`](#spec-parentrefs-ref): string | required @@ -64,7 +64,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`remove`](#spec-rules-backendrefs-filters-responseheadermodifier): map - [`urlRewrite`](#spec-rules-backendrefs-filters-urlrewrite): map - [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): string - - [`weight`](#spec-rules-backendrefs-weight): integer | `1` + - [`weight`](#spec-rules-backendrefs-weight): number | `1` - [`filters`](#spec-rules-filters): map - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map - [`add`](#spec-rules-filters-requestheadermodifier): map @@ -87,24 +87,24 @@ The following list outlines field hierarchy, language-specific data types, and r - [`type`](#spec-rules-matches-method-type): string - [`retries`](#spec-rules-retries): map - [`number`](#spec-rules-retries-number): map - - [`value`](#spec-rules-retries-number): integer + - [`value`](#spec-rules-retries-number): number - [`onConditions`](#spec-rules-retries-onconditions): map of strings - [`onConnectFailure`](#spec-rules-retries-onconnectfailure): boolean | `false` - - [`onStatusCodes`](#spec-rules-retries-onconditions): map of integers + - [`onStatusCodes`](#spec-rules-retries-onconditions): map of numbers - [`timeouts`](#spec-rules-timeouts): map - [`idle`](#spec-rules-timeouts-idle): map - - [`nanos`](#spec-rules-timeouts-idle): integer - - [`seconds`](#spec-rules-timeouts-idle): integer + - [`nanos`](#spec-rules-timeouts-idle): number + - [`seconds`](#spec-rules-timeouts-idle): number - [`request`](#spec-rules-timeouts-request): map - - [`nanos`](#spec-rules-timeouts-request): integer - - [`seconds`](#spec-rules-timeouts-request): integer + - [`nanos`](#spec-rules-timeouts-request): numberer + - [`seconds`](#spec-rules-timeouts-request): number ## Complete configuration -When every field is defined, a GRPCRoute resource CRD has the following form: +When every field is defined, a gRPC route resource CRD has the following form: @@ -118,7 +118,7 @@ metadata: namespace: spec: parentRefs: - port: "" + port: - ref: name: section: @@ -149,24 +149,24 @@ spec: filters: - requestHeaderModifier: add: - name: "" - value: "" + name: + value: - responseHeaderModifier: set: - name: "" - value: "" + name: + value: urlRewrite: pathPrefix: weight: 1 filters: requestHeaderModifier: remove: - name: "" - value: "" + name: + value: responseHeaderModifier: add: - name: "" - value: "" + name: + value: urlRewrite: pathPrefix: matches: @@ -452,7 +452,7 @@ Specifies filtering behavior for services configured in the same [`spec.rules.ba ### `spec.rules.backendRefs.filters.requestHeaderModifier` -Specifies a set of header modification rules applied to requests routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to requests routed with the gRPC route resource. #### Values @@ -472,7 +472,7 @@ The following table describes how to configure values for request headers: ### `spec.rules.backendRefs.filters.responseHeaderModifier` -Specifies a set of header modification rules applied to responses routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to responses routed with the gRPC route resource. #### Values diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index 3673fce2381b..b7c75c7714b2 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -20,10 +20,10 @@ The following list outlines field hierarchy, language-specific data types, and r - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1` - [`kind`](#kind): string | required | must be set to `HTTPRoute` -- [`metadata`](#metadata): object | required +- [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional -- [`spec`](#spec): object | required +- [`spec`](#spec): map | required - [`parentRefs`](#spec-parentrefs): map | required - [`port`](#spec-parentrefs-port): string - [`ref`](#spec-parentrefs-ref): string | required @@ -64,7 +64,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`remove`](#spec-rules-backendrefs-filters-responseheadermodifier): map - [`urlRewrite`](#spec-rules-backendrefs-filters-urlrewrite): map - [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): string - - [`weight`](#spec-rules-backendrefs-weight): integer | `1` + - [`weight`](#spec-rules-backendrefs-weight): number | `1` - [`filters`](#spec-rules-filters): map - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map - [`add`](#spec-rules-filters-requestheadermodifier): map @@ -91,17 +91,17 @@ The following list outlines field hierarchy, language-specific data types, and r - [`value`](#spec-rules-matches-queryparams-value): string - [`retries`](#spec-rules-retries): map - [`number`](#spec-rules-retries-number): map - - [`value`](#spec-rules-retries-number): integer + - [`value`](#spec-rules-retries-number): number - [`onConditions`](#spec-rules-retries-onconditions): map of strings - [`onConnectFailure`](#spec-rules-retries-onconnectfailure): boolean | `false` - [`onStatusCodes`](#spec-rules-retries-onconditions): map of integers - [`timeouts`](#spec-rules-timeouts): map - [`idle`](#spec-rules-timeouts-idle): map - - [`nanos`](#spec-rules-timeouts-idle): integer - - [`seconds`](#spec-rules-timeouts-idle): integer + - [`nanos`](#spec-rules-timeouts-idle): number + - [`seconds`](#spec-rules-timeouts-idle): number - [`request`](#spec-rules-timeouts-request): map - - [`nanos`](#spec-rules-timeouts-request): integer - - [`seconds`](#spec-rules-timeouts-request): integer + - [`nanos`](#spec-rules-timeouts-request): number + - [`seconds`](#spec-rules-timeouts-request): number diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx index 38126d49a4cf..6ca2493c18c7 100644 --- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx +++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx @@ -6,7 +6,7 @@ description: The ProxyConfiguration resource CRD configures sidecar proxy behavi # ProxyConfiguration resource configuration reference -This page provides reference information for the ProxyConfigurations resource, which defines proxy behavior for traffic within the service mesh. The resource specifies both bootstrap and dynamic configurations for proxies. +This page provides reference information for the `ProxyConfigurations` resource, which defines proxy behavior for traffic within the service mesh. The resource specifies both bootstrap and dynamic configurations for proxies. This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). @@ -14,16 +14,12 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t The following list outlines field hierarchy, language-specific data types, and requirements in a ProxyConfiguration CRD. Click on a property name to view additional details, including default values. - - - - - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1` - [`kind`](#kind): string | required | must be set to `ProxyConfiguration` -- [`metadata`](#metadata): object | required +- [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional -- [`spec`](#spec): object | required +- [`spec`](#spec): map | required - [`workloads`](#spec-workloads): map - [`filter`](#spec-workloads): string - [`names`](#spec-workloads): array of strings @@ -76,19 +72,10 @@ The following list outlines field hierarchy, language-specific data types, and r - [`dialedDirectly`](#spec-dynamicconfig-transparentproxy-dialeddirectly): boolean | `false` - [`outboundListenerPort`](#spec-dynamicconfig-transparentproxy-outboundlistenerport): integer | `15001` - - - ## Complete configuration When every field is defined, an ProxyConfigurations CRD has the following form: - - - - - - ```yaml apiVersion: mesh.consul.hashicorp.com/v2beta1 # required kind: ProxyConfiguration # required @@ -150,11 +137,6 @@ spec: outboundListenerPort: 15001 ``` - - - - - ## Specification This section provides details about the fields you can configure in the ProxyConfiguration custom resource definition (CRD). @@ -200,7 +182,7 @@ Specifies a name for the CRD. The name is metadata that you can use to reference ### `metadata.namespace` -Specifies the namespace that the service resolver applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information. +Specifies the namespace that the proxy configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information. #### Values @@ -246,7 +228,7 @@ Specifies initial bootstrap settings for the Envoy proxy, as well as proxy confi Specifies a URL that identifies a DataDog DogStatsD listener. Envoy sends metrics to this listener. -Format the URL as `udp://ip:port` or `unix://uds/path`. For example, `udp://127.0.0.1:8125` configures a local UDP DogStatsD listener for every host. Currently, TCP is not supported. +Format the URL as `udp://ip:port` or `unix://uds/path`. For example, `udp://127.0.0.1:8125` configures a local UDP DogStatsD listener for every host. TCP is not supported. The UDP URL must use an IP address. DNS names are not supported. @@ -259,9 +241,11 @@ For more information about configuring a UNIX domain socket with DogStatsD, refe ### `spec.bootstrapConfig.overrideJsonTpl` -Specifies a template in Go template syntax to use in place of [the default template](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L129) when generating bootstrap via [`consul connect envoy` command](/consul/commands/connect/envoy). The variables that are available to be interpolated are [documented in `bootstrap_tpl.go`](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5). - + This field offers complete control of the proxy's bootstrap. Be aware that major deviations from the default template may break Consul's ability to correctly manage the proxy or enforce its security model. + + +Specifies a template in Go template syntax to use in place of [the default template](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L129) when generating the bootstrap configuration using the [`consul connect envoy` command](/consul/commands/connect/envoy). For information about the variables Consul can interpolate in the template, refer to the [documentation in `bootstrap_tpl.go`](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5). Refer to [Envoy proxy escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) for more information. @@ -281,9 +265,9 @@ Specifies that the proxy should expose a Prometheus metrics endpoint to the _pub ### `spec.bootstrapConfig.readyBindAddr` - Specifies the location to confiugure the proxy's readiness probe, specified as `ip:port`. - - By default the proxy does not have a readiness probe configured on it. +Specifies the location to configure the proxy's readiness probe. Format as `ip:port`. + + By default, the proxy does not have a readiness probe configured on it. #### Values @@ -292,7 +276,7 @@ Specifies that the proxy should expose a Prometheus metrics endpoint to the _pub ### `spec.bootstrapConfig.staticClustersJson` -Specifies one or more [Envoy clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto) to append to the array of [static clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters) in the bootstrap config. +Specifies one or more [Envoy clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto) to append to the array of [static clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters) in the bootstrap configuration. This field enables you to add custom clusters, such as tracing sinks, to the bootstrap configuration. In order to configure a single cluster, specify a single JSON object with the cluster details. @@ -371,7 +355,7 @@ Specifies one or more static tags to add to all metrics produced by the proxy. Specifies a URL that identifies a StatsD listener. Envoy sends metrics to this listener. -Format the URL as `udp://ip:port`. For example, `udp://127.0.0.1:8125` configures a local StatsD listener for every host. Currently, TCP is not supported. +Format the URL as `udp://ip:port`. For example, `udp://127.0.0.1:8125` configures a local StatsD listener for every host. TCP is not supported. The URL must use an IP address. DNS names are not supported. @@ -496,7 +480,7 @@ Refer to [expose paths configuration reference](/consul/docs/connect/proxies/pro ### `spec.dynamicConfig.exposeConfig.exposePaths` -Specifies a configuration for exposing a HTTP path through the proxy. +Specifies a configuration for exposing an HTTP path through the proxy. Refer to [expose paths configuration reference](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference) for more information. @@ -569,7 +553,7 @@ Specifies the strategy for balancing inbound connections across Envoy worker thr ### `spec.dynamicConfig.inboundConnections.maxInboundConnections` - Specifies the maximum number of concurrent inbound connections to the local application instance. If not specified, inherits the Envoy default of `1024`. +Specifies the maximum number of concurrent inbound connections to the local application instance. If not specified, inherits the Envoy default of `1024`. #### Values @@ -587,7 +571,7 @@ Specifies a tracing configuration to be inserted in the proxy's public and upstr ### `spec.dynamicConfig.localClusterJson` -Specifies a complete Envoy cluster to be delivered in place of the local application cluster. This field enables customization of timeouts, rate limits, and load balancing strategy. +Specifies a complete Envoy cluster to be delivered in place of the local application cluster. Use this field to customize timeouts, rate limits, and load balancing strategy. Refer to [cluster configuration in the Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto) for more information. @@ -623,7 +607,7 @@ Specifies the length of time the proxy is allowed to attempt connections to the ### `spec.dynamicConfig.localConnection.requestTimeout` -Specifies the length of time the proxy is allowed to attempt HTTP requests to the local application instance. Applies to HTTP based protocols only. +Specifies the length of time the proxy is allowed to attempt HTTP requests to the local application instance. Applies to HTTP-based protocols only. #### Values @@ -637,7 +621,7 @@ Specifies the length of time the proxy is allowed to attempt HTTP requests to th ### `spec.dynamicConfig.meshGatewayMode` -Specifies the mode of operation for how upstreams with a remote destination datacenter are resolved. Refer to [Mesh gateway configuration reference](/consul/docs/connect/proxies/proxy-config-reference#mesh-gateway-configuration-reference) for more information. +Specifies the proxy's mode of operation for resolving upstreams in remote datacenter destinations. Refer to [Mesh gateway configuration reference](/consul/docs/connect/proxies/proxy-config-reference#mesh-gateway-configuration-reference) for more information. #### Values @@ -651,7 +635,7 @@ Specifies the mode of operation for how upstreams with a remote destination data ### `spec.dynamicConfig.mode` -Specifies the mode the proxy operates in: default, transparent, or direct. Refer to [proxy modes](/consul/docs/connect/proxies/proxy-config-reference#proxy-modes) for more information. +Configures the proxy to operate in transparent, direct, or default mode. Refer to [proxy modes](/consul/docs/connect/proxies/proxy-config-reference#proxy-modes) for more information. #### Values @@ -664,7 +648,7 @@ Specifies the mode the proxy operates in: default, transparent, or direct. Refer ### `spec.dynamicConfig.publicListenerJson` -Specifies a complete Envoy listener to be delivered in place of the main public listener that the proxy used to accept inbound connections. Refer to [escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) for more information +Specifies a complete Envoy listener for Consul to deliver in place of the main public listener that the proxy uses to accept inbound connections. Refer to [escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) for more information #### Values @@ -673,7 +657,7 @@ Specifies a complete Envoy listener to be delivered in place of the main public ### `spec.dynamicConfig.transparentProxy` -Specifies additional configurations for the transparent proxy. Refer to [transparent proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference#transparent-proxy-configuration-reference) for more information. +Specifies additional configurations for operating proxies in transparent proxy mode. Refer to [transparent proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference#transparent-proxy-configuration-reference) for more information. #### Values @@ -682,7 +666,7 @@ Specifies additional configurations for the transparent proxy. Refer to [transpa ### `spec.dynamicConfig.transparentProxy.dialedDirectly` -Determines whether this proxy instance's IP address can be dialed directly by transparent proxies. Transparent proxies typically dial upstreams using the "virtual" tagged address, which load balances across instances. A database cluster with a leader is an example where dialing individual instances can be helpful. +Determines whether this proxy instance's IP address can be dialed directly by transparent proxies. Transparent proxies typically dial upstreams using the _virtual_ tagged address, which load balances across instances. A database cluster with a leader is an example where dialing individual instances can be helpful. #### Values diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx index d0761f98869e..4201f8b92fa0 100644 --- a/website/content/docs/k8s/multiport/reference/tcproute.mdx +++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx @@ -20,10 +20,10 @@ The following list outlines field hierarchy, language-specific data types, and r - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1` - [`kind`](#kind): string | required | must be set to `TCPRoute` -- [`metadata`](#metadata): object | required +- [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional -- [`spec`](#spec): object | required +- [`spec`](#spec): map | required - [`parentRefs`](#spec-parentrefs): map | required - [`port`](#spec-parentrefs-port): string - [`ref`](#spec-parentrefs-ref): string | required @@ -53,7 +53,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`group`](#spec-rules-backendrefs-backendref-ref-type): string - [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): string - [`kind`](#spec-rules-backendrefs-backendref-ref-type): string - - [`weight`](#spec-rules-backendrefs-weight): integer + - [`weight`](#spec-rules-backendrefs-weight): number