# Create a load balancer

Create a load balancer of one of the five types in a region, public or, for the network and dedicated types, attached to a VPC.

A new load balancer has no services and no targets: it carries traffic once you add both. Replace
_web-lb_ with your name and _de1_ with the region of the instances it will serve; a load balancer
reaches targets of its own region only.

**Important:**
The type, algorithm, region, VPC and, for `dedicated`, the scheme are fixed at creation. You pay
for the load balancer per hour from when it exists (`lb11`–`lb31`) or is active
(`application`, `dedicated`) until you delete it.

## Prerequisites

- Permission for `lb:CreateLoadBalancer`.
- Room in the `lb.load-balancers` quota of the region.
- Any tag keys your organization requires.
- For a private `dedicated` load balancer, a VPC in the region that already has an instance or a
  database in it.
- To attach a web ACL at creation (`application`, CLI, API or Terraform), also `lb:SetWebAcl`,
  and `waf:GetWebAcl` on the ACL.
- In the console, also `lb:DescribeLoadBalancers` to open **Load balancers**; without it the page
  says you do not have permission to view load balancers. For a private `dedicated` load
  balancer, also `ec2:DescribeVpcs`, which fills the **VPC** list. Without
  `lb:CreateLoadBalancer`, **Create load balancer** stays off and the page says
  "Creating a load balancer needs lb:CreateLoadBalancer. Ask an administrator."

## Create it

**Console**
1. Open **Load balancers**, then choose **Create load balancer**.
2. For **Name**, enter web-lb.
3. For **Region**, choose the region.
4. For **Type**, choose the type. The form starts on `lb11`.
5. For a `dedicated` load balancer, for **Reachable from**, choose
   **Public: its own IPv4 and IPv6** or **Private: addresses in a VPC only**. For private, choose
   the **VPC**.
6. For **Algorithm**, keep **Round robin** or choose **Least connections**.
7. (Optional) Under **Tags**, add tags.
8. Choose **Create**.

The load balancer appears in the list as `provisioning`. The console cannot attach an `lb11`,
`lb21` or `lb31` to a VPC; use the CLI, API or Terraform for that.

**CLI**
```sh
dcloud lb load-balancers create --name web-lb --type lb11 --region-id de1 \
  --algorithm least_connections
```

A private dedicated load balancer:

```sh
dcloud lb load-balancers create --name internal-lb --type dedicated --scheme private \
  --vpc-id vpc-id --region-id de1
```

**API**
```http
POST /lb/api/load-balancers
{ "name": "web-lb", "type": "lb11", "algorithm": "round_robin", "regionId": "de1" }
```

The answer is `201` with the load balancer, its `status` `provisioning`. Its addresses are filled
in once it is placed; read it with `GET /lb/api/load-balancers/{id}`.

**Terraform**
```hcl
resource "dcloud_lb" "web" {
  name      = "web-lb"
  type      = "lb11"
  algorithm = "round_robin"
  region_id = "de1"
}
```

Changing `name`, `type`, `algorithm`, `region_id`, `scheme` or `vpc_id` replaces the load
balancer.

## Options by type

| Field       | `lb11`, `lb21`, `lb31`                         | `application` | `dedicated`                                            |
| ----------- | ---------------------------------------------- | ------------- | ------------------------------------------------------ |
| `vpcId`     | optional: join the VPC's network               | refused (400) | required with `scheme: "private"`, refused with public |
| `scheme`    | refused (400)                                  | refused (400) | `public` (default) or `private`                        |
| `webAclId`  | refused (400)                                  | optional      | refused (400)                                          |
| `algorithm` | `round_robin` (default) or `least_connections` | same          | same                                                   |

## Result

The status goes from `provisioning` to `active` once the load balancer has its addresses (or, on
the fleet, is placed). An `application` or `dedicated` load balancer also gets a name,
`hostname`. If creation fails, the status is `error` and the reason is shown on its page as
**Provisioning failed.**

## When it is refused

- `400` `scheme is for type "dedicated" only`.
- `400` `A private load balancer lives in a VPC: give vpcId`.
- `400` for `vpcId` on an `application` load balancer, or on a public `dedicated` one.
- `404` `Region not found`, `404` `VPC not found`; `400` when the VPC is in another region.
- `409` when the region's load balancer quota is used up; the message starts with
  `Quota exceeded:`.
- `409` for a private `dedicated` load balancer whose VPC has no network yet, or whose VPC already
  holds 5 load balancer address pairs.
- `409` with the code `provider_unsupported` for any type but `application` in an organization
  whose load balancers run on its own hosts.
- For `webAclId`: `400` on any type but `application`, `404` for an ACL that is not your
  organization's, `403` without `waf:GetWebAcl` on it.

## Related

- [Load balancer types](load-balancer-types.md)
- [Add or remove a service](add-or-remove-a-service.md)
- [Add or remove a target](add-or-remove-a-target.md)
- [Quotas](quotas.md)
