Skip to content

Commit 9bf339f

Browse files
alexwlchanalexwlchan
committed
Tidy up the IPAM driver doc
Signed-off-by: Alex Chan <alex@alexwlchan.net>
1 parent 7e7fa9d commit 9bf339f

1 file changed

Lines changed: 105 additions & 86 deletions

File tree

‎docs/ipam.md‎

Lines changed: 105 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
# Ipam Driver
1+
# IPAM Driver
22

3-
During the Network and Endpoints lifecyle the CNM model controls the ip address assignment for network and endpoint interfaces via the IPAM driver(s).
4-
Libnetwork has a default, built-in ipam driver and allows third party ipam drivers to be dinamically plugged. On network creation user can specify which ipam driver libnetwork needs to use for the network's ip address management. Current document explains the APIs with which IPAM driver needs to comply and the corresponding HTTPS request/response body relevant for remote drivers.
3+
During the Network and Endpoints lifecyle, the CNM model controls the IP address assignment for network and endpoint interfaces via the IPAM driver(s).
4+
Libnetwork has a default, built-in IPAM driver and allows third party IPAM drivers to be dynamically plugged. On network creation, the user can specify which IPAM driver libnetwork needs to use for the network's IP address management. This document explains the APIs with which the IPAM driver needs to comply, and the corresponding HTTPS request/response body relevant for remote drivers.
55

66

7-
## Remote Ipam driver
7+
## Remote IPAM driver
88

9-
On the same line of remote network driver registration (see [remote.md] for more details), Libnetwork initializes the `ipams.remote` package with the `Init()` function, it passes a `ipamapi.Callback` as a parameter, which implements `RegisterOpamDriver()`. The remote driver package uses this interface to register remote drivers with Libnetwork's `NetworkController`, by supplying it in a `plugins.Handle` callback. The remote drivers register and communicate with libnetwork via the Docker plugin package. The `ipams.remote` provides the proxy for the remote driver processes.
9+
On the same line of remote network driver registration (see [remote.md](./remote.md) for more details), libnetwork initializes the `ipams.remote` package with the `Init()` function. It passes a `ipamapi.Callback` as a parameter, which implements `RegisterIpamDriver()`. The remote driver package uses this interface to register remote drivers with libnetwork's `NetworkController`, by supplying it in a `plugins.Handle` callback. The remote drivers register and communicate with libnetwork via the Docker plugin package. The `ipams.remote` provides the proxy for the remote driver processes.
1010

1111

1212
## Protocol
1313

14-
Communication protocol is same as remote network driver.
14+
Communication protocol is the same as the remote network driver.
1515

1616
## Handshake
1717

@@ -20,93 +20,100 @@ More detailed information can be found in the respective section in this documen
2020

2121
## Datastore Requirements
2222

23-
It is remote driver responsibility to manage its database.
23+
It is the remote driver's responsibility to manage its database.
2424

2525
## Ipam Contract
2626

27-
The ipam driver (internal or remote) has to comply with the contract specified in `ipamapi.contract.go`:
28-
29-
30-
// Ipam represents the interface the IPAM service plugins must implement
31-
// in order to allow injection/modification of IPAM database.
32-
type Ipam interface {
33-
// GetDefaultAddressSpaces returns the default local and global address spaces for this ipam
34-
GetDefaultAddressSpaces() (string, string, error)
35-
// RequestPool returns an address pool along with its unique id. Address space is a mandatory field
36-
// which denotes a set of non-overlapping pools. pool describes the pool of addresses in CIDR notation.
37-
// subpool indicates a smaller range of addresses from the pool, for now it is specified in CIDR notation.
38-
// Both pool and subpool are non mandatory fields. When they are not specified, Ipam driver may choose to
39-
// return a self chosen pool for this request. In such case the v6 flag needs to be set appropriately so
40-
// that the driver would return the expected ip version pool.
41-
RequestPool(addressSpace, pool, subPool string, options map[string]string, v6 bool) (string, *net.IPNet, map[string]string, error)
42-
// ReleasePool releases the address pool identified by the passed id
43-
ReleasePool(poolID string) error
44-
// Request address from the specified pool ID. Input options or preferred IP can be passed.
45-
RequestAddress(string, net.IP, map[string]string) (*net.IPNet, map[string]string, error)
46-
// Release the address from the specified pool ID
47-
ReleaseAddress(string, net.IP) error
48-
}
49-
50-
The following sections explain the each of the above API's semantic, when they are called during network/endpoint lyfecyle and the correspondent payload for remote driver HTTP request/responses.
51-
52-
53-
## Ipam Configuration and flow
27+
The IPAM driver (internal or remote) has to comply with the contract specified in `ipamapi.contract.go`:
5428

55-
Libnetwork user can provide ipam related configuration when creating a network, via the `NetworkOptionIpam` setter function.
29+
```go
30+
// Ipam represents the interface the IPAM service plugins must implement
31+
// in order to allow injection/modification of IPAM database.
32+
type Ipam interface {
33+
// GetDefaultAddressSpaces returns the default local and global address spaces for this ipam
34+
GetDefaultAddressSpaces() (string, string, error)
35+
// RequestPool returns an address pool along with its unique id. Address space is a mandatory field
36+
// which denotes a set of non-overlapping pools. pool describes the pool of addresses in CIDR notation.
37+
// subpool indicates a smaller range of addresses from the pool, for now it is specified in CIDR notation.
38+
// Both pool and subpool are non mandatory fields. When they are not specified, Ipam driver may choose to
39+
// return a self chosen pool for this request. In such case the v6 flag needs to be set appropriately so
40+
// that the driver would return the expected ip version pool.
41+
RequestPool(addressSpace, pool, subPool string, options map[string]string, v6 bool) (string, *net.IPNet, map[string]string, error)
42+
// ReleasePool releases the address pool identified by the passed id
43+
ReleasePool(poolID string) error
44+
// Request address from the specified pool ID. Input options or preferred IP can be passed.
45+
RequestAddress(string, net.IP, map[string]string) (*net.IPNet, map[string]string, error)
46+
// Release the address from the specified pool ID
47+
ReleaseAddress(string, net.IP) error
48+
}
49+
```
5650

57-
`func NetworkOptionIpam(ipamDriver string, addrSpace string, ipV4 []*IpamConf, ipV6 []*IpamConf) NetworkOption`
51+
The following sections explain the each of the above API's semantics, when they are called during network/endpoint lifecycle, and the corresponding payload for remote driver HTTP request/responses.
5852

59-
Caller has to provide the ipam driver name and may provide the address space and a list of `IpamConf` structures for ipv4 and a list for ipv6. The ipam driver name is the only mandatory field. If not provided, network creation will fail.
6053

61-
In the list of configurations, each element has the following form:
54+
## IPAM Configuration and flow
6255

56+
A libnetwork user can provide IPAM related configuration when creating a network, via the `NetworkOptionIpam` setter function.
6357

64-
// IpamConf contains all the ipam related configurations for a network
65-
type IpamConf struct {
66-
// The master address pool for containers and network interfaces
67-
PreferredPool string
68-
// A subset of the master pool. If specified,
69-
// this becomes the container pool
70-
SubPool string
71-
// Input options for IPAM Driver (optional)
72-
Options map[string]string
73-
// Preferred Network Gateway address (optional)
74-
Gateway string
75-
// Auxiliary addresses for network driver. Must be within the master pool.
76-
// libnetwork will reserve them if they fall into the container pool
77-
AuxAddresses map[string]string
78-
}
58+
```go
59+
func NetworkOptionIpam(ipamDriver string, addrSpace string, ipV4 []*IpamConf, ipV6 []*IpamConf) NetworkOption
60+
```
7961

62+
The caller has to provide the IPAM driver name and may provide the address space and a list of `IpamConf` structures for IPv4 and a list for IPv6. The IPAM driver name is the only mandatory field. If not provided, network creation will fail.
8063

81-
On network creation, libnetwork will iterate the list and perform the following requests to ipam driver:
82-
1) Request the address pool and pass the options along via `RequestPool()`.
83-
2) Request the network gateway address if specified. Otherwise request any address from the pool to be used as network gateway. This is done via `RequestAddress()`.
84-
3) Request each of the specified auxiliary addresses via `RequestAddress()`.
64+
In the list of configurations, each element has the following form:
8565

86-
If the list of ipv4 configurations is empty, libnetwork will automatically add one empty `IpamConf` structure. This will cause libnetwork to request ipam driver an ipv4 address pool of the driver choice on the configured address space, if specified, or on the ipam driver default address space otherwise. If the ipam driver is not able to provide an address pool, network creation will fail.
87-
If the list of ipv6 configurations is empty, libnetwork will not take any action.
88-
The data retrieved from the ipam driver during the execution of point 1) to 3) will be stored in the network structure as a list of `IpamInfo` structures for IPv6 and for IPv6.
66+
```go
67+
// IpamConf contains all the ipam related configurations for a network
68+
type IpamConf struct {
69+
// The master address pool for containers and network interfaces
70+
PreferredPool string
71+
// A subset of the master pool. If specified,
72+
// this becomes the container pool
73+
SubPool string
74+
// Input options for IPAM Driver (optional)
75+
Options map[string]string
76+
// Preferred Network Gateway address (optional)
77+
Gateway string
78+
// Auxiliary addresses for network driver. Must be within the master pool.
79+
// libnetwork will reserve them if they fall into the container pool
80+
AuxAddresses map[string]string
81+
}
82+
```
83+
84+
On network creation, libnetwork will iterate the list and perform the following requests to the IPAM driver:
85+
86+
1. Request the address pool and pass the options along via `RequestPool()`.
87+
2. Request the network gateway address if specified. Otherwise request any address from the pool to be used as network gateway. This is done via `RequestAddress()`.
88+
3. Request each of the specified auxiliary addresses via `RequestAddress()`.
89+
90+
If the list of IPv4 configurations is empty, libnetwork will automatically add one empty `IpamConf` structure. This will cause libnetwork to request IPAM driver an IPv4 address pool of the driver's choice on the configured address space, if specified, or on the IPAM driver default address space otherwise. If the IPAM driver is not able to provide an address pool, network creation will fail.
91+
If the list of IPv6 configurations is empty, libnetwork will not take any action.
92+
The data retrieved from the IPAM driver during the execution of point 1) to 3) will be stored in the network structure as a list of `IpamInfo` structures for IPv6 and for IPv6.
8993

9094
On endpoint creation, libnetwork will iterate over the list of configs and perform the following operation:
91-
1) Request an IPv4 address from the ipv4 pool and assign it to the endpoint interface ipv4 address. If successful, stop iterating.
92-
2) Request an IPv6 address from the ipv6 pool (if exists) and assign it to the endpoint interface ipv6 address. If successful, stop iterating.
95+
96+
1. Request an IPv4 address from the IPv4 pool and assign it to the endpoint interface IPv4 address. If successful, stop iterating.
97+
2. Request an IPv6 address from the IPv6 pool (if exists) and assign it to the endpoint interface IPv6 address. If successful, stop iterating.
9398

9499
Endpoint creation will fail if any of the above operation does not succeed
95100

96101
On endpoint deletion, libnetwork will perform the following operations:
97-
1) Release the endpoint interface IPv4 address
98-
2) Release the endpoint interface IPv6 address if present
99102

100-
On Network deletion libnetwork will iterate the list of `IpamData` structures and perform the following requests to ipam driver:
101-
1) Release the network gateway address via `ReleaseAddress()`
102-
2) Release each of the auxiliary addresses via `ReleaseAddress()`
103-
3) Release the pool via `ReleasePool()`
103+
1. Release the endpoint interface IPv4 address
104+
2. Release the endpoint interface IPv6 address if present
105+
106+
On network deletion, libnetwork will iterate the list of `IpamData` structures and perform the following requests to ipam driver:
107+
108+
1. Release the network gateway address via `ReleaseAddress()`
109+
2. Release each of the auxiliary addresses via `ReleaseAddress()`
110+
3. Release the pool via `ReleasePool()`
104111

105112
### GetDefaultAddressSpaces
106113

107-
GetDefaultAddressSpaces returns the default local and global address space names for this ipam. An address space is a set of non-overlapping address pools isolated from other address spaces' pools. In other words, same pool can exist on N different address spaces. An address space naturally maps to a tenant name.
108-
In libnetwork the meaning associated to `local` or `global` address space is that a local address space doesn't need to get synchronized across the
109-
cluster where as the global address spaces does. Unless specified otherwise in the ipam configuration, libnetwork will request address pools from the default local or default global address space based on the scope of the network being created. For example, if not specified otherwise in the configuration, libnetwork will request address pool from the default local address space for a bridge network, whereas from the default global address space for an overlay network.
114+
GetDefaultAddressSpaces returns the default local and global address space names for this IPAM. An address space is a set of non-overlapping address pools isolated from other address spaces' pools. In other words, same pool can exist on N different address spaces. An address space naturally maps to a tenant name.
115+
In libnetwork, the meaning associated to `local` or `global` address space is that a local address space doesn't need to get synchronized across the
116+
cluster whereas the global address spaces does. Unless specified otherwise in the IPAM configuration, libnetwork will request address pools from the default local or default global address space based on the scope of the network being created. For example, if not specified otherwise in the configuration, libnetwork will request address pool from the default local address space for a bridge network, whereas from the default global address space for an overlay network.
110117

111118
During registration, the remote driver will receive a POST message to the URL `/IpamDriver.GetDefaultAddressSpaces` with no payload. The driver's response should have the form:
112119

@@ -120,10 +127,12 @@ During registration, the remote driver will receive a POST message to the URL `/
120127

121128
### RequestPool
122129

123-
This API is for registering a address pool with the ipam driver. Multiple identical calls must return the same result.
124-
it is ipam driver responsibility to keep a reference count for the pool.
130+
This API is for registering a address pool with the IPAM driver. Multiple identical calls must return the same result.
131+
It is the IPAM driver's responsibility to keep a reference count for the pool.
125132

126-
`RequestPool(addressSpace, pool, subPool string, options map[string]string, v6 bool) (string, *net.IPNet, map[string]string, error)`
133+
```go
134+
RequestPool(addressSpace, pool, subPool string, options map[string]string, v6 bool) (string, *net.IPNet, map[string]string, error)
135+
```
127136

128137

129138
For this API, the remote driver will receive a POST message to the URL `/IpamDriver.RequestPool` with the following payload:
@@ -138,14 +147,15 @@ For this API, the remote driver will receive a POST message to the URL `/IpamDri
138147

139148

140149
Where:
141-
* `AddressSpace` the ip address space
150+
151+
* `AddressSpace` the IP address space
142152
* `Pool` The IPv4 or IPv6 address pool in CIDR format
143153
* `SubPool` An optional subset of the address pool, an ip range in CIDR format
144-
* `Options` A map of ipam driver specific options
145-
* `V6` Whether a ipam self chosen pool should be IPv6
154+
* `Options` A map of IPAM driver specific options
155+
* `V6` Whether an IPAM self-chosen pool should be IPv6
146156

147-
Address space is the only mandatory field. If no `Pool` is specified ipam driver may return a self chosen address pool. In such case, `V6` flag must be set if caller wants an ipam chosen IPv6 pool. A request with empty `Pool` and non-empty `SubPool` should be rejected as invalid.
148-
If a Pool is not specified IPAM will allocate one of the default pools. When the Pool is not specified V6 flag should be set if the network needs IPv6 addresses to be allocated.
157+
AddressSpace is the only mandatory field. If no `Pool` is specified IPAM driver may return a self chosen address pool. In such case, `V6` flag must be set if caller wants an IPAM-chosen IPv6 pool. A request with empty `Pool` and non-empty `SubPool` should be rejected as invalid.
158+
If a `Pool` is not specified IPAM will allocate one of the default pools. When `Pool` is not specified, the `V6` flag should be set if the network needs IPv6 addresses to be allocated.
149159

150160
A successful response is in the form:
151161

@@ -158,16 +168,19 @@ A successful response is in the form:
158168

159169

160170
Where:
171+
161172
* `PoolID` is an identifier for this pool. Same pools must have same pool id.
162173
* `Pool` is the pool in CIDR format
163-
* `Data` is the ipam driver supplied metadata for this pool
174+
* `Data` is the IPAM driver supplied metadata for this pool
164175

165176

166177
### ReleasePool
167178

168179
This API is for releasing a previously registered address pool.
169180

170-
`ReleasePool(poolID string) error`
181+
```go
182+
ReleasePool(poolID string) error
183+
```
171184

172185
For this API, the remote driver will receive a POST message to the URL `/IpamDriver.ReleasePool` with the following payload:
173186

@@ -176,6 +189,7 @@ For this API, the remote driver will receive a POST message to the URL `/IpamDri
176189
}
177190

178191
Where:
192+
179193
* `PoolID` is the pool identifier
180194

181195
A successful response is empty:
@@ -186,7 +200,9 @@ A successful response is empty:
186200

187201
This API is for reserving an ip address.
188202

189-
`RequestAddress(string, net.IP, map[string]string) (*net.IPNet, map[string]string, error)`
203+
```go
204+
RequestAddress(string, net.IP, map[string]string) (*net.IPNet, map[string]string, error)
205+
```
190206

191207
For this API, the remote driver will receive a POST message to the URL `/IpamDriver.RequestAddress` with the following payload:
192208

@@ -197,9 +213,10 @@ For this API, the remote driver will receive a POST message to the URL `/IpamDri
197213
}
198214

199215
Where:
216+
200217
* `PoolID` is the pool identifier
201-
* `Address` is the preferred address in regular IP form (A.B.C.D). If empty, the ipam driver chooses any available address on the pool
202-
* `Options` are ipam driver specific options
218+
* `Address` is the preferred address in regular IP form (A.B.C.D). If empty, the IPAM driver chooses any available address on the pool
219+
* `Options` are IPAM driver specific options
203220

204221

205222
A successful response is in the form:
@@ -212,8 +229,9 @@ A successful response is in the form:
212229

213230

214231
Where:
232+
215233
* `Address` is the allocated address in CIDR format (A.B.C.D/MM)
216-
* `Data` is some ipam driver specific metadata
234+
* `Data` is some IPAM driver specific metadata
217235

218236
### ReleaseAddress
219237

@@ -227,6 +245,7 @@ For this API, the remote driver will receive a POST message to the URL `/IpamDri
227245
}
228246

229247
Where:
248+
230249
* `PoolID` is the pool identifier
231-
* `Address` is the ip address to release
250+
* `Address` is the IP address to release
232251

0 commit comments

Comments
 (0)