mirror of https://github.com/hashicorp/consul
179 lines
10 KiB
Markdown
179 lines
10 KiB
Markdown
---
|
|
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 <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 filename="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/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 -<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)
|