Skip to content
StratumStratum Docs

Add a runtime floating IP pool (bootstrap-admin).

POST
/v1/network/floating-ip-pools
Code sample: Shell / cURL
curl --request POST \
  --url https://stratum.example.com/v1/network/floating-ip-pools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "cidr": "172.25.0.0/24", "region": "example" }'

Install-scope endpoint to add a new FIP pool after the install has come up. Inserts the pool row with source = runtime (so the DELETE endpoint will allow removing it later) and seeds the per-host available rows the allocator hands out.

Under routed-host topology, multiple CIDRs already “just work”: each pool sits on br-ex as a virtual subnet and the host MASQUERADEs all of them through the same upstream NIC. Under bridged topology, the install today carries a single provider VLAN; per-pool VLAN support is a separate ticket.

CIDR is required; region defaults to the install’s default region.

Refuses with 400 INVALID_INPUT if the CIDR overlaps an existing pool in the same region.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

body for POST /v1/network/floating-ip-pools.

object
cidr
required

CIDR for the new pool. Must not overlap any existing pool in the same region; 400 INVALID_INPUT on overlap.

string

Example 

172.25.0.0/24
region

Target region. Empty defaults to the install’s default region (configured by the bootstrap).

string

Responses

Section titled “Responses”

201

Section titled “201”

Created.

Media typeapplication/json
object
id
required

Pool identifier.

string
/^fip(p)?ool-[a-z0-9-]+$/
cidr
required

The CIDR the pool draws from.

string
source
required

origin marker. install pools are seeded by the bootstrap from STRATUM_NETWORK_FLOATING_IP_POOLS; they are protected from deletion via the runtime DELETE endpoint (409 INSTALL_POOL_PROTECTED) because the FIP allocator depends on at least one install-time pool being present on a fresh install. runtime pools are added via POST after install and freely deletable provided no FIPs are allocated against them. The UI uses this field to disable the delete button on install rows.

string
Allowed values: install runtime
region
required

Region the pool serves.

string
state
required
string
Allowed values: active draining
gatewayIp
required

First host IP of the pool CIDR — the address the operator must reserve on their upstream router under bridged topology. Empty when the CIDR can’t be parsed.

string format: ipv4
providerTopology

How the host wires br-ex into the upstream network. bridged means the operator owns the L2 segment + gateway; routed-host means the host MASQUERADEs out the upstream interface.

string
Allowed values: bridged routed-host
providerVlan

VLAN ID carrying the FIP CIDR under bridged topology. 0 = unset.

integer
<= 4094
upstreamInterface

Host NIC carrying upstream FIP traffic.

string
providerBridge

Host OVS bridge the provider LS localnet port maps to.

string
counts
required
object
total
required

Total FIP rows in the pool (every host IP minus skipped).

integer
available
required

Free to allocate.

integer
allocated
required

Held by a project (sum of allocated + associated FIP states both buckets represent “in use” to operators).

integer
reserved
required

Not free, not in use — covers releasing, released, error. Non-zero usually flags a stuck FIP worth investigating.

integer

Example 

{
  "cidr": "192.0.2.0/24",
  "source": "install",
  "state": "active",
  "providerTopology": "bridged"
}

400

Section titled “400”

Bad request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

403

Section titled “403”

Authenticated but not authorized.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}