Documentation Reference REST API reference API: ip-pools Reference For: developers
API: ip-pools
Operations of the ip-pools tag of the native REST API.
Public IP pools on host-bridge networks, address allocation bound to VM NICs, reverse DNS (L-127)
GET /v1/ip-poolsLists IP pools (those whose network the caller may configure).
CLI kyvernon ip-pools listResponses
POST /v1/ip-poolsCreates an IP pool on a host-bridge network.
CLI kyvernon ip-pools create --name <name> --network <network> --prefix-len <n> --range <range>Request body
application/json: IpPoolRequest
Name Type Required Description addressesarray of string Single IPv4 addresses (a provider's on-link addresses), besides or instead of ranges. dnsServersarray of string DNS servers; empty: the network's. expectedVersioninteger (int64) or nullRequired on update: the version read. gatewaystring or nullGateway. ipv6PoolIpv6Viewnullnamestringyes Name, unique. networkstringyes The host-bridge network id (network-N). prefixLeninteger (int32)yes Prefix length of the IPv4 subnet. quarantineSinteger (int64) or nullQuarantine of released addresses in seconds (default 14 days). rangesarray of RangeView IPv4 ranges. rdnsRdnsModenullreservedarray of string Addresses never handed out. smtpIpv4SmtpPolicynullsmtpIpv6SmtpPolicynull
Responses
Status Description Schema 201 Created IpPoolView400 Invalid argument; the error body names the field ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody
GET /v1/ip-pools/{id}Reads an IP pool.
CLI kyvernon ip-pools get <id>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N)
Responses
PUT /v1/ip-pools/{id}Changes an IP pool (compare-and-set on expectedVersion); allocations are kept.
CLI kyvernon ip-pools update <id> --version <version> --name <name> --network <network> --prefix-len <n> --range <range>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N)
Request body
application/json: IpPoolRequest
Name Type Required Description addressesarray of string Single IPv4 addresses (a provider's on-link addresses), besides or instead of ranges. dnsServersarray of string DNS servers; empty: the network's. expectedVersioninteger (int64) or nullRequired on update: the version read. gatewaystring or nullGateway. ipv6PoolIpv6Viewnullnamestringyes Name, unique. networkstringyes The host-bridge network id (network-N). prefixLeninteger (int32)yes Prefix length of the IPv4 subnet. quarantineSinteger (int64) or nullQuarantine of released addresses in seconds (default 14 days). rangesarray of RangeView IPv4 ranges. rdnsRdnsModenullreservedarray of string Addresses never handed out. smtpIpv4SmtpPolicynullsmtpIpv6SmtpPolicynull
Responses
Status Description Schema 200 OK IpPoolView400 Invalid argument; the error body names the field ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody
DELETE /v1/ip-pools/{id}Deletes an IP pool without allocations.
CLI kyvernon ip-pools delete <id>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N)
Responses
Status Description Schema 204 Done; no body 412 Failed precondition; the error body says which ErrorBody
GET /v1/ip-pools/{id}/allocationsLists the allocated and quarantined addresses of a pool.
CLI kyvernon ip-pools allocations <id>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N)
Responses
POST /v1/ip-pools/{id}/allocationsAllocates an address (or a /64) and binds it to a VM NIC. A named address that another caller took first fails with error.ip_pool.address_in_use (409), one in quarantine with error.ip_pool.address_quarantined (412).
CLI kyvernon ip-pools allocate <id>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N)
Request body
application/json: AllocateBody
Name Type Required Description addressstring or nullA specific IPv4 address. familystring or nullipv4 (default) or ipv6 (a /64).macstring or nullNIC MAC (absent: the VM's first NIC on the pool's network). referencestring or nullCaller reference. rolestring or nullprimary (default) or extra.tenantstring or nullTenant (quota). vmstring or nullVM to bind to (absent: reserved for the tenant).
Responses
Status Description Schema 201 Created AllocationView400 Invalid argument; the error body names the field ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody412 Failed precondition; the error body says which ErrorBody
DELETE /v1/ip-pools/{id}/allocations/{address}Returns an address (or prefix/64, URL-encoded) to the pool: into quarantine, PTR record deleted.
CLI kyvernon ip-pools free <id> <address>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N) addresspath stringyes Allocated address of the pool (an IPv6 block by its address)
Responses
Status Description Schema 204 Done; no body 404 Not found (or not visible to the caller) ErrorBody
PUT /v1/ip-pools/{id}/allocations/{address}/ptrSets or removes the PTR name of an allocated address (operator path).
CLI kyvernon ip-pools ptr <id> <address> [--name <name>]Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N) addresspath stringyes Allocated address of the pool (an IPv6 block by its address)
Request body
application/json: PtrBody
Name Type Required Description ptrstring or nullHost name; null or empty removes the record.
Responses
Status Description Schema 204 Done; no body 400 Invalid argument; the error body names the field ErrorBody412 Failed precondition; the error body says which ErrorBody503 Temporarily unavailable (not the leader, or the service is off) ErrorBody
POST /v1/ip-pools/{id}/allocations/{address}/ptr/appliedThe operator applied a manual PTR request (the name is in DNS, or a removal is done).
CLI kyvernon ip-pools ptr-applied <id> <address>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N) addresspath stringyes Allocated address of the pool (an IPv6 block by its address)
Responses
Status Description Schema 204 Done; no body 412 Failed precondition; the error body says which ErrorBody
POST /v1/ip-pools/{id}/allocations/{address}/ptr/rejectedThe operator could not apply a manual PTR request.
CLI kyvernon ip-pools ptr-rejected <id> <address> --reason <reason>Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N) addresspath stringyes Allocated address of the pool (an IPv6 block by its address)
Request body
application/json: PtrRejectBody
Name Type Required Description reasonstringyes Why (shown to the tenant).
Responses
Status Description Schema 204 Done; no body 400 Invalid argument; the error body names the field ErrorBody412 Failed precondition; the error body says which ErrorBody
GET /v1/ip-pools/{id}/availableLists the IPv4 addresses of a pool that can be allocated now (the allocator's own list, ascending), with the number of free IPv4 addresses and IPv6 blocks. Needs Network.Config or Network.Assign on the pool's network.
CLI kyvernon ip-pools available <id> [--limit <n>]Parameters
Name In Type Required Description idpath stringyes Id of the IP pool (ippool-N) limitquery integer or nullMost addresses returned (default 256, at most 4096; 0 returns only the counts).
Responses
GET /v1/vms/{id}/addressesThe public addresses of a VM.
CLI kyvernon addresses list <vm>Parameters
Name In Type Required Description idpath stringyes Id of the virtual machine (vm-N)
Responses
Status Description Schema 200 OK array of VmAddress
POST /v1/vms/{id}/addressesGives a server its public addresses (the server-create hook as a native call): a primary IPv4 address and, when the pool has IPv6, a /64.
CLI kyvernon addresses assign <vm>Parameters
Name In Type Required Description idpath stringyes Id of the virtual machine (vm-N)
Request body
application/json: ServerAddressBody
Name Type Required Description ipv6boolean or nullAlso a /64 when the pool has IPv6 (default true). poolstring or nullPool (absent: the first pool on the VM's networks with a free address). referencestring or nullCaller reference. tenantstring or nullTenant (quota).
Responses
DELETE /v1/vms/{id}/addressesReturns every address of a server to its pool (the server-delete hook).
CLI kyvernon addresses release <vm>Parameters
Name In Type Required Description idpath stringyes Id of the virtual machine (vm-N)
Responses
PUT /v1/vms/{id}/addresses/{address}/ptrSets or removes the PTR name of one of the VM's addresses (the tenant path).
CLI kyvernon addresses ptr <vm> <address> [--name <name>]Parameters
Name In Type Required Description idpath stringyes Id of the virtual machine (vm-N) addresspath stringyes Public address of the virtual machine
Request body
application/json: PtrBody
Name Type Required Description ptrstring or nullHost name; null or empty removes the record.
Responses
Status Description Schema 204 Done; no body 400 Invalid argument; the error body names the field ErrorBody404 Not found (or not visible to the caller) ErrorBody412 Failed precondition; the error body says which ErrorBody
GET /v1/vms/{id}/smtpOutgoing SMTP of a VM: whether TCP 25 is blocked per family and whether the VM is unblocked.
CLI kyvernon addresses smtp <vm>Parameters
Name In Type Required Description idpath stringyes Id of the virtual machine (vm-N)
Responses
PUT /v1/vms/{id}/smtpUnblocks (or blocks again) outgoing SMTP of a VM (operator or portal after its checks; recorded as event VmSmtpChangedEvent).
CLI kyvernon addresses smtp <vm> --unblockParameters
Name In Type Required Description idpath stringyes Id of the virtual machine (vm-N)
Request body
application/json: SmtpBody
Name Type Required Description reasonstring or nullWhy (stored in the audit event, e.g. the portal's ticket). unblockedbooleanyes true: allow port 25 for this VM in both families; false: the pools' setting.
Responses
Status Description Schema 200 OK SmtpView403 Permission denied; args.privilege names the missing privilege ErrorBody
Guides
Previous API: inventory Next API: licence Version 0.1.