---
layout: docs
page_title: 'Configuration Entry Kind: Service Intentions (beta)'
sidebar_title: service-intentions <sup>Beta</sup>
description: >-
  The service-intentions config entry kind controls Connect traffic
  authorization for both networking layer 4 (e.g. TCP) and networking layer 7
  (e.g. HTTP).
---

# Service Intentions ((#service-intentions)) <sup>Beta</sup>

-> **1.9.0+:** This config entry is available in Consul versions 1.9.0 and newer.

The `service-intentions` config entry kind controls Connect traffic
authorization for both networking layer 4 (e.g. TCP) and networking layer 7
(e.g. HTTP).

Service intentions config entries represent a collection of
[intentions](/docs/connect/intentions) sharing a specific destination. All
intentions governing access to a specific destination are stored in a single
`service-intentions` config entry.

A single config entry may define a mix of both L4 and L7 style intentions, but
for a specific source L4 and L7 intentions are mutually exclusive. Only one
will apply at a time. Default behavior for L4 is configurable (regardless of
global setting) by defining a low precedence intention for that destination.

## Interaction with other Config Entries

L7 intentions within a config entry are restricted to only destination services
that define their protocol as HTTP-based via a corresponding
[`service-defaults`](/docs/agent/config-entries/service-defaults) config entry
or globally via [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .

## Sample Config Entries

Grant some clients more REST access than others:

```hcl
Kind = "service-intentions"
Name = "api"
Sources = [
  {
    Name = "admin-dashboard"
    Permissions = [
      {
        Action = "allow"
        HTTP {
          PathPrefix = "/v2"
          Methods    = ["GET", "PUT", "POST", "DELETE", "HEAD"]
        }
      }
    ]
  },
  {
    Name = "report-generator"
    Permissions = [
      {
        Action = "allow"
        HTTP {
          PathPrefix = "/v2/widgets"
          Methods    = ["GET"]
        }
      }
    ]
  }
  # NOTE: a default catch-all based on the default ACL policy will apply to
  # unmatched connections and requests. Typically this will be DENY.
]
```

Selectively deny some gRPC service methods. Since gRPC method calls [are
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can
use an HTTP path match rule to control traffic:

```hcl
Kind = "service-intentions"
Name = "billing"
Sources = [
  {
    Name = "frontend-web"
    Permissions = [
      # The frontend website can execute all billing service methods except
      # issuing refunds.
      {
        Action = "deny"
        HTTP {
          PathExact = "/mycompany.BillingService/IssueRefund"
        }
      },
      {
        Action = "allow"
        HTTP {
          PathPrefix = "/mycompany.BillingService/"
        }
      }
    ]
  },
  {
    Name = "support-portal"
    Permissions = [
      # But the support team portal page can execute all methods.
      {
        Action = "allow"
        HTTP {
          PathPrefix = "/mycompany.BillingService/"
        }
      }
    ]
  }
  # NOTE: a default catch-all based on the default ACL policy will apply to
  # unmatched connections and requests. Typically this will be DENY.
]
```

You can mix and match L4 and L7 intentions per source:

```hcl
Kind = "service-intentions"
Name = "api"
Sources = [
  {
    Name   = "hackathon-project"
    Action = "deny"
  },
  {
    Name   = "web"
    Action = "allow"
  },
  {
    Name = "nightly-reconciler"
    Permissions = [
      {
        Action = "allow"
        HTTP {
          PathExact = "/v1/reconcile-data"
          Methods   = ["POST"]
        }
      }
    ]
  },
  # NOTE: a default catch-all based on the default ACL policy will apply to
  # unmatched connections and requests. Typically this will be DENY.
]
```

## Available Fields

- `Kind` - Must be set to `service-intentions`.

- `Name` `(string: <required>)` - The destination of all intentions defined in
  this config entry. This may be set to the wildcard character (`*`) to match
  all services that don't otherwise have intentions defined.

- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to.
  This may be set to the wildcard character (`*`) to match
  all services in all namespaces that don't otherwise have intentions defined.

- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.

- `Sources` `(array<SourceIntention>)` - The list of all [intention sources and 
  the authorization granted to those sources](#sourceintention). The order of
  this list does not matter, but out of convenience Consul will always store
  this reverse sorted by intention precedence, as that is the order that they
  will be evaluated at enforcement time.

### `SourceIntention`

- `Name` `(string: <required>)` - The source of the intention.
  For a `Type` of `consul` this is the name of a Consul service. The service
  doesn't need to be registered.

- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - The namespace
  for the `Name` parameter.

- `Action` `(string: "")` - For an L4 intention this is required, and should be
  set to one of `"allow"` or `"deny"` for the action that should be taken if
  this intention matches a request.

  This should be omitted for an L7 intention as it is mutually exclusive with
  the `Permissions` field.

- `Permissions` `(array<IntentionPermission>)` - The list of all [additional L7
  attributes](#intentionpermission) that extend the intention match criteria.

  Permission precedence is applied top to bottom. For any given request the
  first permission to match in the list is terminal and stops further
  evaluation. As with L4 intentions, traffic that fails to match any of the
  provided permissions in this intention will be subject to the default
  intention behavior is defined by the default [ACL
  policy](/docs/agent/options#acl_default_policy).

  This should be omitted for an L4 intention as it is mutually exclusive with
  the `Action` field.

- `Precedence` `(int: <read-only>)` - An [integer precedence
  value](/docs/connect/intentions#precedence-and-match-order) computed from the
  source and destination naming components.

- `Type` `(string: "")` - The type for the `Name` value. This can be
  only "consul" today to represent a Consul service. If not provided, this
  will be defaulted to "consul".

- `Description` `(string: "")` - Description for the intention. This is not
  used by Consul, but is presented in API responses to assist tooling.

- `LegacyID` `(string: <read-only>)` - This is the UUID to uniquely identify
  this intention in the system. Cannot be set directly and is exposed here as
  an artifact of the config entry migration and is primarily used to allow
  legacy intention [API](/api-docs/connect/intentions#update-intention-by-id)
  [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
  continue to function for a period of time after [upgrading to
  1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).

- `LegacyMeta` `(map<string|string>: <read-only>)` - Specified arbitrary KV
  metadata pairs attached to the intention, rather than to the enclosing config
  entry. Cannot be set directly and is exposed here as an artifact of the
  config entry migration and is primarily used to allow legacy intention
  [API](/api-docs/connect/intentions#update-intention-by-id)
  [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
  continue to function for a period of time after [upgrading to
  1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).

- `LegacyCreateTime` `(time: optional)` - The timestamp that this intention was
  created. Cannot be set directly and is exposed here as an artifact of the
  config entry migration and is primarily used to allow legacy intention
  [API](/api-docs/connect/intentions#update-intention-by-id)
  [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
  continue to function for a period of time after [upgrading to
  1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).

- `LegacyUpdateTime` `(time: optional)` - The timestamp that this intention was
  last updated. Cannot be set directly and is exposed here as an artifact of
  the config entry migration and is primarily used to allow legacy intention
  [API](/api-docs/connect/intentions#update-intention-by-id)
  [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
  continue to function for a period of time after [upgrading to
  1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).

### `IntentionPermission`

- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
  the action that should be taken if this permission matches a request.

- `HTTP` `(IntentionHTTPPermission: <required>)` - A set of
  [HTTP-specific authorization criteria](#intentionhttppermission).

### `IntentionHTTPPermission`

- `PathExact` `(string: "")` - Exact path to match on the HTTP request path.

  At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.

- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.

  At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.

- `PathRegex` `(string: "")` - Regular expression to match on the HTTP
  request path.

  The syntax is [described below](#regular-expression-syntax).

  At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.

- `Methods` `(array<string>)` - A list of HTTP methods for which this match
  applies. If unspecified all HTTP methods are matched.
  If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).

- `Header` `(array<IntentionHTTPHeaderPermission>)` - A set of criteria that can
  match on HTTP request headers. If more than one is configured all must match
  for the overall match to apply.

  - `Name` `(string: <required>)` - Name of the header to match.

  - `Present` `(bool: false)` - Match if the header with the given name is
    present with any value.

    At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
    may be configured.

  - `Exact` `(string: "")` - Match if the header with the given name is this
    value.

    At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
    may be configured.

  - `Prefix` `(string: "")` - Match if the header with the given name has
    this prefix.

    At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
    may be configured.

  - `Suffix` `(string: "")` - Match if the header with the given name has
    this suffix.

    At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
    may be configured.

  - `Regex` `(string: "")` - Match if the header with the given name matches
    this pattern.

    The syntax is [described below](#regular-expression-syntax).

    At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
    may be configured.

  - `Invert` `(bool: false)` - Inverts the logic of the match.

## ACLs

Configuration entries may be protected by [ACLs](/docs/security/acl).

Reading a `service-intentions` config entry requires `intentions:read` on the resource.

Creating, updating, or deleting a `service-intentions` config entry requires
`intentions:write` on the resource.

Intention ACL rules are specified as part of a `service` rule. See [Intention
Management Permissions](/docs/connect/intentions#intention-management-permissions) for
more details.

## Regular Expression Syntax

The actual syntax of the regular expression fields described here is entirely
proxy-specific.

When using [Envoy](/docs/connect/proxies/envoy) as a proxy, the syntax for
these fields is [RE2](https://github.com/google/re2/wiki/Syntax).