From bd5ebcbea48a7d97f830034c077879baf36ce3ad Mon Sep 17 00:00:00 2001 From: Stonewall Jackson Date: Sat, 18 Feb 2023 21:06:36 -0500 Subject: proxmox: add docs --- inventory-example/group_vars/all/proxmox.yml | 2 +- playbooks/util/decomission_host.yml | 2 +- roles/proxmox_hypervisor/README.md | 77 ++++++++++++++++++++++ roles/proxmox_hypervisor/defaults/main.yml | 9 ++- roles/proxmox_hypervisor/tasks/nagios.yml | 2 +- roles/proxmox_hypervisor/tasks/pve_api_user.yml | 8 +-- .../templates/etc/postfix/main.cf.j2 | 4 +- .../templates/etc/snmp/snmpd.conf.j2 | 2 +- roles/proxmox_instance/tasks/main.yml | 6 +- 9 files changed, 94 insertions(+), 18 deletions(-) create mode 100644 roles/proxmox_hypervisor/README.md diff --git a/inventory-example/group_vars/all/proxmox.yml b/inventory-example/group_vars/all/proxmox.yml index 44cb9a1..f8d800a 100644 --- a/inventory-example/group_vars/all/proxmox.yml +++ b/inventory-example/group_vars/all/proxmox.yml @@ -1,7 +1,7 @@ # These settings are used when provisioning new proxmox VMs. --- proxmox_api_host: '{{ groups["proxmox_hypervisors"] | first }}' -proxmox_api_user: ansible@pam +proxmox_api_user: ansible proxmox_api_password: '{{ vault_proxmox_api_password }}' proxmox_node: '{{ proxmox_api_host }}' proxmox_password_salt: '{{ vault_proxmox_password_salt }}' diff --git a/playbooks/util/decomission_host.yml b/playbooks/util/decomission_host.yml index dae4b16..01faffa 100644 --- a/playbooks/util/decomission_host.yml +++ b/playbooks/util/decomission_host.yml @@ -47,7 +47,7 @@ proxmox_kvm: node: '{{ proxmox_node }}' api_host: localhost - api_user: '{{ proxmox_api_user }}' + api_user: '{{ proxmox_api_user }}@pam' api_password: '{{ proxmox_api_password }}' name: '{{ inventory_hostname }}' force: yes diff --git a/roles/proxmox_hypervisor/README.md b/roles/proxmox_hypervisor/README.md new file mode 100644 index 0000000..0ac6069 --- /dev/null +++ b/roles/proxmox_hypervisor/README.md @@ -0,0 +1,77 @@ +Proxmox Hypervisor +================== + +Description +----------- + +The `proxmox_hypervisor` role prepares a Proxmox server to run Rocky Linux +virtual machines via the [proxmox\_instance](../proxmox_instance/) role. + +This role is rather large, because it also performs the all the base +configuration that is otherwise performed by the [common](../common/) +role. This does result in some Ansible duplication--but since the Proxmox server +is the only non-Rocky-Linux host in my network, I didn't want to convolute all +the other roles with distro-specific branching. + +VM templates are generated from the image URLs listed in the [vars file](vars/main.yml). + +I would recommend against setting the FreeIPA DNS servers in `resolv.conf` on +the Proxmox host. If your VM is down, you'll lose DNS resolution on the +hypervisor. + + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +----------------------------------|---------------------------|------------ +`proxmox_api_user` | `ansible` | Proxmox API user (will be created) +`proxmox_api_password` |   | Proxmox API pasword +`proxmox_ntp_servers` | `{{ vlan.ntp_servers }}` | NTP servers +`proxmox_postfix_myorigin` | `{{ email_domain }}` | Default sender domain (see [documentation](https://www.postfix.org/postconf.5.html#myorigin)) +`proxmox_postfix_relayhost` | `{{ email_domain }}` | Next-hop destination for mail delivery (see [documentation](https://www.postfix.org/postconf.5.html#relayhost)) +`proxmox_syslog_host` | `{{ syslog_host_ip }}` | Syslog target IP +`proxmox_syslog_port` | 514 | Syslog target port +`proxmox_syslog_proto` | `tcp` | Syslog transport protocol +`proxmox_sudo_mailto` | `root` | Email address for sudo logging +`proxmox_bridge` | `vmbr0` | Template VM bridge interface +`proxmox_storage` | `local-zfs` | Template VM storage name +`proxmox_zfs_trim_on_calendar` | `monthly` | Systemd [calendar interval](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events) for ZFS SSD trim +`proxmox_zfs_scrub_on_calendar` | `monthly` | Systemd [calendar interval](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events) for ZFS scrub +`proxmox_zed_email` | `root` | Destination em +`proxmox_zed_verbose` | yes | Email address for ZFS Event Daemon (ZED) alerts +`proxmox_zed_notify_interval_sec` | 3600 | Notification interval for ZED alerts (seconds) +`proxmox_nagios_ssh_pubkey` | `{{ nagios_ssh_pubkey }}` | Nagios SSH public key +`proxmox_snmp_location` | `unknown` | SNMP location string +`proxmox_snmp_contact` | `root@{{ email_domain }}` | SNMP contact +`proxmox_snmp_v3_users` | `nagios` snmp user | SNMPv3 user list (see [format](#proxmox_snmp_v3_users) below) + + +### proxmox\_snmp\_users + +The `proxmox_snmp_v3_users` variable lists the SNMPv3 user accounts for the +host. It should contain a list of dictionaries of the following format: + +Key | Default | Description +-------------|---------|------------ +`name` |   | SNMPv3 user name +`auth_pass` |   | SNMPv3 authentication password +`priv_pass` |   | SNMPv3 privacy password + + +Usage +----- + +Example playbook: + +````yaml +- name: set up proxmox servers + hosts: proxmox_hypervisors + roles: + - role: proxmox_hypervisor + vars: + proxmox_api_user: ansible + proxmox_api_password: s3cret +``` diff --git a/roles/proxmox_hypervisor/defaults/main.yml b/roles/proxmox_hypervisor/defaults/main.yml index a037eb4..db87291 100644 --- a/roles/proxmox_hypervisor/defaults/main.yml +++ b/roles/proxmox_hypervisor/defaults/main.yml @@ -1,10 +1,9 @@ -proxmox_api_user: ansible@pam -proxmox_api_password: changeme +proxmox_api_user: ansible proxmox_ntp_servers: '{{ vlan.ntp_servers }}' -proxmox_mail_origin: '{{ email_domain }}' -proxmox_relayhost: '{{ email_domain }}' +proxmox_postfix_myorigin: '{{ email_domain }}' +proxmox_postfix_relayhost: '{{ email_domain }}' proxmox_syslog_host: '{{ syslog_host_ip }}' proxmox_syslog_port: 514 @@ -27,7 +26,7 @@ proxmox_nagios_ssh_pubkey: '{{ nagios_ssh_pubkey }}' proxmox_snmp_location: unknown proxmox_snmp_contact: '{{ organization }} Sysadmins ' -snmp_v3_users: +proxmox_snmp_v3_users: - name: '{{ nagios_snmp_user }}' auth_pass: '{{ nagios_snmp_auth_pass }}' priv_pass: '{{ nagios_snmp_priv_pass }}' diff --git a/roles/proxmox_hypervisor/tasks/nagios.yml b/roles/proxmox_hypervisor/tasks/nagios.yml index b42317d..b2feac1 100644 --- a/roles/proxmox_hypervisor/tasks/nagios.yml +++ b/roles/proxmox_hypervisor/tasks/nagios.yml @@ -57,7 +57,7 @@ path: /var/lib/snmp/snmpd.conf line: 'createUser {{ item.name }} SHA "{{ item.auth_pass }}" AES "{{ item.priv_pass }}"' insertafter: EOF - loop: '{{ snmp_v3_users }}' + loop: '{{ proxmox_snmp_v3_users }}' loop_control: label: '{{ item.name }}' diff --git a/roles/proxmox_hypervisor/tasks/pve_api_user.yml b/roles/proxmox_hypervisor/tasks/pve_api_user.yml index f620a90..2fd04f1 100644 --- a/roles/proxmox_hypervisor/tasks/pve_api_user.yml +++ b/roles/proxmox_hypervisor/tasks/pve_api_user.yml @@ -1,6 +1,6 @@ - name: create unix account user: - name: "{{ proxmox_api_user | replace('@pam', '') }}" + name: '{{ proxmox_api_user }}' shell: /sbin/nologin password: '{{ proxmox_api_password | password_hash("sha512", proxmox_password_salt | default("")) }}' state: present @@ -13,9 +13,9 @@ - name: create PVE account block: - name: create PVE user - command: pveum user add {{ proxmox_api_user }} + command: pveum user add {{ proxmox_api_user }}@pam - name: set user ACLs - command: pveum acl modify / -user {{ proxmox_api_user }} -role PVEAdmin -propagate 1 + command: pveum acl modify / -user {{ proxmox_api_user }}@pam -role PVEAdmin -propagate 1 - when: proxmox_api_user not in pve_users.stdout_lines + when: proxmox_api_user~'@pam' not in pve_users.stdout_lines diff --git a/roles/proxmox_hypervisor/templates/etc/postfix/main.cf.j2 b/roles/proxmox_hypervisor/templates/etc/postfix/main.cf.j2 index 76575e3..813a7bf 100644 --- a/roles/proxmox_hypervisor/templates/etc/postfix/main.cf.j2 +++ b/roles/proxmox_hypervisor/templates/etc/postfix/main.cf.j2 @@ -1,6 +1,6 @@ compatibility_level = 2 -myorigin = {{ proxmox_mail_origin }} +myorigin = {{ proxmox_postfix_myorigin }} # disable local delivery biff = no @@ -10,7 +10,7 @@ inet_interfaces = loopback-only inet_protocols = all mynetworks_style = host -relayhost = {{ proxmox_relayhost }} +relayhost = {{ proxmox_postfix_relayhost }} alias_database = hash:/etc/aliases diff --git a/roles/proxmox_hypervisor/templates/etc/snmp/snmpd.conf.j2 b/roles/proxmox_hypervisor/templates/etc/snmp/snmpd.conf.j2 index ad04e59..66fbb89 100644 --- a/roles/proxmox_hypervisor/templates/etc/snmp/snmpd.conf.j2 +++ b/roles/proxmox_hypervisor/templates/etc/snmp/snmpd.conf.j2 @@ -5,6 +5,6 @@ sysServices 72 master agentx -{% for user in snmp_v3_users %} +{% for user in proxmox_snmp_v3_users %} rouser {{ user.name }} {% endfor %} diff --git a/roles/proxmox_instance/tasks/main.yml b/roles/proxmox_instance/tasks/main.yml index 590f1df..91959bf 100644 --- a/roles/proxmox_instance/tasks/main.yml +++ b/roles/proxmox_instance/tasks/main.yml @@ -2,7 +2,7 @@ proxmox_kvm: node: '{{ proxmox_node }}' api_host: localhost - api_user: '{{ proxmox_api_user }}' + api_user: '{{ proxmox_api_user }}@pam' api_password: '{{ proxmox_api_password }}' name: '{{ proxmox_hostname }}' storage: '{{ proxmox_storage }}' @@ -32,7 +32,7 @@ proxmox_kvm: node: '{{ proxmox_node }}' api_host: localhost - api_user: '{{ proxmox_api_user }}' + api_user: '{{ proxmox_api_user }}@pam' api_password: '{{ proxmox_api_password }}' bios: '{{ proxmox_bios }}' efidisk0: @@ -132,7 +132,7 @@ proxmox_kvm: node: '{{ proxmox_node }}' api_host: localhost - api_user: '{{ proxmox_api_user }}' + api_user: '{{ proxmox_api_user }}@pam' api_password: '{{ proxmox_api_password }}' vmid: '{{ proxmox_vmid.stdout }}' state: started -- cgit