mirror of https://github.com/hashicorp/consul
96 lines
8.1 KiB
Markdown
96 lines
8.1 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Service mesh intentions overview
|
|
description: >-
|
|
Intentions are access controls that allow or deny incoming requests to services in the mesh.
|
|
---
|
|
|
|
# Service intentions overview
|
|
|
|
This topic provides overview information about Consul intentions, which are mechanisms that control traffic communication between services in the Consul service mesh.
|
|
|
|
|
|
|
|
## Intention types
|
|
|
|
Intentions control traffic communication between services at the network layer, also called _L4_ traffic, or the application layer, also called _L7 traffic_. The protocol that the destination service uses to send and receive traffic determines the type of authorization the intention can enforce.
|
|
|
|
### L4 traffic intentions
|
|
|
|
If the destination service uses TCP or any non-HTTP-based protocol, then intentions can control traffic based on identities encoded in mTLS certificates. Refer to [Mutual transport layer security (mTLS)](/consul/docs/connect/connect-internals#mutual-transport-layer-security-mtls) for additional information.
|
|
|
|
This implementation allows broad all-or-nothing access control between pairs of services. The only requirement is that the service is aware of the TLS handshake that wraps the opaque TCP connection.
|
|
|
|
### L7 traffic intentions
|
|
|
|
If the destination service uses an HTTP-based protocol, then intentions can enforce access based on application-aware request attributes, in addition to identity-based enforcement, to control traffic between services. Refer to [Service intentions configuration reference](/consul/docs/connect/config-entries/service-intentions#permissions) for additional information.
|
|
|
|
## Workflow
|
|
|
|
You can manually create intentions from the Consul UI, API, or CLI. You can also enable Consul to dynamically create them by defining traffic routes in service intention configuration entries. Refer to [Create and manage intentions](/consul/docs/connect/intentions/create-manage-intentions) for details.
|
|
|
|
### Enforcement
|
|
|
|
The [proxy](/consul/docs/connect/proxies) or [natively-integrated
|
|
application](/consul/docs/connect/native) enforces intentions on inbound connections or requests. Only one intention can control authorization between a pair of services at any single point in time.
|
|
|
|
L4 intentions mediate the ability to establish new connections. Modifying an intention does not have an effect on existing connections. As a result, changing a connection from `allow` to `deny` does not sever the connection.
|
|
|
|
L7 intentions mediate the ability to issue new requests. When an intention is modified, requests received after the modification use the latest intention rules to enforce access. Changing a connection from `allow` to `deny` does not sever the connection, but doing so blocks new requests from being processed.
|
|
|
|
When using L7 intentions, we recommend that you review and update the [Mesh request normalization configuration](/consul/docs/connect/security#request-normalization-and-configured) to avoid unintended match rule circumvention. More details are available in the [Mesh configuration entry reference](/consul/docs/connect/config-entries/mesh#request-normalization).
|
|
|
|
When you use L7 intentions with header matching and it is possible for a header to contain multiple values, we recommend using `contains` or `regex` instead of `exact`, `prefix`, or `suffix`. For more information, refer to the [service intentions configuration entry reference](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions-http-header).
|
|
|
|
### Caching
|
|
|
|
The intentions for services registered with a Consul agent are cached locally on the agent. Supported proxies also cache intention data in their own configurations so that they can authorize inbound connections or requests without relying on the Consul agent. All actions in the data path of connections take place within the proxy.
|
|
|
|
### Updates
|
|
|
|
Consul propagates updates to intentions almost instantly as a result of the continuous blocking query the agent uses. A _blocking query_ is a Consul API feature that uses long polling to wait for potential changes. Refer to [Blocking Queries](/consul/api-docs/features/blocking) for additional information. Proxies also use blocking queries to quickly update their local configurations.
|
|
|
|
Because all intention data is cached locally, authorizations for inbound connection persist, even if the agents are completely severed from the Consul servers or if the proxies are completely severed from their local Consul agent. If the connection is severed, Consul automatically applies changes to intentions when connectivity is restored.
|
|
|
|
### Intention maintenance
|
|
|
|
Services should periodically call the [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) to retrieve all relevant intentions for the target destination. After verifying the TLS client certificate, the cached intentions for each incoming connection or request determine if it should be accepted or rejected.
|
|
|
|
## Precedence and match order
|
|
|
|
Consul processes criteria defined in the service intention configuration entry to match incoming requests. When Consul finds a match, it applies the corresponding action specified in the configuration entry. The match criteria may include specific HTTP headers, request methods, or other attributes. Additionally, you can use regular expressions to programmatically match attributes. Refer to [Service intention configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for details.
|
|
|
|
Consul orders the matches based the following factors:
|
|
|
|
- Specificity: Incoming requests that match attributes directly have the highest precedence. For example, intentions that are configured to deny traffic from services that send `POST` requests take precedence over intentions that allow traffic from methods configured with the wildcard value `*`.
|
|
- Authorization: Consul enforces `deny` over `allow` if match criteria are weighted equally.
|
|
|
|
The following table shows match precedence in descending order:
|
|
|
|
| Precedence | Source Namespace | Source Name | Destination Namespace | Destination Name |
|
|
| -----------| ---------------- | ------------| --------------------- | ---------------- |
|
|
| 9 | Exact | Exact | Exact | Exact |
|
|
| 8 | Exact | `*` | Exact | Exact |
|
|
| 7 | `*` | `*` | Exact | Exact |
|
|
| 6 | Exact | Exact | Exact | `*` |
|
|
| 5 | Exact | `*` | Exact | `*` |
|
|
| 4 | `*` | `*` | Exact | `*` |
|
|
| 3 | Exact | Exact | `*` | `*` |
|
|
| 2 | Exact | `*` | `*` | `*` |
|
|
| 1 | `*` | `*` | `*` | `*` |
|
|
|
|
Consul prints the precedence value to the service intentions configuration entry after it processes the matching criteria. The value is read-only. Refer to
|
|
[`Precedence`](/consul/docs/connect/config-entries/service-intentions#precedence) for additional information.
|
|
|
|
Namespaces are an Enterprise feature. In Consul CE, the only allowable value for either namespace field is `"default"`. Other rows in the table are not applicable.
|
|
|
|
The [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions)
|
|
should be periodically called to retrieve all relevant intentions for the
|
|
target destination. After verifying the TLS client certificate, the cached
|
|
intentions should be consulted for each incoming connection/request to
|
|
determine if it should be accepted or rejected.
|
|
|
|
The default intention behavior is defined by the [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration.
|
|
If the configuration is set `allow`, then all service-to-service connections in the mesh will be allowed by default.
|
|
If is set to `deny`, then all connections or requests will be denied by default.
|