Service Intentions Configuration Entry

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

The service-intentions config entry kind (ServiceIntentions on Kubernetes) 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 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 config entry or globally via proxy-defaults .

Sample Config Entries

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

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 use-case, access to the IssueRefund gRPC service method is set to deny. Because gRPC method calls are HTTP/2, an HTTP path-matching rule can be used 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/"
        }
      }
    ]
  }
  # 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: 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/'
    # 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": "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

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

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

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']
    # 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": "hackathon-project",
      "Action": "deny"
    },
    {
      "Name": "web",
      "Action": "allow"
    },
    {
      "Name": "nightly-reconciler",
      "Permissions": [
        {
          "Action": "allow",
          "HTTP": {
            "PathExact": "/v1/reconcile-data",
            "Methods": ["POST"]
          }
        }
      ]
    }
  ]
}

Available Fields

Kind - Must be set to service-intentions
Name (string: <required>) - The name of the destination service for 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. Wildcard intentions cannot be used when defining L7 Permissions.
Namespace (string: "default")Enterprise - Specifies the namespaces 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. Wildcard intentions cannot be used when defining L7 Permissions.
Partition (string: "default")Enterprise - Specifies the admin partition on which the configuration entry will apply. Wildcard characters (*) are not supported. Admin partitions must specified explicitly.
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. 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.

apiVersion - Must be set to consul.hashicorp.com/v1alpha1
kind - Must be set to ServiceIntentions
metadata
- name - Unlike other config entries, the metadata.name field is not used to set the name of the service being configured. Instead, that is set in spec.destination.name. Thus this name can be set to anything. See ServiceIntentions Special Case (OSS) or ServiceIntentions Special Case (Enterprise) for more details.
- namespace - If running Consul Open Source, the namespace is ignored (see Kubernetes Namespaces in Consul OSS). If running Consul Enterprise see Kubernetes Namespaces in Consul Enterprise for more details.
spec
- destination
  - name (string: <required>) - The name of the destination service for 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. Wildcard intentions cannot be used when defining L7 Permissions.
  - namespace (string: <optional>)Enterprise - Specifies the namespaces 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. If not set, the namespace used will depend on the connectInject.consulNamespaces configuration. See ServiceIntentions Special Case (Enterprise) for more details. Wildcard intentions cannot be used when defining L7 Permissions.
- sources (array<SourceIntention>) - The list of all intention sources and the authorization granted to those sources. 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.
Peer (string: "") - Specifies the peer of the source service. Peer is mutually exclusive with Partition.
Namespace (string: "")Enterprise - The namespace of the source service. If Peer is empty, Namespace defaults to the namespace of the destination service (i.e. the config entry's namespace).
Partition (string: "")Enterprise - Specifies the admin partition of the source service. If Peer is empty, Partition defaults to the destination service's partition (i.e. the configuration entry's partition). Partition is mutually exclusive with Peer.
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 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.

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

Setting Permissions is not valid if a wildcard is used for the Name or Namespace because they can only be applied to services with a compatible protocol.
Precedence (int: <read-only>) - An integer precedence value computed from the source and destination naming components.
Type (string: "consul") - 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 endpoints to continue to function for a period of time after upgrading to 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 endpoints to continue to function for a period of time after upgrading to 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 endpoints to continue to function for a period of time after upgrading to 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 endpoints to continue to function for a period of time after upgrading to 1.9.0.

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.
peer (string: "") - Specifies the peer of the source service. peer is mutually exclusive with partition.
namespace (string: "")Enterprise - The namespace of the source service. If peer is empty, namespace defaults to the namespace of the destination service (i.e. spec.destination.namespace).
partition (string: "")Enterprise - Specifies the admin partition of the source service. If peer is empty, partition defaults to the destination service's partition (i.e. spec.destination.partition). partition is mutually exclusive with peer.
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 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.

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

Setting permissions is not valid if a wildcard is used for the spec.destination.name or spec.destination.namespace because they can only be applied to services with a compatible protocol.
type (string: "consul") - 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.

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

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.

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.
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.
  
  At most only one of Exact, Prefix, Suffix, Regex, or Present may be configured.
- Invert (bool: false) - Inverts the logic of the match

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.

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

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 for more details.

Regular Expression Syntax

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

When using Envoy as a proxy, the syntax for these fields is RE2.