Implement Homepage Proxmox widget integration with API token management

[Copilot]

Adds end-to-end integration for Homepage's Proxmox widget: automated API token provisioning, 1Password storage, and Kubernetes ConfigMap mounting.

New Role: proxmox_homepage_token

Provisions read-only Proxmox API tokens and stores them in 1Password:

• Creates/validates Proxmox user (api@pam), group (api-ro-users), ACL (PVEAuditor on /)
• Generates API token with pveum user token add --privsep 1 --output-format json
• Stores credentials in 1Password using op_item_create (fields: username[text], credential[concealed])
• Reuses existing token from 1Password if present (idempotent)
• Exposes artifacts: url, username, secret for downstream roles

Extended Role: homepage_deploy

Mounts Proxmox credentials into Homepage pod:

• New template: homepage-proxmox-configmap.yml.j2 generates ConfigMap with proxmox.yaml
• Adds persistence configuration to Homepage Application:

  persistence:
    proxmox:
      enabled: true
      type: configMap
      name: homepage-proxmox-config
      mountPath: /app/config/proxmox.yaml
      subPath: proxmox.yaml

• Conditionally applies ConfigMap when credentials provided

Playbook Wiring

In coachlight-infra-stack.yml:

• Runs proxmox_homepage_token before homepage_deploy
• Passes artifacts via role variables
• Sources OP_SERVICE_ACCOUNT_TOKEN from environment

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Fix Homepage Proxmox integration</issue_title>
<issue_description>### Goal

Make the Homepage Proxmox widget and proxmox.yaml integration work end-to-end by:

1. Idempotently creating a Proxmox API token for Homepage.
2. Storing the token in 1Password using existing op_* roles.
3. Wiring the token into the Homepage Kubernetes deployment via ConfigMap so proxmox.yaml is mounted at /app/config/proxmox.yaml as per docs. ([Homepage][1])

Use existing roles where possible; only add minimal new roles.

---

Relevant project context (files/folders to open)

• ansible/playbooks/coachlight-infra-stack.yml (or whichever playbook deploys Homepage + Proxmox)
• ansible/inventories/group_vars/proxmox.yml and proxmox_cluster.yml
• ansible/roles/homepage_deploy/**
• ansible/roles/op_read/**, op_item_create/**, op_item_edit/**, op_vault_validator/**
• ansible/roles/role_artifacts/**
• ansible/roles/omada_api_auth/** and argocd_api_auth/** (copy patterns for “API token in 1Password + k8s config”)
• ansible/roles/proxmox_* (see how we already talk to Proxmox)

---

New role: roles/proxmox_homepage_token

Purpose

On the Proxmox cluster, ensure there is a read-only API token for Homepage, and that the token secret is stored in 1Password for later use by Homepage.

Defaults / variables

Create defaults/main.yml and meta/argument_specs.yml with a minimal set of vars, e.g.:

• proxmox_homepage_user (default api@pam)
• proxmox_homepage_group (default api-ro-users)
• proxmox_homepage_role (default PVEAuditor)
• proxmox_homepage_token_id (default homepage)
• proxmox_homepage_token_1p_item_title (e.g. coachlight-homelab/proxmox-homepage-token)
• proxmox_homepage_url (e.g. https://proxmox.host.or.ip:8006)
• proxmox_primary_node (name to run pveum on; default first in proxmox_cluster)

No secrets in defaults; secrets come from 1Password/env only.

Tasks (high level)

1. Use role_artifacts to register an artifact path like .artifacts/{{ deploy_env }}/proxmox_homepage_token/ to capture outputs.

2. Use op_read + op_vault_validator to check if the 1Password item proxmox_homepage_token_1p_item_title already exists and has fields token, secret, url.

   • If it exists, set facts with those values and skip Proxmox token creation.

3. If the item is missing:

   • On delegate_to: "{{ proxmox_primary_node }}", use ansible.builtin.command with pveum to idempotently ensure:

     • group exists: pveum groupadd {{ proxmox_homepage_group }} guarded with changed_when/failed_when so reruns are safe.
     • user exists: pveum useradd {{ proxmox_homepage_user }} (or equivalent) only if missing.
     • group ACL: pveum acl modify / -group {{ proxmox_homepage_group }} -role {{ proxmox_homepage_role }} -propagate 1.
     • token exists and returns a secret: pveum user token add {{ proxmox_homepage_user }} {{ proxmox_homepage_token_id }} --privsep 1. ([Proxmox VE][2])

   • Parse the command output to capture the newly generated token secret (only visible once).

   • Immediately create/update a 1Password item via op_item_create / op_item_edit with fields:

     • url: {{ proxmox_homepage_url }}
     • username: {{ proxmox_homepage_user }}!{{ proxmox_homepage_token_id }}
     • secret: token secret

4. Register normalized facts:

   • proxmox_homepage_url
   • proxmox_homepage_username (user@realm!tokenid)
   • proxmox_homepage_secret (token secret)

5. Write these into role artifacts for later use by homepage_deploy.

All command tasks must be idempotent and safe: use changed_when based on stdout, and treat “already exists” messages as ok.

---

Extend roles/homepage_deploy

ConfigMap for proxmox.yaml

1. Add a new template, e.g. templates/homepage-proxmox-configmap.yml.j2, that creates/updates a ConfigMap with a proxmox.yaml key exactly as Homepage expects: ([Homepage][1])

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: homepage-config
     namespace: {{ homepage_namespace }}
   data:
     proxmox.yaml: |
       {{ proxmox_homepage_node_name }}:
         url: {{ proxmox_homepage_url }}
         token: {{ proxmox_homepage_username }}
         secret: {{ proxmox_homepage_secret }}

   • homepage_namespace should reuse whatever var the role already uses.
   • proxmox_homepage_node_name can default to your real node name (e.g. pve) and come from group_vars.

2. In tasks/main.yml of homepage_deploy, after the base Homepage Application/ConfigMap resources are applied, add a task using k8s_object_manager (or the same k8s mechanism already used) to apply the new ConfigMap te...

• Fixes Fix Homepage Proxmox integration #4

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.