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

# Intentions

> Control service-to-service communication in your service mesh

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

<CardGroup cols={2}>
  <Card title="L4 Intentions" icon="layer-group">
    Simple allow or deny rules at the network layer. Control whether connections are permitted.
  </Card>

  <Card title="L7 Intentions" icon="code">
    HTTP-level rules with path, method, and header matching for fine-grained access control.
  </Card>

  <Card title="Precedence" icon="sort-amount-down">
    More specific intentions take priority. Exact matches override wildcards.
  </Card>

  <Card title="Default Deny" icon="ban">
    Without intentions, all service communication is denied by default in Consul Connect.
  </Card>
</CardGroup>

## Required Permissions

| Action                   | Permission                       |
| ------------------------ | -------------------------------- |
| View intentions          | `iam:project:cicd:consul:read`   |
| Create/Update intentions | `iam:project:cicd:consul:write`  |
| Delete intentions        | `iam:project:cicd:consul:delete` |

## L4 vs L7 Intentions

| Type                | Use Case             | Features                                       |
| ------------------- | -------------------- | ---------------------------------------------- |
| **L4 (Allow/Deny)** | Basic access control | Simple allow or deny decision                  |
| **L7 (HTTP Rules)** | API-level control    | Path matching, HTTP methods, header conditions |

<Info>
  L7 intentions require the destination service to use HTTP protocol. Services configured for TCP cannot use L7 rules.
</Info>

### Namespace Defaults

When creating intentions, the following defaults apply:

* **Source Namespace**: `default`
* **Destination Namespace**: `default`
* **Source Type**: `consul`

<Tip>
  For Consul Enterprise users, specify namespaces explicitly when creating cross-namespace intentions.
</Tip>

## How to Create an L4 Intention

<Steps>
  <Step title="Select Consul Instance">
    Choose the target Consul cluster from the dropdown.
  </Step>

  <Step title="Click Create Intention">
    Click the **Create Intention** button.
  </Step>

  <Step title="Select Source Service">
    Choose the service initiating the connection. Select `*` (All Services) to apply to all sources.
  </Step>

  <Step title="Select Destination Service">
    Choose the service receiving the connection.
  </Step>

  <Step title="Choose Action">
    Select **Allow** to permit connections or **Deny** to block them.
  </Step>

  <Step title="Add Description (Optional)">
    Describe the purpose of this intention for documentation.
  </Step>

  <Step title="Create">
    Click **Create Intention** to apply the rule.
  </Step>
</Steps>

## How to Create an L7 Intention

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

<Steps>
  <Step title="Start Creating Intention">
    Click **Create Intention** and select source and destination services.
  </Step>

  <Step title="Enable L7 Rules">
    Toggle **L7 (HTTP) Rules** to enable advanced matching.
  </Step>

  <Step title="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
  </Step>

  <Step title="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]+/.*`
  </Step>

  <Step title="Select HTTP Methods (Optional)">
    Click methods to allow only specific HTTP verbs (GET, POST, PUT, DELETE, etc.). Leave empty to allow all methods.
  </Step>

  <Step title="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
  </Step>

  <Step title="Add More Rules">
    Add additional rules as needed. Rules are evaluated in order; first match wins.
  </Step>

  <Step title="Create">
    Click **Create Intention** to apply the rules.
  </Step>
</Steps>

<Warning>
  L7 intentions require your services to be configured with HTTP protocol in Consul Connect. TCP services cannot use L7 rules.
</Warning>

## How to Edit an Intention

<Steps>
  <Step title="Find the Intention">
    Locate the intention in the table using search or scrolling.
  </Step>

  <Step title="Open Actions Menu">
    Click the three-dot menu on the intention row.
  </Step>

  <Step title="Select Edit">
    Click **Edit** to open the intention editor.
  </Step>

  <Step title="Modify Settings">
    Update the action, L7 rules, or description. Source and destination cannot be changed.
  </Step>

  <Step title="Save">
    Click **Update Intention** to apply changes.
  </Step>
</Steps>

<Tip>
  To change source or destination, delete the intention and create a new one.
</Tip>

## How to Delete an Intention

<Steps>
  <Step title="Find the Intention">
    Locate the intention in the table.
  </Step>

  <Step title="Open Actions Menu">
    Click the three-dot menu.
  </Step>

  <Step title="Select Delete">
    Click **Delete** and confirm the action.
  </Step>
</Steps>

<Warning>
  Deleting an intention immediately affects service communication. Ensure no critical traffic depends on this rule.
</Warning>

## Using Wildcards

The wildcard (`*`) matches all services:

| Source | Destination | Meaning                                 |
| ------ | ----------- | --------------------------------------- |
| `*`    | `api`       | All services can connect to `api`       |
| `web`  | `*`         | `web` can connect to all services       |
| `*`    | `*`         | Universal allow/deny (use with caution) |

<Warning>
  Wildcard intentions have lower precedence than specific intentions. A specific deny will override a wildcard allow.
</Warning>

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

<AccordionGroup>
  <Accordion title="Service cannot connect despite Allow intention" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="L7 rules not working" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot create intention" icon="circle-question">
    * You need write permission for Consul intentions
    * An intention for this source/destination pair may already exist
    * Verify the Consul instance is healthy
  </Accordion>

  <Accordion title="Intention not appearing after creation" icon="circle-question">
    * 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)
  </Accordion>

  <Accordion title="Header matching not working" icon="circle-question">
    * 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
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between L4 and L7 intentions?">
    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.
  </Accordion>

  <Accordion title="Can I have multiple L7 rules in one intention?">
    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.
  </Accordion>

  <Accordion title="Do intentions work across namespaces?">
    Yes, with Consul Enterprise. Specify the namespace when creating the intention. The format is `service.namespace`. Community edition uses a single default namespace.
  </Accordion>

  <Accordion title="How do I allow all traffic temporarily?">
    Create a `* → *` Allow intention. This has the lowest precedence, so any specific Deny intentions will still block traffic. Remove it when troubleshooting is complete.
  </Accordion>

  <Accordion title="Can I use regex for service names?">
    No. Service names must be exact matches or the wildcard (`*`). Use tags or metadata in service definitions for more complex matching scenarios.
  </Accordion>

  <Accordion title="What happens if no intention matches?">
    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.
  </Accordion>

  <Accordion title="Are intentions applied immediately?">
    Yes. Intention changes propagate to Envoy sidecars within seconds. No service restart is required.
  </Accordion>
</AccordionGroup>

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