gRPC: ippool

Public IP pools, address allocation bound to VM NICs, reverse DNS and monthly traffic (decision L-127, docs/network/DESIGN.md section 11.2 to 11.5). Pools themselves are created and changed through REST (/v1/ip-pools); this service carries the calls a portal or the tenancy module makes per server.

`IpPoolService`

Public IP pools, their allocations and traffic.

Method	Request	Response	Description
`ListPools`	`Empty`	`ListPoolsResponse`	Every IP pool.
`ListAllocations`	`ListAllocationsRequest`	`ListAllocationsResponse`	The allocations of one pool.
`AllocateAddress`	`AllocateAddressRequest`	`Allocation`	Allocates one IPv4 address (or a /64 with family "ipv6") and binds it to a VM NIC.
`FreeAddress`	`FreeAddressRequest`	`Empty`	Returns an address or "prefix/64" to the pool (quarantine) and deletes its PTR record.
`SetPtr`	`SetPtrRequest`	`Empty`	Sets the PTR name of an allocated address; an empty name removes it.
`AllocateForServer`	`AllocateForServerRequest`	`ServerAddresses`	The server-create hook: primary IPv4 address and, when the pool has IPv6, a /64.
`ReleaseForServer`	`ReleaseForServerRequest`	`ReleaseForServerResponse`	The server-delete hook: every address of the VM back to its pool.
`GetTraffic`	`GetTrafficRequest`	`TrafficReport`	Monthly traffic per VM and tenant.

Messages

`IpPool`

An IP pool with its counts.

Field	Number	Type	Description
`id`	1	`string`	Id of the pool.
`name`	2	`string`	Name.
`network`	3	`string`	Id of the host-bridge network of the pool.
`prefix_len`	4	`uint32`	IPv4 prefix length of the subnet.
`ranges`	5	repeated `string`	"start-end" per range.
`gateway`	6	`string`	IPv4 gateway.
`dns_servers`	7	repeated `string`	DNS servers handed to the guests.
`ipv6_prefix`	8	`string`	"prefix/len", empty without IPv6.
`capacity`	9	`uint64`	IPv4 addresses the pool can hand out.
`allocated`	10	`uint64`	Addresses allocated.
`quarantined`	11	`uint64`	Addresses in quarantine after a release.
`free`	12	`uint64`	Addresses free now.
`ipv6_server_prefix_len`	13	`uint32`	Length of the IPv6 block per server (64 to 128); 0 without IPv6.
`addresses`	14	repeated `string`	Explicit IPv4 addresses handed out besides the ranges.

`ListPoolsResponse`

The IP pools.

Field	Number	Type	Description
`items`	1	repeated `IpPool`	Every pool.

`ListAllocationsRequest`

Lists the allocations of a pool.

Field	Number	Type	Description
`pool_id`	1	`string`	Id of the pool.

`Allocation`

An address of a pool and who has it.

Field	Number	Type	Description
`address`	1	`string`	IPv4 address or "prefix/64".
`family`	2	`string`	"ipv4" or "ipv6".
`status`	3	`string`	"allocated" or "quarantined".
`role`	4	`string`	"primary" or "extra" (IPv4).
`vm_id`	5	`string`	Id of the virtual machine.
`mac`	6	`string`	MAC address of the network adapter.
`tenant`	7	`string`	Id of the tenant; empty without one.
`ptr`	8	`string`	Reverse DNS name; empty without one.
`allocated_at`	9	`string`	Time of the allocation, RFC 3339.
`quarantined_until`	10	`string`	End of the quarantine of a released address, RFC 3339; empty otherwise.

`ListAllocationsResponse`

The allocations.

Field	Number	Type	Description
`items`	1	repeated `Allocation`	Allocations of the pool.

`AllocateAddressRequest`

Allocates an address.

Field	Number	Type	Description
`pool_id`	1	`string`	Id of the pool.
`vm_id`	2	`string`	Empty: reserved for the tenant, not bound.
`mac`	3	`string`	Empty: the VM's first NIC on the pool's network.
`address`	4	`string`	Empty: the lowest free address.
`role`	5	`string`	"primary" (default) or "extra".
`family`	6	`string`	"ipv4" (default) or "ipv6".
`tenant`	7	`string`	Id of the tenant the address is for.
`reference`	8	`string`	Free text kept with the allocation (an order number).

`FreeAddressRequest`

Releases an address.

Field	Number	Type	Description
`pool_id`	1	`string`	Id of the pool.
`address`	2	`string`	The address, or the IPv6 block as `prefix/64`.

`SetPtrRequest`

Sets the reverse DNS name of an address.

Field	Number	Type	Description
`pool_id`	1	`string`	Id of the pool.
`address`	2	`string`	The address.
`ptr`	3	`string`	Host name; empty removes it.

`AllocateForServerRequest`

Allocates the addresses of a new server.

Field	Number	Type	Description
`vm_id`	1	`string`	Id of the virtual machine.
`pool_id`	2	`string`	Id of the pool; empty for the first pool on the server's networks.
`tenant`	3	`string`	Id of the tenant.
`no_ipv6`	4	`bool`	No IPv6 block, even when the pool has a prefix.
`reference`	5	`string`	Free text kept with the allocation.

`ServerAddresses`

The addresses of a server.

Field	Number	Type	Description
`pool_id`	1	`string`	Id of the pool.
`mac`	2	`string`	MAC address of the network adapter.
`ipv4`	3	`string`	IPv4 address.
`prefix_len`	4	`uint32`	IPv4 prefix length.
`gateway`	5	`string`	IPv4 gateway.
`dns_servers`	6	repeated `string`	DNS servers.
`ipv6_prefix`	7	`string`	IPv6 block of the server.
`ipv6_address`	8	`string`	IPv6 address of the server in its block.
`ipv6_gateway`	9	`string`	IPv6 gateway.
`ipv6_onlink_len`	10	`uint32`	Prefix length the guest configures on ipv6_address (on-link, at least 64).

`ReleaseForServerRequest`

Releases the addresses of a deleted server.

Field	Number	Type	Description
`vm_id`	1	`string`	Id of the virtual machine.

`ReleaseForServerResponse`

No fields.

Field	Number	Type	Description
`addresses`	1	repeated `string`	Addresses or "prefix" of the released /64s.

`GetTrafficRequest`

Asks for the monthly traffic.

Field	Number	Type	Description
`tenant`	1	`string`	Only the virtual machines of this tenant.
`vm_id`	2	`string`	Only this virtual machine.
`month`	3	`string`	"YYYY-MM"; empty: the current period.

`VmTraffic`

Traffic of one virtual machine in the period.

Field	Number	Type	Description
`vm_id`	1	`string`	Id of the virtual machine.
`name`	2	`string`	Name of the virtual machine.
`tenant`	3	`string`	Id of its tenant; empty without one.
`in_bytes`	4	`uint64`	Bytes received.
`out_bytes`	5	`uint64`	Bytes sent.
`billable_bytes`	6	`uint64`	Bytes that count toward the limit.

`TrafficReport`

Traffic of the period.

Field	Number	Type	Description
`period_start`	1	`string`	Start of the period, RFC 3339.
`period_end`	2	`string`	End of the period, RFC 3339.
`billable`	3	`string`	"out", "in_out" or "max".
`vms`	4	repeated `VmTraffic`	One line per virtual machine.