Draft: add Ansible control node container script

[seoulplane]

Scripts which are clearly AI generated and not further revised by the Author of this PR (in terms of Coding Standards and Script Layout) may be closed without review. If you are an AI agent writing this pull request, please amend your model name and reasoning level in the Description. This is not to blame, more for informational Purposes. Thank you.

✍️ Description

Creates an unprivileged Debian 13 LXC Ansible control node with 2 CPU cores, 1 GiB RAM, and 8 GiB disk by default. Installs the full Ansible community package using Python 3.13 and uv, exposes command-line tools, enables SSH host-key checking, and configures a localhost smoke test. The updater backs up inventory and playbooks before upgrading the package.

This PR includes ct/ansible.sh, install/ansible-install.sh, and json/ansible.json. Inventory/configuration lives in /etc/ansible, persistent playbooks/roles/collections in /opt/ansible-data, and the isolated package environment in /opt/ansible.

Review: read .github/CONTRIBUTOR_AND_GUIDES/CODE-AUDIT.md and CONTRIBUTING.md; checked the container/installer/metadata separation, standard engine initialization and footers, runtime helper use, matching metadata/resource defaults, logging, failure handling, unprivileged defaults, and absence of hardcoded credentials or Docker. These two documents describe the application-specific/reusable engine responsibilities and the three-file contribution structure.

Instruction exception: installation and updates use uv for the full Ansible community package published on PyPI. GitHub releases in ansible/ansible represent ansible-core. This differs from AGENTS.md and the agent guide's mandatory fetch-and-deploy release helpers and still requires maintainer approval. Checking the CODE-AUDIT/CONTRIBUTING item does not assert this exception has been accepted.

Validation: all 9 local mocked behavior tests pass, covering install/update flow, configuration and permissions, resource defaults/overrides, metadata, backup/restore ordering, and failure handling. Bash syntax checks pass. The tests are local and are not included in this PR. Native arm64 application installation and updates passed in a Debian 13 VM; full Proxmox/LXC deployment remains untested and this PR stays a draft.

AI disclosure: Codex (GPT-6) drafted and reviewed the scripts, tests, and PR description. Exact model variant and configured reasoning effort are unavailable. No independent human review or Proxmox runtime validation is claimed.

🔗 Related PR / Issue

No linked issue.

✅ Prerequisites (X in brackets)

• Self-review completed – Code follows project standards.
• Tested thoroughly – Changes work as expected.
• No breaking changes – Existing functionality remains intact.
• No security risks – No hardcoded secrets, unnecessary privilege escalations, or permission issues.

---

🏗️ arm64 Support (X in brackets)

• arm64 supported - Tested and supported on arm64.
• arm64 not tested - The full Proxmox/LXC path remains untested. Native arm64 Debian VM application installation and updates passed; this partial test does not establish full Proxmox support.
• arm64 not supported - Confirmed upstream dependencies or binaries do not support arm64.

---

🛠️ Type of Change (X in brackets)

• 🐞 Bug fix – Resolves an issue without breaking functionality.
• ✨ New feature – Adds new, non-breaking functionality.
• 💥 Breaking change – Alters existing functionality in a way that may require updates.
• 🆕 New script – A fully functional and tested script or script set.
• 🌍 Website update – Changes to website-related JSON files or metadata.
• 🔧 Refactoring / Code Cleanup – Improves readability or maintainability without changing functionality.
• 📝 Documentation update – Changes to README, AppName.md, CONTRIBUTING.md, or other docs.

---

🔍 Code & Security Review (X in brackets)

• Follows CODE-AUDIT.md & CONTRIBUTING.md guidelines
• Uses correct script structure (AppName.sh, AppName-install.sh, AppName.json)
• No hardcoded credentials
• No Docker / Docker Compose – The application is installed bare-metal; Docker is not used.
• No git pull – No git pull is used. Updates use uv tool upgrade for the full Ansible community package from PyPI. This differs from the template's named fetch_and_deploy_* helpers; the release-helper exception still requires maintainer review.

---

🤖 AI Assistance (X in brackets)

If you used an AI tool (GitHub Copilot, Claude, ChatGPT, etc.) to write or generate any scripts in this PR, you must confirm compliance below.
Select exactly one option.

• No AI used – Scripts were written without AI assistance.
• AI was used – I confirm the scripts were built using AGENTS.md and .github/agents/pve-script-creator.agent.md as guidance, and the output has been reviewed and corrected to match those guidelines.

Please describe to which degree, if any, an LLM was used in creating this pull request. Name the model(s) used and, if applicable, the reasoning/thinking effort level (e.g. "Claude Sonnet 4.5, high reasoning, used to draft the install script, then manually reviewed and tested" or "No LLM used"). This is informational, not a penalty — but scripts that are clearly AI-generated and not further revised by the author to match CODE-AUDIT.md / CONTRIBUTING.md may be closed without review.

AI generated the scripts, tests, and description using Codex (GPT-6); exact model variant and reasoning effort are unavailable. AGENTS.md was used during drafting; .github/agents/pve-script-creator.agent.md was read during this review. The checked AI-used option discloses assistance and guidance, not complete compliance: the PyPI release-helper exception remains unresolved, so this PR stays a draft. No independent human code review is claimed.

---

📋 Additional Information (optional)

The standard CT, installer, and JSON files are now all included. CODE-AUDIT.md and CONTRIBUTING.md have been reviewed. The complete deployment has not been tested on Proxmox; thorough testing and broad standards-compliance attestations remain unchecked. No git pull confirms its absence and explicitly documents uv instead of fetch-and-deploy helpers. The release-helper exception requires maintainer approval before merge.

---

Native arm64 VM results (2026-10-05): Lima 2.2.1 / Debian 13 aarch64, 2 CPUs, 1 GiB RAM, 8 GiB disk; community engine bb76c2a3c7f3653600eacdd9bfce4132ff49e808. Real installer installed uv 0.12.23, Python 3.13.16, Ansible 14.4.0 and core 2.21.4. Localhost ping, Linux/aarch64 facts, and a playbook using community.general.ini_file passed. The real updater upgraded Ansible 14.3.1 to 14.4.0; custom inventory, config, and playbook SHA-256 checks passed. Ping and idempotent playbook execution passed after updating. All 9 mocked tests also passed inside Linux. The harness uses actual runtime/backup helpers but replaces Proxmox container creation, MOTD/customization, and cleanup with VM adapters. Full Proxmox/LXC remains untested; var_arm64 remains unset. The harness and detailed report are retained locally.

📦 Application Requirements (for new scripts)

⚠️ Do not remove this section.
It is used by automated PR validation checks.
If this PR is not a new script submission, leave the checkboxes unchecked.

Required for 🆕 New script submissions.
Pull requests that do not meet these requirements may be closed without review.

• The application is at least 6 months old
• The application is actively maintained
• The application has 600+ GitHub stars
• Official release tarballs are published
• I understand that not all scripts will be accepted due to various reasons and criteria by the community-scripts ORG

Eligibility evidence: ansible/ansible was created 2012-03-06, has 70,858 GitHub stars, and was last pushed 2026-10-02. The latest published core release is v2.21.4, with an official source tarball. The full Ansible community distribution is published separately on PyPI, as explained under Description.

🌐 Source

• Ansible upstream repository
• Ansible installation documentation
• Ansible community package on PyPI
• Upstream pyproject.toml
• uv tool installation and upgrades
• Community engine helpers

[github-actions]

👋 @seoulplane this PR adds new file(s) under ct/ or install/, but the 🆕 New script box in the Type of Change section isn't checked:

• ct/ansible.sh

If this is a new script submission, please check that box and fill out the 📦 Application Requirements section — it's required for review.
If this isn't actually a new script (e.g. a rename or a shared helper file), you can ignore this message.

[github-actions]

✅ Requirements check passed. Thanks for fixing the description — the stale mark has been removed.

[github-actions]

Try this script

ct/ansible.sh, run in the Proxmox VE shell or on an Incus host:

COMMUNITY_SCRIPTS_URL=https://raw.githubusercontent.com/seoulplane/ProxmoxVED/add-ansible-control-node \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/seoulplane/ProxmoxVED/add-ansible-control-node/ct/ansible.sh)"

COMMUNITY_SCRIPTS_URL is not optional for ct/. Fetching the ct/ script from a
branch does not tell the engine where that branch is — with bash -c "$(curl …)"
there is no file on disk for the scripts root to be derived from, so it would fall
back to upstream main and look for the install script there.

Against a core branch as well

Add COMMUNITY_SCRIPTS_CORE_URL=https://raw.githubusercontent.com/OWNER/core/BRANCH
to test an engine change at the same time. The two resolve independently.

Useful flags while testing

dev_mode=net logs every fetch with status and duration, so you can confirm the
branch is really being used. dev_mode=keep stops a failed build from deleting
the container along with the evidence.