luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Docs/intentions refactor docs day 2022 (#16758) 

* converted intentions conf entry to ref CT format

* set up intentions nav

* add page for intentions usage

* final intentions usage page

* final intentions overview page

* fixed old relative links

* updated diagram for overview

* updated links to intentions content

* fixed typo in updated links

* rename intentions overview page file to index

* rollback link updates to intentions overview

* fixed nav

* Updated custom HTML in API and CLI pages to MD

* applied suggestions from review to index page

* moved conf examples from usage to conf ref

* missed custom HTML section

* applied additional feedback

* Apply suggestions from code review

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

* updated headings in usage page

* renamed files and udpated nav

* updated links to new file names

* added redirects and final tweaks

* typo

---------

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
This commit is contained in:
trujillo-adam 2023-03-24 15:16:06 -07:00 committed by GitHub
parent 5be6469506
commit ed502252c7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 1269 additions and 972 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
website/content/api-docs/connect/intentions.mdx
View File

@ -43,16 +43,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `NO` | `none` | `none` | `intentions:write` <p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention create -replace`](/consul/commands/intention/create#replace).
@ -149,16 +140,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `NO` | `none` | `none` | `intentions:write` <p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention create`](/consul/commands/intention/create).
@ -246,16 +228,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `NO` | `none` | `none` | `intentions:write`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
This endpoint supports the same parameters as the [create an intention](#create-intention-with-id) endpoint.
Additional parameters unique to this endpoint include:
@ -300,16 +273,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `YES` | `all` | `none` | `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get).
@ -372,16 +336,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `YES` | `all` | `none` | `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get).
@ -435,16 +390,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `YES` | `all` | `none` | `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention list`](/consul/commands/intention/list).
@ -522,16 +468,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `NO` | `none` | `none` | `intentions:write`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete).
@ -577,16 +514,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `NO` | `none` | `none` | `intentions:write`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete).
@ -633,16 +561,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `NO` | `none` | `none` | `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention check`](/consul/commands/intention/check).
@ -693,16 +612,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | -------------------- | ----------------------------- |
| `YES` | `all` | `background refresh` | `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `YES` | `all` | `background refresh` | `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
The corresponding CLI command is [`consul intention match`](/consul/commands/intention/match).

2
website/content/commands/connect/envoy.mdx
View File

@ -56,7 +56,7 @@ Usage: `consul connect envoy [options] [-- pass-through options]`
ACL token from `-token` or the environment and so should be handled as a secret.
This token grants the identity of any service it has `service:write` permission
for and so can be used to access any upstream service that that service is
allowed to access by [Connect intentions](/consul/docs/connect/intentions).
allowed to access by [service mesh intentions](/consul/docs/connect/intentions).
- `-envoy-version` - The version of envoy that is being started. Default is
`1.23.1`. This is required so that the correct configuration can be generated.

2
website/content/commands/connect/index.mdx
View File

@ -10,7 +10,7 @@ description: >-
Command: `consul connect`
The `connect` command is used to interact with Consul
[Connect](/consul/docs/connect/intentions) subsystems. It exposes commands for
[service mesh](/consul/docs/connect) subsystems. It exposes commands for
running the built-in mTLS proxy and viewing/updating the Certificate Authority
(CA) configuration. This command is available in Consul 1.2 and later.

11
website/content/commands/intention/check.mdx
View File

@ -31,16 +31,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
| ACL Required |
| ----------------------------- |
| `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
## Usage

11
website/content/commands/intention/create.mdx
View File

@ -25,16 +25,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
| ACL Required |
| ------------------------------ |
| `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `intentions:write`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
## Usage

11
website/content/commands/intention/delete.mdx
View File

@ -19,16 +19,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
| ACL Required |
| ------------------------------ |
| `intentions:write`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `intentions:write`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
-> **Deprecated** - The one argument form of this command is deprecated in
Consul 1.9.0. Intentions no longer need IDs when represented as

11
website/content/commands/intention/get.mdx
View File

@ -24,16 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
| ACL Required |
| ----------------------------- |
| `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
## Usage

7
website/content/commands/intention/index.mdx
View File

@ -14,10 +14,9 @@ The `intention` command is used to interact with Connect
creating, updating, reading, deleting, checking, and managing intentions.
This command is available in Consul 1.2 and later.
Intentions are managed primarily via
[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config
entries after Consul 1.9. Intentions may also be managed via the [HTTP
API](/consul/api-docs/connect/intentions).
Use the
[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry or the [HTTP
API](/consul/api-docs/connect/intentions) to manage intentions.
~> **Deprecated** - This command is deprecated in Consul 1.9.0 in favor of
using the [config entry CLI command](/consul/commands/config/write). To create an

11
website/content/commands/intention/list.mdx
View File

@ -19,16 +19,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
| ACL Required |
| ----------------------------- |
| `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `intentions:read` <p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
## Usage

11
website/content/commands/intention/match.mdx
View File

@ -24,16 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
| ACL Required |
| ----------------------------- |
| `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a{' '}
<code>service</code> rule. See{' '}
<a href="/consul/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
| `intentions:read`<p> Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.</p> |
## Usage

4
website/content/docs/connect/config-entries/service-defaults.mdx
View File

@ -459,7 +459,7 @@ Specifies the default protocol for the service. In service mesh use cases, the `
- [observability](/consul/docs/connect/observability)
- [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter)
- [service router configuration entry](/consul/docs/connect/config-entries/service-router)
- [L7 intentions](/consul/docs/connect/intentions)
- [L7 intentions](/consul/docs/connect/intentions/index#l7-traffic-intentions)
You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration.
@ -831,7 +831,7 @@ Specifies the default protocol for the service. In service service mesh use case
- [observability](/consul/docs/connect/observability)
- [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter)
- [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router)
- [L7 intentions](/consul/docs/connect/intentions)
- [L7 intentions](/consul/docs/connect/intentions/index#l7-traffic-intentions)
You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration.

1363
website/content/docs/connect/config-entries/service-intentions.mdx
View File

File diff suppressed because it is too large Load Diff

26
website/content/docs/connect/index.mdx
View File

@ -5,7 +5,7 @@ description: >-
Consul’s service mesh makes application and microservice networking secure and observable with identity-based authentication, mutual TLS (mTLS) encryption, and explicit service-to-service authorization enforced by sidecar proxies. Learn how Consul’s service mesh works and get started on VMs or Kubernetes.
---
# Consul Service Mesh
# Consul service mesh
Consul Service Mesh provides service-to-service connection authorization and
encryption using mutual Transport Layer Security (TLS). Consul Connect is used interchangeably
@ -25,30 +25,30 @@ Review the video below to learn more about Consul Connect from HashiCorp's co-fo
height="315"
></iframe>
## Application Security
## Application security
Connect enables secure deployment best-practices with automatic
Consul service mesh enables secure deployment best-practices with automatic
service-to-service encryption, and identity-based authorization.
Connect uses the registered service identity (rather than IP addresses) to
Consul uses the registered service identity, rather than IP addresses, to
enforce access control with [intentions](/consul/docs/connect/intentions). This
makes it easier to reason about access control and enables services to be
rescheduled by orchestrators including Kubernetes and Nomad. Intention
enforcement is network agnostic, so Connect works with physical networks, cloud
makes it easier to control access and enables services to be
rescheduled by orchestrators, including Kubernetes and Nomad. Intention
enforcement is network agnostic, so Consul service mesh works with physical networks, cloud
networks, software-defined networks, cross-cloud, and more.
## Observability
One of the key benefits of Consul Connect is the uniform and consistent view it can
One of the key benefits of Consul service mesh is the uniform and consistent view it can
provide of all the services on your network, irrespective of their different
programming languages and frameworks. When you configure Consul Connect to use
sidecar proxies, those proxies "see" all service-to-service traffic and can
collect data about it. Consul Connect can configure Envoy proxies to collect
programming languages and frameworks. When you configure Consul service mesh to use
sidecar proxies, those proxies see all service-to-service traffic and can
collect data about it. Consul service mesh can configure Envoy proxies to collect
layer 7 metrics and export them to tools like Prometheus. Correctly instrumented
applications can also send open tracing data through Envoy.
## Getting Started With Consul Service Mesh
## Getting started with Consul service mesh
There are several ways to try Connect in different environments.
Complete the following tutorials try Consul service mesh in different environments:
- The [Getting Started with Consul Service Mesh collection](/consul/tutorials/kubernetes-deploy/service-mesh?utm_source=docs)
walks you through installing Consul as service mesh for Kubernetes using the Helm

341
website/content/docs/connect/intentions.mdx
View File

@ -1,341 +0,0 @@
---
layout: docs
page_title: Service Mesh Intentions
description: >-
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.
---
# Service Mesh Intentions
-> **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).
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).
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):
- **Identity-based** - All intentions may enforce access based on identities
encoded within [TLS
certificates](/consul/docs/connect/connect-internals#mutual-transport-layer-security-mtls).
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**.
- **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**.
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.
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.
## 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>
### Enforcement
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.
For services that define their protocol as HTTP-based, intentions mediate the
ability to **issue new requests**.
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.
## 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 a
[field](/consul/docs/connect/config-entries/service-intentions#precedence) on the
`service-intentions` configuration entry after it is modified. Precedence cannot be
manually overridden today.
The numbers in the table above are not stable. Their ordering will remain
fixed but the actual number values may change in the future.
-> <EnterpriseAlert inline /> - Namespaces are an Enterprise feature. In Consul
OSS the only allowable value for either namespace field is `"default"`. Other
rows in this table 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 Connect 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`.
<CodeTabs>
```hcl
service "web" {
policy = "write"
}
```
```json
{
"service": [
{
"web": [
{
"policy": "write"
}
]
}
]
}
```
</CodeTabs>
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 Connect-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.
Supported [proxies] (such as [Envoy]) also cache this data within their own
configuration so that inbound connections or requests require no Consul agent
involvement during authorization. All actions in the data path of connections
happen within the proxy.
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. Proxies similarly use blocking queries to update
their local configurations quickly.
Because all the intention data is cached locally, the agents or proxies can
fail static. Even if the agents are severed completely from the Consul servers,
or the proxies are severed completely from their local Consul agent, inbound
connection authorization continues to work indefinitely. Changes to intentions
will not be picked up until the partition heals, but will then automatically
take effect when connectivity is restored.
[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol
[proxies]: /consul/docs/connect/proxies
[envoy]: /consul/docs/connect/proxies/envoy

178
website/content/docs/connect/intentions/create-manage-intentions.mdx Normal file
View File

@ -0,0 +1,178 @@
---
layout: docs
page_title: Create and manage service intentions
description: >-
Learn how to create and manage Consul service mesh intentions using service-intentions config entries, the `consul intentions` command, and `/connect/intentions` API endpoint.
---
# Create and manage intentions
This topic describes how to create and manage service intentions, which are configurations for controlling access between services in the service mesh.
## Overview
You can create single intentions or create them in batches using the Consul API, CLI, or UI. You can also define a service intention configuration entry that sets default intentions for all services in the mesh. Refer to [Service intentions overview](/consul/docs/connnect/intentions/intentions) for additional background information about intentions.
## Requirements
- At least two services must be registered in the datacenter.
- TLS must be enabled to enforce L4 intentions. Refer to [Encryption](/consul/docs/security/encryption) for additional information.
### ACL requirements
Consul grants permissions for creating and managing intentions based on the destination, not the source. When ACLs are enabled, services and operators must present a token linked to a policy that grants read and write permissions to the destination service.
Consul implicitly grants `intentions:read` permissions to destination services when they are configured with `service:read` or `service:write` permissions. This is so that the services can allow or deny inbound connections when they attempt to join the service mesh. Refer to [Service rules](/consul/docs/security/acl/acl-rules#service-rules) for additional information about configuring ALCs for intentions.
The default ACL policy configuration determines the default behavior for intentions. If the policy is set to `deny`, then all connections or requests are denied and you must enable them explicitly. Refer to [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) for details.
## Create an intention
You can create and manage intentions one at a time using the Consul API, CLI, or UI You can specify one destination or multiple destinations in a single intention.
### API
Send a `PUT` request to the `/connect/intentions/exact` HTTP API endpoint and specify the following query parameters:
- `source`: Service sending the request
- `destination`: Service responding to the request
- `ns`: Namespace of the destination service <EnterpriseAlert inline/>
For L4 intentions, you must also specify the intention action in the request payload.
The following example creates an intention that allows `web` to send request to `db`:
```shell-session
$ curl --request PUT \
--data ' { "Action": "allow" } ' \
http://localhost:8500/v1/connect/intentions/exact\?source\=web\&destination\=db
```
Refer to the `/connect/intentions/exact` [HTTP API endpoint documentation](/consul/api-docs/connect/intentions) for additional information request payload parameters.
For L7 intentions, specify the `Permissions` in the request payload to configure attributes for dynamically enforcing intentions. In the following example payload, Consul allows HTTP GET requests if the request body is empty:
<CodeBlockConfig heading="payload.json">
```json
{
"Permissions": [
{
"Action": "allow",
"HTTP": {
"Methods": ["GET"],
"Header": [
{
"Name": "Content-Length",
"Exact": "0"
}
]
}
}
]
}
```
</CodeBlockConfig>
The `Permissions` object specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. Refer to the [`Sources[].Permissions[]` parameter](/consul/connect/config-entries/service-intentions#source-permissions) in the service intentions configuration entry reference for configuration details.
To apply the intention, call the endpoint and pass the configuration file containing the attributes to the endpoint:
```shell-session
$ curl --request PUT \
--data @payload.json \
http://localhost:8500/v1/connect/intentions/exact\?source\=svc1\&destination\=sv2
```
### CLI
Use the `consul intention create` command according to the following syntax to create a new intention:
```shell-session
$ consul intention create -<action> <source> <destination>
```
The following example creates an intention that allows `web` service instances to connect to `db` service instances:
```shell-session
$ consul intention create -allow web db
```
You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-match-order) for additional information.
### Consul UI
1. Log into the Consul UI and choose **Services** from the sidebar menu.
1. Click on a service and then click the **Intentions* tab.
1. Click **Create** and choose the source service from the drop-down menu.
1. You can add an optional description.
1. Choose one of the following options:
1. **Allow**: Allows the source service to send requests to the destination.
1. **Deny**: Prevents the source service from sending requests to the destination.
1. **Application Aware**: Enables you to specify L7 criteria for dynamically enforcing intentions. Refer to [Configure application aware settings](#configure-application-aware-settings) for additional information.
1. Click **Save**.
Repeat the procedure as necessary to create additional intentions.
#### Configure application aware settings
You can use the Consul UI to configure L7 permissions.
1. Click **Add permission** to open the permission editor.
1. Enable the **Allow** or **Deny** option.
1. You can specify a path, request method, and request headers to match. All criteria must be satisfied for Consul to enforce the permission. Refer to the [`Sources[].Permissions[]` parameter](/consul/docs/connect/config-entries/service-intentions#sources-permissions) in the service intentions configuration entry reference for information about the available configuration fields.
1. Click **Save**.
Repeat the procedure as necessary to create additional permissions.
## Create multiple intentions
You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic.
### Define a service intention configuration entry
Configure the following fields:
<Tabs>
<Tab heading="HCL" group="hcl">
- [`Kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `service-intentions`.
- [`Name`](/consul/docs/connect/config-entries/service-intentions#kind): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions.
- [`Sources`](/consul/docs/connect/config-entries/service-intentions#sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence.
- [`Sources.Action`](/consul/docs/connect/config-entries/service-intentions#sources-action) or [`Sources.Permissions`](/consul/docs/connect/config-entries/service-intentions#sources-permissions): For L4 intentions, set the `Action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `Permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `Actions` and `Permissions` settings are mutually exclusive.
</Tab>
<Tab heading="YAML" group="yaml">
- [`apiVersion`](/consul/docs/connect/config-entries/service-intentions#apiversion): Specifies the Consul API version. Must be set to `consul.hashicorp.com/v1alpha1`.
- [`kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `ServiceIntentions`.
- [`spec.destination.name`](/consul/docs/connect/config-entries/service-intentions#spec-destination-name): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions.
- [`spec.sources`](/consul/docs/connect/config-entries/service-intentions#spec-sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence.
- [`spec.sources.action`](/consul/docs/connect/config-entries/service-intentions#spec-sources-action) or [`spec.sources.permissions`](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions): For L4 intentions, set the `action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `actions` and `permissions` settings are mutually exclusive.
</Tab>
</Tabs>
Refer to the [service intentions configuration entry](/consul/docs/connect/config-entries/service-intentions) reference documentation for details about all configuration options.
Refer to the [example service intentions configurations](/consul/docs/connect/config-entries/service-intentions#examples) for additional guidance.
#### Interaction with other configuration entries
L7 intentions defined in a configuration entry are restricted to destination services
configured with an HTTP-based protocol as defined in a corresponding
[service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults)
or globally in a [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults).
### Apply the service intentions configuration entry
You can apply the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `ServiceIntentions` custom resource definitions (CRD) to implement and manage Consul configuration entries.
Refer to the following topics for details about applying configuration entries:
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)

91
website/content/docs/connect/intentions/index.mdx Normal file
View File

@ -0,0 +1,91 @@
---
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.
![Diagram showing how service intentions control access between services](/img/consul-connect/consul-service-mesh-intentions-overview.svg)
## 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.
### 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 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.

3
website/content/docs/connect/intentions-legacy.mdx → website/content/docs/connect/intentions/legacy.mdx
View File

@ -8,8 +8,7 @@ description: >-
# 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 please use the updated
documentation [here](/consul/docs/connect/intentions).
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 services via Connect and are used
to control which services may establish connections. Intentions can be

8
website/content/docs/k8s/connect/index.mdx
View File

@ -175,18 +175,18 @@ upstream. This is analogous to the standard Kubernetes service environment varia
point instead to the correct local proxy port to establish connections via
Connect.
We can verify access to the static text server using `kubectl exec`.
You can verify access to the static text server using `kubectl exec`.
Because transparent proxy is enabled by default,
we use Kubernetes DNS to connect to our desired upstream.
use Kubernetes DNS to connect to your desired upstream.
```shell-session
$ kubectl exec deploy/static-client -- curl --silent http://static-server/
"hello world"
```
We can control access to the server using [intentions](/consul/docs/connect/intentions).
You can control access to the server using [intentions](/consul/docs/connect/intentions).
If you use the Consul UI or [CLI](/consul/commands/intention/create) to
create a deny [intention](/consul/docs/connect/intentions) between
deny communication between
"static-client" and "static-server", connections are immediately rejected
without updating either of the running pods. You can then remove this
intention to allow connections again.

2
website/content/docs/lambda/invoke-from-lambda.mdx
View File

@ -264,7 +264,7 @@ Define the following environment variables in your Lambda functions to configure
## Invoke the Lambda function
If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service Mesh Intentions](/consul/docs/connect/intentions) for additional information.
If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service mesh intentions](/consul/docs/connect/intentions) for additional information.
There are several ways to invoke Lambda functions. In the following example, the `aws lambda invoke` CLI command invokes the function:

2
website/content/docs/security/acl/acl-rules.mdx
View File

@ -869,7 +869,7 @@ service "app" {
</CodeTabs>
Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions)
Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements)
for more information about managing intentions access with service rules.
## Session Rules

25
website/data/docs-nav-data.json
View File

@ -539,12 +539,25 @@
]
},
{
"title": "Service-to-service permissions - Intentions",
"path": "connect/intentions"
},
{
"title": "Service-to-service permissions - Intentions (Legacy Mode)",
"path": "connect/intentions-legacy"
"title": "Service intentions",
"routes": [
{
"title": "Overview",
"path": "connect/intentions"
},
{
"title": "Create and manage service intentions",
"path": "connect/intentions/create-manage-intentions"
},
{
"title": "Service intentions legacy mode",
"path": "connect/intentions/legacy"
},
{
"title": "Configuration",
"href": "/consul/docs/connect/config-entries/service-intentions"
}
]
},
{
"title": "Transparent Proxy",

1
website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

10
website/redirects.js
View File

@ -22,4 +22,14 @@ module.exports = [
destination: '/consul/docs/k8s/connect/cluster-peering/tech-specs',
permanent: true,
},
{
source: '/consul/docs/connect/intentions#intention-management-permissions',
destination: `/consul/docs/connect/intentions/create-manage-intentions#acl-requirements`,
permanent: true,
},
{
source: '/consul/docs/connect/intentions#intention-basics',
destination: `/consul/docs/connect/intentions`,
permanent: true,
},
]