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 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 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 for additional information about configuring ACLs 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 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 EnterpriseEnterprise

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:

$ 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 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:

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

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

$ 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:

$ consul intention create -<action> <source> <destination>

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

$ consul intention create -allow web db

You can use the asterisk (*) wildcard to specify multiple destination services. Refer to Precedence and match order for additional information.

Consul UI

1. Log into the Consul UI and choose Services from the sidebar menu.
2. Click on a service and then click the *Intentions tab.
3. Click Create and choose the source service from the drop-down menu.
4. You can add an optional description.
5. Choose one of the following options:
   1. Allow: Allows the source service to send requests to the destination.
   2. Deny: Prevents the source service from sending requests to the destination.
   3. Application Aware: Enables you to specify L7 criteria for dynamically enforcing intentions. Refer to Configure application aware settings for additional information.
6. 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.
2. Enable the Allow or Deny option.
3. 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 in the service intentions configuration entry reference for information about the available configuration fields.
4. 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:

Refer to the service intentions configuration entry reference documentation for details about all configuration options.

Refer to the example service intentions configurations 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 or globally in a proxy defaults configuration entry.

Apply the service intentions configuration entry

You can apply the configuration entry using the consul config command or by calling the /config API endpoint. 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
• Custom Resource Definitions for Consul on Kubernetes