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 requestdestination
: Service responding to the requestns
: Namespace of the destination service Enterprise
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
:
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:
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:
CLI
Use the consul intention create
command according to the following syntax to create a new intention:
The following example creates an intention that allows web
service instances to connect to db
service instances:
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:
- Allow: Allows the source service to send requests to the destination.
- Deny: Prevents the source service from sending requests to the destination.
- 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 toservice-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
orSources.Permissions
: For L4 intentions, set theAction
field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure thePermissions
settings, which define a set of application-aware attributes for dynamically matching incoming requests. TheActions
andPermissions
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: