mirror of
https://github.com/status-im/consul.git
synced 2025-01-29 15:05:04 +00:00
166d7a39e8
Remove outdated usage of "Consul Connect" instead of Consul service mesh. The connect subsystem in Consul provides Consul's service mesh capabilities. However, the term "Consul Connect" should not be used as an alternative to the name "Consul service mesh".
189 lines
8.3 KiB
Plaintext
189 lines
8.3 KiB
Plaintext
---
|
|
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 OSS 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.
|