2018-05-29 21:07:40 +00:00
|
|
|
---
|
|
|
|
layout: api
|
|
|
|
page_title: Intentions - Connect - HTTP API
|
2020-04-13 18:40:26 +00:00
|
|
|
sidebar_title: Intentions
|
2018-05-29 21:07:40 +00:00
|
|
|
description: |-
|
|
|
|
The /connect/intentions endpoint provide tools for managing intentions via
|
|
|
|
Consul's HTTP API.
|
|
|
|
---
|
|
|
|
|
|
|
|
# Intentions - Connect HTTP API
|
|
|
|
|
|
|
|
The `/connect/intentions` endpoint provide tools for managing
|
2020-04-09 23:46:54 +00:00
|
|
|
[intentions](/docs/connect/intentions).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
-> **1.9.0 and later:** Reading and writing intentions has been
|
|
|
|
migrated to the
|
|
|
|
[`service-intentions`](/docs/agent/config-entries/service-intentions)
|
|
|
|
config entry kind.
|
|
|
|
|
2020-12-18 00:11:36 +00:00
|
|
|
## Upsert Intention by Name ((#upsert-intention-by-name))
|
2020-10-14 15:23:05 +00:00
|
|
|
|
|
|
|
-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
|
|
|
|
|
|
|
|
This endpoint creates a new intention and returns `true` if it was created
|
|
|
|
successfully.
|
|
|
|
|
|
|
|
The name and destination pair must be unique. If another intention matches the
|
|
|
|
name and destination, the creation will replace the previous intention.
|
|
|
|
|
|
|
|
~> The intentions created by this endpoint will not be assigned the following
|
|
|
|
fields: `ID`, `CreatedAt`, `UpdatedAt`. Additionally, the `Meta` field cannot
|
|
|
|
be persisted using this endpoint and will require editing the enclosing
|
|
|
|
`service-intentions` config entry for the destination.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
|
|
|
| `PUT` | `/connect/intentions/exact` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
|
|
|
[required ACLs](/api#authentication).
|
|
|
|
|
|
|
|
| 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="/docs/connect/intentions#intention-management-permissions">
|
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
### URL Parameters
|
|
|
|
|
|
|
|
- `source` `(string: <required>)` - Specifies the source service. This
|
|
|
|
is specified as part of the URL.
|
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
|
|
|
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
|
|
|
is specified as part of the URL.
|
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
|
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
|
|
|
If not provided, the default namespace will be inherited from the
|
|
|
|
request's ACL token or will default to the `default` namespace.
|
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
|
|
|
`X-Consul-Namespace` header.
|
|
|
|
Added in Consul 1.9.0.
|
|
|
|
|
|
|
|
### PUT Body Parameters
|
|
|
|
|
|
|
|
- `SourceType` `(string: "")` - The type for the `SourceName` value.
|
|
|
|
This can be only "consul" today to represent a Consul service. If not
|
|
|
|
provided, this will be defaulted to "consul".
|
|
|
|
|
|
|
|
- `Action` `(string: "")` - For an L4 intention this is required, and should be
|
|
|
|
set to one of "allow" or "deny" for the action that should be taken if
|
|
|
|
this intention matches a request.
|
|
|
|
|
|
|
|
This should be omitted for an L7 intention as it is mutually exclusive with
|
|
|
|
the `Permissions` field.
|
|
|
|
|
|
|
|
- `Permissions` `(array<IntentionPermission>)` - The list of all [additional L7
|
|
|
|
attributes](/docs/agent/config-entries/service-intentions#intentionpermission)
|
|
|
|
that extend the intention match criteria.
|
|
|
|
|
|
|
|
Permission precedence is applied top to bottom. For any given request the
|
|
|
|
first permission to match in the list is terminal and stops further
|
|
|
|
evaluation. As with L4 intentions, traffic that fails to match any of the
|
|
|
|
provided permissions in this intention will be subject to the default
|
|
|
|
intention behavior is defined by the default [ACL
|
|
|
|
policy](/docs/agent/options#acl_default_policy).
|
|
|
|
|
|
|
|
This should be omitted for an L4 intention as it is mutually exclusive with
|
|
|
|
the `Action` field.
|
|
|
|
|
|
|
|
- `Description` `(string: "")` - Description for the intention. This is not
|
|
|
|
used by Consul, but is presented in API responses to assist tooling.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--request PUT \
|
|
|
|
--data @payload.json \
|
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
true
|
|
|
|
```
|
|
|
|
|
|
|
|
## Create Intention with ID
|
|
|
|
|
|
|
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
|
|
|
[upserting by name](#upsert-intention-by-name) or editing the
|
|
|
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
|
|
|
entry for the destination.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
This endpoint creates a new intention and returns its ID if it was created
|
|
|
|
successfully.
|
|
|
|
|
|
|
|
The name and destination pair must be unique. If another intention matches
|
|
|
|
the name and destination, the creation will fail. You must either update the
|
|
|
|
existing intention or delete it prior to creating a new one.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------- | ------------------ |
|
|
|
|
| `POST` | `/connect/intentions` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
|
|
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
### URL Parameters
|
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
|
|
namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
|
|
|
|
If not provided, the default namespace will be inherited from the
|
|
|
|
request's ACL token or will default to the `default` namespace.
|
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
|
|
|
`X-Consul-Namespace` header.
|
|
|
|
Added in Consul 1.9.0.
|
|
|
|
|
|
|
|
### POST Body Parameters
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
- `SourceName` `(string: <required>)` - The source of the intention.
|
|
|
|
For a `SourceType` of `consul` this is the name of a Consul service. The
|
|
|
|
service doesn't need to be registered.
|
|
|
|
|
2020-06-26 21:59:15 +00:00
|
|
|
- `SourceNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
|
2020-07-08 23:09:00 +00:00
|
|
|
`SourceName` parameter.
|
2020-06-26 21:59:15 +00:00
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
- `DestinationName` `(string: <required>)` - The destination of the intention.
|
|
|
|
The intention destination is always a Consul service, unlike the source.
|
|
|
|
The service doesn't need to be registered.
|
|
|
|
|
2020-06-26 21:59:15 +00:00
|
|
|
- `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
|
2020-07-08 23:09:00 +00:00
|
|
|
`DestinationName` parameter.
|
2020-06-26 21:59:15 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
- `SourceType` `(string: "")` - The type for the `SourceName` value.
|
|
|
|
This can be only "consul" today to represent a Consul service. If not
|
|
|
|
provided, this will be defaulted to "consul".
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
|
|
|
|
the action that should be taken if this intention matches a request.
|
|
|
|
|
2020-06-26 21:59:15 +00:00
|
|
|
- `Description` `(string: "")` - Description for the intention. This is not
|
2020-10-14 15:23:05 +00:00
|
|
|
used by Consul, but is presented in API responses to assist tooling.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationName": "db",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
|
|
|
--request POST \
|
|
|
|
--data @payload.json \
|
2018-08-28 16:07:15 +00:00
|
|
|
http://127.0.0.1:8500/v1/connect/intentions
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
## Update Intention by ID
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
|
|
|
[upserting by name](#upsert-intention-by-name) or editing the
|
|
|
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
|
|
|
entry for the destination.
|
|
|
|
|
|
|
|
This endpoint updates an intention with the given values.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
2020-10-14 15:23:05 +00:00
|
|
|
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
|
|
|
[required ACLs](/api#authentication).
|
|
|
|
|
|
|
|
| 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="/docs/connect/intentions#intention-management-permissions">
|
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This
|
|
|
|
is specified as part of the URL.
|
|
|
|
|
|
|
|
- Other parameters are identical to creating an intention.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationName": "other-db",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--request PUT \
|
|
|
|
--data @payload.json \
|
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
|
|
|
```
|
|
|
|
|
2020-12-18 00:11:36 +00:00
|
|
|
## Read Specific Intention by Name ((##read-specific-intention-by-name))
|
2020-10-14 15:23:05 +00:00
|
|
|
|
|
|
|
This endpoint reads a specific intention by its unique source and destination.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
|
|
|
| `GET` | `/connect/intentions/exact` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
2018-09-06 10:34:28 +00:00
|
|
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
- `source` `(string: <required>)` - Specifies the source service. This
|
2018-05-29 21:07:40 +00:00
|
|
|
is specified as part of the URL.
|
2020-10-14 15:23:05 +00:00
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
|
|
|
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
|
|
|
is specified as part of the URL.
|
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
|
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
|
|
|
If not provided, the default namespace will be inherited from the
|
|
|
|
request's ACL token or will default to the `default` namespace.
|
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
|
|
|
`X-Consul-Namespace` header.
|
|
|
|
Added in Consul 1.9.0.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2020-10-14 15:23:05 +00:00
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Description": "",
|
|
|
|
"SourceNS": "default",
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationNS": "default",
|
|
|
|
"DestinationName": "db",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow",
|
|
|
|
"Meta": {},
|
2018-06-07 04:18:32 +00:00
|
|
|
"Precedence": 9,
|
2018-05-29 21:07:40 +00:00
|
|
|
"CreateIndex": 11,
|
|
|
|
"ModifyIndex": 11
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
## Read Specific Intention by ID
|
2020-06-26 21:59:15 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
|
|
|
[reading by name](#read-specific-intention-by-name) or by viewing the
|
|
|
|
[`service-intentions`](/docs/agent/config-entries/service-intentions)
|
|
|
|
config entry for the destination.
|
|
|
|
|
|
|
|
This endpoint reads a specific intention.
|
2020-06-26 21:59:15 +00:00
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
2020-10-14 15:23:05 +00:00
|
|
|
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
2020-06-26 21:59:15 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
|
|
|
[required ACLs](/api#authentication).
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
|
|
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
|
|
|
|
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-06-26 21:59:15 +00:00
|
|
|
See{' '}
|
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
|
2020-06-26 21:59:15 +00:00
|
|
|
is specified as part of the URL.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
2020-10-14 15:23:05 +00:00
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
2020-06-26 21:59:15 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
|
|
|
"Description": "",
|
|
|
|
"SourceNS": "default",
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationNS": "default",
|
|
|
|
"DestinationName": "db",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow",
|
|
|
|
"Meta": {},
|
|
|
|
"Precedence": 9,
|
|
|
|
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
|
|
|
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
|
|
|
"CreateIndex": 11,
|
|
|
|
"ModifyIndex": 11
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
## List Intentions
|
|
|
|
|
|
|
|
This endpoint lists all intentions.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------- | ------------------ |
|
|
|
|
| `GET` | `/connect/intentions` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
2018-09-06 10:34:28 +00:00
|
|
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-07 15:48:44 +00:00
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
|
|
queries results prior to returning the data.
|
|
|
|
|
2020-07-08 23:09:00 +00:00
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the
|
|
|
|
namespace to list intentions from.
|
2020-06-26 21:59:15 +00:00
|
|
|
The `*` wildcard may be used to list intentions from all namespaces.
|
2020-10-14 15:23:05 +00:00
|
|
|
If not provided, the default namespace will be inherited from the
|
2020-07-08 23:09:00 +00:00
|
|
|
request's ACL token or will default to the `default` namespace.
|
2020-06-26 21:59:15 +00:00
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
2020-07-08 23:09:00 +00:00
|
|
|
`X-Consul-Namespace` header.
|
2020-06-26 21:59:15 +00:00
|
|
|
Added in Consul 1.9.0.
|
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2020-04-07 15:48:44 +00:00
|
|
|
'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web'
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
{
|
|
|
|
"Description": "",
|
|
|
|
"SourceNS": "default",
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationNS": "default",
|
|
|
|
"DestinationName": "db",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow",
|
|
|
|
"Meta": {},
|
2018-06-07 04:18:32 +00:00
|
|
|
"Precedence": 9,
|
2018-05-29 21:07:40 +00:00
|
|
|
"CreateIndex": 11,
|
|
|
|
"ModifyIndex": 11
|
|
|
|
}
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
2020-04-07 15:48:44 +00:00
|
|
|
### Filtering
|
|
|
|
|
|
|
|
The filter will be executed against each Intention in the result list with
|
|
|
|
the following selectors and filter operations being supported:
|
|
|
|
|
2020-04-13 17:38:44 +00:00
|
|
|
| Selector | Supported Operations |
|
|
|
|
| ----------------- | -------------------------------------------------- |
|
|
|
|
| `Action` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `Description` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `DestinationNS` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `Meta` | Is Empty, Is Not Empty, In, Not In |
|
|
|
|
| `Meta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `Precedence` | Equal, Not Equal |
|
|
|
|
| `SourceNS` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `SourceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
| `SourceType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
2020-04-07 15:48:44 +00:00
|
|
|
|
2020-12-18 00:11:36 +00:00
|
|
|
## Delete Intention by Name ((#delete-intention-by-name))
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
This endpoint deletes a specific intention by its unique source and destination.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| -------- | --------------------------- | ------------------ |
|
|
|
|
| `DELETE` | `/connect/intentions/exact` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
2018-09-06 10:34:28 +00:00
|
|
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
- `source` `(string: <required>)` - Specifies the source service. This
|
2018-05-29 21:07:40 +00:00
|
|
|
is specified as part of the URL.
|
2020-10-14 15:23:05 +00:00
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
|
|
|
is specified as part of the URL.
|
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
|
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
|
|
|
If not provided, the default namespace will be inherited from the
|
|
|
|
request's ACL token or will default to the `default` namespace.
|
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
|
|
|
`X-Consul-Namespace` header.
|
|
|
|
Added in Consul 1.9.0.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2020-10-14 15:23:05 +00:00
|
|
|
--request DELETE \
|
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
## Delete Intention by ID
|
|
|
|
|
|
|
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
|
|
|
[deleting by name](#delete-intention-by-name) or editing the
|
|
|
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
|
|
|
entry for the destination.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
This endpoint deletes a specific intention.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| -------- | --------------------------- | ------------------ |
|
|
|
|
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
2018-09-06 10:34:28 +00:00
|
|
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete. This
|
|
|
|
is specified as part of the URL.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
|
|
|
--request DELETE \
|
2018-08-28 16:07:15 +00:00
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## Check Intention Result
|
|
|
|
|
|
|
|
This endpoint evaluates the intentions for a specific source and destination
|
2020-10-14 15:23:05 +00:00
|
|
|
and returns whether the connection would be authorized or not given the current
|
|
|
|
Consul configuration and set of intentions.
|
|
|
|
|
|
|
|
-> **Note:** This endpoint will always evaulate intentions with `Permissions`
|
|
|
|
defined as *deny* intentions during. This endpoint is only suited for
|
|
|
|
networking layer 4 (e.g. TCP) integration.
|
|
|
|
|
|
|
|
For performance and reliability reasons it is desirable to implement intention
|
|
|
|
enforcement by listing [intentions that match the
|
|
|
|
destination](/api/connect/intentions#list-matching-intentions) and representing
|
|
|
|
them in the native configuration of the proxy itself (such as RBAC for Envoy).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
This endpoint will work even if the destination service has
|
|
|
|
`intention = "deny"` specifically set, because the resulting API response
|
|
|
|
does not contain any information about the intention itself.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
|
|
|
| `GET` | `/connect/intentions/check` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
2018-09-06 10:34:28 +00:00
|
|
|
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `source` `(string: <required>)` - Specifies the source service. This
|
|
|
|
is specified as part of the URL.
|
2020-10-14 15:23:05 +00:00
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
|
|
|
is specified as part of the URL.
|
2020-10-14 15:23:05 +00:00
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
2020-06-26 21:59:15 +00:00
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
|
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
2020-10-14 15:23:05 +00:00
|
|
|
If not provided, the default namespace will be inherited from the
|
2020-07-08 23:09:00 +00:00
|
|
|
request's ACL token or will default to the `default` namespace.
|
2020-06-26 21:59:15 +00:00
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
2020-07-08 23:09:00 +00:00
|
|
|
`X-Consul-Namespace` header.
|
2020-06-26 21:59:15 +00:00
|
|
|
Added in Consul 1.9.0.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/check?source=web&destination=db
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Allowed": true
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
- `Allowed` is true if the connection would be allowed, false otherwise.
|
|
|
|
|
|
|
|
## List Matching Intentions
|
|
|
|
|
|
|
|
This endpoint lists the intentions that match a given source or destination.
|
|
|
|
The intentions in the response are in evaluation order.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
|
|
|
| `GET` | `/connect/intentions/match` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
[required ACLs](/api#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | -------------------- | ----------------------------- |
|
|
|
|
| `YES` | `all` | `background refresh` | `intentions:read`<sup>1</sup> |
|
2018-08-20 19:33:15 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
<p>
|
2020-10-14 15:23:05 +00:00
|
|
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
2020-04-07 18:55:19 +00:00
|
|
|
See{' '}
|
2020-04-09 23:46:54 +00:00
|
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
2020-04-07 18:55:19 +00:00
|
|
|
Intention Management Permissions
|
|
|
|
</a>{' '}
|
|
|
|
for more details.
|
|
|
|
</p>
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `by` `(string: <required>)` - Specifies whether to match the "name" value
|
|
|
|
by "source" or "destination".
|
|
|
|
|
|
|
|
- `name` `(string: <required>)` - Specifies a name to match. This parameter
|
|
|
|
can be repeated for batching multiple matches.
|
2020-10-14 15:23:05 +00:00
|
|
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
2020-06-26 21:59:15 +00:00
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
|
|
namespace to use when `name` parameter lacks namespaces.
|
2020-10-14 15:23:05 +00:00
|
|
|
If not provided, the default namespace will be inherited from the
|
2020-07-08 23:09:00 +00:00
|
|
|
request's ACL token or will default to the `default` namespace.
|
2020-06-26 21:59:15 +00:00
|
|
|
This value may be provided by either the `ns` URL query parameter or in the
|
2020-07-08 23:09:00 +00:00
|
|
|
`X-Consul-Namespace` header.
|
2020-06-26 21:59:15 +00:00
|
|
|
Added in Consul 1.9.0.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"web": [
|
|
|
|
{
|
|
|
|
"Description": "",
|
|
|
|
"SourceNS": "default",
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationNS": "default",
|
|
|
|
"DestinationName": "db",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "deny",
|
|
|
|
"Meta": {},
|
|
|
|
"CreateIndex": 12,
|
|
|
|
"ModifyIndex": 12
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"Description": "",
|
|
|
|
"SourceNS": "default",
|
|
|
|
"SourceName": "web",
|
|
|
|
"DestinationNS": "default",
|
|
|
|
"DestinationName": "*",
|
|
|
|
"SourceType": "consul",
|
|
|
|
"Action": "allow",
|
|
|
|
"Meta": {},
|
|
|
|
"CreateIndex": 11,
|
|
|
|
"ModifyIndex": 11
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|