diff --git a/website/content/commands/intention/list.mdx b/website/content/commands/intention/list.mdx index 85a7d6b9d6..4cdfa5c8a2 100644 --- a/website/content/commands/intention/list.mdx +++ b/website/content/commands/intention/list.mdx @@ -2,7 +2,7 @@ layout: commands page_title: 'Commands: Intention List' description: >- - 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. --- # Consul Intention List diff --git a/website/content/commands/kv/index.mdx b/website/content/commands/kv/index.mdx index f95f8be885..0dd8796d8e 100644 --- a/website/content/commands/kv/index.mdx +++ b/website/content/commands/kv/index.mdx @@ -2,7 +2,7 @@ layout: commands page_title: 'Commands: KV' description: >- - 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. --- # Consul KV diff --git a/website/content/commands/services/deregister.mdx b/website/content/commands/services/deregister.mdx index 79ea7cba27..edc493866e 100644 --- a/website/content/commands/services/deregister.mdx +++ b/website/content/commands/services/deregister.mdx @@ -2,7 +2,7 @@ layout: commands page_title: 'Commands: Services Deregister' description: | - 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: | ACL Required | | --------------- | diff --git a/website/content/commands/services/register.mdx b/website/content/commands/services/register.mdx index cefa235923..a1cbd8cf58 100644 --- a/website/content/commands/services/register.mdx +++ b/website/content/commands/services/register.mdx @@ -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: diff --git a/website/content/docs/agent/limits/usage/limit-request-rates-from-ips.mdx b/website/content/docs/agent/limits/usage/limit-request-rates-from-ips.mdx index 69c97558ce..530ad7b26a 100644 --- a/website/content/docs/agent/limits/usage/limit-request-rates-from-ips.mdx +++ b/website/content/docs/agent/limits/usage/limit-request-rates-from-ips.mdx @@ -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). @@ -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. @@ -69,4 +69,4 @@ $ kubectl apply control-plane-request-limit.yaml ## Disable request 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 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. \ No newline at end of file +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. diff --git a/website/content/docs/agent/limits/usage/set-global-traffic-rate-limits.mdx b/website/content/docs/agent/limits/usage/set-global-traffic-rate-limits.mdx index e21aa78c1e..c0afeec901 100644 --- a/website/content/docs/agent/limits/usage/set-global-traffic-rate-limits.mdx +++ b/website/content/docs/agent/limits/usage/set-global-traffic-rate-limits.mdx @@ -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 = { -## 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. diff --git a/website/content/docs/agent/wal-logstore/index.mdx b/website/content/docs/agent/wal-logstore/index.mdx index 491255e8ed..77dc1dd058 100644 --- a/website/content/docs/agent/wal-logstore/index.mdx +++ b/website/content/docs/agent/wal-logstore/index.mdx @@ -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. \ No newline at end of file +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. diff --git a/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx b/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx index 2bd0638b7c..9ba6923b42 100644 --- a/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx +++ b/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx @@ -5,7 +5,7 @@ description: >- 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 ```shell-session $ rm /data-dir/raft.bak -``` \ No newline at end of file +``` diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx index 577920fd7d..fcb2e1f41b 100644 --- a/website/content/docs/api-gateway/upgrades.mdx +++ b/website/content/docs/api-gateway/upgrades.mdx @@ -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`: ```shell-session $ kubectl delete --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=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. @@ -98,7 +98,7 @@ If you are able to tolerate downtime for your applications, you should delete pr -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 ``` - + 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. @@ -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: "crossNamespaceSecrets": { "group": "", "kind": "Secret", - "name": "cexample-certificate", + "name": "example-certificate", "namespace": "certificate-namespace" } } diff --git a/website/content/docs/architecture/anti-entropy.mdx b/website/content/docs/architecture/anti-entropy.mdx index 39d2a08156..292f5c0070 100644 --- a/website/content/docs/architecture/anti-entropy.mdx +++ b/website/content/docs/architecture/anti-entropy.mdx @@ -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. diff --git a/website/content/docs/architecture/scale.mdx b/website/content/docs/architecture/scale.mdx index 1cf31162da..ba03f23c66 100644 --- a/website/content/docs/architecture/scale.mdx +++ b/website/content/docs/architecture/scale.mdx @@ -1,7 +1,7 @@ --- layout: docs 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. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 4dc23cb00c..8b6f315a7d 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Cluster Peering Overview description: >- - 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 - [Cluster peering](/hcp/docs/consul/usage/cluster-peering) - [Cluster peering topologies](/hcp/docs/consul/usage/cluster-peering/topologies) -- [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. \ No newline at end of file +- Accessing key/value stores across peers is not supported. diff --git a/website/content/docs/connect/config-entries/control-plane-request-limit.mdx b/website/content/docs/connect/config-entries/control-plane-request-limit.mdx index 21b06f6533..8eb00d66d1 100644 --- a/website/content/docs/connect/config-entries/control-plane-request-limit.mdx +++ b/website/content/docs/connect/config-entries/control-plane-request-limit.mdx @@ -1,12 +1,12 @@ --- layout: docs 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. @@ -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 #### Values - Default: No limit. -- Data type: number \ No newline at end of file +- Data type: number diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index b9e89d9ad1..c2c1bdd452 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -270,7 +270,7 @@ A asterisk wildcard (`*`) cannot be specified as the `Peer`. Added in Consul 1.1 - `Partition`: Specifies an admin partition in the datacenter to export the service to. A asterisk wildcard (`*`) cannot be specified as the `Partition`. - `SamenessGroup`: Specifies as sameness group to export the service to. -A asterisk wildcard (`*`) cannot be specified as the `SamennessGroup`. +A asterisk wildcard (`*`) cannot be specified as the `SamenessGroup`. ## Examples diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 63d990f9d8..e4dac5beb0 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -15,7 +15,7 @@ Consul's API gateway is the recommended alternative to ingress gateway. -This topic provides configuration reference information for the ingress gateway configuration entry. An ingress gateway is a type of proxy you register as a service in Consul to enable network connectivity from external services to services inside of the service mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway) for additional information. +This topic provides configuration reference information for the ingress gateway configuration entry. An ingress gateway is a type of proxy you register as a service in Consul to enable network connectivity from external services to services inside of the service mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway) for additional information. ## Configuration model @@ -27,121 +27,121 @@ The following list describes the configuration hierarchy, language-specific data - [`Kind`](#kind): string | must be `ingress-gateway` | required - [`Name`](#name): string | required - [`Namespace`](#namespace): string | `default` | -- [`Meta`](#meta): map of strings +- [`Meta`](#meta): map of strings - [`Partition`](#partition): string | `default` | -- [`TLS`](#tls): map +- [`TLS`](#tls): map - [`Enabled`](#tls-enabled): boolean | `false` - [`TLSMinVersion`](#tls-tlsminversion): string | `TLSv1_2` - - [`TLSMaxVersion`](#tls-tlsmaxversion): string - - [`CipherSuites`](#tls-ciphersuites): list of strings - - [`SDS`](#tls-sds): map of strings - - [`ClusterName`](#tls-sds): string - - [`CertResource`](#tls-sds): string -- [`Defaults`](#defaults): map - - [`MaxConnections`](#defaults-maxconnections): number - - [`MaxPendingRequests`](#defaults-maxpendingrequests): number - - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests): number - - [`PassiveHealthCheck`](#defaults-passivehealthcheck): map - - [`interval`](#defaults-passivehealthcheck): number - - [`max_failures`](#defaults-passivehealthcheck): number - - [`enforcing_consecutive_5xx`](#defaults-passivehealthcheck): number -- [`Listeners`](#listeners): list of maps + - [`TLSMaxVersion`](#tls-tlsmaxversion): string + - [`CipherSuites`](#tls-ciphersuites): list of strings + - [`SDS`](#tls-sds): map of strings + - [`ClusterName`](#tls-sds): string + - [`CertResource`](#tls-sds): string +- [`Defaults`](#defaults): map + - [`MaxConnections`](#defaults-maxconnections): number + - [`MaxPendingRequests`](#defaults-maxpendingrequests): number + - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests): number + - [`PassiveHealthCheck`](#defaults-passivehealthcheck): map + - [`interval`](#defaults-passivehealthcheck): number + - [`max_failures`](#defaults-passivehealthcheck): number + - [`enforcing_consecutive_5xx`](#defaults-passivehealthcheck): number +- [`Listeners`](#listeners): list of maps - [`Port`](#listeners-port): number | `0` - [`Protocol`](#listeners-protocol): number | `tcp` - - [`Services`](#listeners-services): list of objects - - [`Name`](#listeners-services-name): string + - [`Services`](#listeners-services): list of objects + - [`Name`](#listeners-services-name): string - [`Namespace`](#listeners-services-namespace): string | - [`Partition`](#listeners-services-partition): string | - [`Hosts`](#listeners-services-hosts): List of strings | `.ingress.*` - - [`RequestHeaders`](#listeners-services-requestheaders): map - - [`Add`](#listeners-services-requestheaders): map of strings - - [`Set`](#listeners-services-requestheaders): map of strings - - [`Remove`](#listeners-services-requestheaders): list of strings - - [`ResponseHeaders`](#listeners-services-responseheaders): map - - [`Add`](#listeners-services-responseheaders): map of strings - - [`Set`](#listeners-services-responseheaders): map of strings - - [`Remove`](#listeners-services-responseheaders): list of strings - - [`TLS`](#listeners-services-tls): map - - [`SDS`](#listeners-services-tls-sds): map of strings - - [`ClusterName`](#listeners-services-tls-sds): string - - [`CertResource`](#listeners-services-tls-sds): string + - [`RequestHeaders`](#listeners-services-requestheaders): map + - [`Add`](#listeners-services-requestheaders): map of strings + - [`Set`](#listeners-services-requestheaders): map of strings + - [`Remove`](#listeners-services-requestheaders): list of strings + - [`ResponseHeaders`](#listeners-services-responseheaders): map + - [`Add`](#listeners-services-responseheaders): map of strings + - [`Set`](#listeners-services-responseheaders): map of strings + - [`Remove`](#listeners-services-responseheaders): list of strings + - [`TLS`](#listeners-services-tls): map + - [`SDS`](#listeners-services-tls-sds): map of strings + - [`ClusterName`](#listeners-services-tls-sds): string + - [`CertResource`](#listeners-services-tls-sds): string - [`MaxConnections`](#listeners-services-maxconnections): number | `0` - [`MaxPendingRequests`](#listeners-services-maxconnections): number | `0` - [`MaxConcurrentRequests`](#listeners-services-maxconnections): number | `0` - - [`PassiveHealthCheck`](#listeners-services-passivehealthcheck): map - - [`interval`](#listeners-services-passivehealthcheck): number - - [`max_failures`](#listeners-services-passivehealthcheck): number - - [`enforcing_consecutive_5xx`](#listeners-services-passivehealthcheck): number - - [`TLS`](#listeners-tls): map + - [`PassiveHealthCheck`](#listeners-services-passivehealthcheck): map + - [`interval`](#listeners-services-passivehealthcheck): number + - [`max_failures`](#listeners-services-passivehealthcheck): number + - [`enforcing_consecutive_5xx`](#listeners-services-passivehealthcheck): number + - [`TLS`](#listeners-tls): map - [`Enabled`](#listeners-tls-enabled): boolean | `false` - [`TLSMinVersion`](#listeners-tls-tlsminversion): string | `TLSv1_2` - - [`TLSMaxVersion`](#listeners-tls-tlsmaxversion): string - - [`CipherSuites`](#listeners-tls-ciphersuites): list of strings - - [`SDS`](#listeners-tls-sds): map of strings - - [`ClusterName`](#listeners-tls-sds): string - - [`CertResource`](#listeners-tls-sds): string + - [`TLSMaxVersion`](#listeners-tls-tlsmaxversion): string + - [`CipherSuites`](#listeners-tls-ciphersuites): list of strings + - [`SDS`](#listeners-tls-sds): map of strings + - [`ClusterName`](#listeners-tls-sds): string + - [`CertResource`](#listeners-tls-sds): string -- [ `apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` | required +- [ `apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` | required - [`kind`](#kind): string | must be `IngressGateway` | required -- [`metadata`](#metadata): map of strings +- [`metadata`](#metadata): map of strings - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | `default` | -- [`spec`](#spec): map - - [`tls`](#spec-tls): map +- [`spec`](#spec): map + - [`tls`](#spec-tls): map - [`enabled`](#spec-tls-enabled): boolean | `false` - [`tlsMinVersion`](#spec-tls-tlsminversion): string | `TLSv1_2` - - [`tlsMaxVersion`](#spec-tls-tlsmaxversion): string - - [`cipherSuites`](#spec-tls-ciphersuites): list of strings - - [`sds`](#spec-tls-sds): map of strings - - [`clusterName`](#spec-tls-sds): string - - [`certResource`](#spec-tls-sds): string - - [`defaults`](#spec-defaults): map - - [`maxConnections`](#spec-defaults-maxconnections): number - - [`maxPendingRequests`](#spec-defaults-maxpendingrequests): number - - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests): number - - [`passiveHealthCheck`](#spec-defaults-passivehealthcheck): map + - [`tlsMaxVersion`](#spec-tls-tlsmaxversion): string + - [`cipherSuites`](#spec-tls-ciphersuites): list of strings + - [`sds`](#spec-tls-sds): map of strings + - [`clusterName`](#spec-tls-sds): string + - [`certResource`](#spec-tls-sds): string + - [`defaults`](#spec-defaults): map + - [`maxConnections`](#spec-defaults-maxconnections): number + - [`maxPendingRequests`](#spec-defaults-maxpendingrequests): number + - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests): number + - [`passiveHealthCheck`](#spec-defaults-passivehealthcheck): map - [`interval`](#spec-defaults-passivehealthcheck): number | no proxy's default value - [`max_failures`](#spec-defaults-passivehealthcheck): number | no proxy's default value - [`enforcing_consecutive_5xx`](#spec-defaults-passivehealthcheck): number | proxy's default value - - [`listeners`](#spec-listeners): list of maps + - [`listeners`](#spec-listeners): list of maps - [`port`](#spec-listeners-port): number | `0` - [`protocol`](#spec-listeners-protocol): number | `tcp` - - [`services`](#spec-listeners-services): list of maps - - [`name`](#spec-listeners-services-name): string + - [`services`](#spec-listeners-services): list of maps + - [`name`](#spec-listeners-services-name): string - [`namespace`](#spec-listeners-services-namespace): string | current namespace | - [`partition`](#spec-listeners-services-partition): string | current partition | - [`hosts`](#spec-listeners-services-hosts): list of strings | `.ingress.*` - - [`requestHeaders`](#spec-listeners-services-requestheaders): map - - [`add`](#spec-listeners-services-requestheaders): map of strings - - [`set`](#spec-listeners-services-requestheaders): map of strings - - [`remove`](#spec-listeners-services-requestheaders): list of strings - - [`responseHeaders`](#spec-listeners-services-responseheaders): map - - [`add`](#spec-listeners-services-responseheaders): map of strings - - [`set`](#spec-listeners-services-responseheaders): map of strings - - [`remove`](#spec-listeners-services-responseheaders): list of strings - - [`tls`](#spec-listeners-services-tls): map - - [`sds`](#spec-listeners-services-tls-sds): map of strings - - [`clusterName`](#spec-listeners-services-tls-sds): string - - [`certResource`](#spec-listeners-services-tls-sds): string + - [`requestHeaders`](#spec-listeners-services-requestheaders): map + - [`add`](#spec-listeners-services-requestheaders): map of strings + - [`set`](#spec-listeners-services-requestheaders): map of strings + - [`remove`](#spec-listeners-services-requestheaders): list of strings + - [`responseHeaders`](#spec-listeners-services-responseheaders): map + - [`add`](#spec-listeners-services-responseheaders): map of strings + - [`set`](#spec-listeners-services-responseheaders): map of strings + - [`remove`](#spec-listeners-services-responseheaders): list of strings + - [`tls`](#spec-listeners-services-tls): map + - [`sds`](#spec-listeners-services-tls-sds): map of strings + - [`clusterName`](#spec-listeners-services-tls-sds): string + - [`certResource`](#spec-listeners-services-tls-sds): string - [`maxConnections`](#spec-listeners-services-maxconnections): number | `0` - [`maxPendingRequests`](#spec-listeners-services-maxconnections): number | `0` - [`maxConcurrentRequests`](#spec-listeners-services-maxconnections): number | `0` - - [`passiveHealthCheck`](#spec-listeners-services-passivehealthcheck): map - - [`interval`](#spec-listeners-services-passivehealthcheck): number - - [`max_failures`](#spec-listeners-services-passivehealthcheck): number - - [`enforcing_consecutive_5xx`](#spec-listeners-services-passivehealthcheck): number - - [`tls`](#spec-listeners-tls): map + - [`passiveHealthCheck`](#spec-listeners-services-passivehealthcheck): map + - [`interval`](#spec-listeners-services-passivehealthcheck): number + - [`max_failures`](#spec-listeners-services-passivehealthcheck): number + - [`enforcing_consecutive_5xx`](#spec-listeners-services-passivehealthcheck): number + - [`tls`](#spec-listeners-tls): map - [`enabled`](#spec-listeners-tls-enabled): boolean | `false` - [`tlsMinVersion`](#spec-listeners-tls-tlsminversion): string | `TLSv1_2` - - [`tlsMaxVersion`](#spec-listeners-tls-tlsmaxversion): string - - [`cipherSuites`](#spec-listeners-tls-ciphersuites): list of strings - - [`sds`](#spec-listeners-tls-sds): map of strings - - [`clusterName`](#spec-listeners-tls-sds): string - - [`certResource`](#spec-listeners-tls-sds): string + - [`tlsMaxVersion`](#spec-listeners-tls-tlsmaxversion): string + - [`cipherSuites`](#spec-listeners-tls-ciphersuites): list of strings + - [`sds`](#spec-listeners-tls-sds): map of strings + - [`clusterName`](#spec-listeners-tls-sds): string + - [`certResource`](#spec-listeners-tls-sds): string @@ -156,94 +156,94 @@ When every field is defined, an ingress gateway configuration entry has the foll ```hcl -Kind = "ingress-gateway" -Name = "" -Namespace = "" -Partition = "" -Meta = { +Kind = "ingress-gateway" +Name = "" +Namespace = "" +Partition = "" +Meta = { = "" } -TLS = { - Enabled = false - TLSMinVersion = "TLSv1_2" - TLSMaxVersion = "" - CipherSuites = [ +TLS = { + Enabled = false + TLSMinVersion = "TLSv1_2" + TLSMaxVersion = "" + CipherSuites = [ "" ] - SDS = { - ClusterName = "" - CertResource = "" + SDS = { + ClusterName = "" + CertResource = "" } } -Defaults = { - MaxConnections = 0 - MaxPendingRequests = 0 - MaxConcurrentRequests = 0 - PassiveHealthCheck = { - interval = 10 - max_failures = 5 - enforcing_consecutive_5xx = 100 +Defaults = { + MaxConnections = 0 + MaxPendingRequests = 0 + MaxConcurrentRequests = 0 + PassiveHealthCheck = { + interval = 10 + max_failures = 5 + enforcing_consecutive_5xx = 100 } } -Listeners = [ - { - Port = 0 - Protocol = "tcp" - Services = [ - { - Name = "" - Namespace = "" - Partition = "" - Hosts = [ - ".ingress.*" +Listeners = [ + { + Port = 0 + Protocol = "tcp" + Services = [ + { + Name = "" + Namespace = "" + Partition = "" + Hosts = [ + ".ingress.*" ] - RequestHeaders = { - Add = { - RequestHeaderName = "" + RequestHeaders = { + Add = { + RequestHeaderName = "" } - Set = { - RequestHeaderName = "" + Set = { + RequestHeaderName = "" } - Remove = [ - "" + Remove = [ + "" ] } - ResponseHeaders = { - Add = { - ResponseHeaderName = "" + ResponseHeaders = { + Add = { + ResponseHeaderName = "" } - Set = { - ResponseHeaderName = "" + Set = { + ResponseHeaderName = "" } - Remove = [ - "" + Remove = [ + "" ] } - TLS = { - SDS = { - ClusterName = "" - CertResource = "" + TLS = { + SDS = { + ClusterName = "" + CertResource = "" } } - MaxConnections = - MaxPendingRequests = - MaxConcurrentRequests = - PassiveHealthCheck = { - interval = 10 - max_failures = 5 - enforcing_consecutive_5xx = 100 + MaxConnections = + MaxPendingRequests = + MaxConcurrentRequests = + PassiveHealthCheck = { + interval = 10 + max_failures = 5 + enforcing_consecutive_5xx = 100 } }] - TLS = { - Enabled = false - TLSMinVersion = "TLSv1_2" - TLSMaxVersion = "" - CipherSuites = [ - "" + TLS = { + Enabled = false + TLSMinVersion = "TLSv1_2" + TLSMaxVersion = "" + CipherSuites = [ + "" ] - SDS = { - ClusterName = "" - CertResource = "" + SDS = { + ClusterName = "" + CertResource = "" } } } @@ -256,71 +256,71 @@ Listeners = [ ```yaml apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway +kind: IngressGateway metadata: - name: - namespace: "" -spec: - tls: - enabled: false - tlsSMinVersion: TLSv1_2 - tlsMaxVersion: "" - cipherSuites: + name: + namespace: "" +spec: + tls: + enabled: false + tlsSMinVersion: TLSv1_2 + tlsMaxVersion: "" + cipherSuites: - - sds: - clusterName: - certResource: - defaults: - maxConnections: 0 - maxPendingRequests: 0 - maxConcurrentRequests: 0 - passiveHealthCheck: - interval: 10 - max_failures: 5 - enforcing_consecutive_5xx: 100 - listeners: - - port: 0 - protocol: tcp - services: - - name: - namespace: + sds: + clusterName: + certResource: + defaults: + maxConnections: 0 + maxPendingRequests: 0 + maxConcurrentRequests: 0 + passiveHealthCheck: + interval: 10 + max_failures: 5 + enforcing_consecutive_5xx: 100 + listeners: + - port: 0 + protocol: tcp + services: + - name: + namespace: partition: - hosts: - - .ingress.* - requestHeaders: - add: + hosts: + - .ingress.* + requestHeaders: + add: requestHeaderName: set: requestHeaderName: - remove: - - - responseHeaders: - add: - responseHeaderName: - set: + remove: + - + responseHeaders: + add: + responseHeaderName: + set: responseHeaderName: remove: - - - tls: - sds: + - + tls: + sds: clusterName: - certResource: - maxConnections: - maxPendingRequests: - maxConcurrentRequests: - passiveHealthCheck: - interval: 10 - max_failures: 5 - enforcing_consecutive_5xx: 100 - tls: - enabled: false - tlsMinVersion: TLSv1_2 - tlsMaxVersion: - cipherSuites: - - - sds: - clusterName: - certResource: + certResource: + maxConnections: + maxPendingRequests: + maxConcurrentRequests: + passiveHealthCheck: + interval: 10 + max_failures: 5 + enforcing_consecutive_5xx: 100 + tls: + enabled: false + tlsMinVersion: TLSv1_2 + tlsMaxVersion: + cipherSuites: + - + sds: + clusterName: + certResource: ``` @@ -329,100 +329,100 @@ spec: ```json { - "Kind" : "ingress-gateway", - "Name" : "", - "Namespace" : "", - "Partition" : "", - "Meta": { + "Kind" : "ingress-gateway", + "Name" : "", + "Namespace" : "", + "Partition" : "", + "Meta": { "" : "" }, - "TLS" : { - "Enabled" : false, - "TLSMinVersion" : "TLSv1_2", - "TLSMaxVersion" : "", - "CipherSuites" : [ + "TLS" : { + "Enabled" : false, + "TLSMinVersion" : "TLSv1_2", + "TLSMaxVersion" : "", + "CipherSuites" : [ "" ], - "SDS": { - "ClusterName" : "", - "CertResource" : "" + "SDS": { + "ClusterName" : "", + "CertResource" : "" } }, - "Defaults" : { - "MaxConnections" : 0, - "MaxPendingRequests" : 0, - "MaxConcurrentRequests": 0, - "PassiveHealthCheck" : { - "interval" : 10, - "max_failures" : 5, - "enforcing_consecutive_5xx" : 100 + "Defaults" : { + "MaxConnections" : 0, + "MaxPendingRequests" : 0, + "MaxConcurrentRequests": 0, + "PassiveHealthCheck" : { + "interval" : 10, + "max_failures" : 5, + "enforcing_consecutive_5xx" : 100 } }, - "Listeners" : [ - { - "Port" : 0, - "Protocol" : "tcp", - "Services" : [ - { - "Name" : "", - "Namespace" : "", - "Partition" : "", - "Hosts" : [ - ".ingress.*" + "Listeners" : [ + { + "Port" : 0, + "Protocol" : "tcp", + "Services" : [ + { + "Name" : "", + "Namespace" : "", + "Partition" : "", + "Hosts" : [ + ".ingress.*" ], - "RequestHeaders" : { - "Add" : { - "RequestHeaderName" : "" + "RequestHeaders" : { + "Add" : { + "RequestHeaderName" : "" }, - "Set" : { - "RequestHeaderName" : "" + "Set" : { + "RequestHeaderName" : "" }, - "Remove" : [ - "" + "Remove" : [ + "" ] }, - "ResponseHeaders" : { - "Add" : { - "ResponseHeaderName" : "" + "ResponseHeaders" : { + "Add" : { + "ResponseHeaderName" : "" }, - "Set" : { - "ResponseHeaderName" : "" + "Set" : { + "ResponseHeaderName" : "" }, - "Remove" : [ - "" + "Remove" : [ + "" ] }, - "TLS" : { - "SDS" : { - "ClusterName" : "", - "CertResource" : "" + "TLS" : { + "SDS" : { + "ClusterName" : "", + "CertResource" : "" } }, - "MaxConnections" : , - "MaxPendingRequests" : , - "MaxConcurrentRequests" : , - "PassiveHealthCheck" : { - "interval" : 10, - "max_failures" : 5, - "enforcing_consecutive_5xx" : 100 + "MaxConnections" : , + "MaxPendingRequests" : , + "MaxConcurrentRequests" : , + "PassiveHealthCheck" : { + "interval" : 10, + "max_failures" : 5, + "enforcing_consecutive_5xx" : 100 } } ], - "TLS" : { - "Enabled" : false, - "TLSMinVersion" : "TLSv1_2", - "TLSMaxVersion" : "", - "CipherSuites" : [ - "" + "TLS" : { + "Enabled" : false, + "TLSMinVersion" : "TLSv1_2", + "TLSMaxVersion" : "", + "CipherSuites" : [ + "" ], - "SDS" : { - "ClusterName" : "", - "CertResource" : "" + "SDS" : { + "ClusterName" : "", + "CertResource" : "" } } } ] -} +} ``` @@ -465,7 +465,7 @@ If unspecified, the ingress gateway is applied to the `default` namespace. You c #### Values -- Default: `default`, +- Default: `default`, - Data type: String ### `Partition` @@ -481,7 +481,7 @@ If unspecified, the ingress gateway is applied to the `default` partition. You c ### `Meta` -Defines an arbitrary set of key-value pairs to store in the Consul KV. +Defines an arbitrary set of key-value pairs to store in the Consul KV. #### Values @@ -492,7 +492,7 @@ Defines an arbitrary set of key-value pairs to store in the Consul KV. ### `TLS` -Specifies the TLS configuration settings for the gateway. +Specifies the TLS configuration settings for the gateway. #### Values @@ -502,18 +502,18 @@ Specifies the TLS configuration settings for the gateway. - [`TLSMinVersion`](#tls-tlsminversion) - [`TLSMaxVersion`](#tls-tlsmaxversion) - [`CipherSuites`](#tls-ciphersuites) - - [`SDS`](#tls-sds) + - [`SDS`](#tls-sds) ### `TLS.Enabled` Enables and disables TLS for the configuration entry. Set to `true` to enable built-in TLS for every listener on the gateway. TLS is disabled by default. -When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `TLS.TLSMinVersion` @@ -523,7 +523,7 @@ Specifies the minimum TLS version supported for gateway listeners. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -558,21 +558,21 @@ Specifies a list of cipher suites that gateway listeners support when negotiatin ### `TSL.SDS` -Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. Consul applies the SDS configuration specified in this field as defaults for all listeners defined in the gateway. You can override the SDS settings for per listener or per service defined in the listener. Refer to the following configurations for additional information: - [`Listeners.TLS.SDS`](#listeners-tls-sds): Configures SDS settings for all services in the listener. -- [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. +- [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. #### Values - Default: None -- Data type: Map containing the following fields: - - `ClusterName` +- Data type: Map containing the following fields: + - `ClusterName` - `CertResource` -The following table describes how to configure SDS parameters. +The following table describes how to configure SDS parameters. | Parameter | Description | Data type | | --- | --- | --- | @@ -588,13 +588,13 @@ Specifies default configurations for connecting upstream services. - Default: None - The data type is a map containing the following parameters: - - [`MaxConnnections`](#defaults-maxconnections) + - [`MaxConnections`](#defaults-maxconnections) - [`MaxPendingRequests`](#defaults-maxpendingrequests) - - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests) + - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests) ### `Defaults.MaxConnections` -Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. #### Values @@ -603,7 +603,7 @@ Specifies the maximum number of HTTP/1.1 connections a service instance is allow ### `Defaults.MaxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). #### Values @@ -612,7 +612,7 @@ Specifies the maximum number of requests that are allowed to queue while waiting ### `Defaults.MaxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). +Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). #### Values @@ -621,7 +621,7 @@ Specifies the maximum number of concurrent HTTP/2 traffic requests that are allo ### `Defaults.PassiveHealthCheck` -Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. +Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. #### Values @@ -651,7 +651,7 @@ Specifies a list of listeners in the mesh for the gateway. Listeners are uniquel ### `Listeners[].Port` -Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. +Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. #### Values @@ -663,7 +663,7 @@ Specifies the port that the listener receives traffic on. The port is bound to t Specifies the protocol associated with the listener. To enable L7 network management capabilities, specify one of the following values: - `http` -- `http2` +- `http2` - `grpc` #### Values @@ -673,12 +673,12 @@ Specifies the protocol associated with the listener. To enable L7 network manage - `tcp` - `http` - - `http2` + - `http2` - `grpc` ### `Listeners[].Services[]` -Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `Namespace` field is required for Consul Enterprise datacenters. If the [`Listeners.Protocol`] field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. +Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `Namespace` field is required for Consul Enterprise datacenters. If the [`Listeners.Protocol`] field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. #### Values @@ -711,7 +711,7 @@ Specifies the name of a service to expose to the listener. You can specify servi ### `Listeners[].Services[].Namespace` -Specifies the namespace to use when resolving the location of the service. +Specifies the namespace to use when resolving the location of the service. #### Values @@ -720,7 +720,7 @@ Specifies the namespace to use when resolving the location of the service. ### `Listeners[].Services[].Partition` -Specifies the admin partition to use when resolving the location of the service. +Specifies the admin partition to use when resolving the location of the service. #### Values @@ -729,18 +729,18 @@ Specifies the admin partition to use when resolving the location of the service. ### `Listeners[].Services[].Hosts[]` -Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. +Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. -If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. +If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. -When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. +When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. You can use the wildcard in the left-most DNS label to match a set of hosts. For example, `*.example.com` is valid, but `example.*` and `*-suffix.example.com` are invalid. #### Values - Default: None -- Data type: List of strings or `*` +- Data type: List of strings or `*` ### `Listeners[].Services[].RequestHeaders` @@ -757,7 +757,7 @@ Specifies a set of HTTP-specific header modification rules applied to requests r The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -782,7 +782,7 @@ Specifies a set of HTTP-specific header modification rules applied to responses The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `Set` | Defines a set of key-value pairs to add to the response header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -794,18 +794,18 @@ For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the ### `Listeners[].Services[].TLS` -Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`TLS`](#tls) settings for the configuration entry. +Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`TLS`](#tls) settings for the configuration entry. #### Values - Default: None -- Data type: Map +- Data type: Map ### `Listeners[].Services[].TLS.SDS` -Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. +Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -This configuration overrides the main [`TLS.SDS`](#tls-sds) settings for configuration entry. If unspecified, Consul applies the top-level [`TLS.SDS`](#tls-sds) settings. +This configuration overrides the main [`TLS.SDS`](#tls-sds) settings for configuration entry. If unspecified, Consul applies the top-level [`TLS.SDS`](#tls-sds) settings. #### Values @@ -823,7 +823,7 @@ The following table describes how to configure SDS parameters. Refer to [Configu ### `Listeners[].Services[].MaxConnections` -Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. When defined, this field overrides the [`Defaults.MaxConnections`](#defaults-maxconnections) configuration. @@ -834,9 +834,9 @@ When defined, this field overrides the [`Defaults.MaxConnections`](#defaults-max ### `Listeners[].Services.MaxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. When defined, this field overrides the value specified in the [`Defaults.MaxPendingRequests`](#defaults-maxpendingrequests) field of the configuration entry. +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. When defined, this field overrides the value specified in the [`Defaults.MaxPendingRequests`](#defaults-maxpendingrequests) field of the configuration entry. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. #### Values @@ -845,9 +845,9 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `Listeners[].Services[].MaxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. This field overrides the value set in the [`Defaults.MaxConcurrentRequests`](#defaults-maxconcurrentrequests) field of the configuration entry. +Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. This field overrides the value set in the [`Defaults.MaxConcurrentRequests`](#defaults-maxconcurrentrequests) field of the configuration entry. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. #### Values @@ -856,7 +856,7 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `Listeners[].Services[].PassiveHealthCheck` -Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. This field overrides the value set in the [`Defaults.PassiveHealthCheck`](#defaults-passivehealthcheck) field of the configuration entry. +Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. This field overrides the value set in the [`Defaults.PassiveHealthCheck`](#defaults-passivehealthcheck) field of the configuration entry. #### Values @@ -873,7 +873,7 @@ The following table describes the configurations for passive health checks: ### `Listeners[].TLS` -Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`TLS`](#tls) settings for the configuration entry. +Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`TLS`](#tls) settings for the configuration entry. #### Values @@ -887,12 +887,12 @@ Specifies the TLS configuration for the listener. If unspecified, Consul applies ### `Listeners[].TLS.Enabled` -Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `Listeners[].TLS.TLSMinVersion` @@ -902,7 +902,7 @@ Specifies the minimum TLS version supported for the listener. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -932,14 +932,14 @@ Specifies a list of cipher suites that the listener supports when negotiating co #### Values -- Default: None +- Default: None - Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. ### `Listeners[].TLS.SDS` Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `Listeners.TLS.SDS` configuration per service by configuring the [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds) settings for each service. +Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `Listeners.TLS.SDS` configuration per service by configuring the [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds) settings for each service. #### Values @@ -963,7 +963,7 @@ Kubernetes-only parameter that specifies the version of the Consul API that the ### `kind` -Specifies the type of configuration entry to implement. Must be set to `IngressGatewa`. +Specifies the type of configuration entry to implement. Must be set to `IngressGateway`. #### Values @@ -973,7 +973,7 @@ Specifies the type of configuration entry to implement. Must be set to `IngressG ### `metadata` -Specifies metadata for the gateway. +Specifies metadata for the gateway. #### Values @@ -1001,7 +1001,7 @@ If unspecified, the ingress gateway is applied to the `default` namespace. You c #### Values -- Default: `default`, +- Default: `default`, - Data type: String ### `spec` @@ -1019,7 +1019,7 @@ Kubernetes-only field that contains all of the configurations for ingress gatewa ### `spec.tls` -Specifies the TLS configuration settings for the gateway. +Specifies the TLS configuration settings for the gateway. #### Values @@ -1029,18 +1029,18 @@ Specifies the TLS configuration settings for the gateway. - [`tlsMinVersion`](#spec-tls-tlsminversion) - [`tlsMaxVersion`](#spec-tls-tlsmaxversion) - [`cipherSuites`](#spec-tls-tlsciphersuites) - - [`sds`](#spec-tls-sds) + - [`sds`](#spec-tls-sds) ### `spec.tls.enabled` Enables and disables TLS for the configuration entry. Set to `true` to enable built-in TLS for every listener on the gateway. TLS is disabled by default. -When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `spec.tls.tlsMinVersion` @@ -1050,7 +1050,7 @@ Specifies the minimum TLS version supported for gateway listeners. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -1085,21 +1085,21 @@ Specifies a list of cipher suites that gateway listeners support when negotiatin ### `spec.tls.sds` -Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. Consul applies the SDS configuration specified in this field as defaults for all listeners defined in the gateway. You can override the SDS settings for per listener or per service defined in the listener. Refer to the following configurations for additional information: - [`spec.listeners.tls.sds`](#spec-listeners-tls-sds): Configures SDS settings for all services in the listener. -- [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. +- [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. #### Values - Default: None -- Data type: Map containing the following fields: - - [`clusterName`] +- Data type: Map containing the following fields: + - [`clusterName`] - [`certResource`] -The following table describes how to configure SDS parameters. +The following table describes how to configure SDS parameters. | Parameter | Description | Data type | | --- | --- | --- | @@ -1115,9 +1115,9 @@ Specifies default configurations for upstream connections. - Default: None - The data type is a map containing the following parameters: - - [`maxConnnections`](#spec-defaults-maxconnections) + - [`maxConnections`](#spec-defaults-maxconnections) - [`maxPendingRequests`](#spec-defaults-maxpendingrequests) - - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) + - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) ### `spec.defaults.maxConnections` @@ -1130,7 +1130,7 @@ Specifies the maximum number of HTTP/1.1 connections a service instance is allow ### `spec.defaults.maxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.Protocol`](#spec-listeners-protocol). +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.Protocol`](#spec-listeners-protocol). If unspecified, Consul uses Envoy's configuration. The default for Envoy is `1024`. @@ -1141,7 +1141,7 @@ If unspecified, Consul uses Envoy's configuration. The default for Envoy is `102 ### `spec.defaults.maxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol). +Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol). If unspecified, Consul uses Envoy's configuration. The default for Envoy is `1024`. @@ -1152,7 +1152,7 @@ If unspecified, Consul uses Envoy's configuration. The default for Envoy is `102 ### `spec.defaults.passiveHealthCheck` -Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. +Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. #### Values @@ -1182,7 +1182,7 @@ Specifies a list of listeners in the mesh for the gateway. Listeners are uniquel ### `spec.listeners[].port` -Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. +Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. #### Values @@ -1194,7 +1194,7 @@ Specifies the port that the listener receives traffic on. The port is bound to t Specifies the protocol associated with the listener. To enable L7 network management capabilities, specify one of the following values: - `http` -- `http2` +- `http2` - `grpc` #### Values @@ -1204,12 +1204,12 @@ Specifies the protocol associated with the listener. To enable L7 network manage - `tcp` - `http` - - `http2` + - `http2` - `grpc` ### `spec.listeners[].services[]` -Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `namespace` field is required for Consul Enterprise datacenters. If the listener's [`protocol`](#spec-listeners-protocol) field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. +Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `namespace` field is required for Consul Enterprise datacenters. If the listener's [`protocol`](#spec-listeners-protocol) field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. #### Values @@ -1232,7 +1232,7 @@ Specifies a list of services that the listener exposes to services outside the m Specifies the name of a service to expose to the listener. You can specify services in the following ways: - Provide the name of a service registered in the Consul catalog. -- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. +- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. - Provide a `*` wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for additional information. #### Values @@ -1242,7 +1242,7 @@ Specifies the name of a service to expose to the listener. You can specify servi ### `spec.listeners[].services[].namespace` -Specifies the namespace to use when resolving the location of the service. +Specifies the namespace to use when resolving the location of the service. #### Values @@ -1251,7 +1251,7 @@ Specifies the namespace to use when resolving the location of the service. ### `spec.listeners[].services[].partition` -Specifies the admin partition to use when resolving the location of the service. +Specifies the admin partition to use when resolving the location of the service. #### Values @@ -1260,18 +1260,18 @@ Specifies the admin partition to use when resolving the location of the service. ### `spec.listeners[].services[].hosts[]` -Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. +Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. -If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. +If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. -When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. +When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. You can use the wildcard in the left-most DNS label to match a set of hosts. For example, `*.example.com` is valid, but `example.*` and `*-suffix.example.com` are invalid. #### Values - Default: None -- Data type: List of strings or `*` +- Data type: List of strings or `*` ### `spec.listeners[].services[].requestHeaders` @@ -1288,7 +1288,7 @@ Specifies a set of HTTP-specific header modification rules applied to requests r The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -1313,7 +1313,7 @@ Specifies a set of HTTP-specific header modification rules applied to responses The following table describes how to configure values for request headers: -| Rule | Description | Data type | +| Rule | Description | Data type | | --- | --- | --- | | `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | | `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | @@ -1325,18 +1325,18 @@ For `add` and `set`, if the service is configured to use Envoy as the proxy, the ### `spec.listeners[].services[].tls` -Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`tls`](#spec.tls) settings for the configuration entry. +Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`tls`](#spec.tls) settings for the configuration entry. #### Values - Default: None -- Data type: Map +- Data type: Map ### `spec.listeners[].services[].tls.sds` -Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. +Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -If unspecified, Consul applies the [`sds`](#spec-tls-sds) settings configured for the ingress gateway. If both are specified, this configuration overrides the settings for configuration entry. +If unspecified, Consul applies the [`sds`](#spec-tls-sds) settings configured for the ingress gateway. If both are specified, this configuration overrides the settings for configuration entry. #### Values @@ -1355,7 +1355,7 @@ The following table describes how to configure SDS parameters. Refer to [Serve c ### `spec-listeners[].services[].maxConnections` -Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. A value specified in this field overrides the [`maxConnections`](#spec-defaults-maxconnections) field specified in the `defaults` configuration. @@ -1366,9 +1366,9 @@ A value specified in this field overrides the [`maxConnections`](#spec-defaults- ### `spec.listeners[].services.maxPendingRequests` -Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. A value specified in this field overrides the [`maxPendingRequests`](#spec-defaults-maxpendingrequests) field specified in the `defaults` configuration. +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. A value specified in this field overrides the [`maxPendingRequests`](#spec-defaults-maxpendingrequests) field specified in the `defaults` configuration. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. #### Values @@ -1377,9 +1377,9 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `spec.listeners[].services[].maxConcurrentRequests` -Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. A value specified in this field overrides the [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) field specified in the `defaults` configuration entry. +Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. A value specified in this field overrides the [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) field specified in the `defaults` configuration entry. -Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. #### Values @@ -1388,7 +1388,7 @@ Listeners must use an L7 protocol for this configuration to take effect. Refer t ### `spec.listeners[].services[].passiveHealthCheck` -Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. Health checks specified for services override the health checks defined in the [`spec.defaults.passiveHealthCheck`](#spec-defaults-passivehealthcheck) configuration. +Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. Health checks specified for services override the health checks defined in the [`spec.defaults.passiveHealthCheck`](#spec-defaults-passivehealthcheck) configuration. #### Values @@ -1405,7 +1405,7 @@ The following table describes the configurations for passive health checks: ### `spec.listeners[].tls` -Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#spec-listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`tls`](#tls) settings for the configuration entry. +Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#spec-listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`tls`](#tls) settings for the configuration entry. #### Values @@ -1419,12 +1419,12 @@ Specifies the TLS configuration for the listener. If unspecified, Consul applies ### `spec.listeners[].tls.enabled` -Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). +Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). #### Values - Default: `false` - - Data type: boolean + - Data type: boolean ### `spec.listeners[].tls.tlsMinVersion` @@ -1434,7 +1434,7 @@ Specifies the minimum TLS version supported for the listener. - Default: Depends on the version of Envoy: - Envoy v1.22.0 and later: `TLSv1_2` - - Older versions: `TLSv1_0` + - Older versions: `TLSv1_0` - Data type: String with one of the following values: - `TLS_AUTO` - `TLSv1_0` @@ -1464,20 +1464,20 @@ Specifies a list of cipher suites that the listener supports when negotiating co #### Values -- Default: None +- Default: None - Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. ### `spec.listeners[].tls.sds` Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `spec.listeners[].tls.sds` configuration per service by configuring the [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds) settings for each service. +Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `spec.listeners[].tls.sds` configuration per service by configuring the [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds) settings for each service. #### Values - Default: None -- Data type: Map containing the following fields - - `clusterName` +- Data type: Map containing the following fields + - `clusterName` - `certResource` The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/tls-external-service#configure-static-sds-clusters) for usage information: @@ -1493,9 +1493,9 @@ The following table describes how to configure SDS parameters. Refer to [Configu ## Examples -Refer to the following examples for common ingress gateway configuration patterns: +Refer to the following examples for common ingress gateway configuration patterns: - [Define a TCP listener](#define-a-tcp-listener) -- [Use wildcards to define listeners](#use-wilcards-to-define-an-http-listener) +- [Use wildcards to define listeners](#use-wildcards-to-define-an-http-listener) - [HTTP listener with path-based routes](#http-listener-with-path-based-routes) ### Define a TCP listener @@ -1845,4 +1845,4 @@ spec: } ``` - \ No newline at end of file + diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index 43cfee2e5e..9ab8214cce 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -80,7 +80,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`remote`](#spec-jsonwebkeyset-remote): map - [`uri`](#spec-jsonwebkeyset-remote-uri): string - [`requestTimeoutMs`](#spec-jsonwebkeyset-remote-requesttimeoutms): integer - - [`cacheDuration`](#spec-jsonwebkeyset-remote-cacheduration): string | `5m` + - [`cacheDuration`](#spec-jsonwebkeyset-remote-cacheduration): string | `5m` - [`fetchAsynchronously`](#spec-jsonwebkeyset-remote-fetchasynchronously): boolean | `false` - [`retryPolicy`](#spec-jsonwebkeyset-remote-retrypolicy): map - [`numRetries`](#spec-jsonwebkeyset-remote-retrypolicy-numretries): integer | `0` @@ -156,7 +156,7 @@ JSONWebKeySet = { # specify only one child: TrustedCA or CaCertificateProviderInstance TLSCertificates = { # specify only one child: Filename, EnvironmentVariable, InlineString or InlineBytes - TrustedCA = { + TrustedCA = { Filename = "" EnvironmentVariable = "" InlineString = "" @@ -240,7 +240,7 @@ CacheConfig = { "TrustedCA": { "Filename": "", "EnvironmentVariable": "", - "InlineString": "", + "InlineString": "", "InlineBytes": "\302\000\302\302\302\302" }, "TLSCertificates": { @@ -317,17 +317,17 @@ spec: # required tlsCertificates: # specify only one child: filename, environmentVariable, inlineString or inlineBytes trustedCA: - filename: + filename: environmentVariable: inlineString: - inlineBytes: \302\000\302\302\302\302 + inlineBytes: \302\000\302\302\302\302 tlsCertificates: caCertificateProviderInstance: instanceName: certificateName: audiences: [] - locations: - header: + locations: + header: name: valuePrefix: "" forward: false @@ -335,7 +335,7 @@ spec: # required name: "" cookie: name: "" - forwarding: + forwarding: headerName: "" padForwardPayloadHeader: false clockSkewSeconds: 30 @@ -435,8 +435,8 @@ Specifies a remote source for the JSON Web Key Set and configures behavior when - Data type: Map that can contain the following parameters: - [`URI`](#jsonwebkeyset-remote-uri) - - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms) - - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration) + - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms) + - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration) - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously) - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy) - [`JWKSCluster`](#jsonwebkeyset-remote-jwkscluster) @@ -504,7 +504,7 @@ Specifies the number of times to attempt to fetch the JSON Web Key Set when the ### `JSONWebKeySet{}.Remote{}.RetryPolicy{}.RetryPolicyBackoff` -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 ### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.CaCertificateProviderInstance` -Speficies the certificate provider instance for fetching TLS certificates. +Specifies the certificate provider instance for fetching TLS certificates. #### Values @@ -582,13 +582,13 @@ Speficies the certificate provider instance for fetching TLS certificates. | :-------- | :------------------------------------------------- | :-------- | :------------ | | `InstanceName`| Refers to the certificate provider instance name. | String | `default` | | `CertificateName` | Specifies the certificate instances or types. For example, use `ROOTCA` to specify a root-certificate. | String | None | - + ### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.TrustedCA` 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 ### `spec.jsonWebKeySet.remote.retryPolicy.retryPolicyBackoff` -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. ### `spec.jsonWebKeySet.remote.jwksCluster.discoveryType` 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- ### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.caCertificateProviderInstance` -Speficies the certificate provider instance for fetching TLS certificates. +Specifies the certificate provider instance for fetching TLS certificates. #### Values @@ -1028,13 +1028,13 @@ Speficies the certificate provider instance for fetching TLS certificates. | :-------- | :------------------------------------------------- | :-------- | :------------ | | `instanceName`| Refers to the certificate provider instance name. | String | `default` | | `certificateName` | Specifies the certificate instances or types. For example, use `ROOTCA` to specify a root-certificate. | String | None | - + ### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.trustedCA` 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. diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index 9787d39b37..648271c684 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -17,8 +17,8 @@ The following outline shows how to format the service defaults configuration ent - [`Kind`](#kind): string | required - [`Name`](#name): string | required -- [`Namespace`](#namespace): string -- [`Partition`](#partition): string +- [`Namespace`](#namespace): string +- [`Partition`](#partition): string - [`Meta`](#meta): map | no default - [`Protocol`](#protocol): string | default: `tcp` - [`BalanceInboundConnections`](#balanceinboundconnections): string | no default @@ -32,8 +32,8 @@ The following outline shows how to format the service defaults configuration ent - [`ConnectTimeoutMs`](#upstreamconfig-overrides-connecttimeoutms): int | default: `5000` - [`MeshGateway`](#upstreamconfig-overrides-meshgateway): map | no default - [`mode`](#upstreamconfig-overrides-meshgateway): string | no default - - [`BalanceOutboundConnections`](#upstreamconfig-overrides-balanceoutboundconnections): string | no default - - [`Limits`](#upstreamconfig-overrides-limits): map | optional + - [`BalanceOutboundConnections`](#upstreamconfig-overrides-balanceoutboundconnections): string | no default + - [`Limits`](#upstreamconfig-overrides-limits): map | optional - [`MaxConnections`](#upstreamconfig-overrides-limits): integer | `0` - [`MaxPendingRequests`](#upstreamconfig-overrides-limits): integer | `0` - [`MaxConcurrentRequests`](#upstreamconfig-overrides-limits): integer | `0` @@ -46,15 +46,15 @@ The following outline shows how to format the service defaults configuration ent - [`ConnectTimeoutMs`](#upstreamconfig-defaults-connecttimeoutms): int | default: `5000` - [`MeshGateway`](#upstreamconfig-defaults-meshgateway): map | no default - [`mode`](#upstreamconfig-defaults-meshgateway): string | no default - - [`BalanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default - - [`Limits`](#upstreamconfig-defaults-limits): map | optional + - [`BalanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default + - [`Limits`](#upstreamconfig-defaults-limits): map | optional - [`MaxConnections`](#upstreamconfig-defaults-limits): integer | `0` - [`MaxPendingRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`MaxConcurrentRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`PassiveHealthCheck`](#upstreamconfig-defaults-passivehealthcheck): map | optional - [`Interval`](#upstreamconfig-defaults-passivehealthcheck): string | `0s` - [`MaxFailures`](#upstreamconfig-defaults-passivehealthcheck): integer | `0` - - [`EnforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | + - [`EnforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | - [`TransparentProxy`](#transparentproxy): map | no default - [`OutboundListenerPort`](#transparentproxy): integer | `15001` - [`DialedDirectly`](#transparentproxy ): boolean | `false` @@ -87,7 +87,7 @@ The following outline shows how to format the service defaults configuration ent - [`kind`](#kind): string | no default - [`metadata`](#metadata): map | no default - [`name`](#name): string | no default - - [`namespace`](#namespace): string | no default | + - [`namespace`](#namespace): string | no default | - [`spec`](#spec): map | no default - [`protocol`](#protocol): string | default: `tcp` - [`balanceInboundConnections`](#balanceinboundconnections): string | no default @@ -101,8 +101,8 @@ The following outline shows how to format the service defaults configuration ent - [`connectTimeoutMs`](#upstreamconfig-overrides-connecttimeoutms): int | default: `5000` - [`meshGateway`](#upstreamconfig-overrides-meshgateway): map | no default - [`mode`](#upstreamconfig-overrides-meshgateway): string | no default - - [`balanceOutboundConnections`](#overrides-balanceoutboundconnections): string | no default - - [`limits`](#upstreamconfig-overrides-limits): map | optional + - [`balanceOutboundConnections`](#overrides-balanceoutboundconnections): string | no default + - [`limits`](#upstreamconfig-overrides-limits): map | optional - [`maxConnections`](#upstreamconfig-overrides-limits): integer | `0` - [`maxPendingRequests`](#upstreamconfig-overrides-limits): integer | `0` - [`maxConcurrentRequests`](#upstreamconfig-overrides-limits): integer | `0` @@ -115,15 +115,15 @@ The following outline shows how to format the service defaults configuration ent - [`connectTimeoutMs`](#upstreamconfig-defaults-connecttimeoutms): int | default: `5000` - [`meshGateway`](#upstreamconfig-defaults-meshgateway): map | no default - [`mode`](#upstreamconfig-defaults-meshgateway): string | no default - - [`balanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default - - [`limits`](#upstreamconfig-defaults-limits): map | optional + - [`balanceOutboundConnections`](#upstreamconfig-defaults-balanceoutboundconnections): string | no default + - [`limits`](#upstreamconfig-defaults-limits): map | optional - [`maxConnections`](#upstreamconfig-defaults-limits): integer | `0` - [`maxPendingRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`maxConcurrentRequests`](#upstreamconfig-defaults-limits): integer | `0` - [`passiveHealthCheck`](#upstreamconfig-defaults-passivehealthcheck): map | optional - [`interval`](#upstreamconfig-defaults-passivehealthcheck): string | `0s` - [`maxFailures`](#upstreamconfig-defaults-passivehealthcheck): integer | `0` - - [`enforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | + - [`enforcingConsecutive5xx`](#upstreamconfig-defaults-passivehealthcheck): integer | - [`transparentProxy`](#transparentproxy): map | no default - [`outboundListenerPort`](#transparentproxy): integer | `15001` - [`dialedDirectly`](#transparentproxy): boolean | `false` @@ -249,15 +249,15 @@ Expose = { ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceDefaults -metadata: +metadata: name: namespace: -spec: +spec: protocol: tcp - balanceInboundConnnections: exact_balance + balanceInboundConnections: exact_balance mode: transparent upstreamConfig: - overrides: + overrides: - name: namespace: peer: @@ -266,25 +266,25 @@ spec: meshGateway: mode: balanceOutboundConnections: exact_balance - limits: + limits: maxConnections: 0 maxPendingRequests: 0 maxConcurrentRequests: 0 - passiveHealthCheck: + passiveHealthCheck: interval: 0s maxFailures: 0 enforcingConsecutive5xx: 100 - defaults: + defaults: protocol: connectTimeoutMs: 5000 meshGateway: mode: 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: externalSNI: - expose: + expose: checks: false - paths: + paths: - path: 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. @@ -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` -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: - [observability](/consul/docs/connect/observability) -- [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter) -- [service router configuration entry](/consul/docs/connect/config-entries/service-router) +- [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter) +- [service router configuration entry](/consul/docs/connect/config-entries/service-router) - [L7 intentions](/consul/docs/connect/intentions#l7-traffic-intentions) -You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration. +You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration. #### Values - Default: `tcp` -- You can speciyf one of the following string values: +- You can specify one of the following string values: - `tcp` (default) - - `http` + - `http` - `http2` - - `grpc` + - `grpc` Refer to [Set the default protocol](#set-the-default-protocol) for an example configuration. ### `BalanceInboundConnections` -Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -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: - [`UpstreamConfig.Overrides`](#upstreamconfig-overrides) - [`UpstreamConfig.Defaults`](#upstreamconfig-defaults) @@ -517,7 +517,7 @@ Controls default upstream connection settings and custom overrides for individua ### `UpstreamConfig.Overrides[]` -Specifies options that override the [default upstream configurations](#upstreamconfig-defaults) for individual upstreams. +Specifies options that override the [default upstream configurations](#upstreamconfig-defaults) for individual upstreams. #### Values @@ -535,7 +535,7 @@ Specifies the name of the upstream service that the configuration applies to. We ### `UpstreamConfig.Overrides[].Namespace` -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. ### `UpstreamConfig.Overrides[].BalanceOutboundConnections` -Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. +Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. #### Values -The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. - Default: none - Data type: string ### `UpstreamConfig.Overrides[].Limits` -Map that specifies a set of limits to apply to when connecting to individual upstream services. +Map that specifies a set of limits to apply to when connecting to individual upstream services. #### Values @@ -615,7 +615,7 @@ Refer to the [upstream configuration example](#upstream-configuration) for addit ### `UpstreamConfig.Overrides[].PassiveHealthCheck` -Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. +Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. #### Values @@ -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. ### `UpstreamConfig.Defaults.BalanceOutboundConnections` -Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. - Default: none - Data type: string @@ -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 -### `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: - [observability](/consul/docs/connect/observability) -- [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter) -- [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router) +- [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter) +- [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router) - [L7 intentions](/consul/docs/connect/intentions#l7-traffic-intentions) -You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration. +You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration. #### Values - Default: `tcp` - You can specify one of the following string values: - - `tcp` - - `http` + - `tcp` + - `http` - `http2` - - `grpc` + - `grpc` Refer to [Set the default protocol](#set-the-default-protocol) for an example configuration. ### `spec.balanceInboundConnections` -Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Specifies the strategy for allocating inbound connections to the service across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -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 ### `spec.upstreamConfig.overrides[].connectTimeoutMs` -Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. +Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. @@ -970,19 +970,19 @@ We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/ ### `spec.upstreamConfig.overrides[].meshGateway.mode` -Map that contains the default mesh gateway `mode` field for the upstream. Refer to [Connect Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) in the mesh gateway documentation for additional information. +Map that contains the default mesh gateway `mode` field for the upstream. Refer to [Connect Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) in the mesh gateway documentation for additional information. #### Values You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. ### `spec.upstreamConfig.overrides[].balanceInboundConnections` -Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Sets the strategy for allocating outbound connections from the upstream across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -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: ### `spec.upstreamConfig.overrides[].passiveHealthCheck` -Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. +Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. #### Values @@ -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 ### `spec.upstreamConfig.default.connectTimeoutMs` -Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. +Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for upstream destination services. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. @@ -1048,19 +1048,19 @@ We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/ ### `spec.upstreamConfig.defaults.meshGateway.mode` -Specifies the default mesh gateway `mode` field for all upstreams. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. +Specifies the default mesh gateway `mode` field for all upstreams. Refer to [Service Mesh Proxy Configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) in the mesh gateway documentation for additional information. #### Values You can specify the following string values for the `mode` field: - `none`: The service does not make outbound connections through a mesh gateway. Instead, the service makes outbound connections directly to the destination services. -- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. -- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. +- `local`: The service mesh proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. ### `spec.upstreamConfig.defaults.balanceInboundConnections` -Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. +Sets the strategy for allocating outbound connections from upstreams across Envoy proxy threads. The only supported value is `exact_balance`. By default, no connections are balanced. Refer to the [Envoy documentation](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig) for details. #### Values @@ -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` | ### `spec.upstreamConfig.defaults.passiveHealthCheck` -Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. +Map that specifies a set of rules that enable Consul to remove hosts from the upstream cluster that are unreachable or that return errors. #### Values @@ -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 -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. @@ -1645,7 +1645,7 @@ represents a location outside the Consul cluster. Services can dial destinations { name: 'Peer', type: 'string: ""', - description: + description: `The peer name of the upstream. Do not use a wildcard specifier ( \`*\`).`, }, { @@ -1660,7 +1660,7 @@ represents a location outside the Consul cluster. Services can dial destinations proxy upstream config will not fully enable some [L7 features](/consul/docs/connect/l7-traffic). It is supported here for backwards compatibility with Consul versions prior to 1.6.0. - In addition, the \`protocol\` of a peered service cannot be overriden. Any value in + In addition, the \`protocol\` of a peered service cannot be overridden. Any value in this field is ignored for peered services. `, }, @@ -1784,15 +1784,15 @@ represents a location outside the Consul cluster. Services can dial destinations name: 'MaxEjectionPercent', type: 'int: 10', description: `Measured in percent (%), the maximum percentage of hosts that can be ejected - from a upstream cluster due to passive health check failures. If not specified, inherits + from a upstream cluster due to passive health check failures. If not specified, inherits Envoy's default of 10% or at least one host.`, }, { name: 'BaseEjectionTime', type: 'duration: 30s', description: `The base time that a host is ejected for. The real time is equal to the base - time multiplied by the number of times the host has been ejected and is capped by - max_ejection_time (Default 300s). If not speficied, inherits Envoy's default value of 30s.`, + 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.`, }, ], }, @@ -1949,15 +1949,15 @@ represents a location outside the Consul cluster. Services can dial destinations name: 'MaxEjectionPercent', type: 'int: 10', description: `Measured in percent (%), the maximum percentage of hosts that can be ejected - from a upstream cluster due to passive health check failures. If not specified, inherits + from a upstream cluster due to passive health check failures. If not specified, inherits Envoy's default of 10% or at least one host.`, }, { name: 'BaseEjectionTime', type: 'duration: 30s', description: `The base time that a host is ejected for. The real time is equal to the base - time multiplied by the number of times the host has been ejected and is capped by - max_ejection_time (Default 300s). If not speficied, inherits Envoy's default value of 30s.`, + 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.`, }, ], }, diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 8d7572c772..bf57733892 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -18,11 +18,11 @@ The following outline shows how to format the service intentions configuration e - [`Kind`](#kind): string | required | must be set to `service-intentions` -- [`Name`](#name): string | required +- [`Name`](#name): string | required - [`Namespace`](#namespace): string | `default` | - [`Partition`](#partition): string | `default` | -- [`Meta`](#meta): map -- [`JWT`](#jwt): map +- [`Meta`](#meta): map +- [`JWT`](#jwt): map - [`Providers`](#jwt-providers): list of maps - [`Name`](#jwt-providers-name): string - [`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 = "" Namespace = "" # string Partition = "" # string Meta = { - "" = "" - "" = "" - } + "" = "" + "" = "" + } JWT = { Providers = [ { @@ -141,14 +141,14 @@ Sources = [ Partition = "" # string SamenessGroup = "" # string Action = "allow" or "deny" # string for L4 intentions - Permissions = [ - { - Action = "allow" or "deny" # string for L7 intenions - HTTP = { - PathExact = "" # string - PathPrefix = "" # string - PathRegex = "" # string - Methods = [ + Permissions = [ + { + Action = "allow" or "deny" # string for L7 intentions + HTTP = { + PathExact = "" # string + PathPrefix = "" # string + PathRegex = "" # string + Methods = [ "", # string "" ] @@ -174,17 +174,17 @@ Sources = [ Regex = "" # string Invert = # boolean } - ] + ] } - } + } ] - Type = "consul" # string - Description = "" # string + Type = "consul" # string + Description = "" # string Precedence = # number - LegacyID = # string + LegacyID = # string LegacyMeta = # string LegacyCreateTime = # string - LegacyUpdateTime = # string + LegacyUpdateTime = # 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` +### `Namespace` -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` +### `Partition` -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. #### Values - Default: None - Data type: String -### `Sources[].Namespace` +### `Sources[].Namespace` -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`](#sources-peer) is unspecified, defaults to the destination [`Namespace`](#namespace). - Data type: String -### `Sources[].Partition` +### `Sources[].Partition` -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). - Data type: string -### `Sources[].SamenessGroup` +### `Sources[].SamenessGroup` -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 - Default: None - Data type: String -### `metadata.namespace` +### `metadata.namespace` 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. #### Values - Default: None - Data type: String -### `spec.sources[].namespace` +### `spec.sources[].namespace` -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. - Data type: String -### `spec.sources[].partition` +### `spec.sources[].partition` -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). - Data type: String -### `spec.sources[].samenessGroup` +### `spec.sources[].samenessGroup` -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`. - + ```hcl Kind = "service-intentions" @@ -1019,7 +1019,7 @@ spec: ### L4 intentions for all destinations -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. @@ -1064,7 +1064,7 @@ spec: ### L4 intentions for all sources -In the following L4 example, the source is configured with a `*` wildcard. As a result, traffic from any service is denied to `db` service instances. +In the following L4 example, the source is configured with a `*` wildcard. As a result, traffic from any service is denied to `db` service instances. @@ -1206,7 +1206,7 @@ spec: ### gRPC -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: @@ -1517,7 +1517,7 @@ Sources = [ providers: - name: okta verifyClaims: - - path: + - path: - perms - role value: admin diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index b4218d6d06..03b97be2dd 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -1,7 +1,7 @@ --- layout: docs 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 = "" -Namespace = "" -Partition = "" +Namespace = "" +Partition = "" Meta = { = "" } @@ -220,7 +220,7 @@ LoadBalancer = { "Kind":"service-resolver", // required "Name":"", "Namespace":"", - "Partition":"parition-configuration-applies-to>", + "Partition":"partition-configuration-applies-to>", "Meta":{ "":"" }, @@ -288,7 +288,7 @@ LoadBalancer = { }, "SourceIP":false, // cannot specify with Field or FieldValue "Terminal":false - } + } ] } } @@ -300,7 +300,7 @@ LoadBalancer = { ```yaml apiVersion: consul.hashicorp.com/v1alpha1 # required -kind: ServiceResolver # required +kind: ServiceResolver # required metadata: name: namespace: @@ -315,7 +315,7 @@ spec: filter: onlyPassing: false defaultSubset: - redirect: + redirect: service: servicesubset: namespace: @@ -323,7 +323,7 @@ spec: samenessGroup: peer: failover: # requires at least one of the following: service, serviceSubset, namespace, targets, datacenters, samenessGroup - : + : targets: - service: - serviceSubset: @@ -445,7 +445,7 @@ For additional guidance, refer to the [filter on service version configuration e - Data type: Map containing a key-value pair. - ``: String that names the subset. The string must be valid as a DNS subdomain element. - ``: Map that can contain the following parameters: - + | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | | `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: - + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | | `ChoiceCount` | Specifies the number of random healthy hosts from which to select the one with the least requests. | Integer | `2` | @@ -732,7 +732,7 @@ Specifies configuration for the `ring_hash` policy type. - Default: None - Data type: List that can contain the following parameters: - + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------- | --------- | ------- | | `MinimumRingSize` | Determines the minimum number of entries in the hash ring. | Integer | `1024` | @@ -789,7 +789,7 @@ Specifies additional configuration options for the `cookie` hash policy type. Th - Default: None - Data type: Map that can contain the following parameters: - + | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | | `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 be source 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 - + ### `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: - + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | | `choiceCount` | Specifies the number of random healthy hosts from which to select the one with the least requests. | Integer | `2` | @@ -1193,7 +1193,7 @@ Specifies configuration for the `ring_hash` policy type. - Default: None - Data type: List that can contain the following parameters: - + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------- | --------- | ------- | | `minimumRingSize` | Determines the minimum number of entries in the hash ring. | Integer | `1024` | @@ -1217,7 +1217,7 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. Specifies the attribute type to hash on. You cannot specify the `field` parameter if `sourceIP` is also configured. -Supported attribute types include the following: +Supported attribute types include the following: | Attribute | Description | | :--------- | :-------------------------------------------------------------- | @@ -1250,7 +1250,7 @@ Specifies additional configuration options for the `cookie` hash policy type. Th - Default: None - Data type: Map that can contain the following parameters: - + | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | | `session` | Directs Consul to generate a session cookie with no expiration. | Boolean | `false` | @@ -1259,7 +1259,7 @@ Specifies additional configuration options for the `cookie` hash policy type. Th ### `spec.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 be source IP address. You cannot specify `sourceIP` if `field` or `fieldValue` are configured. #### Values @@ -1346,7 +1346,7 @@ spec: ### Resolve virtual upstreams -The folowing example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service. +The following example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service. diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 4362925f59..fd3e1b04be 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -1,7 +1,7 @@ --- layout: docs 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 - [`Name`](#name): string | required - [`Namespace`](#namespace): string - [`Partition`](#partition): string | `default` -- [`Meta`](#meta): map +- [`Meta`](#meta): map - [`Routes`](#routes): list - [`Match`](#routes-match): map - [`HTTP`](#routes-match-http): map @@ -114,7 +114,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`add`](#spec-routes-destination-responseheaders): map - [`set`](#spec-routes-destination-responseheaders): map - [`remove`](#spec-routes-destination-responseheaders): map - + @@ -169,7 +169,7 @@ Routes = [ Name = "" ## required when specifying Routes.Match.HTTP.Header Present = false Exact = "" - Regex = "" + Regex = "" ] } }, @@ -181,7 +181,7 @@ Routes = [ Namespace = "" Partition = "" PrefixRewrite = "" ## required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact - RequestTimeout = 0 + RequestTimeout = 0 IdleTimeout = 0 NumRetries = 1 RetryOnConnectFailure = false @@ -222,9 +222,9 @@ Routes = [ "HTTP": { "PathExact": "" // cannot specify with PathPrefix or PathRegex }, - "HTTP": { + "HTTP": { "PathPrefix": "" // cannot specify with PathExact or PathRegex - }, + }, "HTTP": { "PathRegex": "" // cannot specify with PathPrefix or PathExact }, @@ -249,7 +249,7 @@ Routes = [ "Name": "", // required when specifying Routes.Match.HTTP.Header "Present": false, "Exact": "", - "Regex": "" + "Regex": "" ] } }, @@ -260,7 +260,7 @@ Routes = [ "Namespace": "", "Partition": "", "PrefixRewrite": "", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact - "RequestTimeout": 0, + "RequestTimeout": 0, "IdleTimeout": 0, "NumRetries": 1, "RetryOnConnectFailure": false, @@ -288,7 +288,7 @@ Routes = [ ```yaml apiVersion: consul.hashicorp.com/v1alpha1 # required -kind: ServiceRouter # required +kind: ServiceRouter # required metadata: name: namespace: @@ -301,7 +301,7 @@ spec: pathPrefix: ## cannot specify with pathExact or pathRegex http: pathRegex: ## 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: ## required when specifying spec.routes.match.http.header present: false exact: - regex: + regex: destination: service: @@ -325,7 +325,7 @@ spec: namespace: partition: prefixRewrite: ## 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 -### `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. @@ -1685,4 +1685,4 @@ spec: ``` - \ No newline at end of file + diff --git a/website/content/docs/connect/dataplane/consul-dataplane.mdx b/website/content/docs/connect/dataplane/consul-dataplane.mdx index cf0ae43321..fa29bf8de5 100644 --- a/website/content/docs/connect/dataplane/consul-dataplane.mdx +++ b/website/content/docs/connect/dataplane/consul-dataplane.mdx @@ -15,7 +15,7 @@ Usage: `consul-dataplane [options]` ### Requirements -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). ### Startup diff --git a/website/content/docs/connect/gateways/mesh-gateway/index.mdx b/website/content/docs/connect/gateways/mesh-gateway/index.mdx index bcac555527..6faec5e9e7 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/index.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/index.mdx @@ -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. diff --git a/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx index 3cf7eadc64..7fa47f215a 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx @@ -57,7 +57,7 @@ For Consul Enterprise clusters, mesh gateways must be registered in the "default -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" -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`. @@ -122,12 +122,12 @@ Peering { ```yaml Kind: mesh -Peeering: +Peering: PeerThroughMeshGateways: true ``` -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. diff --git a/website/content/docs/connect/intentions/create-manage-intentions.mdx b/website/content/docs/connect/intentions/create-manage-intentions.mdx index ecd7987e84..7f224ed6f9 100644 --- a/website/content/docs/connect/intentions/create-manage-intentions.mdx +++ b/website/content/docs/connect/intentions/create-manage-intentions.mdx @@ -7,7 +7,7 @@ description: >- # Create and manage intentions -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 -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`: ```shell-session -$ curl --request PUT \ +$ curl --request PUT \ --data ' { "Action": "allow" } ' \ -http://localhost:8500/v1/connect/intentions/exact\?source\=web\&destination\=db +http://localhost:8500/v1/connect/intentions/exact\?source\=web\&destination\=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: @@ -76,18 +76,18 @@ For L7 intentions, specify the `Permissions` in the request payload to configure -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: ```shell-session -$ curl --request PUT \ +$ curl --request PUT \ --data @payload.json \ -http://localhost:8500/v1/connect/intentions/exact\?source\=svc1\&destination\=sv2 +http://localhost:8500/v1/connect/intentions/exact\?source\=svc1\&destination\=sv2 ``` ### CLI -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 - @@ -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: - + - [`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: -- [`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 -[service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults) +[service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults) 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) \ No newline at end of file +- [How to Use Configuration Entries](/consul/docs/agent/config-entries) +- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds) diff --git a/website/content/docs/connect/proxies/envoy-extensions/configuration/wasm.mdx b/website/content/docs/connect/proxies/envoy-extensions/configuration/wasm.mdx index 56d910f3ee..41506025fd 100644 --- a/website/content/docs/connect/proxies/envoy-extensions/configuration/wasm.mdx +++ b/website/content/docs/connect/proxies/envoy-extensions/configuration/wasm.mdx @@ -1,10 +1,10 @@ --- layout: docs -page_title: WebAssembly extension configuration reference +page_title: WebAssembly extension configuration reference 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. - -- [`Protocol`](#protocol): string + +- [`Protocol`](#protocol): string - [`ListenerType`](#listenertype): string | required - [`ProxyType`](#proxytype): string | `connect-proxy` - [`PluginConfig`](#pluginconfig): map | required - [`Name`](#pluginconfig-name): string - [`RootID`](#pluginconfig-rootid): string | required - [`VmConfig`](#pluginconfig-vmconfig): map - - [`VmID`](#pluginconfig-vmconfig-vmid): string + - [`VmID`](#pluginconfig-vmconfig-vmid): string - [`Runtime`](#pluginconfig-vmconfig): string | `v8` - [`Code`](#pluginconfig-vmconfig-code): map - [`Local`](#pluginconfig-vmconfig-code-local): map @@ -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 = "" +Protocol = "" ListenerType = "" ProxyType = "connect-proxy" PluginConfig = { @@ -73,7 +73,7 @@ PluginConfig = { HttpURI = { Service = { Name = "" - Namespace = "" + Namespace = "" Partition = "" } URI = "" @@ -82,19 +82,19 @@ PluginConfig = { RetryPolicy = { RetryBackOff = { BaseInterval = "1s" - MaxInterval = "10s" + MaxInterval = "10s" } NumRetries = -1 } } Configuration = "" 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 ### `PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.Service` -Specifies the upstream service to fetch the remote plugin from. +Specifies the upstream service to fetch the remote plugin from. #### Values @@ -295,17 +295,17 @@ The following table describes the fields you can specify in the `Service` map: ### `PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.URI` -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. #### Values - Default: None - This field is required. -- Data type: String value that specifies a FDQN +- Data type: String value that specifies a FQDN ### `PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.Timeout` -Specifies the maximum duration that a response can take to complete the request for the plugin data. +Specifies the maximum duration that a response can take to complete the request for the plugin data. #### Values @@ -335,7 +335,7 @@ Defines a policy for retrying requests to the upstream service when fetching the - Data type: Map ### `PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}.RetryBackOff{}` -Specifies parameters that control retry backoff strategy. +Specifies parameters that control retry backoff strategy. #### Values @@ -370,9 +370,9 @@ Specifies the configuration Envoy encodes as bytes and passes to the plugin duri ### `PluginConfig{}.VmConfig{}.EnvironmentVariables{}` -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 ### `PluginConfig{}.CapabilityRestrictionConfiguration{}` -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. ```hcl Kind = "proxy-defaults" diff --git a/website/content/docs/connect/proxies/envoy-extensions/index.mdx b/website/content/docs/connect/proxies/envoy-extensions/index.mdx index d79d78b50e..8cea47b0ec 100644 --- a/website/content/docs/connect/proxies/envoy-extensions/index.mdx +++ b/website/content/docs/connect/proxies/envoy-extensions/index.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Envoy Extensions description: >- - 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. diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 51ff61d8a2..7c87842c1d 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -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 | | ------------------- | ------------------------------------------------------------|----------------------------------------------| | 1.16.x | 1.2.x (Envoy 1.26.x) | 1.1.x (Envoy 1.25.x) | | 1.15.x | 1.1.x (Envoy 1.25.x) | 1.2.x (Envoy 1.26.x), 1.0.x (Envoy 1.24.x) | @@ -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 diff --git a/website/content/docs/consul-vs-other/service-mesh-compare.mdx b/website/content/docs/consul-vs-other/service-mesh-compare.mdx index 419f5679ba..1164336781 100644 --- a/website/content/docs/consul-vs-other/service-mesh-compare.mdx +++ b/website/content/docs/consul-vs-other/service-mesh-compare.mdx @@ -2,14 +2,14 @@ layout: docs 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. diff --git a/website/content/docs/ecs/compatibility.mdx b/website/content/docs/ecs/compatibility.mdx index 8fc0fd0808..c243a95878 100644 --- a/website/content/docs/ecs/compatibility.mdx +++ b/website/content/docs/ecs/compatibility.mdx @@ -1,11 +1,11 @@ --- layout: docs -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. diff --git a/website/content/docs/enterprise/index.mdx b/website/content/docs/enterprise/index.mdx index 7d47d160f3..bf97af5b3c 100644 --- a/website/content/docs/enterprise/index.mdx +++ b/website/content/docs/enterprise/index.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul Enterprise description: >- - 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 ### Regulatory compliance diff --git a/website/content/docs/enterprise/license/utilization-reporting.mdx b/website/content/docs/enterprise/license/utilization-reporting.mdx index 444b5733ce..051f29901c 100644 --- a/website/content/docs/enterprise/license/utilization-reporting.mdx +++ b/website/content/docs/enterprise/license/utilization-reporting.mdx @@ -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 -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. @@ -84,17 +84,17 @@ If your installation is air-gapped or your network does not allow the correct eg -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 @@ -172,4 +172,4 @@ HashiCorp collects the following utilization data as JSON payloads: } ``` - \ No newline at end of file + diff --git a/website/content/docs/enterprise/network-segments/create-network-segment.mdx b/website/content/docs/enterprise/network-segments/create-network-segment.mdx index b7ef6b66b8..bc300f7708 100644 --- a/website/content/docs/enterprise/network-segments/create-network-segment.mdx +++ b/website/content/docs/enterprise/network-segments/create-network-segment.mdx @@ -7,16 +7,16 @@ description: >- # Create Network Segments -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 ] } ``` - + 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 client1 192.168.4.159:8447 alive client 1.14+ent 2 dc1 default alpha ``` - + 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 `` segment port: @@ -133,18 +133,18 @@ client1 10.20.10.21:8303 alive client 1.14+ent 2 dc1 alpha -Refer to the [`members`](/consul/commands/members) documentation for additional information. +Refer to the [`members`](/consul/commands/members) documentation for additional information. -Call the `/agent/members` API endpoint to view members that the agent sees in the cluster gossip pool. +Call the `/agent/members` API endpoint to view members that the agent sees in the cluster gossip pool. ```shell-session -$ curl http://127.0.0.1:8500/v1/agent/members?segment=alpha +$ curl http://127.0.0.1:8500/v1/agent/members?segment=alpha { "Addr" : "192.168.4.163", @@ -179,7 +179,7 @@ Refer to the [`/agent/members` API endpoint documentation](/consul/api-docs/agen -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. \ No newline at end of file +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. diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx index 57096a4a29..4b7def3609 100644 --- a/website/content/docs/k8s/connect/index.mdx +++ b/website/content/docs/k8s/connect/index.mdx @@ -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 - [Consul Helm chart reference](/consul/docs/k8s/helm) - [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. @@ -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. @@ -243,7 +243,7 @@ spec: echo "Started test job" sleep 10 echo "Killing proxy" - curl --max-time 2 -s -f -XPOST http://127.0.0.1:20600/graceful_shutdown + curl --max-time 2 -s -f -X POST http://127.0.0.1:20600/graceful_shutdown sleep 10 echo "Ended test job" serviceAccountName: test-job @@ -255,18 +255,18 @@ spec: 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. diff --git a/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx b/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx index d7e37333ab..041b73033f 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx @@ -476,7 +476,7 @@ Repeat the following steps for each datacenter in the cluster: acls: manageSystemACLs: true createReplicationToken: true - boostrapToken: + bootstrapToken: secretName: consul/data/secret/bootstrap secretKey: token replicationToken: diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index 011133251a..34bda9400c 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -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 [`ResourceRequirements``](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#resourcerequirements-v1-core) object. @@ -440,7 +440,7 @@ Use these links to navigate to a particular top-level stanza. - `secretName` ((#v-global-acls-partitiontoken-secretname)) (`string: null`) - The name of the Vault secret that holds the partition token. - - `secretKey` ((#v-global-acls-partitiontoken-secretkey)) (`string: null`) - The key within the Vault secret that holds the parition token. + - `secretKey` ((#v-global-acls-partitiontoken-secretkey)) (`string: null`) - The key within the Vault secret that holds the partition token. - `tolerations` ((#v-global-acls-tolerations)) (`string: ""`) - tolerations configures the taints and tolerations for the server-acl-init and server-acl-init-cleanup jobs. This should be a multi-line string matching the @@ -484,7 +484,7 @@ Use these links to navigate to a particular top-level stanza. - `enabled` ((#v-global-federation-enabled)) (`boolean: false`) - If enabled, this datacenter will be federation-capable. Only federation via mesh gateways is supported. Mesh gateways and servers will be configured to allow federation. - Requires `global.tls.enabled`, `connectInject.enabled`, and one of + Requires `global.tls.enabled`, `connectInject.enabled`, and one of `meshGateway.enabled` or `externalServers.enabled` to be true. Requires Consul 1.8+. @@ -508,7 +508,7 @@ Use these links to navigate to a particular top-level stanza. from the one used by the Consul Service Mesh. Please refer to the [Kubernetes Auth Method documentation](/consul/docs/security/acl/auth-methods/kubernetes). - If `externalServers.enabled` is set to true, `global.federation.k8sAuthMethodHost` and + If `externalServers.enabled` is set to true, `global.federation.k8sAuthMethodHost` and `externalServers.k8sAuthMethodHost` should be set to the same value. You can retrieve this value from your `kubeconfig` by running: @@ -1004,7 +1004,7 @@ Use these links to navigate to a particular top-level stanza. ... ``` - - `auditLogs` ((#v-server-auditlogs)) - Added in Consul 1.8, the audit object allow users to enable auditing + - `auditLogs` ((#v-server-auditlogs)) - Added in Consul 1.8, the audit object allow users to enable auditing and configure a sink and filters for their audit logs. Please refer to [audit logs](/consul/docs/enterprise/audit-logging) documentation for further information. @@ -1012,7 +1012,7 @@ Use these links to navigate to a particular top-level stanza. - `enabled` ((#v-server-auditlogs-enabled)) (`boolean: false`) - Controls whether Consul logs out each time a user performs an operation. global.acls.manageSystemACLs must be enabled to use this feature. - - `sinks` ((#v-server-auditlogs-sinks)) (`array`) - A single entry of the sink object provides configuration for the destination to which Consul + - `sinks` ((#v-server-auditlogs-sinks)) (`array`) - A single entry of the sink object provides configuration for the destination to which Consul will log auditing events. Example: @@ -1027,7 +1027,7 @@ Use these links to navigate to a particular top-level stanza. rotate_duration: 24h rotate_max_files: 15 rotate_bytes: 25165824 - + ``` The sink object supports the following keys: @@ -1124,7 +1124,7 @@ Use these links to navigate to a particular top-level stanza. This address must be reachable from the Consul servers. Please refer to the [Kubernetes Auth Method documentation](/consul/docs/security/acl/auth-methods/kubernetes). - If `global.federation.enabled` is set to true, `global.federation.k8sAuthMethodHost` and + If `global.federation.enabled` is set to true, `global.federation.k8sAuthMethodHost` and `externalServers.k8sAuthMethodHost` should be set to the same value. You could retrieve this value from your `kubeconfig` by running: diff --git a/website/content/docs/k8s/service-sync.mdx b/website/content/docs/k8s/service-sync.mdx index 54ebbdd54d..daf03396f2 100644 --- a/website/content/docs/k8s/service-sync.mdx +++ b/website/content/docs/k8s/service-sync.mdx @@ -287,7 +287,7 @@ metadata: ### Service meta A service registered in Consul from Kubernetes sets the `external-source` key to -`kubernetes`. This can be used from the APLI, CLI and UI to filter +`kubernetes`. This can be used from the API, CLI and UI to filter service instances that are set in k8s. The Consul UI displays a Kubernetes icon next to all externally registered services from Kubernetes. @@ -422,7 +422,7 @@ configuration. **If a conflicting service is found**: the service is not synced. This does not match the Kubernetes to Consul behavior, but given the current -implementation we must do this because Kubernetes cannott mix both CNAME and +implementation we must do this because Kubernetes cannot mix both CNAME and Endpoint-based services. ### Kubernetes service labels and annotations diff --git a/website/content/docs/k8s/upgrade/index.mdx b/website/content/docs/k8s/upgrade/index.mdx index 5075ffce48..26ef776e1b 100644 --- a/website/content/docs/k8s/upgrade/index.mdx +++ b/website/content/docs/k8s/upgrade/index.mdx @@ -120,7 +120,7 @@ to update to the new version. Before you upgrade to a new version: -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. diff --git a/website/content/docs/nia/usage/requirements.mdx b/website/content/docs/nia/usage/requirements.mdx index 7d3f84dd89..0fcdf1645a 100644 --- a/website/content/docs/nia/usage/requirements.mdx +++ b/website/content/docs/nia/usage/requirements.mdx @@ -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) -- [Publishing Providers](/terraform/registry/providers/publishing). +- [Setup and Implement Read](/terraform/tutorials/providers/provider-setup) +- [Publishing Providers](/terraform/registry/providers/publishing). ## Network integration using a Terraform module diff --git a/website/content/docs/nia/usage/run-ha.mdx b/website/content/docs/nia/usage/run-ha.mdx index 31d2251564..6152007255 100644 --- a/website/content/docs/nia/usage/run-ha.mdx +++ b/website/content/docs/nia/usage/run-ha.mdx @@ -8,7 +8,7 @@ description: >- # Run Consul-Terraform-Sync with high availability - 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). 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`: @@ -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. ```shell-session $ consul-terraform-sync start -config-file ha-config.hcl - ``` + ``` 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. $ curl --request DELETE localhost:8558/v1/tasks/task_a ``` - 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/` endpoint and include the updated task in your payload. +1. Send a `POST` call to the `/task/` 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 2022-08-23T09:25:09.501-0700 [ERROR] tasksmanager: error applying task: task_name=config-task error= | error tf-apply for 'config-task': exit status 1 - | + | | 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. diff --git a/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx b/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx index 5de0b43f58..caa67d526b 100644 --- a/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx +++ b/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx @@ -11,9 +11,9 @@ description: >- - **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. - - `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`. * `connectInject.consulNamespaces.mirroringK8S` now defaults to `true`. -- `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. ## Changelogs diff --git a/website/content/docs/release-notes/consul/v1_15_x.mdx b/website/content/docs/release-notes/consul/v1_15_x.mdx index 06513080ae..4b4e9fb570 100644 --- a/website/content/docs/release-notes/consul/v1_15_x.mdx +++ b/website/content/docs/release-notes/consul/v1_15_x.mdx @@ -9,54 +9,54 @@ description: >- ## Release Highlights -- **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 ``` diff --git a/website/content/docs/services/configuration/checks-configuration-reference.mdx b/website/content/docs/services/configuration/checks-configuration-reference.mdx index c0d3e24cfd..10934217aa 100644 --- a/website/content/docs/services/configuration/checks-configuration-reference.mdx +++ b/website/content/docs/services/configuration/checks-configuration-reference.mdx @@ -10,46 +10,46 @@ description: -> 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:`. If multiple service checks are registered, the autogenerated default is appended with colon and incrementing number starting with `1`. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | | `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. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | -| `notes` | String value that provides a human-readabiole description of the check. The contents are not visible to Consul. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | +| `notes` | String value that provides a human-readable description of the check. The contents are not visible to Consul. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | | `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). |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • Docker
  • gRPC
  • H2ping
    • | | `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:
  • Script: `30s`
  • HTTP: `10s`
  • TCP: `10s`
  • UDP: `10s`
  • gRPC: `10s`
  • H2ping: `10s`
    • |
  • Script
  • HTTP
  • TCP
  • UDP
  • gRPC
  • H2ping
    • | | `status` | Optional string value that specifies the initial status of the health check. You can specify the following values:
  • `critical` (default)
  • `warning`
  • `passing`
    • |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | | `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) |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | | `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`. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | | `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`. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | -| `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`. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | +| `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`. |
  • Script
  • HTTP
  • TCP
  • UDP
  • OSService
  • TTL
  • Docker
  • gRPC
  • H2ping
  • Alias
    • | | `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. |
  • Script
  • Docker
    • | | `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. |
  • Docker
    • | | `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. |
  • Docker
    • | -| `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). |
  • gRPC
    • | +| `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). |
  • gRPC
    • | | `grpc_use_tls` | Boolean value that enables TLS for gRPC checks when set to `true`. |
  • gRPC
    • | -| `h2ping` | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. |
  • H2ping
    • | +| `h2ping` | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. |
  • H2ping
    • | | `h2ping_use_tls` | Boolean value that enables TLS for H2ping checks when set to `true`. |
  • H2ping
    • | | `http` | String value that specifies an HTTP endpoint to send requests to. |
  • HTTP
    • | | `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:
  • 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.
  • 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.
    • |
  • HTTP
  • H2Ping
  • gRPC
    • | | `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`. |
  • HTTP
  • H2Ping
  • gRPC
    • | | `method` | String value that specifies the request method to send during HTTP checks. Default is `GET`. |
  • HTTP
    • | | `header` | Object that specifies header fields to send in HTTP check requests. Each header specified in `header` object contains a list of string values. |
  • HTTP
    • | -| `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. |
  • HTTP
    • | -| `disable_redirects` | Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`. |
  • HTTP
    • | +| `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. |
  • HTTP
    • | +| `disable_redirects` | Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`. |
  • HTTP
    • | | `os_service` | String value that specifies the name of the name of a service to check during an OSService check. |
  • OSService
    • | | `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. |
  • OSService
    • | | `tcp` | String value that specifies an IP address or host and port number for the check establish a TCP connection with. |
  • TCP
    • | | `udp` | String value that specifies an IP address or host and port number for the check to send UDP datagrams to. |
  • UDP
    • | | `ttl` | String value that specifies how long to wait for an update from an external process during a TTL check. |
  • TTL
    • | -| `alias_service` | String value that specifies a service or node that the service associated with the health check aliases. |
  • Alias
    • | +| `alias_service` | String value that specifies a service or node that the service associated with the health check aliases. |
  • Alias
    • | ## 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). diff --git a/website/content/docs/services/discovery/dns-overview.mdx b/website/content/docs/services/discovery/dns-overview.mdx index 37eda715de..843d97bd18 100644 --- a/website/content/docs/services/discovery/dns-overview.mdx +++ b/website/content/docs/services/discovery/dns-overview.mdx @@ -1,41 +1,41 @@ --- layout: docs -page_title: DNS usage overview +page_title: DNS usage overview description: >- 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. diff --git a/website/content/docs/services/discovery/dns-static-lookups.mdx b/website/content/docs/services/discovery/dns-static-lookups.mdx index a279373460..6c26fc0060 100644 --- a/website/content/docs/services/discovery/dns-static-lookups.mdx +++ b/website/content/docs/services/discovery/dns-static-lookups.mdx @@ -9,10 +9,10 @@ description: -> 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 [.].service[..dc][..peer]. ``` -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: ```text _._[.service][.]. @@ -231,7 +231,7 @@ _redis._tcp.service.phx1.peer.consul. 0 IN SRV 1 1 29142 0a010d56.addr.consul. #### 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: ```text .addr..consul`. @@ -322,7 +322,7 @@ Use the following query format to specify namespace, partition, or datacenter: [.].service[..ns][..ap][..dc] ``` -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 .virtual[.]. ``` -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. \ No newline at end of file +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. diff --git a/website/content/docs/services/services.mdx b/website/content/docs/services/services.mdx index 7300b9d1aa..f2d4eb70c1 100644 --- a/website/content/docs/services/services.mdx +++ b/website/content/docs/services/services.mdx @@ -2,19 +2,19 @@ layout: docs page_title: Services overview description: >- - 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. \ No newline at end of file +Refer to [Define Service Defaults](/consul/docs/services/usage/define-services#define-service-defaults) for additional information. diff --git a/website/content/docs/services/usage/define-services.mdx b/website/content/docs/services/usage/define-services.mdx index 1e0490b9b3..60f19997eb 100644 --- a/website/content/docs/services/usage/define-services.mdx +++ b/website/content/docs/services/usage/define-services.mdx @@ -1,17 +1,17 @@ --- layout: docs -page_title: Define services +page_title: Define services description: >- - 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: @@ -226,7 +226,7 @@ spec: ### Consul Enterprise example -The following example instructs services named `counting` in the `prod` namespace to send up to `512` concurrent requests to a mesh gateway: +The following example instructs services named `counting` in the `prod` namespace to send up to `512` concurrent requests to a mesh gateway: @@ -308,15 +308,15 @@ spec: ### Apply service defaults -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 { -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. \ No newline at end of file +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.