Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt

Use this file to discover all available pages before exploring further.

Consul Intentions define authorization rules for service-to-service communication. They control which services can connect to each other, supporting both simple allow/deny rules (L4) and advanced HTTP-based rules (L7).

​
Key Concepts

L4 Intentions

Simple allow or deny rules at the network layer. Control whether connections are permitted.

L7 Intentions

HTTP-level rules with path, method, and header matching for fine-grained access control.

Precedence

More specific intentions take priority. Exact matches override wildcards.

Default Deny

Without intentions, all service communication is denied by default in Consul Connect.

​
Required Permissions

ActionPermission
View intentionsiam:project:cicd:consul:read
Create/Update intentionsiam:project:cicd:consul:write
Delete intentionsiam:project:cicd:consul:delete

​
L4 vs L7 Intentions

TypeUse CaseFeatures
L4 (Allow/Deny)Basic access controlSimple allow or deny decision
L7 (HTTP Rules)API-level controlPath matching, HTTP methods, header conditions
L7 intentions require the destination service to use HTTP protocol. Services configured for TCP cannot use L7 rules.

​
Namespace Defaults

When creating intentions, the following defaults apply:
  • Source Namespace: default
  • Destination Namespace: default
  • Source Type: consul
For Consul Enterprise users, specify namespaces explicitly when creating cross-namespace intentions.

​
How to Create an L4 Intention

1

Select Consul Instance

Choose the target Consul cluster from the dropdown.
2

Click Create Intention

Click the Create Intention button.
3

Select Source Service

Choose the service initiating the connection. Select * (All Services) to apply to all sources.
4

Select Destination Service

Choose the service receiving the connection.
5

Choose Action

Select Allow to permit connections or Deny to block them.
6

Add Description (Optional)

Describe the purpose of this intention for documentation.
7

Create

Click Create Intention to apply the rule.

​
How to Create an L7 Intention

L7 intentions provide HTTP-level access control with path, method, and header matching.
1

Start Creating Intention

Click Create Intention and select source and destination services.
2

Enable L7 Rules

Toggle L7 (HTTP) Rules to enable advanced matching.
3

Add Permission Rules

Click Add Rule to create HTTP-level conditions:
  • Action: Allow or Deny for this specific rule
  • Path Match: Exact path, prefix, or regex pattern
  • HTTP Methods: Restrict to specific methods (GET, POST, etc.)
  • Headers: Match on header presence or values
4

Configure Path Matching (Optional)

Choose a path match type:
  • Exact: Matches /api/v1/users exactly
  • Prefix: Matches /api/v1/ and all subpaths
  • Regex: Pattern matching like /api/v[0-9]+/.*
5

Select HTTP Methods (Optional)

Click methods to allow only specific HTTP verbs (GET, POST, PUT, DELETE, etc.). Leave empty to allow all methods.
6

Add Header Rules (Optional)

Click Add Header to match on HTTP headers:
  • Is Present: Header exists
  • Exact Match: Header equals specific value
  • Prefix/Suffix: Header starts/ends with value
  • Contains: Header includes substring
  • Regex: Pattern matching
Options:
  • Ignore case: Case-insensitive matching
  • Invert match: Negate the condition
7

Add More Rules

Add additional rules as needed. Rules are evaluated in order; first match wins.
8

Create

Click Create Intention to apply the rules.
L7 intentions require your services to be configured with HTTP protocol in Consul Connect. TCP services cannot use L7 rules.

​
How to Edit an Intention

1

Find the Intention

Locate the intention in the table using search or scrolling.
2

Open Actions Menu

Click the three-dot menu on the intention row.
3

Select Edit

Click Edit to open the intention editor.
4

Modify Settings

Update the action, L7 rules, or description. Source and destination cannot be changed.
5

Save

Click Update Intention to apply changes.
To change source or destination, delete the intention and create a new one.

​
How to Delete an Intention

1

Find the Intention

Locate the intention in the table.
2

Open Actions Menu

Click the three-dot menu.
3

Select Delete

Click Delete and confirm the action.
Deleting an intention immediately affects service communication. Ensure no critical traffic depends on this rule.

​
Using Wildcards

The wildcard (*) matches all services:
SourceDestinationMeaning
*apiAll services can connect to api
web*web can connect to all services
**Universal allow/deny (use with caution)
Wildcard intentions have lower precedence than specific intentions. A specific deny will override a wildcard allow.

​
Common L7 Patterns

​
Allow Only GET Requests

Path Match: None
Methods: GET
Action: Allow

​
Protect Admin Endpoints

Path Match: Prefix /admin
Methods: All
Action: Deny

​
Version-Specific API Access

Path Match: Regex /api/v[12]/.*
Methods: GET, POST
Action: Allow

​
Header-Based Authorization

Header: X-Service-Token
Match: Is Present
Action: Allow

​
Precedence Rules

Intentions are evaluated by specificity:
  1. Exact match beats wildcard
  2. Source-specific beats source-wildcard
  3. Destination-specific beats destination-wildcard
  4. Most recently created wins for equal specificity
Example precedence (highest to lowest):
  1. web → api (most specific)
  2. * → api (destination specific)
  3. web → * (source specific)
  4. * → * (least specific)

​
Troubleshooting

  • Check for a more specific Deny intention that takes precedence
  • Verify both services are registered in Consul
  • Ensure services are using Consul Connect (sidecar proxies)
  • Check namespace if using Consul Enterprise
  • Verify the destination service protocol is HTTP, not TCP
  • Check path patterns for typos
  • Ensure regex patterns are valid
  • Rules evaluate in order; check if an earlier rule matches
  • You need write permission for Consul intentions
  • An intention for this source/destination pair may already exist
  • Verify the Consul instance is healthy
  • Refresh the page or click the refresh button
  • Verify you’re viewing the correct Consul instance
  • Check that the creation was successful (look for error messages)
  • Header names are case-insensitive by default
  • Check if “Invert match” is accidentally enabled
  • Verify the header is being sent by the client
  • Test with simpler rules first, then add complexity

​
FAQ

L4 intentions make a simple allow/deny decision at the connection level. L7 intentions inspect HTTP traffic and can make decisions based on paths, methods, and headers. Use L4 for basic access control, L7 for API-level security.
Yes. Add multiple permission rules to a single intention. Rules are evaluated in order, and the first matching rule determines access. If no rules match, the connection is denied.
Yes, with Consul Enterprise. Specify the namespace when creating the intention. The format is service.namespace. Community edition uses a single default namespace.
Create a * → * Allow intention. This has the lowest precedence, so any specific Deny intentions will still block traffic. Remove it when troubleshooting is complete.
No. Service names must be exact matches or the wildcard (*). Use tags or metadata in service definitions for more complex matching scenarios.
Default behavior depends on your Consul ACL configuration. With ACLs enabled in default-deny mode, connections are blocked. Without ACLs or in default-allow mode, connections are permitted.
Yes. Intention changes propagate to Envoy sidecars within seconds. No service restart is required.

​
Best Practices

​
Start Restrictive

Begin with deny-all and explicitly allow required communication:
  1. Create * → * Deny intention
  2. Add specific Allow intentions for each required connection

​
Document Intentions

Use the description field to explain:
  • Why this intention exists
  • Who requested it
  • Related ticket or change request

​
Use L7 for APIs

For HTTP services, use L7 intentions to:
  • Restrict write operations (POST, PUT, DELETE)
  • Protect admin endpoints
  • Enforce API versioning

​
Regular Review

Periodically audit intentions:
  • Remove intentions for decommissioned services
  • Verify intentions match current architecture
  • Check for overly permissive wildcards