You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This commit introduces the maas_nameserver Ansible role to configure DNS domains and records in MAAS (Metal as a Service) based on an Ansible inventory. Key features include:
- Configures DNS entries for hosts (e.g., main interfaces, IPMI interfaces) using `dns_domains` and inventory variables (`ip`, `ipmi`).
- Dynamically sets `maas_cluster_instance.host` via `maas_api_url` in `defaults/main.yml`, with credentials (`customer_key`, `token_key`, `token_secret`) loaded from a secrets file (`secrets/maas.yml`).
- Filters inventory to process only hosts with `ip` or `ipmi` variables, excluding groups like `all` and `ungrouped`.
- Cleans up unwanted DNS records and domains not in `dns_domains` or `excluded_domains`, skipping default MAAS domains.
- Skips NS record creation due to module limitations, with instructions for manual creation via MAAS CLI/UI.
- Includes comprehensive `README.md` with:
- Inventory example with `mac`, `ip`, `ipmi`, and `bmc` attributes (e.g., `server01.example.com mac=00:1a:2b:3c:4d:5e ip=192.168.1.11 ipmi=192.168.2.11 bmc=00:1a:2b:3c:4d:5f`).
- Setup instructions for inventory, secrets, and variables.
- Troubleshooting for common issues (e.g., network errors, missing `dns_domains`).
- Performance tips (e.g., fact caching).
- Ensures idempotency and supports large inventories.
Signed-off-by: Adam Kraitman <akraitma@li-8b09b2cc-35b7-11b2-a85c-cd1dbade58f9.ibm.com>
The `maas_nameserver` role configures DNS domains and records in MAAS (Metal as a Service) based on an Ansible inventory. It manages DNS entries for hosts (e.g., Main interfaces, IPMI interfaces, VLAN interfaces) in specified domains, ensuring only desired records and domains exist while cleaning up unwanted ones. This role depends on a secrets file to load MAAS API credentials.
5
+
The `maas_nameserver` role configures DNS domains and records in MAAS (Metal as a Service) based on an Ansible inventory. It manages DNS entries for hosts (e.g., main interfaces, IPMI interfaces) in specified domains, ensuring only desired records and domains exist while cleaning up unwanted ones. This role depends on a secrets file to load MAAS API credentials.
6
6
7
7
## Requirements
8
8
9
9
- Ansible: Version 2.9 or higher
10
10
- MAAS CLI: Installed on the target MAAS server
11
+
- Python: Version 3.6 or higher (for `maas.maas` collection)
11
12
- Inventory: A valid Ansible inventory with `group_vars/all.yml` defining `dns_domains`
13
+
- MAAS API Access: Valid credentials in a secrets file
14
+
- Network: Stable connectivity to the MAAS server
12
15
13
16
## Role Structure
14
17
@@ -26,135 +29,203 @@ roles/
26
29
27
30
## Dependencies
28
31
29
-
-**Secrets File**: A `maas.yml` file at `{{ secrets_path }}/maas.yml` provides MAAS API credentials (e.g., `maas_api_key`, `maas_api_url`). No separate secrets role is required; credentials are loaded via `include_vars`.
32
+
-**Secrets File**: A `maas.yml` file at `{{ secrets_path }}/maas.yml` provides MAAS API credentials (`maas_cluster_instance` with `customer_key`, `token_key`, and `token_secret`). The `host` is set dynamically at runtime.
33
+
-**maas.maas Collection**: Automatically installed by the role if not present.
30
34
31
35
## Usage
32
36
33
37
1.**Prepare Inventory**
34
38
35
-
Define your `maas` and target host groups:
39
+
Define your `maas`group and target hosts in your inventory file (e.g., `inventory/hosts`):
Define `dns_domains` in `group_vars/all.yml` to specify the domains for A/AAAA records derived from inventory hosts (e.g., `ip` and `ipmi` variables):
51
53
52
54
```yaml
53
55
---
54
56
dns_domains:
55
-
ceph: "internal.ceph.ibm.com"
56
-
ipmi: "ipmi.ceph.ibm.com"
57
-
vlan104: "vlan104.internal.ceph.ibm.com"
57
+
ip: "example.com"
58
+
ipmi: "ipmi.example.com"
59
+
```
60
+
61
+
Optionally, define `dns_records` in `group_vars/dns_records.yml` to configure additional DNS records. This file is used for:
62
+
- **Hosts outside the Ansible inventory**: Records for external services or devices not managed in the inventory (e.g., third-party servers, wildcard records).
63
+
- **Non-A/AAAA record types**: Records such as MX, SRV, TXT, or CNAME, which require specific attributes (e.g., priority, target, port) not derived from inventory variables like `ip` or `ipmi`.
64
+
65
+
Example `group_vars/dns_records.yml`:
66
+
67
+
```yaml
68
+
---
69
+
dns_records:
70
+
- name: "api"
71
+
domain: "ocp1.example.com"
72
+
type: "A/AAAA"
73
+
ip: "192.168.1.101"
74
+
- name: "*"
75
+
domain: "apps.ocp1.example.com"
76
+
type: "A/AAAA"
77
+
ip: "192.168.1.102"
78
+
- name: "mail"
79
+
domain: "example.com"
80
+
type: "MX"
81
+
priority: 10
82
+
target: "mailserver.example.com"
83
+
- name: "_sip._tcp"
84
+
domain: "example.com"
85
+
type: "SRV"
86
+
priority: 10
87
+
weight: 60
88
+
port: 5060
89
+
target: "sipserver.example.com"
58
90
```
59
91
60
92
3. **Set Up Secrets**
61
93
62
-
Create a secrets file at `{{ secrets_path }}/maas.yml`:
94
+
Create a secrets file at `{{ secrets_path }}/maas.yml` (e.g., `secrets/maas.yml`):
63
95
64
96
```yaml
65
97
---
66
-
maas_profile: "admin" # also called the maas api username
67
-
maas_api_key: "XXXXXXXXXXXXXXXX" # api key of the profile defined in maas_profile
**Note**: The `host` field is not included in `maas_cluster_instance` as it is set dynamically using `maas_api_url` from `defaults/main.yml` and the `maas` group in the inventory. Restrict file permissions (e.g., `chmod 600 secrets/maas.yml`) and consider using Ansible Vault for encryption.
105
+
71
106
4. **Run the Playbook**
72
107
73
108
```bash
74
109
ansible-playbook maas_nameserver.yml
75
110
```
76
111
112
+
For verbose output to troubleshoot:
113
+
114
+
```bash
115
+
ansible-playbook maas_nameserver.yml -v
116
+
```
117
+
77
118
## Variables
78
119
79
120
### defaults/main.yml
80
121
81
-
These are overridable defaults:
122
+
Overridable defaults:
82
123
83
-
- `maas_api_url`: Default MAAS API endpoint (`http://localhost:5240/MAAS/api/2.0/`). Override in `secrets/maas.yml`.
124
+
- `maas_server_ip`: Derived from the first host in the `maas` group (`{{ groups.get('maas', []) | first | default('undefined_maas_server') }}`).
125
+
- `maas_api_url`: MAAS API endpoint (`http://{{ maas_server_ip }}:5240/MAAS`).
126
+
- `dns_ttl`: Default TTL for DNS records (`3600` seconds).
127
+
- `excluded_groups`: Groups to exclude from inventory processing (`["all", "ungrouped"]`).
128
+
- `excluded_domains`: Domains to preserve from cleanup (`["maas", "front.sepia.example.com"]`).
129
+
- `supported_record_types`: Allowed DNS record types (`["A/AAAA", "CNAME", "MX", "NS", "SRV", "SSHFP", "TXT"]`).
84
130
85
-
- `maas_profile`: Default MAAS profile name (`admin`). Override in `secrets/maas.yml`.
131
+
Example `defaults/main.yml`:
86
132
87
-
- `default_domains`: Domains to preserve (default: `["maas"]`). The `maas` domain is used by MAAS for internal DNS records and is excluded from cleanup.
133
+
```yaml
134
+
---
135
+
maas_server_ip: "{{ groups.get('maas', []) | first | default('undefined_maas_server') }}"
- `target_hosts`: List of hosts for DNS records. Defaults to an empty list (`[]`), in which case the role dynamically selects all hosts from inventory groups except those in `exclude_groups`. Override in `group_vars/maas.yml`:
143
+
### vars/main.yml
90
144
91
-
```yaml
92
-
target_hosts:
93
-
- machine001.internal.ceph.ibm.com
94
-
- machine002.internal.ceph.ibm.com
95
-
```
145
+
No mandatory, non-overridable variables are defined. Environment-specific variables like `dns_domains` must be set in `inventory/group_vars/all.yml`.
- `exclude_groups`: List of inventory groups to exclude from `target_hosts` when `target_hosts` is empty. Defaults to `["maas", "all", "ungrouped"]`. The `all` and `ungrouped` groups must be included to prevent the automatic inclusion of all hosts (via the `all` group, which contains every host in the inventory) or ungrouped hosts (via the `ungrouped` group). Override in `group_vars/maas.yml`:
151
+
- `maas_cluster_instance.customer_key`: MAAS API customer key.
152
+
- `maas_cluster_instance.token_key`: MAAS API token key.
153
+
- `maas_cluster_instance.token_secret`: MAAS API token secret.
No mandatory, non-overridable variables are defined. Environment-specific variables like `dns_domains` must be set in `inventory/group_vars/all.yml`.
165
+
## Behavior
112
166
113
-
### secrets/maas.yml
167
+
- **DNS Records**: Creates A/AAAA records for hosts based on `dns_domains` and inventory variables (e.g., `ip`, `ipmi`). Example:
168
+
- `server01.example.com`→ `192.168.1.11`
169
+
- `server01.ipmi.example.com`→ `192.168.2.11`
170
+
- Additional records from `dns_records` (e.g., `api.ocp1.example.com` → `192.168.1.101`, MX/SRV records).
171
+
- **Cleanup**: Deletes DNS records and domains not in `dns_domains` or `excluded_domains`, skipping default MAAS domains, with retries to handle transient network issues.
172
+
- **NS Records**: Skipped due to module limitations; a notification is displayed for skipped NS records, which must be created manually via MAAS CLI or UI.
173
+
- **Idempotency**: Skips actions if the desired state is already met.
174
+
- **Retries**: All tasks creating or deleting DNS records or domains include retries (`retries: 3`, `delay: 5`) to handle transient network issues (e.g., `TimeoutError`).
175
+
- **Result Display**: Displays results for created or updated DNS domains, inventory host DNS records, and static DNS records from `dns_records`.
114
176
115
-
Provides MAAS API credentials and optional overrides:
177
+
## Troubleshooting
116
178
117
-
1. `maas_api_key`: MAAS API key for authentication.
118
-
2. `maas_api_url`: MAAS API endpoint (e.g., `http://127.0.0.1:5240/MAAS/api/2.0/`).
179
+
- **Network Issues**: If you see `[Errno -2] Name or service not known` or `TimeoutError`, verify the MAAS server hostname (e.g., `maas-server.example.com`) resolves correctly and the server is responsive:
Add to `/etc/hosts` if needed (e.g., `192.168.1.10 maas-server.example.com`). Check network stability or MAAS server load if timeouts persist.
119
185
120
-
`maas_profile`: MAAS CLI profile name (e.g., `admin`).
186
+
- **Missing dns_domains**: Ensure `dns_domains` is defined in `group_vars/all.yml`.
121
187
122
-
1. `target_hosts` (optional): Override the default `target_hosts` list.
123
-
2. `exclude_groups` (optional): Override the default `exclude_groups` list.
188
+
- **Missing dns_records**: Ensure `dns_records` is defined in `group_vars/dns_records.yml` for non-inventory hosts or non-A/AAAA records, if needed.
124
189
125
-
**Example**:
190
+
- **Secrets Not Loading**: Verify `secrets_path` points to the correct directory and `maas.yml` contains valid credentials. If using Ansible Vault, provide the vault password:
- **Cleanup**: Deletes DNS records and domains not in `dns_domains` or `default_domains`.
152
-
- **Idempotency**: Skips actions if the desired state is already met.
219
+
## Performance Optimizations
153
220
154
-
## Troubleshooting
221
+
- **Inventory Filtering**: Only hosts with `ip` or `ipmi` variables are processed, reducing unnecessary iterations.
222
+
- **Retries for Reliability**: All tasks that create or delete DNS records or domains use retries (`retries: 3`, `delay: 5`) to handle transient network issues, improving robustness for large inventories (e.g., 48 hosts).
223
+
- **Minimal Debug Output**: Includes only essential debug output for NS record skip notifications and results of DNS domain and record creation to provide feedback without excessive overhead.
155
224
156
-
- **Missing** `dns_domains`: Ensure `dns_domains` is defined in `inventory/group_vars/all.yml`. The playbook will fail if undefined.
157
-
- **Secrets Not Loading**: Verify `secrets_path` points to the correct directory and `maas.yml` contains valid credentials.
158
-
- **MAAS CLI Errors**: Confirm the MAAS CLI is installed on the target server and the API key is valid.
159
-
- **Failed Deletions**: Check playbook output for errors during DNS record or domain deletions (e.g., permissions, network issues, or records that do not exist).
160
-
- **Unwanted DNS Records**: If DNS records are created for unintended hosts, verify `exclude_groups` includes `all` and `ungrouped` to prevent the inclusion of all inventory hosts or ungrouped hosts. Check for overrides in `secrets/maas.yml` or extra vars that modify `target_hosts` or `exclude_groups`.
225
+
For further optimization, consider enabling fact caching in `ansible.cfg` to reduce API calls in subsequent runs:
0 commit comments