# Attach and detach a floating IP

> Point a floating IP at an instance or a server, move it to another one, or take it off.

Source: https://docs.coritan.com/floating-ips/attach-and-detach/

In the dashboard:

- /dashboard/networking/ips/…/attach: https://www.coritan.com/dashboard/networking/ips

Attach a floating IP to a Cloud Compute instance or a Container Apps server to make it answer on the address. Detach it to take the address off again. The floating IP stays on your account either way, so you can attach it somewhere else later.

## Before you begin

- The floating IP must be active, which the list shows as `Attached` or `Unattached`. A suspended floating IP cannot be attached until you pay its invoice.
- You need an instance or a server on your account to attach it to.
- An instance sets up its addresses when it starts, so plan to restart it after you attach or detach an address.
- A server holds one floating IP, and attaching or detaching can restart a running server.

## Attach a single address

1. In the [dashboard](https://www.coritan.com/dashboard/networking), go to **Floating IPs**, open the address and select the **Attach** tab.
2. Under **Choose a target**, select an instance or a server. Each one shows its name, status and type, and says `already has a floating IP` when it holds one. With more than six targets, a search box lets you find one by name.
3. For an instance, choose the address's role:
   - Tick **Make it the primary address** to make it the instance's main address. The current primary address becomes an additional one.
   - Leave it unticked to add the address next to the current one.

   An instance with no address takes the first one you attach as its primary address, ticked or not.
4. If you hold a coritan.gg name, you can tick **Also give the address a name** and type a name under it, such as `vm.survival-smp.coritan.gg`. We create an `A` record for the name in that zone once the address is attached.
5. Select **Attach address**.

The message that confirms the attach also says what to do next.

On an instance, restart the instance from its header. The instance sets up the address when it starts, as [Start, stop and restart an instance](/cloud-compute/power/#restart-from-the-dashboard-to-apply-changes) explains, and a `reboot` typed inside the instance does not. An additional address gets a network interface of its own inside the instance, with no gateway.

On a server, the ports the server publishes move onto the address, and [join addresses](/proxies/join-addresses/) that point at the server follow it. For a Minecraft server, we also open the game's default ports on the address, `25565` for Java and `19132` for Bedrock, and make the matching one the server's main port, so players can connect with the address alone. A running server restarts only when the ports it uses change. The message says which applies:

- `The server restarts to bind the new address.`
- `The address answers right away; no restart needed.`
- `Applies when the server next starts.`

> [!NOTE]
> A single address costs nothing while it is an instance's primary address, and bills at its plan's price anywhere else. Choosing the primary address therefore also chooses which address you pay for, as [What a floating IP costs](/floating-ips/billing/#what-a-floating-ip-costs) explains.

## Attach a host of a subnet

Each host of a subnet attaches to one instance or server. You can attach the other hosts of the same subnet to other targets, one at a time.

1. Open the subnet and select the **Attach** tab. You can also open the **Hosts** tab, open a free host's actions menu and select **Attach**, which opens the tab with that host chosen.
2. Under **Choose a target**, select the instance or server.
3. Under **Host address**, choose a host, or leave **First free host** to take the lowest free one. The hint under the field says how many hosts are free.
4. Select the button under the form. It reads **Attach address**, or `Attach` followed by the host when you chose one.

Then restart the instance, or check the message for a server, as for a single address.

## Move a floating IP to another target

A single address attaches to one target at a time, so you move it by detaching it and attaching it again.

1. On the **Attach** tab, select **Detach…** on the **Currently attached** card, then select **Detach address**.
2. Under **Choose a target**, select the new instance or server, and select **Attach address**.
3. Restart the instance you attached the address to. Also restart the instance you took it from, so that it stops using the address.

The address keeps its reverse DNS and its DDoS Shield settings when it moves.

## Detach a floating IP

1. Open the floating IP and select **Detach…** in the header. On the **Attach** tab, the button is on the **Currently attached** card.
2. Read what the dialog says will stop working, then select **Detach address**.

To detach one host of a subnet, open the **Hosts** tab, open the host's actions menu and select **Detach…**.

On an instance, we take the address out of the instance's network settings. Restart the instance to apply the change. When the address was the primary one, the address that has been attached to the instance longest becomes the primary address. An instance with no address left has no public IPv4 address until you attach one.

On a server, the ports the server published on the address go back to the address it used before, and the ports we opened on the floating IP close. Players then connect with that address and its port again. A running server restarts when the ports it uses change, and the message after detaching says so.

The floating IP stays on your account, and we keep billing it until you [cancel it](/floating-ips/billing/).

## Result

The **Currently attached** card on the **Attach** tab shows the **Target**, its **Type** and **Since** when. On an instance, **Role** shows `Primary address` or `Additional address`. On a server, **Delivery** shows whether the address has reached the server's host. The list on the **IPs** tab shows the floating IP as `Attached`, and the address appears on the instance's **Network** tab.

After a detach, the list shows `Unattached`, and the **Overview** tab shows **Not attached to anything yet**.

## Troubleshooting

`Detach it first` under **Attach address**
: The address is attached to another target. Detach it, then attach it to the new one, as [Move a floating IP to another target](#move-a-floating-ip-to-another-target) describes.

A message that starts `IP is already attached to`
: The address is attached elsewhere. The message names the service it is attached to. Detach it there first.

`Container already has a primary floating IP; detach first`
: The server already has a floating IP. Detach that one first, or choose another server.

`Unsuspend the IP service before attaching`
: The floating IP is suspended, usually for an unpaid invoice, and a suspension also detaches it. [Pay the open invoice](/billing/invoices/), then attach it again.

`IP service must be active or suspended to attach`
: The floating IP is not ready yet. Wait until its order leaves the **Orders** tab.

`No free host in this block`
: Every usable host of the subnet is attached. Detach a host on the **Hosts** tab, or order another subnet.

`Address is reserved (network/broadcast/gateway) and cannot be attached`
: You chose the network, gateway or broadcast address of a subnet. Choose a usable host instead. [How subnets work](/floating-ips/subnets/) explains which addresses those are.

`Nothing to attach to`
: You have no instance or server on your account. Select **Order service** to order one.

A message that starts `This server's node`
: The server's host cannot take a floating IP yet, and nothing was attached. [Contact support](/support/conversations/) with the server's name.

A message that starts `Failed to program guest IP` or `Could not place the floating IP on the server's host`
: We could not set up the address on the target, and nothing was attached. Try again. If the message stays, [contact support](/support/conversations/).

`IP was attached by a concurrent request; refresh and try again`
: Another tab attached the address at the same moment. Reload the page to see where it went.

The address does not answer on an instance
: Restart the instance from its header. Addresses are set up when the instance starts from the dashboard, and a `reboot` typed inside the instance does not set them up.

**Last error** on the **Currently attached** card
: The address has not reached the server's host. Detach it and attach it again. If the error comes back, [contact support](/support/conversations/).

## Related

- [Manage an instance's addresses and names](/cloud-compute/networking/)
- [Set reverse DNS for a floating IP](/floating-ips/reverse-dns/)
- [How subnets work](/floating-ips/subnets/)
- [Cancel a floating IP](/floating-ips/billing/)
- [How join addresses work](/proxies/join-addresses/)

## With the API

`GET /api/v1/client/ips/attach-targets` lists the instances and servers on your account that you can attach a floating IP to.

```bash
curl https://api.coritan.com/api/v1/client/ips/attach-targets \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "items": [
    {"service_id": 118, "hostname": "vm.example.com", "module_name": "vps", "resource_id": 57, "resource_status": "running", "has_floating_ip": true},
    {"service_id": 131, "hostname": "survival-smp", "module_name": "container", "resource_id": null, "resource_status": "active", "has_floating_ip": false}
  ],
  "total": 2
}
```

`module_name` is `vps` for an instance and `container` for a server. `has_floating_ip` is `true` when the target already has a floating IP attached.

`POST /api/v1/client/ips/{service_id}/attach` attaches the floating IP whose service ID is in the path:

```bash
curl -X POST https://api.coritan.com/api/v1/client/ips/214/attach \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_type": "vps", "target_service_id": 118, "is_primary": false}'
```

| Field | Meaning |
| --- | --- |
| `target_type` | Required. `vps` for an instance, `container` for a server. |
| `target_service_id` | Required. The target's `service_id` from the list above. |
| `is_primary` | Instances only. `true` makes the address primary and `false` adds it next to the current one. Left out, the address becomes primary only when the instance has no address yet. |
| `host_address` | Subnets only. The host to attach. Leave it out to attach the lowest free host. |
| `host_inventory_id` | Subnets only. The host's `id` from the subnet's host list, in place of `host_address`. |

The response is the new attachment: its `address`, `target_type`, `target_service_id`, `is_primary` and `attached_at`. Attaching an address to the target it is already on returns the existing attachment. For a server, the response also carries `publish`:

- `requires_restart` is `true` when the server restarts to use the address.
- `reachable_now` is `true` when the address answers without a restart.
- `restart` is `not_needed`, `scheduled` or `pending`.

`POST /api/v1/client/ips/{service_id}/detach` detaches the floating IP. The body is optional. For a subnet with more than one host attached, send the `host_address` or `host_inventory_id` of the host to detach:

```bash
curl -X POST https://api.coritan.com/api/v1/client/ips/220/detach \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host_address": "203.0.113.18"}'
```

The response has `detached` set to `true` and the removed attachment under `previous`, plus `publish` for a server. A floating IP that is not attached answers the same way with `already_detached` set to `true` and `previous` set to `null`.

| Response | When |
| --- | --- |
| `404` | The floating IP, or the target service, is not on your account. |
| `409` with a message that starts `IP is already attached to` | The address is attached to another target. |
| `409` with `Container already has a primary floating IP; detach first` | The server already has a floating IP. |
| `409` with `Unsuspend the IP service before attaching` | The floating IP is suspended. |
| `409` with `No free hosts available in this subnet` | Every usable host of the subnet is attached. |
| `422` with `target_service_id must be a Cloud Compute service` or `target_service_id must be a container service` | `target_type` does not match the service. |
| `422` with `host_address / host_inventory_id only apply to subnet block services` | You sent a host for a single address. |
| `422` with `Subnet has multiple attached hosts; pass host_address to detach one` | A detach of a subnet named no host. |

The [Floating IPs API reference](/api/reference/client/floating-ips/#op-post-api-v1-client-ips-service-id-attach) lists every field.

## API

- `GET /api/v1/client/ips/attach-targets`: Thin list of owned compute services eligible as floating-IP attach targets (https://docs.coritan.com/api/reference/client/floating-ips/#op-get-api-v1-client-ips-attach-targets)
- `POST /api/v1/client/ips/{service_id}/attach`: Attach IP (https://docs.coritan.com/api/reference/client/floating-ips/#op-post-api-v1-client-ips-service-id-attach)
- `POST /api/v1/client/ips/{service_id}/detach`: Detach IP (or one subnet host) from its compute target; service remains on your account (https://docs.coritan.com/api/reference/client/floating-ips/#op-post-api-v1-client-ips-service-id-detach)