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,23 +29,22 @@ 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`):
**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.
89
+
71
90
4. **Run the Playbook**
72
91
73
92
```bash
74
93
ansible-playbook maas_nameserver.yml
75
94
```
76
95
77
-
## Variables
78
-
79
-
### defaults/main.yml
80
-
81
-
These are overridable defaults:
82
-
83
-
- `maas_api_url`: Default MAAS API endpoint (`http://localhost:5240/MAAS/api/2.0/`). Override in `secrets/maas.yml`.
96
+
For verbose output to troubleshoot:
84
97
85
-
- `maas_profile`: Default MAAS profile name (`admin`). Override in `secrets/maas.yml`.
86
-
87
-
- `default_domains`: Domains to preserve (default: `["maas"]`). The `maas` domain is used by MAAS for internal DNS records and is excluded from cleanup.
98
+
```bash
99
+
ansible-playbook maas_nameserver.yml -vvvv
100
+
```
88
101
89
-
- `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`:
- `maas_server_ip`: Derived from the first host in the `maas` group (`{{ groups.get('maas', []) | first | default('undefined_maas_server') }}`).
109
+
- `maas_api_url`: MAAS API endpoint (`http://{{ maas_server_ip }}:5240/MAAS`).
110
+
- `dns_ttl`: Default TTL for DNS records (`3600` seconds).
111
+
- `excluded_groups`: Groups to exclude from inventory processing (`["all", "ungrouped"]`).
112
+
- `excluded_domains`: Domains to preserve from cleanup (`["maas", "front.sepia.example.com"]`).
113
+
- `supported_record_types`: Allowed DNS record types (`["A/AAAA", "CNAME", "MX", "NS", "SRV", "SSHFP", "TXT"]`).
102
114
103
-
- `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`:
- **Cleanup**: Deletes DNS records and domains not in `dns_domains` or `default_domains`.
151
+
- **DNS Records**: Creates A/AAAA records for hosts based on `dns_domains` and inventory variables (e.g., `ip`, `ipmi`). Example:
152
+
- `server01.example.com`→ `192.168.1.11`
153
+
- `server01.ipmi.example.com`→ `192.168.2.11`
154
+
- Additional records from `dns_records` (e.g., `api.ocp1.example.com` → `192.168.1.101`).
155
+
- **Cleanup**: Deletes DNS records and domains not in `dns_domains` or `excluded_domains`, skipping default MAAS domains.
156
+
- **NS Records**: Skipped due to module limitations; create manually via MAAS CLI or UI.
152
157
- **Idempotency**: Skips actions if the desired state is already met.
158
+
- **Retries**: Removal tasks include retries (`retries: 3`, `delay: 5`) to handle transient network issues.
153
159
154
160
## Troubleshooting
155
161
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`.
162
+
- **Network Issues**: If you see `[Errno -2] Name or service not known`, verify the MAAS server hostname (e.g., `maas-server.example.com`) resolves correctly:
Add to `/etc/hosts` if needed (e.g., `192.168.1.10 maas-server.example.com`).
168
+
169
+
- **Missing dns_domains**: Ensure `dns_domains` is defined in `inventory/group_vars/all.yml`.
170
+
171
+
- **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:
- **Slow Execution**: Enable profiling to identify bottlenecks:
191
+
```bash
192
+
ansible-playbook maas_nameserver.yml -v
193
+
```
194
+
Adjust `ansible.cfg` for higher parallelism:
195
+
```ini
196
+
[defaults]
197
+
forks = 20
198
+
```
199
+
200
+
## Performance Optimizations
201
+
202
+
- **Inventory Filtering**: Only hosts with `ip` or `ipmi` variables are processed, reducing unnecessary iterations.
203
+
- **Retries for Reliability**: Removal tasks use retries to handle transient network issues, improving robustness for large inventories (e.g., 48 hosts).
204
+
205
+
For further optimization, consider enabling fact caching in `ansible.cfg` to reduce API calls in subsequent runs:
0 commit comments