The `consul intention list` command returns all L4 service intentions, including a unique ID and intention precendence. It was deprecated in Consul v1.9.0; use `consul config` instead.
The `consul intention list` command returns all L4 service intentions, including a unique ID and intention precedence. It was deprecated in Consul v1.9.0; use `consul config` instead.
The `consul kv` command interacts with Consul's key/value store. It exposes top level commands to insert, update, read, and delte data from the store.
The `consul kv` command interacts with Consul's key/value store. It exposes top level commands to insert, update, read, and delete data from the store.
The `consul services deregister` command removes a service from the Consul catalog. Run the commeand on the agent that initially registered the service.
The `consul services deregister` command removes a service from the Consul catalog. Run the command on the agent that initially registered the service.
---
# Consul Agent Service Deregistration
@ -13,12 +13,12 @@ Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/deregister/:service_
The `services deregister` command deregisters a service with the local agent.
Note that this command can only deregister services that were registered
with the agent specified and is intended to be paired with `services register`.
By default, the command deregisters services on the local agent.
with the agent specified and is intended to be paired with `services register`.
By default, the command deregisters services on the local agent.
We recommend deregistering services registered with a configuration file by deleting the file and [reloading](/consul/commands/reload) Consul. Refer to [Services Overview](/consul/docs/services/services) for additional information about services.
The following table shows the [ACLs](/consul/api-docs/api-structure#authentication) required to run the `consul services deregister` command:
The following table shows the [ACLs](/consul/api-docs/api-structure#authentication) required to run the `consul services deregister` command:
@ -14,7 +14,7 @@ Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/register](/consul/ap
The `services register` command registers a service with the local agent.
This command returns after registration and must be paired with explicit
service deregistration. This command simplifies service registration from
scripts. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for information about other service registeration methods.
scripts. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for information about other service registration methods.
The following table shows the [ACLs](/consul/api-docs/api-structure#authentication) required to use the `consul services register` command:
@ -4,9 +4,9 @@ page_title: Limit traffic rates for a source IP address
description: Learn how to set read and request rate limits on RPC and gRPC traffic from all source IP addresses to a Consul resource.
---
# Limit traffic rates from source IP addresses
# Limit traffic rates from source IP addresses
This topic describes how to configure RPC and gRPC traffic rate limits for source IP addresses. This enables you to specify a budget for read and write requests to prevent any single source IP from overwhelming the Consul server and negatively affecting the network. For information about setting global traffic rate limits, refer to [Set a global limit on traffic rates](/consul/docs/agent/limits/usage/set-global-traffic-rate-limits). For an overview of Consul's server rate limiting capabilities, refer to [Limit traffic rates overview](/consul/docs/agent/limits).
This topic describes how to configure RPC and gRPC traffic rate limits for source IP addresses. This enables you to specify a budget for read and write requests to prevent any single source IP from overwhelming the Consul server and negatively affecting the network. For information about setting global traffic rate limits, refer to [Set a global limit on traffic rates](/consul/docs/agent/limits/usage/set-global-traffic-rate-limits). For an overview of Consul's server rate limiting capabilities, refer to [Limit traffic rates overview](/consul/docs/agent/limits).
<EnterpriseAlert>
@ -28,7 +28,7 @@ You should also monitor read and write rate activity and make any necessary adju
## Define rate limits
Create a control plane request limit configuration entry in the `default` partition. The configuration entry applies to all client requests targeting any partition. Refer to the [control plane request limit configuration entry](/consul/docs/connect/config-entries/control-plane-request-limit) reference documentation for details about the available configuration parameters.
Create a control plane request limit configuration entry in the `default` partition. The configuration entry applies to all client requests targeting any partition. Refer to the [control plane request limit configuration entry](/consul/docs/connect/config-entries/control-plane-request-limit) reference documentation for details about the available configuration parameters.
Specify the following parameters:
@ -37,11 +37,11 @@ Specify the following parameters:
- `read_rate`: Specify overall number of read operations per second allowed from the service.
- `write_rate`: Specify overall number of write operations per second allowed from the service.
You can also configure limits on calls to the key-value store, ACL system, and Consul catalog.
You can also configure limits on calls to the key-value store, ACL system, and Consul catalog.
## Apply the configuration entry
## Apply the configuration entry
If your network is deployed to virtual machines, use the `consul config write` command and specify the control plane request limit configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the `kubectl apply` command.
If your network is deployed to virtual machines, use the `consul config write` command and specify the control plane request limit configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the `kubectl apply` command.
Set the [limits.request_limits.mode](/consul/docs/agent/config/config-files#mode-1) in the agent configuration to `disabled` to allow services to exceed the specified read and write requests limits. The `disabled` mode applies to all request rate limits, even limits specifed in the [control plane request limits configuration entry](/consul/docs/connect/config-entries/control-plane-request-limit). Note that any other mode specified in the agent configuration only applies to global traffic rate limits.
Set the [limits.request_limits.mode](/consul/docs/agent/config/config-files#mode-1) in the agent configuration to `disabled` to allow services to exceed the specified read and write requests limits. The `disabled` mode applies to all request rate limits, even limits specified in the [control plane request limits configuration entry](/consul/docs/connect/config-entries/control-plane-request-limit). Note that any other mode specified in the agent configuration only applies to global traffic rate limits.
@ -6,22 +6,22 @@ description: Use global rate limits to prevent excessive rates of requests to Co
# Set a global limit on traffic rates
This topic describes how to configure rate limits for RPC and gRPC traffic to the Consul server.
This topic describes how to configure rate limits for RPC and gRPC traffic to the Consul server.
## Introduction
## Introduction
Rate limits apply to each Consul server separately and limit the number of read requests or write requests to the server on the RPC and internal gRPC endpoints.
Because all requests coming to a Consul server eventually perform an RPC or an internal gRPC request, global rate limits apply to Consul's user interfaces, such as the HTTP API interface, the CLI, and the external gRPC endpoint for services in the service mesh.
Refer to [Initialize Rate Limit Settings](/consul/docs/agent/limits/init-rate-limits) for additional information about right-sizing your gRPC request configurations.
Refer to [Initialize Rate Limit Settings](/consul/docs/agent/limits/init-rate-limits) for additional information about right-sizing your gRPC request configurations.
## Set a global rate limit for a Consul server
## Set a global rate limit for a Consul server
Configure the following settings in your Consul server configuration to limit the RPC and gRPC traffic rates.
- Set the rate limiter [`mode`](/consul/docs/agent/config/config-files#mode-1)
- Set the [`read_rate`](/consul/docs/agent/config/config-files#read_rate)
- Set the [`read_rate`](/consul/docs/agent/config/config-files#read_rate)
- Set the [`write_rate`](/consul/docs/agent/config/config-files#write_rate)
In the following example, the Consul server is configured to prevent more than `500` read and `200` write RPC calls:
@ -53,10 +53,10 @@ limits = {
</CodeTabs>
## Monitor request rate traffic
## Monitor request rate traffic
You should continue to mmonitor request traffic to ensure that request rates remain within the threshold you defined. Refer to [Monitor traffic rate limit data](/consul/docs/agent/limits/usage/monitor-rate-limits) for instructions about checking metrics and log entries, as well as troubleshooting informaiton.
You should continue to monitor request traffic to ensure that request rates remain within the threshold you defined. Refer to [Monitor traffic rate limit data](/consul/docs/agent/limits/usage/monitor-rate-limits) for instructions about checking metrics and log entries, as well as troubleshooting information.
## Disable request rate limits
Set the [`limits.request_limits.mode`](/consul/docs/agent/config/config-files#mode-1) to `disabled` to allow services to exceed the specified read and write requests limits, even limits specified in the [control plane request limits configuration entry](/consul/docs/connect/config-entries/control-plane-request-limit). Note that any other mode specified in the agent configuration only applies to global traffic rate limits.
Set the [`limits.request_limits.mode`](/consul/docs/agent/config/config-files#mode-1) to `disabled` to allow services to exceed the specified read and write requests limits, even limits specified in the [control plane request limits configuration entry](/consul/docs/connect/config-entries/control-plane-request-limit). Note that any other mode specified in the agent configuration only applies to global traffic rate limits.
@ -24,15 +24,15 @@ WAL implements a traditional log with rotating, append-only log files. WAL resol
The existing BoltDB log store inefficiently stores append-only logs to disk because it was designed as a full key-value database. It is a single file that only ever grows. Deleting the oldest logs, which Consul does regularly when it makes new snapshots of the state, leaves free space in the file. The free space must be tracked in a `freelist` so that BoltDB can reuse it on future writes. By contrast, a simple segmented log can delete the oldest log files from disk.
A burst of writes at double or triple the normal volume can suddenly cause the log file to grow to several times its steady-state size. After Consul takes the next snapshot and truncates the oldest logs, the resulting file is mostly empty space.
A burst of writes at double or triple the normal volume can suddenly cause the log file to grow to several times its steady-state size. After Consul takes the next snapshot and truncates the oldest logs, the resulting file is mostly empty space.
To track the free space, Consul must write extra metadata to disk with every write. The metadata is proportional to the amount of free pages, so after a large burst write latencies tend to increase. In some cases, the latencies cause serious performance degradation to the cluster.
To mitigate risks associated with sudden bursts of log data, Consul tries to limit lots of logs from accumulating in the LogStore. Significantly larger BoltDB files are slower to append to because the tree is deeper and freelist larger. For this reason, Consul's default options associated with snapshots, truncating logs, and keeping the log history have been aggressively set toward keeping BoltDB small rather than using disk IO optimally.
To mitigate risks associated with sudden bursts of log data, Consul tries to limit lots of logs from accumulating in the LogStore. Significantly larger BoltDB files are slower to append to because the tree is deeper and freelist larger. For this reason, Consul's default options associated with snapshots, truncating logs, and keeping the log history have been aggressively set toward keeping BoltDB small rather than using disk IO optimally.
But the larger the file, the more likely it is to have a large freelist or suddenly form one after a burst of writes. For this reason, the many of Consul's default options asssociated with snapshots, truncating logs, and keeping the log history aggressively keep BoltDT small rather than uisng disk IO more efficiently.
But the larger the file, the more likely it is to have a large freelist or suddenly form one after a burst of writes. For this reason, the many of Consul's default options associated with snapshots, truncating logs, and keeping the log history aggressively keep BoltDT small rather than using disk IO more efficiently.
Other reliability issues, such as [raft replication capacity issues](/consul/docs/agent/telemetry#raft-replication-capacity-issues), are much simpler to solve without the performance concerns caused by storing more logs in BoltDB.
Other reliability issues, such as [raft replication capacity issues](/consul/docs/agent/telemetry#raft-replication-capacity-issues), are much simpler to solve without the performance concerns caused by storing more logs in BoltDB.
### WAL approaches storage issues differently
@ -43,11 +43,11 @@ When directly measured, WAL is more performant than BoltDB because it solves a s
The WAL backend has been tested thoroughly during development:
- Every component in the WAL, such as [metadata management](https://github.com/hashicorp/raft-wal/blob/main/types/meta.go), [log file encoding](https://github.com/hashicorp/raft-wal/blob/main/types/segment.go) to actual [file-system interaction](https://github.com/hashicorp/raft-wal/blob/main/types/vfs.go) are abstracted so unit tests can simulate difficult-to-reproduce disk failures.
- We used the [application-level intelligent crash explorer (ALICE)](https://github.com/hashicorp/raft-wal/blob/main/alice/README.md) to exhaustively simulate thousands of possible crash failure scenarios. WAL correctly recovered from all scenarios.
- We ran hundreds of tests in a performance testing cluster with checksum verification enabled and did not detect data loss or corruption. We will continue testing before making WAL the default backend.
We are aware of how complex and critical disk-persistence is for your data.
We hope that many users at different scales will try WAL in their environments after upgrading to 1.15 or later and report success or failure so that we can confidently replace BoltDB as the default for new clusters in a future release.
We hope that many users at different scales will try WAL in their environments after upgrading to 1.15 or later and report success or failure so that we can confidently replace BoltDB as the default for new clusters in a future release.
Learn how to revert Consul to the BoltDB backend after enabled the WAL (write-ahead log) LogStore backend shipped in Consul 1.15.
---
# Revert storage backend to BoltDB from WAL
# Revert storage backend to BoltDB from WAL
This topic describes how to revert your Consul storage backend from the experimental WAL LogStore backend to the default BoltDB.
@ -18,14 +18,14 @@ The overall process for reverting to BoltDB consists of the following steps. Rep
## Stop target server gracefully
Stop the target server gracefully. For example, if you are using `systemd`,
Stop the target server gracefully. For example, if you are using `systemd`,
run the following command:
```shell-session
$ systemctl stop consul
```
If your environment uses configuration management automation that might interfere with this process, such as Chef or Puppet, you must disable them until you have completely revereted the storage backend.
If your environment uses configuration management automation that might interfere with this process, such as Chef or Puppet, you must disable them until you have completely reverted the storage backend.
## Remove data directory from target server
@ -73,4 +73,4 @@ If necessary, clean up any `raft.wal.bak` directories. Replace `/data-dir` with
@ -11,7 +11,7 @@ Since Consul v1.15, the Consul API gateway is a native feature within the Consul
## Introduction
Because Consul API gateway releases as part of Consul, it no longer has an independent version number. Instead, the API gateway inherits the same version number as the Consul binary. Refer to the [release notes](/consul/docs/release-notes) for additional information.
Because Consul API gateway releases as part of Consul, it no longer has an independent version number. Instead, the API gateway inherits the same version number as the Consul binary. Refer to the [release notes](/consul/docs/release-notes) for additional information.
To begin using the native API gateway, complete one of the following upgrade paths:
@ -20,7 +20,7 @@ To begin using the native API gateway, complete one of the following upgrade pat
1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
### Upgrade from v0.4.x - v0.5.x
1. Complete the [standard upgrade instructions](#standard-upgrade)
1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
@ -53,11 +53,11 @@ You must begin the upgrade procedure with API gateway with Consul on Kubernetes
If you are able to tolerate downtime for your applications, you should delete previously installed CRDs and allow Consul to install and manage them for future updates. The amount of downtime depends on how quickly you are able to install the new version of Consul. If you are unable to tolerate any downtime, refer to [Self-managed CRDs](#self-managed-crds) for instructions on how to upgrade without downtime.
1. Run the `kubectl delete` command and reference the `kustomize` directory to delete the existing CRDs. The following example deletes the CRDs that were installed with API gateway `v0.5.1`:
1. Run the `kubectl delete` command and reference the `kustomize` directory to delete the existing CRDs. The following example deletes the CRDs that were installed with API gateway `v0.5.1`:
1. Issue the following command to use the API gateway packaged in Consul. Since Consul will not detected an external CRD, it will try to install the API gateway packaged with Consul.
@ -69,7 +69,7 @@ If you are able to tolerate downtime for your applications, you should delete pr
1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information.
1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller.
1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller.
<CodeBlockConfig filename="values.yaml">
@ -98,7 +98,7 @@ If you are able to tolerate downtime for your applications, you should delete pr
</Note>
If you are unable to tolerate any downtime, you can complete the following steps to upgrade to the native Consul API gateway. If you choose this upgrade option, you must continue to manually install the CRDs necessary for operating the API gateway.
If you are unable to tolerate any downtime, you can complete the following steps to upgrade to the native Consul API gateway. If you choose this upgrade option, you must continue to manually install the CRDs necessary for operating the API gateway.
1. Create a Helm chart that installs the version of Consul API gateway that ships with Consul and disables externally-managed CRDs:
@ -119,7 +119,7 @@ If you are unable to tolerate any downtime, you can complete the following steps
```
</CodeBlockConfig>
You must set `connectInject.apiGateway.manageExternalCRDs` to `false`. If you have external CRDs with legacy installation and you do not set this, you will get an error when you try to upgrade because Helm will try to install CRDs that already exist.
1. Issue the following command to install the new version of API gateway and disables externally-managed CRDs:
@ -132,7 +132,7 @@ If you are unable to tolerate any downtime, you can complete the following steps
1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information.
1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller.
1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller.
<CodeBlockConfig filename="values.yaml">
@ -240,7 +240,7 @@ If you have any active `ReferencePolicy` resources, you will receive output simi
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: example-namesapce
namespace: example-namespace
to:
- group: ""
kind: Service
@ -418,7 +418,7 @@ Ensure that the following requirements are met prior to upgrading:
@ -117,7 +117,7 @@ the source of truth for tag information. For example, the Redis
database and its monitoring service Redis Sentinel have this kind of
relationship. Redis instances are responsible for much of their
configuration, but Sentinels determine whether the Redis instance is a
primary or a secondary. Enable the
primary or a secondary. Enable the
[`enable_tag_override`](/consul/docs/services/configuration/services-configuration-reference#enable_tag_override) parameter in your service definition file to tell the Consul agent where the Redis database is running to bypass
tags during anti-entropy synchronization. Refer to
[Modify anti-entropy synchronozation](/consul/docs/services/usage/define-services#modify-anti-entropy-synchronization) for additional information.
tags during anti-entropy synchronization. Refer to
[Modify anti-entropy synchronization](/consul/docs/services/usage/define-services#modify-anti-entropy-synchronization) for additional information.
page_title: Recommendations for operating Consul at scale
description: >-
description: >-
When using Consul for large scale deployments, you can ensure network resilience by tailoring your network to your needs. Learn more about HashiCorp's recommendations for deploying Consul at scale.
---
@ -57,7 +57,7 @@ If appropriate for your use case, we recommend breaking up a single Consul datac
Be aware that the number 5,000 is a heuristic for deployments. The number of agents you deploy per datacenter is limited by performance, not Consul itself. Because gossip stability risk is determined by _the rate of agent churn_ rather than _the number of nodes_, a gossip pool with mostly static nodes may be able to operate effectively with more than 5,000 agents. Meanwhile, a gossip pool with highly dynamic agents, such as spot fleet instances and serverless functions where 10% of agents are replaced each day, may need to be smaller than 5,000 agents.
For additional information about the specifc tests we conducted on Consul deployments at scale in order to generate these recommendations, refer to [Consul Scale Test Report to Observe Gossip Stability](https://www.hashicorp.com/blog/consul-scale-test-report-to-observe-gossip-stability) on the HashiCorp blog.
For additional information about the specific tests we conducted on Consul deployments at scale in order to generate these recommendations, refer to [Consul Scale Test Report to Observe Gossip Stability](https://www.hashicorp.com/blog/consul-scale-test-report-to-observe-gossip-stability) on the HashiCorp blog.
For most use cases, a limit of 5,000 agents is appropriate. When the `consul.serf.queue.Intent` metric is consistently high, it is an indication that the gossip pool cannot keep up with the sustained level of churn. In this situation, reduce the churn by lowering the number agents per datacenter.
@ -175,13 +175,13 @@ Refer to [Consul agent telemetry](/consul/docs/agent/telemetry#bolt-db-performan
#### Raft database size
Raft writes logs to BoltDB, which is designed as a single grow-only file. As a result, if you add 1GB of log entries and then you take a snapshot, only a small number of recent log entries may appear in the file. However, the actual file on disk never shrinks smaller than the 1GB size it grew.
Raft writes logs to BoltDB, which is designed as a single grow-only file. As a result, if you add 1GB of log entries and then you take a snapshot, only a small number of recent log entries may appear in the file. However, the actual file on disk never shrinks smaller than the 1GB size it grew.
If you need to reclaim disk space, use the `bbolt` CLI to copy the data to a new database and repoint to the new database in the process. However, be aware that the `bbolt compact` command requires the database to be offline while being pointed to the new database.
In many cases, including in large clusters, disk space is not a primary concern because Raft logs rarely grow larger than a small number of GiB. However, an inflated file with lots of free space significantly degrades write performance overall due to _freelist management_.
After they are written to disk, Raft logs are eventually captured in a snapshot and log nodes are removed from BoltDB. BoltDB keeps track of the pages for the removed nodes in its freelist. BoltDB also writes this freelist to disk every time there is a Raft write. When the Raft log grows large quickly and then gets truncated, the size of the freelist can become very large. In the worst case reported to us, the freelist was over 10MB. When this large freelist is written to disk on every Raft commit, the result is a large write amplification for what should be a small Raft commit.
After they are written to disk, Raft logs are eventually captured in a snapshot and log nodes are removed from BoltDB. BoltDB keeps track of the pages for the removed nodes in its freelist. BoltDB also writes this freelist to disk every time there is a Raft write. When the Raft log grows large quickly and then gets truncated, the size of the freelist can become very large. In the worst case reported to us, the freelist was over 10MB. When this large freelist is written to disk on every Raft commit, the result is a large write amplification for what should be a small Raft commit.
To figure out if a Consul server’s disk performance issues are the result of BoldDB’s freelist, try the following strategies:
@ -208,7 +208,7 @@ For example, if snapshot A on the leader has an index of 99 and the current inde
When the leader takes snapshot B at index 199, it truncates the logs that accumulated between snapshot A and snapshot B, which means it truncates Raft logs with indexes between 100 and 199.
Because the new server restored snapshot A, the new server has a current index of 99. It requests logs 100 to 150 because index 150 was the current index when it started the replication restore process. At this point, the leader recognizes that it only has logs 200 and higher, and does not have logs for indexes 100 to 150. The leader determines that the new server’s state is stale and starts the process over by sending the new server the latest snapshot, snapshot B.
Because the new server restored snapshot A, the new server has a current index of 99. It requests logs 100 to 150 because index 150 was the current index when it started the replication restore process. At this point, the leader recognizes that it only has logs 200 and higher, and does not have logs for indexes 100 to 150. The leader determines that the new server’s state is stale and starts the process over by sending the new server the latest snapshot, snapshot B.
Consul keeps a configurable number of [Raft trailing logs](/consul/docs/agent/config/config-files#raft_trailing_logs) to prevent the snapshot install loop from repeating. The trailing logs are the last logs that went into the snapshot, and the new server can more easily catch up to the current state using these logs. The default Raft trailing logs configuration value is suitable for most deployments.
Cluster peering establishes communication between independent clusters in Consul, allowing services to interact across datacenters. Learn how cluster peering works, its differences with WAN federation for multi-datacenter deployments, and how to troubleshoot common issues.
Cluster peering establishes communication between independent clusters in Consul, allowing services to interact across datacenters. Learn how cluster peering works, its differences with WAN federation for multi-datacenter deployments, and how to troubleshoot common issues.
---
# Cluster peering overview
@ -22,7 +22,7 @@ In this diagram, the `default` partition in Consul DC 1 has a cluster peering co
Cluster peering leverages several components of Consul's architecture to enforce secure communication between services:
- A _peering token_ contains an embedded secret that securely establishes communication when shared symetrically between datacenters. Sharing this token enables each datacenter's server agents to recognize requests from authorized peers, similar to how the [gossip encryption key secures agent LAN gossip](/consul/docs/security/encryption#gossip-encryption).
- A _peering token_ contains an embedded secret that securely establishes communication when shared symmetrically between datacenters. Sharing this token enables each datacenter's server agents to recognize requests from authorized peers, similar to how the [gossip encryption key secures agent LAN gossip](/consul/docs/security/encryption#gossip-encryption).
- A _mesh gateway_ encrypts outgoing traffic, decrypts incoming traffic, and directs traffic to healthy services. Consul's service mesh features must be enabled in order to use mesh gateways. Mesh gateways support the specific admin partitions they are deployed on. Refer to [Mesh gateways](/consul/docs/connect/gateways/mesh-gateway) for more information.
- An _exported service_ communicates with downstreams deployed in other admin partitions. They are explicitly defined in an [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services).
- A _service intention_ secures [service-to-service communication in a service mesh](/consul/docs/connect/intentions). Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request.
@ -75,7 +75,7 @@ The following resources are available to help you use Consul's cluster peering f
- [Establish cluster peering connnections on HCP Consul](/hcp/docs/consul/usage/cluster-peering/create-connections)
- [Establish cluster peering connections on HCP Consul](/hcp/docs/consul/usage/cluster-peering/create-connections)
- [Cluster peering with management plane](/hcp/docs/consul/usage/management-plane#cluster-peering)
### Reference documentation
@ -93,4 +93,4 @@ If you experience errors when using Consul's cluster peering features, refer to
- Two admin partitions in the same datacenter cannot be peered. Use the [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services#exporting-services-to-peered-clusters) instead.
- To manage intentions that specify services in peered clusters, use [configuration entries](/consul/docs/connect/config-entries/service-intentions). The `consul intention` CLI command is not supported.
- The Consul UI does not support exporting services between clusters or creating service intentions. Use either the API or the CLI to complete these required steps when establishing new cluster peering connections.
- Accessing key/value stores across peers is not supported.
- Accessing key/value stores across peers is not supported.
page_title: Control Plane Request Limit Configuration Entry Configuration Reference
description: Learn how to configure the control-plane-request-limit configuration entry, which defines how Consul agents limit read and reqeust traffic rate limits.
description: Learn how to configure the control-plane-request-limit configuration entry, which defines how Consul agents limit read and request traffic rate limits.
---
# Control Plane Request Limit Configuration Entry Configuration Reference
This topic describes the configuration options for the `control-plane-request-limit` configuration entry. You can only write the `control-plane-request-limit` configuration entry to the `default` partition, but the configuration entry applies to all client requests that target any partition.
This topic describes the configuration options for the `control-plane-request-limit` configuration entry. You can only write the `control-plane-request-limit` configuration entry to the `default` partition, but the configuration entry applies to all client requests that target any partition.
<EnterpriseAlert>
@ -29,7 +29,7 @@ The following list outlines field hierarchy, language-specific data types, and r
- [`acl`](#acl): map | no default
- [`read_rate`](#acl-read-rate): number | `100`
- [`write_rate`](#acl-write-rate): number | `100`
- [`catalog`](#catalog): map
- [`catalog`](#catalog): map
- [`read_rate`](#catalog-read-rate): number | default is `100`
- [`write_rate`](#catalog-write-rate): number | default is `100`
@ -90,7 +90,7 @@ read_rate: 100
write_rate: 100
kv:
read_rate: 100
write_rate: 100
write_rate: 100
acl:
read_rate: 100
write_rate: 100
@ -124,13 +124,13 @@ Specifies an action to take if the rate of requests exceeds the limit.
- Default: None
- This field is required.
- One of the following string values:
- `permissive`: The server continues to allow requests and records an error in the logs. This is the default value for `mode`.
- `enforcing`: The server stops accepting requests and records an error in the logs.
- `disabled`: Limits are not enforced or tracked.
- `permissive`: The server continues to allow requests and records an error in the logs. This is the default value for `mode`.
- `enforcing`: The server stops accepting requests and records an error in the logs.
- `disabled`: Limits are not enforced or tracked.
### `name`
Specifies the name of the configuration entry.
Specifies the name of the configuration entry.
#### Values
@ -158,7 +158,7 @@ Specifies the maximum number of write requests per second that the agent allows.
### `kv`
Specifies the maximum number of read and write requests to the Consul key-value store.
Specifies the maximum number of read and write requests to the Consul key-value store.
#### Values
@ -191,7 +191,7 @@ Specifies the maximum number of read and write ACL requests to the Consul server
### `acl.read_rate`
S
pecifies the maximum number of ACL read requests per second allowed to the Consul server.
Specifies the maximum number of ACL read requests per second allowed to the Consul server.
#### Values
@ -227,4 +227,4 @@ Specifies the maximum number of write requests per second allowed to the Consul
Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval.
Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval.
#### Values
@ -534,10 +534,10 @@ Defines how Envoy fetches the remote JSON Web Key Set URI.
Specifies the service discovery type to use for resolving the cluster.
You can specify the following discovery types:
- `STRICT_DNS`
- `STATIC`
- `LOGICAL_DNS`
- `EDS`
- `STRICT_DNS`
- `STATIC`
- `LOGICAL_DNS`
- `EDS`
- `ORIGINAL_DST`
#### Values
@ -571,7 +571,7 @@ You cannot specify [`TLSCertificates{}.CaCertificateProviderInstance`](#jsonwebk
Specifies TLS certificate data containing certificate authority certificates. Specify exactly one of the following data holders:
- `Filename`
- `EnvironmentVariable`
- `InlineString`
- `Filename`
- `EnvironmentVariable`
- `InlineString`
- `InlineBytes`
#### Values
@ -614,7 +614,7 @@ Specifies a set of audiences that the JWT is allowed to access, formatted as a l
### `Locations`
Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT.
Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT.
This field can specify token locations in a header, a query parameter, or a cookie. When no locations are specified, Envoy defaults to the following locations:
@ -725,7 +725,7 @@ The header value is base64 URL encoded. It is not padded by default.
### `Forwarding{}.PadForwardPayloadHeader`
Determines whether to add padding to the base64 encoded token specified in [`Forwarding{}.HeaderName`](#forwarding-header-name).
Determines whether to add padding to the base64 encoded token specified in [`Forwarding{}.HeaderName`](#forwarding-header-name).
By default, this field is set to `false`.
@ -736,7 +736,7 @@ By default, this field is set to `false`.
### `ClockSkewSeconds`
Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf` (not before) claims, measured in seconds.
Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf` (not before) claims, measured in seconds.
By default, this parameter is configured to 30 seconds.
@ -949,7 +949,7 @@ Specifies the number of times to attempt to fetch the JSON Web Key Set when the
Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval.
Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval.
#### Values
@ -977,11 +977,11 @@ Defines how Envoy fetches the remote JSON Web Key Set URI.
Specifies the service discovery type to use for resolving the cluster.
You can specify the following discovery types:
- `STRICT_DNS`
- `STATIC`
- `LOGICAL_DNS`
- `EDS`
You can specify the following discovery types:
- `STRICT_DNS`
- `STATIC`
- `LOGICAL_DNS`
- `EDS`
- `ORIGINAL_DST`
String values must be a valid [Cluster DiscoveryType](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-enum-config-cluster-v3-cluster-discoverytype).
@ -1017,7 +1017,7 @@ You cannot specify [`spec.tlsCertificates.caCertificateProviderInstance`](#spec-
Specifies TLS certificate data containing certificate authority certificates. Specify exactly one of the following data holders:
- `Filename`
- `EnvironmentVariable`
- `InlineString`
- `Filename`
- `EnvironmentVariable`
- `InlineString`
- `InlineBytes`
#### Values
@ -1171,7 +1171,7 @@ The header value is base64 URL encoded. It is not padded by default.
### `spec.forwarding.padForwardPayloadHeader`
Determines whether to add padding to the base64 encoded token specified in [spec.forwarding.headerName`](#spec-forwarding-header-name).
Determines whether to add padding to the base64 encoded token specified in [spec.forwarding.headerName`](#spec-forwarding-header-name).
By default, this field is set to `false`.
@ -1182,7 +1182,7 @@ By default, this field is set to `false`.
### `spec.clockSkewSeconds`
Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf` (not before) claims, measured in seconds.
Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf` (not before) claims, measured in seconds.
By default, this parameter is configured to 30 seconds.
namespace: <namespace containing upstream - Consul Enterprise>
peer: <peer name of the upstream service>
@ -266,25 +266,25 @@ spec:
meshGateway:
mode: <type of mesh gateway>
balanceOutboundConnections: exact_balance
limits:
limits:
maxConnections: 0
maxPendingRequests: 0
maxConcurrentRequests: 0
passiveHealthCheck:
passiveHealthCheck:
interval: 0s
maxFailures: 0
enforcingConsecutive5xx: 100
defaults:
defaults:
protocol: <protocol for the upstream listener>
connectTimeoutMs: 5000
meshGateway:
mode: <type of mesh gateway>
balanceOutboundConnections: exact_balance
limits:
limits:
maxConnections: 0
maxPendingRequests: 0
maxConcurrentRequests: 0
passiveHealthCheck:
passiveHealthCheck:
interval: 0s
maxFailures: 0
enforcingConsecutive5xx: 100
@ -301,9 +301,9 @@ spec:
meshGateway:
mode: <type of mesh gateway>
externalSNI: <name of TLS SNI outside o f the mesh>
expose:
expose:
checks: false
paths:
paths:
- path: <HTTP path to expose through Envoy>
localPathPort: 0
listenerPort: 0
@ -325,7 +325,7 @@ spec:
},
"spec": {
"protocol": "tcp",
"balanceInboundConnnections": "exact_balance",
"balanceInboundConnections": "exact_balance",
"mode": "transparent",
"upstreamConfig": {
"overrides": [
@ -408,7 +408,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.
<Tabs>
<Tab heading="HCL" group="hcl">
@ -425,7 +425,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
@ -435,7 +435,7 @@ Specifies the name of the service you are setting the defaults for.
### `Namespace` <Enterprise/>
Specifies the Consul namespace that the configuration entry applies to.
Specifies the Consul namespace that the configuration entry applies to.
#### Values
@ -453,7 +453,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
@ -467,26 +467,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:
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
@ -495,17 +495,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:
Specifies the namespace containing the upstream service that the configuration applies to. Do not use the `*` wildcard to prevent the configuration from appling to unintended upstreams.
Specifies the namespace containing the upstream service that the configuration applies to. Do not use the `*` wildcard to prevent the configuration from applying to unintended upstreams.
#### Values
@ -552,7 +552,7 @@ Specifies the peer name of the upstream service that the configuration applies t
- 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.
@ -564,7 +564,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.
@ -575,31 +575,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.
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
@ -615,7 +615,7 @@ Refer to the [upstream configuration example](#upstream-configuration) for addit
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
@ -629,7 +629,7 @@ The following table describes passive health check parameters you can configure:
### `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
@ -638,7 +638,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.
@ -647,7 +647,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.
@ -656,17 +656,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.
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
@ -717,7 +717,7 @@ You can specify the following string values for the `MutualTLSMode` field:
### `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:
@ -729,7 +729,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:
@ -752,7 +752,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.
@ -761,22 +761,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.
@ -785,7 +785,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.
@ -807,9 +807,9 @@ Specifies a list of configuration maps that define paths to expose through Envoy
<Tab heading="YAML" group="yaml">
### `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.
@ -824,7 +824,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
@ -834,10 +834,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
@ -854,33 +854,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:
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
@ -889,7 +889,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
@ -897,12 +897,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
@ -913,7 +913,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
@ -959,7 +959,7 @@ Specifies the protocol to use for requests to the upstream listener. We recommen
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.
@ -970,19 +970,19 @@ We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/
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.
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
@ -991,7 +991,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
@ -1005,7 +1005,7 @@ The following table describes limits you can configure:
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
@ -1019,7 +1019,7 @@ The following table describes passive health check parameters you can configure:
### `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
@ -1037,7 +1037,7 @@ Specifies default protocol for upstream listeners. We recommend configuring the
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.
@ -1048,19 +1048,19 @@ We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/
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.
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
@ -1069,7 +1069,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
@ -1082,7 +1082,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` |
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
@ -1096,7 +1096,7 @@ The following table describes the health check parameters you can configure:
### `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
@ -1138,7 +1138,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
@ -1167,7 +1167,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.
@ -1176,20 +1176,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
@ -1207,7 +1207,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.
@ -1218,7 +1218,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
@ -1278,7 +1278,7 @@ You can also set the global default protocol for all proxies in the [`proxy-defa
<Tabs>
<Tab heading="Consul OSS">
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.
- [`VerifyClaims`](#jwt-provider-verifyclaims): list of maps
@ -113,13 +113,13 @@ When every field is defined, a service intentions configuration entry has the fo
```hcl
Kind = "service-intentions"
Name = "<name of destination service>"
Name = "<name of destination service>"
Namespace = "<destination namespace>" # string
Partition = "<destination partition>" # string
Meta = {
"<key-1>" = "<value-1>"
"<key-2>" = "<value-2>"
}
"<key-1>" = "<value-1>"
"<key-2>" = "<value-2>"
}
JWT = {
Providers = [
{
@ -141,14 +141,14 @@ Sources = [
Partition = "<sources-partition>" # string
SamenessGroup = "<group-name>" # string
Action = "allow" or "deny" # string for L4 intentions
Permissions = [
{
Action = "allow" or "deny" # string for L7 intenions
HTTP = {
PathExact = "<exact path to match>" # string
PathPrefix = "<path prefix to match>" # string
PathRegex = "<regex pattern to match>" # string
Methods = [
Permissions = [
{
Action = "allow" or "deny" # string for L7 intentions
HTTP = {
PathExact = "<exact path to match>" # string
PathPrefix = "<path prefix to match>" # string
PathRegex = "<regex pattern to match>" # string
Methods = [
"<fist http method to match>", # string
"<second http method to match>"
]
@ -174,17 +174,17 @@ Sources = [
Regex = "<regex pattern to match>" # string
Invert = <true or false> # boolean
}
]
]
}
}
}
]
Type = "consul" # string
Description = "<description for API responses>" # string
Type = "consul" # string
Description = "<description for API responses>" # string
Precedence = <read-only> # number
LegacyID = <read-only> # string
LegacyID = <read-only> # string
LegacyMeta = <read-only> # string
LegacyCreateTime = <read-only> # string
LegacyUpdateTime = <read-only> # string
LegacyUpdateTime = <read-only> # string
}
]
```
@ -346,7 +346,7 @@ Specifies the type of configuration entry to implement. Must be set to `service-
### `Name`
Specifies a name of the destination service for all intentions defined in the configuration entry.
Specifies a name of the destination service for all intentions defined in the configuration entry.
#### Values
@ -354,22 +354,22 @@ Specifies a name of the destination service for all intentions defined in the co
- This field is required.
- Data type: String
You can also specify a wildcard character (`*`) to match all services without intentions. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`Permissions`](#sources-permissions).
You can also specify a wildcard character (`*`) to match all services without intentions. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`Permissions`](#sources-permissions).
### `Namespace` <EnterpriseAlert inline />
### `Namespace` <EnterpriseAlert inline />
Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. Services in the namespace are the traffic destinations that the intentions allow or deny traffic to.
Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. Services in the namespace are the traffic destinations that the intentions allow or deny traffic to.
#### Values
- Default: `default`
- Data type: String
You can also specify a wildcard character (`*`) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`Permissions`](#sources-permissions).
You can also specify a wildcard character (`*`) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`Permissions`](#sources-permissions).
### `Partition` <EnterpriseAlert inline />
### `Partition` <EnterpriseAlert inline />
Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to apply the configuration entry. Services in the specified partition are the traffic destinations that the intentions allow or deny traffic to.
Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to apply the configuration entry. Services in the specified partition are the traffic destinations that the intentions allow or deny traffic to.
#### Values
@ -469,7 +469,7 @@ List of configurations that define intention sources and the authorization grant
### `Sources[].Name`
Specifies the name of the source that the intention allows or denies traffic from. If [`Type`](#sources-type) is set to `consul`, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog.
Specifies the name of the source that the intention allows or denies traffic from. If [`Type`](#sources-type) is set to `consul`, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog.
#### Values
@ -479,38 +479,38 @@ Specifies the name of the source that the intention allows or denies traffic fro
### `Sources[].Peer`
Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to [Cluster peering overview](/consul/docs/connect/cluster-peering) for additional information about peers.
Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to [Cluster peering overview](/consul/docs/connect/cluster-peering) for additional information about peers.
The `Peer` and `Partition` fields are mutually exclusive.
The `Peer` and `Partition` fields are mutually exclusive.
Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information about partitions.
Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information about partitions.
The `Peer` and `Partition` fields are mutually exclusive.
The `Peer` and `Partition` fields are mutually exclusive.
#### Values
- Default: If [`Peer`](#sources-peer) is unspecified, defaults to the destination [`Partition`](#partition).
Specifies the name of a sameness group that the intention allows or denies traffic from. Refer to [create samenes groups](/consul/docs/connect/cluster-peering/usage/create-sameness-groups) for additional information.
Specifies the name of a sameness group that the intention allows or denies traffic from. Refer to [create sameness groups](/consul/docs/connect/cluster-peering/usage/create-sameness-groups) for additional information.
#### Values
@ -520,12 +520,12 @@ Specifies the name of a sameness group that the intention allows or denies traff
### `Sources[].Action`
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field to apply L7 intentions to the same source. Configure the [`Permissions`](#sources-permissions) field instead.
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field to apply L7 intentions to the same source. Configure the [`Permissions`](#sources-permissions) field instead.
#### Values
- Default: None
- This field is required for L4 intentions.
- This field is required for L4 intentions.
- Data type: String value set to either `allow` or `deny`
Refer to the following examples for additional guidance:
@ -537,13 +537,13 @@ Refer to the following examples for additional guidance:
### `Sources[].Permissions[]`
Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action.
Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action.
Consul applies permissions in the order specified in the configuration. Beginning at the top of the list, Consul applies the first matching request and stops evaluating against the remaining configurations.
Consul applies permissions in the order specified in the configuration. Beginning at the top of the list, Consul applies the first matching request and stops evaluating against the remaining configurations.
For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration.
For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration.
Do not configure this field for L4 intentions. Use the [`Sources.Action`](#sources-action) parameter instead.
Do not configure this field for L4 intentions. Use the [`Sources.Action`](#sources-action) parameter instead.
The `Permissions` only applies to services with a compatible protocol. `Permissions` are not supported when the [`Name`](#name) or [`Namespace`](#namespace) field is configured with a wildcard because service instances or services in a namespace may use different protocols.
@ -563,12 +563,12 @@ Refer to the following examples for additional guidance:
### `Sources[].Permissions[].Action`
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`.
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`.
#### Values
- Default: None
- This field is required.
- This field is required.
- Data type: String value set to either `allow` or `deny`.
### `Sources[].Permissions[].HTTP`
@ -579,7 +579,7 @@ Specifies a set of HTTP-specific match criteria. Consul applies the action defin
- Default: None
- This field is required.
- Data type: Map
- Data type: Map
The following table describes the parameters that the HTTP map may contain:
@ -593,14 +593,14 @@ The following table describes the parameters that the HTTP map may contain:
### `Sources[].Permissions[].HTTP[].Header[]`
Specifies a header name and matching criteria for HTTP request headers. The request header must match all specified criteria for the permission to apply.
Specifies a header name and matching criteria for HTTP request headers. The request header must match all specified criteria for the permission to apply.
#### Values
- Default: None
- Data type: list of objects
- Data type: list of objects
Each member of the `Header` list is a map that contains a `Name` field and at least one match criterion. The following table describes the parameters that each member of the `Header` list may contain:
Each member of the `Header` list is a map that contains a `Name` field and at least one match criterion. The following table describes the parameters that each member of the `Header` list may contain:
| Parameter | Description | Data type | Required |
| --- | --- | --- | --- |
@ -614,11 +614,11 @@ Each member of the `Header` list is a map that contains a `Name` field and at le
### `Sources[].Precedence`
The `Precedence` field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to [Precedence and matching order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-matching-order) for additional information.
The `Precedence` field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to [Precedence and matching order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-matching-order) for additional information.
### `Sources[].Type`
Specifies the type of destination service that the configuration entry applies to. The only value supported is `consul`.
Specifies the type of destination service that the configuration entry applies to. The only value supported is `consul`.
#### Values
@ -627,7 +627,7 @@ Specifies the type of destination service that the configuration entry applies t
### `Sources[].Description`
Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network.
Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network.
#### Values
@ -656,7 +656,7 @@ Read-only timestamp marking the most recent intention update. Consul exposes the
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
#### Values
@ -676,7 +676,7 @@ Specifies the type of configuration entry to implement. Must be set to `ServiceI
### `metadata`
Map that contains an arbitrary name for the configuration entry and the namespace it applies to.
Map that contains an arbitrary name for the configuration entry and the namespace it applies to.
#### Values
@ -687,7 +687,7 @@ Map that contains an arbitrary name for the configuration entry and the namespac
Specifies an arbitrary name for the configuration entry. Note that in other configuration entries, the `metadata.name` field specifies the name of the service that the settings apply to. For service intentions, the service that accepts the configurations is the _destination_ and is specified in the [`spec.destination.name`](#spec-destination-name) field. Refer to the following topics for additional information:
- [ServiceIntentions Special Case (OSS)](/consul/docs/k8s/crds#serviceintentions-special-case)
- [ServiceIntentions Special Case (OSS)](/consul/docs/k8s/crds#serviceintentions-special-case)
- [ServiceIntentions Special Case (Enterprise)](/consul/docs/k8s/crds#serviceintentions-special-case-enterprise)
#### Values
@ -695,7 +695,7 @@ Specifies an arbitrary name for the configuration entry. Note that in other conf
Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. Refer to [Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for information about how Consul namespaces map to Kubernetes Namespaces. Open source Consul distributions (Consul OSS) ignore the `metadata.namespace` configuration.
@ -727,13 +727,13 @@ Map that identifies the destination name and destination namespace that source s
### `spec.destination.name`
Specifies the name of the destination service in the mesh that the intentions apply to.
You can also specify a wildcard character (`*`) to match all services that are missing intention settings. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`permissions`](#spec-sources-permissions).
You can also specify a wildcard character (`*`) to match all services that are missing intention settings. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`permissions`](#spec-sources-permissions).
#### Values
- Default: None
- This field is required.
- Data type: String
- Data type: String
### `spec.jwt`
@ -791,10 +791,10 @@ Specifies the value to match on when verifying the the claim designated in [`JWT
- Default: None
- Data type: String
### `spec.sources[]`
List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime.
List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime.
#### Values
@ -812,7 +812,7 @@ List of configurations that define intention sources and the authorization grant
### `spec.sources[].name`
Specifies the name of the source that the intention allows or denies traffic from. If [`type`](#sources-type) is set to `consul`, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog.
Specifies the name of the source that the intention allows or denies traffic from. If [`type`](#sources-type) is set to `consul`, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog.
#### Values
@ -822,58 +822,58 @@ Specifies the name of the source that the intention allows or denies traffic fro
### `spec.sources[].peer`
Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to [Cluster peering overview](/consul/docs/connect/cluster-peering) for additional information about peers. The `peer` and `partition` fields are mutually exclusive.
Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to [Cluster peering overview](/consul/docs/connect/cluster-peering) for additional information about peers. The `peer` and `partition` fields are mutually exclusive.
Specifies the traffic source namespace that the intention allows or denies traffic from.
Specifies the traffic source namespace that the intention allows or denies traffic from.
#### Values
- Default: If [`peer`](#spec-sources-peer) is unspecified, defaults to the namespace specified in the [`spec.destination.namespace`](#spec-destination-namespace) field.
Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information about partitions. The `peer` and `partition` fields are mutually exclusive.
Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information about partitions. The `peer` and `partition` fields are mutually exclusive.
#### Values
- Default: If [`peer`](#sources-peer) is unspecified, defaults to the partition specified in [`spec.destination.partition`](#spec-destination-partition).
Specifies the name of a sameness group that the intention allows or denies traffic from. Refer to [create samenes groups](/consul/docs/k8s/connect/cluster-peering/usage/create-sameness-groups) for additional information.
Specifies the name of a sameness group that the intention allows or denies traffic from. Refer to [create sameness groups](/consul/docs/k8s/connect/cluster-peering/usage/create-sameness-groups) for additional information.
#### Values
- Default: None
- Data type: string
### `spec.sources[].action`
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field for L7 intentions. Configure the [`spec.sources.permissions`](#spec-sources-permissions) field instead.
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field for L7 intentions. Configure the [`spec.sources.permissions`](#spec-sources-permissions) field instead.
#### Values
- Default: None
- This field is required for L4 intentions.
- This field is required for L4 intentions.
- Data type: String value set to either `allow` or `deny`
### `spec.sources[].permissions[]`
Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action.
Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action.
Consul applies permissions in the order specified in the configuration. Starting at the beginning of the list, Consul applies the first matching request and stops evaluating against the remaining configurations.
Consul applies permissions in the order specified in the configuration. Starting at the beginning of the list, Consul applies the first matching request and stops evaluating against the remaining configurations.
For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration.
For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration.
Do not configure this field for L4 intentions. Use the [`spec.sources.action`](#sources-action) parameter instead.
Do not configure this field for L4 intentions. Use the [`spec.sources.action`](#sources-action) parameter instead.
`permissions` configurations only apply to services with a compatible protocol. As a result, they are not supported when the [`spec.destination.name`](#spec-destination-name) or [`spec.destination.namespace`](#spec-destination-namespace) field is configured with a wildcard because service instances or services in a namespace may use different protocols.
@ -886,12 +886,12 @@ Do not configure this field for L4 intentions. Use the [`spec.sources.action`](#
### `spec.sources[].permissions[].action`
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`.
Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`.
#### Values
- Default: None
- This field is required.
- This field is required.
- Data type: String value set to either `allow` or `deny`
### `spec.sources[].permissions[].http`
@ -902,7 +902,7 @@ Specifies a set of HTTP-specific match criteria. Consul applies the action defin
- Default: None
- This field is required.
- Data type: Map
- Data type: Map
The following table describes the parameters that the HTTP map may contain:
@ -916,7 +916,7 @@ The following table describes the parameters that the HTTP map may contain:
### `spec.sources[].permissions[].http[].header`
Specifies a set of criteria for matching HTTP request headers. The request header must match all specified criteria for the permission to apply.
Specifies a set of criteria for matching HTTP request headers. The request header must match all specified criteria for the permission to apply.
#### Values
@ -937,7 +937,7 @@ Each member of the `header` list is a map that contains a `name` field and at le
### `spec.sources[].type`
Specifies the type of destination service that the configuration entry applies to. The only value supported is `consul`.
Specifies the type of destination service that the configuration entry applies to. The only value supported is `consul`.
#### Values
@ -946,7 +946,7 @@ Specifies the type of destination service that the configuration entry applies t
### `spec.sources[].description`
Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network.
Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network.
#### Values
@ -964,9 +964,9 @@ The following examples demonstrate potential use-cases for the service intention
### L4 Intentions for specific sources and destinations
The following example configuration entry specifies an L4 intention that denies traffic from `web` to `db` service instances, but allows traffic from `api` to `db`.
The following example configuration entry specifies an L4 intention that denies traffic from `web` to `db` service instances, but allows traffic from `api` to `db`.
In the following L4 example, the destination is configured with a `*` wildcard. As a result, traffic from `web` service instances is denied for any service in the datacenter.
In the following L4 example, the destination is configured with a `*` wildcard. As a result, traffic from `web` service instances is denied for any service in the datacenter.
In the following example, Consul denies requests from `frontend-web` to the `IssueRefund` gRPC service.
In the following example, Consul denies requests from `frontend-web` to the `IssueRefund` gRPC service.
Because gRPC method calls use the [HTTP/2 protocol](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), you can apply an HTTP path-matching rule to control traffic:
page_title: Service Resolver Configuration Entry Reference
description: >-
description: >-
Service resolver configuration entries are L7 traffic management tools for defining sets of service instances that resolve upstream requests and Consul’s behavior when resolving them. Learn how to write `service-resolver` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case.
---
@ -136,8 +136,8 @@ When every field is defined, a service resolver configuration entry has the foll
```hcl
Kind = "service-resolver" ## required
Name = "<name-of-service-configuration-applies-to>"
| `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). For more information about creating and using expressions to filter, refer to [filtering](/consul/api-docs/features/filtering). | String | None |
@ -557,7 +557,7 @@ This parameter is a map, and its key is the name of the local service subset tha
- [`SamenessGroup`](#failover-samenessgroup)
- [`Datacenters`](#failover-datacenters)
- [`Targets`](#failover-targets)
### `Failover{}.Service`
Specifies the name of the service to resolve at the failover location during a failover scenario.
@ -706,10 +706,10 @@ Specifies the type of load balancing policy for selecting a host. Supported load
- Data type: String containing one of the following values:
- `random`
- `round_robin`
- `round_robin`
- `least_request`
- `ring_hash`
- `maglev`
- `ring_hash`
- `maglev`
### `LoadBalancer{}.LeastRequestConfig`
@ -719,7 +719,7 @@ Specifies configuration for the `least_request` policy type.
- Default: None
- Data type: Map containing the following parameter:
| `Session` | Directs Consul to generate a session cookie with no expiration. | Boolean | `false` |
@ -798,13 +798,13 @@ Specifies additional configuration options for the `cookie` hash policy type. Th
### `LoadBalancer{}.HashPolicies[].SourceIP`
Determines if the hash type should besource IP address. You cannot specify `SourceIP` if `Field` or `FieldValue` are configured.
Determines if the hash type should besource IP address. You cannot specify `SourceIP` if `Field` or `FieldValue` are configured.
#### Values
- Default: `false`
- Data type: Boolean
### `LoadBalancer{}.HashPolicies[].Terminal`
Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored.
@ -813,14 +813,14 @@ Determines if the hash type should besource IP address. You cannot specify `Sour
- Default: `false`
- Data type: Boolean
</Tab>
<Tab heading="YAML" group="yaml">
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
#### Values
@ -840,7 +840,7 @@ Specifies the type of configuration entry to implement. Must be set to `ServiceR
## `metadata`
Map that contains an arbitrary name for the configuration entry and the namespace it applies to.
Map that contains an arbitrary name for the configuration entry and the namespace it applies to.
#### Values
@ -1019,7 +1019,7 @@ This parameter is a map, and its key is the name of the local service subset tha
- [`samenessGroup`](#spec-failover-samenessgroup)
- [`datacenters`](#spec-failover-datacenters)
- [`targets`](#spec-failover-targets)
### `spec.failover.service`
Specifies the name of the service to resolve at the failover location during a failover scenario.
@ -1167,9 +1167,9 @@ Specifies the type of load balancing policy for selecting a host. Supported load
- Data type: String containing one of the following values:
- `random`
- `round_robin`
- `round_robin`
- `least_request`
- `ring_hash`
- `ring_hash`
- `maglev`
### `spec.loadBalancer.leastRequestConfig`
@ -1180,7 +1180,7 @@ Specifies configuration for the `least_request` policy type.
- Default: None
- Data type: Map containing the following parameter:
page_title: Service Router Configuration Entry Reference
description: >-
description: >-
Service router configuration entries are L7 traffic management tools for redirecting requests for a service to a particular instance or set of instances. Learn how to write `service-router` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case.
---
@ -23,7 +23,7 @@ The following list outlines field hierarchy, language-specific data types, and r
pathPrefix: <path/prefix> ## cannot specify with pathExact or pathRegex
http:
pathRegex: <regex/path> ## cannot specify with pathPrefix or pathExact
http:
http:
methods: [GET, POST, PUT]
http:
header: ## do not specify present, exact, prefix, suffix, and regex in a single header
@ -317,7 +317,7 @@ spec:
- name: <text-to-match-in-query-parameter> ## required when specifying spec.routes.match.http.header
present: false
exact: <exact-text-to-match-in-query-parameter>
regex: <regex-to-match-in-query-paramater>
regex: <regex-to-match-in-query-parameter>
destination:
service: <service-name-at-destination>
@ -325,7 +325,7 @@ spec:
namespace: <namespace-at-destination>
partition: <partition-at-destination>
prefixRewrite: <new-prefix-after-routing> ## required specifying either spec.routes.match.http.pathPrefix or spec.routes.match.http.pathExact
requestTimeout: 0
requestTimeout: 0
idleTimeout: 0
numRetries: 1
retryOnConnectFailure: false
@ -351,15 +351,15 @@ This section provides details about the fields you can configure in the service
<Tab heading="HCL" group="hcl">
### `Kind`
### `Kind`
Specifies the type of configuration entry to implement.
Specifies the type of configuration entry to implement.
#### Values
- Default: none
- This field is required.
- Data type: String value that must be set to `service-router`.
- Data type: String value that must be set to `service-router`.
### `Name`
@ -609,7 +609,7 @@ Specifies that a request matches when the query parameter with the given name is
- Default: None
- Data type: String
### `Routes[].Match{}.HTTP{}.QueryParam[].Regex`
Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `Present` or `Exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use.
@ -646,7 +646,7 @@ Specifies the target service to route matching requests to, as well as behavior
Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`Name` field](#name).
#### Values
#### Values
- Default: None
- Data type: String
@ -655,7 +655,7 @@ Specifies the name of the service to resolve. If this parameter is not specified
Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used.
#### Values
#### Values
- Default: None
- Data type: String
@ -664,7 +664,7 @@ Specifies a named subset of the given service to resolve instead of the one defi
Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used.
#### Values
#### Values
- Default: None
- Data type: String
@ -673,7 +673,7 @@ Specifies the Consul namespace to resolve the service from instead of the curren
Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used.
#### Values
#### Values
- Default: None
- Data type: String
@ -682,7 +682,7 @@ Specifies the Consul admin partition to resolve the service from instead of the
Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Routes[].Match{}.HTTP{}.PathPrefix`](#routes-match-http-pathprefix) or [`Routes[].Match{}.HTTP{}.PathExact`](#routes-match-http-pathexact) be configured on this route.
#### Values
#### Values
- Default: None
- Data type: String
@ -691,7 +691,7 @@ Specifies rewrites to the HTTP request path before proxying it to its final dest
Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts.
#### Values
#### Values
- Default: `0`
- Data type: Integer
@ -700,7 +700,7 @@ Specifies the total amount of time permitted for the entire downstream request t
Specifies the total amount of time permitted for the request stream to be idle.
#### Values
#### Values
- Default: `0`
- Data type: Integer
@ -709,7 +709,7 @@ Specifies the total amount of time permitted for the request stream to be idle.
Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`.
#### Values
#### Values
- Default: `1`
- Data type: Integer
@ -718,7 +718,7 @@ Specifies the number of times to retry the request when a retry condition occurs
Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic).
#### Values
#### Values
- Default: `false`
- Data type: Boolean
@ -766,7 +766,7 @@ The following retry conditions are supported:
Specifies a list of integers for [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) that trigger a retry request. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic)
#### Values
#### Values
- Default: None
- Data type: List of integers
@ -785,10 +785,10 @@ 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 | 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 |
| Rule | Description | 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 |
| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
#### Use variable placeholders
@ -797,7 +797,7 @@ For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the
### `Routes[].Destination{}.ResponseHeaders`
Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`.
Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`.
#### Values
@ -808,12 +808,12 @@ Specifies a set of HTTP-specific header modification rules applied to responses
- `Remove`: Map of one or more string key-value pairs.
The following table describes how to configure values for response headers:
| Rule | Description | 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 |
| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
| Rule | Description | 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 |
| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
#### Use variable placeholders
@ -825,21 +825,21 @@ For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the
### `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`.
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`
### `kind`
Specifies the type of configuration entry to implement.
Specifies the type of configuration entry to implement.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `ServiceRouter`.
- Data type: String value that must be set to `ServiceRouter`.
### `metadata.name`
Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster.
Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster.
#### Values
@ -861,9 +861,9 @@ Map that contains the details about the `ServiceRouter` configuration entry. The
#### Values
- Default: None
- Default: None
- This field is required.
- Data type: Object containing [`spec.routes`](#spec-routes) configuration
- Data type: Object containing [`spec.routes`](#spec-routes) configuration
### `spec.meta`
@ -871,10 +871,10 @@ Specifies key-value pairs to add to the KV store.
#### Values
- Default: none
- Data type: Map of one or more key-value pairs
- Default: none
- Data type: Map of one or more key-value pairs
- keys: String
- values: String, integer, or float
- values: String, integer, or float
### `spec.routes`
@ -1085,7 +1085,7 @@ Specifies that a request matches when the query parameter with the given name is
- Default: None
- Data type: String
### `spec.routes[].match.http.queryParam[].regex`
Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `present` or `exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use.
@ -1122,7 +1122,7 @@ Specifies the target service to route matching requests to, as well as behavior
Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`metadata.name` field](#metadata-name).
#### Values
#### Values
- Default: None
- Data type: String
@ -1131,7 +1131,7 @@ Specifies the name of the service to resolve. If this parameter is not specified
Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used.
#### Values
#### Values
- Default: None
- Data type: String
@ -1140,7 +1140,7 @@ Specifies a named subset of the given service to resolve instead of the one defi
Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used.
#### Values
#### Values
- Default: None
- Data type: String
@ -1149,7 +1149,7 @@ Specifies the Consul namespace to resolve the service from instead of the curren
Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used.
#### Values
#### Values
- Default: None
- Data type: String
@ -1158,7 +1158,7 @@ Specifies the Consul admin partition to resolve the service from instead of the
Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`spec.routes[].match.http.pathPrefix`](#spec-routes-match-http-pathprefix) or [`spec.routes[].match.http.pathExact`](#spec-routes-match-http-pathexact) be configured on this route.
#### Values
#### Values
- Default: None
- Data type: String
@ -1167,7 +1167,7 @@ Specifies rewrites to the HTTP request path before proxying it to its final dest
Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts.
#### Values
#### Values
- Default: `0`
- Data type: Integer
@ -1176,7 +1176,7 @@ Specifies the total amount of time permitted for the entire downstream request t
Specifies the total amount of time permitted for the request stream to be idle.
#### Values
#### Values
- Default: `0`
- Data type: Integer
@ -1185,7 +1185,7 @@ Specifies the total amount of time permitted for the request stream to be idle.
Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `spec.routes.destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`.
#### Values
#### Values
- Default: `1`
- Data type: Integer
@ -1194,7 +1194,7 @@ Specifies the number of times to retry the request when a retry condition occurs
Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `spec.routes[].destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic).
#### Values
#### Values
- Default: `false`
- Data type: Boolean
@ -1242,7 +1242,7 @@ The following retry conditions are supported:
Specifies a list of integers for [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) that trigger a retry request. Configure this field and other retry fields in `spec.routes[].destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic)
#### Values
#### Values
- Default: None
- Data type: List of integers
@ -1261,10 +1261,10 @@ 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 | 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 |
| Rule | Description | 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 |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
#### Use variable placeholders
@ -1284,12 +1284,12 @@ Specifies a set of HTTP-specific header modification rules applied to responses
- `remove`: Map of one or more string key-value pairs.
The following table describes how to configure values for response headers:
| Rule | Description | 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 |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
| Rule | Description | 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 |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
#### Use variable placeholders
@ -1301,7 +1301,7 @@ For `add` and `set`, if the service is configured to use Envoy as the proxy, the
## Examples
The following examples demonstrate common service router configuration patterns for specific use cases.
The following examples demonstrate common service router configuration patterns for specific use cases.
### Path prefix matching
@ -1568,7 +1568,7 @@ spec:
The following example configures Consul so that when a request for the `orders` service passes through the service mesh, Consul routes the traffic to the `products` service or the `procurement` service based on the HTTP path that originated the request:
- If it originates from the `/coffees` path, the request routes to the `products` service, times out after 15 seconds, and attempts 5 retries.
- If it originates from the `/coffees` path, the request routes to the `products` service, times out after 15 seconds, and attempts 5 retries.
- If it originates from the `/orders` path, the request routes to the `procurement` services, times out after 10 seconds, and attempts 3 retries.
Consul Dataplane requires servers running Consul version `v1.14+`. To find a specific version of Consul, refer to [Hashicorp's Official Release Channels](https://www.hashicorp.com/official-release-channels).
Consul Dataplane requires servers running Consul version `v1.14+`. To find a specific version of Consul, refer to [HashiCorp's Official Release Channels](https://www.hashicorp.com/official-release-channels).
@ -12,7 +12,7 @@ Datacenters can reside in different clouds or runtime environments where general
## Prerequisites
Mesh gateways can be used with any of the following Consul configrations for managing separate datacenters or partitions.
Mesh gateways can be used with any of the following Consul configurations for managing separate datacenters or partitions.
1. WAN Federation
* [Mesh gateways can be used to route service-to-service traffic between datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters)
@ -59,7 +59,7 @@ Depending on your network, the proxy's connection to the gateway can operate in
* `none` - No gateway is used and a service mesh sidecar proxy makes its outbound connections directly
to the destination services. This is the default for WAN federation. This setting is invalid for peered clusters
and will be treated as remote instead.
and will be treated as remote instead.
* `local` - The service mesh sidecar proxy makes an outbound connection to a gateway running in the
same datacenter. That gateway is responsible for ensuring that the data is forwarded to gateways in the destination datacenter.
@ -57,7 +57,7 @@ For Consul Enterprise clusters, mesh gateways must be registered in the "default
<Tabs>
<Tab heading="Consul OSS">
In addition to the [ACL Configuration](/consul/docs/connect/cluster-peering/tech-specs#acl-specifications) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings.
In addition to the [ACL Configuration](/consul/docs/connect/cluster-peering/tech-specs#acl-specifications) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings.
This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered datacenter.
@ -79,7 +79,7 @@ peering = "read"
<Tab heading="Consul Enterprise">
In addition to the [ACL Configuration](/consul/docs/connect/cluster-peering/tech-specs#acl-specifications) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings in all partitions.
In addition to the [ACL Configuration](/consul/docs/connect/cluster-peering/tech-specs#acl-specifications) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings in all partitions.
This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered partition.
@ -108,7 +108,7 @@ partition_prefix "" {
### Modes
Connect proxy configuration [Modes](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration#modes) are not applicable to peering control plane traffic.
Connect proxy configuration [Modes](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration#modes) are not applicable to peering control plane traffic.
The flow of control plane traffic through the gateway is implied by the presence of a [Mesh config entry](/consul/docs/connect/config-entries/mesh#peer-through-mesh-gateways) with `PeerThroughMeshGateways = true`.
<CodeTabs heading="Example: Enabling Peering Control Plane Traffic for Mesh Gateways">
@ -122,12 +122,12 @@ Peering {
```yaml
Kind: mesh
Peeering:
Peering:
PeerThroughMeshGateways: true
```
</CodeTabs>
By setting this mesh config on a cluster before [creating a peering token](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#create-a-peering-token), inbound control plane traffic will be sent through the mesh gateway registered this cluster, also known the accepting cluster.
By setting this mesh config on a cluster before [creating a peering token](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#create-a-peering-token), inbound control plane traffic will be sent through the mesh gateway registered this cluster, also known the accepting cluster.
As mesh gateway instances are registered at the accepting cluster, their addresses will be exposed to the dialing cluster over the bi-directional peering stream.
Setting this mesh config on a cluster before [establishing a connection](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#establish-a-connection-between-clusters) will cause the outbound control plane traffic to flow through the mesh gateway.
This topic describes how to create and manage service intentions, which are configurations for controlling access between services in the service mesh.
This topic describes how to create and manage service intentions, which are configurations for controlling access between services in the service mesh.
## Overview
@ -15,14 +15,14 @@ You can create single intentions or create them in batches using the Consul API,
## Requirements
- At least two services must be registered in the datacenter.
- At least two services must be registered in the datacenter.
- TLS must be enabled to enforce L4 intentions. Refer to [Encryption](/consul/docs/security/encryption) for additional information.
### ACL requirements
Consul grants permissions for creating and managing intentions based on the destination, not the source. When ACLs are enabled, services and operators must present a token linked to a policy that grants read and write permissions to the destination service.
Consul grants permissions for creating and managing intentions based on the destination, not the source. When ACLs are enabled, services and operators must present a token linked to a policy that grants read and write permissions to the destination service.
Consul implicitly grants `intentions:read` permissions to destination services when they are configured with `service:read` or `service:write` permissions. This is so that the services can allow or deny inbound connections when they attempt to join the service mesh. Refer to [Service rules](/consul/docs/security/acl/acl-rules#service-rules) for additional information about configuring ALCs for intentions.
Consul implicitly grants `intentions:read` permissions to destination services when they are configured with `service:read` or `service:write` permissions. This is so that the services can allow or deny inbound connections when they attempt to join the service mesh. Refer to [Service rules](/consul/docs/security/acl/acl-rules#service-rules) for additional information about configuring ACLs for intentions.
The default ACL policy configuration determines the default behavior for intentions. If the policy is set to `deny`, then all connections or requests are denied and you must enable them explicitly. Refer to [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) for details.
@ -38,19 +38,19 @@ Send a `PUT` request to the `/connect/intentions/exact` HTTP API endpoint and sp
- `destination`: Service responding to the request
- `ns`: Namespace of the destination service <EnterpriseAlert inline/>
For L4 intentions, you must also specify the intention action in the request payload.
For L4 intentions, you must also specify the intention action in the request payload.
The following example creates an intention that allows `web` to send request to `db`:
The following example creates an intention that allows `web` to send request to `db`:
Refer to the `/connect/intentions/exact` [HTTP API endpoint documentation](/consul/api-docs/connect/intentions) for additional information request payload parameters.
For L7 intentions, specify the `Permissions` in the request payload to configure attributes for dynamically enforcing intentions. In the following example payload, Consul allows HTTP GET requests if the request body is empty:
For L7 intentions, specify the `Permissions` in the request payload to configure attributes for dynamically enforcing intentions. In the following example payload, Consul allows HTTP GET requests if the request body is empty:
<CodeBlockConfig heading="payload.json">
@ -76,18 +76,18 @@ For L7 intentions, specify the `Permissions` in the request payload to configure
</CodeBlockConfig>
The `Permissions` object specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. Refer to the [`Sources[].Permissions[]` parameter](/consul/docs/connect/config-entries/service-intentions#sources-permissions) in the service intentions configuration entry reference for configuration details.
The `Permissions` object specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. Refer to the [`Sources[].Permissions[]` parameter](/consul/docs/connect/config-entries/service-intentions#sources-permissions) in the service intentions configuration entry reference for configuration details.
To apply the intention, call the endpoint and pass the configuration file containing the attributes to the endpoint:
Use the `consul intention create` command according to the following syntax to create a new intention:
Use the `consul intention create` command according to the following syntax to create a new intention:
```shell-session
$ consul intention create -<action> <source> <destination>
@ -99,7 +99,7 @@ The following example creates an intention that allows `web` service instances t
$ consul intention create -allow web db
```
You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-match-order) for additional information.
You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-match-order) for additional information.
### Consul UI
@ -111,7 +111,7 @@ You can use the asterisk (`*`) wildcard to specify multiple destination services
1. **Allow**: Allows the source service to send requests to the destination.
1. **Deny**: Prevents the source service from sending requests to the destination.
1. **Application Aware**: Enables you to specify L7 criteria for dynamically enforcing intentions. Refer to [Configure application aware settings](#configure-application-aware-settings) for additional information.
1. Click **Save**.
1. Click **Save**.
Repeat the procedure as necessary to create additional intentions.
@ -128,7 +128,7 @@ Repeat the procedure as necessary to create additional permissions.
## Create multiple intentions
You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic.
You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic.
### Define a service intention configuration entry
@ -136,7 +136,7 @@ Configure the following fields:
<Tabs>
<Tab heading="HCL" group="hcl">
<Tab heading="HCL" group="hcl">
- [`Kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `service-intentions`.
- [`Name`](/consul/docs/connect/config-entries/service-intentions#kind): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions.
@ -147,7 +147,7 @@ Configure the following fields:
<Tab heading="YAML" group="yaml">
- [`apiVersion`](/consul/docs/connect/config-entries/service-intentions#apiversion): Specifies the Consul API version. Must be set to `consul.hashicorp.com/v1alpha1`.
- [`apiVersion`](/consul/docs/connect/config-entries/service-intentions#apiversion): Specifies the Consul API version. Must be set to `consul.hashicorp.com/v1alpha1`.
- [`kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `ServiceIntentions`.
- [`spec.destination.name`](/consul/docs/connect/config-entries/service-intentions#spec-destination-name): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions.
- [`spec.sources`](/consul/docs/connect/config-entries/service-intentions#spec-sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence.
@ -159,20 +159,20 @@ Configure the following fields:
Refer to the [service intentions configuration entry](/consul/docs/connect/config-entries/service-intentions) reference documentation for details about all configuration options.
Refer to the [example service intentions configurations](/consul/docs/connect/config-entries/service-intentions#examples) for additional guidance.
Refer to the [example service intentions configurations](/consul/docs/connect/config-entries/service-intentions#examples) for additional guidance.
#### Interaction with other configuration entries
L7 intentions defined in a configuration entry are restricted to destination services
configured with an HTTP-based protocol as defined in a corresponding
or globally in a [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults).
### Apply the service intentions configuration entry
You can apply the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `ServiceIntentions` custom resource definitions (CRD) to implement and manage Consul configuration entries.
You can apply the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `ServiceIntentions` custom resource definitions (CRD) to implement and manage Consul configuration entries.
Refer to the following topics for details about applying configuration entries:
Refer to the following topics for details about applying configuration entries:
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)
description: Learn how to configure the wasm Envoy extension, which is a builtin Consul extension that allows you to run WebAssembly plugins in Envoy proxies.
---
# WebAssembly extension configuration reference
# WebAssembly extension configuration reference
This topic describes how to configure the `wasm` extension, which directs Consul to run WebAssembly (Wasm) plugins in Envoy proxies. Refer to [Run WebAssembly plug-ins in Envoy proxy](/consul/docs/connect/proxies/envoy-extensions/usage/wasm) for usage information.
@ -16,15 +16,15 @@ The following list outlines the field hierarchy, data types, and requirements fo
- [`EnvoyExtensions` in service defaults](/consul/docs/connect/config-entries/service-defaults#envoyextensions)
Click on a property name to view additional details, including default values.
@ -56,7 +56,7 @@ Click on a property name to view additional details, including default values.
When all parameters are set for the extension, the configuration has the following form:
```hcl
Protocol = "<tcp or http>"
Protocol = "<tcp or http>"
ListenerType = "<inbound or outbound>"
ProxyType = "connect-proxy"
PluginConfig = {
@ -73,7 +73,7 @@ PluginConfig = {
HttpURI = {
Service = {
Name = "<name of the upstream service>"
Namespace = "<Consul namespace containing the usptream service>"
Namespace = "<Consul namespace containing the upstream service>"
Partition = "<Consul partition containing the upstream service>"
}
URI = "<URI of the plugin data>"
@ -82,19 +82,19 @@ PluginConfig = {
RetryPolicy = {
RetryBackOff = {
BaseInterval = "1s"
MaxInterval = "10s"
MaxInterval = "10s"
}
NumRetries = -1
}
}
Configuration = "<configuration passed to plugin on VM startup>"
EnvironmentVariables = {
HostEnvKeys = [
<"keys">
HostEnvKeys = [
<"keys">
]
KeyValues = {
[
<"key = value">
[
<"key = value">
]
}
}
@ -128,7 +128,7 @@ Specifies the type of Wasm filter to apply. You can set either `tcp` or `http`.
### `ListenerType`
Specifies the type of listener the extension applies to. The listener type is either `inbound` or `outbound`. If the listener type is set to `inbound`, Consul applies the extension so the Wasm plugin is run when other services in the mesh send messages to the service attached to the proxy. If the listener type is set to `outbound`, Consul applies the extension so the Wasm plugin is run when the attached proxy sends messages to other services in the mesh.
Specifies the type of listener the extension applies to. The listener type is either `inbound` or `outbound`. If the listener type is set to `inbound`, Consul applies the extension so the Wasm plugin is run when other services in the mesh send messages to the service attached to the proxy. If the listener type is set to `outbound`, Consul applies the extension so the Wasm plugin is run when the attached proxy sends messages to other services in the mesh.
#### Values
@ -146,7 +146,7 @@ Specifies the type of Envoy proxy that the extension applies to. The only suppor
- Default: `connect-proxy`
- This field is required.
- Data type: String
- Data type: String
### `PluginConfig{}`
@ -208,7 +208,7 @@ Specifies an ID that Envoy uses with a hash of the Wasm code to determine which
### `PluginConfig{}.VmConfig{}.Runtime`
Specifies the type of Wasm runtime.
Specifies the type of Wasm runtime.
#### Values
- Default: `v8`
@ -225,7 +225,7 @@ Map containing one of the following configuration parameters:
- [`Local`](#pluginconfig-vmconfig-code-local)
- [`Remote`](#pluginconfig-vmconfig-code-local)
You can configure either `Local` or `Remote`, but not both. The `Code` block instructs Consul how to find the Wasm plugin code for Envoy to execute.
You can configure either `Local` or `Remote`, but not both. The `Code` block instructs Consul how to find the Wasm plugin code for Envoy to execute.
#### Values
@ -237,9 +237,9 @@ You can configure either `Local` or `Remote`, but not both. The `Code` block ins
### `PluginConfig{}.VmConfig{}.Code{}.Local{}`
Instructs Envoy to load the plugin code from a local volume. Do not configure the `Local` parameter if the plugin code is on a remote server.
Instructs Envoy to load the plugin code from a local volume. Do not configure the `Local` parameter if the plugin code is on a remote server.
The `Local` field is a map that contains a `Filename` parameter. The `Filename` parameter takes a string value that specifies the path to the plugin on the local file system.
The `Local` field is a map that contains a `Filename` parameter. The `Filename` parameter takes a string value that specifies the path to the plugin on the local file system.
Local plug-ins are not supported in Kubernetes-orchestrated environments.
@ -250,7 +250,7 @@ Local plug-ins are not supported in Kubernetes-orchestrated environments.
### `PluginConfig{}.VmConfig{}.Code{}.Remote{}`
Instructs Envoy to load the plugin code from a remote server. Do not configure the `Remote` parameter if the plugin code is on the local VM.
Instructs Envoy to load the plugin code from a remote server. Do not configure the `Remote` parameter if the plugin code is on the local VM.
The `Remote` field is a map containing the following parameters:
@ -278,7 +278,7 @@ Specifies the configuration for fetching the remote data. The `HttpURI` field is
Specifies the URI Envoy uses to fetch the plugin file from the upstream. This field is required for Envoy to retrieve plugin code from a remote location. You must specify the fully-qualified domain name (FDQN) of the remote URI, which includes the protocol, host, and path.
Specifies the URI Envoy uses to fetch the plugin file from the upstream. This field is required for Envoy to retrieve plugin code from a remote location. You must specify the fully-qualified domain name (FQDN) of the remote URI, which includes the protocol, host, and path.
Specifies environment variables for Enovy to inject into this VM so that they are available through WASI's `environ_get` and `environ_get_sizes` system calls.
Specifies environment variables for Envoy to inject into this VM so that they are available through WASI's `environ_get` and `environ_get_sizes` system calls.
In most cases, WASI calls the functions implicitly in your language's standard library. As a result, you do not need to call them directly. You can also access environment variables as you would on native platforms.
In most cases, WASI calls the functions implicitly in your language's standard library. As a result, you do not need to call them directly. You can also access environment variables as you would on native platforms.
Envoy rejects the configuration if there is a key space conflict.
@ -401,16 +401,16 @@ Specifies the configuration Consul encodes as bytes and passes to the plugin dur
Specifies a configuration for restricting the proxy-Wasm capabilities that are available to the module.
Specifies a configuration for restricting the proxy-Wasm capabilities that are available to the module.
The `CapabilityRestrictionConfiguration` field is a map that contains a `AllowedCapabilities` parameter. The `AllowedCapabilities` parameter takes a map of string values that correspond to Envoy capability names. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) for additional information.
!> **Security warning**: Consul ignores the value that each capability maps to. You can leave the `AllowedCapabilities` empty to allow all capabilities, but doing so gives the configured plugin full unrestricted access to the runtime API provided by the Wasm VM. You must set this to a non-empty map if you want to restrict access to specific capabilities provided by the Wasm runtime API.
!> **Security warning**: Consul ignores the value that each capability maps to. You can leave the `AllowedCapabilities` empty to allow all capabilities, but doing so gives the configured plugin full unrestricted access to the runtime API provided by the Wasm VM. You must set this to a non-empty map if you want to restrict access to specific capabilities provided by the Wasm runtime API.
#### Values
- Default: `""`
- Data type is a map containing the `AllowedCapabilities` parameter. The `AllowedCapabilities` parameter takes a map of string values that correspond to Envoy capability names. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) for additional information.
- Data type is a map containing the `AllowedCapabilities` parameter. The `AllowedCapabilities` parameter takes a map of string values that correspond to Envoy capability names. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) for additional information.
## Examples
@ -453,7 +453,7 @@ EOF
### Run a Wasm plugin from a remote file
In the following example, Consul configures the Envoy proxy for all HTTP services with an HTTP Wasm filter. The filter uses the plugin code from a remote `https://extension-server/waf.wasm` file. The Envoy proxy for each service fetches the remote file and verify the SHA256 checksum. The proxy times if Consul cannot fetch the remote plugin after three seconds.
In the following example, Consul configures the Envoy proxy for all HTTP services with an HTTP Wasm filter. The filter uses the plugin code from a remote `https://extension-server/waf.wasm` file. The Envoy proxy for each service fetches the remote file and verify the SHA256 checksum. The proxy times if Consul cannot fetch the remote plugin after three seconds.
Learn how Envoy extensions enables you to add support for additional Envoy features without modifying the Consul codebase.
Learn how Envoy extensions enables you to add support for additional Envoy features without modifying the Consul codebase.
---
# Envoy extensions overview
@ -24,7 +24,7 @@ Envoy extensions enable additional service mesh functionality in Consul by chang
- Lua
- Lambda
- Property override
- WebAssembly (Wasm)
- WebAssembly (Wasm)
### External authorization
@ -44,4 +44,4 @@ The `property-override` extension lets you set and unset individual properties o
### WebAssembly
The `wasm` extension enables you to configure TCP and HTTP filters that invoke custom WebAssembly (Wasm) plugins. Refer to the [WebAssembly extenstion documentation](/consul/docs/connect/proxies/envoy-extensions/usage/wasm) for more information.
The `wasm` extension enables you to configure TCP and HTTP filters that invoke custom WebAssembly (Wasm) plugins. Refer to the [WebAssembly extension documentation](/consul/docs/connect/proxies/envoy-extensions/usage/wasm) for more information.
@ -45,9 +45,9 @@ Consul supports **four major Envoy releases** at the beginning of each major Con
### Envoy and Consul Dataplane
The Consul dataplane component was introduced in Consul v1.14 as a way to manage Envoy proxies without the use of Consul clients. Each new minor version of Consul is released with a new minor version of Consul dataplane, which packages both Envoy and the `consul-dataplane` binary in a single container image. For backwards compatability reasons, each new minor version of Consul will also support the previous minor version of Consul dataplane to allow for seamless upgrades. In addition, each minor version of Consul will support the next minor version of Consul dataplane to allow for extended dataplane support via newer versions of Envoy.
The Consul dataplane component was introduced in Consul v1.14 as a way to manage Envoy proxies without the use of Consul clients. Each new minor version of Consul is released with a new minor version of Consul dataplane, which packages both Envoy and the `consul-dataplane` binary in a single container image. For backwards compatibility reasons, each new minor version of Consul will also support the previous minor version of Consul dataplane to allow for seamless upgrades. In addition, each minor version of Consul will support the next minor version of Consul dataplane to allow for extended dataplane support via newer versions of Envoy.
| Consul Version | Default `consul-dataplane` Version | Other compatible `consul-dataplane` Versions |
| Consul Version | Default `consul-dataplane` Version | Other compatible `consul-dataplane` Versions |
@ -194,7 +194,7 @@ the [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block
- `envoy_telemetry_collector_bind_socket_dir` - Specifies the directory where Envoy creates a Unix socket.
Envoy sends metrics to the socket where a Consul telemetry collector can collect them.
The socket is not configured by default.
The [Advanced Configuration](#advanced-configuration) section describes additional configurations that allow incremental or complete control over the bootstrap configuration generated.
### Bootstrap Envoy on Windows VMs
@ -204,7 +204,7 @@ The [Advanced Configuration](#advanced-configuration) section describes addition
If you are running Consul on a Windows VM, attempting to bootstrap Envoy with the `consul connect envoy` command returns the following output:
```shell-session hideClipboard
Directly running Envoy is only supported on linux and macOS since envoy itself doesn't build on other plataforms currently.
Directly running Envoy is only supported on linux and macOS since envoy itself doesn't build on other platforms currently.
Use the -bootstrap option to generate the JSON to use when running envoy on a supported OS or via a container or VM.
```
@ -420,10 +420,10 @@ definition](/consul/docs/connect/registration/service-registration) or
- `max_ejection_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.
- `base_ejection_time` - 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
speficied, inherits Envoy's default value of 30s.
- `base_ejection_time` - 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.
- `balance_outbound_connections` - Specifies the strategy for balancing outbound connections
across Envoy worker threads. Consul service mesh Envoy integration supports the
page_title: Consul compared to other service meshes
description: >-
Consul's service mesh provides zero trust networking based on service identities to authorize, authenticate, and encrypt network services. Consul's service mesh can also provide advanced traffic management capabilties. Although there are many similar capabilities between Consul and other providers like Istio, Solo, Linkerd, Kong, Tetrate, and AWS App Mesh, we highlight the main differentiating factors for help customers compare.
Consul's service mesh provides zero trust networking based on service identities to authorize, authenticate, and encrypt network services. Consul's service mesh can also provide advanced traffic management capabilities. Although there are many similar capabilities between Consul and other providers like Istio, Solo, Linkerd, Kong, Tetrate, and AWS App Mesh, we highlight the main differentiating factors for help customers compare.
---
# Consul compared to other service mesh software
**Examples**: Istio, Solo Gloo Mesh, Linkerd, Kong/Kuma, AWS App Mesh
Consul’s service mesh allows organizations to securely connect and manage their network services across multiple different environments. Using Envoy as the sidecar proxy attached to every service, Consul ensures that all service-to-service communication is authorized, authenticated, and encrypted. Consul includes traffic management capabilities like load balancing and traffic splitting, which help developers perform canary testing, A/B tests, and blue/green deployments. Consul also includes health check and observability features.
Consul’s service mesh allows organizations to securely connect and manage their network services across multiple different environments. Using Envoy as the sidecar proxy attached to every service, Consul ensures that all service-to-service communication is authorized, authenticated, and encrypted. Consul includes traffic management capabilities like load balancing and traffic splitting, which help developers perform canary testing, A/B tests, and blue/green deployments. Consul also includes health check and observability features.
Consul is platform agnostic — it supports any runtime (Kubernetes, EKS, AKS, GKE, VMs, ECS, Lambda, Nomad) and any cloud provider (AWS, Microsoft Azure, GCP, private clouds). This makes it one of the most flexible service discovery and service mesh platforms. While other service mesh software provides support for multiple runtimes for the data plane, they require you to run the control plane solely on Kubernetes. With Consul, you can run both the control plane and data plane in different runtimes.
page_title: Consul on AWS Elastic Container Service (ECS) Compatability Matrix
page_title: Consul on AWS Elastic Container Service (ECS) Compatibility Matrix
description: >-
The binary for Consul on Amazon Web Services ECS and the Terraform modules for automating deployments are tightly coupled and have specific version requirements. Review compatibility information for versions of Consul and `consul-ecs` to help you choose compatible versions.
---
# Consul on AWS Elastic Container Service (ECS) compatability matrix
# Consul on AWS Elastic Container Service (ECS) compatibility matrix
For every release of Consul on ECS, the `consul-ecs` binary and `consul-ecs` Terraform module are updated. The versions of the Terraform module and binary are tightly coupled. For example, `consul-ecs` 0.5.2 binary must use the `consul-ecs` 0.5.2 Terraform module.
Consul Enterprise is a paid offering that extends Consul’s open source functions to support large and complex deployments. Learn about scaling infrastructure, simplifying operations, and making networks more resilient with Enterprise. Evaluate Enteprise features with the feature availability and compatibility matrix.
Consul Enterprise is a paid offering that extends Consul’s open source functions to support large and complex deployments. Learn about scaling infrastructure, simplifying operations, and making networks more resilient with Enterprise. Evaluate Enterprise features with the feature availability and compatibility matrix.
---
# Consul Enterprise
@ -45,7 +45,7 @@ The following features are [available in several forms of Consul Enterprise](#co
### Governance
- [OIDC Auth Method](/consul/docs/security/acl/auth-methods/oidc): Manage user access to Consul through an OIDC identity provider instead of Consul ACL tokens directly
- [Audit Logging](/consul/docs/enterprise/audit-logging): Understand Consul access and usage patterns by reviewing access to the Consul HTTP API
- [Audit Logging](/consul/docs/enterprise/audit-logging): Understand Consul access and usage patterns by reviewing access to the Consul HTTP API
@ -29,7 +29,7 @@ Download a supported release from the [Consul Versions](https://releases.hashico
## Enable automated reporting
Before you enable automated reporting, make sure that outbound network traffic is configured correctly and upgrade your enterprise product to a version that supports it. If your installation is air-gapped or network settings are not in place, automated reporting will not work.
Before you enable automated reporting, make sure that outbound network traffic is configured correctly and upgrade your enterprise product to a version that supports it. If your installation is air-gapped or network settings are not in place, automated reporting will not work.
To enable automated reporting, complete the following steps:
@ -38,7 +38,7 @@ To enable automated reporting, complete the following steps:
### Allow outbound HTTPS traffic on port 443
Make sure that your network allows HTTPS egress on port 443 from `https://reporting.hashicorp.services` by adding the following IP adddresses to your allow-list:
Make sure that your network allows HTTPS egress on port 443 from `https://reporting.hashicorp.services` by adding the following IP addresses to your allow-list:
- `100.20.70.12`
- `35.166.5.222`
@ -67,7 +67,7 @@ Automatic license utilization reporting starts sending data within roughly 24 ho
</CodeBlockConfig>
If your installation is air-gapped or your network does not allow the correct egress, the logs show an error.
If your installation is air-gapped or your network does not allow the correct egress, the logs show an error.
<CodeBlockConfig hideClipboard>
@ -84,17 +84,17 @@ If your installation is air-gapped or your network does not allow the correct eg
</CodeBlockConfig>
In this case, reconfigure your network to allow egress and check the logs again in roughly 24 hours to confirm that automated reporting works correctly.
In this case, reconfigure your network to allow egress and check the logs again in roughly 24 hours to confirm that automated reporting works correctly.
## Opt out
If your installation is air-gapped or you want to manually collect and report on the same license utilization metrics, you can opt out of automated reporting.
If your installation is air-gapped or you want to manually collect and report on the same license utilization metrics, you can opt out of automated reporting.
Manually reporting these metrics can be time consuming. Opting out of automated reporting does not mean that you also opt out from sending license utilization metrics. Customers who opt out of automated reporting are still required to manually collect and send license utilization metrics to HashiCorp.
Manually reporting these metrics can be time consuming. Opting out of automated reporting does not mean that you also opt out from sending license utilization metrics. Customers who opt out of automated reporting are still required to manually collect and send license utilization metrics to HashiCorp.
If you are considering opting out because you are worried about the data, we strongly recommend that you review the [example payloads](#example-payloads) before opting out. If you have concerns with any of the automatically reported data, raise these concerns with your account manager.
If you are considering opting out because you are worried about the data, we strongly recommend that you review the [example payloads](#example-payloads) before opting out. If you have concerns with any of the automatically reported data, raise these concerns with your account manager.
There are two methods for opting out of automated reporting:
There are two methods for opting out of automated reporting:
- HCL configuration (recommended)
- Environment variable (requires restart)
@ -130,7 +130,7 @@ Check your product logs roughly 24 hours after opting out to make sure that the
## Example payloads
HashiCorp collects the following utilization data as JSON payloads:
HashiCorp collects the following utilization data as JSON payloads:
`exporter_version` - The version of the licensing exporter
<CodeBlockConfig hideClipboard>
@ -172,4 +172,4 @@ HashiCorp collects the following utilization data as JSON payloads:
This topic describes how to create Consul network segments so that services can connect to other services in the LAN gossip pool that have been placed into separate communication boundaries. Refer to [Network Segments Overview](/consul/docs/enterprise/network-segments/network-segments-overview) for additional information.
This topic describes how to create Consul network segments so that services can connect to other services in the LAN gossip pool that have been placed into separate communication boundaries. Refer to [Network Segments Overview](/consul/docs/enterprise/network-segments/network-segments-overview) for additional information.
## Requirements
- Consul Enterprise 0.9.3+
- Consul Enterprise 0.9.3+
## Define segments in the server configuration
## Define segments in the server configuration
1. Add the `segments` block to your server configuration. Refer to the [`segments`](/consul/docs/agent/config/config-files#segments) documentation for details about how to define the configuration.
1. Add the `segments` block to your server configuration. Refer to the [`segments`](/consul/docs/agent/config/config-files#segments) documentation for details about how to define the configuration.
In the following example, an `alpha` segment is configured to listen for traffic on port `8303` and a `beta` segment is configured to listen to traffic on port `8304`:
@ -57,7 +57,7 @@ This topic describes how to create Consul network segments so that services can
]
}
```
</CodeTabs>
1. Start the server using the `consul agent` command. Copy the address for each segment listener so that you can [direct clients to join the segment](#configure-clients-to-join-segments) when you start them:
@ -71,7 +71,7 @@ This topic describes how to create Consul network segments so that services can
[INFO] consul: Started listener for LAN segment "beta" on 10.20.10.11:8304
[INFO] serf: EventMemberJoin: server1 10.20.10.11
```
1. Verfiy that the server is a member of all segments:
1. Verify that the server is a member of all segments:
```shell-session
$ consul members
@ -118,7 +118,7 @@ server 192.168.4.159:8301 alive server 1.14+ent 2 dc1 defaul
You can also pass the name of a segment in the `-segment` flag to view agents in a specific segment. Note that server agents display their LAN listener port for the specified segment the segment filter applied. In the following example, the command returns port `8303` for alpha, rather than for the `<default>` segment port:
@ -179,7 +179,7 @@ Refer to the [`/agent/members` API endpoint documentation](/consul/api-docs/agen
</Tab>
<Tab heading="UI">
If the UI is enabled in your agent configuration, the segment name appears in the node’s Metadata tab.
If the UI is enabled in your agent configuration, the segment name appears in the node’s Metadata tab.
1. Open the URL for the UI. By default, the UI is `localhost:8500`.
1. Click **Node** in the sidebar and click on the name of the client agent you want to check.
@ -191,4 +191,4 @@ If the UI is enabled in your agent configuration, the segment name appears in th
## Related resources
You can also create and run a prepared query to query for additional information about the services registered to client nodes. Prepared queries are HTTP API endpoint features that enable you to run complex queries of Consul nodes. Refer [Prepared Query HTTP Endpoint](/consul/api-docs/query) for usage.
You can also create and run a prepared query to query for additional information about the services registered to client nodes. Prepared queries are HTTP API endpoint features that enable you to run complex queries of Consul nodes. Refer [Prepared Query HTTP Endpoint](/consul/api-docs/query) for usage.
@ -13,11 +13,11 @@ Consul service mesh automates service-to-service authorization and encryption ac
Consul service mesh is enabled by default when you install Consul on Kubernetes using the Consul Helm chart. Consul also automatically injects sidecars into the pods in your clusters that run Envoy. These sidecar proxies, called Consul dataplanes, are enabled when `connectInject.default` is set to `false` in the Helm chart. Refer to the following documentation for additional information about these concepts:
- [Installation and Configuration](#installation-and-configuration) in this topic
- [Installation and Configuration](#installation-and-configuration) in this topic
- [Simplified Service Mesh with Consul Dataplane](/consul/docs/connect/dataplane)
If `connectInject.default` is set to `false` or you want to explicitly enable service mesh sidecar proxy injection for a specific deployment, add the `consul.hashicorp.com/connect-inject` annotation to the pod specification template and set it to `true` when connecting services to the mesh.
If `connectInject.default` is set to `false` or you want to explicitly enable service mesh sidecar proxy injection for a specific deployment, add the `consul.hashicorp.com/connect-inject` annotation to the pod specification template and set it to `true` when connecting services to the mesh.
### Service names
@ -25,13 +25,13 @@ When the service is onboarded, the name registered in Consul is set to the name
### Transparent proxy mode
By default, the Consul service mesh runs in transparent proxy mode. This mode forces inbound and outbound traffic through the sidecar proxy even though the service binds to all interfaces. Transparent proxy infers the location of upstream services using Consul service intentions, and also allows you to use Kubernetes DNS as you normally would for your workloads.
By default, the Consul service mesh runs in transparent proxy mode. This mode forces inbound and outbound traffic through the sidecar proxy even though the service binds to all interfaces. Transparent proxy infers the location of upstream services using Consul service intentions, and also allows you to use Kubernetes DNS as you normally would for your workloads.
When transparent proxy mode is enabled, all service-to-service traffic is required to use mTLS. When onboarding new services to service mesh, your network may have mixed mTLS and non-mTLS traffic, which can result in broken service-to-service communication. You can temporarily enable permissive mTLS mode during the onboarding process so that existing mesh services can accept traffic from services that are not yet fully onboarded. Permissive mTLS enables sidecar proxies to access both mTLS and non-mTLS traffic. Refer to [Onboard mesh services in transparent proxy mode](/consul/docs/k8s/connect/onboarding-tproxy-mode) for additional information.
### Kubernetes service mesh workload scenarios
### Kubernetes service mesh workload scenarios
-> **Note:** A Kubernetes Service is required in order to register services on the Consul service mesh. Consul monitors the lifecyle of the Kubernetes Service and its service instances using the service object. In addition, the Kubernetes service is used to register and de-register the service from Consul's catalog.
-> **Note:** A Kubernetes Service is required in order to register services on the Consul service mesh. Consul monitors the lifecycle of the Kubernetes Service and its service instances using the service object. In addition, the Kubernetes service is used to register and de-register the service from Consul's catalog.
The following configurations are examples for registering workloads on Kubernetes into Consul's service mesh in different scenarios. Each scenario provides an example Kubernetes manifest to demonstrate how to use Consul's service mesh with a specific Kubernetes workload type.
@ -42,7 +42,7 @@ The following configurations are examples for registering workloads on Kubernete
#### Kubernetes Pods running as a deployment
The following example shows a Kubernetes configuration that specifically enables service mesh connections for the `static-server` service. Consul starts and registers a sidecar proxy that listens on port 20000 by default and proxies valid inbound connections to port 8080.
The following example shows a Kubernetes configuration that specifically enables service mesh connections for the `static-server` service. Consul starts and registers a sidecar proxy that listens on port 20000 by default and proxies valid inbound connections to port 8080.
<CodeBlockConfig filename="static-server.yaml">
@ -192,7 +192,7 @@ command terminated with exit code 52
Kubernetes Jobs run pods that only make outbound requests to services on the mesh and successfully terminate when they are complete. In order to register a Kubernetes Job with the mesh, you must provide an integer value for the `consul.hashicorp.com/sidecar-proxy-lifecycle-shutdown-grace-period-seconds` annotation. Then, issue a request to the `http://127.0.0.1:20600/graceful_shutdown` API endpoint so that Kubernetes gracefully shuts down the `consul-dataplane` sidecar after the job is complete.
Below is an example Kubernetes manifest that deploys a job correctly.
Below is an example Kubernetes manifest that deploys a job correctly.
Upon completing the job you should be able to verify that all containers are shut down within the pod.
```shell-session
$ kubectl get pods
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
test-job-49st7 0/2 Completed 0 3m55s
```
```shell-session
```shell-session
$ kubectl get job
NAME COMPLETIONS DURATION AGE
test-job 1/1 30s 4m31s
```
In addition, based on the logs emitted by the pod you can verify that the proxy was shut down before the Job completed.
In addition, based on the logs emitted by the pod you can verify that the proxy was shut down before the Job completed.
```shell-session
$ kubectl logs test-job-49st7 -c test-job
@ -382,7 +382,7 @@ The service account on the pod spec for the deployment should be set to the firs
serviceAccountName: web
```
The following deployment example demonstrates the required annotations for the manifest. In addition, the previous YAML manifests can also be combined into a single manifest for easier deployment.
The following deployment example demonstrates the required annotations for the manifest. In addition, the previous YAML manifests can also be combined into a single manifest for easier deployment.
@ -414,7 +414,7 @@ Use these links to navigate to a particular top-level stanza.
- `secretKey` ((#v-global-acls-replicationtoken-secretkey)) (`string: null`) - The key within the Kubernetes or Vault secret that holds the replication token.
- `resources` ((#v-global-acls-resources)) (`map`) - The resource requests (CPU, memory, etc.) for the server-acl-init and server-acl-init-cleanup pods.
- `resources` ((#v-global-acls-resources)) (`map`) - The resource requests (CPU, memory, etc.) for the server-acl-init and server-acl-init-cleanup pods.
This should be a YAML map corresponding to a Kubernetes
@ -120,7 +120,7 @@ to update to the new version. Before you upgrade to a new version:
</CodeBlockConfig>
2. Determine the version of your exisiting Helm installation. In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used.
2. Determine the version of your existing Helm installation. In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used.
```shell-session
$ helm list --filter consul --namespace consul
@ -174,7 +174,7 @@ that can be used.
1. Take specific note if `consul-server, StatefulSet` is listed, as it means your Consul server statefulset will be redeployed.
If your Consul server statefulset needs to be redeployed, follow the same pattern for upgrades as
on other platforms by redploying servers one by one. Refer tp [Upgrading Consul](/consul/docs/upgrading) for more information.
on other platforms by redeploying servers one by one. Refer tp [Upgrading Consul](/consul/docs/upgrading) for more information.
If neither the server statefulset is not being redeployed,
then you can continue with the Helm upgrade without any specific sequence to follow.
@ -258,7 +258,7 @@ If you upgrade Consul from a version that uses client agents to a version the us
1. If ACLs are enabled, outdated ACL tokens will persist a result of the upgrade. You can manually delete the tokens to declutter your Consul environment.
Outdated connect-injector tokens have the following description: `token created via login: {"component":"connect-injector"}`. Do not delete
the tokens that have a description where `pod` is a key, for example `token created via login: {"component":"connect-injector","pod":"default/consul-connect-injector-576b65747c-9547x"}`). The dataplane-enabled connect inject pods use these tokens.
the tokens that have a description where `pod` is a key, for example `token created via login: {"component":"connect-injector","pod":"default/consul-connect-injector-576b65747c-9547x"}`). The dataplane-enabled connect inject pods use these tokens.
You can also review the creation date for the tokens and only delete the injector tokens created before your upgrade, but do not delete all old tokens without considering if they are still in use. Some tokens, such as the server tokens, are still necessary.
@ -31,19 +31,19 @@ For information on compatible Consul versions, refer to the [Consul compatibilit
### Run an agent
The Consul agent must be running in order to dynamically update network devices. Refer to the [Consul agent documentation](/consul/docs/agent) for information about configuring and starting a Consul agent.
The Consul agent must be running in order to dynamically update network devices. Refer to the [Consul agent documentation](/consul/docs/agent) for information about configuring and starting a Consul agent.
When running a Consul agent with CTS in production, consider that CTS uses [blocking queries](/consul/api-docs/features/blocking) to monitor task dependencies, such as changes to registered services. This results in multiple long-running TCP connections between CTS and the agent to poll changes for each dependency. Consul may quickly reach the agent connection limits if CTS is monitoring a high number of services.
To avoid reaching the limit prematurely, we recommend using HTTP/2 (requires HTTPS) to communicate between CTS and the Consul agent. When using HTTP/2, CTS establishes a single connection and reuses it for all communication. Refer to the [Consul Configuration section](/consul/docs/nia/configuration#consul) for details.
To avoid reaching the limit prematurely, we recommend using HTTP/2 (requires HTTPS) to communicate between CTS and the Consul agent. When using HTTP/2, CTS establishes a single connection and reuses it for all communication. Refer to the [Consul Configuration section](/consul/docs/nia/configuration#consul) for details.
Alternatively, you can configure the [`limits.http_max_conns_per_client`](/consul/docs/agent/config/config-files#http_max_conns_per_client) option to set a maximimum number of connections to meet your needs.
Alternatively, you can configure the [`limits.http_max_conns_per_client`](/consul/docs/agent/config/config-files#http_max_conns_per_client) option to set a maximum number of connections to meet your needs.
### Register services
CTS monitors the Consul catalog for service changes that lead to downstream changes to your network devices. Without services, your CTS daemon is operational but idle. You can register services with your Consul agent by either loading a service definition or by sending an HTTP API request.
The following HTTP API request example registers a service named `web` with your Consul agent:
The following HTTP API request example registers a service named `web` with your Consul agent:
```shell-session
$ echo '{
@ -56,7 +56,7 @@ $ echo '{
$ curl --request PUT --data @payload.json http://localhost:8500/v1/agent/service/register
```
The example represents a non-existent web service running at `10.10.10.10:8000` that is now available for CTS to consume.
The example represents a non-existent web service running at `10.10.10.10:8000` that is now available for CTS to consume.
You can configure CTS to monitor the web service, execute a task, and update network device(s) by configuring `web` in the [`condition "services"`](/consul/docs/nia/configuration#services-condition) task block. If the web service has any non-default values, it can also be configured in `condition "services"`.
@ -80,8 +80,8 @@ To find providers for the infrastructure platforms you use, browse the providers
If a Terraform provider does not exist for your environment, you can create a new Terraform provider and publish it to the registry so that you can use it within a network integration task or create a compatible Terraform module. Refer to the following Terraform tutorial and documentation for additional information on creating and publishing providers:
- [Setup and Implement Read](/terraform/tutorials/providers/provider-setup)
# Run Consul-Terraform-Sync with high availability
<EnterpriseAlert>
An enterpise license is only required for enterprise distributions of Consul-Terraform-Sync (CTS).
An enterprise license is only required for enterprise distributions of Consul-Terraform-Sync (CTS).
</EnterpriseAlert>
This topic describes how to run Consul-Terraform-Sync (CTS) configured for high availability. High availability is an enterprise capability that ensures that all changes to Consul that occur during a failover transition are processed and that CTS continues to operate as expected.
@ -18,10 +18,10 @@ This topic describes how to run Consul-Terraform-Sync (CTS) configured for high
A network always has exactly one instance of the CTS cluster that is the designated leader. The leader is responsible for monitoring and running tasks. If the leader fails, CTS triggers the following process when it is configured for high availability:
1. The CTS cluster promotes a new leader from the pool of followers in the network.
1. The new leader begins running all existing tasks in `once-mode` in order to process changes that occurred during the failover transition period. In this mode, CTS runs all existing tasks one time.
1. The new leader logs any errors that occur during `once-mode` operation and the new leader continues to monitor Consul for changes.
1. The new leader begins running all existing tasks in `once-mode` in order to process changes that occurred during the failover transition period. In this mode, CTS runs all existing tasks one time.
1. The new leader logs any errors that occur during `once-mode` operation and the new leader continues to monitor Consul for changes.
In a standard configuration, CTS exits if errors occur when the CTS instance runs tasks in `once-mode`. In a high availability configuration, CTS logs the errors and continues to operate without interruption.
In a standard configuration, CTS exits if errors occur when the CTS instance runs tasks in `once-mode`. In a high availability configuration, CTS logs the errors and continues to operate without interruption.
The following diagram shows operating state when high availability is enabled. CTS Instance A is the current leader and is responsible for monitoring and running tasks:
@ -36,28 +36,28 @@ The following diagram shows the CTS cluster state after the leader stops. CTS In
- The time it takes for a new leader to be elected is determined by the `high_availability.cluster.storage.session_ttl` configuration. The minimum failover time is equal to the `session_ttl` value. The maximum failover time is double the `session_ttl` value.
- If failover occurs during task execution, a new leader is elected. The new leader will attempt to run all tasks once before continuing to monitor for changes.
- If using the [Terraform Cloud (TFC) driver](/consul/docs/nia/network-drivers/terraform-cloud), the task finishes and CTS starts a new leader that attempts to queue a run for each task in TFC in once-mode.
- If using [Terraform driver](/consul/docs/nia/network-drivers/terraform), the task may complete depending on the cause of the failover. The new leader starts and attempts to run each task in [once-mode](/consul/docs/nia/cli/start#modes). Depending on the module and provider, the task may require manual intervention to fix any inconsistencies between the infrastructure and Terraform state.
- If using [Terraform driver](/consul/docs/nia/network-drivers/terraform), the task may complete depending on the cause of the failover. The new leader starts and attempts to run each task in [once-mode](/consul/docs/nia/cli/start#modes). Depending on the module and provider, the task may require manual intervention to fix any inconsistencies between the infrastructure and Terraform state.
- If failover occurs when no task is executing, CTS elects a new leader that attempts to run all tasks in once-mode.
Note that driver behavior is consistent whether or not CTS is running in high availability mode.
## Requirements
Verify that you have met the [basic requirements](/consul/docs/nia/usage/requirements) for running CTS.
Verify that you have met the [basic requirements](/consul/docs/nia/usage/requirements) for running CTS.
* CTS Enterprise 0.7 or later
* Terraform CLI 0.13 or later
* All instances in a cluster must be in the same datacenter.
You must configure appropriate ACL permissions for your cluster. Refer to [ACL permissions](#) for details.
You must configure appropriate ACL permissions for your cluster. Refer to [ACL permissions](#) for details.
We recommend specifying the [TFC driver](/consul/docs/nia/network-drivers/terraform-cloud) in your CTS configuration if you want to run in high availability mode.
We recommend specifying the [TFC driver](/consul/docs/nia/network-drivers/terraform-cloud) in your CTS configuration if you want to run in high availability mode.
## Configuration
Add the `high_availability` block in your CTS configuration and configure the required settings to enable high availability. Refer to the [Configuration reference](/consul/docs/nia/configuration#high-availability) for details about the configuration fields for the `high_availability` block.
Add the `high_availability` block in your CTS configuration and configure the required settings to enable high availability. Refer to the [Configuration reference](/consul/docs/nia/configuration#high-availability) for details about the configuration fields for the `high_availability` block.
The following example configures high availability functionality for a cluster named `cts-cluster`:
The following example configures high availability functionality for a cluster named `cts-cluster`:
<CodeBlockConfig filename="cts-config.hcl">
@ -83,17 +83,17 @@ high_availability {
The `session` and `keys` resources in your Consul environment must have `write` permissions. Refer to the [ACL documentation](/consul/docs/security/acl) for details on how to define ACL policies.
If the `high_availability.cluster.storage.namespace` field is configured, then your ACL policy must also enable `write` permissions for the `namespace` resource.
If the `high_availability.cluster.storage.namespace` field is configured, then your ACL policy must also enable `write` permissions for the `namespace` resource.
## Start a new CTS cluster
## Start a new CTS cluster
We recommend deploying a cluster that includes three CTS instances. This is so that the cluster has one leader and two followers.
1. Create an HCL configuration file that includes the settings you want to include, including the `high_availability` block. Refer to [Configuration Options for Consul-Terraform-Sync](/consul/docs/nia/configuration) for all configuration options.
1. Issue the startup command and pass the configuration file. Refer to the [`start` command reference](/consul/docs/nia/cli/start#modes) for additional information about CTS startup modes.
1. Issue the startup command and pass the configuration file. Refer to the [`start` command reference](/consul/docs/nia/cli/start#modes) for additional information about CTS startup modes.
1. You can call the `/status` API endpoint to verify the status of tasks CTS is configured to monitor. Only the leader of the cluster will return a successful response. Refer to the [`/status` API reference documentation](/consul/docs/nia/api/status) for information about usage and responses.
```shell-session
@ -102,9 +102,9 @@ We recommend deploying a cluster that includes three CTS instances. This is so t
Repeat the procedure to start the remaining instances for your cluster. We recommend using near-identical configurations for all instances in your cluster. You may not be able to use exact configurations in all cases, but starting instances with the same configuration improves consistency and reduces confusion if you need to troubleshoot errors.
## Modify an instance configuration
## Modify an instance configuration
You can implement a rolling update to update a non-task configuration for a CTS instance, such as the Consul connection settings. If you need to update a task in the instance configuration, refer to [Modify tasks](#modify-tasks).
You can implement a rolling update to update a non-task configuration for a CTS instance, such as the Consul connection settings. If you need to update a task in the instance configuration, refer to [Modify tasks](#modify-tasks).
1. Identify the leader CTS instance by either making a call to the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) or by checking the logs for the following entry:
```shell-session
@ -112,19 +112,19 @@ You can implement a rolling update to update a non-task configuration for a CTS
```
1. Stop one of the follower CTS instances and apply the new configuration.
1. Restart the follower instance.
1. Repeat steps 2 and 3 for other follower instances in your cluster.
1. Repeat steps 2 and 3 for other follower instances in your cluster.
1. Stop the leader instance. One of the follower instances becomes the leader.
1. Apply the new configuration to the former leader instance and restart it.
## Modify tasks
## Modify tasks
When high availability is enabled, CTS persists task and event data. Refer to [State storage and persistence](/consul/docs/nia/architecture#state-storage-and-persistence) for additional information.
When high availability is enabled, CTS persists task and event data. Refer to [State storage and persistence](/consul/docs/nia/architecture#state-storage-and-persistence) for additional information.
You can use the following methods for modifying tasks when high availability is enabled. We recommend choosing a single method to make all task configuration changes because inconsistencies between the state and the configuration can occur when mixing methods.
### Delete and recreate the task
We recommend deleting and recreating a task if you need to make a modification. Use the CTS API to identify the CTS leader instance and replace a task.
### Delete and recreate the task
We recommend deleting and recreating a task if you need to make a modification. Use the CTS API to identify the CTS leader instance and replace a task.
1. Identify the leader CTS instance by either making a call to the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) or by checking the logs for the following entry:
@ -137,19 +137,19 @@ We recommend deleting and recreating a task if you need to make a modification.
You can also use the [`task delete` command](/consul/docs/nia/cli/task#task-delete) to complete this step.
You can also use the [`task delete` command](/consul/docs/nia/cli/task#task-delete) to complete this step.
1. Send a `POST` call to the `/task/<task-name>` endpoint and include the updated task in your payload.
1. Send a `POST` call to the `/task/<task-name>` endpoint and include the updated task in your payload.
```shell-session
$curl --header "Content-Type: application/json" \
--request POST \
$curl --header "Content-Type: application/json" \
--request POST \
--data @payload.json \
localhost:8558/v1/tasks
```
```
You can also use the [`task-create` command](/consul/docs/nia/cli/task#task-create) to complete this step.
### Discard data with the `-reset-storage` flag
### Discard data with the `-reset-storage` flag
You can restart the CTS cluster using the [`-reset-storage` flag](/consul/docs/nia/cli/start#options) to discard persisted data if you need to update a task.
@ -158,7 +158,7 @@ You can restart the CTS cluster using the [`-reset-storage` flag](/consul/docs/n
1. Restart the instance and include the `-reset-storage` flag.
1. Stop all other instances so that the updated instance becomes the leader.
1. Start all other instances again.
1. Restart the instance you restarted in step 3 without the `-reset-storage` flag so that it starts up with the current state. If you continue to run an instance with the `-reset-storage` flag enabled, then CTS will reset the state data whenever the instance becomes the leader.
1. Restart the instance you restarted in step 3 without the `-reset-storage` flag so that it starts up with the current state. If you continue to run an instance with the `-reset-storage` flag enabled, then CTS will reset the state data whenever the instance becomes the leader.
## Troubleshooting
@ -169,9 +169,9 @@ Use the following troubleshooting procedure if a previous leader had been runnin
| Error: GET https://api.github.com/user: 401 Bad credentials []
|
|
| with module.config-task.provider["registry.terraform.io/integrations/github"],
| on .terraform/modules/config-task/main.tf line 11, in provider "github":
| 11: provider "github" {
@ -179,5 +179,5 @@ Use the following troubleshooting procedure if a previous leader had been runnin
```
1. Check for differences between the previous leader and new leader, such as differences in configurations, environment variables, and local resources.
1. Start a new instance with the fix that resolves the issue.
1. Tear down the leader instance that has the issue and any other instances that may have the same issue.
1. Restart the affected instances to implement the fix.
1. Tear down the leader instance that has the issue and any other instances that may have the same issue.
1. Restart the affected instances to implement the fix.
- **Simplified Service Mesh Deployments with Consul Dataplane:** Consul client agents are no longer deployed by default, and Consul service mesh no longer uses Consul clients to operate. A new component `consul-dataplane` is now injected as a sidecar-proxy instead of plain Envoy. `consul-dataplane` manages the Envoy proxy process and proxies xDS requests from Envoy to Consul servers. All service mesh consul-k8s components are configured to talk directly to Consul servers.
- **Cluster Peering GA with Peering over Mesh Gateways:** This version promotes Cluster Peering, a new model to federate Consul clusters for both service mesh and traditional service discovery, to General Availability. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. Cluster Peering on Consul K8s now enables [Cluster Peering with Control Plane traffic routed via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) by default instead of provisioning load balancers using the `servers.exposeServers` stanza. In addtion, failover for service to service traffic over Cluster Peering can be configured through the `failover.targets` field in the [ServiceResolver](/consul/docs/connect/config-entries/service-resolver#targets) CRD.
- **Consul API Gateway 0.5.0 Support:** Support to run Consul API Gateway without clients and allow Consul API Gateway to directly connect to Consul servers.
- **Cluster Peering GA with Peering over Mesh Gateways:** This version promotes Cluster Peering, a new model to federate Consul clusters for both service mesh and traditional service discovery, to General Availability. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. Cluster Peering on Consul K8s now enables [Cluster Peering with Control Plane traffic routed via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) by default instead of provisioning load balancers using the `servers.exposeServers` stanza. In addition, failover for service to service traffic over Cluster Peering can be configured through the `failover.targets` field in the [ServiceResolver](/consul/docs/connect/config-entries/service-resolver#targets) CRD.
- **Consul API Gateway 0.5.0 Support:** Support to run Consul API Gateway without clients and allow Consul API Gateway to directly connect to Consul servers.
## What's Changed
@ -22,27 +22,27 @@ description: >-
- `externalServers.hosts` no longer supports [cloud auto-join](/consul/docs/install/cloud-auto-join) strings directly. Instead, include an [`exec=`](https://github.com/hashicorp/go-netaddrs#command-line-tool-usage) string in the `externalServers.hosts` list to invoke the `discover` CLI. For example, the following string invokes the `discover` CLI with a cloud auto-join string: `exec=discover -q addrs provider=aws region=us-west-2 tag_key=consul-server tag_value=true`. The `discover` CLI is included in the official `hashicorp/consul-dataplane` images by default.
- `sync-catalog` now communicates directly to Consul servers. When communicating to servers outside of Kubernetes, use the `externalServers.hosts` stanza as described in [Join External Servers to Consul on Kubernetes](/consul/docs/k8s/deployment-configurations/servers-outside-kubernetes).
- Consul snapshot agent runs as a sidecar to Consul servers. <EnterpriseAlert inline />
- `client.snapshotAgent` values are moved to `server.snapshotAgent`, with the exception of the following values: `client.snaphostAgent.replicas`, `client.snaphostAgent.serviceAccount`
- `global.secretsBackend.vault.consulSnapshotAgentRole` value is now removed. You should now use the `global.secretsBackend.vault.consulServerRole` for access to any Vault secrets.
- `client.snapshotAgent` values are moved to `server.snapshotAgent`, with the exception of the following values: `client.snapshotAgent.replicas`, `client.snapshotAgent.serviceAccount`
- `global.secretsBackend.vault.consulSnapshotAgentRole` value is now removed. You should now use the `global.secretsBackend.vault.consulServerRole` for access to any Vault secrets.
- Support simplified default deployment values to allow for easier quick starts and testing:
* Set `server.replicas` to `1`. Formerly, this defaulted to `3`.
* `connectInject.enabled` now defaults to true.
* `dns.enabled` and `dns.enableRedirection` will now default to the value of `connectInject.transparentProxy.defaultEnabled`. Previously, `dns.enabled` defaulted to the value of `global.enabled` and `dns.enableRedirection` defaulted to the value to `false`.
* Set `connectInject.replicas` to 1
* Set `server.replicas` to `1`. Formerly, this defaulted to `3`.
* `connectInject.enabled` now defaults to true.
* `dns.enabled` and `dns.enableRedirection` will now default to the value of `connectInject.transparentProxy.defaultEnabled`. Previously, `dns.enabled` defaulted to the value of `global.enabled` and `dns.enableRedirection` defaulted to the value to `false`.
* Set `connectInject.replicas` to 1
* Set `meshGateway.affinity` to null and `meshGateway.replicas` to 1
* Set `ingressGateways.defaults.affinity` to null and `ingressGateways.defaults.replicas` to 1
* Set `ingressGateways.defaults.affinity` to null and `ingressGateways.defaults.replicas` to 1
* Set `terminatingGateways.defaults.affinity` to null and `terminatingGateways.defaults.replicas` to 1
* `syncCatalog.consulNamespaces.mirroringK8S` now defaults to `true`. <EnterpriseAlert inline />
* `connectInject.consulNamespaces.mirroringK8S` now defaults to `true`. <EnterpriseAlert inline />
- `global.imageEnvoy` is now replaced with `global.imageConsulDataplane` for running the sidecar proxy. apiGateway.imageEnvoy` is now available for configuring the version of Envoy that the API Gateway uses.
- `global.imageEnvoy` is now replaced with `global.imageConsulDataplane` for running the sidecar proxy. apiGateway.imageEnvoy` is now available for configuring the version of Envoy that the API Gateway uses.
## Supported Software
~> **Note:** Consul 1.13.x and 1.12.x is not supported. Please use Consul K8s 0.49.x if you want to use Consul 1.13.x or 1.12.x.
- Consul 1.14.x.
- Consul Dataplane v1.0.x. Refer to [Envoy and Consul Dataplane](/consul/docs/connect/proxies/envoy#envoy-and-consul-dataplane) for details about Consul Dataplane versions and the available packaged Envoy version.
~> **Note:** Consul 1.13.x and 1.12.x is not supported. Please use Consul K8s 0.49.x if you want to use Consul 1.13.x or 1.12.x.
- Consul 1.14.x.
- Consul Dataplane v1.0.x. Refer to [Envoy and Consul Dataplane](/consul/docs/connect/proxies/envoy#envoy-and-consul-dataplane) for details about Consul Dataplane versions and the available packaged Envoy version.
- Kubernetes 1.22.x - 1.25.x
- `kubectl` 1.22.x - 1.25.x
- `kubectl` 1.22.x - 1.25.x
- Helm 3.6+
## Upgrading
@ -51,9 +51,9 @@ For detailed information on upgrading, please refer to the [Upgrades page](/cons
## Known Issues
The following issues are known to exist in the v1.0.0 release:
The following issues are known to exist in the v1.0.0 release:
- Pod Security Standards that are configured for the [Pod Security Admission controller](https://kubernetes.io/blog/2022/08/25/pod-security-admission-stable/) are currently not supported by Consul K8s. OpenShift 4.11.x enables Pod Security Standards on Kubernetes 1.25 [by default](https://connect.redhat.com/en/blog/important-openshift-changes-pod-security-standards) and is also not supported. Support will be added in a future Consul K8s 1.0.x patch release.
- Pod Security Standards that are configured for the [Pod Security Admission controller](https://kubernetes.io/blog/2022/08/25/pod-security-admission-stable/) are currently not supported by Consul K8s. OpenShift 4.11.x enables Pod Security Standards on Kubernetes 1.25 [by default](https://connect.redhat.com/en/blog/important-openshift-changes-pod-security-standards) and is also not supported. Support will be added in a future Consul K8s 1.0.x patch release.
- **Enhanced Envoy Access Logging:** Envoy access logs are now centrally managed via config entries and CRDs to allow operators to easily turn on access logs for all proxies within the service mesh. Refer to [Access logs overview](/consul/docs/connect/observability/access-logs) for more information. Additionally, the [Proxy default configuration entry](/consul/docs/connect/config-entries/proxy-defaults) shows you how to enable access logs centrally via the ProxyDefaults config entry or CRD.
- **Enhanced Envoy Access Logging:** Envoy access logs are now centrally managed via config entries and CRDs to allow operators to easily turn on access logs for all proxies within the service mesh. Refer to [Access logs overview](/consul/docs/connect/observability/access-logs) for more information. Additionally, the [Proxy default configuration entry](/consul/docs/connect/config-entries/proxy-defaults) shows you how to enable access logs centrally via the ProxyDefaults config entry or CRD.
- **Consul Envoy Extensions:** The new Envoy extension system enables you to modify Consul-generated Envoy resources outside of the Consul binary. This will allow extensions to add, delete, and modify Envoy listeners, routes, clusters, and endpoints, enabling support for additional Envoy features without changes to the Consul codebase.
Current supported extensions include the [Lua](/consul/docs/connect/proxies/envoy-extensions#lua) and [AWS Lambda](/consul/docs/connect/proxies/envoy-extensions#lambda) extensions. Refer to [Envoy extensions overview](/consul/docs/connect/proxies/envoy-extensions) for more information on how to use these extensions for Consul service mesh.
- **Consul Envoy Extensions:** The new Envoy extension system enables you to modify Consul-generated Envoy resources outside of the Consul binary. This will allow extensions to add, delete, and modify Envoy listeners, routes, clusters, and endpoints, enabling support for additional Envoy features without changes to the Consul codebase.
Current supported extensions include the [Lua](/consul/docs/connect/proxies/envoy-extensions#lua) and [AWS Lambda](/consul/docs/connect/proxies/envoy-extensions#lambda) extensions. Refer to [Envoy extensions overview](/consul/docs/connect/proxies/envoy-extensions) for more information on how to use these extensions for Consul service mesh.
- **API Gateway support on Linux VM runtimes:** You can now deploy Consul API Gateway on Linux VM runtimes. API Gateway is built into Consul and, when deploying on Linux VM runtimes, is not separately installed software. Refer to [API gateway overview](/consul/docs/connect/gateways/api-gateway) for more information on API Gateway specifically for VM.
- **API Gateway support on Linux VM runtimes:** You can now deploy Consul API Gateway on Linux VM runtimes. API Gateway is built into Consul and, when deploying on Linux VM runtimes, is not separately installed software. Refer to [API gateway overview](/consul/docs/connect/gateways/api-gateway) for more information on API Gateway specifically for VM.
~> **Note:** Support for API Gateway on Linux VM runtimes is considered a "Beta" feature in Consul v1.15.0. HashiCorp expects to change it to a GA feature as part of a v1.15 patch release in the near future.
- **Limit traffic rates to Consul servers:** You can now configure global RPC rate limits to mitigate the risks to Consul servers when clients send excessive read or write requests to Consul resources. Refer to [Limit traffic rates overview](/consul/docs/agent/limits) for more details on how to use the new troubleshooting commands.
- **Limit traffic rates to Consul servers:** You can now configure global RPC rate limits to mitigate the risks to Consul servers when clients send excessive read or write requests to Consul resources. Refer to [Limit traffic rates overview](/consul/docs/agent/limits) for more details on how to use the new troubleshooting commands.
- **Service-to-service troubleshooting:** Consul includes a built-in tool for troubleshooting communication between services in a service mesh. The `consul troubleshoot` command enables you to validate communication between upstream and downstream Envoy proxies on VM and Kubernetes deployments. Refer to [Service-to-service troubleshooting overview](/consul/docs/troubleshoot/troubleshoot-services) for more details on how to use the new troubleshooting commands.
Refer to [Service-to-service troubleshooting overview](/consul/docs/troubleshoot/troubleshoot-services) for more details on how to use the new troubleshooting commands.
- **Service-to-service troubleshooting:** Consul includes a built-in tool for troubleshooting communication between services in a service mesh. The `consul troubleshoot` command enables you to validate communication between upstream and downstream Envoy proxies on VM and Kubernetes deployments. Refer to [Service-to-service troubleshooting overview](/consul/docs/troubleshoot/troubleshoot-services) for more details on how to use the new troubleshooting commands.
Refer to [Service-to-service troubleshooting overview](/consul/docs/troubleshoot/troubleshoot-services) for more details on how to use the new troubleshooting commands.
- **Raft write-ahead log (Experimental):** Consul provides an experimental storage backend called write-ahead log (WAL). WAL implements a traditional log with rotating, append-only log files which resolves a number of performance issues with the current BoltDB storage backend. Refer to [Experimental WAL LogStore backend overview](/consul/docs/agent/wal-logstore) for more details.
~> **Note:** The new Raft write-ahead log storage backend is not recommended for production use cases yet, but is ready for testing by the general community.
- **Raft write-ahead log (Experimental):** Consul provides an experimental storage backend called write-ahead log (WAL). WAL implements a traditional log with rotating, append-only log files which resolves a number of performance issues with the current BoltDB storage backend. Refer to [Experimental WAL LogStore backend overview](/consul/docs/agent/wal-logstore) for more details.
~> **Note:** The new Raft write-ahead log storage backend is not recommended for production use cases yet, but is ready for testing by the general community.
## What's Changed
- ACL errors have now been ehanced to return descriptive errors when the specified resource cannot be found. Other ACL request errors provide more information about when a resource is missing. In addition, errors are now gracefully thrown when interacting with the ACL system before the ACL system been bootstrapped.
- ACL errors have now been enhanced to return descriptive errors when the specified resource cannot be found. Other ACL request errors provide more information about when a resource is missing. In addition, errors are now gracefully thrown when interacting with the ACL system before the ACL system been bootstrapped.
- The Delete Token/Policy/AuthMethod/Role/BindingRule endpoints now return 404 when the resource cannot be found. The new error format is as follows:
```log hideClipboard
Requested * does not exist: ACL not found", "* not found in namespace $NAMESPACE: ACL not found`
```
- The Read Token/Policy/Role endpoints now return 404 when the resource cannot be found. The new error format is as follows:
- The Read Token/Policy/Role endpoints now return 404 when the resource cannot be found. The new error format is as follows:
```log hideClipboard
Cannot find * to delete
```
- The Logout endpoint now returns a 401 error when the supplied token cannot be found. The new error format is as follows:
- The Logout endpoint now returns a 401 error when the supplied token cannot be found. The new error format is as follows:
```log hideClipboard
Supplied token does not exist
```
- The Token Self endpoint now returns 404 when the token cannot be found. The new error format is as follows:
- The Token Self endpoint now returns 404 when the token cannot be found. The new error format is as follows:
```log hideClipboard
Supplied token does not exist
```
- Consul v1.15.0 formally removes all uses of legacy ACLs and ACL policies from Consul. The legacy ACL system was deprecated in Consul v1.4.0 and removed in Consul v1.11.0. The documentation for the new ACL system can be found [here](/consul/docs/v1.14.x/security/acl). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens tutorial](/consul/tutorials/security-operations/access-control-token-migration).
- The following agent flags are now deprecated: `-join`, `-join-wan`, `start_join`, and `start_join_wan`. These options are now aliases of `-retry-join`, `-retry-join-wan`, `retry_join`, and `retry_join_wan`, respectively.
- A `peer` field has been added to ServiceDefaults upstream overrides to make it possible to apply upstream overrides only to peer services. Prior to this change, overrides would be applied based on matching the namespace and name fields only, which means users could not have different configuration for local versus peer services. With this change, peer upstreams are only affected if the peer field matches the destination peer name.
- The following agent flags are now deprecated: `-join`, `-join-wan`, `start_join`, and `start_join_wan`. These options are now aliases of `-retry-join`, `-retry-join-wan`, `retry_join`, and `retry_join_wan`, respectively.
- A `peer` field has been added to ServiceDefaults upstream overrides to make it possible to apply upstream overrides only to peer services. Prior to this change, overrides would be applied based on matching the namespace and name fields only, which means users could not have different configuration for local versus peer services. With this change, peer upstreams are only affected if the peer field matches the destination peer name.
- If you run the `consul connect envoy` command with an incompatible Envoy version, Consul will now error and exit. To ignore this check, use flag `--ignore-envoy-compatibility`.
- Ingress Gateway upstream clusters will have empty `outlier_detection` if passive health check is unspecified.
@ -74,15 +74,15 @@ The following issues are known to exist in the v1.15.x releases:
due to a problem with leaf certificate rotation.
This is resolved in Consul v1.15.2.
- For v1.15.0, Consul is reporting newer releases of Envoy (for example, v1.25.1) as not supported, even though these versions are listed as valid in the [Envoy compatilibity matrix](/consul/docs/connect/proxies/envoy#envoy-and-consul-client-agent). The following error would result for newer versions of Envoy:
- For v1.15.0, Consul is reporting newer releases of Envoy (for example, v1.25.1) as not supported, even though these versions are listed as valid in the [Envoy compatibility matrix](/consul/docs/connect/proxies/envoy#envoy-and-consul-client-agent). The following error would result for newer versions of Envoy:
```log hideClipboard
Envoy version 1.25.1 is not supported. If there is a reason you need to use this version of envoy use the ignore-envoy-compatibility flag. Using an unsupported version of Envoy is not recommended and your experience may vary.
```
To workaround this issue on Consul v1.15.0, launch sidecar proxies
with the `ignore-envoy-compatiblity` flag:
with the `ignore-envoy-compatibility` flag:
```shell-session
$ consul connect envoy --ignore-envoy-compatibility
This topic provides configuration reference information for health checks. For information about the different kinds of health checks and guidance on defining them, refer to [Define Health Checks].
## Introduction
Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. You can configure health checks to monitor the health of the entire node. Refer to [Define Health Checks](/consul/docs/services/usage/checks) for information about how to define the differnet types of health checks available in Consul.
Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. You can configure health checks to monitor the health of the entire node. Refer to [Define Health Checks](/consul/docs/services/usage/checks) for information about how to define the different types of health checks available in Consul.
## Check block
Specify health check options in the `check` block. To register two or more heath checks in the same configuration, use the [`checks` block](#checks-block). The following table describes the configuration options contained in the `check` block.
Specify health check options in the `check` block. To register two or more heath checks in the same configuration, use the [`checks` block](#checks-block). The following table describes the configuration options contained in the `check` block.
| Parameter | Description | Check types |
| --- | --- | --- |
| Parameter | Description | Check types |
| --- | --- | --- |
| `name` | Required string value that specifies the name of the check. Default is `service:<service-id>`. If multiple service checks are registered, the autogenerated default is appended with colon and incrementing number starting with `1`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `id` | A unique string value that specifies an ID for the check. Default to the `name` value. If `name` values conflict, specify a unique ID to avoid overwriting existing checks with same ID on the same node. Consul auto-generates an ID if the check is defined in a service definition file. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `notes` | String value that provides a human-readabiole description of the check. The contents are not visible to Consul. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `notes` | String value that provides a human-readable description of the check. The contents are not visible to Consul. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `interval` | Required string value that specifies how frequently to run the check. The `interval` parameter is required for supported check types. The value is parsed by the golang [time package formatting specification](https://golang.org/pkg/time/#ParseDuration). | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>Docker </li> <li>gRPC </li> <li>H2ping</li> |
| `timeout` | String value that specifies how long unsuccessful requests take to end with a timeout. The `timeout` is optional for the supported check types and has the following defaults: <li> Script: `30s` </li> <li> HTTP: `10s` </li><li> TCP: `10s` </li><li> UDP: `10s` </li><li> gRPC: `10s` </li><li> H2ping: `10s` </li> | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>gRPC </li> <li>H2ping </li> |
| `status` | Optional string value that specifies the initial status of the health check. You can specify the following values: <li>`critical` (default)</li><li>`warning`</li><li>`passing`</li> | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `deregister_critical_service_after` | String value that specifies how long a service and its associated checks are allowed to be in a `critical` state. Consul deregisters services if they are `critical` for the specified amount of time. The value is parsed by the golang [time package formatting specification](https://golang.org/pkg/time/#ParseDuration) | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `success_before_passing` | Integer value that specifies how many consecutive times the check must pass before Consul marks the service or node as `passing`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `failures_before_warning` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `warning`. The value cannot be more than `failures_before_critical`. Defaults to the value specified for `failures_before_critical`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `failures_before_critical` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `critical`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `failures_before_critical` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `critical`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `args` | Specifies a list of arguments strings to pass to the command line. The list of values includes the path to a script file or external application to invoke and any additional parameters for running the script or application. | <li> Script </li><li> Docker </li> |
| `docker_container_id` | Specifies the Docker container ID in which to run an external health check application. Specify the external application with the `args` parameter. | <li> Docker </li> |
| `shell` | String value that specifies the type of command line shell to use for running the health check application. Specify the external application with the `args` parameter. | <li> Docker </li> |
| `grpc` | String value that specifies the gRPC endpoint, including port number, to send requests to. Append the endpoint with `:/` and a service identifier to check a specific service. The endpoint must support the [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). | <li>gRPC </li>|
| `grpc` | String value that specifies the gRPC endpoint, including port number, to send requests to. Append the endpoint with `:/` and a service identifier to check a specific service. The endpoint must support the [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). | <li>gRPC </li>|
| `grpc_use_tls` | Boolean value that enables TLS for gRPC checks when set to `true`. | <li>gRPC </li> |
| `h2ping` | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. | <li>H2ping</li> |
| `h2ping` | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. | <li>H2ping</li> |
| `h2ping_use_tls` | Boolean value that enables TLS for H2ping checks when set to `true`. | <li>H2ping</li> |
| `http` | String value that specifies an HTTP endpoint to send requests to. | <li>HTTP</li> |
| `tls_server_name` | String value that specifies the server name used to verify the hostname on the returned certificates unless `tls_skip_verify` is given. Also included in the client's handshake to support SNI. It is recommended that this field be left unspecified. The TLS client will deduce the server name for SNI from the check address unless it's an IP ([RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3)). There are two common circumstances where supplying a `tls_server_name` can be beneficial: <li>When the check address is an IP, `tls_server_name` can be specified for SNI. Note: setting `tls_server_name` will also override the hostname used to verify the certificate presented by the server being checked.</li><li>When the hostname in the check address won't be present in the SAN (Subject Alternative Name) field of the certificate presented by the server being checked. Note: setting `tls_server_name` will also override the hostname used for SNI.</li> | <li>HTTP </li> <li>H2Ping </li> <li>gRPC </li> |
| `tls_skip_verify` | Boolean value that determines if the check verifies the chain and hostname of the certificate that the server presents. Set to `true` to disable verification. We recommend setting to `false` for production use. Default is `false`. | <li>HTTP </li> <li>H2Ping </li> <li>gRPC </li> |
| `method` | String value that specifies the request method to send during HTTP checks. Default is `GET`. | <li>HTTP</li> |
| `header` | Object that specifies header fields to send in HTTP check requests. Each header specified in `header` object contains a list of string values. | <li>HTTP</li> |
| `body` | String value that contains JSON attributes to send in HTTP check requests. You must escap the quotation marks around the keys and values for each attribute. | <li>HTTP</li> |
| `disable_redirects` | Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`. | <li>HTTP</li> |
| `body` | String value that contains JSON attributes to send in HTTP check requests. You must escape the quotation marks around the keys and values for each attribute. | <li>HTTP</li> |
| `disable_redirects` | Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`. | <li>HTTP</li> |
| `os_service` | String value that specifies the name of the name of a service to check during an OSService check. | <li>OSService</li> |
| `service_id` | String value that specifies the ID of a service instance to associate with an OSService check. That service instance must be on the same node as the check. If not specified, the check verifies the health of the node. | <li>OSService</li> |
| `tcp` | String value that specifies an IP address or host and port number for the check establish a TCP connection with. | <li>TCP</li> |
| `udp` | String value that specifies an IP address or host and port number for the check to send UDP datagrams to. | <li>UDP</li> |
| `ttl` | String value that specifies how long to wait for an update from an external process during a TTL check. | <li>TTL</li> |
| `alias_service` | String value that specifies a service or node that the service associated with the health check aliases. | <li>Alias</li> |
| `alias_service` | String value that specifies a service or node that the service associated with the health check aliases. | <li>Alias</li> |
## Checks block
You can define multiple health checks in a single `checks` block. The `checks` block is an array of objects that contain the configuration options described in the [`check` block configuration reference](#check-block).
You can define multiple health checks in a single `checks` block. The `checks` block is an array of objects that contain the configuration options described in the [`check` block configuration reference](#check-block).
For service discovery use cases, Domain Name Service (DNS) is the main interface to look up, query, and address Consul nodes and services. Learn how a Consul DNS lookup can help you find services by tag, name, namespace, partition, datacenter, or domain.
---
# DNS usage overview
This topic provides overview information about how to look up Consul nodes and services using the Consul DNS.
This topic provides overview information about how to look up Consul nodes and services using the Consul DNS.
## Consul DNS
The Consul DNS is the primary interface for discovering services registered in the Consul catalog. The DNS enables you to look up services and nodes registered with Consul using terminal commands instead of making HTTP API requests to Consul.
The Consul DNS is the primary interface for discovering services registered in the Consul catalog. The DNS enables you to look up services and nodes registered with Consul using terminal commands instead of making HTTP API requests to Consul.
We recommend using the DNS for service discovery in virtual machine (VM) environments because it removes the need to modify native applications so that they can consume the Consul service discovery APIs.
We recommend using the DNS for service discovery in virtual machine (VM) environments because it removes the need to modify native applications so that they can consume the Consul service discovery APIs.
The DNS has several default configurations, but you can customize how the server processes lookups. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for additional information.
The DNS has several default configurations, but you can customize how the server processes lookups. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for additional information.
### DNS versus native app integration
You can use DNS to reach services registered with Consul or modify your application to natively consume the Consul service discovery HTTP APIs.
We recommend using the DNS because it is less invasive. You do not have to modify your application with Consul to retrieve the service’s connection information. Instead, you can use a DNS fully qualified domain (FQDN) that conforms to Consul's lookup format to retreive the relevant information.
We recommend using the DNS because it is less invasive. You do not have to modify your application with Consul to retrieve the service’s connection information. Instead, you can use a DNS fully qualified domain (FQDN) that conforms to Consul's lookup format to retrieve the relevant information.
Refer to [ Native App Integration](/consul/docs/connect/native) and its [Go package](/consul/docs/connect/native/go) for additional information.
Refer to [ Native App Integration](/consul/docs/connect/native) and its [Go package](/consul/docs/connect/native/go) for additional information.
### DNS versus upstreams
If you are using Consul for service discovery and have not enabled service mesh features, then use the DNS to discover services and nodes in the Consul catalog.
If you are using Consul for service discovery and have not enabled service mesh features, then use the DNS to discover services and nodes in the Consul catalog.
If you are using Consul for service mesh on VMs, you can use upstreams or DNS. We recommend using upstreams because you can query services and nodes without modifying the application code or environment variables. Refer to [Upstream Configuration Reference](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for additional information.
If you are using Consul on Kubernetes, refer to [the upstreams annotation documentation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) for additional information.
If you are using Consul on Kubernetes, refer to [the upstreams annotation documentation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) for additional information.
## Static queries
Node lookups and service lookups are the fundamental types of static queries. Depending on your use case, you may need to use different query methods and syntaxes to query the DNS for services and nodes.
Node lookups and service lookups are the fundamental types of static queries. Depending on your use case, you may need to use different query methods and syntaxes to query the DNS for services and nodes.
Consul relies on a very specific format for queries to resolve names. Note that all queries are case-sensitive.
Consul relies on a very specific format for queries to resolve names. Note that all queries are case-sensitive.
Refer to [Perform Static DNS Lookups](/consul/docs/services/discovery/dns-static-lookups) for details about how to perform node and service lookups.
Refer to [Perform Static DNS Lookups](/consul/docs/services/discovery/dns-static-lookups) for details about how to perform node and service lookups.
## Prepared queries
Prepared queries are configurations that enable you to register complex DNS queries. They provide lookup features that extend Consul's service discovery capabilities, such as filtering by multiple tags and automatically querying remote datacenters for services if no healthy nodes are available in the local datacenter. You can also create prepared query templates that match names using a prefix match, allowing a single template to apply to potentially many services. Refer to [Enable Dynamic DNS Queries](/consul/docs/services/discovery/dns-dynamic-lookups) for additional information.
This topic describes how to query the Consul DNS to look up nodes and services registered with Consul. Refer to [Enable Dynamic DNS Queries](/consul/docs/services/discovery/dns-dynamic-lookups) for information about using prepared queries.
## Introduction
Node lookups and service lookups are the fundamental types of queries you can perform using the Consul DNS. Node lookups interrogate the catalog for named Consul agents. Service lookups interrogate the catalog for services registered with Consul. Refer to [DNS Usage Overivew](/consul/docs/services/discovery/dns-overview) for additional background information.
Node lookups and service lookups are the fundamental types of queries you can perform using the Consul DNS. Node lookups interrogate the catalog for named Consul agents. Service lookups interrogate the catalog for services registered with Consul. Refer to [DNS Usage Overview](/consul/docs/services/discovery/dns-overview) for additional background information.
## Requirements
All versions of Consul support DNS lookup features.
All versions of Consul support DNS lookup features.
### ACLs
If ACLs are enabled, you must present a token linked with the necessary policies. We recommend using a separate token in production deployments for querying the DNS. By default, Consul agents resolve DNS requests using the preconfigured tokens in order of precedence:
@ -39,7 +39,7 @@ Specify the name of the node, datacenter, and domain using the following FQDN sy
The `datacenter` subdomain is optional. By default, the lookup queries the datacenter of the agent.
By default, the domain is `consul`. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for information about using alternate domains.
By default, the domain is `consul`. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for information about using alternate domains.
### Node lookup results
@ -75,9 +75,9 @@ consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
### Node lookups for Consul Enterprise
Consul Enterprise includes the admin partition concept, which is an abstraction that lets you define isolated administrative network areas. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information.
Consul Enterprise includes the admin partition concept, which is an abstraction that lets you define isolated administrative network areas. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information.
Consul nodes reside in admin partitions within a datacenter. By default, node lookups query the same partition and datacenter of the Consul agent that received the DNS query.
Consul nodes reside in admin partitions within a datacenter. By default, node lookups query the same partition and datacenter of the Consul agent that received the DNS query.
Use the following query format to specify a partition for a node lookup:
@ -88,9 +88,9 @@ Use the following query format to specify a partition for a node lookup:
Consul server agents are in the `default` partition. If you send a DNS query to Consul server agents, you must explicitly specify the partition of the target node if it is not `default`.
## Service lookups
You can query the network for service providers using either the [standard lookup](#standard-lookup) method or [strict RFC 2782 lookup](#rfc-2782-lookup) method.
You can query the network for service providers using either the [standard lookup](#standard-lookup) method or [strict RFC 2782 lookup](#rfc-2782-lookup) method.
By default, all SRV records are weighted equally in service lookup responses, but you can configure the weights using the [`Weights`](/consul/docs/services/configuration/services-configuration-reference#weights) attribute of the service definition. Refer to [Define Services](/consul/docs/services/usage/define-services) for additional information.
By default, all SRV records are weighted equally in service lookup responses, but you can configure the weights using the [`Weights`](/consul/docs/services/configuration/services-configuration-reference#weights) attribute of the service definition. Refer to [Define Services](/consul/docs/services/usage/define-services) for additional information.
The DNS protocol limits the size of requests, even when performing DNS TCP queries, which may affect your experience querying for services. For services with more than 500 instances, you may not be able to retrieve the complete list of instances for the service. Refer to [RFC 1035, Domain Names - Implementation and Specification](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.4) for additional information.
@ -103,13 +103,13 @@ To perform standard service lookups, specify tags, the name of the service, data
The `tag` subdomain is optional. It filters responses so that only service providers containing the tag appear.
The `tag` subdomain is optional. It filters responses so that only service providers containing the tag appear.
The `datacenter` subdomain is optional. By default, Consul interrogates the querying agent's datacenter.
The `cluster-peer` name is optional, and specifies the [cluster peer](/consul/docs/connect/cluster-peering) whose [exported services](/consul/docs/connect/config-entries/exported-services) should be the target of the query.
By default, the lookups query in the `consul` domain. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for information about using alternate domains.
By default, the lookups query in the `consul` domain. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for information about using alternate domains.
#### Standard lookup results
Standard services queries return A and SRV records. SRV records include the port that the service is registered on. SRV records are only served if the client specifically requests them.
@ -163,7 +163,7 @@ primary.postgresql.service.dc2.consul. 0 IN A 10.1.10.12
```
### RFC 2782 lookup
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries must prepend `service` and `protocol` values with an underscore (`_`) to prevent DNS collisions. Use the following syntax to perform RFC 2782 lookups:
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries must prepend `service` and `protocol` values with an underscore (`_`) to prevent DNS collisions. Use the following syntax to perform RFC 2782 lookups:
#### SRV responses for hosts in the .addr subdomain
If a service registered with Consul is configured with an explicit IP address or addresses in the [`address`](/consul/docs/services/configuration/services-configuration-reference#address) or [`tagged_address`](/consul/docs/services/configuration/services-configuration-reference#tagged_address) parameter, then Consul returns the hostname in the target field of the answer section for the DNS SRV query according to the following format:
If a service registered with Consul is configured with an explicit IP address or addresses in the [`address`](/consul/docs/services/configuration/services-configuration-reference#address) or [`tagged_address`](/consul/docs/services/configuration/services-configuration-reference#tagged_address) parameter, then Consul returns the hostname in the target field of the answer section for the DNS SRV query according to the following format:
The `namespace`, `partition`, and `datacenter` are optional. By default, all service lookups use the `default` namespace within the partition and datacenter of the Consul agent that received the DNS query.
The `namespace`, `partition`, and `datacenter` are optional. By default, all service lookups use the `default` namespace within the partition and datacenter of the Consul agent that received the DNS query.
Consul server agents reside in the `default` partition. If DNS queries are addressed to Consul server agents, you must explicitly specify the partition of the target service when querying for services in partitions other than `default`.
@ -357,7 +357,7 @@ Add the `.virtual` subdomain to queries to find the unique virtual IP allocated
<service>.virtual[.<peer>].<domain>
```
This returns the unique virtual IP for any service mesh-capable service. Each service mesh service has a virtual IP assigned to it by Consul. Sidecar proxies use the virtual IP to enable the [transparent proxy](/consul/docs/connect/transparent-proxy) feature.
This returns the unique virtual IP for any service mesh-capable service. Each service mesh service has a virtual IP assigned to it by Consul. Sidecar proxies use the virtual IP to enable the [transparent proxy](/consul/docs/connect/transparent-proxy) feature.
The peer name is an optional. The DNS uses it to query for the virtual IP of a service imported from the specified peer.
@ -388,4 +388,4 @@ This endpoint finds services within the same datacenter and does not support tag
### UDP-based DNS queries
When the DNS query is performed using UDP, Consul truncateß the results without setting the truncate bit. This prevents a redundant lookup over TCP that generates additional load. If the lookup is done over TCP, the results are not truncated.
When the DNS query is performed using UDP, Consul truncates the results without setting the truncate bit. This prevents a redundant lookup over TCP that generates additional load. If the lookup is done over TCP, the results are not truncated.
Learn about services and service discovery workflows and concepts for virtual machine environments.
Learn about services and service discovery workflows and concepts for virtual machine environments.
---
# Services overview
This topic provides overview information about services and how to make them discoverable in Consul when your network operates on virtual machines. If service mesh is enabled in your network, refer to the following articles for additional information about connecting services in a mesh:
- [How Service Mesh Works](/consul/docs/connect/connect-internals)
- [How Service Mesh Works](/consul/docs/connect/connect-internals)
- [How Consul Service Mesh Works on Kubernetes](/consul/docs/k8s/connect)
## Introduction
A _service_ is an entity in your network that performs a specialized operation or set of related operations. In many contexts, a service is software that you want to make available to users or other programs with access to your network. Services can also refer to native Consul functionality, such as _service mesh proxies_ and _gateways_, that enable you to establish connections between different parts of your network.
A _service_ is an entity in your network that performs a specialized operation or set of related operations. In many contexts, a service is software that you want to make available to users or other programs with access to your network. Services can also refer to native Consul functionality, such as _service mesh proxies_ and _gateways_, that enable you to establish connections between different parts of your network.
You can define and register services with Consul, which makes them discoverable to other services in the network. You can also define various types of health checks that perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary.
@ -37,13 +37,13 @@ Consul redirects service traffic through sidecar proxies if you use Consul servi
You must define upstream services in the service definition. Consul uses the upstream configuration to bind the service with its upstreams. After registering the service, you must start a sidecar proxy on the VM to enable mesh connectivity. Refer to [Register a Service Mesh Proxy in a Service Registration](/consul/docs/connect/registration/sidecar-service) for details.
### Kubernetes
### Kubernetes
If you use Consul on Kubernetes, enable the service mesh injector in your Consul Helm chart and Consul automatically adds a sidecar to each of your pods using the Kubernetes `Service` definition as a reference. You can specify upstream annotations in the `Deployment` definition to bind upstream services to the pods.
Refer to [`connectInject`](/consul/docs/k8s/connect#installation-and-configuration) and [the upstreams annotation documentation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) for additional information.
### Multiple services
You can define common characteristics for services in your mesh, such as the admin partition, namespace, or upstreams, by creating and applying a `service-defaults` configuration entry. You can also define override configurations for specific upstreams or service instances. To use `service-defaults` configuraiton entries, you must enable Consul service mesh in your network.
You can define common characteristics for services in your mesh, such as the admin partition, namespace, or upstreams, by creating and applying a `service-defaults` configuration entry. You can also define override configurations for specific upstreams or service instances. To use `service-defaults` configuration entries, you must enable Consul service mesh in your network.
Refer to [Define Service Defaults](/consul/docs/services/usage/define-services#define-service-defaults) for additional information.
Refer to [Define Service Defaults](/consul/docs/services/usage/define-services#define-service-defaults) for additional information.
Learn how to define services so that they are discoverable in your network.
Learn how to define services so that they are discoverable in your network.
---
# Define services
This topic describes how to define services so that they can be discovered by other services. Refer to [Services Overview](/consul/docs/services/services) for additional information.
This topic describes how to define services so that they can be discovered by other services. Refer to [Services Overview](/consul/docs/services/services) for additional information.
## Overview
You must tell Consul about the services deployed to your network if you want them to be discoverable. You can define services in a configuration file or send the service definition parameters as a payload to the `/agent/service/register` API endpoint. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for details about how to register services with Consul.
You must tell Consul about the services deployed to your network if you want them to be discoverable. You can define services in a configuration file or send the service definition parameters as a payload to the `/agent/service/register` API endpoint. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for details about how to register services with Consul.
You can define multiple services individually using `service` blocks or group multiple services into the same `services` configuration block. Refer to [Define multiple services in a single file](#define-multiple-services-in-a-single-file) for additional information.
@ -19,7 +19,7 @@ If Consul service mesh is enabled in your network, you can use the [service defa
## Requirements
The core service discovery features are available in all versions of Consul.
The core service discovery features are available in all versions of Consul.
### Service defaults
To use the [service defaults configuration entry](#define-service-defaults), verify that your installation meets the following requirements:
@ -28,11 +28,11 @@ To use the [service defaults configuration entry](#define-service-defaults), ver
- Consul 1.8.4+ is required to use the `ServiceDefaults` custom resource on Kubernetes
### ACLs
If ACLs are enabled, resources in your network must present a token with `service:read` access to read a service defaults configuration entry.
If ACLs are enabled, resources in your network must present a token with `service:read` access to read a service defaults configuration entry.
You must also present a token with `service:write` access to create, update, or delete a service defaults configuration entry.
Service configurations must also contain and present an ACL token to perform anti-entropy syncs and deregistration operations. Refer to [Modify anti-entropy synchronozation](#modify-anti-entropy-synchronization) for additional information.
Service configurations must also contain and present an ACL token to perform anti-entropy syncs and deregistration operations. Refer to [Modify anti-entropy synchronization](#modify-anti-entropy-synchronization) for additional information.
On Consul Enterprise, you can register services with specific namespaces if the services' ACL tokens are scoped to the namespace. Services registered with a service definition do not inherit the namespace associated with the ACL token specified in the `token` field. The `namespace` and the `token` parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.
@ -52,17 +52,17 @@ service {
id = "redis"
port = 80
tags = ["primary"]
meta = {
custom_meta_key = "custom_meta_value"
}
tagged_addresses = {
lan = {
address = "192.168.0.55"
port = 8000
}
wan = {
address = "198.18.0.23"
port = 80
@ -138,17 +138,17 @@ You can add a `check` or `checks` block to your service configuration to define
### Register a service
You can register your service using the [`consul services` command](/consul/commands/services) or by calling the [`/agent/services` API endpoint](/consul/api-docs/agent/service). Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for details.
You can register your service using the [`consul services` command](/consul/commands/services) or by calling the [`/agent/services` API endpoint](/consul/api-docs/agent/service). Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for details.
## Define service defaults
If Consul service mesh is enabled in your network, you can define default values for services in your mesh by creating and applying a `service-defaults` configuration entry containing. Refer to [Service Mesh Configuration Overview](/consul/docs/connect/configuration) for additional information.
If Consul service mesh is enabled in your network, you can define default values for services in your mesh by creating and applying a `service-defaults` configuration entry containing. Refer to [Service Mesh Configuration Overview](/consul/docs/connect/configuration) for additional information.
Create a file for the configuration entry and specify the required fields. If you are authoring `service-defaults` in HCL or JSON, the `Kind` and `Name` fields are required. On Kubernetes, the `apiVersion`, `kind`, and `metadata.name` fields are required. Refer to [Service Defaults Reference](/consul/docs/connect/config-entries/service-defaults) for details about the configuration options.
If you use Consul Enterprise, you can also specify the `Namespace` and `Partition` fields to apply the configuration to services in a specific namespace or partition. For Kubernetes environments, the configuration entry is always created in the same partition as the Kubernetes cluster.
### Consul OSS example
The following example instructs services named `counting` to send up to `512` concurrent requests to a mesh gateway:
The following example instructs services named `counting` to send up to `512` concurrent requests to a mesh gateway:
You can apply your `service-defaults` configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `service-defaults` custom resource definitions (CRD) to implement and manage Consul configuration entries.
You can apply your `service-defaults` configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `service-defaults` custom resource definitions (CRD) to implement and manage Consul configuration entries.
Refer to the following topics for details about applying configuration entries:
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
Refer to the following topics for details about applying configuration entries:
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)
## Define multiple services in a single file
The `services` block contains an array of `service` objects. It is a wrapper that enables you to define multiple services in the service definition and instruct Consul to expect more than just a single service configuration. As a result, you can register multiple services in a single `consul services register` command. Note that the `/agent/service/register` API endpoint does not support the `services` parameter.
The `services` block contains an array of `service` objects. It is a wrapper that enables you to define multiple services in the service definition and instruct Consul to expect more than just a single service configuration. As a result, you can register multiple services in a single `consul services register` command. Note that the `/agent/service/register` API endpoint does not support the `services` parameter.
In the following example, the service definition configures an instance of the `redis` service tagged as `primary` running on port `6000`. It also configures an instance of the service tagged as `secondary` running on port `7000`.
@ -436,7 +436,7 @@ service {
</CodeTabs>
This configuration only applies to the locally registered service. Nodes that register the same service apply the `enable_tag_override` and other service configurations independently. The tags for a service registered on one node update are not affected by operations performed on services with the same name registered on other nodes.
This configuration only applies to the locally registered service. Nodes that register the same service apply the `enable_tag_override` and other service configurations independently. The tags for a service registered on one node update are not affected by operations performed on services with the same name registered on other nodes.
Refer to [`enable_tag_override`](/consul/docs/services/configuration/services-configuration-reference#enable_tag_override) for additional configuration information.
@ -444,7 +444,7 @@ Refer to [`enable_tag_override`](/consul/docs/services/configuration/services-co
Defining services for service mesh environments on virtual machines and in Kubernetes requires a different workflow.
### Define service mesh proxies
You can register services to function as service mesh or sidecar proxies so that they can facilitate communication between other services across your network. Refer to [Service Mesh Proxy Overview](/consul/docs/connect/registration) for additional information.
You can register services to function as service mesh or sidecar proxies so that they can facilitate communication between other services across your network. Refer to [Service Mesh Proxy Overview](/consul/docs/connect/registration) for additional information.
### Define services in Kubernetes
You can enable the services running in Kubernetes and Consul to sync automatically. Doing so ensures that Kubernetes services are available to Consul agents and services in Consul can be available as first-class Kubernetes services. Refer to [Service Sync for Consul on Kubernetes](/consul/docs/k8s/service-sync) for details.
You can enable the services running in Kubernetes and Consul to sync automatically. Doing so ensures that Kubernetes services are available to Consul agents and services in Consul can be available as first-class Kubernetes services. Refer to [Service Sync for Consul on Kubernetes](/consul/docs/k8s/service-sync) for details.
Blake Covarrubias
1 year ago
committed by