It has been a hectic few months for me. I relocated my family to Colorado last month, and as a result all of my side-projects were put on the back-burner. During the time I was away, I was selected for the fourth year in a row as a vExpert! I am grateful to be a part of this awesome community! I strive to make the work I do and submit here worthwhile and informative for others.
Now that I am back into the swing of things, I was able to jump back into improving the NSX-v Ansible module. Recently a member of the community opened an issue regarding the implementation method I had used for Edge NAT rules. Sure enough, they were correct in that the method I was using was really an append and not a creation.
Note: I wrote and tested the code against a pre-release version of NSX-v 6.4.1. There are no documented differences between the two API calls used in the nsx_edge_nat.py Ansible module in NSX 6.4.x or 6.3.x
When I looked at the NSX API, I realized there were two methods for adding NAT rules to an NSX Edge:
PUT /api/4.0/edges/{edgeId}/nat/config
URI Parameters:
edgeId (required) Specify the ID of the edge in edgeId.
Description:
Configure NAT rules for an Edge.
If you use this method to add new NAT rules, you must include all existing rules in the request body. Any rules that are omitted will be deleted.
And also:
POST /api/4.0/edges/{edgeId}/nat/config/rules
URI Parameters:
edgeId (required)
Specify the ID of the edge in edgeId.
Query Parameters:
aboveRuleId (optional)
Specified rule ID. If no NAT rules exist, you can specify rule ID 0.
Description:
Add a NAT rule above a specific rule in the NAT rules table (using aboveRuleId query parameter) or append NAT rules to the bottom.
The original code was using the second method, which meant each time an Ansible playbook was run, it would return an OK status because it was adding the rules — even if they already existed.
I decided to dive into the issue and spent a few more hours than I anticipated improving the code. It is now possible to use either method — one to create a full set of rules (deleting any existing rules) or appending new rules to the existing ruleset.
In order to create multiple rules, I modified how the Ansible playbook is interpreted. The example is in the readme.md file, but I want to highlight it here:
1 ---
2 - hosts: localhost
3 connection: local
4 gather_facts: False
5 vars_files:
6 - nsxanswer.yml
7 - envanswer.yml
8
9 tasks:
10 - name: Create NAT rules
11 nsx_edge_nat:
12 nsxmanager_spec: '{{ nsxmanager_spec }}'
13 mode: 'create'
14 name: '{{ edge_name }}'
15 rules:
16 dnat0: { description: 'Ansible created HTTP NAT rule',
17 loggingEnabled: 'true',
18 rule_type: 'dnat',
19 nat_enabled: 'true',
20 dnatMatchSourceAddress: 'any',
21 dnatMatchSourcePort: 'any',
22 vnic: '0',
23 protocol: 'tcp',
24 originalAddress: '10.180.138.131',
25 originalPort: '80',
26 translatedAddress: '192.168.0.2',
27 translatedPort: '80'
28 }
29 dnat1: { description: 'Ansible created HTTPS NAT rule',
30 loggingEnabled: 'true',
31 rule_type: 'dnat',
32 vnic: '0',
33 nat_enabled: 'true',
34 dnatMatchSourceAddress: 'any',
35 dnatMatchSourcePort: 'any',
36 protocol: 'tcp',
37 originalAddress: '10.180.138.131',
38 originalPort: '443',
39 translatedAddress: '192.168.0.2',
40 translatedPort: '443'
41 }
Please note the identifiers, dnat0 and dnat1, are merely that — identifiers for your playbook. They do not influence the API call made to the NSX Manager.
A new function was required in the Ansible module to allow for multiple rules to be appended to one another to make a single API call that would add each rule. The data structure used to create this dictionary of lists was rather convoluted since Python struggles to convert these sort of thing to XML properly. With some help from a few people in the NSBU, I was able to get it working.
def create_init_nat_rules:
55 def create_init_nat_rules(client_session, module):
56 """
57 Create single dictionary with all of the NAT rules, both SNAT and DNAT, to be used
58 in a single API call. Should be used when wiping out ALL existing rules or when
59 a new NSX Edge is created.
60 :return: return dictionary with the full NAT rules list
61 """
62 nat_rules = module.params['rules']
63 params_check_nat_rules(module)
64
65 nat_rules_info = {}
66 nat_rules_info['natRule'] = []
67
68 for rule_key, nat_rule in nat_rules.items():
69 rules_index = rule_key[-1:]
70 rule_type = nat_rule['rule_type']
71 if rule_type == 'snat':
72 nat_rules_info['natRule'].append(
73 {'action': rule_type, 'vnic': nat_rule['vnic'], 'originalAddress': nat_rule['originalAddress'],
74 'translatedAddress': nat_rule['translatedAddress'], 'loggingEnabled': nat_rule['loggingEnabled'],
75 'enabled': nat_rule['nat_enabled'], 'protocol': nat_rule['protocol'], 'originalPort': nat_rule['originalPort'],
76 'translatedPort': nat_rule['translatedPort'], 'snatMatchDestinationAddress': nat_rule['snatMatchDestinationAddress'],
77 'snatMatchDestinationPort': nat_rule['snatMatchDestinationPort'], 'description': nat_rule['description']
78 }
79 )
80 elif rule_type == 'dnat':
81 nat_rules_info['natRule'].append(
82 {'action': rule_type, 'vnic': nat_rule['vnic'], 'originalAddress': nat_rule['originalAddress'],
83 'translatedAddress': nat_rule['translatedAddress'], 'loggingEnabled': nat_rule['loggingEnabled'],
84 'enabled': nat_rule['nat_enabled'], 'protocol': nat_rule['protocol'], 'originalPort': nat_rule['originalPort'],
85 'translatedPort': nat_rule['translatedPort'], 'dnatMatchSourceAddress': nat_rule['dnatMatchSourceAddress'],
86 'dnatMatchSourcePort': nat_rule['dnatMatchSourcePort'], 'description': nat_rule['description']
87 }
88 )
89
90 if nat_rule['protocol'] == 'icmp':
91 nat_rules_info['natRule']['icmpType'] = nat_rule['icmpType']
92
93 return nat_rules_info
I also took the opportunity to clean up some of the excessively long lines of code to make it more clearly readable. The result is a new working playbook for initial Edge NAT rule creation and the ability to add new rules later. There are a few items that remain where I would like to see some improvements — mainly I would like to add logic in to the code that, when performing an append, it will check to see if the rule already exists and skip it.
In the meantime, the code has been checked into GitHub and the Docker image I use for running Ansible has been updated.
Enjoy!
