open-consul/website/pages/api-docs/connect/intentions.mdx

586 lines
19 KiB
Plaintext
Raw Normal View History

---
layout: api
page_title: Intentions - Connect - HTTP API
sidebar_title: Intentions
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).
## Create Intention
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` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### Parameters
- `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.
- `SourceNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
2020-07-08 23:09:00 +00:00
`SourceName` parameter.
- `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.
- `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
2020-07-08 23:09:00 +00:00
`DestinationName` parameter.
- `SourceType` `(string: <required>)` - The type for the `SourceName` value.
This can be only "consul" today to represent a Consul service.
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
the action that should be taken if this intention matches a request.
- `Description` `(string: "")` - Description for the intention. This is not
used for anything by Consul, but is presented in API responses to assist
tooling.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
If not provided at all, 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.
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.
Added in Consul 1.9.0.
### Sample Payload
```json
{
"SourceName": "web",
"DestinationName": "db",
"SourceType": "consul",
"Action": "allow"
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8500/v1/connect/intentions
```
### Sample Response
```json
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
## Read Specific Intention
This endpoint reads a specific intention.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `GET` | `/connect/intentions/:uuid` | `application/json` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
is specified as part of the URL.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
```
### Sample Response
```json
{
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
"Description": "",
"SourceNS": "default",
"SourceName": "web",
"DestinationNS": "default",
"DestinationName": "db",
"SourceType": "consul",
"Action": "allow",
"Meta": {},
2018-06-07 04:18:32 +00:00
"Precedence": 9,
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
"CreateIndex": 11,
"ModifyIndex": 11
}
```
## Read Specific Intention by Name
This endpoint reads a specific intention by its unique source and destination.
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `GET` | `/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 |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '}
<a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions
</a>{' '}
for more details.
</p>
### Parameters
- `source` `(string: <required>)` - Specifies the source service. This
is specified as part of the URL.
This can take [several forms](/docs/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](/docs/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 at all, 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.
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.
Added in Consul 1.9.0.
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
```
### 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
}
```
## List Intentions
This endpoint lists all intentions.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------------- | ------------------ |
| `GET` | `/connect/intentions` | `application/json` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### 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.
The `*` wildcard may be used to list intentions from all namespaces.
If not provided at all, 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.
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.
Added in Consul 1.9.0.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web'
```
### Sample Response
```json
[
{
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
"Description": "",
"SourceNS": "default",
"SourceName": "web",
"DestinationNS": "default",
"DestinationName": "db",
"SourceType": "consul",
"Action": "allow",
"Meta": {},
2018-06-07 04:18:32 +00:00
"Precedence": 9,
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
"CreateIndex": 11,
"ModifyIndex": 11
}
]
```
### 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 |
## Update Intention
This endpoint updates an intention with the given values.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### 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
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
```
## Delete Intention
This endpoint deletes a specific intention.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| -------- | --------------------------- | ------------------ |
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### 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
$ curl \
--request DELETE \
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
```
## Check Intention Result
This endpoint evaluates the intentions for a specific source and destination
and returns whether the connection would be authorized or not given the
current Consul configuration and set of intentions.
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` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### Parameters
- `source` `(string: <required>)` - Specifies the source service. This
is specified as part of the URL.
This can take [several forms](/docs/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](/docs/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 at all, 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.
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.
Added in Consul 1.9.0.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
http://127.0.0.1:8500/v1/connect/intentions/check?source=web&destination=db
```
### 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` |
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).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
2020-04-07 18:55:19 +00:00
<p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
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>
### 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.
This can take [several forms](/docs/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `name` parameter lacks namespaces.
If not provided at all, 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.
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.
Added in Consul 1.9.0.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web
```
### Sample Response
```json
{
"web": [
{
"ID": "ed16f6a6-d863-1bec-af45-96bbdcbe02be",
"Description": "",
"SourceNS": "default",
"SourceName": "web",
"DestinationNS": "default",
"DestinationName": "db",
"SourceType": "consul",
"Action": "deny",
"Meta": {},
"CreatedAt": "2018-05-21T16:41:33.296693825Z",
"UpdatedAt": "2018-05-21T16:41:33.296694288Z",
"CreateIndex": 12,
"ModifyIndex": 12
},
{
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
"Description": "",
"SourceNS": "default",
"SourceName": "web",
"DestinationNS": "default",
"DestinationName": "*",
"SourceType": "consul",
"Action": "allow",
"Meta": {},
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
"CreateIndex": 11,
"ModifyIndex": 11
}
]
}
```