Service intentions configuration entry reference

This topic provides reference information for the service intentions configuration entry. Intentions are configurations for controlling access between services in the service mesh. A single service intentions configuration entry specifies one destination service and one or more L4 traffic sources, L7 traffic sources, or combination of traffic sources. Refer to Service mesh intentions overview for additional information.

Configuration model

The following outline shows how to format the service intentions configuration entry. Click on a property name to view details about the configuration.

Kind: string | required | must be set to service-intentions
Name: string | required
Namespace: string | default | Enterprise
Partition: string | default | Enterprise
Meta: map | no default
Sources: list | no default
- Name: string | no default
- Peer: string | no default
- Namespace: string | no default | Enterprise
- Partition: string | no default | Enterprise
- Action: string | no default | required for L4 intentions
- Permissions: list | no default
  - Action: string | no default | required
  - HTTP: map | required
    - PathExact: string | no default
    - PathPrefix: string | no default
    - PathRegex: string | no default
    - Methods: list | no default
    - Header: list of maps |no default
      - Name: string | required
      - Present: boolean | false
      - Exact: string | no default
      - Prefix: string | no default
      - Suffix: string | no default
      - Contains: string | no default
      - Regex: string | no default
      - IgnoreCase: boolean | false
      - Invert: boolean | false
- Precedence: number | no default | read-only
- Type: string | consul
- Description: string
- LegacyID: string | no default | read-only
- LegacyMeta: map | no default | read-only
- LegacyCreateTime: string | no default | read-only
- LegacyUpdateTime: string | no default | read-only

apiVersion: string | must be set to consul.hashicorp.com/v1alpha1
kind: string | must be set to ServiceIntentions
metadata: map | required
- name: string | required
- namespace: string | default | Enterprise
spec: map | no default
- destination: map | no default
  - name: string | required
  - namespace: string | default | Enterprise
- sources: list | no default
  - name: string | no default
  - peer: string | no default
  - namespace: string | no default | Enterprise
  - partition: string | no default | Enterprise
  - action: string | no default | required for L4 intentions
  - permissions: list | no default
    - action: string | no default | required
    - http: map | required
      - pathExact: string | no default
      - pathPrefix: string | no default
      - pathRegex: string | no default
      - methods: list | no default
        header: list of maps |no default
        name: string | required
        present: boolean | false
        exact: string | no default
        prefix: string | no default
        suffix: string | no default
        contains: string | no default
        regex: string | no default
        ignoreCase: boolean | false
        invert: boolean | false
  - type: string | consul
  - description: string

Complete configuration

When every field is defined, a service intentions configuration entry has the following form:

Kind =  "service-intentions"
Name = "<name of destination service>"
Namespace = "<destination namespace>"                    # string
Partition = "<destination partition>"                    # string
Meta = {
  "<key-1>" = "<value-1>"
  "<key-2>" = "<value-2>"
  }
Sources = [
  {
    Name =  "<name of service sending traffic>"            # string
    Peer =  "<name of cluster containing source service>"  # string
    Namespace = "<namespace containing source service>"    # string
    Partition = "<sources-partition>"                      # string
    Action = "allow" or "deny"                             # string for L4 intentions
    Permissions = [
      {
        Action = "allow" or "deny"                   # string for L7 intentions
        HTTP =  {
          PathExact =  "<exact path to match>"       # string
          PathPrefix = "<path prefix to match>"      # string
          PathRegex = "<regex pattern to match>"     # string
          Methods = [
            "<fist http method to match>",           # string
            "<second http method to match>"
          ]
          Header = [
            {
              Name = "<http header name>"              # string
              Present = <true or false>                # boolean
              Invert = <true or false>                 # boolean
            },
            {
              Name = "<http header name>"              # string
              Exact = "<header-value>"                 # boolean
              IgnoreCase = <true or false>             # boolean
              Invert = <true or false>                 # boolean
            },
            {
              Name = "<http header name>"              # string
              Prefix = "<source header value prefix>"  # string
              IgnoreCase = <true or false>             # boolean
              Invert = <true or false>                 # boolean
            },
            {
              Name = "<http header name>"              # string
              Suffix = "<source header value suffix>"  # string
              IgnoreCase = <true or false>             # boolean
              Invert = <true or false>                 # boolean
            },
            {
              Name = "<http header name>"              # string
              Contains = "<value to search for>"       # string
              IgnoreCase = <true or false>             # boolean
              Invert = <true or false>                 # boolean
            },
            {
              Name = "<http header name>"              # string
              Regex = "<regex pattern to match>"       # string
              Invert = <true or false>                 # boolean
            }
         ]
        }
      }
    ]
    Type = "consul"                                     # string
    Description = "<description for API responses>"     # string
    Precedence = <read-only>                            # number
    LegacyID = <read-only>                              # string
    LegacyMeta = <read-only>                            # string
    LegacyCreateTime = <read-only>                      # string
    LegacyUpdateTime = <read-only>                      # string
  }
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: service-intentions
metadata:
  name: <name of destination service>
  namespace: <destination namespace>
spec:
  destination:
    destination:
      name: <name of destination service>
      namespace: <destination namespace>
  sources:
    name: <name of service sending traffic>
    peer: <name of cluster containing source service>
    namespace: <namespace containing source service>
    partition: <sources-partition>
    action: allow or deny
    permissions:
    - action: allow or deny
      http:
        pathExact: <exact path to match>
        pathPrefix: <path prefix to match>
        pathRegex: <regex pattern to match>
        methods:
        - <fist http method to match>
          <second http method to match>
      header:
      - name: <http header name>
        present: true
        invert: false
      - name: <http header name>
        exact: <header-value>
        ignoreCase: false
        invert: false
      - name: <http header name>
        prefix: <source header value prefix>
        ignoreCase: false
        invert: false
      - name: <http header name>
        suffix: <source header value suffix>
        ignoreCase: false
        invert: false
      - name: <http header name>
        contains: <value to search for>
        ignoreCase: false
        invert: false
      - name: <http header name>
        regex: <regex pattern to match>
        invert: false
  type: consul
  description: <description for API responses>

{
   "Kind":"service-intentions",
   "Name":"<name of destination service>",
   "Namespace":"<destination namespace>",
   "Partition":"<destination partition>",
   "Meta":{
      "key-1":"<value-1>",
      "key-2":"<value-2>"
   },
   "Sources":[
      {
         "Name":"<name of service sending traffic>",
         "Peer":"<name of cluster containing source service>",
         "Namespace":"<namespace containing source service>",
         "Partition":"<sources-partition>",
         "Action":"allow or deny",
         "Permissions":[
            {
               "Action":"allow or deny",
               "HTTP":{
                  "PathExact":"<exact path to match>",
                  "PathPrefix":"<path prefix to match>",
                  "PathRegex":"<regex pattern to match>",
                  "Methods":[
                     "<fist http method to match>",
                     "<second http method to match>"
                  ],
                  "Header":[
                     {
                        "Name":"<http header name>",
                        "Present":true,
                        "Invert":false
                     },
                     {
                        "Name":"<http header name>",
                        "Exact":"<header-value>",
                        "IgnoreCase":false,,
                        "Invert":false
                     },
                     {
                        "Name":"<http header name>",
                        "Prefix":"<source header value prefix>",
                        "IgnoreCase":false,
                        "Invert":false
                     },
                     {
                        "Name":"<http header name>",
                        "Suffix":"<source header value suffix>",
                        "IgnoreCase":false,
                        "Invert":false
                     },
                     {
                        "Name":"<http header name>",
                        "Contains":"<value to search for>",
                        "IgnoreCase":false,
                        "Invert":false
                     },
                     {
                        "Name":"<http header name>",
                        "Regex":"<regex pattern to match>",
                        "Invert":false
                     }
                  ]
               }
            }
         ],
         "Type":"consul",
         "Description":"<description for API responses>",
         "Precedence":"<read-only-number>",
         "LegacyID":"<read-only-string>",
         "LegacyMeta":"<read-only-string>",
         "LegacyCreateTime":"<read-only-string>",
         "LegacyUpdateTime":"<read-only-string>"
      }
   ]
}

Specification

This section provides details about the fields you can configure in the service intentions configuration entry.

`Kind`

Specifies the type of configuration entry to implement. Must be set to service-intentions.

Values

Default: None
This field is required.
Data type: String value that must be set to service-intentions.

`Name`

Specifies a name of the destination service for all intentions defined in the configuration entry.

Values

Default: Defaults to the name of the node after writing the entry to the Consul server.
This field is required.
Data type: String

You can also specify a wildcard character (*) to match all services without intentions. Intentions that are applied with a wildcard, however, are not supported when defining L7 Permissions.

`Namespace` Enterprise

Specifies the namespace that the configuration entry applies to. Services in the namespace are the traffic destinations that the intentions allow or deny traffic to.

Values

Default: default
Data type: String

You can also specify a wildcard character (*) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 Permissions.

`Partition` Enterprise

Specifies the admin partition to apply the configuration entry. Services in the specified partition are the traffic destinations that the intentions allow or deny traffic to.

Values

Default: default
Data type: String

`Meta`

Specifies key-value pairs to add to the KV store when the configuration entry is evaluated.

Values

Default: None
Data type: Map of one or more key-value pairs
- keys: String
- values: String, integer, or float

`Sources[]`

List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime. Refer to Precedence for additional information.

Values

Default: None
List of objects that contain the following fields:
- Name
- Peer
- Namespace Enterprise
- Partition Enterprise
- Action
- Permissions
- Precedence
- Type
- Description
- LegacyID
- LegacyMeta
- LegacyCreateTime
- LegacyUpdateTime

`Sources[].Name`

Specifies the name of the source that the intention allows or denies traffic from. If Type is set to consul, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog.

Values

Default: None
This field is required.
Data type: String

`Sources[].Peer`

Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to Cluster peering overview for additional information about peers.

The Peer and Partition fields are mutually exclusive.

Values

Default: None
Data type: String

`Sources[].Namespace` Enterprise

Specifies the traffic source namespace that the intention allows or denies traffic from.

Values

Default: If Peer is unspecified, defaults to the destination Namespace.
Data type: String

`Sources[].Partition` Enterprise

Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to Admin Partitions for additional information about partitions.

The Peer and Partition fields are mutually exclusive.

Values

Default: If Peer is unspecified, defaults to the destination Partition.
Data type: string

`Sources[].Action`

Specifies the action to take when the source sends traffic to the destination service. The value is either allow or deny. Do not configure this field to apply L7 intentions to the same source. Configure the Permissions field instead.

Values

Default: None
This field is required for L4 intentions.
Data type: String value set to either allow or deny

Refer to the following examples for additional guidance:

`Sources[].Permissions[]`

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.

Consul applies permissions in the order specified in the configuration. Beginning at the top of the list, Consul applies the first matching request and stops evaluating against the remaining configurations.

For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the acl_default_policy configuration.

Do not configure this field for L4 intentions. Use the Sources.Action parameter instead.

The Permissions only applies to services with a compatible protocol. Permissions are not supported when the Name or Namespace field is configured with a wildcard because service instances or services in a namespace may use different protocols.

Values

Default: None
List of objects that contain the following fields:
- Action
- HTTP

Refer to the following examples for additional guidance:

`Sources[].Permissions[].Action`

Specifies the action to take when the source sends traffic to the destination service. The value is either allow or deny.

Values

Default: None
This field is required.
Data type: String value set to either allow or deny.

`Sources[].Permissions[].HTTP`

Specifies a set of HTTP-specific match criteria. Consul applies the action defined in the Action field to source traffic that matches the criteria.

Values

Default: None
This field is required.
Data type: Map

The following table describes the parameters that the HTTP map may contain:

Parameter	Description	Data type	Default
`PathExact`	Specifies an exact path to match on the HTTP request path. Do not specify `PathExact` if `PathPrefix` or `PathRegex` are configured in the same `HTTP` configuration.	string	none
`PathPrefix`	Specifies a path prefix to match on the HTTP request path. Do not specify `PathPrefix` if `PathExact` or `PathRegex` are configured in the same `HTTP` configuration.	string	none
`PathRegex`	Defines a regular expression to match on the HTTP request path. Do not specify `PathRegex` if `PathExact` or `PathPrefix` are configured in the same `HTTP` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the re2 documentation for details.	string	none
`Methods`	Specifies a list of HTTP methods. Consul applies the permission if a request matches the `PathExact`, `PathPrefix`, `PathRegex`, or `Header`, and the source sent the request using one of the specified methods. Refer to the Mozilla documentation for a list of supported request headers.	list	All request methods
`Header`	Specifies a header name and matching criteria for HTTP request headers. Refer to `Sources[].Permissions[].HTTP[].Header` for details.	list of maps	none

`Sources[].Permissions[].HTTP[].Header[]`

Specifies a header name and matching criteria for HTTP request headers. The request header must match all specified criteria for the permission to apply.

Values

Default: None
Data type: list of objects

Each member of the Header list is a map that contains a Name field and at least one match criterion. The following table describes the parameters that each member of the Header list may contain:

Parameter	Description	Data type	Required
`Name`	Specifies the name of the header to match.	string	required
`Present`	Enables a match if the header configured in the `Name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `Present` if `Exact`, `Prefix`, `Suffix`, or `Regex` are configured in the same `Header` configuration.	boolean	optional
`Exact`	Specifies a value for the header key set in the `Name` field. If the request header value matches the `Exact` value, Consul applies the permission. Do not specify `Exact` if `Present`, `Prefix`, `Suffix`, or `Regex` are configured in the same `Header` configuration.	string	optional
`Prefix`	Specifies a prefix value for the header key set in the `Name` field. If the request header value starts with the `Prefix` value, Consul applies the permission. Do not specify `Prefix` if `Present`, `Exact`, `Suffix`, or `Regex` are configured in the same `Header` configuration.	string	optional
`Suffix`	Specifies a suffix value for the header key set in the `Name` field. If the request header value ends with the `Suffix` value, Consul applies the permission. Do not specify `Suffix` if `Present`, `Exact`, `Prefix`, or `Regex` are configured in the same `Header` configuration.	string	optional
`Contains`	Specifies a contains value for the header key set in the `Name` field. If the request header value includes the `Contains` value, Consul applies the permission. Do not specify `Contains` if `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` are configured in the same `header` configuration.	string	optional
`Regex`	Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, `Suffix`, or `Contains` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the re2 documentation for details.	string	optional
`IgnoreCase`	Ignores the case of the provided header value when matching with `Exact`, `Prefix`, `Suffix`, or `Contains`. Default is `false`.	boolean	optional
`Invert`	Inverts the matching logic configured in the `Header`. Default is `false`.	boolean	optional

`Sources[].Precedence`

The Precedence field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to Precedence and matching order for additional information.

`Sources[].Type`

Specifies the type of destination service that the configuration entry applies to. The only value supported is consul.

Values

Default: consul
Data type: String

`Sources[].Description`

Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network.

Values

Default: None
Data type: String

`Sources[].LegacyID`

Read-only unique user ID (UUID) for the intention in the system. Consul generates the value and exposes it in the configuration entry so that legacy API endpoints continue to function. Refer to Read Specific Intention by ID for additional information.

`Sources[].LegacyMeta`

Read-only set of arbitrary key-value pairs to attach to the intention. Consul generates the metadata and exposes it in the configuration entry so that legacy intention API endpoints continue to function. Refer to Read Specific Intention by ID for additional information.

`Sources[].CreateTime`

Read-only timestamp for the intention creation. Consul exposes the timestamp in the configuration entry to allow legacy intention API endpoints to continue functioning. Refer to Read Specific Intention by ID for additional information.

`Sources[].LegacyUpdateTime`

Read-only timestamp marking the most recent intention update. Consul exposes the timestamp in the configuration entry to allow legacy intention API endpoints to continue functioning. Refer to Read Specific Intention by ID for additional information.

`apiVersion`

Specifies the version of the Consul API for integrating with Kubernetes. The value must be consul.hashicorp.com/v1alpha1.

Values

Default: None
This field is required.
String value that must be set to consul.hashicorp.com/v1alpha1.

`kind`

Specifies the type of configuration entry to implement. Must be set to ServiceIntentions.

Values

Default: None
This field is required.
Data type: String value that must be set to ServiceIntentions.

`metadata`

Map that contains an arbitrary name for the configuration entry and the namespace it applies to.

Values

Default: None
Data type: Map

`metadata.name`

Specifies an arbitrary name for the configuration entry. Note that in other configuration entries, the metadata.name field specifies the name of the service that the settings apply to. For service intentions, the service that accepts the configurations is the destination and is specified in the spec.destination.name field. Refer to the following topics for additional information:

Values

Default: None
Data type: String

`metadata.namespace` Enterprise

Specifies the namespace that the configuration entry applies to. Refer to Consul Enterprise for information about how Consul namespaces map to Kubernetes Namespaces. Open source Consul distributions (Consul OSS) ignore the metadata.namespace configuration.

Values

Default: default
Data type: String

`spec`

Map that contains the details about the ServiceIntentions configuration entry. The apiVersion, kind, and metadata fields are siblings of the spec field. All other configurations are children.

Values

Default: None
This field is required.
Data type: Map

`spec.destination`

Map that identifies the destination name and destination namespace that source services are allowed or denied access to.

Values

Default: None
This field is required.
Data type: Map

`spec.destination.name`

Specifies the name of the destination service in the mesh that the intentions apply to. You can also specify a wildcard character (*) to match all services that are missing intention settings. Intentions that are applied with a wildcard, however, are not supported when defining L7 permissions.

Values

Default: None
This field is required.
Data type: String

`spec.metadata.namespace` Enterprise

Specifies the namespace that the configuration entry applies to. You can also specify a wildcard character (*) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 permissions.

Refer to Consul Enterprise for information about how Consul namespaces map to Kubernetes Namespaces. Open source Consul distributions (Consul OSS) ignore the metadata.namespace configuration.

Values

Default: If not set, destination service namespace is inherited from the connectInject.consulNamespaces configuration. Refer to ServiceIntentions Special Case (Enterprise) for details.
Data type: String

`spec.sources[]`

Values

Default: None
List of objects that contain the following fields:
- name
- peer
- namespace Enterprise
- partition Enterprise
- Action
- permissions
- type
- description

`spec.sources[].name`

Specifies the name of the source that the intention allows or denies traffic from. If type is set to consul, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog.

Values

Default: None
This field is required.
Data type: String

`spec.sources[].peer`

Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to Cluster peering overview for additional information about peers. The peer and partition fields are mutually exclusive.

Values

Default: None
Data type: String

`spec.sources[].namespace` Enterprise

Specifies the traffic source namespace that the intention allows or denies traffic from.

Values

Default: If peer is unspecified, defaults to the namespace specified in the spec.destination.namespace field.
Data type: String

`spec.sources[].partition` Enterprise

Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to Admin Partitions for additional information about partitions. The peer and partition fields are mutually exclusive.

Values

Default: If peer is unspecified, defaults to the partition specified in spec.destination.partition.
Data type: String

`spec.sources[].action`

Specifies the action to take when the source sends traffic to the destination service. The value is either allow or deny. Do not configure this field for L7 intentions. Configure the spec.sources.permissions field instead.

Values

Default: None
This field is required for L4 intentions.
Data type: String value set to either allow or deny

`spec.sources[].permissions[]`

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.

Consul applies permissions in the order specified in the configuration. Starting at the beginning of the list, Consul applies the first matching request and stops evaluating against the remaining configurations.

For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the acl_default_policy configuration.

Do not configure this field for L4 intentions. Use the spec.sources.action parameter instead.

permissions configurations only apply to services with a compatible protocol. As a result, they are not supported when the spec.destination.name or spec.destination.namespace field is configured with a wildcard because service instances or services in a namespace may use different protocols.

Values

Default: None
List of objects that contain the following fields:
- action
- http

`spec.sources[].permissions[].action`

Specifies the action to take when the source sends traffic to the destination service. The value is either allow or deny.

Values

Default: None
This field is required.
Data type: String value set to either allow or deny

`spec.sources[].permissions[].http`

Specifies a set of HTTP-specific match criteria. Consul applies the action defined in the spec.sources.permissions.action field to source traffic that matches the criteria.

Values

Default: None
This field is required.
Data type: Map

The following table describes the parameters that the HTTP map may contain:

Parameter	Description	Data type	Default
`pathExact`	Specifies an exact path to match on the HTTP request path. Do not specify `pathExact` if `pathPrefix` or `pathRegex` are configured in the same `http` configuration.	string	none
`pathPrefix`	Specifies a path prefix to match on the HTTP request path. Do not specify `pathPrefix` if `pathExact` or `pathRegex` are configured in the same `http` configuration.	string	none
`pathRegex`	Defines a regular expression to match on the HTTP request path. Do not specify `pathRegex` if `pathExact` or `pathPrefix` are configured in the same `http` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the re2 documentation for details.	string	none
`methods`	Specifies a list of HTTP methods. Consul applies the permission if a request matches the `pathExact`, `pathPrefix`, `pathRegex`, or `header`, and the source sent the request using one of the specified methods. Refer to the Mozilla documentation for a list of supported request headers.	list	All request methods
`header`	Specifies a header name and matching criteria for HTTP request headers. Refer to `spec.sources[].permissions[].http[].header` for details.	list of maps	none

`spec.sources[].permissions[].http[].header`

Specifies a set of criteria for matching HTTP request headers. The request header must match all specified criteria for the permission to apply.

Values

Default: None
Data type: List of maps

Each member of the header list is a map that contains a name field and at least one match criterion.

Warning: If it is possible for a header to contain multiple values, we recommend using contains or regex rather than exact, prefix, or suffix. Envoy internally concatenates multiple header values into a single CSV value prior to applying match rules, which may result in match rules that depend on the beginning or end of a string vulnerable to circumvention. A more robust alternative is using contains or, if a stricter value match is required, configuring a regex pattern that is tolerant of comma-separated values. These options are available as of Consul CE 1.20.1 and Consul Enterprise 1.20.1, 1.19.2, 1.18.3, and 1.15.15.

The following table describes the parameters that each member of the header list may contain:

Parameter	Description	Data type	Required
`name`	Specifies the name of the header to match.	string	required
`present`	Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, `contains`, or `regex` are configured in the same `header` configuration.	boolean	optional
`Exact`	Specifies a value for the header key set in the `Name` field. If the request header value matches the `exact` value, Consul applies the permission. Do not specify `exact` if `present`, `prefix`, `suffix`, `contains`, or `regex` are configured in the same `header` configuration.	string	optional
`prefix`	Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission. Do not specify `prefix` if `present`, `exact`, `suffix`, `contains`, or `regex` are configured in the same `header` configuration.	string	optional
`suffix`	Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission. Do not specify `suffix` if `present`, `exact`, `prefix`, `contains`, or `regex` are configured in the same `header` configuration.	string	optional
`contains`	Specifies a contains value for the header key set in the `name` field. If the request header value includes the `contains` value, Consul applies the permission. Do not specify `contains` if `present`, `exact`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration.	string	optional
`regex`	Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, `suffix`, or `contains` are configured in the same `header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the re2 documentation for details.	string	optional
`ignoreCase`	Ignores the case of the provided header value when matching with exact, prefix, suffix, or contains. Default is `false`.	boolean	optional
`invert`	Inverts the matching logic configured in the `header`. Default is `false`.	boolean	optional

`spec.sources[].type`

Specifies the type of destination service that the configuration entry applies to. The only value supported is consul.

Values

Default: consul
Data type: String

`spec.sources[].description`

Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network.

Values

Default: None
Data type: String

Examples

The following examples demonstrate potential use-cases for the service intentions configuration entry.

L4 Intentions for specific sources and destinations

The following example configuration entry specifies an L4 intention that denies traffic from web to db service instances, but allows traffic from api to db.

Kind = "service-intentions"
Name = "db"
Sources = [
  {
    Name   = "web"
    Action = "deny"
  },
  {
    Name   = "api"
    Action = "allow"
  }
]

L4 intentions for all destinations

In the following L4 example, the destination is configured with a * wildcard. As a result, traffic from web service instances is denied for any service in the datacenter.

Kind = "service-intentions"
Name = "*"
Sources = [
  {
    Name   = "web"
    Action = "deny"
  }
]

L4 intentions for all sources

In the following L4 example, the source is configured with a * wildcard. As a result, traffic from any service is denied to db service instances.

Kind = "service-intentions"
Name = "db"
Sources = [
  {
    Name   = "*"
    Action = "deny"
  }
]

REST access

In the following example, the admin-dashboard and report-generator services have different levels of access when making REST calls:

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.
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: api
spec:
  destination:
    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.

{
  "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"]
          }
        }
      ]
    }
  ]
}

gRPC

In the following example, Consul denies requests from frontend-web to the IssueRefund gRPC service. Because gRPC method calls use the HTTP/2 protocol, you can apply an HTTP path-matching rule to control traffic:

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/"
        }
      }
    ]
  }
  # A default catch-all based on the default ACL policy applies to
  # unmatched connections and requests. This is typically DENY.
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: billing
spec:
  destination:
    name: billing
  sources:
    # The frontend website can execute all billing service methods except
    # issuing refunds.
    - name: frontend-web
      permissions:
        - action: deny
          http:
            pathExact: /mycompany.BillingService/IssueRefund
        - action: allow
          http:
            pathPrefix: '/mycompany.BillingService/'
    - name: support-protocol
      # But the support team portal page can execute all methods.
      permissions:
        - action: allow
          http:
            pathPrefix: '/mycompany.BillingService/'
  # A default catch-all based on the default ACL policy applies to
  # unmatched connections and requests. This is typically DENY.

{
  "Kind": "service-intentions",
  "Name": "billing",
  "Sources": [
    {
      "Name": "frontend-web",
      "Permissions": [
        {
          "Action": "deny",
          "HTTP": {
            "PathExact": "/mycompany.BillingService/IssueRefund"
          }
        },
        {
          "Action": "allow",
          "HTTP": {
            "PathPrefix": "/mycompany.BillingService/"
          }
        }
      ]
    },
    {
      "Name": "support-portal",
      "Permissions": [
        {
          "Action": "allow",
          "HTTP": {
            "PathPrefix": "/mycompany.BillingService/"
          }
        }
      ]
    }
  ]
}

L4 and L7

In the following example, Consul enforces application layer intentions that deny requests to api from hackathon-project but allow requests from web. In the same configuration entry, Consul enforces network layer intentions that allow requests from nightly-reconciler that send POST requests to the /v1/reconcile-data HTTP endpoint:

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"]
        }
      }
    ]
  },
  # A default catch-all based on the default ACL policy applies to
  # unmatched connections and requests. This is typically DENY.
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: api
spec:
  destination:
    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']
    # A default catch-all based on the default ACL policy applies to
    # unmatched connections and requests. This is typically DENY.

{
  "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"]
          }
        }
      ]
    }
  ]
}

Cluster peering

When using cluster peering connections, intentions secure your deployments with authorized service-to-service communication between remote datacenters. In the following example, the service intentions configuration entry authorizes the backend-service to communicate with the frontend-service that is hosted on remote peer cluster-02:

Kind      = "service-intentions"
Name      = "backend-service"

Sources = [
  {
    Name   = "frontend-service"
    Peer   = "cluster-02"
    Action = "allow"
  }
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: backend-deny
spec:
  destination:
    name: backend
  sources:
   - name: "*"
     action: deny
   - name: frontend
     action: allow
     peer: cluster-01 ## The peer of the source service

Service intentions configuration entry reference

Configuration model

Complete configuration

Specification

Kind

Values

Name

Values

Namespace EnterpriseEnterprise

Values

Partition EnterpriseEnterprise

Values

Meta

Values

Sources[]

Values

Sources[].Name

Values

Sources[].Peer

Values

Sources[].Namespace EnterpriseEnterprise

Values

Sources[].Partition EnterpriseEnterprise

Values

Sources[].Action

Values

Sources[].Permissions[]

Values

Sources[].Permissions[].Action

Values

Sources[].Permissions[].HTTP

Values

Sources[].Permissions[].HTTP[].Header[]

Values

Sources[].Precedence

Sources[].Type

Values

Sources[].Description

Values

Sources[].LegacyID

Sources[].LegacyMeta

Sources[].CreateTime

Sources[].LegacyUpdateTime

Examples

L4 Intentions for specific sources and destinations

L4 intentions for all destinations

L4 intentions for all sources

REST access

gRPC

L4 and L7

Cluster peering

`Kind`

`Name`

`Namespace` Enterprise

`Partition` Enterprise

`Meta`

`Sources[]`

`Sources[].Name`

`Sources[].Peer`

`Sources[].Namespace` Enterprise

`Sources[].Partition` Enterprise

`Sources[].Action`

`Sources[].Permissions[]`

`Sources[].Permissions[].Action`

`Sources[].Permissions[].HTTP`

`Sources[].Permissions[].HTTP[].Header[]`

`Sources[].Precedence`

`Sources[].Type`

`Sources[].Description`

`Sources[].LegacyID`

`Sources[].LegacyMeta`

`Sources[].CreateTime`

`Sources[].LegacyUpdateTime`