code.grnet.gr Git - ganeti-local/blob - doc/design-network.rst

   1 ==================
   2 Network management
   3 ==================
   4
   5 .. contents:: :depth: 4
   6
   7 This is a design document detailing the implementation of network resource
   8 management in Ganeti.
   9
  10 Current state and shortcomings
  11 ==============================
  12
  13 Currently Ganeti supports two configuration modes for instance NICs:
  14 routed and bridged mode. The ``ip`` NIC parameter, which is mandatory
  15 for routed NICs and optional for bridged ones, holds the given NIC's IP
  16 address and may be filled either manually, or via a DNS lookup for the
  17 instance's hostname.
  18
  19 This approach presents some shortcomings:
  20
  21 a) It relies on external systems to perform network resource
  22    management. Although large organizations may already have IP pool
  23    management software in place, this is not usually the case with
  24    stand-alone deployments. For smaller installations it makes sense to
  25    allocate a pool of IP addresses to Ganeti and let it transparently
  26    assign these IPs to instances as appropriate.
  27
  28 b) The NIC network information is incomplete, lacking netmask and
  29    gateway.  Operating system providers could for example use the
  30    complete network information to fully configure an instance's
  31    network parameters upon its creation.
  32
  33    Furthermore, having full network configuration information would
  34    enable Ganeti nodes to become more self-contained and be able to
  35    infer system configuration (e.g. /etc/network/interfaces content)
  36    from Ganeti configuration. This should make configuration of
  37    newly-added nodes a lot easier and less dependant on external
  38    tools/procedures.
  39
  40 c) Instance placement must explicitly take network availability in
  41    different node groups into account; the same ``link`` is implicitly
  42    expected to connect to the same network across the whole cluster,
  43    which may not always be the case with large clusters with multiple
  44    node groups.
  45
  46
  47 Proposed changes
  48 ----------------
  49
  50 In order to deal with the above shortcomings, we propose to extend
  51 Ganeti with high-level network management logic, which consists of a new
  52 NIC slot called ``network``, a new ``Network`` configuration object
  53 (cluster level) and logic to perform IP address pool management, i.e.
  54 maintain a set of available and occupied IP addresses.
  55
  56 Configuration changes
  57 +++++++++++++++++++++
  58
  59 We propose the introduction of a new high-level Network object,
  60 containing (at least) the following data:
  61
  62 - Symbolic name
  63 - UUID
  64 - Network in CIDR notation (IPv4 + IPv6)
  65 - Default gateway, if one exists (IPv4 + IPv6)
  66 - IP pool management data (reservations)
  67 - Default NIC connectivity mode (bridged, routed). This is the
  68   functional equivalent of the current NIC ``mode``.
  69 - Default host interface (e.g. br0). This is the functional equivalent
  70   of the current NIC ``link``.
  71 - Tags
  72
  73 Each network will be connected to any number of node groups. During the
  74 connection of a network to a nodegroup, we define the corresponding
  75 connectivity mode (bridged or routed) and the host interface (br100 or
  76 routing_table_200). This is achieved by adding a ``networks`` slot to
  77 the NodeGroup object and using the networks' UUIDs as keys. The value
  78 for each key is a dictionary containing the network's ``mode`` and
  79 ``link`` (netparams). Every NIC assigned to the network will eventually
  80 inherit the network's netparams, as its nicparams.
  81
  82
  83 IP pool management
  84 ++++++++++++++++++
  85
  86 A new helper library is introduced, wrapping around Network objects to
  87 give IP pool management capabilities. A network's pool is defined by two
  88 bitfields, the length of the network size each:
  89
  90 ``reservations``
  91   This field holds all IP addresses reserved by Ganeti instances.
  92
  93 ``external reservations``
  94   This field holds all IP addresses that are manually reserved by the
  95   administrator (external gateway, IPs of external servers, etc) or
  96   automatically by ganeti (the network/broadcast addresses,
  97   Cluster IPs (node addresses + cluster master)). These IPs are excluded
  98   from the IP pool and cannot be assigned automatically by ganeti to
  99   instances (via ip=pool).
 100
 101 The bitfields are implemented using the python-bitarray package for
 102 space efficiency and their binary value stored base64-encoded for JSON
 103 compatibility. This approach gives relatively compact representations
 104 even for large IPv4 networks (e.g. /20).
 105
 106 Cluster IP addresses (node + master IPs) are reserved automatically
 107 as external if the cluster's data network itself is placed under
 108 pool management.
 109
 110 Helper ConfigWriter methods provide free IP address generation and
 111 reservation, using a TemporaryReservationManager.
 112
 113 It should be noted that IP pool management is performed only for IPv4
 114 networks, as they are expected to be densely populated. IPv6 networks
 115 can use different approaches, e.g. sequential address asignment or
 116 EUI-64 addresses.
 117
 118 New NIC parameter: network
 119 ++++++++++++++++++++++++++
 120
 121 In order to be able to use the new network facility while maintaining
 122 compatibility with the current networking model, a new NIC parameter is
 123 introduced, called ``network`` to reflect the fact that the given NIC
 124 belongs to the given network and its configuration is managed by Ganeti
 125 itself. To keep backwards compatibility, existing code is executed if
 126 the ``network`` value is 'none' or omitted during NIC creation. If we
 127 want our NIC to be assigned to a network, then only the ip (optional)
 128 and the network parameters should be passed. Mode and link are inherited
 129 from the network-nodegroup mapping configuration (netparams). This
 130 provides the desired abstraction between the VM's network and the
 131 node-specific underlying infrastructure.
 132
 133 We also introduce a new ``ip`` address value, ``constants.NIC_IP_POOL``,
 134 that specifies that a given NIC's IP address should be obtained using
 135 the first available IP address inside the pool of the specified network.
 136 (reservations OR external_reservations). This value is only valid
 137 for NICs belonging to a network. A NIC's IP address can also be
 138 specified manually, as long as it is contained in the network the NIC
 139 is connected to. In case this IP is externally reserved, Ganeti will produce
 140 an error which the user can override if explicitly requested. Of course
 141 this IP will be reserved and will not be able to be assigned to another
 142 instance.
 143
 144
 145 Hooks
 146 +++++
 147
 148 Introduce new hooks concerning network operations:
 149
 150 ``OP_NETWORK_ADD``
 151   Add a network to Ganeti
 152
 153   :directory: network-add
 154   :pre-execution: master node
 155   :post-execution: master node
 156
 157 ``OP_NETWORK_REMOVE``
 158   Remove a network from Ganeti
 159
 160   :directory: network-remove
 161   :pre-execution: master node
 162   :post-execution: master node
 163
 164 ``OP_NETWORK_SET_PARAMS``
 165   Modify a network
 166
 167   :directory: network-modify
 168   :pre-execution: master node
 169   :post-execution: master node
 170
 171 For connect/disconnect operations use existing:
 172
 173 ``OP_GROUP_SET_PARAMS``
 174   Modify a nodegroup
 175
 176   :directory: group-modify
 177   :pre-execution: master node
 178   :post-execution: master node
 179
 180 Hook variables
 181 ^^^^^^^^^^^^^^
 182
 183 During instance related operations:
 184
 185 ``INSTANCE_NICn_NETWORK``
 186   The friendly name of the network
 187
 188 During network related operations:
 189
 190 ``NETWORK_NAME``
 191   The friendly name of the network
 192
 193 ``NETWORK_SUBNET``
 194   The ip range of the network
 195
 196 ``NETWORK_GATEWAY``
 197   The gateway of the network
 198
 199 During nodegroup related operations:
 200
 201 ``GROUP_NETWORK``
 202   The friendly name of the network
 203
 204 ``GROUP_NETWORK_MODE``
 205   The mode (bridged or routed) of the netparams
 206
 207 ``GROUP_NETWORK_LINK``
 208   The link of the netparams
 209
 210 Backend changes
 211 +++++++++++++++
 212
 213 To keep the hypervisor-visible changes to a minimum, and maintain
 214 compatibility with the existing network configuration scripts, the
 215 instance's hypervisor configuration will have host-level mode and link
 216 replaced by the *connectivity mode* and *host interface* (netparams) of
 217 the given network on the current node group.
 218
 219 Network configuration scripts detect if a NIC is assigned to a Network
 220 by the presence of the new environment variable:
 221
 222 Network configuration script variables
 223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 224
 225 ``NETWORK``
 226   The friendly name of the network
 227
 228 Conflicting IPs
 229 +++++++++++++++
 230
 231 To ensure IP uniqueness inside a nodegroup, we introduce the term
 232 ``conflicting ips``. Conflicting IPs occur: (a) when creating a
 233 networkless NIC with IP contained in a network already connected to the
 234 instance's nodegroup  (b) when connecting/disconnecting a network
 235 to/from a nodegroup and at the same time instances with IPs inside the
 236 network's range still exist. Conflicting IPs produce prereq errors.
 237
 238 Handling of conflicting IP with --force option:
 239
 240 For case (a) reserve the IP and assign the NIC to the Network.
 241 For case (b) during connect same as (a), during disconnect release IP and
 242 reset NIC's network parameter to None
 243
 244
 245 Userland interface
 246 ++++++++++++++++++
 247
 248 A new client script is introduced, ``gnt-network``, which handles
 249 network-related configuration in Ganeti.
 250
 251 Network addition/deletion
 252 ^^^^^^^^^^^^^^^^^^^^^^^^^
 253 ::
 254
 255  gnt-network add --network=192.168.100.0/28 --gateway=192.168.100.1 \
 256                  --network6=2001:db8:2ffc::/64 --gateway6=2001:db8:2ffc::1 \
 257                  --add-reserved-ips=192.168.100.10,192.168.100.11 net100
 258   (Checks for already exising name and valid IP values)
 259  gnt-network remove network_name
 260   (Checks if not connected to any nodegroup)
 261
 262
 263 Network modification
 264 ^^^^^^^^^^^^^^^^^^^^
 265 ::
 266
 267  gnt-network modify --gateway=192.168.100.5 net100
 268   (Changes the gateway only if ip is available)
 269  gnt-network modify --add-reserved-ips=192.168.100.11 net100
 270   (Adds externally reserved ip)
 271  gnt-network modify --remove-reserved-ips=192.168.100.11 net100
 272   (Removes externally reserved ip)
 273
 274
 275 Assignment to node groups
 276 ^^^^^^^^^^^^^^^^^^^^^^^^^
 277 ::
 278
 279  gnt-network connect net100 nodegroup1 bridged br100
 280   (Checks for existing bridge among nodegroup)
 281  gnt-network connect net100 nodegroup2 routed rt_table
 282   (Checks for conflicting IPs)
 283  gnt-network disconnect net101 nodegroup1
 284   (Checks for conflicting IPs)
 285
 286
 287 Network listing
 288 ^^^^^^^^^^^^^^^
 289 ::
 290
 291  gnt-network list
 292
 293  Network      Subnet           Gateway       NodeGroups GroupList
 294  net100       192.168.100.0/28 192.168.100.1          1 default(bridged, br100)
 295  net101       192.168.101.0/28 192.168.101.1          1 default(routed, rt_tab)
 296
 297 Network information
 298 ^^^^^^^^^^^^^^^^^^^
 299 ::
 300
 301  gnt-network info testnet1
 302
 303  Network name: testnet1
 304   subnet: 192.168.100.0/28
 305   gateway: 192.168.100.1
 306   size: 16
 307   free: 10 (62.50%)
 308   usage map:
 309         0 XXXXX..........X                                                 63
 310           (X) used    (.) free
 311   externally reserved IPs:
 312     192.168.100.0, 192.168.100.1, 192.168.100.15
 313   connected to node groups:
 314     default(bridged, br100)
 315   used by 3 instances:
 316     test1 : 0:192.168.100.4
 317     test2 : 0:192.168.100.2
 318     test3 : 0:192.168.100.3
 319
 320
 321 IAllocator changes
 322 ++++++++++++++++++
 323
 324 The IAllocator protocol can be made network-aware, i.e. also consider
 325 network availability for node group selection. Networks, as well as
 326 future shared storage pools, can be seen as constraints used to rule out
 327 the placement on certain node groups.
 328
 329 .. vim: set textwidth=72 :
 330 .. Local Variables:
 331 .. mode: rst
 332 .. fill-column: 72
 333 .. End: