forked from org1/infra
x
This commit is contained in:
@@ -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`.
|
||||
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user