772 lines
27 KiB
Plaintext
772 lines
27 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Intentions - Connect - HTTP API
|
|
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
|
|
[intentions](/consul/docs/connect/intentions).
|
|
|
|
-> **1.9.0 and later:** Reading and writing intentions has been
|
|
migrated to the
|
|
[`service-intentions`](/consul/docs/connect/config-entries/service-intentions)
|
|
config entry kind.
|
|
|
|
## Upsert Intention by Name ((#upsert-intention-by-name))
|
|
|
|
-> **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](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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>
|
|
|
|
The corresponding CLI command is [`consul intention create -replace`](/consul/commands/intention/create#replace).
|
|
|
|
### Query Parameters
|
|
|
|
- `source` `(string: <required>)` - Specifies the source service
|
|
according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service
|
|
according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
|
|
to use when `source` or `destination` query parameters do not include a namespace
|
|
as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `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](/consul/docs/connect/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](/consul/docs/agent/config/config-files#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`](/consul/docs/connect/config-entries/service-intentions) config
|
|
entry for the destination.
|
|
|
|
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.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------- | ------------------ |
|
|
| `POST` | `/connect/intentions` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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>
|
|
|
|
The corresponding CLI command is [`consul intention create`](/consul/commands/intention/create).
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
|
|
to use when `SourceNS` or `DestinationNS` request body parameters do not include a namespace
|
|
as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `SourceName` `(string: <required>)` - The source of the intention.
|
|
For a `SourceType` of `consul` this is the name of a Consul service. The
|
|
service does not need to be registered.
|
|
|
|
- `SourceNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
|
|
`SourceName` parameter.
|
|
|
|
- `DestinationName` `(string: <required>)` - The destination of the intention.
|
|
The intention destination is always a Consul service, unlike the source.
|
|
The service does not need to be registered.
|
|
|
|
- `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
|
|
`DestinationName` parameter.
|
|
|
|
- `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: <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 by Consul, but is presented in API responses to assist tooling.
|
|
|
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"SourceName": "web",
|
|
"DestinationName": "db",
|
|
"SourceType": "consul",
|
|
"Action": "allow"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```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"
|
|
}
|
|
```
|
|
|
|
## Update Intention by 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`](/consul/docs/connect/config-entries/service-intentions) config
|
|
entry for the destination.
|
|
|
|
This endpoint updates an intention with the given values.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------------- | ------------------ |
|
|
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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>
|
|
|
|
This endpoint supports the same parameters as the [create an intention](#create-intention-with-id) endpoint.
|
|
Additional parameters unique to this endpoint include:
|
|
|
|
### Path Parameters
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update.
|
|
|
|
### 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
|
|
```
|
|
|
|
## Read Specific Intention by Name ((##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](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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{' '}
|
|
<code>service</code> rule. See{' '}
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
|
Intention Management Permissions
|
|
</a>{' '}
|
|
for more details.
|
|
</p>
|
|
|
|
The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get).
|
|
|
|
### Query Parameters
|
|
|
|
- `source` `(string: <required>)` - Specifies the source service
|
|
according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service
|
|
according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
|
|
to use when `source` or `destination` query parameters do not include a namespace
|
|
as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Description": "",
|
|
"SourceNS": "default",
|
|
"SourceName": "web",
|
|
"DestinationNS": "default",
|
|
"DestinationName": "db",
|
|
"SourceType": "consul",
|
|
"Action": "allow",
|
|
"Meta": {},
|
|
"Precedence": 9,
|
|
"CreateIndex": 11,
|
|
"ModifyIndex": 11
|
|
}
|
|
```
|
|
|
|
## Read Specific Intention by ID
|
|
|
|
-> **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`](/consul/docs/connect/config-entries/service-intentions)
|
|
config entry for the destination.
|
|
|
|
This endpoint reads a specific intention.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------------- | ------------------ |
|
|
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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{' '}
|
|
<code>service</code> rule. See{' '}
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
|
Intention Management Permissions
|
|
</a>{' '}
|
|
for more details.
|
|
</p>
|
|
|
|
The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get).
|
|
|
|
### Path Parameters
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read.
|
|
|
|
### Sample Request
|
|
|
|
```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": {},
|
|
"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.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------- | ------------------ |
|
|
| `GET` | `/connect/intentions` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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{' '}
|
|
<code>service</code> rule. See{' '}
|
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
|
Intention Management Permissions
|
|
</a>{' '}
|
|
for more details.
|
|
</p>
|
|
|
|
The corresponding CLI command is [`consul intention list`](/consul/commands/intention/list).
|
|
|
|
### Query Parameters
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
queries results prior to returning the data.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the
|
|
namespace to list intentions from.
|
|
The `*` wildcard may be used to list intentions from all namespaces.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web'
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Description": "",
|
|
"SourceNS": "default",
|
|
"SourceName": "web",
|
|
"DestinationNS": "default",
|
|
"DestinationName": "db",
|
|
"SourceType": "consul",
|
|
"Action": "allow",
|
|
"Meta": {},
|
|
"Precedence": 9,
|
|
"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:
|
|
|
|
| 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 |
|
|
|
|
## Delete Intention by Name ((#delete-intention-by-name))
|
|
|
|
-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
|
|
|
|
This endpoint deletes a specific intention by its unique source and destination.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | --------------------------- | ------------------ |
|
|
| `DELETE` | `/connect/intentions/exact` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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>
|
|
|
|
The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete).
|
|
|
|
### Query Parameters
|
|
|
|
- `source` `(string: <required>)` - Specifies the source service
|
|
according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service
|
|
according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
|
|
to use when `source` or `destination` query parameters do not include a namespace
|
|
as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
|
```
|
|
|
|
## 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`](/consul/docs/connect/config-entries/service-intentions) config
|
|
entry for the destination.
|
|
|
|
This endpoint deletes a specific intention.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | --------------------------- | ------------------ |
|
|
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#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>
|
|
|
|
The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete).
|
|
|
|
### Path Parameters
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete.
|
|
|
|
### Sample Request
|
|
|
|
```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.
|
|
|
|
-> **Note:** This endpoint will always evaluate 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](/consul/api-docs/connect/intentions#list-matching-intentions) and representing
|
|
them in the native configuration of the proxy itself (such as RBAC for Envoy).
|
|
|
|
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.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------------- | ------------------ |
|
|
| `GET` | `/connect/intentions/check` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| 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="/docs/connect/intentions#intention-management-permissions">
|
|
Intention Management Permissions
|
|
</a>{' '}
|
|
for more details.
|
|
</p>
|
|
|
|
The corresponding CLI command is [`consul intention check`](/consul/commands/intention/check).
|
|
|
|
### Query Parameters
|
|
|
|
- `source` `(string: <required>)` - Specifies the source service
|
|
according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `destination` `(string: <required>)` - Specifies the destination service
|
|
according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
|
|
to use when `source` or `destination` query parameters do not include a namespace
|
|
as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```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.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------------- | ------------------ |
|
|
| `GET` | `/connect/intentions/match` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| 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="/docs/connect/intentions#intention-management-permissions">
|
|
Intention Management Permissions
|
|
</a>{' '}
|
|
for more details.
|
|
</p>
|
|
|
|
The corresponding CLI command is [`consul intention match`](/consul/commands/intention/match).
|
|
|
|
### Query Parameters
|
|
|
|
- `by` `(string: <required>)` - Specifies whether to match the "name" value
|
|
by "source" or "destination".
|
|
|
|
- `name` `(string: <required>)` - Specifies a name to match
|
|
according to the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can repeat this parameter for batching multiple matches.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
|
|
to use when the `name` query parameter does not include a namespace
|
|
as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming).
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
"http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web"
|
|
```
|
|
|
|
### 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
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Methods to Specify Namespace <EnterpriseAlert inline />
|
|
|
|
Connect intention endpoints
|
|
support several methods for specifying the namespace of intention resources
|
|
with the following order of precedence:
|
|
1. `ns` query parameter
|
|
1. `X-Consul-Namespace` request header
|
|
1. Namespace is inherited from the namespace of the request's ACL token (if any)
|
|
1. The `default` namespace
|