Create and manage intentions

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

payload.json

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

Log into the Consul UI and choose Services from the sidebar menu.
Click on a service and then click the *Intentions tab.
Click Create and choose the source service from the drop-down menu.
You can add an optional description.
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.
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.

Click Add permission to open the permission editor.
Enable the Allow or Deny option.
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.
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:

Kind: Declares the type of configuration entry. Must be set to service-intentions.
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.
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 or 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.
apiVersion: Specifies the Consul API version. Must be set to consul.hashicorp.com/v1alpha1.
kind: Declares the type of configuration entry. Must be set to ServiceIntentions.
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: 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 or 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.

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:

Create and manage service intentions