vcloud-edge_gateway 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. data/CHANGELOG.md +11 -0
  2. data/README.md +219 -11
  3. data/examples/firewall-rules.yaml +50 -0
  4. data/examples/loadbalancer-rules.yaml +55 -0
  5. data/examples/nat-rules.yaml +58 -0
  6. data/lib/vcloud/edge_gateway.rb +2 -3
  7. data/lib/vcloud/edge_gateway/configuration_differ.rb +13 -1
  8. data/lib/vcloud/edge_gateway/configuration_generator/nat_service.rb +10 -10
  9. data/lib/vcloud/edge_gateway/edge_gateway_configuration.rb +2 -2
  10. data/lib/vcloud/edge_gateway/firewall_configuration_differ.rb +18 -0
  11. data/lib/vcloud/edge_gateway/load_balancer_configuration_differ.rb +3 -13
  12. data/lib/vcloud/edge_gateway/nat_configuration_differ.rb +18 -0
  13. data/lib/vcloud/edge_gateway/version.rb +1 -1
  14. data/lib/vcloud/edge_gateway_services.rb +1 -1
  15. data/spec/integration/edge_gateway/edge_gateway_services_spec.rb +7 -13
  16. data/spec/integration/edge_gateway/firewall_service_spec.rb +2 -12
  17. data/spec/integration/edge_gateway/load_balancer_service_spec.rb +4 -4
  18. data/spec/integration/edge_gateway/nat_service_spec.rb +4 -4
  19. data/spec/spec_helper.rb +2 -2
  20. data/spec/vcloud/edge_gateway/configuration_differ_shared_examples.rb +132 -0
  21. data/spec/vcloud/edge_gateway/configuration_differ_spec.rb +5 -122
  22. data/spec/vcloud/edge_gateway/configuration_generator/firewall_service_spec.rb +46 -52
  23. data/spec/vcloud/edge_gateway/firewall_configuration_differ_spec.rb +65 -0
  24. data/spec/vcloud/edge_gateway/firewall_schema_validation_spec.rb +2 -2
  25. data/spec/vcloud/edge_gateway/load_balancer_configuration_differ_spec.rb +32 -147
  26. data/spec/vcloud/edge_gateway/load_balancer_schema_validation_spec.rb +7 -7
  27. data/spec/vcloud/edge_gateway/nat_configuration_differ_spec.rb +65 -0
  28. data/spec/vcloud/edge_gateway/nat_schema_validation_spec.rb +4 -4
  29. data/vcloud-edge_gateway.gemspec +2 -2
  30. metadata +18 -13
  31. data/lib/vcloud/config_loader.rb +0 -27
  32. data/lib/vcloud/config_validator.rb +0 -207
  33. data/spec/vcloud/config_loader_spec.rb +0 -112
  34. data/spec/vcloud/config_validator_spec.rb +0 -570
@@ -1,3 +1,14 @@
1
+ ## 0.2.3 (2014-04-22)
2
+
3
+ Bugfixes:
4
+
5
+ - Requires vCloud Core v0.0.12 which fixes issue with progress bar falling over when progress is not returned
6
+
7
+ Features:
8
+
9
+ - Now uses the config loader and validator in vcloud-core rather than its own duplicate.
10
+ - Require fog v1.21 to allow use of FOG_VCLOUD_TOKEN via ENV as an alternative to a .fog file
11
+
1
12
  ## 0.2.2 (2014-03-05)
2
13
 
3
14
  Bugfixes:
data/README.md CHANGED
@@ -25,15 +25,63 @@ To configure an Edge Gateway:
25
25
 
26
26
  $ vcloud-configure-edge input.yaml
27
27
 
28
+ ### Credentials
28
29
 
29
- ## Contributing
30
+ vCloud Edge Gateway is based around [fog]. To use it you'll need to give it credentials that allow it to talk to a VMware
31
+ environment. Fog offers two ways to do this.
30
32
 
31
- 1. Fork it
32
- 2. Create your feature branch (`git checkout -b my-new-feature`)
33
- 3. Commit your changes (`git commit -am 'Add some feature'`)
34
- 4. Push to the branch (`git push origin my-new-feature`)
35
- 5. Create new Pull Request
33
+ #### 1. Create a `.fog` file containing your credentials
34
+
35
+ To use this method, you need a `.fog` file in your home directory.
36
+
37
+ For example:
38
+
39
+ test:
40
+ vcloud_director_username: 'username@org_name'
41
+ vcloud_director_password: 'password'
42
+ vcloud_director_host: 'host.api.example.com'
43
+
44
+ Unfortunately current usage of fog requires the password in this file. Multiple sets of credentials can be specified in the fog file, using the following format:
45
+
46
+ test:
47
+ vcloud_director_username: 'username@org_name'
48
+ vcloud_director_password: 'password'
49
+ vcloud_director_host: 'host.api.example.com'
50
+
51
+ test2:
52
+ vcloud_director_username: 'username@org_name'
53
+ vcloud_director_password: 'password'
54
+ vcloud_director_host: 'host.api.vendor.net'
55
+
56
+ You can then pass the `FOG_CREDENTIAL` environment variable at the start of your command. The value of the `FOG_CREDENTIAL` environment variable is the name of the credential set in your fog file which you wish to use. For instance:
57
+
58
+ $ FOG_CREDENTIAL=test2 vcloud-configure-edge input.yaml
59
+
60
+ To understand more about `.fog` files, visit the 'Credentials' section here => http://fog.io/about/getting_started.html.
61
+
62
+ #### 2. Log on externally and supply your session token
63
+
64
+ You can choose to log on externally by interacting independently with the API and supplying your session token to the
65
+ tool by setting the `FOG_VCLOUD_TOKEN` ENV variable. This option reduces the risk footprint by allowing the user to
66
+ store their credentials in safe storage. The default token lifetime is '30 minutes idle' - any activity extends the life by another 30 mins.
67
+
68
+ A basic example of this would be the following:
69
+
70
+ curl
71
+ -D-
72
+ -d ''
73
+ -H 'Accept: application/*+xml;version=5.1' -u '<user>@<org>'
74
+ https://host.com/api/sessions
75
+
76
+ This will prompt for your password.
36
77
 
78
+ From the headers returned, select the header below
79
+
80
+ x-vcloud-authorization: AAAABBBBBCCCCCCDDDDDDEEEEEEFFFFF=
81
+
82
+ Use token as ENV var FOG_VCLOUD_TOKEN
83
+
84
+ $ FOG_VCLOUD_TOKEN=AAAABBBBBCCCCCCDDDDDDEEEEEEFFFFF= vcloud-configure-edge input.yaml
37
85
 
38
86
  ### Configure edge gateway services
39
87
 
@@ -93,6 +141,8 @@ Rule fields have the following behaviour
93
141
  * A CIDR range, eg `192.0.2.0/24`
94
142
  * A hyphened range, such as `192.0.2.50-192.0.2.60`
95
143
 
144
+
145
+
96
146
  #### nat_service
97
147
 
98
148
  The edge gateway NAT service offers simple stateful Source-NAT and
@@ -148,7 +198,7 @@ A DNAT rule has the following form, and translates packets going to the
148
198
  #### load_balancer_service
149
199
 
150
200
  The load balancer service comprises two sets of configurations: 'pools' and
151
- 'virtual_servers'. These are coupled together to form a load balanced service:
201
+ 'virtual_servers'. These are coupled together to form load balanced services:
152
202
 
153
203
  * A virtual_server provides the front-end of a load balancer - the port and
154
204
  IP that clients connect to.
@@ -158,8 +208,13 @@ The load balancer service comprises two sets of configurations: 'pools' and
158
208
  it.
159
209
  * Multiple virtual_servers can specify the same pool (to run the same service
160
210
  on different FQDNs, for example)
211
+ * virtual_servers define any 'session persistence' information, if sessions
212
+ are required to stick to the same pool member. (Session persistence is not currently supported by this tool.)
213
+ * pools define 'member healthchecks', and so are aware of the health of their
214
+ member nodes.
161
215
 
162
- A typical load balancer configuration (for one service) would look something like:
216
+ A typical load balancer configuration (for one service, mapping 192.0.2.0:80 to
217
+ port 8080 on three servers) would look something like:
163
218
 
164
219
  ```
165
220
  load_balancer_service:
@@ -183,9 +238,146 @@ load_balancer_service:
183
238
  pool: 'example-pool-1' # must refer to a pool name detailed above
184
239
  service_profiles:
185
240
  http: # protocol to balance, can be tcp/http/https.
186
- port: '80' # external port
241
+ port: '80' # external port
242
+ ```
243
+
244
+ The vCloud Director load balancer service is quite basic, but supports the following:
245
+
246
+ * Layer 7 balancing of HTTP traffic
247
+ * Balancing of HTTPS traffic (though no decryption is possible, so this is
248
+ purely level-4 based)
249
+ * Layer 4 balancing of arbitrary TCP traffic.
250
+ * URI-based healthchecks of backend nodes
251
+ * Several balancing algorithms, such as 'round robin', and 'least connections'
252
+ * Ability to persist sessions to the same backend member node, via a variety of
253
+ means (eg HTTP cookie value, SSL session ID, source IP hash).
254
+
255
+ `vcloud-configure-edge` supports all of the above features.
256
+
257
+ It is also worth noting that the vCloud Director load balancer *does not support*:
258
+
259
+ * In vCD 5.1, TCP and HTTPS layer-4 balancing are based on TCP port forwarding.
260
+ There is no NAT in the mix, so the backend pools see the IP address/port of
261
+ the edge rather than the remote host.
262
+ * There is no SSL offloading/decryption possible on the device, so traffic
263
+ inspection of HTTPS is not feasible.
264
+
265
+ Rather unusually, each virtual server and pool combination can handle traffic
266
+ balancing for HTTP, HTTPS, and a single TCP port simultaneously. For example:
267
+
268
+ ```
269
+ load_balancer_service:
270
+ pools:
271
+ - name: 'example-multi-protocol-pool-1'
272
+ description: 'A pool balancing HTTP, HTTPS, and SMTP traffic'
273
+ service:
274
+ http: {}
275
+ https: {}
276
+ tcp:
277
+ port: 25
278
+ members:
279
+ - ip_address: 10.10.10.14
280
+ - ip_address: 10.10.10.15
281
+ virtual_servers:
282
+ - name: 'example-multi-protocol-virtual-server-1'
283
+ description: 'A virtual server connecting to example-pool-1'
284
+ ip_address: 192.0.2.11
285
+ network: '12345678-1234-1234-1234-123456789012'
286
+ pool: 'example-multi-protocol-pool-1'
287
+ service_profiles:
288
+ http: {}
289
+ https: {}
290
+ tcp:
291
+ port: 25
292
+ ```
293
+
294
+ The above is particularly useful for services that require balancing of HTTP
295
+ and HTTPS traffic together.
296
+
297
+ #### load_balancer_service pool entries in detail
298
+
299
+ Each pool entry consists of:
300
+
301
+ * a pool name, and optional description
302
+ * a 'service' section - which protocol(s) to balance, and how to balance them.
303
+ * a 'members' list - which backend nodes to use.
304
+
305
+ For example:
306
+
307
+ ```
308
+ name: test-pool-1
309
+ description: Balances HTTP and HTTPS
310
+ service:
311
+ http: {}
312
+ https: {}
313
+ members:
314
+ - ip_address: 10.10.10.11
315
+ - ip_address: 10.10.10.12
316
+ weight: 10
187
317
  ```
188
318
 
319
+ Here we have:
320
+
321
+ * HTTP and HTTPS traffic balanced across 10.10.10.11 and 10.10.10.12.
322
+ * member 10.10.10.11 has a default `weight` of 1
323
+ * member 10.10.10.12 has a `weight` of 10, so will receive 10x the traffic of
324
+ 10.10.10.11
325
+ * http and https services are using all defaults, which means:
326
+ * they use standard ports (80 for HTTP, 443 for HTTPS)
327
+ * they will use 'round robin' balancing
328
+ * HTTP service will 'GET /' from each node to check its health
329
+ * HTTPS service will check 'SSL hello' response to confirm its health.
330
+
331
+ Service entries are the most complex, due to the available options on
332
+ a per-service basis. The defaults we provide are suitable for most situations,
333
+ but for more infomation see below.
334
+
335
+ A more complete HTTP service entry looks like:
336
+
337
+ ```
338
+ service:
339
+ http:
340
+ port: 8080
341
+ algorithm: 'ROUND_ROBIN' # can also be 'LEAST_CONNECTED', 'IP_HASH', 'URI'
342
+ health_check:
343
+ port: 8081 # port to check health on, if not service port above.
344
+ uri: /healthcheck # for HTTP, the URI to check for 200/30* response
345
+ protocol: HTTP # the protocol to talk to health check service: HTTP, SSL, TCP
346
+ health_threshold: 2 # how many checks to success before reenabling member
347
+ unhealth_threshold: 3 # how many checks to fail before disabling member
348
+ interval: 5 # interval between checks
349
+ timeout: 15 # how long to wait before assuming healthcheck has failed
350
+
351
+ ```
352
+
353
+ See [the vCloud Director Admin Guide](http://pubs.vmware.com/vcd-51/topic/com.vmware.vcloud.admin.doc_51/GUID-C12B3954-155F-48AF-9855-E0DE026752D0.html)
354
+ for more details on configuring Pool entries.
355
+
356
+ #### load_balancer_service virtual_server entries in detail
357
+
358
+ Each virtual_server entry must consist of:
359
+
360
+ * a virtual_server name, and optional description
361
+ * a 'service_profiles' section: which protocol(s) to handle
362
+ * a `network` reference - the UUID of the network which the ip_address sits on.
363
+ * a backend `pool` to use, referenced by name
364
+
365
+ For example:
366
+
367
+ ```
368
+ name: test-virtual_server-1
369
+ description: Public facing side of test-pool-1
370
+ pool: test-pool-1
371
+ ip_address: 192.0.2.55 # front-end IP address, usually external
372
+ network: 12345678-1234-1234-1234-1234567890aa # UUID of network containing ip_address
373
+ service_profiles:
374
+ http: { port: 8080 } # override default port 80
375
+ https: { } # port defaults to 443
376
+ ```
377
+
378
+ See [the vCloud Director Admin Guide](http://pubs.vmware.com/vcd-51/topic/com.vmware.vcloud.admin.doc_51/GUID-EC5EE5F9-1A2C-4609-9347-4C3143727704.html)
379
+ for more details on configuring VirtualServer entries.
380
+
189
381
  ### Finding external network details from vcloud-walk
190
382
 
191
383
  You can find the network UUID and external address allocations using [vCloud
@@ -218,12 +410,28 @@ cat edges.out | jq '
218
410
  '
219
411
  ```
220
412
 
413
+ ### Full configuration examples
414
+
415
+ You can find full configuration examples in the `examples` folder.
221
416
 
222
417
 
223
- ### Debug output
418
+ ## Debugging
224
419
 
225
- Set environment variable `DEBUG=true` and/or `EXCON_DEBUG=true` to see Fog debug info.
420
+ `export EXCON_DEBUG=true` - this will print out the API requests and responses.
421
+
422
+ `export DEBUG=true` - this will show you the stack trace when there is an exception instead of just the message.
226
423
 
227
424
  ### References
228
425
 
229
426
  * [vCloud Director Edge Gateway documentation](http://pubs.vmware.com/vcd-51/topic/com.vmware.vcloud.admin.doc_51/GUID-ADE1DCAB-874F-45A9-9337-1E971DAC0F7D.html)
427
+
428
+ ## Contributing
429
+
430
+ 1. Fork it
431
+ 2. Create your feature branch (`git checkout -b my-new-feature`)
432
+ 3. Commit your changes (`git commit -am 'Add some feature'`)
433
+ 4. Push to the branch (`git push origin my-new-feature`)
434
+ 5. Create new Pull Request
435
+
436
+
437
+ [fog]: http://fog.io/
@@ -0,0 +1,50 @@
1
+ # Example configuration file for defining Firewall rules on the vShield Edge Gateway
2
+ #
3
+ # Note that applying this configuration file will replace the current FW rules on the vShield Edge Gateway.
4
+ #
5
+ # Quick tips:
6
+ # gateway: should contain the name of the edge gateway (human readable form, not the UUID)
7
+ #
8
+ ---
9
+ gateway: "My gateway name"
10
+ firewall_service:
11
+ enabled: true
12
+ policy: 'drop'
13
+ log_default_action: true
14
+ firewall_rules:
15
+
16
+ - :id: '1'
17
+ :enabled: true
18
+ :match_on_translate: false
19
+ :description: 'allow_ssh'
20
+ :policy: 'allow'
21
+ :protocols: 'tcp'
22
+ :destination_port_range: '22'
23
+ :destination_ip: '00.01.02.03'
24
+ :source_port_range: 'Any'
25
+ :source_ip: 'Any'
26
+ :enable_logging: true
27
+
28
+ - :id: '2'
29
+ :enabled: true
30
+ :match_on_translate: false
31
+ :description: 'allow_access_to_good_sunny_days'
32
+ :policy: 'allow'
33
+ :protocols: 'tcp'
34
+ :destination_port_range: 'Any'
35
+ :destination_ip: 'external'
36
+ :source_port_range: 'Any'
37
+ :source_ip: '12.18.0.0/24'
38
+ :enable_logging: true
39
+
40
+ - :id: '6'
41
+ :enabled: true
42
+ :match_on_translate: false
43
+ :description: 'network_to_internet_ICMP'
44
+ :policy: 'allow'
45
+ :protocols: "icmp"
46
+ :destination_port_range: 'Any'
47
+ :destination_ip: 'external'
48
+ :source_port_range: 'Any'
49
+ :source_ip: '12.16.0.0/24'
50
+ :enable_logging: true
@@ -0,0 +1,55 @@
1
+ # Example configuration file for defining Load Balancing rules on the vShield Edge Gateway
2
+ #
3
+ # Note that applying this configuration file will replace the current Load Balancing rules on the vShield Edge Gateway.
4
+ #
5
+ # Quick tips:
6
+ # gateway: should contain the name of the edge gateway (human readable form, not the UUID)
7
+ # network: should contain the UUID for the internet facing network (not the internal ones).
8
+ # You can find the UUID for the vcloud network object using vcloud-walker.
9
+ #
10
+ ---
11
+ gateway: "My gateway name"
12
+ load_balancer_service:
13
+ pools:
14
+ - name: 'pool-001'
15
+ description: 'pool for balancing http(s)"
16
+ service:
17
+ http:
18
+ port: 80
19
+ algorithm: 'IP_HASH'
20
+ health_check:
21
+ port: 80
22
+ uri: /
23
+ protocol: HTTP
24
+ health_threshold: 2
25
+ unhealth_threshold: 3
26
+ interval: 5
27
+ timeout: 15
28
+ https:
29
+ port: 443
30
+ algorithm: 'IP_HASH'
31
+ health_check:
32
+ port: 443
33
+ uri: /
34
+ protocol: SSL
35
+ health_threshold: 2
36
+ unhealth_threshold: 3
37
+ interval: 5
38
+ timeout: 15
39
+ members:
40
+ - ip_address: 192.168.1.1
41
+ - ip_address: 192.168.1.2
42
+ - ip_address: 192.168.1.3
43
+
44
+ virtual_servers:
45
+ - name: 'vs-website'
46
+ description: 'virtual server for my website"
47
+ ip_address: 20.20.20.20
48
+ network: '00000000-1111-2222-3333-444444444444'
49
+ pool: 'pool-001'
50
+ service_profiles:
51
+ http:
52
+ port: '80'
53
+ https:
54
+ port: '443'
55
+
@@ -0,0 +1,58 @@
1
+ # Example configuration file for defining NAT rules on the vShield Edge Gateway
2
+ #
3
+ # Note that applying this configuration file will replace the current SNAT/DNAT rules on the vShield Edge Gateway.
4
+ #
5
+ # Quick tips:
6
+ # gateway: should contain the name of the edge gateway (human readable form, not the UUID)
7
+ #
8
+ # network_id: you can find the UUID for the vcloud network object using vcloud-walker
9
+ #
10
+ ---
11
+ gateway: "My gateway name"
12
+ nat_service:
13
+ enabled: true
14
+ nat_rules:
15
+
16
+ - :id: '65537'
17
+ :enabled: true
18
+ :rule_type: 'DNAT'
19
+ :network_id: '00000000-1111-2222-3333-444444444444'
20
+ :original_ip: '00.01.02.03'
21
+ :original_port: '22'
22
+ :translated_ip: '10.20.30.40'
23
+ :translated_port: '22'
24
+ :protocol: 'tcp'
25
+
26
+ - :id: '65538'
27
+ :enabled: true
28
+ :rule_type: 'DNAT'
29
+ :network_id: '00000000-1111-2222-3333-444444444444'
30
+ :original_ip: '00.01.02.03'
31
+ :original_port: '80'
32
+ :translated_ip: '10.20.30.40'
33
+ :translated_port: '80'
34
+ :protocol: 'tcp'
35
+
36
+ - :id: '65539'
37
+ :enabled: true
38
+ :rule_type: 'DNAT'
39
+ :network_id: '00000000-1111-2222-3333-444444444444'
40
+ :original_ip: '00.01.02.03'
41
+ :original_port: '443'
42
+ :translated_ip: '10.20.30.40'
43
+ :translated_port: '443'
44
+ :protocol: 'tcp'
45
+
46
+ - :id: '65540'
47
+ :enabled: true
48
+ :rule_type: 'SNAT'
49
+ :network_id: '00000000-1111-2222-3333-444444444444'
50
+ :original_ip: '90.100.110.0/24'
51
+ :translated_ip: '00.01.02.03'
52
+
53
+ - :id: '65541'
54
+ :enabled: true
55
+ :rule_type: 'SNAT'
56
+ :network_id: '00000000-1111-2222-3333-444444444444'
57
+ :original_ip: '10.20.30.40/24'
58
+ :translated_ip: '00.01.02.03'