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) 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 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 for details.

Enforcement

The proxy or natively-integrated application 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 to avoid unintended match rule circumvention. More details are available in the Mesh configuration entry reference.

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.

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 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 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 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:

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 for additional information.

Namespaces are an Enterprise feature. In Consul OSS, the only allowable value for either namespace field is "default". Other rows in the table are not applicable.

The intention match API 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 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.