Title here
Summary here
This page documents a version of Oakestra which is not the latest stable. Please refer to the latest docs for a current version.
Retrieve Available Service IPs
Oakestra provides a mechanism to query the System Manager for available Service IPs (IPv4 and IPv6) to avoid address collisions during manual service deployments or addon creation.Overview
When developing addons (e.g., FLOps) or deploying custom services, assigning a static Service IP usually involves guessing an available address or performing calculations on hashes. This approach is error-prone and can lead to IP collisions within the cluster.
The Network Information API exposes an endpoint to “ask” Oakestra for valid, currently unoccupied Service IPs.
Single Source of Truth
Using this endpoint is the recommended way to acquire Service IPs. It minimizes collisions by checking the centralized database of occupied addresses instead of relying on client-side randomization.
Endpoint Definition
The endpoint is part of the pubnet API blueprint.
Method: GET
Path: http://<root-orchestrator-ip>:10099/api/pubnet/service/netinfo/available-ip/{x}
Parameters
| Parameter | Type | In | Description | Default |
|---|---|---|---|---|
x | integer | Path | The number of IP addresses to retrieve. | 1 |
v | string | Query | IP version filter. Values: "4" (IPv4), "6" (IPv6). If omitted, both are returned. | None (Both) |
Important: No Reservation
This endpoint returns the next available IP addresses but does not reserve them in the system. It is a read-only operation intended to suggest valid IPs for immediate use. If multiple clients query this endpoint simultaneously without using the IPs, they might receive the same addresses.
Usage Examples
You can retrieve a single IP, multiple IPs, or filter by version using the query parameters.
1. Retrieve a single available IP (IPv4 & IPv6)
Call the endpoint without specifying x to get one available address for both versions (if available).
Request & Response
Request:
GET http://<root-orchestrator-ip>:10099/api/pubnet/service/netinfo/available-ip
Authorization: Bearer <your-jwt-token>Response:
{
"available_service_ips": [
"10.30.0.5",
"fdff:0:0:0:0:0:0:5"
]
}2. Retrieve multiple IPv4 addresses
Specify the number of IPs in the path and filter by version v=4.
Request & Response
Request:
GET http://<root-orchestrator-ip>:10099/api/pubnet/service/netinfo/available-ip/3?v=4
Authorization: Bearer <your-jwt-token>Response:
{
"available_service_ips": [
"10.30.0.12",
"10.30.0.13",
"10.30.0.14"
]
}3. Retrieve multiple IPv6 addresses
Filter by version Request: Response:v=6.Request & Response
GET http://<root-orchestrator-ip>:10099/api/pubnet/service/netinfo/available-ip/2?v=6
Authorization: Bearer <your-jwt-token>{
"available_service_ips": [
"fdff:0:0:0:0:0:0:a1",
"fdff:0:0:0:0:0:0:a2"
]
}