Intentions define communication permissions in the service mesh between microservices. Learn about configuration basics, wildcard intentions, precedence and match order, and protecting intention management with ACLs.
Intentions are access controls that allow or deny incoming requests to services in the mesh.
---
# Service Mesh Intentions
# Service intentions overview
-> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and
later. The documentation for the legacy intentions system is
[here](/consul/docs/connect/intentions-legacy).
This topic provides overview information about Consul intentions, which are mechanisms that control traffic communication between services in the Consul service mesh.
Intentions define access control for services via Connect and are used to
control which services may establish connections or make requests. Intentions
can be managed via the API, CLI, or UI.
Intentions are enforced on inbound connections or requests by the
[proxy](/consul/docs/connect/proxies) or within a [natively integrated
application](/consul/docs/connect/native).
## Intention types
Depending upon the [protocol] in use by the destination service, you can define
intentions to control Connect traffic authorization either at networking layer
4 (e.g. TCP) and application layer 7 (e.g. HTTP):
Intentions control traffic communication between services at the network layer, also called _L7_ traffic, or the application layer, also called _L4 traffic_. The protocol that the destination service uses to send and receive traffic determines the type of authorization the intention can enforce.
- **Identity-based** - All intentions may enforce access based on identities
This allows for coarse all-or-nothing access control between pairs of
services. These work with for services with any [protocol] as they only
require awareness of the TLS handshake that wraps the opaque TCP connection.
These can also be thought of as **L4 intentions**.
### L4 traffic intentions
- **Application-aware** - Some intentions may additionally enforce access based
on [L7 request
attributes](/consul/docs/connect/config-entries/service-intentions#permissions) in
addition to connection identity. These may only be defined for services with
a [protocol] that is HTTP-based. These can also be thought of as **L7
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.
At any given point in time, between any pair of services **only one intention
controls authorization**. This may be either an L4 intention or an L7
intention, but at any given point in time only one of those applies.
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.
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.
### L7 traffic intentions
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 mesh Connect connections will be allowed by default.
If is set to `deny`, then all connections or requests will be denied by default.
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.
## Intention Basics
You can define a [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry to create and manage intentions, as well as manage intentions through the Consul UI. You can also perform some intention-related tasks using the API and CLI commands. Refer to the [API](/consul/api-docs/connect/intentions) and [CLI](/consul/commands/intention) documentation for details.
The following example shows a `service-intentions` configuration entry that specifies two intentions. Refer to the [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) documentation for the full data model and additional examples.
<CodeTabs>
```hcl
Kind = "service-intentions"
Name = "db"
Sources = [
{
Name = "web"
Action = "deny"
},
{
Name = "api"
Action = "allow"
}
]
```
```json
{
"Kind": "service-intentions",
"Name": "db",
"Sources": [
{
"Action": "deny",
"Name": "web"
},
{
"Action": "allow",
"Name": "api"
}
]
}
```
</CodeTabs>
This configuration entry defines two intentions with a common destination of `db`. The
first intention above is a deny intention with a source of `web`. This says
that connections from web to db are not allowed and the connection will be
rejected. The second intention is an allow intention with a source of `api`.
This says that connections from api to db are allowed and connections will be
accepted.
### Wildcard Intentions
You can use the `*` wildcard to match service names when defining an intention source or destination. The wildcard matches _any_ value, which enables you to set a wide initial scope when configuring intentions.
The wildcard is supported in Consul Enterprise `namespace` fields (see [Namespaces](/consul/docs/enterprise/namespaces) for additional information), but it _is not supported_ in `partition` fields (see [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information).
In the following example, the `web` service cannot connect to _any_ service:
<CodeTabs>
```hcl
Kind = "service-intentions"
Name = "*"
Sources = [
{
Name = "web"
Action = "deny"
}
]
```
```json
{
"Kind": "service-intentions",
"Name": "*",
"Sources": [
{
"Action": "deny",
"Name": "web"
}
]
}
```
</CodeTabs>
The `db` service is configured to deny all connection in the following example:
<CodeTabs>
```hcl
Kind = "service-intentions"
Name = "db"
Sources = [
{
Name = "*"
Action = "deny"
}
]
```
```json
{
"Kind": "service-intentions",
"Name": "db",
"Sources": [
{
"Action": "deny",
"Name": "*"
}
]
}
```
</CodeTabs>
<EnterpriseAlert inline /> This example grants Prometheus access to any service in
any namespace.
<CodeTabs>
```hcl
Kind = "service-intentions"
Name = "*"
Namespace = "*"
Sources = [
{
Name = "prometheus"
Namespace = "monitoring"
Action = "allow"
}
]
```
```json
{
"Kind": "service-intentions",
"Name": "*",
"Namespace": "*",
"Sources": [
{
"Action": "allow",
"Name": "prometheus",
"Namespace": "monitoring"
}
]
}
```
</CodeTabs>
## Workflow
### Enforcement
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/intentions-usage) for details.
For services that define their [protocol] as TCP, intentions mediate the
ability to **establish new connections**. When an intention is modified,
existing connections will not be affected. This means that changing a
connection from "allow" to "deny" today _will not_ kill the connection.
### Precedence and match order
For services that define their protocol as HTTP-based, intentions mediate the
ability to **issue new requests**.
Consul processes criteria configured in the service intention configuration entry to match on incoming requests and either allow or deny the request to the destination service. 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.
When an intention is modified, requests received after the modification will
use the latest intention rules to enforce access. This means that though
changing a connection from "allow" to "deny" today will not kill the
connection, it will correctly block new requests from being processed.
Consul orders the matches implicitly based the following factors:
## Precedence and Match Order
- 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.
Intentions are matched in an implicit order based on specificity, preferring
deny over allow. Specificity is determined by whether a value is an exact
specified value or is the wildcard value `*`.
The full precedence table is shown below and is evaluated
top to bottom, with larger numbers being evaluated first.
The following table describes the order of precedence:
| Source Namespace | Source Name | Destination Namespace | Destination Name | Precedence |
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`](/docs/connect/config-entries/service-intentions#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](/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 mesh Connect connections will be allowed by default.
If is set to `deny`, then all connections or requests will be denied by default.
### 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.
### 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.
trujillo-adam
2 years ago
