---
layout: docs
page_title: Create and manage service intentions
description: >-
  Learn how to create and manage Consul service mesh intentions using service-intentions config entries, the `consul intentions` command, and `/connect/intentions` API endpoint.
---

# Create and manage intentions

This topic describes how to create and manage service intentions, which are configurations for controlling access between services in the service mesh. 

## Overview

You can create single intentions or create them in batches using the Consul API, CLI, or UI. You can also define a service intention configuration entry that sets default intentions for all services in the mesh. Refer to [Service intentions overview](/consul/docs/connnect/intentions/intentions) for additional background information about intentions.

## Requirements

- At least two services must be registered in the datacenter. 
- TLS must be enabled to enforce L4 intentions. Refer to [Encryption](/consul/docs/security/encryption) for additional information.

### ACL requirements

Consul grants permissions for creating and managing intentions based on the destination, not the source. When ACLs are enabled, services and operators must present a token linked to a policy that grants read and write permissions to the destination service. 

Consul implicitly grants `intentions:read` permissions to destination services when they are configured with `service:read` or `service:write` permissions. This is so that the services can allow or deny inbound connections when they attempt to join the service mesh. Refer to [Service rules](/consul/docs/security/acl/acl-rules#service-rules) for additional information about configuring ALCs for intentions. 

The default ACL policy configuration determines the default behavior for intentions. If the policy is set to `deny`, then all connections or requests are denied and you must enable them explicitly. Refer to [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) for details.

## Create an intention

You can create and manage intentions one at a time using the Consul API, CLI, or UI You can specify one destination or multiple destinations in a single intention.

### API

Send a `PUT` request to the `/connect/intentions/exact` HTTP API endpoint and specify the following query parameters:

- `source`: Service sending the request
- `destination`: Service responding to the request
- `ns`: Namespace of the destination service <EnterpriseAlert inline/>

For L4 intentions, you must also specify the intention action in the request payload. 

The following example creates an intention that allows `web` to send request to `db`: 

```shell-session
$ curl --request PUT \ 
--data ' { "Action": "allow" } ' \
http://localhost:8500/v1/connect/intentions/exact\?source\=web\&destination\=db 
```

Refer to the `/connect/intentions/exact` [HTTP API endpoint documentation](/consul/api-docs/connect/intentions) for additional information request payload parameters.

For L7 intentions, specify the `Permissions` in the request payload to configure attributes for dynamically enforcing intentions. In the following example payload, Consul allows HTTP GET requests if the request body is empty:   

<CodeBlockConfig heading="payload.json">

```json
{
   "Permissions": [
   {
      "Action": "allow",
      "HTTP": {
         "Methods": ["GET"],
         "Header": [
           {
              "Name": "Content-Length",
	   "Exact": "0"
           }
         ]
      }
    }
  ]
}

```

</CodeBlockConfig>

The `Permissions` object specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. Refer to the [`Sources[].Permissions[]` parameter](/consul/connect/config-entries/service-intentions#source-permissions) in the service intentions configuration entry reference for configuration details.   

To apply the intention, call the endpoint and pass the configuration file containing the attributes to the endpoint:

```shell-session
$ curl --request PUT \ 
--data @payload.json \
http://localhost:8500/v1/connect/intentions/exact\?source\=svc1\&destination\=sv2 
```
### CLI

Use the `consul intention create` command according to the following syntax to create a new intention: 

```shell-session
$ consul intention create -<action> <source> <destination>
```

The following example creates an intention that allows `web` service instances to connect to `db` service instances:

```shell-session
$ consul intention create -allow web db
```

You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-match-order) for additional information.  

### Consul UI

1. Log into the Consul UI and choose **Services** from the sidebar menu.
1. Click on a service and then click the **Intentions* tab.
1. Click **Create** and choose the source service from the drop-down menu.
1. You can add an optional description.
1. Choose one of the following options:
    1. **Allow**: Allows the source service to send requests to the destination.
    1. **Deny**: Prevents the source service from sending requests to the destination.
    1. **Application Aware**: Enables you to specify L7 criteria for dynamically enforcing intentions. Refer to [Configure application aware settings](#configure-application-aware-settings) for additional information.
1. Click **Save**. 

Repeat the procedure as necessary to create additional intentions.

#### Configure application aware settings

You can use the Consul UI to configure L7 permissions.

1. Click **Add permission** to open the permission editor.
1. Enable the **Allow** or **Deny** option.
1. You can specify a path, request method, and request headers to match. All criteria must be satisfied for Consul to enforce the permission. Refer to the [`Sources[].Permissions[]` parameter](/consul/docs/connect/config-entries/service-intentions#sources-permissions) in the service intentions configuration entry reference for information about the available configuration fields.
1. Click **Save**.

Repeat the procedure as necessary to create additional permissions.

## Create multiple intentions

You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic. 

### Define a service intention configuration entry

Configure the following fields:

<Tabs>

<Tab heading="HCL" group="hcl"> 

- [`Kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `service-intentions`.
- [`Name`](/consul/docs/connect/config-entries/service-intentions#kind): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions.
- [`Sources`](/consul/docs/connect/config-entries/service-intentions#sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence.
- [`Sources.Action`](/consul/docs/connect/config-entries/service-intentions#sources-action) or [`Sources.Permissions`](/consul/docs/connect/config-entries/service-intentions#sources-permissions): For L4 intentions, set the `Action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `Permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `Actions` and `Permissions` settings are mutually exclusive.

</Tab>

<Tab heading="YAML" group="yaml">

- [`apiVersion`](/consul/docs/connect/config-entries/service-intentions#apiversion): Specifies the Consul API version. Must be set to `consul.hashicorp.com/v1alpha1`. 
- [`kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `ServiceIntentions`.
- [`spec.destination.name`](/consul/docs/connect/config-entries/service-intentions#spec-destination-name): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions.
- [`spec.sources`](/consul/docs/connect/config-entries/service-intentions#spec-sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence.
- [`spec.sources.action`](/consul/docs/connect/config-entries/service-intentions#spec-sources-action) or [`spec.sources.permissions`](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions): For L4 intentions, set the `action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `actions` and `permissions` settings are mutually exclusive.

</Tab>

</Tabs>

Refer to the [service intentions configuration entry](/consul/docs/connect/config-entries/service-intentions) reference documentation for details about all configuration options.

Refer to the [example service intentions configurations](/consul/docs/connect/config-entries/service-intentions#examples) for additional guidance.  

#### Interaction with other configuration entries

L7 intentions defined in a configuration entry are restricted to destination services
configured with an HTTP-based protocol as defined in a corresponding
[service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults) 
or globally in a [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults).

### Apply the service intentions configuration entry

You can apply the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `ServiceIntentions` custom resource definitions (CRD) to implement and manage Consul configuration entries.  

Refer to the following topics for details about applying configuration entries: 

- [How to Use Configuration Entries](/consul/docs/agent/config-entries) 
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)