# Route requests by host and path

On an application load balancer, send requests for a host name or path prefix to their own target group.

Rules exist on `application` load balancers only. Each rule forwards requests that match its host,
its path prefix or both to one target group. Replace _api_ with your group's name.

## How rules are applied

- Rules are checked lowest `priority` first (1–1000, one rule per priority); the first that
  matches wins. A request no rule matches goes to the `default` group.
- `host` must be one of the load balancer's own names: its platform name, or a name of its https
  service (a name under a wildcard it serves counts). Left out, the rule applies to every name.
- `pathPrefix` matches whole path segments: `/api` matches `/api`, `/api/` and `/api/v1`, not
  `/apix`. The path reaches the target unchanged.
- Rules apply to the `http` and `https` services alike, each with its own destination port and
  health check.
- A rule whose group has no target answers `503`; it never falls through to another group. The
  load balancer's page warns about it, and so does `application.warnings` in the API.
- A rule cannot be changed: remove it and add it again. Changes reach the fleet within seconds.

## Prerequisites

- An `application` load balancer.
- Permission for `lb:AddRule` to add a rule, `lb:RemoveRule` to remove one, and `lb:AddTarget` to
  put targets in a group.
- In the console, also `lb:DescribeLoadBalancers` on the load balancer; without it its page
  answers 404. The **Rules** tab exists for `application` load balancers only.

## Step 1: Put targets in the group

A target joins a group when it is added; see [Add or remove a target](add-or-remove-a-target.md).
In the console, enter the group under **Target group** in **Add target**.

```sh
dcloud lb targets add lb-id --type ip --ip 192.0.2.11 --target-group api
```

## Step 2: Add the rule

**Console**
1. Open the load balancer, then the **Rules** tab.
2. Choose **Add rule**.
3. For **Priority**, keep the suggested value (10, then 10 above the highest) or enter another.
4. (Optional) For **Host**, enter one of the load balancer's names.
5. (Optional) For **Path prefix**, enter a prefix such as `/api`.
6. For **Target group**, enter api.
7. Choose **Add**.

A rule needs a host, a path prefix or both. The table lists the rules by priority and, last, the
`default` group for everything else.

**CLI**
```sh
dcloud lb rules add lb-id --priority 10 --path-prefix /api --target-group api
```

**API**
```http
POST /lb/api/load-balancers/lb-id/rules
{ "priority": 10, "pathPrefix": "/api", "targetGroup": "api" }
```

**Terraform**
```hcl
resource "dcloud_lb_rule" "api" {
  load_balancer_id = dcloud_lb.web.id
  priority         = 10
  path_prefix      = "/api"
  target_group     = "api"
}
```

Any change replaces the rule.

`201` with the rule, its `host` lower-cased.

### When adding is refused

- `400` `A rule needs a host, a pathPrefix or both (the default group already takes the rest)`.
- `400` on a type other than `application`.
- `400` `Priority 10 is taken: each rule of a load balancer has its own` (with your priority), or
  `409` `Priority 10 is taken` when another request took it at the same moment.
- `400` for a host that is not one of the load balancer's names; the message lists its names.
- `400` `An application load balancer has at most 50 rules`, or at most 10 target groups.

## Remove a rule

**Console**
1. On the **Rules** tab, on the rule's row, choose the remove control (**Remove rule**).
2. Choose **Delete**.

**CLI**
```sh
dcloud lb rules remove lb-id rule-id
```

**API**
```http
DELETE /lb/api/load-balancers/lb-id/rules/rule-id
```

**Terraform**
Remove the `dcloud_lb_rule` resource and apply.

Requests the rule matched go to the next matching rule, or the `default` group. `404`
`Rule not found` when the rule is not on this load balancer.

## Related

- [Add or remove a target](add-or-remove-a-target.md)
- [Serve HTTPS](serve-https.md)
- [Protect an application load balancer with a web ACL](protect-with-a-web-acl.md)
