Files
dingo fad79973e2
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m24s
Foundation / postgres-tools (push) Successful in 6s
Foundation / server-image (push) Successful in 5s
Foundation / image (push) Successful in 6s
fix(deploy): constrain DEV workloads to worker nodes
2026-10-19 15:08:00 -04:00

191 lines
10 KiB
Markdown

# Build and dev delivery
## Current delivery flow (maintainer confirmed 2026-10-19)
Pushing to Git runs Actions, which builds and publishes to Harbor; ArgoCD picks
up the deployment and delivers it to Kubernetes. Workload manifests are under
`deploy/`. Use this configured flow for development delivery. The manual-sync
and image-pinning instructions below describe earlier setup and must not be
treated as a request to replace the current automation.
DEV workloads use `evolution-dev`, run on worker nodes rather than the control
plane, and retain the existing PostgreSQL server, network structure and URLs.
The full DEV and standalone region/store overlays enforce both standard
control-plane role exclusions through `worker-only-dev`; rendered policy checks
every required alternative and refuses a direct `nodeName` bypass. See
[placement evidence](../docs/engineering/M12_DEV_WORKER_PLACEMENT.md).
Qualification data must remain isolated from existing worlds. Immediately before
each push refresh `REGION_SESSION_WINDOW` in
`kubernetes/region/dev-session-route/listener.yaml` with a unique activation and
an absolute UTC expiry four hours ahead. Record actual pipeline/deployment
results separately: a push alone does not prove build success or reachability.
World0 deployment, reset and pruning remain outside routine development.
## Historical setup and verification notes
The maintainer has configured Gitea, Harbor and Argo. Gitea run
[1399](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1399)
successfully built, tested and published commit `8ab48d3`. This repository adds
broader checks and a bounded **stateless proof Job**. It is not a region server.
Cluster execution must be recorded separately from image publication.
The expanded [run 1402](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1402)
passed all checks and published `4c2cc04`. The maintainer's later GitOps commit
`20e609d` pins the verified run 1399 image instead; M1.6 preserves that selection.
The maintainer confirms Argo is ready to pick up deployment additions. Bootstrap
examples still need the actual
application namespace and destination; do not apply examples unchanged.
## Gitea and Harbor
The single workflow is `.gitea/workflows/build.yaml`. The existing runner label
is `ubuntu-22.04`; this does not imply its compiler version. Checks use explicit
Ubuntu 24.04 Docker stages with GCC14 and LLVM19. The runner needs Git, Node20 for
checkout, Bash and a working Docker builder.
| Setting | Kind | Value / purpose |
|---|---|---|
| HARBOR_HOST | Existing variable | registry.aeternalisgames.com; publishing is scoped to this host |
| HARBOR_PROJECT | Existing variable | aeternalis |
| HARBOR_USERNAME / HARBOR_PASSWORD | Existing secrets | Harbor push robot; values never belong in Git |
| HARBOR_REPOSITORY | Optional variable | Defaults to aevolution |
| CI_RUNNER_LABEL | Optional variable | Defaults to the verified ubuntu-22.04 label |
| UBUNTU_IMAGE | Optional variable | Defaults to ubuntu:24.04; prefer a reviewed base digest |
Checks include Debug/Release CTest, format, clang-tidy, ASan/UBSan, a million
synthetic ticks and bounded seeded libFuzzer. TSan runs separately. No failure
is ignored. Windows MSVC checks use `tools/windows-check.ps1`. The image job waits
for checks and executes a restricted runtime smoke test. Only main push/manual
runs publish, using a temporary Docker credential directory.
Published tags use `sha-<commit>-run-<run-number>-<attempt>` to distinguish rebuilds.
This replaces the original commit-only tag convention. The job prints the
registry digest in its logs/summary. GitOps references the digest, never latest.
CI does not receive cluster credentials or automatically commit/sync GitOps.
Use isolated runners for untrusted pull requests; Docker access is privileged.
## Local container checks
```sh
docker build --progress=plain -f deploy/docker/Dockerfile --target ci-checks .
docker build --progress=plain -f deploy/docker/Dockerfile --target ci-tsan .
docker build -f deploy/docker/Dockerfile -t aeternalis-evo:dev .
docker run --rm --network none --read-only --cap-drop ALL \
--security-opt no-new-privileges aeternalis-evo:dev \
--seed 123456 --entities 8 --ticks 1000 --verify-replay
```
Runtime UID/GID is 10001; JSON goes to stdout. Builder package versions are in
`/usr/share/evo/build-packages.txt`; file output needs an explicit writable mount.
Source COPY operations exclude local chat logs, `.git` and credentials. Ubuntu
security packages move: production promotion still needs pinned provenance,
SBOM, scan/signature and retention. TSan on this sequential proof validates
instrumentation, not future concurrency. Record actual results in VALIDATION.md.
## Argo settings and promotion
Reuse the maintainer's confirmed application. The following are bootstrap
settings for an application watching this repository directly, not an inspection
of the live application's configuration:
| Field | Value |
|---|---|
| Repository | https://git.aeternalisgames.com/dingo/AEvolution.git |
| Revision | main; review the resolved commit before syncing |
| Path | deploy/kubernetes/dev |
| Destination namespace | evolution-dev |
| Project | aevolution-dev, or an equivalently restricted project |
| Sync | Manual full sync; no automated prune/self-heal (recommended) |
Inventory (2026-09-29, docs/infrastructure/INVENTORY.md): the live `aevolution-dev`
application has no automated sync, which matches this guidance. Other projects'
applications do auto-sync with prune. Keep AEvolution durable resources out of any
automated-prune application.
Bootstrap examples in `deploy/argocd/*.yaml.example` are outside the workload
path. Replace the Argo namespace and registered cluster API URL, or use its UI.
Create evolution-dev separately. Configure Argo's private Git read credential
and a **pull-only** harbor-pull Secret in that namespace. Neither is the CI push
credential. The project allows only Job, ServiceAccount and NetworkPolicy there.
Before syncing:
1. Wait for successful checks and publication of the intended commit.
2. Update `deploy/kubernetes/dev/kustomization.yaml` to the published
`sha256:<64 hex>` digest, review and commit it. It currently pins run 1399;
no floating tag or fallback image is used.
3. Run `kubectl kustomize deploy/kubernetes/dev`. Check exactly three resources,
all in evolution-dev, the selected digest and no unresolved marker.
4. Full-sync the dev app. Selective sync skips hooks.
5. Verify Job aevolution-dev-proof completes with exit 0 and JSON
`replay_verified: true`, seed 123456, 8 entities and 100000 ticks. Record the
digest, source commit and result in the validation report.
The Job has a five-minute deadline, no retries, token mount, network access or
writable root, and bounded resources. NetworkPolicy requires CNI enforcement;
node-level image pulling is separate from pod egress. No Service, port, PVC or
persistent world is included. BeforeHookCreation retains the latest Job until
the next full sync replaces it; collect logs first. Kubernetes can execute a Job
more than once: harmless here, not an exactly-once persistence mechanism.
World0 is unchanged. Persistent deployment follows
[infrastructure architecture](../docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md)
and [operations gates](../docs/infrastructure/OPERATIONS.md).
TSan requires execution outside the Docker build sandbox on this runner. The
ci-tsan target now builds its tests; the Gitea workflow runs them in a non-root,
read-only, networkless container with tmpfs test-output directories. Its pinned
Moby seccomp profile adds only personality(0x40000). No host security settings
change. See ADR-0020 for the source, integrity hash and removal policy. Building
the ci-tsan image alone is NOT a TSan test pass; use the workflow's docker run
command with the generated profile to execute it locally.
The TSan run requires writable tmpfs mounts for `build/tsan/Testing`,
`build/tsan/cli-integration` and `build/tsan/world-proof`, plus `/tmp`. Each is
bounded to 16 MiB in the workflow. The world restart test retains generated snapshots,
journals and JSON reports beneath its own random run directory; it cannot create
that directory on the read-only image filesystem. Any new file-producing CTest
must declare its scratch directory in this container invocation as well.
## PostgreSQL migration tooling
The `postgres` CI matrix builds and tests the isolated adapter in Release,
clang-tidy and ASan/UBSan against private PostgreSQL clusters. The `postgres-tools`
Docker target contains pinned psql plus checked-in migrations, not a database server.
Set Gitea variable `HARBOR_POSTGRES_REPOSITORY=aevolution-postgres-tools` to enable
publishing that image using existing HARBOR_PROJECT and robot secrets. Leave it
unset for build/smoke only. Use the reported immutable digest in the Job example.
Do not reuse the simulation image repository for this entrypoint.
[Secret and role setup](../docs/infrastructure/POSTGRESQL.md) describes the separate
migrator/runtime credentials. The example is outside active Argo resources until
an operator supplies the database endpoint, role, Secret and egress rules. No region
server or world-state migration is deployed by M7.2. Schema v2 (M7.3) additionally
requires `EVO_PG_RUNTIME_ROLE`, naming an operator-created NOLOGIN runtime group role.
## Region server image (M7.8)
The `server-image` job builds the Docker target `server-runtime` (`evo-server`
plus the pinned libpq, UID 10001, no credentials). It smoke-tests the image with
`tools/ci/server-image-smoke.sh` and publishes only when Gitea variable
`HARBOR_SERVER_REPOSITORY` is set.
The region host is deployed from `kubernetes/region/<env>` (M8.4, ADR-0071),
included in each environment's Argo path. It replaces the former
`region-server` example. Probes: `/readyz` means authority, and `/livez` means
only that the process is alive. Without a gateway, the region receives no inputs.
## Environments and World0 protection (M8.2)
`kubernetes/platform/<env>` holds each environment's namespace, quota, limit range,
default-deny policies and service accounts. `kubernetes/platform/admission` holds
the World0 admission policy. Since the M8.3 amendment they are delivered by the
`aevolution-platform` Argo Application (`kubernetes/platform/cluster`), which
self-heals and never prunes. Originally a cluster administrator applied them by
hand; they
are never part of an Argo Application. The stage and World0 Argo projects and
applications are in `argocd/stage` and `argocd/world0` as examples.
See docs/infrastructure/ENVIRONMENTS.md for the runbook, and ADR-0069. The CI
`deploy` suite runs `tools/ci/deploy-policy-check.py` over every manifest.