--- 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/connect/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 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`](/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 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: ```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](/consul/docs/connect/config-entries/service-intentions#sources-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 - ``` 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: - [`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. - [`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. 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)