deploy/README.templater

   1 ##############################################################################
   2 # Copyright (c) 2016 Ericsson AB and others.
   3 # peter.barabas@ericsson.com
   4 # All rights reserved. This program and the accompanying materials
   5 # are made available under the terms of the Apache License, Version 2.0
   6 # which accompanies this distribution, and is available at
   7 # http://www.apache.org/licenses/LICENSE-2.0
   8 ##############################################################################
   9
  10 ======== TEMPLATING SUPPORT IN YAML CONFIGURATION FILES ========
  11
  12 deploy/templater.py makes it possible to use templates to generate configuration
  13 files. It takes 2 input YAML files and an output file as arguments. One being
  14 the dictionary (called the base file), which is used to look up values in; the
  15 other file is the template, where the substitution will take place. Templater
  16 will write the result to an output file, specified as the 3rd argument.
  17
  18
  19 ======== SYNTAX OF TEMPLATE FILES ========
  20
  21 A template file can contain any valid YAML data and template variables, whose
  22 syntax is described below:
  23
  24 1. Single value references
  25
  26    %{title}
  27
  28    %{environment/net_segment_type}
  29
  30    Either a root element, or a path can be specified.
  31
  32 2. YAML sections
  33
  34    %{nodes}
  35
  36    %{network/networking_parameters}
  37
  38    Either a root element, or a path can be specified.
  39
  40 3. Interface lookup for network
  41
  42    %{interface(storage)}
  43
  44    Specify a network type as argument to interface().
  45
  46 4. Interface lookup for network and role
  47
  48    %{interface(public,compute)}
  49
  50    Specify a network type and a role as arguments to interface().
  51
  52 5. File inclusion
  53
  54    %{include(templates/interfaces.yaml)}
  55
  56    Filename with absolute or relative path.
  57
  58
  59 ======== EXAMPLES ========
  60
  61 Base YAML file (excerpt):
  62
  63 title: Deployment Environment Adapter (DEA)
  64 version: 1.1
  65 created: Wed Mar 30 08:16:04 2016
  66 environment:
  67   name: vCity
  68   net_segment_type: tun
  69 wanted_release: Liberty on Ubuntu 14.04
  70 nodes:
  71 - id: 1
  72   interfaces: interfaces_1
  73   role: ceph-osd,compute
  74   transformations: transformations_1
  75 - id: 2
  76   interfaces: interfaces_1
  77   role: ceph-osd,compute
  78   transformations: transformations_1
  79 - id: 3
  80   interfaces: interfaces_1
  81   role: ceph-osd,compute
  82   transformations: transformations_1
  83 - id: 4
  84   interfaces: interfaces_2
  85   role: controller,mongo
  86   transformations: transformations_2
  87 - id: 5
  88   interfaces: interfaces_2
  89   role: controller,mongo
  90   transformations: transformations_2
  91 - id: 6
  92   interfaces: interfaces_2
  93   role: controller,mongo
  94   transformations: transformations_2
  95 interfaces_1:
  96   ens3:
  97   - fuelweb_admin
  98   - management
  99   ens4:
 100   - storage
 101   ens5:
 102   - private
 103   ens6:
 104   - public
 105 interfaces_2:
 106   ens3:
 107   - fuelweb_admin
 108   - management
 109   ens4:
 110   - storage
 111   - private
 112   - public
 113 network:
 114   networks:
 115   - cidr: 172.16.0.0/24
 116     gateway: 172.16.0.1
 117     ip_ranges:
 118     - - 172.16.0.2
 119       - 172.16.0.126
 120     meta:
 121       cidr: 172.16.0.0/24
 122       configurable: true
 123       floating_range_var: floating_ranges
 124       ip_range:
 125       - 172.16.0.2
 126       - 172.16.0.126
 127       map_priority: 1
 128       name: public
 129       notation: ip_ranges
 130       render_addr_mask: public
 131       render_type: null
 132       use_gateway: true
 133       vips:
 134       - haproxy
 135       - vrouter
 136       vlan_start: null
 137     name: public
 138     vlan_start: null
 139   - cidr: 192.168.1.0/24
 140     gateway: null
 141     ip_ranges:
 142     - - 192.168.1.1
 143       - 192.168.1.254
 144     meta:
 145       cidr: 192.168.1.0/24
 146       configurable: true
 147       map_priority: 2
 148       name: storage
 149       notation: cidr
 150       render_addr_mask: storage
 151       render_type: cidr
 152       use_gateway: false
 153       vlan_start: 102
 154     name: storage
 155     vlan_start: 102
 156
 157
 158 --- Example 1 ---
 159
 160 Template file:
 161
 162 deployment-scenario-metadata:
 163   title: %{title}
 164   version: 0.1
 165 dea-override-config:
 166   environment:
 167     net_segment_type: %{environment/net_segment_type}
 168   nodes:
 169   %{nodes}
 170
 171
 172 Result:
 173
 174 deployment-scenario-metadata:
 175   title: Deployment Environment Adapter (DEA)
 176   version: 0.1
 177 dea-override-config:
 178   environment:
 179     net_segment_type: tun
 180   nodes:
 181   - id: 1
 182     interfaces: interfaces_1
 183     role: ceph-osd,compute
 184     transformations: transformations_1
 185   - id: 2
 186     interfaces: interfaces_1
 187     role: ceph-osd,compute
 188     transformations: transformations_1
 189   - id: 3
 190     interfaces: interfaces_1
 191     role: ceph-osd,compute
 192     transformations: transformations_1
 193   - id: 4
 194     interfaces: interfaces_2
 195     role: controller,mongo
 196     transformations: transformations_2
 197   - id: 5
 198     interfaces: interfaces_2
 199     role: controller,mongo
 200     transformations: transformations_2
 201   - id: 6
 202     interfaces: interfaces_2
 203     role: controller,mongo
 204     transformations: transformations_2
 205
 206
 207 --- Example 2 ---
 208
 209 Template file:
 210
 211 dea-override-config:
 212   network:
 213     networks:
 214     %{network/networks}
 215
 216
 217 Result:
 218
 219 dea-override-config:
 220   network:
 221     networks:
 222     - cidr: 172.16.0.0/24
 223       gateway: 172.16.0.1
 224       ip_ranges:
 225       - - 172.16.0.2
 226         - 172.16.0.126
 227       meta:
 228         cidr: 172.16.0.0/24
 229         configurable: true
 230         floating_range_var: floating_ranges
 231         ip_range:
 232         - 172.16.0.2
 233         - 172.16.0.126
 234         map_priority: 1
 235         name: public
 236         notation: ip_ranges
 237         render_addr_mask: public
 238         render_type: null
 239         use_gateway: true
 240         vips:
 241         - haproxy
 242         - vrouter
 243         vlan_start: null
 244       name: public
 245       vlan_start: null
 246     - cidr: 192.168.1.0/24
 247       gateway: null
 248       ip_ranges:
 249       - - 192.168.1.1
 250         - 192.168.1.254
 251       meta:
 252         cidr: 192.168.1.0/24
 253         configurable: true
 254         map_priority: 2
 255         name: storage
 256         notation: cidr
 257         render_addr_mask: storage
 258         render_type: cidr
 259         use_gateway: false
 260         vlan_start: 102
 261       name: storage
 262       vlan_start: 102
 263
 264
 265 --- Example 3 ---
 266
 267 Template file:
 268
 269 storage_if: %{interface(storage)}
 270 compute_private_if: %{interface(private,compute)}
 271 # Management interface of a mongo node
 272 mongo_mgmt_if: %{interface(management,mongo)}
 273 controller_private_if: %{interface(private,controller)}
 274
 275
 276 Result:
 277
 278 storage_if: ens4
 279 compute_private_if: ens5
 280 # Management interface of a mongo node
 281 mongo_mgmt_if: ens3
 282 controller_private_if: ens4
 283
 284
 285 --- Example 4 ---
 286
 287 Template file:
 288
 289 version: 1.1
 290 created: Mon Jun 13 19:39:35 2016
 291 comment: None
 292 %{include(environment.yaml)}
 293
 294
 295 environment.yaml:
 296
 297 environment:
 298   name: F9-NOSDN-NOFEATURE-VXLAN-BAREMETAL
 299   net_segment_type: tun
 300
 301
 302 Result:
 303
 304 version: 1.1
 305 created: Mon Jun 13 19:39:35 2016
 306 comment: None
 307 environment:
 308   name: F9-NOSDN-NOFEATURE-VXLAN-BAREMETAL
 309   net_segment_type: tun
 310
 311
 312 --- Example 5 ---
 313
 314 Template file (except):
 315
 316 settings:
 317   editable:
 318     access:
 319       email:
 320         description: Email address for Administrator
 321         label: Email
 322         regex:
 323           error: Invalid email
 324           source: ^\S+@\S+$
 325         type: text
 326         value: admin@localhost
 327         weight: 40
 328 # ...
 329 # lines omitted for brevity
 330     %{include(templates/cgroups.yaml)}
 331
 332
 333 cgroups.yaml:
 334
 335     cgroups:
 336       metadata:
 337         always_editable: true
 338         group: general
 339         label: Cgroups conguration for services
 340         restrictions:
 341         - action: hide
 342           condition: 'true'
 343         weight: 90
 344
 345
 346 Result:
 347
 348 settings:
 349   editable:
 350     access:
 351       email:
 352         description: Email address for Administrator
 353         label: Email
 354         regex:
 355           error: Invalid email
 356           source: ^\S+@\S+$
 357         type: text
 358         value: admin@localhost
 359         weight: 40
 360 # ...
 361 # again, lines omitted for brevity
 362     cgroups:
 363       metadata:
 364         always_editable: true
 365         group: general
 366         label: Cgroups conguration for services
 367         restrictions:
 368         - action: hide
 369           condition: 'true'
 370         weight: 90
 371