TrafficPermissions configuration reference

This page provides reference information for the TrafficPermissions resource, which authorizes east-west traffic between services within the service mesh. The traffic permissions CRD replaces the service intentions CRD when using the v2 catalog API. Refer to changes to Consul's existing architecture for more information.

This custom resource definition (CRD) describes a resource related to the Kubernetes GAMMA initiative that requires the v2 catalog API. It is not compatible with the v1 catalog API. For more information about GAMMA resources, refer to the Kubernetes Gateway API documentation.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in a traffic permissions CRD. Click on a property name to view additional details, including default values.

• apiVersion: string | required | must be set to auth.consul.hashicorp.com/v2beta1
• kind: string | required | must be set to TrafficPermissions
• metadata: map | required
  • name: string | required
  • namespace: string | optional EnterpriseEnterprise
• spec: map | required
  • destination: map
    • identityName: string
  • action: string
  • permissions: list of maps
    • sources: map
      • identityName: string
    • destinationRules:
      • portNames: array of strings

Complete configuration

When every field is defined, a traffic permissions CRD has the following form:

apiVersion: auth.consul.hashicorp.com/v2beta1    # required
kind: TrafficPermissions                         # required
metadata:
  name: <permissionsResourceName>
  namespace: <default>
spec:
  destination:
    identityName: <permissionsDestinationService>
  action: allow
  permissions:
    - sources:
      identityName: <sourceWorkloadIdentity> 
    destinationRules:
      portNames: 
        - <servicePortName>

Specification

This section provides details about the fields you can configure in the TrafficPermissions custom resource definition (CRD).

apiVersion

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

Values

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

kind

Specifies the type of CRD to implement. Must be set to TrafficPermissions.

Values

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

metadata

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

Values

• Default: None
• Data type: Map

metadata.name

Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the consul resource command. Refer to consul resource for more information.

Values

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

metadata.namespace EnterpriseEnterprise

Specifies the namespace that the service resolver applies to. Refer to namespaces for more information.

Values

• Default: None
• Data type: String

spec

Map that contains the details about the TrafficPermissions CRD. 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

Specifies the proxies of the services where these traffic permissions apply.

Values

• Default: None
• Data type: Map

spec.destination.identityName

Specifies the Workload identity for a service. The permissions you configure in this TrafficPermissions CRD apply to sidecar proxies when a request has this identity as their destination.

Values

• Default: None
• Data type: String

spec.action

Specifies whether the proxy should allow traffic or deny traffic between the destination in spec.destination and the sources in spec.permissions.sources.

By default, Consul allows traffic between all services. When the Helm value global.acls.manageSystemACLs is set to true, then Consul operates in "default-deny" mode. In this mode, TrafficPermissions CRDs that allow traffic between services are required for service-to-service traffic.

Values

• Default: None

• Data type: String that must contain one of the following values:

  • ACTION_ALLOW
  • ACTION_DENY

spec.permissions

Permissions is a list of the traffic permissions Consul evaluates requests against. When the list contains more than one permission, Consul follows OR semantics to select the permission.

Values

• Default: None
• Data type: List of maps

spec.permissions.sources

Lists sources for traffic in the permission. This block contains information Consul uses to evaluate the service that originated the request when the sidecar proxy authorizes incoming traffic.

To specify wildcard references in this block using *, omit all other fields. For example, you can apply traffic permissions to all namespaces using the wildcard, but you cannot specify an identity name, partition, peer, or sameness group in the same source.

Values

• Default: None
• Data type: Map

spec.permissions.sources.identityName

Specifies the Workload identity for the service that originates the request.

Values

• Default: None
• Data type: Map

spec.permissions.destinationRules

Specifies L7 properties to match against when Consul enforces traffic permissions.

When spec.action allows traffic, Consul authorizes requests to the destination service when the request matches one or more rules defined in this block. Requests that do not match any rules are denied.

When spec.action denies traffic, Consul denies authorization to requests that match one or more rules defined in this block. Requests that do not match any rules are allowed.

Values

• Default: None
• Data type: Map

spec.permissions.destinationRules.portNames

Specifies a port name that the Kubernetes Service exposes at the destination.

Values

• Default: None
• Data type: String

Examples

The following examples demonstrate common TrafficPermissions CRD configuration patterns for specific use cases.

Allow traffic to multiple ports

The following example configures traffic permissions to allow traffic when the web service makes a request to the api service on the api port or admin port.

apiVersion: auth.consul.hashicorp.com/v2beta1
kind: TrafficPermissions
metadata:
  name: api-allow-web-all
spec:
  destination:
    identityName: "api"
  action: ACTION_ALLOW
  permissions:
    - sources:
        - identityName: "web"
      destinationRules:
        - portNames: ["api", "admin"]

Deny traffic between a service and a specific port

The following example configures traffic permissions to deny traffic when the web service makes a request to the api service on the admin port.

apiVersion: auth.consul.hashicorp.com/v2beta1
kind: TrafficPermissions
metadata:
  name: web-to-admin-port-deny
spec:
  destination:
    identityName: api
  action: ACTION_DENY
  permissions:
    - sources:
        - identityName: web
      destinationRules:
        - portNames: ["admin"]