Floating IPs

Floating IPs are permanent, project-scoped resources which bind an individual IP address from a given IP pool. They allow for well-known addresses to be allocated (explicitly or automatically) and assigned to target instances, making it easier to host services from a consistent address.

Floating IP Lifecycle

Floating IPs are created within a project, and take ownership of an IP address from an available IP pool for their lifetime. A floating IP may then be attached to an instance during its creation or using the floating_ip_attach endpoint, and detached when that same instance is destroyed or via the floating_ip_detach endpoint.

A floating IP must be detached from an instance before it can be either deleted or attached to another instance. Once deleted, the address held by a floating IP resource is released back into its original IP pool.

API endpoints

Creating and Attaching Floating IPs

Here are some example workflows for using floating IPs with VM instances. In the below examples we assume the default IP pool provides 192.168.32.1–192.168.32.254, and that a pool named alternate-pool provides 192.168.64.64–192.168.64.72.

Example 1: Create a floating IP

If neither an address or pool is specified, we are allocated the next available IP from the default pool:

oxide floating-ip create \
    --project cafe \
    --name rootbeer-float \
    --description "A classic."
Command output
{
  "description": "A classic.",
  "id": "..........<REDACTED_UUID>...........",
  "ip": "192.168.32.1",
  "ip_pool_id": "..........<REDACTED_UUID>...........",
  "name": "rootbeer-float",
  "project_id": "..........<REDACTED_UUID>...........",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>"
}

Example 2: Create a floating IP from a given pool

The above example shows how a floating IP takes the first free IP address within the default pool. We can instead choose any other pool visible from within the target project:

fip-explicit-pool.json
{
  "name": "cola-float",
  "description": "A favourite.",
  "address_allocator": {
    "type": "auto",
    "pool_selector": {
      "type": "explicit",
      "pool": "alternate-pool"
    }
  }
}
oxide floating-ip create \
    --project cafe \
    --json-body examples/fip-explicit-pool.json
Command output
{
  "description": "A favourite.",
  "id": "..........<REDACTED_UUID>...........",
  "ip": "192.168.64.64",
  "ip_pool_id": "..........<REDACTED_UUID>...........",
  "name": "cola-float",
  "project_id": "..........<REDACTED_UUID>...........",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>"
}

Example 3: Create a floating IP for a specific address

When allocating a floating IP for use by a given service, we often want to use a particular IP address. This can be specified during creation:

fip-explicit-ip.json
{
  "name": "affogato",
  "description": "A reverse float.",
  "address_allocator": {
    "type": "explicit",
    "ip": "192.168.32.32"
  }
}
oxide floating-ip create \
    --project cafe \
    --json-body examples/fip-explicit-ip.json
Command output
{
  "description": "A reverse float.",
  "id": "..........<REDACTED_UUID>...........",
  "ip": "192.168.32.32",
  "ip_pool_id": "..........<REDACTED_UUID>...........",
  "name": "affogato",
  "project_id": "..........<REDACTED_UUID>...........",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>"
}
Important
If a specific IP address is not present in the default pool, you must specify the correct pool name as in Example 2. For example, if you wanted to allocate 192.168.64.71, you must also specify --pool alternate-pool.

Example 4: Create an instance bound to one or more floating IPs

Now that we have allocated some floating IPs, we are ready to attach them to an instance within our project. floating IPs can be associated with an instance when it is being created:

instance-define.json
{
  "name": "menu",
  "description": "We serve floats!",
  "hostname": "menu-server",
  "memory": 1073741824,
  "ncpus": 1,
  "start": false,
  "network_interfaces": {
    "type": "default_ipv4"
  },
  "external_ips": [
    { "type": "ephemeral" },
    { "type": "floating", "floating_ip": "cola-float" }
  ]
}
oxide instance create --project cafe --json-body examples/instance-define.json
Command output
{
  "auto_restart_enabled": true,
  "description": "We serve floats!",
  "hostname": "menu-server",
  "id": "..........<REDACTED_UUID>...........",
  "memory": 1073741824,
  "name": "menu",
  "ncpus": 1,
  "project_id": "..........<REDACTED_UUID>...........",
  "run_state": "stopped",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>",
  "time_run_state_updated": "<REDACTED_TIMESTAMP>"
}

This command creates an instance with a new ephemeral IP and attaches one of the above floating IPs. Once the instance is deleted, these will be detached and the floating IP will be available for reuse.

Tip
Multiple floating IPs (and a single ephemeral IP) can be attached to a given instance. This allows a host to send and receive VPC-external traffic on several addresses. See the 'Networking' guide for the exact semantics.

Example 5: View and list floating IPs

Floating IPs can be viewed on an individual basis:

oxide floating-ip view --project cafe --floating-ip cola-float
Command output
{
  "description": "A favourite.",
  "id": "..........<REDACTED_UUID>...........",
  "instance_id": "..........<REDACTED_UUID>...........",
  "ip": "192.168.64.64",
  "ip_pool_id": "..........<REDACTED_UUID>...........",
  "name": "cola-float",
  "project_id": "..........<REDACTED_UUID>...........",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>"
}

Similarly, we can also view all floating IPs within a project using the command:

oxide floating-ip list --project cafe

Floating IPs retrieved either way show whether they are attached to an instance by their instance_id field.

Example 6: Delete a floating IP

To release a floating IP so that it may be reused elsewhere, we can delete the resource:

oxide floating-ip delete \
    --project cafe \
    --floating-ip affogato
Important
A floating IP can only be deleted once it has been detached from any instances. Deleting an IP with a non-null instance_id will return an HTTP 400 Bad Request.

Example 7: Attach and detach a floating IP from an existing instance

Floating IPs may be attached and detached from any instance which is started or stopped. To attach an address to an instance:

oxide floating-ip attach \
    --kind instance \
    --parent menu \
    --project cafe \
    --floating-ip rootbeer-float
Command output
{
  "description": "A classic.",
  "id": "..........<REDACTED_UUID>...........",
  "instance_id": "..........<REDACTED_UUID>...........",
  "ip": "192.168.32.1",
  "ip_pool_id": "..........<REDACTED_UUID>...........",
  "name": "rootbeer-float",
  "project_id": "..........<REDACTED_UUID>...........",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>"
}

And to detach a floating IP from an instance:

oxide floating-ip detach --project cafe --floating-ip cola-float
Command output
{
  "description": "A favourite.",
  "id": "..........<REDACTED_UUID>...........",
  "instance_id": null,
  "ip": "192.168.64.64",
  "ip_pool_id": "..........<REDACTED_UUID>...........",
  "name": "cola-float",
  "project_id": "..........<REDACTED_UUID>...........",
  "time_created": "<REDACTED_TIMESTAMP>",
  "time_modified": "<REDACTED_TIMESTAMP>"
}

cola-float is now ready to be reassigned to another instance, if desired. Ephemeral IPs can be configured in a similar manner:

oxide instance external-ip detach-ephemeral \
    --instance menu \
    --project cafe
Command output
oxide instance external-ip attach-ephemeral \
    --instance menu \
    --project cafe
{
  "kind": "ephemeral",
  "ip": "192.168.32.3",
  "ip_pool_id": "..........<REDACTED_UUID>..........."
}