rename dmc12 inventory to cloudlorean and vault admin_password
- replace inventory/dmc12.yml with cloudlorean.yml (+ group_vars) and update all README/AGENTS call examples and the inventory table - move admin_password hash into encrypted vault.yml; remove plaintext copies from roles/bootstrap/defaults and group_vars/external.yml - bootstrap.yml loads vault.yml via vars_files (same pattern as monitoring) - monitoring: PSK config/registration updates, docker role defaults, os-updates logging/reboot refinements, ansible.cfg/execute.sh tweaks - add .project-wiki knowledge base and .github agent instructions
This commit is contained in:
DerLinkman
@@ -0,0 +1,20 @@
|
||||
# Requirements
|
||||
|
||||
This section stores explicit product intent, constraints, and open questions.
|
||||
|
||||
## When To Read
|
||||
|
||||
- Understand confirmed project behavior, scope, constraints, or unresolved product intent.
|
||||
|
||||
## Key Files
|
||||
|
||||
- [Product brief](./product-brief.md)
|
||||
- [Functional requirements](./functional/INDEX.md)
|
||||
- [Non-functional requirements](./non-functional/INDEX.md)
|
||||
- [Constraints](./constraints.md)
|
||||
- [Open questions](./open-questions.md)
|
||||
|
||||
## Placeholders Or Stale Areas
|
||||
|
||||
- `product-brief.md` is still a placeholder (project identity lives in
|
||||
[PROJECT.md](../PROJECT.md)); fill or remove during the next update.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: CONSTRAINTS
|
||||
type: note
|
||||
status: active
|
||||
title: Constraints
|
||||
created: '2026-09-09'
|
||||
updated: '2026-09-09'
|
||||
tags:
|
||||
- requirements
|
||||
- constraints
|
||||
related:
|
||||
- PROJECT
|
||||
source_paths:
|
||||
- AGENTS.md
|
||||
confidence: confirmed
|
||||
---
|
||||
|
||||
# Constraints
|
||||
|
||||
Explicitly documented constraints for this repository (source: `AGENTS.md`).
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
- **Debian-only**: every playbook must check
|
||||
`ansible_facts['os_family'] == "Debian"` and abort on non-Debian hosts.
|
||||
- **LXC containers**: tasks affecting `sysctl` or `reboot` must check
|
||||
`virtualization_type != "lxc"` and be skipped there.
|
||||
- **Ansible style**: modules use FQCN (`ansible.builtin.apt`, ...);
|
||||
variable defaults live in `roles/<name>/defaults/main.yml`, never hardcoded
|
||||
in tasks; role logic is split into `tasks/<name>.yml` subtask files with
|
||||
`tasks/main.yml` containing only imports.
|
||||
- **Templates** use `# {{ ansible_managed }}` as header.
|
||||
- **Execution environment**: changes to collections require updating
|
||||
`docker/requirements.yml` and rebuilding the Docker image.
|
||||
|
||||
## Process Constraints
|
||||
|
||||
- **Documentation duty**: every new feature, parameter, or variable must be
|
||||
documented in the corresponding README before commit (see `AGENTS.md`
|
||||
mapping table).
|
||||
- **Code language**: documentation in German, code (variable names, task
|
||||
names) in English.
|
||||
- **Secrets**: sensitive values belong in encrypted `vault.yml`; `.vault_pass`,
|
||||
`setenv.sh`, `logs/`, and `.zabbix-psk/` are git-ignored and must never be
|
||||
committed. No plaintext secrets in `defaults/` or `group_vars/`.
|
||||
- **Testing**: changes are tested in the Docker container (`./execute.sh`),
|
||||
with `ansible-lint` and `--check` dry runs where sensible.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Functional Requirements
|
||||
|
||||
This index routes to functional requirement topics; atomic REQ records live only in linked topic files.
|
||||
|
||||
## When To Read
|
||||
|
||||
- Work with product capabilities, workflows, integrations, or other functional behavior.
|
||||
|
||||
## Key Files
|
||||
|
||||
- [Host lifecycle operations](./host-lifecycle-operations.md) - REQ-001..REQ-006 (provisioning, docker, monitoring, updates, hawser, ssh keys)
|
||||
|
||||
## Placeholders Or Stale Areas
|
||||
|
||||
- None.
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
id: REQ-FUNC-HOST-LIFECYCLE
|
||||
type: requirements
|
||||
status: active
|
||||
title: Host Lifecycle Operations
|
||||
created: '2026-09-09'
|
||||
updated: '2026-09-09'
|
||||
tags:
|
||||
- requirements
|
||||
- functional
|
||||
related:
|
||||
- PROJECT
|
||||
- PRODUCT-BRIEF
|
||||
source_paths:
|
||||
- README.md
|
||||
- AGENTS.md
|
||||
confidence: confirmed
|
||||
---
|
||||
|
||||
# Host Lifecycle Operations
|
||||
|
||||
Explicitly stated functional scope of the collection (source: root
|
||||
`README.md` purpose statement and playbook table; evidence linked in
|
||||
[requirement-evidence.yml](../../traceability/requirement-evidence.yml)).
|
||||
|
||||
<a id="req-001"></a>
|
||||
|
||||
## REQ-001 - Initial provisioning of Debian hosts
|
||||
|
||||
Status: active
|
||||
Tags: [provisioning, bootstrap]
|
||||
Related: [MOD-001]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
The collection provides a complete initial setup ("Ersteinrichtung") for
|
||||
Debian hosts via `bootstrap.yml` (packages, admin user, SSH, MOTD, sysctl,
|
||||
Docker, monitoring).
|
||||
|
||||
### Rationale
|
||||
|
||||
README.md: "bootstrap.yml | Vollständige Ersteinrichtung eines Debian-Hosts";
|
||||
README purpose statement: "Bereitstellung, Härtung, Aktualisierung und
|
||||
Überwachung von Debian-Hosts".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Runs against the three sites in `inventory/`; composes docker and
|
||||
monitoring roles with skip flags.
|
||||
|
||||
<a id="req-002"></a>
|
||||
|
||||
## REQ-002 - Docker Engine installation
|
||||
|
||||
Status: active
|
||||
Tags: [docker]
|
||||
Related: [MOD-002]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Install Docker Engine from the official Docker repository
|
||||
(`playbooks/docker.yml` / role `docker`).
|
||||
|
||||
### Rationale
|
||||
|
||||
README playbook table: "docker | Docker Engine installieren".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Official repository, not distribution packages.
|
||||
|
||||
<a id="req-003"></a>
|
||||
|
||||
## REQ-003 - Zabbix Agent 2 installation and registration
|
||||
|
||||
Status: active
|
||||
Tags: [monitoring, zabbix]
|
||||
Related: [MOD-003, TECH-INTEGRATIONS-ZABBIX]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Install Zabbix Agent 2 and register the host on the Zabbix server
|
||||
(`playbooks/monitoring.yml` / role `monitoring`).
|
||||
|
||||
### Rationale
|
||||
|
||||
README playbook table: "monitoring | Zabbix Agent 2 installieren &
|
||||
registrieren".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Includes TLS-PSK and Docker plugin support per implementation.
|
||||
|
||||
<a id="req-004"></a>
|
||||
|
||||
## REQ-004 - Package updates with healthcheck
|
||||
|
||||
Status: active
|
||||
Tags: [updates, healthcheck]
|
||||
Related: [MOD-004, MOD-005]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Update Debian packages and verify running containers afterwards
|
||||
(`playbooks/os-updates-deb.yml`: roles `os-updates` + `healthcheck`).
|
||||
|
||||
### Rationale
|
||||
|
||||
README playbook table: "os-updates, healthcheck | Pakete aktualisieren +
|
||||
Healthcheck".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Mirror switch, reboot and logging are part of the implemented update flow.
|
||||
|
||||
<a id="req-005"></a>
|
||||
|
||||
## REQ-005 - Hawser stack update
|
||||
|
||||
Status: active
|
||||
Tags: [docker, hawser]
|
||||
Related: [MOD-006]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Update the Hawser Docker Compose stack (`playbooks/upgrade-hawser.yml` /
|
||||
role `hawser`).
|
||||
|
||||
### Rationale
|
||||
|
||||
README playbook table: "hawser | Hawser-Stack aktualisieren".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- None.
|
||||
|
||||
<a id="req-006"></a>
|
||||
|
||||
## REQ-006 - SSH key hardening
|
||||
|
||||
Status: active
|
||||
Tags: [ssh, hardening]
|
||||
Related: [MOD-007]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Manage desired and undesired SSH keys on hosts
|
||||
(`playbooks/hardening/manage-ssh-keys.yml` / role `manage-ssh-keys`).
|
||||
|
||||
### Rationale
|
||||
|
||||
README playbook table: "manage-ssh-keys | SSH-Schlüssel hartieren"; role
|
||||
name/description in README roles table.
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- None.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Non-Functional Requirements
|
||||
|
||||
This index routes to non-functional requirement topics; atomic NFR records live only in linked topic files.
|
||||
|
||||
## When To Read
|
||||
|
||||
- Work with quality attributes, operations, security, resilience, performance, or service levels.
|
||||
|
||||
## Key Files
|
||||
|
||||
- [Operational policies](./operational-policies.md) - NFR-001..NFR-006 (platform, secrets, logging, runtime, documentation, LXC)
|
||||
|
||||
## Placeholders Or Stale Areas
|
||||
|
||||
- None.
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
id: NFR-OPERATIONAL-POLICIES
|
||||
type: requirements
|
||||
status: active
|
||||
title: Operational Policies
|
||||
created: '2026-09-09'
|
||||
updated: '2026-09-09'
|
||||
tags:
|
||||
- requirements
|
||||
- non-functional
|
||||
related:
|
||||
- PROJECT
|
||||
- CONSTRAINTS
|
||||
source_paths:
|
||||
- README.md
|
||||
- AGENTS.md
|
||||
confidence: confirmed
|
||||
---
|
||||
|
||||
# Operational Policies
|
||||
|
||||
Explicitly stated non-functional requirements (sources: root `README.md`,
|
||||
`AGENTS.md`; evidence linked in
|
||||
[requirement-evidence.yml](../../traceability/requirement-evidence.yml)).
|
||||
|
||||
<a id="nfr-001"></a>
|
||||
|
||||
## NFR-001 - Debian-only target platforms
|
||||
|
||||
Status: active
|
||||
Tags: [platform]
|
||||
Related: [REQ-001]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
All playbooks must target Debian only and verify
|
||||
`ansible_facts['os_family'] == "Debian"`, aborting on other systems.
|
||||
|
||||
### Rationale
|
||||
|
||||
README "Voraussetzungen": "Ziel-Hosts: Debian (alle Playbooks prüfen
|
||||
`os_family == "Debian"`)".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Exception observed: `playbooks/hardening/manage-ssh-keys.yml` lacks the
|
||||
guard (tracked in the scan report).
|
||||
|
||||
<a id="nfr-002"></a>
|
||||
|
||||
## NFR-002 - Secrets never committed unencrypted
|
||||
|
||||
Status: active
|
||||
Tags: [security, vault]
|
||||
Related: [TECH-SECURITY, ALERT-20260909-001]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Sensitive values (passwords, API keys) belong in encrypted `vault.yml`;
|
||||
no plaintext secrets in `defaults/`, `group_vars/`, or commits.
|
||||
|
||||
### Rationale
|
||||
|
||||
README "Secrets & Vault" and "Beitragen" rule 3; AGENTS.md "Secrets"
|
||||
section.
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Resolved 2026-09-09: `admin_password` moved to encrypted `vault.yml`
|
||||
(ALERT-20260909-001); no plaintext secrets remain in `defaults/` or
|
||||
`group_vars/`.
|
||||
|
||||
<a id="nfr-003"></a>
|
||||
|
||||
## NFR-003 - Per-host update audit log
|
||||
|
||||
Status: active
|
||||
Tags: [logging, audit]
|
||||
Related: [MOD-004, MOD-005]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
The `os-updates` and `healthcheck` roles write one update log per host to
|
||||
`logs/<inventory>/<hostname>/update.log` on the controller as a local
|
||||
audit trail.
|
||||
|
||||
### Rationale
|
||||
|
||||
README "Logging" section.
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- `logs/` is git-ignored.
|
||||
|
||||
<a id="nfr-004"></a>
|
||||
|
||||
## NFR-004 - Docker-based execution environment
|
||||
|
||||
Status: active
|
||||
Tags: [runtime, docker]
|
||||
Related: [TECH-DEPLOYMENT]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Playbooks must be runnable from the provided Docker environment without a
|
||||
local Ansible installation (`execute.sh`, `docker/Dockerfile`).
|
||||
|
||||
### Rationale
|
||||
|
||||
README "Docker-Ausführungsumgebung": "Damit Playbooks nicht lokal
|
||||
installiert werden müssen, liefert das Repository ein fertiges Docker-Image."
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Collections pinned in `docker/requirements.yml`; image rebuild on
|
||||
collection changes.
|
||||
|
||||
<a id="nfr-005"></a>
|
||||
|
||||
## NFR-005 - Documentation duty for every change
|
||||
|
||||
Status: active
|
||||
Tags: [documentation, process]
|
||||
Related: [CONSTRAINTS]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Every new feature, parameter, and variable must be documented in the
|
||||
corresponding role README before commit; playbook changes update the root
|
||||
README.
|
||||
|
||||
### Rationale
|
||||
|
||||
README "Beitragen" rule 2; AGENTS.md "WICHTIG: Dokumentationspflicht bei
|
||||
Änderungen".
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- None.
|
||||
|
||||
<a id="nfr-006"></a>
|
||||
|
||||
## NFR-006 - LXC-aware execution
|
||||
|
||||
Status: active
|
||||
Tags: [platform, lxc]
|
||||
Related: [MOD-004]
|
||||
Confidence: confirmed
|
||||
|
||||
### Statement
|
||||
|
||||
Tasks affecting `sysctl` or `reboot` must be skipped on LXC containers
|
||||
(`virtualization_type != "lxc"`).
|
||||
|
||||
### Rationale
|
||||
|
||||
AGENTS.md "OS-Unterstützung": "LXC-Container: Tasks, die `sysctl` oder
|
||||
`reboot` betreffen, müssen ... übersprungen werden."
|
||||
|
||||
### Acceptance Notes
|
||||
|
||||
- Implemented in `roles/os-updates/tasks/reboot.yml`.
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
id: OPEN-QUESTIONS
|
||||
type: note
|
||||
status: active
|
||||
title: Open Questions
|
||||
created: '2026-09-09'
|
||||
updated: '2026-09-09'
|
||||
tags:
|
||||
- requirements
|
||||
- open-questions
|
||||
related:
|
||||
- SCAN-20260909
|
||||
- ALERT-20260909-001
|
||||
- ALERT-20260909-002
|
||||
source_paths:
|
||||
- AGENTS.md
|
||||
- README.md
|
||||
- inventory/group_vars/external.yml
|
||||
confidence: confirmed
|
||||
---
|
||||
|
||||
# Open Questions
|
||||
|
||||
Reconciliation state after the 2026-09-09 scan (workflow: Open Questions
|
||||
Reconciliation). Anchors are stable; statuses follow the schema
|
||||
(`open`, `partially-resolved`, `resolved`, ...).
|
||||
|
||||
<a id="oq-001"></a>
|
||||
|
||||
## OQ-001 - Who are the stakeholders/owners of this repository?
|
||||
|
||||
Status: partially-resolved
|
||||
Updated: 2026-09-09
|
||||
Related: [SCAN-20260909]
|
||||
|
||||
Resolution (partial): Operators appear to be "Niklas" and "Dennis"
|
||||
(SSH key comments in `roles/bootstrap/defaults/main.yml`,
|
||||
`confidence: inferred`). Formal ownership and roles remain undocumented.
|
||||
|
||||
Remaining question: Who formally owns and operates the playbooks, and who
|
||||
approves changes?
|
||||
|
||||
<a id="oq-002"></a>
|
||||
|
||||
## OQ-002 - What are the explicit success criteria?
|
||||
|
||||
Status: partially-resolved
|
||||
Updated: 2026-09-09
|
||||
Related: [SCAN-20260909], MOD-005
|
||||
|
||||
Resolution (partial): For update runs, success is defined by the
|
||||
`healthcheck` quality gate (all Docker containers running; fails the play
|
||||
only when `healthcheck_fail_on_unhealthy` is true). No success criteria for
|
||||
the overall project are documented.
|
||||
|
||||
Remaining question: What defines success beyond a passing update-run gate?
|
||||
|
||||
<a id="oq-003"></a>
|
||||
|
||||
## OQ-003 - Is `AGENTS.md`/`README.md` stale regarding `inventory/dmc12.yml`?
|
||||
|
||||
Status: resolved
|
||||
Updated: 2026-09-09
|
||||
Related: [ALERT-20260909-002], SCAN-20260909
|
||||
|
||||
Resolution: Yes. Git status shows `D inventory/dmc12.yml` (uncommitted) and
|
||||
untracked `inventory/cloudlorean.yml`; `dmc12` is now a Proxmox host inside
|
||||
the `cloudlorean` site. `README.md` (inventory table, examples) and
|
||||
`AGENTS.md` still reference `dmc12.yml`. Documentation updates and the
|
||||
commit of the rename are tracked in ALERT-20260909-002.
|
||||
|
||||
<a id="oq-004"></a>
|
||||
|
||||
## OQ-004 - Is the external site's Zabbix passive server correct?
|
||||
|
||||
Status: open
|
||||
Created: 2026-09-09
|
||||
Related: [SCAN-20260909], MOD-003
|
||||
|
||||
`inventory/group_vars/external.yml` sets
|
||||
`monitoring_zabbix_passive_servers: ["2a01:4f8:1c1e:62dd::1"]`, which is the
|
||||
`healthcheck` host's own address. Is a Zabbix server/proxy intentionally
|
||||
running on that host, or is this a misconfiguration? (`confidence: unknown`)
|
||||
|
||||
<a id="oq-005"></a>
|
||||
|
||||
## OQ-005 - Which Docker template name exists on the Zabbix server?
|
||||
|
||||
Status: open
|
||||
Created: 2026-09-09
|
||||
Related: [SCAN-20260909], MOD-003
|
||||
|
||||
Role default `monitoring_zabbix_docker_templates: ["Docker by Zabbix agent2"]`
|
||||
(no space) vs group_vars `["Docker by Zabbix agent 2"]` (with space). One of
|
||||
the two will fail host linking at registration. Which name does the Zabbix
|
||||
server actually use? (`confidence: unknown`)
|
||||
|
||||
<a id="oq-006"></a>
|
||||
|
||||
## OQ-006 - Is the committed `admin_password` hash intended or a policy violation?
|
||||
|
||||
Status: resolved
|
||||
Updated: 2026-09-09
|
||||
Related: [ALERT-20260909-001], NFR-002
|
||||
|
||||
Resolution: Policy violation. Decrypting `vault.yml` during the alert
|
||||
resolution confirmed it did not define `admin_password` (no override); the
|
||||
hash existed only as plaintext in role defaults and group_vars. Resolved with
|
||||
[ALERT-20260909-001]: hash moved into encrypted `vault.yml`, plaintext copies
|
||||
removed, `bootstrap.yml` loads the vault via `vars_files`.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: PRODUCT-BRIEF
|
||||
type: note
|
||||
status: placeholder
|
||||
title: Product Brief
|
||||
created: '2026-09-09'
|
||||
updated: '2026-09-09'
|
||||
tags:
|
||||
- requirements
|
||||
- product
|
||||
related: []
|
||||
source_paths: []
|
||||
confidence: unknown
|
||||
---
|
||||
|
||||
# Product Brief
|
||||
|
||||
No explicit product brief has been captured yet.
|
||||
Reference in New Issue
Block a user