From 062ee8c1371ca2d0f4fca11981f8bec0e1681cc0 Mon Sep 17 00:00:00 2001 From: Melisa Griffin Date: Fri, 8 Sep 2023 10:02:04 -0400 Subject: [PATCH] Adds PassiveHealthCheck Fields to ServiceDefaults and IngressGateway (#18532) Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../config-entries/ingress-gateway.mdx | 801 +++++++++--------- .../config-entries/service-defaults.mdx | 320 ++++--- 2 files changed, 606 insertions(+), 515 deletions(-) diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 4c1b57e75e75..cf553af14f1f 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -7,7 +7,7 @@ description: >- # Ingress gateway configuration entry reference -This topic provides configuration reference information for the ingress gateway configuration entry. An ingress gateway is a type of proxy you register as a service in Consul to enable network connectivity from external services to services inside of the service mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway) for additional information. +This topic provides configuration reference information for the ingress gateway configuration entry. An ingress gateway is a type of proxy you register as a service in Consul to enable network connectivity from external services to services inside of the service mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway) for additional information. ## Configuration model @@ -19,121 +19,129 @@ The following list describes the configuration hierarchy, language-specific data - [`Kind`](#kind): string | must be `ingress-gateway` | required - [`Name`](#name): string | required - [`Namespace`](#namespace): string | `default` | -- [`Meta`](#meta): map of strings +- [`Meta`](#meta): map of strings - [`Partition`](#partition): string | `default` | -- [`TLS`](#tls): map +- [`TLS`](#tls): map - [`Enabled`](#tls-enabled): boolean | `false` - [`TLSMinVersion`](#tls-tlsminversion): string | `TLSv1_2` - - [`TLSMaxVersion`](#tls-tlsmaxversion): string - - [`CipherSuites`](#tls-ciphersuites): list of strings - - [`SDS`](#tls-sds): map of strings - - [`ClusterName`](#tls-sds): string - - [`CertResource`](#tls-sds): string -- [`Defaults`](#defaults): map - - [`MaxConnections`](#defaults-maxconnections): number - - [`MaxPendingRequests`](#defaults-maxpendingrequests): number - - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests): number - - [`PassiveHealthCheck`](#defaults-passivehealthcheck): map - - [`interval`](#defaults-passivehealthcheck): number - - [`max_failures`](#defaults-passivehealthcheck): number - - [`enforcing_consecutive_5xx`](#defaults-passivehealthcheck): number -- [`Listeners`](#listeners): list of maps + - [`TLSMaxVersion`](#tls-tlsmaxversion): string + - [`CipherSuites`](#tls-ciphersuites): list of strings + - [`SDS`](#tls-sds): map of strings + - [`ClusterName`](#tls-sds): string + - [`CertResource`](#tls-sds): string +- [`Defaults`](#defaults): map + - [`MaxConnections`](#defaults-maxconnections): number + - [`MaxPendingRequests`](#defaults-maxpendingrequests): number + - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests): number + - [`PassiveHealthCheck`](#defaults-passivehealthcheck): map + - [`Interval`](#defaults-passivehealthcheck): number + - [`MaxFailures`](#defaults-passivehealthcheck): number + - [`EnforcingConsecutive5xx`](#defaults-passivehealthcheck): number + - [`MaxEjectionPercent`](#defaults-passivehealthcheck): number + - [`BaseEjectionTime`](#defaults-passivehealthcheck): string +- [`Listeners`](#listeners): list of maps - [`Port`](#listeners-port): number | `0` - [`Protocol`](#listeners-protocol): number | `tcp` - - [`Services`](#listeners-services): list of objects - - [`Name`](#listeners-services-name): string + - [`Services`](#listeners-services): list of objects + - [`Name`](#listeners-services-name): string - [`Namespace`](#listeners-services-namespace): string | - [`Partition`](#listeners-services-partition): string | - [`Hosts`](#listeners-services-hosts): List of strings | `.ingress.*` - - [`RequestHeaders`](#listeners-services-requestheaders): map - - [`Add`](#listeners-services-requestheaders): map of strings - - [`Set`](#listeners-services-requestheaders): map of strings - - [`Remove`](#listeners-services-requestheaders): list of strings - - [`ResponseHeaders`](#listeners-services-responseheaders): map - - [`Add`](#listeners-services-responseheaders): map of strings - - [`Set`](#listeners-services-responseheaders): map of strings - - [`Remove`](#listeners-services-responseheaders): list of strings - - [`TLS`](#listeners-services-tls): map - - [`SDS`](#listeners-services-tls-sds): map of strings - - [`ClusterName`](#listeners-services-tls-sds): string - - [`CertResource`](#listeners-services-tls-sds): string + - [`RequestHeaders`](#listeners-services-requestheaders): map + - [`Add`](#listeners-services-requestheaders): map of strings + - [`Set`](#listeners-services-requestheaders): map of strings + - [`Remove`](#listeners-services-requestheaders): list of strings + - [`ResponseHeaders`](#listeners-services-responseheaders): map + - [`Add`](#listeners-services-responseheaders): map of strings + - [`Set`](#listeners-services-responseheaders): map of strings + - [`Remove`](#listeners-services-responseheaders): list of strings + - [`TLS`](#listeners-services-tls): map + - [`SDS`](#listeners-services-tls-sds): map of strings + - [`ClusterName`](#listeners-services-tls-sds): string + - [`CertResource`](#listeners-services-tls-sds): string - [`MaxConnections`](#listeners-services-maxconnections): number | `0` - [`MaxPendingRequests`](#listeners-services-maxconnections): number | `0` - [`MaxConcurrentRequests`](#listeners-services-maxconnections): number | `0` - - [`PassiveHealthCheck`](#listeners-services-passivehealthcheck): map - - [`interval`](#listeners-services-passivehealthcheck): number - - [`max_failures`](#listeners-services-passivehealthcheck): number - - [`enforcing_consecutive_5xx`](#listeners-services-passivehealthcheck): number - - [`TLS`](#listeners-tls): map + - [`PassiveHealthCheck`](#listeners-services-passivehealthcheck): map + - [`Interval`](#listeners-services-passivehealthcheck): number + - [`MaxFailures`](#listeners-services-passivehealthcheck): number + - [`EnforcingConsecutive5xx`](#listeners-services-passivehealthcheck): number + - [`MaxEjectionPercent`](#listeners-services-passivehealthcheck): number + - [`BaseEjectionTime`](#listeners-services-passivehealthcheck): string + - [`TLS`](#listeners-tls): map - [`Enabled`](#listeners-tls-enabled): boolean | `false` - [`TLSMinVersion`](#listeners-tls-tlsminversion): string | `TLSv1_2` - - [`TLSMaxVersion`](#listeners-tls-tlsmaxversion): string - - [`CipherSuites`](#listeners-tls-ciphersuites): list of strings - - [`SDS`](#listeners-tls-sds): map of strings - - [`ClusterName`](#listeners-tls-sds): string - - [`CertResource`](#listeners-tls-sds): string + - [`TLSMaxVersion`](#listeners-tls-tlsmaxversion): string + - [`CipherSuites`](#listeners-tls-ciphersuites): list of strings + - [`SDS`](#listeners-tls-sds): map of strings + - [`ClusterName`](#listeners-tls-sds): string + - [`CertResource`](#listeners-tls-sds): string -- [ `apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` | required +- [ `apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` | required - [`kind`](#kind): string | must be `IngressGateway` | required -- [`metadata`](#metadata): map of strings +- [`metadata`](#metadata): map of strings - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | `default` | -- [`spec`](#spec): map - - [`tls`](#spec-tls): map +- [`spec`](#spec): map + - [`tls`](#spec-tls): map - [`enabled`](#spec-tls-enabled): boolean | `false` - [`tlsMinVersion`](#spec-tls-tlsminversion): string | `TLSv1_2` - - [`tlsMaxVersion`](#spec-tls-tlsmaxversion): string - - [`cipherSuites`](#spec-tls-ciphersuites): list of strings - - [`sds`](#spec-tls-sds): map of strings - - [`clusterName`](#spec-tls-sds): string - - [`certResource`](#spec-tls-sds): string - - [`defaults`](#spec-defaults): map - - [`maxConnections`](#spec-defaults-maxconnections): number - - [`maxPendingRequests`](#spec-defaults-maxpendingrequests): number - - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests): number - - [`passiveHealthCheck`](#spec-defaults-passivehealthcheck): map - - [`interval`](#spec-defaults-passivehealthcheck): number | no proxy's default value - - [`max_failures`](#spec-defaults-passivehealthcheck): number | no proxy's default value - - [`enforcing_consecutive_5xx`](#spec-defaults-passivehealthcheck): number | proxy's default value - - [`listeners`](#spec-listeners): list of maps + - [`tlsMaxVersion`](#spec-tls-tlsmaxversion): string + - [`cipherSuites`](#spec-tls-ciphersuites): list of strings + - [`sds`](#spec-tls-sds): map of strings + - [`clusterName`](#spec-tls-sds): string + - [`certResource`](#spec-tls-sds): string + - [`defaults`](#spec-defaults): map + - [`maxConnections`](#spec-defaults-maxconnections): number + - [`maxPendingRequests`](#spec-defaults-maxpendingrequests): number + - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests): number + - [`passiveHealthCheck`](#spec-defaults-passivehealthcheck): map + - [`interval`](#spec-defaults-passivehealthcheck): string + - [`maxFailures`](#spec-defaults-passivehealthcheck): integer + - [`enforcingConsecutive5xx`](#spec-defaults-passivehealthcheck): number + - [`maxEjectionPercent`](#spec-defaults-passivehealthcheck): number + - [`baseEjectionTime`](#spec-defaults-passivehealthcheck): string + - [`listeners`](#spec-listeners): list of maps - [`port`](#spec-listeners-port): number | `0` - [`protocol`](#spec-listeners-protocol): number | `tcp` - - [`services`](#spec-listeners-services): list of maps - - [`name`](#spec-listeners-services-name): string + - [`services`](#spec-listeners-services): list of maps + - [`name`](#spec-listeners-services-name): string - [`namespace`](#spec-listeners-services-namespace): string | current namespace | - [`partition`](#spec-listeners-services-partition): string | current partition | - [`hosts`](#spec-listeners-services-hosts): list of strings | `.ingress.*` - - [`requestHeaders`](#spec-listeners-services-requestheaders): map - - [`add`](#spec-listeners-services-requestheaders): map of strings - - [`set`](#spec-listeners-services-requestheaders): map of strings - - [`remove`](#spec-listeners-services-requestheaders): list of strings - - [`responseHeaders`](#spec-listeners-services-responseheaders): map - - [`add`](#spec-listeners-services-responseheaders): map of strings - - [`set`](#spec-listeners-services-responseheaders): map of strings - - [`remove`](#spec-listeners-services-responseheaders): list of strings - - [`tls`](#spec-listeners-services-tls): map - - [`sds`](#spec-listeners-services-tls-sds): map of strings - - [`clusterName`](#spec-listeners-services-tls-sds): string - - [`certResource`](#spec-listeners-services-tls-sds): string + - [`requestHeaders`](#spec-listeners-services-requestheaders): map + - [`add`](#spec-listeners-services-requestheaders): map of strings + - [`set`](#spec-listeners-services-requestheaders): map of strings + - [`remove`](#spec-listeners-services-requestheaders): list of strings + - [`responseHeaders`](#spec-listeners-services-responseheaders): map + - [`add`](#spec-listeners-services-responseheaders): map of strings + - [`set`](#spec-listeners-services-responseheaders): map of strings + - [`remove`](#spec-listeners-services-responseheaders): list of strings + - [`tls`](#spec-listeners-services-tls): map + - [`sds`](#spec-listeners-services-tls-sds): map of strings + - [`clusterName`](#spec-listeners-services-tls-sds): string + - [`certResource`](#spec-listeners-services-tls-sds): string - [`maxConnections`](#spec-listeners-services-maxconnections): number | `0` - [`maxPendingRequests`](#spec-listeners-services-maxconnections): number | `0` - [`maxConcurrentRequests`](#spec-listeners-services-maxconnections): number | `0` - - [`passiveHealthCheck`](#spec-listeners-services-passivehealthcheck): map - - [`interval`](#spec-listeners-services-passivehealthcheck): number - - [`max_failures`](#spec-listeners-services-passivehealthcheck): number - - [`enforcing_consecutive_5xx`](#spec-listeners-services-passivehealthcheck): number - - [`tls`](#spec-listeners-tls): map + - [`passiveHealthCheck`](#spec-listeners-services-passivehealthcheck): map + - [`interval`](#spec-listeners-services-passivehealthcheck): string + - [`maxFailures`](#spec-listeners-services-passivehealthcheck): number + - [`enforcingConsecutive5xx`](#spec-listeners-services-passivehealthcheck): number + - [`maxEjectionPercent`](#spec-listeners-services-passivehealthcheck): integer + - [`baseEjectionTime`](#spec-listeners-services-passivehealthcheck): string + - [`tls`](#spec-listeners-tls): map - [`enabled`](#spec-listeners-tls-enabled): boolean | `false` - [`tlsMinVersion`](#spec-listeners-tls-tlsminversion): string | `TLSv1_2` - - [`tlsMaxVersion`](#spec-listeners-tls-tlsmaxversion): string - - [`cipherSuites`](#spec-listeners-tls-ciphersuites): list of strings - - [`sds`](#spec-listeners-tls-sds): map of strings - - [`clusterName`](#spec-listeners-tls-sds): string - - [`certResource`](#spec-listeners-tls-sds): string + - [`tlsMaxVersion`](#spec-listeners-tls-tlsmaxversion): string + - [`cipherSuites`](#spec-listeners-tls-ciphersuites): list of strings + - [`sds`](#spec-listeners-tls-sds): map of strings + - [`clusterName`](#spec-listeners-tls-sds): string + - [`certResource`](#spec-listeners-tls-sds): string @@ -148,94 +156,98 @@ When every field is defined, an ingress gateway configuration entry has the foll ```hcl -Kind = "ingress-gateway" -Name = "" -Namespace = "" -Partition = "" -Meta = { +Kind = "ingress-gateway" +Name = "" +Namespace = "" +Partition = "" +Meta = { = "" } -TLS = { - Enabled = false - TLSMinVersion = "TLSv1_2" - TLSMaxVersion = "" - CipherSuites = [ +TLS = { + Enabled = false + TLSMinVersion = "TLSv1_2" + TLSMaxVersion = "" + CipherSuites = [ "" ] - SDS = { - ClusterName = "" - CertResource = "" + SDS = { + ClusterName = "" + CertResource = "" } } -Defaults = { - MaxConnections = 0 - MaxPendingRequests = 0 - MaxConcurrentRequests = 0 - PassiveHealthCheck = { - interval = 10 - max_failures = 5 - enforcing_consecutive_5xx = 100 +Defaults = { + MaxConnections = + MaxPendingRequests = + MaxConcurrentRequests = + PassiveHealthCheck = { + Interval = "" + MaxFailures = + EnforcingConsecutive5xx = + MaxEjectionPercent = + BaseEjectionTime = "" } } -Listeners = [ - { - Port = 0 - Protocol = "tcp" - Services = [ - { - Name = "" - Namespace = "" - Partition = "" - Hosts = [ - ".ingress.*" +Listeners = [ + { + Port = 0 + Protocol = "tcp" + Services = [ + { + Name = "" + Namespace = "" + Partition = "" + Hosts = [ + ".ingress.*" ] - RequestHeaders = { - Add = { - RequestHeaderName = "" + RequestHeaders = { + Add = { + RequestHeaderName = "" } - Set = { - RequestHeaderName = "" + Set = { + RequestHeaderName = "" } - Remove = [ - "" + Remove = [ + "" ] } - ResponseHeaders = { - Add = { - ResponseHeaderName = "" + ResponseHeaders = { + Add = { + ResponseHeaderName = "" } - Set = { - ResponseHeaderName = "" + Set = { + ResponseHeaderName = "" } - Remove = [ - "" + Remove = [ + "" ] } - TLS = { - SDS = { - ClusterName = "" - CertResource = "" + TLS = { + SDS = { + ClusterName = "" + CertResource = "" } } - MaxConnections = - MaxPendingRequests = - MaxConcurrentRequests = - PassiveHealthCheck = { - interval = 10 - max_failures = 5 - enforcing_consecutive_5xx = 100 + MaxConnections = + MaxPendingRequests = + MaxConcurrentRequests = + PassiveHealthCheck = { + Interval = "" + MaxFailures = + EnforcingConsecutive5xx = + MaxEjectionPercent = + BaseEjectionTime = "" } }] - TLS = { - Enabled = false - TLSMinVersion = "TLSv1_2" - TLSMaxVersion = "" - CipherSuites = [ - "" + TLS = { + Enabled = false + TLSMinVersion = "TLSv1_2" + TLSMaxVersion = "" + CipherSuites = [ + "" ] - SDS = { - ClusterName = "" - CertResource = "" + SDS = { + ClusterName = "" + CertResource = "" } } } @@ -248,71 +260,75 @@ Listeners = [ ```yaml apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway +kind: IngressGateway metadata: - name: - namespace: "" -spec: - tls: - enabled: false - tlsSMinVersion: TLSv1_2 - tlsMaxVersion: "" - cipherSuites: + name: + namespace: "" +spec: + tls: + enabled: false + tlsSMinVersion: TLSv1_2 + tlsMaxVersion: "" + cipherSuites: - - sds: - clusterName: - certResource: - defaults: - maxConnections: 0 - maxPendingRequests: 0 - maxConcurrentRequests: 0 - passiveHealthCheck: - interval: 10 - max_failures: 5 - enforcing_consecutive_5xx: 100 - listeners: - - port: 0 - protocol: tcp - services: - - name: - namespace: + sds: + clusterName: + certResource: + defaults: + maxConnections: + maxPendingRequests: + maxConcurrentRequests: + passiveHealthCheck: + interval: "" + maxFailures: + enforcingConsecutive5xx: + maxEjectionPercent: + baseEjectionTime: "" + listeners: + - port: 0 + protocol: tcp + services: + - name: + namespace: partition: - hosts: - - .ingress.* - requestHeaders: - add: + hosts: + - .ingress.* + requestHeaders: + add: requestHeaderName: set: requestHeaderName: - remove: - - - responseHeaders: - add: - responseHeaderName: - set: + remove: + - + responseHeaders: + add: + responseHeaderName: + set: responseHeaderName: remove: - - - tls: - sds: + - + tls: + sds: clusterName: - certResource: - maxConnections: - maxPendingRequests: - maxConcurrentRequests: - passiveHealthCheck: - interval: 10 - max_failures: 5 - enforcing_consecutive_5xx: 100 - tls: - enabled: false - tlsMinVersion: TLSv1_2 - tlsMaxVersion: - cipherSuites: - - - sds: - clusterName: - certResource: + certResource: + maxConnections: + maxPendingRequests: + maxConcurrentRequests: + passiveHealthCheck: + interval: "" + maxFailures: + enforcingConsecutive5xx: + maxEjectionPercent: + baseEjectionTime: "" + tls: + enabled: false + tlsMinVersion: TLSv1_2 + tlsMaxVersion: + cipherSuites: + - + sds: + clusterName: + certResource: ``` @@ -321,100 +337,103 @@ spec: ```json { - "Kind" : "ingress-gateway", - "Name" : "", - "Namespace" : "", - "Partition" : "", - "Meta": { + "Kind" : "ingress-gateway", + "Name" : "", + "Namespace" : "", + "Partition" : "", + "Meta": { "" : "" }, - "TLS" : { - "Enabled" : false, - "TLSMinVersion" : "TLSv1_2", - "TLSMaxVersion" : "", - "CipherSuites" : [ + "TLS" : { + "Enabled" : false, + "TLSMinVersion" : "TLSv1_2", + "TLSMaxVersion" : "", + "CipherSuites" : [ "" ], - "SDS": { - "ClusterName" : "", - "CertResource" : "" + "SDS": { + "ClusterName" : "", + "CertResource" : "" } }, - "Defaults" : { - "MaxConnections" : 0, - "MaxPendingRequests" : 0, - "MaxConcurrentRequests": 0, - "PassiveHealthCheck" : { - "interval" : 10, - "max_failures" : 5, - "enforcing_consecutive_5xx" : 100 + "Defaults" : { + "MaxConnections" : , + "MaxPendingRequests" : , + "MaxConcurrentRequests": , + "PassiveHealthCheck" : { + "interval": ", + "maxFailures": , + "enforcingConsecutive5xx":, + "maxEjectionPercent": , + "baseEjectionTime": "" } }, - "Listeners" : [ - { - "Port" : 0, - "Protocol" : "tcp", - "Services" : [ - { - "Name" : "", - "Namespace" : "", - "Partition" : "", - "Hosts" : [ - ".ingress.*" + "Listeners" : [ + { + "Port" : 0, + "Protocol" : "tcp", + "Services" : [ + { + "Name" : "", + "Namespace" : "", + "Partition" : "", + "Hosts" : [ + ".ingress.*" ], - "RequestHeaders" : { - "Add" : { - "RequestHeaderName" : "" + "RequestHeaders" : { + "Add" : { + "RequestHeaderName" : "" }, - "Set" : { - "RequestHeaderName" : "" + "Set" : { + "RequestHeaderName" : "" }, - "Remove" : [ - "" + "Remove" : [ + "" ] }, - "ResponseHeaders" : { - "Add" : { - "ResponseHeaderName" : "" + "ResponseHeaders" : { + "Add" : { + "ResponseHeaderName" : "" }, - "Set" : { - "ResponseHeaderName" : "" + "Set" : { + "ResponseHeaderName" : "" }, - "Remove" : [ - "" + "Remove" : [ + "" ] }, - "TLS" : { - "SDS" : { - "ClusterName" : "", - "CertResource" : "" + "TLS" : { + "SDS" : { + "ClusterName" : "", + "CertResource" : "" } }, - "MaxConnections" : , - "MaxPendingRequests" : , - "MaxConcurrentRequests" : , - "PassiveHealthCheck" : { - "interval" : 10, - "max_failures" : 5, - "enforcing_consecutive_5xx" : 100 - } + "MaxConnections" : , + "MaxPendingRequests" : , + "MaxConcurrentRequests" : , + "PassiveHealthCheck" : { + "interval": ", + "maxFailures": , + "enforcingConsecutive5xx":, + "maxEjectionPercent": , + "baseEjectionTime": "" } ], - "TLS" : { - "Enabled" : false, - "TLSMinVersion" : "TLSv1_2", - "TLSMaxVersion" : "", - "CipherSuites" : [ - "" + "TLS" : { + "Enabled" : false, + "TLSMinVersion" : "TLSv1_2", + "TLSMaxVersion" : "", + "CipherSuites" : [ + "" ], - "SDS" : { - "ClusterName" : "", - "CertResource" : "" + "SDS" : { + "ClusterName" : "", + "CertResource" : "" } } } ] -} +} ``` @@ -457,7 +476,7 @@ If unspecified, the ingress gateway is applied to the `default` namespace. You c #### Values -- Default: `default`, +- Default: `default`, - Data type: String ### `Partition` @@ -465,6 +484,7 @@ If unspecified, the ingress gateway is applied to the `default` namespace. You c Specifies the admin partition that the ingress gateway applies to. The value must match the partition in which the gateway is registered. Refer to [Admin partitions](/consul/docs/enterprise/admin-partitions) for additional information. If unspecified, the ingress gateway is applied to the `default` partition. You can override the partition when using the [`/config` API endpoint](/consul/api-docs/config) to register the configuration entry by specifying the `partition` query parameter. + #### Values - Default: `default @@ -472,7 +492,7 @@ If unspecified, the ingress gateway is applied to the `default` partition. You c ### `Meta` -Defines an arbitrary set of key-value pairs to store in the Consul KV. +Defines an arbitrary set of key-value pairs to store in the Consul KV. #### Values @@ -483,7 +503,7 @@ Defines an arbitrary set of key-value pairs to store in the Consul KV. ### `TLS` -Specifies the TLS configuration settings for the gateway. +Specifies the TLS configuration settings for the gateway. #### Values @@ -493,18 +513,18 @@ Specifies the TLS configuration settings for the gateway. - [`TLSMinVersion`](#tls-tlsminversion) - [`TLSMaxVersion`](#tls-tlsmaxversion) - [`CipherSuites`](#tls-ciphersuites) - - [`SDS`](#tls-sds) + - [`SDS`](#tls-sds) ### `TLS.Enabled` Enables and disables TLS for the configuration entry. Set to `true` to enable built-in TLS for every listener on the gateway. TLS is disabled by default. -When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `TLS.TLSMinVersion` @@ -514,7 +534,7 @@ Specifies the minimum TLS version supported for gateway listeners. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -549,21 +569,21 @@ Specifies a list of cipher suites that gateway listeners support when negotiatin ### `TSL.SDS` -Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. Consul applies the SDS configuration specified in this field as defaults for all listeners defined in the gateway. You can override the SDS settings for per listener or per service defined in the listener. Refer to the following configurations for additional information: - [`Listeners.TLS.SDS`](#listeners-tls-sds): Configures SDS settings for all services in the listener. -- [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. +- [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. #### Values - Default: None -- Data type: Map containing the following fields: - - `ClusterName` +- Data type: Map containing the following fields: + - `ClusterName` - `CertResource` -The following table describes how to configure SDS parameters. +The following table describes how to configure SDS parameters. | Parameter | Description | Data type | | --- | --- | --- | @@ -579,13 +599,13 @@ Specifies default configurations for connecting upstream services. - Default: None - The data type is a map containing the following parameters: - - [`MaxConnnections`](#defaults-maxconnections) + - [`MaxConnections`](#defaults-maxconnections) - [`MaxPendingRequests`](#defaults-maxpendingrequests) - - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests) + - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests) ### `Defaults.MaxConnections` -Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. #### Values @@ -594,7 +614,7 @@ Specifies the maximum number of HTTP/1.1 connections a service instance is allow ### `Defaults.MaxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). #### Values @@ -603,7 +623,7 @@ Specifies the maximum number of requests that are allowed to queue while waiting ### `Defaults.MaxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). +Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). #### Values @@ -612,7 +632,7 @@ Specifies the maximum number of concurrent HTTP/2 traffic requests that are allo ### `Defaults.PassiveHealthCheck` -Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. +Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. #### Values @@ -623,9 +643,11 @@ The following table describes the configurations for passive health checks: | Parameter | Description | Data type | Default | | --- | --- | --- | --- | -| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | -| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | -| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + | `Interval` | Specifies the time between checks. | string | `0s` | + | `MaxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | + | `EnforcingConsecutive5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `Listeners[]` @@ -642,17 +664,19 @@ Specifies a list of listeners in the mesh for the gateway. Listeners are uniquel ### `Listeners[].Port` -Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. +Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. + #### Values - Default: `0` - Data type: Integer + ### `Listeners[].Protocol` Specifies the protocol associated with the listener. To enable L7 network management capabilities, specify one of the following values: - `http` -- `http2` +- `http2` - `grpc` #### Values @@ -662,12 +686,12 @@ Specifies the protocol associated with the listener. To enable L7 network manage - `tcp` - `http` - - `http2` + - `http2` - `grpc` ### `Listeners[].Services[]` -Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `Namespace` field is required for Consul Enterprise datacenters. If the [`Listeners.Protocol`] field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. +Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `Namespace` field is required for Consul Enterprise datacenters. If the [`Listeners.Protocol`] field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. #### Values @@ -700,7 +724,7 @@ Specifies the name of a service to expose to the listener. You can specify servi ### `Listeners[].Services[].Namespace` -Specifies the namespace to use when resolving the location of the service. +Specifies the namespace to use when resolving the location of the service. #### Values @@ -709,7 +733,7 @@ Specifies the namespace to use when resolving the location of the service. ### `Listeners[].Services[].Partition` -Specifies the admin partition to use when resolving the location of the service. +Specifies the admin partition to use when resolving the location of the service. #### Values @@ -718,18 +742,18 @@ Specifies the admin partition to use when resolving the location of the service. ### `Listeners[].Services[].Hosts[]` -Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. +Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. -If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. +If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. -When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. +When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. You can use the wildcard in the left-most DNS label to match a set of hosts. For example, `*.example.com` is valid, but `example.*` and `*-suffix.example.com` are invalid. #### Values - Default: None -- Data type: List of strings or `*` +- Data type: List of strings or `*` ### `Listeners[].Services[].RequestHeaders` @@ -746,7 +770,7 @@ Specifies a set of HTTP-specific header modification rules applied to requests r The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -771,7 +795,7 @@ Specifies a set of HTTP-specific header modification rules applied to responses The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `Set` | Defines a set of key-value pairs to add to the response header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -783,18 +807,18 @@ For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the ### `Listeners[].Services[].TLS` -Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`TLS`](#tls) settings for the configuration entry. +Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`TLS`](#tls) settings for the configuration entry. #### Values - Default: None -- Data type: Map +- Data type: Map ### `Listeners[].Services[].TLS.SDS` -Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. +Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -This configuration overrides the main [`TLS.SDS`](#tls-sds) settings for configuration entry. If unspecified, Consul applies the top-level [`TLS.SDS`](#tls-sds) settings. +This configuration overrides the main [`TLS.SDS`](#tls-sds) settings for configuration entry. If unspecified, Consul applies the top-level [`TLS.SDS`](#tls-sds) settings. #### Values @@ -804,7 +828,7 @@ This configuration overrides the main [`TLS.SDS`](#tls-sds) settings for configu - `ClusterName` - `CertResource` -The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service#configure-static-sds-clusters) for usage information: +The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/tls-external-service#configure-static-sds-clusters) for usage information: | Parameter | Description | Data type | | `ClusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | @@ -812,7 +836,7 @@ The following table describes how to configure SDS parameters. Refer to [Configu ### `Listeners[].Services[].MaxConnections` -Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. When defined, this field overrides the [`Defaults.MaxConnections`](#defaults-maxconnections) configuration. @@ -823,9 +847,9 @@ When defined, this field overrides the [`Defaults.MaxConnections`](#defaults-max ### `Listeners[].Services.MaxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. When defined, this field overrides the value specified in the [`Defaults.MaxPendingRequests`](#defaults-maxpendingrequests) field of the configuration entry. +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. When defined, this field overrides the value specified in the [`Defaults.MaxPendingRequests`](#defaults-maxpendingrequests) field of the configuration entry. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. #### Values @@ -834,9 +858,9 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `Listeners[].Services[].MaxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. This field overrides the value set in the [`Defaults.MaxConcurrentRequests`](#defaults-maxconcurrentrequests) field of the configuration entry. +Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. This field overrides the value set in the [`Defaults.MaxConcurrentRequests`](#defaults-maxconcurrentrequests) field of the configuration entry. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. #### Values @@ -845,7 +869,7 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `Listeners[].Services[].PassiveHealthCheck` -Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. This field overrides the value set in the [`Defaults.PassiveHealthCheck`](#defaults-passivehealthcheck) field of the configuration entry. +Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. This field overrides the value set in the [`Defaults.PassiveHealthCheck`](#defaults-passivehealthcheck) field of the configuration entry. #### Values @@ -856,13 +880,15 @@ The following table describes the configurations for passive health checks: | Parameter | Description | Data type | Default | | --- | --- | --- | --- | -| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | -| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | -| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + | `Interval` | Specifies the time between checks. | string | `0s` | + | `MaxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | + | `EnforcingConsecutive5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `Listeners[].TLS` -Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`TLS`](#tls) settings for the configuration entry. +Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`TLS`](#tls) settings for the configuration entry. #### Values @@ -876,12 +902,12 @@ Specifies the TLS configuration for the listener. If unspecified, Consul applies ### `Listeners[].TLS.Enabled` -Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `Listeners[].TLS.TLSMinVersion` @@ -891,7 +917,7 @@ Specifies the minimum TLS version supported for the listener. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -921,14 +947,14 @@ Specifies a list of cipher suites that the listener supports when negotiating co #### Values -- Default: None +- Default: None - Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. ### `Listeners[].TLS.SDS` Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. -Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `Listeners.TLS.SDS` configuration per service by configuring the [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds) settings for each service. +Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `Listeners.TLS.SDS` configuration per service by configuring the [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds) settings for each service. #### Values @@ -949,9 +975,10 @@ The following table describes how to configure SDS parameters. Refer to [Configu ### `apiVersion` Kubernetes-only parameter that specifies the version of the Consul API that the configuration entry maps to Kubernetes configurations. The value must be `consul.hashicorp.com/v1alpha1`. + ### `kind` -Specifies the type of configuration entry to implement. Must be set to `IngressGatewa`. +Specifies the type of configuration entry to implement. Must be set to `IngressGateway`. #### Values @@ -961,7 +988,7 @@ Specifies the type of configuration entry to implement. Must be set to `IngressG ### `metadata` -Specifies metadata for the gateway. +Specifies metadata for the gateway. #### Values @@ -989,7 +1016,7 @@ If unspecified, the ingress gateway is applied to the `default` namespace. You c #### Values -- Default: `default`, +- Default: `default`, - Data type: String ### `spec` @@ -1007,7 +1034,7 @@ Kubernetes-only field that contains all of the configurations for ingress gatewa ### `spec.tls` -Specifies the TLS configuration settings for the gateway. +Specifies the TLS configuration settings for the gateway. #### Values @@ -1017,16 +1044,16 @@ Specifies the TLS configuration settings for the gateway. - [`tlsMinVersion`](#spec-tls-tlsminversion) - [`tlsMaxVersion`](#spec-tls-tlsmaxversion) - [`cipherSuites`](#spec-tls-tlsciphersuites) - - [`sds`](#spec-tls-sds) + - [`sds`](#spec-tls-sds) ### `spec.tls.enabled` Enables and disables TLS for the configuration entry. Set to `true` to enable built-in TLS for every listener on the gateway. TLS is disabled by default. -When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `spec.tls.tlsMinVersion` Specifies the minimum TLS version supported for gateway listeners. @@ -1035,16 +1062,18 @@ Specifies the minimum TLS version supported for gateway listeners. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` - `TLSv1_1` - `TLSv1_2` - `TLSv1_3` + ### `spec.tls.tlsMaxVersion` Specifies the maximum TLS version supported for gateway listeners. + #### Values - Default: Depends on the version of Envoy: @@ -1068,21 +1097,21 @@ Specifies a list of cipher suites that gateway listeners support when negotiatin ### `spec.tls.sds` -Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. Consul applies the SDS configuration specified in this field as defaults for all listeners defined in the gateway. You can override the SDS settings for per listener or per service defined in the listener. Refer to the following configurations for additional information: - [`spec.listeners.tls.sds`](#spec-listeners-tls-sds): Configures SDS settings for all services in the listener. -- [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. +- [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. #### Values - Default: None -- Data type: Map containing the following fields: - - [`clusterName`] +- Data type: Map containing the following fields: + - [`clusterName`] - [`certResource`] -The following table describes how to configure SDS parameters. +The following table describes how to configure SDS parameters. | Parameter | Description | Data type | | --- | --- | --- | @@ -1098,9 +1127,9 @@ Specifies default configurations for upstream connections. - Default: None - The data type is a map containing the following parameters: - - [`maxConnnections`](#spec-defaults-maxconnections) + - [`maxConnections`](#spec-defaults-maxconnections) - [`maxPendingRequests`](#spec-defaults-maxpendingrequests) - - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) + - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) ### `spec.defaults.maxConnections` @@ -1113,7 +1142,7 @@ Specifies the maximum number of HTTP/1.1 connections a service instance is allow ### `spec.defaults.maxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.Protocol`](#spec-listeners-protocol). +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.Protocol`](#spec-listeners-protocol). If unspecified, Consul uses Envoy's configuration. The default for Envoy is `1024`. @@ -1124,7 +1153,7 @@ If unspecified, Consul uses Envoy's configuration. The default for Envoy is `102 ### `spec.defaults.maxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol). +Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol). If unspecified, Consul uses Envoy's configuration. The default for Envoy is `1024`. @@ -1135,7 +1164,7 @@ If unspecified, Consul uses Envoy's configuration. The default for Envoy is `102 ### `spec.defaults.passiveHealthCheck` -Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. +Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. #### Values @@ -1146,9 +1175,11 @@ The following table describes the configurations for passive health checks: | Parameter | Description | Data type | Default | | --- | --- | --- | --- | -| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | -| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | -| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + | `Interval` | Specifies the time between checks. | string | `0s` | + | `MaxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | + | `EnforcingConsecutive5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `spec.listeners[]` @@ -1165,7 +1196,7 @@ Specifies a list of listeners in the mesh for the gateway. Listeners are uniquel ### `spec.listeners[].port` -Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. +Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. #### Values @@ -1177,7 +1208,7 @@ Specifies the port that the listener receives traffic on. The port is bound to t Specifies the protocol associated with the listener. To enable L7 network management capabilities, specify one of the following values: - `http` -- `http2` +- `http2` - `grpc` #### Values @@ -1187,12 +1218,12 @@ Specifies the protocol associated with the listener. To enable L7 network manage - `tcp` - `http` - - `http2` + - `http2` - `grpc` ### `spec.listeners[].services[]` -Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `namespace` field is required for Consul Enterprise datacenters. If the listener's [`protocol`](#spec-listeners-protocol) field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. +Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `namespace` field is required for Consul Enterprise datacenters. If the listener's [`protocol`](#spec-listeners-protocol) field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. #### Values @@ -1215,7 +1246,7 @@ Specifies a list of services that the listener exposes to services outside the m Specifies the name of a service to expose to the listener. You can specify services in the following ways: - Provide the name of a service registered in the Consul catalog. -- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. +- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. - Provide a `*` wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for additional information. #### Values @@ -1225,7 +1256,7 @@ Specifies the name of a service to expose to the listener. You can specify servi ### `spec.listeners[].services[].namespace` -Specifies the namespace to use when resolving the location of the service. +Specifies the namespace to use when resolving the location of the service. #### Values @@ -1234,7 +1265,7 @@ Specifies the namespace to use when resolving the location of the service. ### `spec.listeners[].services[].partition` -Specifies the admin partition to use when resolving the location of the service. +Specifies the admin partition to use when resolving the location of the service. #### Values @@ -1243,18 +1274,18 @@ Specifies the admin partition to use when resolving the location of the service. ### `spec.listeners[].services[].hosts[]` -Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. +Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. -If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. +If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. -When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. +When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. You can use the wildcard in the left-most DNS label to match a set of hosts. For example, `*.example.com` is valid, but `example.*` and `*-suffix.example.com` are invalid. #### Values - Default: None -- Data type: List of strings or `*` +- Data type: List of strings or `*` ### `spec.listeners[].services[].requestHeaders` @@ -1271,7 +1302,7 @@ Specifies a set of HTTP-specific header modification rules applied to requests r The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -1296,7 +1327,7 @@ Specifies a set of HTTP-specific header modification rules applied to responses The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -1308,18 +1339,18 @@ For `add` and `set`, if the service is configured to use Envoy as the proxy, the ### `spec.listeners[].services[].tls` -Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`tls`](#spec.tls) settings for the configuration entry. +Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`tls`](#spec.tls) settings for the configuration entry. #### Values - Default: None -- Data type: Map +- Data type: Map ### `spec.listeners[].services[].tls.sds` -Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. +Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -If unspecified, Consul applies the [`sds`](#spec-tls-sds) settings configured for the ingress gateway. If both are specified, this configuration overrides the settings for configuration entry. +If unspecified, Consul applies the [`sds`](#spec-tls-sds) settings configured for the ingress gateway. If both are specified, this configuration overrides the settings for configuration entry. #### Values @@ -1338,7 +1369,7 @@ The following table describes how to configure SDS parameters. Refer to [Serve c ### `spec-listeners[].services[].maxConnections` -Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. A value specified in this field overrides the [`maxConnections`](#spec-defaults-maxconnections) field specified in the `defaults` configuration. @@ -1349,9 +1380,9 @@ A value specified in this field overrides the [`maxConnections`](#spec-defaults- ### `spec.listeners[].services.maxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. A value specified in this field overrides the [`maxPendingRequests`](#spec-defaults-maxpendingrequests) field specified in the `defaults` configuration. +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. A value specified in this field overrides the [`maxPendingRequests`](#spec-defaults-maxpendingrequests) field specified in the `defaults` configuration. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. #### Values @@ -1360,9 +1391,9 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `spec.listeners[].services[].maxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. A value specified in this field overrides the [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) field specified in the `defaults` configuration entry. +Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. A value specified in this field overrides the [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) field specified in the `defaults` configuration entry. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. #### Values @@ -1371,7 +1402,7 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `spec.listeners[].services[].passiveHealthCheck` -Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. Health checks specified for services override the health checks defined in the [`spec.defaults.passiveHealthCheck`](#spec-defaults-passivehealthcheck) configuration. +Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. Health checks specified for services override the health checks defined in the [`spec.defaults.passiveHealthCheck`](#spec-defaults-passivehealthcheck) configuration. #### Values @@ -1382,13 +1413,15 @@ The following table describes the configurations for passive health checks: | Parameter | Description | Data type | Default | | --- | --- | --- | --- | -| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | -| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | -| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + | `Interval` | Specifies the time between checks. | string | `0s` | + | `MaxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | + | `EnforcingConsecutive5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `spec.listeners[].tls` -Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#spec-listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`tls`](#tls) settings for the configuration entry. +Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#spec-listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`tls`](#tls) settings for the configuration entry. #### Values @@ -1402,12 +1435,12 @@ Specifies the TLS configuration for the listener. If unspecified, Consul applies ### `spec.listeners[].tls.enabled` -Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `spec.listeners[].tls.tlsMinVersion` @@ -1417,7 +1450,7 @@ Specifies the minimum TLS version supported for the listener. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -1447,20 +1480,20 @@ Specifies a list of cipher suites that the listener supports when negotiating co #### Values -- Default: None +- Default: None - Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. ### `spec.listeners[].tls.sds` Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service) for additional information. -Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `spec.listeners[].tls.sds` configuration per service by configuring the [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds) settings for each service. +Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `spec.listeners[].tls.sds` configuration per service by configuring the [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds) settings for each service. #### Values - Default: None -- Data type: Map containing the following fields - - `clusterName` +- Data type: Map containing the following fields + - `clusterName` - `certResource` The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/ingress-gateways-tls-external-service#configure-static-sds-clusters) for usage information: @@ -1476,9 +1509,9 @@ The following table describes how to configure SDS parameters. Refer to [Configu ## Examples -Refer to the following examples for common ingress gateway configuration patterns: +Refer to the following examples for common ingress gateway configuration patterns: - [Define a TCP listener](#define-a-tcp-listener) -- [Use wildcards to define listeners](#use-wilcards-to-define-an-http-listener) +- [Use wildcards to define listeners](#use-wildcards-to-define-an-http-listener) - [HTTP listener with path-based routes](#http-listener-with-path-based-routes) ### Define a TCP listener @@ -1828,4 +1861,4 @@ spec: } ``` - \ No newline at end of file + diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index 68dbf9a67ecc..2e048e5b2725 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -10,15 +10,15 @@ This topic describes how to configure service defaults configuration entries. Th ## Configuration model -The following outline shows how to format the service splitter configuration entry. Click on a property name to view details about the configuration. +The following outline shows how to format the service defaults configuration entry. Click on a property name to view details about the configuration. - [`Kind`](#kind): string | required - [`Name`](#name): string | required -- [`Namespace`](#namespace): string -- [`Partition`](#partition): string +- [`Namespace`](#namespace): string +- [`Partition`](#partition): string - [`Meta`](#meta): map | no default - [`Protocol`](#protocol): string | default: `tcp` - [`BalanceInboundConnections`](#balanceinboundconnections): string | no default @@ -27,33 +27,38 @@ The following outline shows how to format the service splitter configuration ent - [`Overrides`](#upstreamconfig-overrides): map | no default - [`Name`](#upstreamconfig-overrides-name): string | no default - [`Namespace`](#upstreamconfig-overrides-namespace): string | no default + - [`Peer`](#upstreamconfig-overrides-peer): string | no default - [`Protocol`](#upstreamconfig-overrides-protocol): string | no default - [`ConnectTimeoutMs`](#upstreamconfig-overrides-connecttimeoutms): int | default: `5000` - [`MeshGateway`](#upstreamconfig-overrides-meshgateway): map | no default - [`mode`](#upstreamconfig-overrides-meshgateway): string | no default - - [`BalanceOutboundConnections`](#upstreamconfig-overrides-balanceoutboundconnections): string | no default - - [`Limits`](#upstreamconfig-overrides-limits): map | optional + - [`BalanceOutboundConnections`](#upstreamconfig-overrides-balanceoutboundconnections): string | no default + - [`Limits`](#upstreamconfig-overrides-limits): map | optional - [`MaxConnections`](#upstreamconfig-overrides-limits): integer | `0` - [`MaxPendingRequests`](#upstreamconfig-overrides-limits): integer | `0` - [`MaxConcurrentRequests`](#upstreamconfig-overrides-limits): integer | `0` - [`PassiveHealthCheck`](#upstreamconfig-overrides-passivehealthcheck): map | optional - [`Interval`](#upstreamconfig-overrides-passivehealthcheck): string | `0s` - [`MaxFailures`](#upstreamconfig-overrides-passivehealthcheck): integer | `0` - - [`EnforcingConsecutive5xx`](#upstreamconfig-overrides-passivehealthcheck): integer | `100` + - [`EnforcingConsecutive5xx`](#upstreamconfig-overrides-passivehealthcheck): integer | `0` + - [`MaxEjectionPercent`](#upstreamconfig-overrides-passivehealthcheck): integer | `0` + - [`BaseEjectionTime`](#upstreamconfig-overrides-passivehealthcheck): string | `30s` - [`Defaults`](#upstreamconfig-defaults): map | no default - [`Protocol`](#upstreamconfig-defaults-protocol): string | no default - [`ConnectTimeoutMs`](#upstreamconfig-defaults-connecttimeoutms): int | default: `5000` - [`MeshGateway`](#upstreamconfig-defaults-meshgateway): map | no default - [`mode`](#upstreamconfig-defaults-meshgateway): string | no default - - [`BalanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default - - [`Limits`](#upstreamconfig-defaults-limits): map | optional + - [`BalanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default + - [`Limits`](#upstreamconfig-defaults-limits): map | optional - [`MaxConnections`](#upstreamconfig-defaults-limits): integer | `0` - [`MaxPendingRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`MaxConcurrentRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`PassiveHealthCheck`](#upstreamconfig-defaults-passivehealthcheck): map | optional - [`Interval`](#upstreamconfig-defaults-passivehealthcheck): string | `0s` - [`MaxFailures`](#upstreamconfig-defaults-passivehealthcheck): integer | `0` - - [`EnforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | + - [`EnforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | `100` + - [`MaxEjectionPercent`](#upstreamconfig-defaults-passivehealthcheck): integer | `0` + - [`BaseEjectionTime`](#upstreamconfig-defaults-passivehealthcheck): string | `30s` - [`TransparentProxy`](#transparentproxy): map | no default - [`OutboundListenerPort`](#transparentproxy): integer | `15001` - [`DialedDirectly`](#transparentproxy ): boolean | `false` @@ -85,7 +90,7 @@ The following outline shows how to format the service splitter configuration ent - [`kind`](#kind): string | no default - [`metadata`](#metadata): map | no default - [`name`](#name): string | no default - - [`namespace`](#namespace): string | no default | + - [`namespace`](#namespace): string | no default | - [`spec`](#spec): map | no default - [`protocol`](#protocol): string | default: `tcp` - [`balanceInboundConnections`](#balanceinboundconnections): string | no default @@ -98,29 +103,33 @@ The following outline shows how to format the service splitter configuration ent - [`connectTimeoutMs`](#upstreamconfig-overrides-connecttimeoutms): int | default: `5000` - [`meshGateway`](#upstreamconfig-overrides-meshgateway): map | no default - [`mode`](#upstreamconfig-overrides-meshgateway): string | no default - - [`balanceOutboundConnections`](#overrides-balanceoutboundconnections): string | no default - - [`limits`](#upstreamconfig-overrides-limits): map | optional + - [`balanceOutboundConnections`](#overrides-balanceoutboundconnections): string | no default + - [`limits`](#upstreamconfig-overrides-limits): map | optional - [`maxConnections`](#upstreamconfig-overrides-limits): integer | `0` - [`maxPendingRequests`](#upstreamconfig-overrides-limits): integer | `0` - [`maxConcurrentRequests`](#upstreamconfig-overrides-limits): integer | `0` - [`passiveHealthCheck`](#upstreamconfig-overrides-passivehealthcheck): map | optional - [`interval`](#upstreamconfig-overrides-passivehealthcheck): string | `0s` - [`maxFailures`](#upstreamconfig-overrides-passivehealthcheck): integer | `0` - - [`mnforcingConsecutive5xx`](#upstreamconfig-overrides-passivehealthcheck): integer | `100` + - [`enforcingConsecutive5xx`](#upstreamconfig-overrides-passivehealthcheck): integer | `100` + - [`maxEjectionPercent`](#upstreamconfig-overrides-passivehealthcheck): integer | `10` + - [`baseEjectionTime`](#upstreamconfig-overrides-passivehealthcheck): string | `30s` - [`defaults`](#upstreamconfig-defaults): map | no default - [`protocol`](#upstreamconfig-defaults-protocol): string | no default - [`connectTimeoutMs`](#upstreamconfig-defaults-connecttimeoutms): int | default: `5000` - [`meshGateway`](#upstreamconfig-defaults-meshgateway): map | no default - [`mode`](#upstreamconfig-defaults-meshgateway): string | no default - - [`balanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default - - [`limits`](#upstreamconfig-defaults-limits): map | optional + - [`balanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default + - [`limits`](#upstreamconfig-defaults-limits): map | optional - [`maxConnections`](#upstreamconfig-defaults-limits): integer | `0` - [`maxPendingRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`maxConcurrentRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`passiveHealthCheck`](#upstreamconfig-defaults-passivehealthcheck): map | optional - [`interval`](#upstreamconfig-defaults-passivehealthcheck): string | `0s` - [`maxFailures`](#upstreamconfig-defaults-passivehealthcheck): integer | `0` - - [`enforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | + - [`enforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | `100` + - [`maxEjectionPercent`](#upstreamconfig-defaults-passivehealthcheck): integer | `10` + - [`baseEjectionTime`](#upstreamconfig-defaults-passivehealthcheck): string | `30s` - [`transparentProxy`](#transparentproxy): map | no default - [`outboundListenerPort`](#transparentproxy): integer | `15001` - [`dialedDirectly`](#transparentproxy): boolean | `false` @@ -150,7 +159,7 @@ The following outline shows how to format the service splitter configuration ent ## Complete configuration -When every field is defined, a service splitter configuration entry has the following form: +When every field is defined, a service-defaults configuration entry has the following form: @@ -185,6 +194,8 @@ UpstreamConfig = { Interval = "5s" MaxFailures = 5 EnforcingConsecutive5xx = 99 + MaxEjectionPercent = 10 + BaseEjectionTime = "30s" } } Defaults = { @@ -203,6 +214,8 @@ UpstreamConfig = { Interval = "1s" MaxFailures = 1 EnforcingConsecutive5xx = 89 + MaxEjectionPercent = 10 + BaseEjectionTime = "30s" } } } @@ -243,15 +256,15 @@ Expose = { ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceDefaults -metadata: +metadata: name: namespace: -spec: +spec: protocol: tcp - balanceInboundConnnections: exact_balance + balanceInboundConnections: exact_balance mode: transparent upstreamConfig: - overrides: + overrides: - name: namespace: protocol: @@ -259,28 +272,32 @@ spec: meshGateway: mode: balanceOutboundConnections: exact_balance - limits: + limits: maxConnections: 0 maxPendingRequests: 0 maxConcurrentRequests: 0 - passiveHealthCheck: - interval: 0s + passiveHealthCheck: + interval: "10s" maxFailures: 0 enforcingConsecutive5xx: 100 - defaults: + maxEjectionPercent: 10 + baseEjectionTime: "30s" + defaults: protocol: connectTimeoutMs: 5000 meshGateway: mode: balanceOutboundConnections: exact_balance - limits: + limits: maxConnections: 0 maxPendingRequests: 0 maxConcurrentRequests: 0 - passiveHealthCheck: - interval: 0s + passiveHealthCheck: + interval: "0s" maxFailures: 0 enforcingConsecutive5xx: 100 + maxEjectionPercent: 10 + baseEjectionTime: "30s" transparentProxy: outboundListenerPort: 15001 dialedDirectly: false @@ -293,9 +310,9 @@ spec: meshGateway: mode: externalSNI: - expose: + expose: checks: false - paths: + paths: - path: localPathPort: 0 listenerPort: 0 @@ -317,13 +334,14 @@ spec: }, "spec": { "protocol": "tcp", - "balanceInboundConnnections": "exact_balance", + "balanceInboundConnections": "exact_balance", "mode": "transparent", "upstreamConfig": { "overrides": [ { "name": "", "namespace": "", + "peer": "", "protocol": "", "connectTimeoutMs": 5000, "meshGateway": { @@ -338,8 +356,10 @@ spec: "passiveHealthCheck": { "interval": "0s", "maxFailures": 0, - "enforcingConsecutive5xx": 100 - } + "enforcingConsecutive5xx": 100, + "maxEjectionPercent": 10, + "baseEjectionTime": "30s", + }, } ], "defaults": { @@ -357,7 +377,9 @@ spec: "passiveHealthCheck": { "interval": "0s", "maxFailures": 0, - "enforcingConsecutive5xx": 100 + "enforcingConsecutive5xx": 100, + "maxEjectionPercent": 10, + "baseEjectionTime": "30s", } } }, @@ -398,7 +420,7 @@ spec: ## Specification -This section provides details about the fields you can configure in the service defaults configuration entry. +This section provides details about the fields you can configure in the service defaults configuration entry. @@ -415,7 +437,7 @@ Specifies the configuration entry type. ### `Name` -Specifies the name of the service you are setting the defaults for. +Specifies the name of the service you are setting the defaults for. #### Values @@ -425,7 +447,7 @@ Specifies the name of the service you are setting the defaults for. ### `Namespace` -Specifies the Consul namespace that the configuration entry applies to. +Specifies the Consul namespace that the configuration entry applies to. #### Values @@ -443,7 +465,7 @@ Specifies the name of the name of the Consul admin partition that the configurat ### `Meta` -Specifies a set of custom key-value pairs to add to the [Consul KV](/consul/docs/dynamic-app-config/kv) store. +Specifies a set of custom key-value pairs to add to the [Consul KV](/consul/docs/dynamic-app-config/kv) store. #### Values @@ -457,26 +479,26 @@ Specifies a set of custom key-value pairs to add to the [Consul KV](/consul/docs Specifies the default protocol for the service. In service mesh use cases, the `protocol` configuration is required to enable the following features and components: - [observability](/consul/docs/connect/observability) -- [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter) -- [service router configuration entry](/consul/docs/connect/config-entries/service-router) -- [L7 intentions](/consul/docs/connect/intentions/index#l7-traffic-intentions) +- [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter) +- [service router configuration entry](/consul/docs/connect/config-entries/service-router) +- [L7 intentions](/consul/docs/connect/intentions#l7-traffic-intentions) -You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration. +You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration. #### Values - Default: `tcp` -- You can speciyf one of the following string values: +- You can specify one of the following string values: - `tcp` (default) - - `http` + - `http` - `http2` - - `grpc` + - `grpc` Refer to [Set the default protocol](#set-the-default-protocol) for an example configuration. ### `BalanceInboundConnections` -Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -485,17 +507,17 @@ Specifies the strategy for allocating inbound connections to the service across ### `Mode` -Specifies a mode for how the service directs inbound and outbound traffic. +Specifies a mode for how the service directs inbound and outbound traffic. - Default: none - You can specify the following string values: - - `direct`: The proxy's listeners must be dialed directly by the local application and other proxies. - - `transparent`: The service captures inbound and outbound traffic and redirects it through the proxy. The mode does not enable the traffic redirection. It instructs Consul to configure Envoy as if traffic is already being redirected. + - `direct`: The proxy's listeners must be dialed directly by the local application and other proxies. + - `transparent`: The service captures inbound and outbound traffic and redirects it through the proxy. The mode does not enable the traffic redirection. It instructs Consul to configure Envoy as if traffic is already being redirected. ### `UpstreamConfig` -Controls default upstream connection settings and custom overrides for individual upstream services. If your network contains federated datacenters, individual upstream configurations apply to all pairs of source and upstream destination services in the network. Refer to the following fields for details: +Controls default upstream connection settings and custom overrides for individual upstream services. If your network contains federated datacenters, individual upstream configurations apply to all pairs of source and upstream destination services in the network. Refer to the following fields for details: - [`UpstreamConfig.Overrides`](#upstreamconfig-overrides) - [`UpstreamConfig.Defaults`](#upstreamconfig-defaults) @@ -507,7 +529,7 @@ Controls default upstream connection settings and custom overrides for individua ### `UpstreamConfig.Overrides[]` -Specifies options that override the [default upstream configurations](#upstreamconfig-defaults) for individual upstreams. +Specifies options that override the [default upstream configurations](#upstreamconfig-defaults) for individual upstreams. #### Values @@ -533,7 +555,7 @@ Specifies the namespace containing the upstream service that the configuration a - Data type: string ### `UpstreamConfig.Overrides[].Protocol` -Specifies the protocol to use for requests to the upstream listener. +Specifies the protocol to use for requests to the upstream listener. We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/l7-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. @@ -545,7 +567,7 @@ We recommend configuring the protocol in the main [`Protocol`](#protocol) field ### `UpstreamConfig.Overrides[].ConnectTimeoutMs` -Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. +Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. We recommend configuring the upstream timeout in the [`connection_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `service-resolver` configuration entry for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `service-defaults` upstream configuration limits L7 management functionality. @@ -556,31 +578,31 @@ We recommend configuring the upstream timeout in the [`connection_timeout`](/con ### `UpstreamConfig.Overrides[].MeshGateway` -Map that contains the default mesh gateway `mode` field for the upstream. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. +Map that contains the default mesh gateway `mode` field for the upstream. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. #### Values - Default: `none` - You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. - - `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. - - `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. + - `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. + - `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. ### `UpstreamConfig.Overrides[].BalanceOutboundConnections` -Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. +Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. #### Values -The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. - Default: none - Data type: string ### `UpstreamConfig.Overrides[].Limits` -Map that specifies a set of limits to apply to when connecting to individual upstream services. +Map that specifies a set of limits to apply to when connecting to individual upstream services. #### Values @@ -596,7 +618,7 @@ Refer to the [upstream configuration example](#upstream-configuration) for addit ### `UpstreamConfig.Overrides[].PassiveHealthCheck` -Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. +Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. #### Values @@ -606,11 +628,13 @@ The following table describes passive health check parameters you can configure: | --- | --- | --- | --- | | `Interval` | Specifies the time between checks. | string | `0s` | | `MaxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | -| `EnforcingConsecutive5xx ` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | +| `EnforcingConsecutive5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `UpstreamConfig.Defaults` -Specifies configurations that set default upstream settings. For information about overriding the default configurations for in for individual upstreams, refer to [`UpstreamConfig.Overrides`](#upstreamconfig-overrides). +Specifies configurations that set default upstream settings. For information about overriding the default configurations for in for individual upstreams, refer to [`UpstreamConfig.Overrides`](#upstreamconfig-overrides). #### Values @@ -619,7 +643,7 @@ Specifies configurations that set default upstream settings. For information abo ### `UpstreamConfig.Defaults.Protocol` -Specifies default protocol for upstream listeners. +Specifies default protocol for upstream listeners. We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/l7-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. @@ -628,7 +652,7 @@ We recommend configuring the protocol in the main [`Protocol`](#protocol) field ### `UpstreamConfig.Defaults.ConnectTimeoutMs` -Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. +Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. For non-Kubernetes environments, we recommend configuring the upstream timeout in the [`connection_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `service-resolver` configuration entry for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `service-defaults` upstream configuration limits L7 management functionality. @@ -637,17 +661,17 @@ For non-Kubernetes environments, we recommend configuring the upstream timeout i ### `UpstreamConfig.Defaults.MeshGateway` -Specifies the default mesh gateway `mode` field for all upstreams. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. +Specifies the default mesh gateway `mode` field for all upstreams. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. ### `UpstreamConfig.Defaults.BalanceOutboundConnections` -Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. - Default: none - Data type: string @@ -671,6 +695,8 @@ Map that specifies a set of rules that enable Consul to remove hosts from the up | `Interval` | Specifies the time between checks. | string | `0s` | | `MaxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | | `EnforcingConsecutive5xx ` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `TransparentProxy` @@ -685,7 +711,7 @@ You can configure the following parameters in the `TransparentProxy` block: ### `EnvoyExtensions` -List of extensions to modify Envoy proxy configuration. Refer to [Envoy Extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information. +List of extensions to modify Envoy proxy configuration. Refer to [Envoy Extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information. You can configure the following parameters in the `EnvoyExtensions` block: @@ -697,7 +723,7 @@ You can configure the following parameters in the `EnvoyExtensions` block: ### `Destination[]` -Configures the destination for service traffic through terminating gateways. Refer to [Terminating Gateway](/consul/docs/connect/gateways/terminating-gateway) for additional information. +Configures the destination for service traffic through terminating gateways. Refer to [Terminating Gateway](/consul/docs/connect/gateways/terminating-gateway) for additional information. You can configure the following parameters in the `Destination` block: @@ -720,7 +746,7 @@ Specifies the number of milliseconds allowed for establishing connections to the - Default: `5000` - Data type: integer -### `LocalRequestTimeoutMs` +### `LocalRequestTimeoutMs` Specifies the timeout for HTTP requests to the local application instance. Applies to HTTP-based protocols only. If not specified, inherits the Envoy default for route timeouts. @@ -729,22 +755,22 @@ Specifies the timeout for HTTP requests to the local application instance. Appli ### `MeshGateway` -Specifies the default mesh gateway `mode` field for the service. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. +Specifies the default mesh gateway `mode` field for the service. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. -### `ExternalSNI` +### `ExternalSNI` -Specifies the TLS server name indication (SNI) when federating with an external system. +Specifies the TLS server name indication (SNI) when federating with an external system. - Default: none - Data type: string -### `Expose` +### `Expose` Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on localhost only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for additional information and example configurations. @@ -753,7 +779,7 @@ Specifies default configurations for exposing HTTP paths through Envoy. Exposing ### `Expose.Checks` -Exposes all HTTP and gRPC checks registered with the agent if set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise_addr). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. +Exposes all HTTP and gRPC checks registered with the agent if set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise_addr). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. We recommend enabling the `Checks` configuration when a Consul client cannot reach registered services over localhost, such as when Consul agents run in their own pods in Kubernetes. @@ -775,9 +801,9 @@ Specifies a list of configuration maps that define paths to expose through Envoy -### `apiVersion` +### `apiVersion` -Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`. The `apiVersion` field is not supported for non-Kubernetes deployments. +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`. The `apiVersion` field is not supported for non-Kubernetes deployments. - Default: none - This field is required. @@ -792,7 +818,7 @@ Specifies the configuration entry type. Must be ` ServiceDefaults`. ### `metadata` -Map that contains the service name, namespace, and admin partition that the configuration entry applies to. +Map that contains the service name, namespace, and admin partition that the configuration entry applies to. #### Values @@ -802,10 +828,10 @@ Map that contains the service name, namespace, and admin partition that the conf - [`namespace`](#namespace) - [`partition`](#partition) - -### `metadata.name` -Specifies the name of the service you are setting the defaults for. +### `metadata.name` + +Specifies the name of the service you are setting the defaults for. #### Values @@ -822,33 +848,33 @@ Specifies the Consul namespace that the configuration entry applies to. Refer to ### `spec` -Map that contains the details about the `ServiceDefaults` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children. +Map that contains the details about the `ServiceDefaults` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children. ### `spec.protocol` Specifies the default protocol for the service. In service service mesh use cases, the `protocol` configuration is required to enable the following features and components: - [observability](/consul/docs/connect/observability) -- [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter) -- [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router) -- [L7 intentions](/consul/docs/connect/intentions/index#l7-traffic-intentions) +- [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter) +- [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router) +- [L7 intentions](/consul/docs/connect/intentions#l7-traffic-intentions) -You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration. +You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration. #### Values - Default: `tcp` - You can specify one of the following string values: - - `tcp` - - `http` + - `tcp` + - `http` - `http2` - - `grpc` + - `grpc` Refer to [Set the default protocol](#set-the-default-protocol) for an example configuration. ### `spec.balanceInboundConnections` -Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -857,7 +883,7 @@ Specifies the strategy for allocating inbound connections to the service across ### `spec.mode` -Specifies a mode for how the service directs inbound and outbound traffic. +Specifies a mode for how the service directs inbound and outbound traffic. #### Values @@ -865,12 +891,12 @@ Specifies a mode for how the service directs inbound and outbound traffic. - Required: optional - You can specified the following string values: -- `direct`: The proxy's listeners must be dialed directly by the local application and other proxies. -- `transparent`: The service captures inbound and outbound traffic and redirects it through the proxy. The mode does not enable the traffic redirection. It instructs Consul to configure Envoy as if traffic is already being redirected. +- `direct`: The proxy's listeners must be dialed directly by the local application and other proxies. +- `transparent`: The service captures inbound and outbound traffic and redirects it through the proxy. The mode does not enable the traffic redirection. It instructs Consul to configure Envoy as if traffic is already being redirected. ### `spec.upstreamConfig` -Specifies a map that controls default upstream connection settings and custom overrides for individual upstream services. If your network contains federated datacenters, individual upstream configurations apply to all pairs of source and upstream destination services in the network. +Specifies a map that controls default upstream connection settings and custom overrides for individual upstream services. If your network contains federated datacenters, individual upstream configurations apply to all pairs of source and upstream destination services in the network. #### Values @@ -881,7 +907,7 @@ Specifies a map that controls default upstream connection settings and custom ov ### `spec.upstreamConfig.overrides[]` -Specifies options that override the [default upstream configurations](#spec-upstreamconfig-defaults) for individual upstreams. +Specifies options that override the [default upstream configurations](#spec-upstreamconfig-defaults) for individual upstreams. #### Values @@ -918,7 +944,7 @@ Specifies the protocol to use for requests to the upstream listener. We recommen ### `spec.upstreamConfig.overrides[].connectTimeoutMs` -Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. +Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. @@ -929,19 +955,19 @@ We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/ ### `spec.upstreamConfig.overrides[].meshGateway.mode` -Map that contains the default mesh gateway `mode` field for the upstream. Refer to [Connect Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) in the mesh gateway documentation for additional information. +Map that contains the default mesh gateway `mode` field for the upstream. Refer to [Connect Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) in the mesh gateway documentation for additional information. #### Values You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. ### `spec.upstreamConfig.overrides[].balanceInboundConnections` -Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -950,7 +976,7 @@ Sets the strategy for allocating outbound connections from the upstream across E ### `spec.upstreamConfig.overrides[].limits` -Map that specifies a set of limits to apply to when connecting to individual upstream services. +Map that specifies a set of limits to apply to when connecting to individual upstream services. #### Values @@ -964,7 +990,7 @@ The following table describes limits you can configure: ### `spec.upstreamConfig.overrides[].passiveHealthCheck` -Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. +Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. #### Values @@ -975,10 +1001,12 @@ The following table describes passive health check parameters you can configure: | `interval` | Specifies the time between checks. | string | `0s` | | `maxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | | `enforcingConsecutive5xx ` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `maxEjectionPercent` | The maximum % of an upstream cluster that can be ejected due to outlier detection. Defaults to 10% but will eject at least one host regardless of the value. | integer | `10` | + | `baseEjectionTime` | The base time that a host is ejected for. The real time is equal to the base time multiplied by the number of times the host has been ejected and is capped by max_ejection_time (Default 300s). Defaults to 30000ms or 30s. | string | `30s` | ### `spec.upstreamConfig.defaults` -Map of configurations that set default upstream configurations for the service. For information about overriding the default configurations for in for individual upstreams, refer to [`spec.upstreamConfig.overrides`](#spec-upstreamconfig-overrides). +Map of configurations that set default upstream configurations for the service. For information about overriding the default configurations for in for individual upstreams, refer to [`spec.upstreamConfig.overrides`](#spec-upstreamconfig-overrides). #### Values @@ -996,7 +1024,7 @@ Specifies default protocol for upstream listeners. We recommend configuring the ### `spec.upstreamConfig.default.connectTimeoutMs` -Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. +Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for upstream destination services. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. @@ -1007,19 +1035,19 @@ We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/ ### `spec.upstreamConfig.defaults.meshGateway.mode` -Specifies the default mesh gateway `mode` field for all upstreams. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. +Specifies the default mesh gateway `mode` field for all upstreams. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. #### Values You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. ### `spec.upstreamConfig.defaults.balanceInboundConnections` -Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -1028,7 +1056,7 @@ Sets the strategy for allocating outbound connections from upstreams across Envo ### `spec.upstreamConfig.defaults.limits` -Map that specifies a set of limits to apply to when connecting upstream services. +Map that specifies a set of limits to apply to when connecting upstream services. #### Values @@ -1041,7 +1069,7 @@ The following table describes limits you can configure: | `maxConcurrentRequests` | Specifies the maximum number of concurrent requests. Define this limit for HTTP/2 traffic. An L7 protocol must be defined in the [`protocol`](#protocol) field for this limit to take effect. | integer | `0` | ### `spec.upstreamConfig.defaults.passiveHealthCheck` -Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. +Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. #### Values @@ -1052,10 +1080,12 @@ The following table describes the health check parameters you can configure: | `interval` | Specifies the time between checks. | string | `0s` | | `maxFailures` | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | `0` | | `enforcingConsecutive5xx ` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | integer | `100` | + | `MaxEjectionPercent` | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | `10` | + | `BaseEjectionTime` | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the `BaseEjectionTime` multiplied by the number of times the host has been ejected. | string | `30s` | ### `spec.transparentProxy` -Map of configurations specific to proxies in transparent mode. Refer to [Transparent Proxy](/consul/docs/connect/transparent-proxy) for additional information. +Map of configurations specific to proxies in transparent mode. Refer to [Transparent Proxy](/consul/docs/connect/transparent-proxy) for additional information. #### Values @@ -1082,7 +1112,7 @@ You can configure the following parameters in the `EnvoyExtensions` block: ### `spec.destination` -Map of configurations that specify one or more destinations for service traffic routed through terminating gateways. Refer to [Terminating Gateway](/consul/docs/connect/gateways/terminating-gateway) for additional information. +Map of configurations that specify one or more destinations for service traffic routed through terminating gateways. Refer to [Terminating Gateway](/consul/docs/connect/gateways/terminating-gateway) for additional information. #### Values @@ -1111,7 +1141,7 @@ Specifies the number of milliseconds allowed for establishing connections to the - Default: `5000` - Data type: integer -### `spec.localRequestTimeoutMs` +### `spec.localRequestTimeoutMs` Specifies the timeout for HTTP requests to the local application instance. Applies to HTTP-based protocols only. If not specified, inherits the Envoy default for route timeouts. @@ -1120,20 +1150,20 @@ Specifies the timeout for HTTP requests to the local application instance. Appli - Default of `15s` is inherited from Envoy - Data type: string -### `spec.meshGateway.mode` -Specifies the default mesh gateway `mode` field for the service. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. +### `spec.meshGateway.mode` +Specifies the default mesh gateway `mode` field for the service. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. #### Values You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. -### `spec.externalSNI` +### `spec.externalSNI` -Specifies the TLS server name indication (SNI) when federating with an external system. +Specifies the TLS server name indication (SNI) when federating with an external system. #### Values @@ -1142,7 +1172,7 @@ Specifies the TLS server name indication (SNI) when federating with an external ### `spec.expose` -Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on localhost only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for additional information and example configurations. +Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on `localhost` only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for additional information and example configurations. #### Values @@ -1151,7 +1181,7 @@ Specifies default configurations for exposing HTTP paths through Envoy. Exposing ### `spec.expose.checks` -Exposes all HTTP and gRPC checks registered with the agent if set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise_addr). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. +Exposes all HTTP and gRPC checks registered with the agent if set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise_addr). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. We recommend enabling the `Checks` configuration when a Consul client cannot reach registered services over localhost, such as when Consul agents run in their own pods in Kubernetes. @@ -1162,7 +1192,7 @@ We recommend enabling the `Checks` configuration when a Consul client cannot rea ### `spec.expose.paths[]` -Specifies an list of maps that define paths to expose through Envoy when `spec.expose.checks` is set to `true`. +Specifies an list of maps that define paths to expose through Envoy when `spec.expose.checks` is set to `true`. #### Values @@ -1222,7 +1252,7 @@ You can also set the global default protocol for all proxies in the [`proxy-defa -The following example sets default connection limits and mesh gateway mode across all upstreams of the `dashboard` service. +The following example sets default connection limits and mesh gateway mode across all upstreams of the `dashboard` service. It also overrides the mesh gateway mode used when dialing its `counting` upstream service. @@ -1589,11 +1619,11 @@ represents a location outside the Consul cluster. Services can dial destinations { name: 'Peer', type: 'string: ""', - description: + description: `The name of the peer containing the upstream. Do not use a wildcard specifier ( \`*\`).

- If the \`peer\` field is not set in any \`Overrides\` configuration, then Consul applies overrides to peered services with the same [\`name\`](/consul/docs/connect/config-entries/service-defaults#name). - This maintains backward compatibility with Consul 1.14.0. - If the \`peer\` field is specified in any override, then backward compatibility with Consul 1.14.0 is disabled. + If the \`peer\` field is not set in any \`Overrides\` configuration, then Consul applies overrides to peered services with the same [\`name\`](/consul/docs/connect/config-entries/service-defaults#name). + This maintains backward compatibility with Consul 1.14.0. + If the \`peer\` field is specified in any override, then backward compatibility with Consul 1.14.0 is disabled. As a result, each peered service must have a separate override configuration if desired.` , }, { @@ -1608,7 +1638,7 @@ represents a location outside the Consul cluster. Services can dial destinations proxy upstream config will not fully enable some [L7 features](/consul/docs/connect/l7-traffic). It is supported here for backwards compatibility with Consul versions prior to 1.6.0. - In addition, the \`protocol\` of a peered service cannot be overriden. Any value in + In addition, the \`protocol\` of a peered service cannot be overridden. Any value in this field is ignored for peered services. `, }, @@ -1728,6 +1758,20 @@ represents a location outside the Consul cluster. Services can dial destinations after a passive health check detects an outlier status through consecutive 5xx.`, }, }, + { + name: 'MaxEjectionPercent', + type: 'int: 10', + description: `Measured in percent (%), the maximum percentage of hosts that can be ejected + from a upstream cluster due to passive health check failures. If not specified, inherits + Envoy's default of 10% or at least one host.`, + }, + { + name: 'BaseEjectionTime', + type: 'duration: 30s', + description: `The base time that a host is ejected for. The real time is equal to the base + time multiplied by the number of times the host has been ejected and is capped by + max_ejection_time (Default 300s). If not specified, inherits Envoy's default value of 30s.`, + }, ], }, ], @@ -1879,6 +1923,20 @@ represents a location outside the Consul cluster. Services can dial destinations after a passive health check detects an outlier status through consecutive 5xx.`, }, }, + { + name: 'MaxEjectionPercent', + type: 'int: 10', + description: `Measured in percent (%), the maximum percentage of hosts that can be ejected + from a upstream cluster due to passive health check failures. If not specified, inherits + Envoy's default of 10% or at least one host.`, + }, + { + name: 'BaseEjectionTime', + type: 'duration: 30s', + description: `The base time that a host is ejected for. The real time is equal to the base + time multiplied by the number of times the host has been ejected and is capped by + max_ejection_time (Default 300s). If not specified, inherits Envoy's default value of 30s.`, + }, ], }, ],