»Intentions - Connect HTTP API

The /connect/intentions endpoint provide tools for managing intentions.

»Upsert Intention by Name

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.

Method Path Produces
PUT /connect/intentions/exact application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none intentions:write1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»URL Parameters

  • source (string: <required>) - Specifies the source service. This is specified as part of the URL. This can take several forms.

  • destination (string: <required>) - Specifies the destination service. This is specified as part of the URL. This can take several forms.

  • ns (string: "")

    Enterprise
    - 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 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.

    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

{
  "SourceType": "consul",
  "Action": "allow"
}
{  "SourceType": "consul",  "Action": "allow"}

»Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
$ curl \    --request PUT \    --data @payload.json \    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db

»Sample Response

true
true

»Create Intention with ID

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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none intentions:write1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»URL Parameters

  • ns (string: "")
    Enterprise
    - 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

  • 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: "")

    Enterprise
    - 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 doesn't need to be registered.

  • DestinationNS (string: "")

    Enterprise
    - 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

{
  "SourceName": "web",
  "DestinationName": "db",
  "SourceType": "consul",
  "Action": "allow"
}
{  "SourceName": "web",  "DestinationName": "db",  "SourceType": "consul",  "Action": "allow"}

»Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/connect/intentions
$ curl \    --request POST \    --data @payload.json \    http://127.0.0.1:8500/v1/connect/intentions

»Sample Response

{
  "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
{  "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"}

»Update Intention by ID

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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none intentions:write1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»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

{
  "SourceName": "web",
  "DestinationName": "other-db",
  "SourceType": "consul",
  "Action": "allow"
}
{  "SourceName": "web",  "DestinationName": "other-db",  "SourceType": "consul",  "Action": "allow"}

»Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
$ 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

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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all none intentions:read1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»Parameters

  • source (string: <required>) - Specifies the source service. This is specified as part of the URL. This can take several forms.

  • destination (string: <required>) - Specifies the destination service. This is specified as part of the URL. This can take several forms.

  • ns (string: "")

    Enterprise
    - 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.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
$ curl \    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db

»Sample Response

{
  "Description": "",
  "SourceNS": "default",
  "SourceName": "web",
  "DestinationNS": "default",
  "DestinationName": "db",
  "SourceType": "consul",
  "Action": "allow",
  "Meta": {},
  "Precedence": 9,
  "CreateIndex": 11,
  "ModifyIndex": 11
}
{  "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

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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all none intentions:read1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»Parameters

  • uuid (string: <required>) - Specifies the UUID of the intention to read. This is specified as part of the URL.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
$ curl \    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c

»Sample Response

{
  "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
}
{  "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.

Method Path Produces
GET /connect/intentions application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all none intentions:read1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»Parameters

  • filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.

  • ns (string: "")

    Enterprise
    - Specifies the namespace to list intentions from. The * wildcard may be used to list intentions from all 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.

»Sample Request

$ curl \
    'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web'
$ curl \    'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web'

»Sample Response

[
  {
    "Description": "",
    "SourceNS": "default",
    "SourceName": "web",
    "DestinationNS": "default",
    "DestinationName": "db",
    "SourceType": "consul",
    "Action": "allow",
    "Meta": {},
    "Precedence": 9,
    "CreateIndex": 11,
    "ModifyIndex": 11
  }
]
[  {    "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

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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none intentions:write1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»Parameters

  • source (string: <required>) - Specifies the source service. This is specified as part of the URL. This can take several forms.

  • destination (string: <required>) - Specifies the destination service. This is specified as part of the URL. This can take several forms.

  • ns (string: "")

    Enterprise
    - 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.

»Sample Request

$ curl \
    --request DELETE \
    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
$ curl \    --request DELETE \    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db

»Delete Intention by ID

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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none intentions:write1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»Parameters

  • uuid (string: <required>) - Specifies the UUID of the intention to delete. This is specified as part of the URL.

»Sample Request

$ curl \
    --request DELETE \
    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
$ 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.

For performance and reliability reasons it is desirable to implement intention enforcement by listing intentions that match the destination 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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none intentions:read1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»Parameters

  • source (string: <required>) - Specifies the source service. This is specified as part of the URL. This can take several forms.

  • destination (string: <required>) - Specifies the destination service. This is specified as part of the URL. This can take several forms.

  • ns (string: "")

    Enterprise
    - 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.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/intentions/check?source=web&destination=db
$ curl \    http://127.0.0.1:8500/v1/connect/intentions/check?source=web&destination=db

»Sample Response

{
  "Allowed": true
}
{  "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, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all background refresh intentions:read1

1 Intention ACL rules are specified as part of a service rule. See Intention Management Permissions for more details.

»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.

  • ns (string: "")

    Enterprise
    - Specifies the default namespace to use when name parameter lacks 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.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web
$ curl \    http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web

»Sample Response

{
  "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
    }
  ]
}
{  "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    }  ]}