mirror of https://github.com/hashicorp/consul
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
188 lines
8.3 KiB
188 lines
8.3 KiB
--- |
|
layout: docs |
|
page_title: Intentions (Legacy Mode) |
|
description: >- |
|
Intentions define service communication permissions in the service mesh. As of version 1.9, Consul uses a new system for creating and managing intentions. Learn how intentions worked in earlier versions of Consul with this legacy documentation. |
|
--- |
|
|
|
# Intentions in Legacy Mode |
|
|
|
~> **1.8.x and earlier:** This document only applies in Consul versions 1.8.x |
|
and before. If you are using version 1.9.0 or later, refer to the [current intentions documentation](/consul/docs/connect/intentions). |
|
|
|
Intentions define access control for service-to-service connections in the service mesh. Intentions can be |
|
managed via the API, CLI, or UI. |
|
|
|
Intentions are enforced by the [proxy](/consul/docs/connect/proxies) |
|
or [natively integrated application](/consul/docs/connect/native) on |
|
inbound connections. After verifying the TLS client certificate, the |
|
[authorize API endpoint](/consul/api-docs/agent/connect#authorize) is called which verifies the connection |
|
is allowed by testing the intentions. If authorize returns false the |
|
connection must be terminated. |
|
|
|
The default intention behavior is defined by the default [ACL |
|
policy](/consul/docs/agent/config/config-files#acl_default_policy). If the default ACL policy is |
|
"allow all", then all service-to-service connections in the mesh are allowed by default. If the |
|
default ACL policy is "deny all", then all service-to-service connections are denied by |
|
default. |
|
|
|
## Intention Basics |
|
|
|
Intentions can be managed via the [API](/consul/api-docs/connect/intentions), |
|
[CLI](/consul/commands/intention), or UI. Please see the respective documentation for |
|
each for full details on options, flags, etc. Below is an example of a basic |
|
intention to show the basic attributes of an intention. The full data model of |
|
an intention can be found in the [API |
|
documentation](/consul/api-docs/connect/intentions). |
|
|
|
```shell-session |
|
$ consul intention create -deny web db |
|
Created: web => db (deny) |
|
``` |
|
|
|
The intention above is a deny intention with a source of "web" and |
|
destination of "db". This says that connections from web to db are not |
|
allowed and the connection will be rejected. |
|
|
|
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. Addressing this shortcoming is on |
|
the near term roadmap for Consul. |
|
|
|
### Wildcard Intentions |
|
|
|
An intention source or destination may also be the special wildcard |
|
value `*`. This matches _any_ value and is used as a catch-all. Example: |
|
|
|
```shell-session |
|
$ consul intention create -deny web '*' |
|
Created: web => * (deny) |
|
``` |
|
|
|
This example says that the "web" service cannot connect to _any_ service. |
|
|
|
### Metadata |
|
|
|
Arbitrary string key/value data may be associated with intentions. This |
|
is unused by Consul but can be used by external systems or for visibility |
|
in the UI. |
|
|
|
```shell-session |
|
$ consul intention create \ |
|
-deny \ |
|
-meta description='Hello there' \ |
|
web db |
|
... |
|
|
|
$ consul intention get web db |
|
Source: web |
|
Destination: db |
|
Action: deny |
|
ID: 31449e02-c787-f7f4-aa92-72b5d9b0d9ec |
|
Meta[description]: Hello there |
|
Created At: Friday, 25-May-18 02:07:51 CEST |
|
``` |
|
|
|
## Precedence and Match Order |
|
|
|
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. |
|
|
|
| Source Namespace | Source Name | Destination Namespace | Destination Name | Precedence | |
|
| ---------------- | ----------- | --------------------- | ---------------- | ---------- | |
|
| Exact | Exact | Exact | Exact | 9 | |
|
| Exact | `*` | Exact | Exact | 8 | |
|
| `*` | `*` | Exact | Exact | 7 | |
|
| Exact | Exact | Exact | `*` | 6 | |
|
| Exact | `*` | Exact | `*` | 5 | |
|
| `*` | `*` | Exact | `*` | 4 | |
|
| Exact | Exact | `*` | `*` | 3 | |
|
| Exact | `*` | `*` | `*` | 2 | |
|
| `*` | `*` | `*` | `*` | 1 | |
|
|
|
The precedence value can be read from the [API](/consul/api-docs/connect/intentions) |
|
after an intention is created. |
|
Precedence cannot be manually overridden today. This is a feature that will |
|
be added in a later version of Consul. |
|
|
|
In the case the two precedence values match, Consul will evaluate |
|
intentions based on lexicographical ordering of the destination then |
|
source name. In practice, this is a moot point since authorizing a connection |
|
has an exact source and destination value so its impossible for two |
|
valid non-wildcard intentions to match. |
|
|
|
The numbers in the table above are not stable. Their ordering will remain |
|
fixed but the actual number values may change in the future. |
|
|
|
-> **Consul Enterprise** - Namespaces are an Enterprise feature. In Consul CE, any of the rows in |
|
the table with a `*` for either the source namespace or destination namespace are not applicable. |
|
|
|
## Intention Management Permissions |
|
|
|
Intention management can be protected by [ACLs](/consul/docs/security/acl). |
|
Permissions for intentions are _destination-oriented_, meaning the ACLs |
|
for managing intentions are looked up based on the destination value |
|
of the intention, not the source. |
|
|
|
Intention permissions are by default implicitly granted at `read` level |
|
when granting `service:read` or `service:write`. This is because a |
|
service registered that wants to use service mesh needs `intentions:read` |
|
for its own service name in order to know whether or not to authorize |
|
connections. The following ACL policy will implicitly grant `intentions:read` |
|
(note _read_) for service `web`. |
|
|
|
```hcl |
|
service "web" { |
|
policy = "write" |
|
} |
|
``` |
|
|
|
It is possible to explicitly specify intention permissions. For example, |
|
the following policy will allow a service to be discovered without granting |
|
access to read intentions for it. |
|
|
|
```hcl |
|
service "web" { |
|
policy = "read" |
|
intentions = "deny" |
|
} |
|
``` |
|
|
|
Note that `intentions:read` is required for a token that a mesh-enabled |
|
service uses to register itself or its proxy. If the token used does not |
|
have `intentions:read` then the agent will be unable to resolve intentions |
|
for the service and so will not be able to authorize any incoming connections. |
|
|
|
~> **Security Note:** Explicitly allowing `intentions:write` on the token you |
|
provide to a service instance at registration time opens up a significant |
|
additional vulnerability. Although you may trust the service _team_ to define |
|
which inbound connections they accept, using a combined token for registration |
|
allows a compromised instance to to redefine the intentions which allows many |
|
additional attack vectors and may be hard to detect. We strongly recommend only |
|
delegating `intentions:write` using tokens that are used by operations teams or |
|
orchestrators rather than spread via application config, or only manage |
|
intentions with management tokens. |
|
|
|
## Performance and Intention Updates |
|
|
|
The intentions for services registered with a Consul agent are cached |
|
locally on that agent. They are then updated via a background blocking query |
|
against the Consul servers. |
|
|
|
Service mesh connection attempts require only local agent |
|
communication for authorization and generally only impose microseconds |
|
of latency to the connection. All actions in the data path of connections |
|
require only local data to ensure minimal performance overhead. |
|
|
|
Updates to intentions are propagated nearly instantly to agents since agents |
|
maintain a continuous blocking query in the background for intention updates |
|
for registered services. |
|
|
|
Because all the intention data is cached locally, the agents can fail static. |
|
Even if the agents are severed completely from the Consul servers, inbound |
|
connection authorization continues to work for a configured amount of time. |
|
Changes to intentions will not be picked up until the partition heals, but |
|
will then automatically take effect when connectivity is restored.
|
|
|