# Add or remove a target

Send a load balancer's traffic to an instance or an IP address, or stop sending it there.

A target is one of your instances (`server`) or an IP address (`ip`). Every target serves every
service of the load balancer, except on `application`, where a target serves its target group.
Replace _i-0123456789abcdef_ with your instance's id.

## Prerequisites

- Permission for `lb:AddTarget` to add a target, `lb:RemoveTarget` to remove one. They are
  separate, so someone can be allowed to take a broken backend out without being allowed to add
  new ones. Without `lb:AddTarget` the **Targets** tab says "Adding a target needs
  lb:AddTarget." in place of the button; without `lb:RemoveTarget` the rows have no remove
  control.
- In the console, also `lb:DescribeLoadBalancers` on the load balancer (without it its page
  answers 404), and `ec2:DescribeInstances` to pick an instance from the list.
- An instance in the load balancer's region. What else it needs depends on the type:

| Type                   | An instance target                                                                                                               | An IP target                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `lb11`, `lb21`, `lb31` | reached at its public address, or with `usePrivateIp` at its VPC address (the load balancer must have been created with `vpcId`) | any IPv4 address the load balancer can reach    |
| `application`          | needs a public IPv4 (in an organization whose load balancers run on its own hosts: reached at its site address instead)          | a public address that is not the platform's own |
| `dedicated`, public    | needs a public IPv4                                                                                                              | a public address that is not the platform's own |
| `dedicated`, private   | must be in the load balancer's VPC and have an address there                                                                     | inside the VPC's range                          |

On `application` the target joins a target group (`targetGroup`, default `default`). The other
types refuse any group but `default`. The console's **Add target** form has no private-address
option: add a `usePrivateIp` target with the CLI, API or Terraform.

## Add a target

**Console**
1. Open **Load balancers**, open the load balancer, then the **Targets** tab.
2. Choose **Add target**.
3. For **Target type**, choose **Instance** or **IP address**.
4. For **Instance**, pick the instance, or for **IP address**, enter the address. Instances the
   load balancer cannot use are greyed with the reason: terminated or being terminated, in
   another region, already a target (not on `application`, where one instance may serve several
   target groups), or without a public address (`application` only).
5. On `application`, (optional) for **Target group**, enter a group; empty means `default`.
6. Choose **Add**.

**CLI**
```sh
dcloud lb targets add lb-id --type server --instance-id i-0123456789abcdef \
  --use-private-ip
```

`--use-private-ip` only on `lb11`–`lb31` created in a VPC. An address: `--type ip --ip 192.0.2.10`.

**API**
```http
POST /lb/api/load-balancers/lb-id/targets
{ "type": "ip", "ip": "192.0.2.10" }
```

**Terraform**
```hcl
resource "dcloud_lb_target" "web" {
  load_balancer_id = dcloud_lb.web.id
  type             = "server"
  instance_id      = "i-0123456789abcdef"
}
```

The new target is in the **Targets** tab. On `application` and `dedicated` the fleet picks it up
within seconds; its status is `unknown` on `application` until the fleet has checked it. On
`lb11`–`lb31` it is registered at the provider in the background and its status is `healthy`.

### When adding is refused

- `400` `instanceId is required for server targets`, `400` `ip is required for ip targets`.
- `400` when the instance is in another region than the load balancer.
- `400` `usePrivateIp needs a load balancer in a VPC: create it with vpcId, or target the public address`
  on `lb11`–`lb31`; on `application`, `usePrivateIp` is always refused with `400`. On
  `dedicated` it is ignored: the scheme decides which address is used.
- `400` on `application` and public `dedicated` for an instance without a public IPv4 or an
  address that is not public; on private `dedicated` for an instance or address outside the VPC.
- `400` over 25 targets (`application`, `dedicated`) or 10 target groups (`application`), and for a
  target group on another type.
- `409` for a load balancer another service owns.

## Remove a target

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

**CLI**
```sh
dcloud lb targets remove lb-id target-id
```

**API**
```http
DELETE /lb/api/load-balancers/lb-id/targets/target-id
```

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

The answer is `200` with the target's `id`, also for a target id that does not exist. The
instance keeps running. `409` for a load balancer another service owns.

## Related

- [Add or remove a service](add-or-remove-a-service.md)
- [Health checks](health-checks.md)
- [Route requests by host and path](route-by-host-and-path.md)
