715 lines
27 KiB
Plaintext
715 lines
27 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Configuration Entry Kind: Service Defaults'
|
|
description: >-
|
|
The service-defaults config entry kind controls default global values for a
|
|
service, such as its protocol.
|
|
---
|
|
|
|
# Service Defaults
|
|
|
|
-> **v1.8.4+:** On Kubernetes, the `ServiceDefaults` custom resource is supported in Consul versions 1.8.4+.<br />
|
|
**v1.5.0+:** On other platforms, this config entry is supported in Consul versions 1.5.0+.
|
|
|
|
The `service-defaults` config entry kind (`ServiceDefaults` on Kubernetes) controls default global values for a
|
|
service, such as its protocol.
|
|
|
|
## Sample Config Entries
|
|
|
|
### Default protocol
|
|
|
|
-> **NOTE**: The default protocol can also be configured globally for all proxies
|
|
using the [proxy defaults](/docs/connect/config-entries/proxy-defaults#default-protocol)
|
|
config entry. However, if the protocol value is specified in a service defaults
|
|
config entry for a given service, that value will take precedence over the
|
|
globally configured value from proxy defaults.
|
|
|
|
Set the default protocol for a service in the default namespace to HTTP:
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "service-defaults"
|
|
Name = "web"
|
|
Namespace = "default"
|
|
Protocol = "http"
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: ServiceDefaults
|
|
metadata:
|
|
name: web
|
|
spec:
|
|
protocol: http
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "web",
|
|
"Namespace": "default",
|
|
"Protocol": "http"
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
### Upstream configuration
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
Set default connection limits and mesh gateway mode across all upstreams
|
|
of "counting", and also override the mesh gateway mode used when dialing
|
|
the "dashboard" service.
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "service-defaults"
|
|
Name = "counting"
|
|
|
|
UpstreamConfig = {
|
|
Defaults = {
|
|
MeshGateway = {
|
|
Mode = "local"
|
|
}
|
|
Limits = {
|
|
MaxConnections = 512
|
|
MaxPendingRequests = 512
|
|
MaxConcurrentRequests = 512
|
|
}
|
|
}
|
|
|
|
Overrides = [
|
|
{
|
|
Name = "dashboard"
|
|
MeshGateway = {
|
|
Mode = "remote"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: ServiceDefaults
|
|
metadata:
|
|
name: counting
|
|
spec:
|
|
upstreamConfig:
|
|
defaults:
|
|
meshGateway:
|
|
mode: local
|
|
limits:
|
|
maxConnections: 512
|
|
maxPendingRequests: 512
|
|
maxConcurrentRequests: 512
|
|
overrides:
|
|
- name: dashboard
|
|
meshGateway:
|
|
mode: remote
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "counting",
|
|
"UpstreamConfig": {
|
|
"Defaults": {
|
|
"MeshGateway": {
|
|
"Mode": "local"
|
|
},
|
|
"Limits": {
|
|
"MaxConnections": 512,
|
|
"MaxPendingRequests": 512,
|
|
"MaxConcurrentRequests": 512
|
|
}
|
|
},
|
|
"Overrides": [
|
|
{
|
|
"Name": "dashboard",
|
|
"MeshGateway": {
|
|
"Mode": "remote"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
Set default connection limits and mesh gateway mode across all upstreams
|
|
of "counting" and also override the mesh gateway mode used when dialing
|
|
the "dashboard" service in the "frontend" namespace.
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "service-defaults"
|
|
Name = "counting"
|
|
Namespace = "product"
|
|
|
|
UpstreamConfig = {
|
|
Defaults = {
|
|
MeshGateway = {
|
|
Mode = "local"
|
|
}
|
|
Limits = {
|
|
MaxConnections = 512
|
|
MaxPendingRequests = 512
|
|
MaxConcurrentRequests = 512
|
|
}
|
|
}
|
|
|
|
Overrides = [
|
|
{
|
|
Name = "dashboard"
|
|
Namespace = "frontend"
|
|
MeshGateway = {
|
|
Mode = "remote"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: ServiceDefaults
|
|
metadata:
|
|
name: counting
|
|
namespace: product
|
|
spec:
|
|
upstreamConfig:
|
|
defaults:
|
|
meshGateway:
|
|
mode: local
|
|
limits:
|
|
maxConnections: 512
|
|
maxPendingRequests: 512
|
|
maxConcurrentRequests: 512
|
|
overrides:
|
|
- name: dashboard
|
|
namespace: frontend
|
|
meshGateway:
|
|
mode: remote
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "counting",
|
|
"Namespace": "product",
|
|
"UpstreamConfig": {
|
|
"Defaults": {
|
|
"MeshGateway": {
|
|
"Mode": "local"
|
|
},
|
|
"Limits": {
|
|
"MaxConnections": 512,
|
|
"MaxPendingRequests": 512,
|
|
"MaxConcurrentRequests": 512
|
|
}
|
|
},
|
|
"Overrides": [
|
|
{
|
|
"Name": "dashboard",
|
|
"Namespace": "frontend",
|
|
"MeshGateway": {
|
|
"Mode": "remote"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Available Fields
|
|
|
|
<ConfigEntryReference
|
|
keys={[
|
|
{
|
|
name: 'apiVersion',
|
|
description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
|
|
hcl: false,
|
|
},
|
|
{
|
|
name: 'Kind',
|
|
description: {
|
|
hcl: 'Must be set to `service-defaults`',
|
|
yaml: 'Must be set to `ServiceDefaults`',
|
|
},
|
|
},
|
|
{
|
|
name: 'Name',
|
|
description: 'Set to the name of the service being configured.',
|
|
type: 'string: <required>',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Namespace',
|
|
type: `string: "default"`,
|
|
enterprise: true,
|
|
description: 'Specifies the namespace the config entry will apply to.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Partition',
|
|
type: `string: "default"`,
|
|
enterprise: true,
|
|
description:
|
|
'Specifies the name of the admin partition in which the configuration entry applies. Refer to the [Admin Partitions documentation](/docs/enterprise/admin-partitions) for additional information.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Meta',
|
|
type: 'map<string|string>: nil',
|
|
description:
|
|
'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'metadata',
|
|
children: [
|
|
{
|
|
name: 'name',
|
|
description: 'Set to the name of the service being configured.',
|
|
},
|
|
{
|
|
name: 'namespace',
|
|
description:
|
|
'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
|
|
},
|
|
{
|
|
name: 'partition',
|
|
enterprise: true,
|
|
description:
|
|
'Specifies the admin partition in which the configuration will apply. The current partition is used if unspecified. Refer to the [Admin Partitions documentation](/docs/enterprise/admin-partitions) for details. The partitions parameter is not supported in Consul OSS.',
|
|
},
|
|
],
|
|
hcl: false,
|
|
},
|
|
{
|
|
name: 'Protocol',
|
|
type: `string: "tcp"`,
|
|
description: `Sets the protocol of the service. This is used
|
|
by Connect proxies for things like observability features and to unlock usage
|
|
of the [\`service-splitter\`](/docs/connect/config-entries/service-splitter) and
|
|
[\`service-router\`](/docs/connect/config-entries/service-router) config entries
|
|
for a service. It also unlocks the ability to define L7 intentions via
|
|
[\`service-intentions\`](/docs/connect/config-entries/service-intentions).
|
|
Supported values are one of \`tcp\`, \`http\`, \`http2\`, or \`grpc\`.`,
|
|
},
|
|
{
|
|
name: 'Mode',
|
|
type: `string: ""`,
|
|
description: `One of \`direct\` or \`transparent\`.
|
|
\`transparent\` represents that inbound and outbound application traffic is being
|
|
captured and redirected through the proxy. This mode does not enable the traffic redirection
|
|
itself. Instead it signals Consul to configure Envoy as if traffic is already being redirected.
|
|
\`direct\` represents that the proxy's listeners must be dialed directly by the local
|
|
application and other proxies.
|
|
Added in v1.10.0.`,
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'UpstreamConfig',
|
|
type: 'UpstreamConfiguration: <optional>',
|
|
description: `Controls default configuration settings that apply across all upstreams, and per-upstream
|
|
configuration overrides. Note that per-upstream configuration applies across all federated datacenters
|
|
to the pairing of source and upstream destination services.
|
|
Added in v1.10.0.`,
|
|
children: [
|
|
{
|
|
name: 'Overrides',
|
|
type: 'array<UpstreamConfig>: []',
|
|
description: `A list of optional overrides for per-upstream configuration.`,
|
|
children: [
|
|
{
|
|
name: 'Name',
|
|
type: 'string: ""',
|
|
description:
|
|
'The upstream name to apply the configuration to. This should not be set to the wildcard specifier `*`.',
|
|
},
|
|
{
|
|
name: 'Namespace',
|
|
type: 'string: ""',
|
|
description:
|
|
'The namespace of the upstream. This should not be set to the wildcard specifier `*`.',
|
|
},
|
|
{
|
|
name: 'Protocol',
|
|
type: 'string: ""',
|
|
description: `The protocol for the upstream listener.<br><br>
|
|
NOTE: The protocol of a service should ideally be configured via the
|
|
[\`protocol\`](/docs/connect/config-entries/service-defaults#protocol)
|
|
field of a
|
|
[\`service-defaults\`](/docs/connect/config-entries/service-defaults)
|
|
config entry for the upstream destination service. Configuring it in a
|
|
proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
},
|
|
{
|
|
name: 'ConnectTimeoutMs',
|
|
type: 'int: 5000',
|
|
description: {
|
|
hcl: `The number of milliseconds to allow when making upstream connections before timing out.<br><br>
|
|
NOTE: The connect timeout of a service should ideally be configured via the
|
|
[\`connect_timeout\`](/docs/connect/config-entries/service-resolver#connecttimeout)
|
|
field of a
|
|
[\`service-resolver\`](/docs/connect/config-entries/service-resolver)
|
|
config entry for the upstream destination service.
|
|
Configuring it in a proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
yaml: `The number of milliseconds to allow when making upstream connections before timing out.<br><br>
|
|
NOTE: The connect timeout of a service should ideally be configured via the
|
|
[\`connectTimeout\`](/docs/connect/config-entries/service-resolver#connecttimeout)
|
|
field of a
|
|
[\`ServiceResolver\`](/docs/connect/config-entries/service-resolver)
|
|
CRD for the upstream destination service.
|
|
Configuring it in a proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
},
|
|
},
|
|
{
|
|
name: 'MeshGateway',
|
|
type: 'MeshGatewayConfig: <optional>',
|
|
description: `Controls the default
|
|
[mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
|
|
for this upstream.`,
|
|
children: [
|
|
{
|
|
name: 'Mode',
|
|
type: 'string: ""',
|
|
description: 'One of `none`, `local`, or `remote`.',
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'Limits',
|
|
type: 'Limits: <optional>',
|
|
description: `A set of limits to apply when connecting to the upstream service.
|
|
These limits are applied on a per-service-instance basis.
|
|
The following limits are respected.`,
|
|
children: [
|
|
{
|
|
name: 'MaxConnections',
|
|
type: 'int: 0',
|
|
description: `The maximum number of connections a service instance
|
|
will be allowed to establish against the given upstream. Use this to limit
|
|
HTTP/1.1 traffic, since HTTP/1.1 has a request per connection.`,
|
|
},
|
|
{
|
|
name: 'MaxPendingRequests',
|
|
type: 'int: 0',
|
|
description: `The maximum number of requests that will be queued
|
|
while waiting for a connection to be established. For this configuration to
|
|
be respected, a L7 protocol must be defined in the \`protocol\` field.`,
|
|
},
|
|
{
|
|
name: 'MaxConcurrentRequests',
|
|
type: 'int: 0',
|
|
description: `The maximum number of concurrent requests that
|
|
will be allowed at a single point in time. Use this to limit HTTP/2 traffic,
|
|
since HTTP/2 has many requests per connection. For this configuration to be
|
|
respected, a L7 protocol must be defined in the \`protocol\` field.`,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'PassiveHealthCheck',
|
|
type: 'PassiveHealthCheck: <optional>',
|
|
description: `Passive health checks are used to remove hosts from
|
|
the upstream cluster which are unreachable or are returning errors..`,
|
|
children: [
|
|
{
|
|
name: 'Interval',
|
|
type: 'duration: 0s',
|
|
description: {
|
|
hcl: `The time between checks. Each check will cause hosts which
|
|
have exceeded \`max_failures\` to be removed from the load balancer, and
|
|
any hosts which have passed their ejection time to be returned to the
|
|
load balancer.`,
|
|
yaml: `The time between checks. Each check will cause hosts which
|
|
have exceeded \`maxFailures\` to be removed from the load balancer, and
|
|
any hosts which have passed their ejection time to be returned to the
|
|
load balancer.`,
|
|
},
|
|
},
|
|
{
|
|
name: 'MaxFailures',
|
|
type: 'int: 0',
|
|
description: `The number of consecutive failures which cause a host to be
|
|
removed from the load balancer.`,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'Defaults',
|
|
type: 'UpstreamConfig: <optional>',
|
|
description: `Default configuration that applies to all upstreams of this service.`,
|
|
children: [
|
|
{
|
|
name: 'Protocol',
|
|
type: 'string: ""',
|
|
description: {
|
|
hcl: `The protocol for the upstream listener.<br><br>
|
|
NOTE: The protocol of a service should ideally be configured via the
|
|
[\`protocol\`](/docs/connect/config-entries/service-defaults#protocol)
|
|
field of a
|
|
[\`service-defaults\`](/docs/connect/config-entries/service-defaults)
|
|
config entry for the upstream destination service. Configuring it in a
|
|
proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
yaml: `The protocol for the upstream listener.<br><br>
|
|
NOTE: The protocol of a service should ideally be configured via the
|
|
[\`protocol\`](/docs/connect/config-entries/service-defaults#protocol)
|
|
field of a
|
|
[\`ServiceDefaults\`](/docs/connect/config-entries/service-defaults)
|
|
CRD for the upstream destination service. Configuring it in a
|
|
proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
},
|
|
},
|
|
{
|
|
name: 'ConnectTimeoutMs',
|
|
type: 'int: 5000',
|
|
description: {
|
|
hcl: `The number of milliseconds to allow when making upstream connections before timing out.<br><br>
|
|
NOTE: The connect timeout of a service should ideally be configured via the
|
|
[\`connect_timeout\`](/docs/connect/config-entries/service-resolver#connecttimeout)
|
|
field of a
|
|
[\`service-resolver\`](/docs/connect/config-entries/service-resolver)
|
|
config entry for the upstream destination service.
|
|
Configuring it in a proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
yaml: `The number of milliseconds to allow when making upstream connections before timing out.<br><br>
|
|
NOTE: The connect timeout of a service should ideally be configured via the
|
|
[\`connectTimeout\`](/docs/connect/config-entries/service-resolver#connecttimeout)
|
|
field of a
|
|
[\`ServiceResolver\`](/docs/connect/config-entries/service-resolver)
|
|
CRD for the upstream destination service.
|
|
Configuring it in a proxy upstream config will not fully enable some
|
|
[L7 features](/docs/connect/l7-traffic).
|
|
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
|
|
`,
|
|
},
|
|
},
|
|
{
|
|
name: 'MeshGateway',
|
|
type: 'MeshGatewayConfig: <optional>',
|
|
description: `Controls the default
|
|
[mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
|
|
for this upstream.`,
|
|
children: [
|
|
{
|
|
name: 'Mode',
|
|
type: 'string: ""',
|
|
description: 'One of `none`, `local`, or `remote`.',
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'Limits',
|
|
type: 'Limits: <optional>',
|
|
description: `A set of limits to apply when connecting to the upstream service.
|
|
These limits are applied on a per-service-instance basis.
|
|
The following limits are respected.`,
|
|
children: [
|
|
{
|
|
name: 'MaxConnections',
|
|
type: 'int: 0',
|
|
description: `The maximum number of connections a service instance
|
|
will be allowed to establish against the given upstream. Use this to limit
|
|
HTTP/1.1 traffic, since HTTP/1.1 has a request per connection.`,
|
|
},
|
|
{
|
|
name: 'MaxPendingRequests',
|
|
type: 'int: 0',
|
|
description: `The maximum number of requests that will be queued
|
|
while waiting for a connection to be established. For this configuration to
|
|
be respected, a L7 protocol must be defined in the \`protocol\` field.`,
|
|
},
|
|
{
|
|
name: 'MaxConcurrentRequests',
|
|
type: 'int: 0',
|
|
description: `The maximum number of concurrent requests that
|
|
will be allowed at a single point in time. Use this to limit HTTP/2 traffic,
|
|
since HTTP/2 has many requests per connection. For this configuration to be
|
|
respected, a L7 protocol must be defined in the \`protocol\` field.`,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'PassiveHealthCheck',
|
|
type: 'PassiveHealthCheck: <optional>',
|
|
description: `Passive health checks are used to remove hosts from
|
|
the upstream cluster which are unreachable or are returning errors..`,
|
|
children: [
|
|
{
|
|
name: 'Interval',
|
|
type: 'duration: 0s',
|
|
description: {
|
|
hcl: `The time between checks. Each check will cause hosts which
|
|
have exceeded \`max_failures\` to be removed from the load balancer, and
|
|
any hosts which have passed their ejection time to be returned to the
|
|
load balancer.`,
|
|
yaml: `The time between checks. Each check will cause hosts which
|
|
have exceeded \`maxFailures\` to be removed from the load balancer, and
|
|
any hosts which have passed their ejection time to be returned to the
|
|
load balancer.`,
|
|
},
|
|
},
|
|
{
|
|
name: 'MaxFailures',
|
|
type: 'int: 0',
|
|
description: `The number of consecutive failures which cause a host to be
|
|
removed from the load balancer.`,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'TransparentProxy',
|
|
type: 'TransparentProxyConfig: <optional>',
|
|
description: `Controls configuration specific to proxies in transparent mode. Added in v1.10.0.`,
|
|
children: [
|
|
{
|
|
name: 'OutboundListenerPort',
|
|
type: 'int: "15001"',
|
|
description: `The port the proxy should listen on for outbound traffic. This must be the port where
|
|
outbound application traffic is redirected to.`,
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'DialedDirectly',
|
|
type: 'bool: false',
|
|
description: {
|
|
hcl: `Determines whether this proxy instance's IP address can be dialed directly by transparent proxies.
|
|
Typically transparent proxies dial upstreams using the "virtual" tagged address, which load balances
|
|
across instances. Dialing individual instances can be helpful in cases like stateful services such
|
|
as a database cluster with a leader.`,
|
|
yaml: `Determines whether the Pod IPs can be dialed directly (versus the Cluster IP).
|
|
Dialing Pod IPs can be helpful in cases like stateful services such
|
|
as a database cluster with a leader or with an ingress controller that dials Pod IPs instead of Cluster IPs.`,
|
|
},
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'MeshGateway',
|
|
type: 'MeshGatewayConfig: <optional>',
|
|
description: `Controls the default
|
|
[mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
|
|
for this service. Added in v1.6.0.`,
|
|
children: [
|
|
{
|
|
name: 'Mode',
|
|
type: 'string: ""',
|
|
description: 'One of `none`, `local`, or `remote`.',
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'ExternalSNI',
|
|
type: 'string: ""',
|
|
description: `This is an optional setting that allows for
|
|
the TLS [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value to
|
|
be changed to a non-connect value when federating with an external system.
|
|
Added in v1.6.0.`,
|
|
},
|
|
{
|
|
name: 'Expose',
|
|
type: 'ExposeConfig: <optional>',
|
|
description: `Controls the default
|
|
[expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference)
|
|
for Envoy. Added in v1.6.2.<br><br>
|
|
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
|
|
non-Connect-enabled applications to contact an HTTP endpoint.
|
|
Some examples include: exposing a \`/metrics\` path for Prometheus or \`/healthz\` for kubelet liveness checks.`,
|
|
children: [
|
|
{
|
|
name: 'Checks',
|
|
type: 'bool: false',
|
|
description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
|
|
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
|
|
[advertise address](/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from
|
|
[expose_min_port](/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/docs/agent/config/config-files#expose_max_port).
|
|
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
|
|
Consul on Kubernetes, and Consul agents run in their own pods.`,
|
|
},
|
|
{
|
|
name: 'Paths',
|
|
type: 'array<Path>: []',
|
|
description: 'A list of paths to expose through Envoy.',
|
|
children: [
|
|
{
|
|
name: 'Path',
|
|
type: 'string: ""',
|
|
description:
|
|
'The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.',
|
|
},
|
|
{
|
|
name: 'LocalPathPort',
|
|
type: 'int: 0',
|
|
description:
|
|
'The port where the local service is listening for connections to the path.',
|
|
},
|
|
{
|
|
name: 'ListenerPort',
|
|
type: 'int: 0',
|
|
description: `The port where the proxy will listen for connections. This port must be available
|
|
for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
|
|
but the proxy registration will not fail.`,
|
|
},
|
|
{
|
|
name: 'Protocol',
|
|
type: 'string: "http"',
|
|
description:
|
|
'Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.',
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
]}
|
|
/>
|
|
|
|
## ACLs
|
|
|
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
|
|
|
Reading a `service-defaults` config entry requires `service:read` on the resource.
|
|
|
|
Creating, updating, or deleting a `service-defaults` config entry requires
|
|
`service:write` on the resource.
|