consul/website/content/docs/connect/intentions/create-manage-intentions.mdx

178 lines
11 KiB
Plaintext
Raw Normal View History

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