maas dns role for configuring maas dns domains and records

Signed-off-by: Adam Kraitman <akraitma@li-8b09b2cc-35b7-11b2-a85c-cd1dbade58f9.ibm.com>

Author: Adam Kraitman

maas_nameserver.yml

@@ -0,0 +1,6 @@
+---
+- name: Configure MAAS DNS
+  hosts: maas
+  gather_facts: false
+  roles:
+    - maas_nameserver

roles/maas_nameserver/README.md

@@ -0,0 +1,164 @@
+# maas_nameserver Ansible Role
+
+## Overview
+
+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.
+
+## Requirements
+
+- Ansible: Version 2.9 or higher
+- MAAS CLI: Installed on the target MAAS server
+- Inventory: A valid Ansible inventory with `group_vars/all.yml` defining `dns_domains`
+
+## Role Structure
+
+```
+roles/
+  maas_nameserver/
+    defaults/
+      main.yml
+    tasks/
+      main.yml
+    meta/
+      main.yml
+    README.md
+```
+
+## Dependencies
+
+- **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`.
+
+## Usage
+
+1. **Place the Role**
+
+   Ensure the `maas_nameserver` role is in your `roles/` directory.
+
+2. **Prepare Inventory**
+
+   Define your `maas` and target host groups:
+
+   ```ini
+   [maas]
+   maas.internal.ceph.ibm.com ip=10.11.120.237
+
+   [snipeit]
+   snipe-it.internal.ceph.ibm.com ip=10.60.100.11
+
+   [machine]
+   machine001.internal.ceph.ibm.com ip=10.18.131.100 ipmi=10.18.139.100 vlan104=10.18.144.3
+   ```
+
+3. **Set Up Inventory Variables**
+
+   Define `dns_domains` in `group_vars/all.yml`:
+
+   ```yaml
+   ---
+   dns_domains:
+     ceph: "internal.ceph.ibm.com"
+     ipmi: "ipmi.ceph.ibm.com"
+     vlan104: "vlan104.internal.ceph.ibm.com"
+   ```
+
+4. **Set Up Secrets**
+
+   Create a secrets file at `{{ secrets_path }}/maas.yml`:
+
+   ```yaml
+   ---
+   maas_api_key: "XXXXXXXXXXXXXXXX"
+   maas_api_url: "http://localhost:5240/MAAS/api/2.0/"
+   maas_profile: "admin"
+   ```
+
+5. **Run the Playbook**
+
+   ```bash
+   ansible-playbook maas_nameserver.yml
+   ```
+
+## Variables
+
+### defaults/main.yml
+
+These are overridable defaults:
+
+- `maas_api_url`: Default MAAS API endpoint (`http://localhost:5240/MAAS/api/2.0/`). Override in `secrets/maas.yml`.
+
+- `maas_profile`: Default MAAS profile name (`admin`). Override in `secrets/maas.yml`.
+
+- `default_domains`: Domains to preserve (default: `["maas"]`). The `maas` domain is used by MAAS for internal DNS records and is excluded from cleanup.
+
+- `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 `secrets/maas.yml` or via extra vars:
+
+  ```yaml
+  target_hosts:
+    - machine001.internal.ceph.ibm.com
+    - machine002.internal.ceph.ibm.com
+  ```
+
+  Or via command line:
+
+  ```bash
+  ansible-playbook maas_nameserver.yml -e "target_hosts=['machine001.internal.ceph.ibm.com']"
+  ```
+
+- `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 `secrets/maas.yml` or via extra vars:
+
+  ```yaml
+  exclude_groups: ["maas", "all", "ungrouped", "other_group"]
+  ```
+
+### vars/main.yml
+
+No mandatory, non-overridable variables are defined. Environment-specific variables like `dns_domains` must be set in `inventory/group_vars/all.yml`.
+
+### secrets/maas.yml
+
+Provides MAAS API credentials and optional overrides:
+
+1. `maas_api_key`: MAAS API key for authentication.
+2. `maas_api_url`: MAAS API endpoint (e.g., `http://127.0.0.1:5240/MAAS/api/2.0/`).
+
+`maas_profile`: MAAS CLI profile name (e.g., `admin`).
+
+1. `target_hosts` (optional): Override the default `target_hosts` list.
+2. `exclude_groups` (optional): Override the default `exclude_groups` list.
+
+**Example**:
+
+```yaml
+maas_api_key: "XXXXXXXXXXXXXXXX"
+maas_api_url: "http://127.0.0.1:5240/MAAS/api/2.0/"
+maas_profile: "admin"
+# Optional overrides
+target_hosts:
+  - machine001.internal.ceph.ibm.com
+exclude_groups:
+  - maas
+  - all
+  - ungrouped
+```
+
+**Notes**:
+
+- **Security**: Ensure file permissions are restricted (e.g., `chmod 600 maas.yml`).
+- **Vault**: If encrypted, provide the vault password (e.g., via `--vault-password-file ~/.vault_pass.txt`).
+
+## Behavior
+
+- **DNS Records**: Creates A records for hosts based on `dns_domains` and inventory variables (e.g., `ip`, `ipmi`, `vlan104`). Example:
+  - `machine001.internal.ceph.ibm.com` → `10.18.131.100`
+  - `machine001.ipmi.ceph.ibm.com` → `10.18.139.100`
+  - `machine001.vlan104.internal.ceph.ibm.com` → `10.18.144.3`
+- **Cleanup**: Deletes DNS records and domains not in `dns_domains` or `default_domains`.
+- **Idempotency**: Skips actions if the desired state is already met.
+
+## Troubleshooting
+
+- **Missing** `dns_domains`: Ensure `dns_domains` is defined in `inventory/group_vars/all.yml`. The playbook will fail if undefined.
+- **Secrets Not Loading**: Verify `secrets_path` points to the correct directory and `maas.yml` contains valid credentials.
+- **MAAS CLI Errors**: Confirm the MAAS CLI is installed on the target server and the API key is valid.
+- **Failed Deletions**: Check playbook output for errors during DNS record or domain deletions (e.g., permissions, network issues, or records that do not exist).
+- **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`.

roles/maas_nameserver/defaults/main.yml

@@ -0,0 +1,17 @@
+---
+maas_api_url: "http://localhost:5240/MAAS/api/2.0/"  # Default, overridden by secrets
+maas_profile: "admin"  # Default, overridden by secrets
+default_domains:
+  - "maas"
+
+# List of target hosts for DNS records, excluding the 'maas' group by default.
+# Can be overridden in secrets/maas.yml (e.g., target_hosts: ['host1.example.com', 'host2.example.com'])
+# If not set, defaults to all hosts in inventory groups except those in exclude_groups.
+target_hosts: []
+
+# List of inventory groups to exclude from target_hosts.
+# Includes 'all' and 'ungrouped' to prevent automatic inclusion of all hosts or ungrouped hosts,
+# as 'all' contains every host in the inventory and 'ungrouped' includes hosts not assigned to any group.
+exclude_groups: ["maas", "all", "ungrouped"]
+
+# Note: dns_domains should be defined in the inventory's group_vars/all.yml

roles/maas_nameserver/meta/main.yml

@@ -0,0 +1,3 @@
+---
+dependencies:
+  - role: secrets

roles/maas_nameserver/tasks/main.yml

@@ -0,0 +1,117 @@
+---
+# Include secrets from maas.yml (e.g., maas_api_key, maas_api_url).
+# Note: dns_domains should be defined in the inventory's group_vars/all.yml
+- name: Include secrets
+  ansible.builtin.include_vars: "{{ item }}"
+  no_log: true
+  with_first_found:
+    - "{{ secrets_path | mandatory }}/maas.yml"
+  tags:
+    - always
+
+- name: Ensure MAAS CLI is logged in
+  ansible.builtin.command: "maas login {{ maas_profile }} {{ maas_api_url }} {{ maas_api_key }}"
+  register: maas_login
+  changed_when: maas_login.rc == 0
+  failed_when: maas_login.rc != 0 and maas_login.stderr != "Profile already exists"
+
+- name: Get existing DNS resources
+  ansible.builtin.command: "maas {{ maas_profile }} dnsresources read"
+  register: existing_resources
+  changed_when: false
+
+- name: Initialize DNS records list
+  ansible.builtin.set_fact:
+    dns_records: []
+
+# Define target hosts list for DNS records, excluding the 'maas' group.
+- name: Initialize target hosts list
+  ansible.builtin.set_fact:
+    target_hosts_list: []
+
+- name: Build target hosts list
+  ansible.builtin.set_fact:
+    target_hosts_list: "{{ target_hosts_list + item.value }}"
+  loop: "{{ groups | dict2items }}"
+  when: item.key not in exclude_groups
+
+# After population, target_hosts will contain all hosts from inventory groups except 'maas', e.g.,
+# ['machine001.internal.example.com', 'snipe.internal.example.com', 'vm-14.example.com'].
+# This can be overridden in secrets/maas.yml (e.g., target_hosts: ['host1.example.com', 'host2.example.com'])
+# or via extra vars (e.g., -e "target_hosts=['host1.example.com']").
+- name: Define target hosts for DNS records
+  ansible.builtin.set_fact:
+    target_hosts: "{{ target_hosts if target_hosts | length > 0 else (target_hosts_list | flatten | unique | default([])) }}"
+  when: groups.keys() | length > 0
+
+- name: Build DNS records for all interfaces
+  ansible.builtin.set_fact:
+    dns_records: "{{ dns_records + [{'name': item[0].split('.')[0], 'ip': interface_ip, 'type': 'A', 'domain': item[1].value}] }}"
+  loop: "{{ (target_hosts | default([])) | product(dns_domains | dict2items) | list }}"
+  vars:
+    interface_ip: "{{ hostvars[item[0]][item[1].key] if item[1].key != 'ceph' else hostvars[item[0]]['ip'] }}"
+  when:
+    - target_hosts is defined and target_hosts | length > 0
+    - "item[1].key in hostvars[item[0]] or (item[1].key == 'ceph' and 'ip' in hostvars[item[0]])"
+
+- name: Parse desired FQDNs
+  ansible.builtin.set_fact:
+    desired_fqdns: "{{ dns_records | map(attribute='name') | zip(dns_records | map(attribute='domain')) | map('join', '.') | list }}"
+  when: dns_records | length > 0
+
+- name: Remove unwanted DNS records
+  ansible.builtin.command: "maas {{ maas_profile }} dnsresource delete {{ item.id }}"
+  loop: "{{ existing_resources.stdout | from_json }}"
+  when: >
+    dns_records | length > 0 and
+    item.fqdn not in desired_fqdns
+  register: dns_deletion
+  failed_when: dns_deletion.rc != 0 and "does not exist" not in dns_deletion.stderr
+
+- name: Get updated DNS resources after deletions
+  ansible.builtin.command: "maas {{ maas_profile }} dnsresources read"
+  register: updated_resources
+  changed_when: false
+
+- name: Get existing DNS domains
+  ansible.builtin.command: "maas {{ maas_profile }} domains read"
+  register: existing_domains
+  changed_when: false
+
+- name: Parse existing domains
+  ansible.builtin.set_fact:
+    current_domains: "{{ existing_domains.stdout | from_json | map(attribute='name') | list }}"
+
+- name: Remove unwanted domains
+  ansible.builtin.command: "maas {{ maas_profile }} domain delete {{ item.id }}"
+  loop: "{{ existing_domains.stdout | from_json }}"
+  when: >
+    item.name not in default_domains and
+    item.name not in dns_domains.values()
+  register: domain_deletion
+  failed_when: domain_deletion.rc != 0 and "does not exist" not in domain_deletion.stderr and "protected foreign keys" not in domain_deletion.stderr
+
+- name: Ensure new DNS domains exist
+  ansible.builtin.command: "maas {{ maas_profile }} domains create name={{ item.value }}"
+  loop: "{{ dns_domains | dict2items }}"
+  when: item.value not in current_domains
+  register: domain_creation
+  failed_when: domain_creation.rc != 0 and "already exists" not in domain_creation.stderr
+
+- name: Ensure DNS records exist
+  ansible.builtin.command: >
+    maas {{ maas_profile }} dnsresources create
+    fqdn={{ item.name }}.{{ item.domain }}
+    ip_addresses={{ item.ip }}
+  loop: "{{ dns_records }}"
+  when: >
+    dns_records | length > 0 and
+    (item.name + '.' + item.domain) not in 
+    (updated_resources.stdout | from_json | map(attribute='fqdn') | list)
+  register: dns_creation
+  failed_when: dns_creation.rc != 0 and "already exists" not in dns_creation.stderr
+
+- name: Logout from MAAS
+  ansible.builtin.command: "maas logout {{ maas_profile }}"
+  when: maas_login is success
+  changed_when: true