feat(backup): MinIO S3 backup target on Proxmox host for Velero + CNPG

Stand up a single-node/single-drive MinIO S3 endpoint on the Proxmox host as the
off-cluster backup target for Velero (R-STATE-03) and CloudNativePG (R-IDP-05).

Ansible (author + executed):
- roles/minio_backup_target + playbooks/backup-minio.yml — idempotent, additive only:
  ZFS dataset Storage/k3s-backups (zstd, quota=100G, /mnt/Storage/k3s-backups, no
  sharenfs); minio system user; pinned+checksummed MinIO/mc binaries (fetched on the
  controller since the host has no WAN, copied to host); hardened systemd unit bound to
  the host's cluster-reachable LAN IP (auto-discovered) on :9000; velero + cnpg buckets;
  a non-root access key scoped by IAM policy to only those two buckets.
- inventory: new [proxmox_hosts] group ([email protected].2.102); overrides the cluster-wide
  ansible_user. Does not disturb existing k3s node entries.
- group_vars/proxmox_hosts/vault.yml (ansible-vault): root + scoped MinIO creds.

GitOps hand-off:
- platform/backup/minio-credentials.sops.yaml (+ .example) — SOPS/age-encrypted endpoint +
  scoped key/secret for the Velero/CNPG wiring (WS-STORAGE/WS-SEC). Not yet wired into a
  kustomization (left for the consuming agents).

Verified live: dataset props correct; minio active+enabled bound to 192.168.1.9:9000;
S3 endpoint http://192.168.1.9:9000/minio/health/ready returns 200 from an in-cluster pod;
buckets velero+cnpg present; scoped key created+policy attached; re-run is idempotent.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
jakman85andClaude Opus 4.8 committed 2026-08-28 22:15:05 -05:00
1 parent 748e9ca55d
commit ac32f01f7b
13 files changed
+609

No files matched your search

@@ -0,0 +1,263 @@
---
# ── 0. Preconditions / safety asserts ─────────────────────────────────────────────────────────
- name: Assert MinIO credentials are supplied (from vaulted group_vars)
ansible.builtin.assert:
that:
- minio_backup_target_root_user | default('') | length > 0
- minio_backup_target_root_password | default('') | length >= 8
- minio_backup_target_access_key | default('') | length > 0
- minio_backup_target_secret_key | default('') | length >= 8
fail_msg: >-
MinIO credentials are missing. Provide minio_backup_target_root_user/_password and
minio_backup_target_access_key/_secret_key via inventory/group_vars/proxmox_hosts/vault.yml.
quiet: true
# Determine the host's 192.168.1.0/24 address (the S3 endpoint the cluster reaches). If the
# operator pinned minio_backup_target_bind_address, honour it; else auto-discover and assert.
- name: Discover the host LAN (cluster-reachable) IPv4 address
ansible.builtin.set_fact:
minio_backup_target_bind_address: >-
{{ minio_backup_target_bind_address
if (minio_backup_target_bind_address | length > 0)
else (ansible_facts.all_ipv4_addresses
| select('match', '^' ~ (minio_backup_target_lan_prefix | regex_escape))
| list | first | default('')) }}
- name: Assert a cluster-reachable LAN address was found
ansible.builtin.assert:
that:
- minio_backup_target_bind_address | length > 0
fail_msg: >-
Could not find a {{ minio_backup_target_lan_prefix }}x address on this host
(interfaces: {{ ansible_facts.all_ipv4_addresses | default([]) | join(', ') }}).
The cluster egresses onto that LAN — refusing to bind MinIO to an unreachable address.
Set minio_backup_target_bind_address explicitly if discovery is wrong.
quiet: true
# ── 1. ZFS dataset (backup drive) — idempotent, never touches other datasets ───────────────────
- name: Create/ensure the k3s-backups ZFS dataset (compression, quota, mountpoint; NO sharenfs)
community.general.zfs:
name: "{{ minio_backup_target_zfs_dataset }}"
state: present
extra_zfs_properties:
compression: "{{ minio_backup_target_zfs_compression }}"
quota: "{{ minio_backup_target_zfs_quota }}"
mountpoint: "{{ minio_backup_target_mountpoint }}"
# ── 2. Service identity ───────────────────────────────────────────────────────────────────────
- name: Create the minio system group
ansible.builtin.group:
name: "{{ minio_backup_target_group }}"
system: true
- name: Create the minio system user (no login shell, home = data dir)
ansible.builtin.user:
name: "{{ minio_backup_target_user }}"
group: "{{ minio_backup_target_group }}"
system: true
shell: /usr/sbin/nologin
home: "{{ minio_backup_target_data_dir }}"
create_home: false
- name: Ensure the MinIO data directory exists (owned by minio, inside the dataset)
ansible.builtin.file:
path: "{{ minio_backup_target_data_dir }}"
state: directory
owner: "{{ minio_backup_target_user }}"
group: "{{ minio_backup_target_group }}"
mode: "0750"
# ── 3. Binaries — fetched on the CONTROLLER (host has no internet), copied to the host ──────────
- name: Ensure controller-side download cache exists
ansible.builtin.file:
path: "{{ minio_backup_target_controller_cache }}"
state: directory
mode: "0700"
delegate_to: localhost
become: false
run_once: true
- name: Fetch MinIO server binary onto the controller (checksummed)
ansible.builtin.get_url:
url: "{{ minio_backup_target_minio_url }}"
dest: "{{ minio_backup_target_controller_cache }}/minio.{{ minio_backup_target_minio_version }}"
checksum: "sha256:{{ minio_backup_target_minio_sha256 }}"
mode: "0755"
delegate_to: localhost
become: false
run_once: true
- name: Fetch mc client binary onto the controller (checksummed)
ansible.builtin.get_url:
url: "{{ minio_backup_target_mc_url }}"
dest: "{{ minio_backup_target_controller_cache }}/mc.{{ minio_backup_target_mc_version }}"
checksum: "sha256:{{ minio_backup_target_mc_sha256 }}"
mode: "0755"
delegate_to: localhost
become: false
run_once: true
# Integrity is already guaranteed by the SHA256 verification get_url performed on the controller
# above; copy transfers that verified artifact faithfully. (The copy module's own `checksum` arg is
# SHA1, not SHA256 — deliberately not used here to avoid a false mismatch.)
- name: Install MinIO server binary on the host
ansible.builtin.copy:
src: "{{ minio_backup_target_controller_cache }}/minio.{{ minio_backup_target_minio_version }}"
dest: "{{ minio_backup_target_minio_bin }}"
owner: root
group: root
mode: "0755"
notify: Restart minio
- name: Install mc client binary on the host
ansible.builtin.copy:
src: "{{ minio_backup_target_controller_cache }}/mc.{{ minio_backup_target_mc_version }}"
dest: "{{ minio_backup_target_mc_bin }}"
owner: root
group: root
mode: "0755"
# ── 4. systemd service ────────────────────────────────────────────────────────────────────────
- name: Write the MinIO environment file (root creds, bind address, data dir)
ansible.builtin.template:
src: minio.env.j2
dest: "{{ minio_backup_target_env_file }}"
owner: root
group: "{{ minio_backup_target_group }}"
mode: "0640"
no_log: true
notify: Restart minio
- name: Install the MinIO systemd unit
ansible.builtin.template:
src: minio.service.j2
dest: /etc/systemd/system/minio.service
owner: root
group: root
mode: "0644"
notify: Restart minio
- name: Enable + start MinIO (apply any pending unit/env changes now)
ansible.builtin.systemd:
name: minio
enabled: true
state: started
daemon_reload: true
- name: Flush handlers so MinIO is (re)started before we configure buckets/users
ansible.builtin.meta: flush_handlers
# ── 5. Readiness gate ─────────────────────────────────────────────────────────────────────────
- name: Wait for the MinIO S3 health endpoint to report ready
ansible.builtin.uri:
url: "http://{{ minio_backup_target_bind_address }}:{{ minio_backup_target_api_port }}/minio/health/ready"
status_code: 200
register: minio_backup_target_health
retries: 30
delay: 2
until: minio_backup_target_health.status == 200
# ── 6. Buckets + scoped non-root user (via mc, idempotent) ─────────────────────────────────────
- name: Configure the local mc alias against the running MinIO
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- alias
- set
- k3sbackup
- "http://{{ minio_backup_target_bind_address }}:{{ minio_backup_target_api_port }}"
- "{{ minio_backup_target_root_user }}"
- "{{ minio_backup_target_root_password }}"
no_log: true
changed_when: false
- name: Create the Velero + CNPG buckets (idempotent)
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- mb
- --ignore-existing
- "k3sbackup/{{ item }}"
loop: "{{ minio_backup_target_buckets }}"
register: minio_backup_target_mb
changed_when: "'created successfully' in (minio_backup_target_mb.stdout | default(''))"
- name: Render the scoped bucket RW policy to the host
ansible.builtin.template:
src: bucket-policy.json.j2
dest: "/etc/minio-{{ minio_backup_target_policy_name }}.json"
owner: root
group: "{{ minio_backup_target_group }}"
mode: "0640"
- name: Check whether the scoped policy already exists
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- admin
- policy
- info
- k3sbackup
- "{{ minio_backup_target_policy_name }}"
register: minio_backup_target_policy_info
changed_when: false
failed_when: false
- name: Create the scoped bucket RW policy (velero + cnpg only)
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- admin
- policy
- create
- k3sbackup
- "{{ minio_backup_target_policy_name }}"
- "/etc/minio-{{ minio_backup_target_policy_name }}.json"
when: minio_backup_target_policy_info.rc != 0
changed_when: true
- name: Check whether the scoped access key already exists
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- admin
- user
- info
- k3sbackup
- "{{ minio_backup_target_access_key }}"
register: minio_backup_target_user_info
changed_when: false
failed_when: false
- name: Create the scoped non-root access key
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- admin
- user
- add
- k3sbackup
- "{{ minio_backup_target_access_key }}"
- "{{ minio_backup_target_secret_key }}"
when: minio_backup_target_user_info.rc != 0
no_log: true
changed_when: true
- name: Attach the scoped policy to the access key (idempotent)
ansible.builtin.command:
argv:
- "{{ minio_backup_target_mc_bin }}"
- admin
- policy
- attach
- k3sbackup
- "{{ minio_backup_target_policy_name }}"
- --user
- "{{ minio_backup_target_access_key }}"
register: minio_backup_target_attach
changed_when:
- minio_backup_target_attach.rc == 0
- "'already in effect' not in (minio_backup_target_attach.stderr | default(''))"
failed_when:
- minio_backup_target_attach.rc != 0
- "'already in effect' not in (minio_backup_target_attach.stderr | default(''))"