howto-dea.md

   1 DEA: Deployment Environment Adapter
   2 -----------------------------------
   3
   4 This file has several sections, some of the sections are self describing:
   5
   6 ```
   7 title: Deployment Environment Adapter (DEA)
   8 version:
   9 comment: Config for LF POD1 - HA deployment with Ceph and Opendaylight
  10 wanted_release: Kilo on Ubuntu 14.04
  11 ```
  12
  13 ## The Environment section
  14
  15 environment:
  16   name: opnfv
  17   mode: ha                     # noha, no-ha?
  18   net_segment_type: tun        # ?
  19
  20
  21 ## The "Fuel" section
  22
  23 ```
  24 fuel:
  25   ADMIN_NETWORK:                 # Static Fuel admin network configuration
  26     cidr: 10.20.0.0/24           # this is the "fuelweb_admin" in the nodes
  27     dhcp_gateway: 10.20.0.2      # nodes us this as default gateway
  28     dhcp_pool_end: 10.20.0.254   # nodes get addresses from here
  29     dhcp_pool_start: 10.20.0.3   # This is the Fuel server IP address
  30     ipaddress: 10.20.0.2
  31     netmask: 255.255.0.0         # netmask for nodes (otherwise why is it
  32                                  # needed if CIDR above?
  33   DNS_DOMAIN: domain.tld         #
  34   DNS_SEARCH: domain.tld         #
  35   DNS_UPSTREAM: 8.8.8.8          # Fuel->Network Settings->Other->DNS Servers
  36   FUEL_ACCESS:
  37     password: admin
  38     user: admin
  39   HOSTNAME: opnfv
  40   NTP1: 0.pool.ntp.org           # Fuel->Newtok Setting->Other->NTP server list
  41   NTP2: 1.pool.ntp.org
  42   NTP3: 2.pool.ntp.org
  43 ```
  44
  45 It would make more sense if NTP was a list:
  46
  47 ```
  48   NTP:
  49      - 0.pool.ntp.org
  50      - 1.pool.ntp.org
  51      - 2.pool.ntp.org
  52 ```
  53
  54 Now I don't know if NTP4 would be a valid key...
  55
  56 ## The "node" section
  57
  58 Then there is the important "node" section:
  59
  60 ```
  61 node:
  62    - id: 1
  63      interfaces: <some section describing interfaces>
  64      transformations: <section describing what to do with the interfaces>
  65      role: [controller|compute|cinder|...]
  66    - id: 2
  67       interfaces: interfaces_1
  68       transformations: transformations_1
  69       role: ceph-osd,controller
  70    ...
  71    - id: n
  72      ...
  73 ```
  74
  75 Now, the "interfaces" section could be something line:
  76
  77 ```
  78 node:
  79    - id: 1
  80      interfaces: interfaces_1
  81      transformations: transformations_1
  82 ```
  83
  84 ## Interfaces
  85
  86 In this case we would have a "section" called intefaces_apm, that looks like:
  87
  88 ```
  89 interfaces_1:
  90   eth0:
  91   - none # I made this up, I don't know if "none" is valid
  92   eth1:
  93   - fuelweb_admin
  94   eth2:
  95   - public
  96   - storage     # vlan 2010
  97   - management  # vlan 2011
  98   - private     # vlan 2012
  99 ```
 100
 101 This is self describing in a way. eth1 is used as the interface for the
 102 "fuel admin" network, while eth2 will be used for what Fuel calls "public",
 103 "storage", "management" and "private" networks. These match the networks in
 104 the "networks" tab in the Fuel dashboard.
 105
 106 ## Transformations
 107
 108 For now we won't come into huge detail about the transformations, but they
 109 seem to contain a list of "commands" issued to ovs-vsctl (Open vSwitch).
 110 For example:
 111
 112 ```
 113 transformations_1:
 114   transformations:
 115   - ...
 116   - action: add-port
 117     bridge: br-mgmt
 118     name: eth1.300
 119   - ...
 120 ```
 121
 122 Basically the deploy script will issue the command:
 123
 124 ```
 125   ovs-vsctl add-port br-mgmt eth1.300
 126 ```
 127 (or ...eth1 tag=300)
 128
 129 ## The "network" section:
 130
 131 The networks listed in each of the devices of the "interfaces_1" section
 132 are defined in the "network" section. Inside the "network" section, there is
 133 another section called "networks", with a list of networks defined:
 134
 135 ```
 136 network:
 137    ...
 138    networks:
 139   - cidr: 192.168.0.0/24
 140     gateway: null
 141     ip_ranges:
 142     - - 192.168.0.1
 143       - 192.168.0.254
 144     meta:
 145       cidr: 192.168.0.0/24        # TBD: Can it be different from previos CIDR?
 146                                   # Is this the default value in the UI?
 147       configurable: true          # TBD, UI?
 148       map_priority: 2             # TBD, UI?
 149       name: management
 150       notation: cidr              # TBD, UI?
 151       render_addr_mask: internal  # TBD, UI?
 152       render_type: cidr           # TBD, UI stuff?
 153       use_gateway: false          # Only for public net, or for
 154       vips:                       # TBD
 155       - haproxy
 156       - vrouter
 157       vlan_start: 101
 158     name: management
 159     vlan_start: 300               # must match transformations
 160   - cidr: ...
 161     ...
 162 ```
 163
 164 Let's take the "management" network as an example. Here we define the
 165 netmask and several parameters that will look familiar when looking at the
 166 "Networks" Fuel dashboard tab. The available keys:
 167 - name: the name of the network
 168 - cidr: the CIDR for this network
 169 - gateway: an IP address (only for public network?)
 170 - ip_ranges: a list with the IP ranges available to this network.
 171 - vlan_start: When using vlan tagging, the first vlan tag
 172 - meta: (explained below)
 173
 174 The purpose of the "meta" key is less obvious here, and some of the data
 175 appears to be redundant. My guess is that it is part of Fuel's user
 176 interface. The CIDR here would be the default and "notation" is probably the
 177 way it is displayed in the form field:
 178
 179 - cidr: again the same CIDR as above [is this redundant? error prone?]
 180 - configurable: boolean [?]
 181 - map_priority: int [?]
 182 - name: again the same name as above?
 183 - notation: cidr [any other available keys?]
 184 - use_gateway: boolean [apparently only "true "if an IP was given above]
 185 - vips: This seems to be a list of "namespaces" defined later in the
 186 -       "network section".
 187 - vlan_start same as above...
 188
 189 Now if we look back, in the "interfaces_1" section we had this:
 190
 191 ```
 192 interfaces_1:
 193    eth2:
 194       - management
 195 ```
 196
 197 This is clearly the network defined above. The same goes for "public",
 198 "storage" and "private".
 199
 200 ## The "network" section continued
 201
 202 Apart from the definition of each of the networks and required by Fuel,
 203 the "network" section also has a "preamble" with the following parameters
 204 and corresponding setting in Fuel:
 205
 206 ```
 207 network:
 208   management_vip: 192.168.0.2         # TBD (see vips)
 209   management_vrouter_vip: 192.168.0.1 # TBD
 210   public_vip: 172.30.9.64             # TBD
 211   public_vrouter_vip: 172.30.9.65     # TBD
 212   networking_parameters:              # Fuel->Networ->Settings
 213     base_mac: fa:16:3e:00:00:00       # Neutron L2
 214     configuration_template: null
 215     dns_nameservers:                  # Neutron L3, guess OS DNS Servers
 216     - 8.8.4.4
 217     - 8.8.8.8
 218     floating_ranges:                  # Neutron L3, floating Network Param
 219     - - 172.30.9.160                  #  floating IP range start
 220       - 172.30.9.254                  #  floating IP range end
 221     gre_id_range:                     # Neutron L2, what if VXLAN?
 222     - 2                               # Neutron L2, tunnel ID range start
 223     - 65535                           # Neutron L2, tunnel ID range end
 224                                       # Neutron L3, Internal Network
 225                                       # Parameters
 226     internal_cidr: 192.168.111.0/24   #  internal network CIDR
 227     internal_gateway: 192.168.111.1   #  internal network gateway
 228     net_l23_provider: ovs             # TBD: must match transformations?
 229     segmentation_type: tun            # TBD: what options are there? tun/vlan?
 230     vlan_range:                       # TBD
 231     - 1000
 232     - 1030
 233   vips:
 234     ...
 235 ```
 236
 237 ## The "vips" in the "network" section
 238
 239 In addition to all the above, the network section contains a "vips" section.
 240 I don't know what they mean, but there are some relations between these
 241 vips, and the networks defined above:
 242
 243 ```
 244 network:
 245    vips:
 246       management:
 247          ipaddr: 192.168.0.2     # TBD: same as management_vip?
 248          namespace: haproxy      # TBD: network namespace?
 249          network_role: mgmt/vip  # TBD
 250          node_roles:
 251          - controller            # Why do we define it here?
 252          - primary-controller    # for an HA environment?
 253       public:
 254          ...
 255       vrouter:
 256          ...
 257       vrouter_pub:
 258          ...
 259 ```
 260
 261 Also, in contrast to the "networks" section, the "vips" section is not a list,
 262 but a series of records...
 263
 264 Some Fuel plugins seem to look at this particular setup, one of the examples
 265 in [2], absolute-dashboard-link.pp, reads:
 266
 267 ```
 268 $os_public_vip = $network_metadata['vips']['public']['ipaddr']
 269 ```
 270
 271 If you remember from above, each network has a "metadata" section, this
 272 matches the name of the variable $network_metadata. In that section there is
 273 a "vips" section, that contains a list of "vips", and one of the vips is
 274 "public", and one of the fields is "ipaddr".
 275
 276 * [1] https://docs.mirantis.com/openstack/fuel/fuel-8.0/file-ref.html#fuel-file-reference-pages
 277 * [2] https://wiki.openstack.org/wiki/Fuel/Plugins
 278
 279
 280 ## The "Settings" section
 281
 282 This looks like user interface stuff and default settings. For instance:
 283 settings:
 284
 285 ```
 286   editable:
 287     ...
 288     additional_components:
 289       ceilometer:
 290         description: If selected, Ceilometer component will be installed
 291         label: Install Ceilometer
 292         type: checkbox
 293         value: false
 294         weight: 40
 295 ```
 296
 297 This is clearly the label "Install Ceilometer" in the Fuel web dashboard.
 298
 299 This looks like an email label entry with the corresponding regex to
 300 validate it:
 301
 302 ```
 303 settings:
 304   editable:
 305     access:
 306       email:
 307         description: Email address for Administrator
 308         label: Email
 309         regex:
 310           error: Invalid email
 311           source: ^\S+@\S+$
 312         type: text
 313         value: admin@localhost
 314         weight: 40
 315   ...
 316 ```
 317
 318 ## Other
 319
 320 I think most of it, specially the "settings" part, has been machine created.
 321 It would be nice to recreate one of this files from a manual Fuel
 322 deployment.