This commit is contained in:
2026-11-12 23:08:52 +01:00
parent 7789e95247
commit 2889600de1
4 changed files with 256 additions and 5 deletions
-5
View File
@@ -1,5 +0,0 @@
# Project Instructions
## Docker Swarm Stack Files
All YAML files in this project are Docker Swarm stack files. Keep them compatible with Docker Swarm and deploy them with `docker stack deploy -c <file> <stack-name>`, not `docker compose up`.
+52
View File
@@ -0,0 +1,52 @@
# Repository Decisions
This file records repository decisions and the guidance that follows from them. Accepted decisions are in force. Draft decisions are proposals, not policy. Declined decisions are retained for context and are not in force.
## Accepted
### DEC-001: Make the Kubernetes cluster the primary infrastructure
- **Decision:** New services should be deployed in the Kubernetes cluster, and services running on other instances should be migrated there.
[kustomization.yaml](kustomization.yaml) is entry point for the Kubernetes cluster configuration.
### DEC-002: Document manual operations in README.md
- **Decision:** The repository's `README.md` should document useful manual operations and link to all other manual instructions in the repository.
### DEC-003: Retire Ansible
- **Decision:** Ansible is legacy and should be removed strategically.
### DEC-004: Treat Docker Swarm files as legacy
- **Decision:** Docker Swarm files are legacy. New services should not use Docker Swarm and should adopt Kubernetes or other modern orchestration solutions.
### DEC-005: Isolate Kubernetes namespaces by default
- **Decision:** Each namespace should be isolated by default for ingress and egress. Egress should allow only explicitly whitelisted connectivity.
### DEC-006: Use GitOps for infrastructure changes
- **Decision:** Use GitOps as much as possible and keep the repository as the source for infrastructure. Automate changes through CI/CD. Make infrastructure changes through pull requests and have them reviewed before application.
### DEC-007: Preserve Docker Swarm deployment for legacy stack files
- **Decision:** Legacy Docker Swarm stack files should remain compatible with Docker Swarm and be deployed with `docker stack deploy -c <file> <stack-name>`, not `docker compose up`.
## Draft
No draft decisions recorded.
## Declined
No declined decisions recorded.
## Adding a decision
Add each decision under its current status. Use a unique `DEC-NNN` identifier and include the context, decision, and consequences. Drafts are not instructions; move a decision to Accepted when approved, or to Declined if it is not adopted.
### DEC-NNN: Short title
- **Context:** Why a decision is needed.
- **Decision:** What is decided.
- **Consequences:** Important effects or tradeoffs.
+161
View File
@@ -0,0 +1,161 @@
# Open findings
This file tracks findings from the repository compliance review against the
accepted decisions in [AGENTS.md](./AGENTS.md). The root
[README.md](./README.md) now documents the repository and manual operations;
the findings below are the remaining unresolved items.
## DEC-001 — Kubernetes is not yet the primary infrastructure
**Status:** Open
The root [kustomization.yaml](./kustomization.yaml) currently reconciles Flux,
DNS, the agent gateway, and network-policy scaffolding, but no production
application workloads. Production services are still documented as Docker
Swarm deployments in [PROD.md](./PROD.md), and service definitions remain
under [poc/](./poc/), [nextcloud/](./nextcloud/), and
[hermes_squid/](./hermes_squid/).
Required follow-up:
- Define target Kubernetes namespaces and ownership for production services.
- Add application overlays under `k3s_rencher/`.
- Migrate services to Kubernetes one at a time.
- Add migrated workloads to the root Kustomize entry point.
- Replace production Swarm instructions after each successful migration.
## DEC-003 — Ansible has not been retired
**Status:** Open
The repository still contains active-looking playbooks, inventory, variables,
Galaxy dependencies, and host-management roles:
- [all.yaml](./all.yaml)
- [gogs.yaml](./gogs.yaml)
- [orientdb.yaml](./orientdb.yaml)
- [syncthing.yaml](./syncthing.yaml)
- [hosts](./hosts)
- [group_vars/all](./group_vars/all)
- [requirements.yaml](./requirements.yaml)
- [roles/](./roles/)
Required follow-up:
- Inventory all Ansible-managed resources.
- Classify each resource as migrated, required for host bootstrap, obsolete,
or requiring a Kubernetes replacement.
- Retain only unavoidable host bootstrap.
- Deprecate and then remove obsolete playbooks, roles, inventory, and
dependencies after replacement procedures are documented.
## DEC-004 — Swarm remains the production deployment path
**Status:** Open
Legacy Swarm files may remain during migration, but [PROD.md](./PROD.md) still
instructs operators to initialize Swarm and deploy production services with
`docker stack deploy`. Service documentation also presents Swarm or Docker
Compose as the primary deployment method.
Relevant legacy material includes:
- [docker-compose-nginx.yaml](./docker-compose-nginx.yaml)
- [docker-compose-registry.yaml](./docker-compose-registry.yaml)
- [nextcloud/stack-compose.yaml](./nextcloud/stack-compose.yaml)
- [hermes_squid/stack-compose.yml](./hermes_squid/stack-compose.yml)
- [poc/immich/stack-compose.yml](./poc/immich/stack-compose.yml)
- [poc/gitea/stack-compose.yml](./poc/gitea/stack-compose.yml)
- [poc/vscode/stack-code-server.yml](./poc/vscode/stack-code-server.yml)
Required follow-up:
- Mark remaining Swarm files and instructions as legacy and identify their
migration status.
- Do not add new Swarm services.
- Migrate production services to Kubernetes and replace their operational
instructions.
- Keep legacy stack files compatible with `docker stack deploy` until removed.
## DEC-005 — Namespace isolation is incomplete
**Status:** Partially implemented
The default policies in
[default-deny.yaml](./k3s_rencher/infrastructure/network-policies/default-deny.yaml)
and the DNS exception in
[allow-dns.yaml](./k3s_rencher/infrastructure/network-policies/allow-dns.yaml)
are currently applied through the `agent-gateway` overlay only.
Required follow-up:
- Create a dedicated Kustomize overlay for every workload namespace.
- Apply default-deny ingress and egress to every workload namespace.
- Add explicit ingress, pod-to-pod, and external egress policies per service.
- Decide and document the policy baseline for `flux-system` and other system
namespaces.
- Verify that the externally sourced connectivity tester has equivalent
namespace and network-policy controls.
- Review all future uses of `hostNetwork`, host ports, privileged containers,
and node-originated traffic.
## DEC-006 — GitOps changes are not sufficiently validated or gated
**Status:** Partially implemented
Flux reconciliation is configured through
[flux-system/gitrepository.yaml](./k3s_rencher/flux-system/gitrepository.yaml)
and [flux-system/sync.yaml](./k3s_rencher/flux-system/sync.yaml), but the
repository has no visible pull-request validation workflow for Kubernetes
changes. The existing
[release workflow](./.gitea/workflows/release.yml) only builds and publishes
the connectivity tester image.
Required follow-up:
- Add pull-request checks for YAML, Kustomize rendering, Kubernetes schemas,
network policies, secrets, and image references.
- Protect the Flux-tracked branch and require review plus passing checks.
- Document the one-time bootstrap boundary versus normal Flux-managed changes.
- Add rollback and reconciliation verification procedures.
- Review whether public Git sources are an intentional trust decision.
- Prefer immutable image tags or digests over `latest` for production.
## Secret and credential hygiene
**Status:** Open
Potential credentials and unsafe examples remain in tracked files, including
[roles/metricbeat/defaults/main.yml](./roles/metricbeat/defaults/main.yml),
[roles/orientdb/defaults/main.yml](./roles/orientdb/defaults/main.yml),
[scratches/tomcat/tomcat-users.xml](./scratches/tomcat/tomcat-users.xml),
and [hermes_squid/README.md](./hermes_squid/README.md).
Required follow-up:
- Determine whether each value was ever active.
- Rotate any potentially active credential.
- Remove credentials from tracked files and examples.
- Use SOPS, External Secrets, or another approved secret manager for
Kubernetes workloads.
- Keep only clearly fake placeholders in documentation.
## Repository structure and lifecycle
**Status:** Open
The repository is still structured primarily as an Ansible project even though
the accepted direction is Kubernetes and GitOps. Kubernetes resources,
experimental deployments, legacy stacks, and historical scratch files are
mixed together.
Required follow-up:
- Establish clear ownership boundaries for cluster bootstrap,
infrastructure, applications, legacy deployments, and historical material.
- Consider separating `cluster-bootstrap/`, `infrastructure/`, `apps/`, and
`legacy/`.
- Archive or remove obsolete material only after its replacement and rollback
procedure are documented.
- Keep the root [README.md](./README.md) and this file updated as migrations
complete.
+43
View File
@@ -0,0 +1,43 @@
# Infrastructure repository
See [FINDINGS.md](./FINDINGS.md) for unresolved compliance findings and
required follow-up actions.
## Manual operations and service documentation
### Cluster and production operations
- [K3s installation and health operations](./k3s_rencher/README.md)
- [GitOps and Flux bootstrap](./k3s_rencher/README-gitops.md)
- [Legacy production setup](./PROD.md)
- [Legacy Docker Compose operations](./README_docker_compose.md)
### Service documentation
- [Nextcloud operations](./nextcloud/README.md)
- [Hermes Squid operations](./hermes_squid/README.md)
- [Anywherelan deployment](./poc/anywherelan/README.md)
- [Beszel stack](./poc/beszel/stack-compose.yml)
- [Gitea runner stack](./poc/gitea/stack-compose.yml)
- [Hermes stack](./poc/hermes/README.md)
- [Immich stack](./poc/immich/README.md)
- [Lampa stack](./poc/lampa/README.md)
- [NetBird deployment](./poc/netbird/README.md)
- [VS Code server stack](./poc/vscode/README.md)
The service-specific Docker documentation remains valid only for services
that have not yet been migrated. Update the migration status above and the
service documentation when a service moves to Kubernetes.
## Repository layout
- [k3s_rencher/](./k3s_rencher/) — Kubernetes and Flux resources.
- [connectivity_tester/](./connectivity_tester/) — connectivity tester image
and tests.
- [poc/](./poc/) — legacy and experimental service deployments.
- [nextcloud/](./nextcloud/) and [hermes_squid/](./hermes_squid/) — legacy
service deployments.
- [roles/](./roles/) — legacy Ansible roles retained during migration.
- [scratches/](./scratches/) — historical experiments; not production
configuration.