# Add or remove a service

Make a load balancer listen on a port and forward to a port on its targets, or stop it listening there.

A service is one listener: a protocol, the port the load balancer listens on (source port) and
the port on each target it forwards to (destination port), with its health check. For `https`,
see [Serve HTTPS](serve-https.md).

## Prerequisites

- Permission for `lb:AddService` to add a service, `lb:DeleteService` to remove one. Without
  `lb:AddService` the **Services** tab says "Adding a service needs lb:AddService." in place of
  the button; without `lb:DeleteService` the rows have no delete control.
- In the console, also `lb:DescribeLoadBalancers` on the load balancer; without it its page
  answers 404.

What a service may be depends on the type:

| Type                   | Protocols        | Source ports                                | Other options                                                  |
| ---------------------- | ---------------- | ------------------------------------------- | -------------------------------------------------------------- |
| `lb11`, `lb21`, `lb31` | tcp, http, https | any                                         | `proxyprotocol`                                                |
| `application`          | http, https      | http on 80, https on 443 only               | none of `proxyprotocol`, `healthCheckPort`, `closeOnUnhealthy` |
| `dedicated`            | tcp, http, https | any but 22, 9901, 9902; at most 10 services | `proxyprotocol`, `healthCheckPort`, `closeOnUnhealthy` (tcp)   |

## Add a service

**Console**
1. Open **Load balancers**, open the load balancer, then the **Services** tab.
2. Choose **Add service**.
3. For **Protocol**, choose **TCP**, **HTTP** or **HTTPS**.
4. For **Source port** and **Destination port**, enter the ports. The form starts on 80 and 80;
   choosing **HTTPS** moves a source port of 80 to 443.
5. For HTTP and HTTPS, (optional) for **Health check path**, enter the path to probe.
6. Choose **Add**.

The form sets no other health-check or sticky-session setting; change those afterwards with the
CLI, API or Terraform.

**CLI**
```sh
dcloud lb services add lb-id --protocol tcp --source-port 5432 --destination-port 5432 \
  --health-check-protocol tcp --health-check-interval 5 --health-check-timeout 3
```

**API**
```http
POST /lb/api/load-balancers/lb-id/services
{ "protocol": "http", "sourcePort": 80, "destinationPort": 8080, "healthCheckPath": "/healthz" }
```

**Terraform**
```hcl
resource "dcloud_lb_service" "http" {
  load_balancer_id  = dcloud_lb.web.id
  protocol          = "http"
  source_port       = 80
  destination_port  = 8080
  health_check_path = "/healthz"
}
```

Changing the protocol or a port replaces the service.

The answer is `201` with the service and its health-check settings, defaults filled in. On
`application` and `dedicated` the fleet carries it within seconds; on `lb11`–`lb31` it is created
at the provider in the background, and a refusal there is recorded as an event on the load
balancer, not as an error of the call.

### When adding is refused

- `400` `This load balancer already has a service on port 80` (with the port you asked for).
- `400` `Port 80 is taken by the https service that redirects HTTP to HTTPS; remove that service or add one without the redirect`.
- `400` on `application` for `tcp`, for a port other than 80 (http) or 443 (https), or for
  `proxyprotocol`.
- `400` on `dedicated` for ports 22, 9901 and 9902, or over 10 services.
- `400` `healthCheckPort and closeOnUnhealthy are for dedicated load balancers`.
- `400` `closeOnUnhealthy is for tcp services (an http request ends by itself)`.
- `400` for health-check values out of range; see [Health checks](health-checks.md).
- `409` for a load balancer another service owns.

## Remove a service

**Console**
1. On the **Services** tab, on the service's row, choose the delete control (**Delete service**).
2. Choose **Delete**.

**CLI**
```sh
dcloud lb services delete lb-id service-id
```

**API**
```http
DELETE /lb/api/load-balancers/lb-id/services/service-id
```

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

The answer is `200` with the service's `id`, also for an id that does not exist. The listener
(and on `lb11`–`lb31` an uploaded certificate) is removed at the provider in the background.
`409` for a load balancer another service owns.

## Related

- [Serve HTTPS](serve-https.md)
- [Change a health check or sticky sessions](change-a-health-check.md)
- [Health checks](health-checks.md)
