Files
aevolution/deploy/README.md
T
dingo c60cdf8e19
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (client) (push) Canceled after 1m11s
Foundation / checks (checks) (push) Canceled after 1m13s
Foundation / checks (postgres) (push) Canceled after 1m8s
Foundation / checks (ecs) (push) Canceled after 1m13s
Foundation / checks (network) (push) Canceled after 1m14s
Foundation / checks (deploy) (push) Canceled after 1m18s
feat(persistence): admit durable retained offspring plans
2026-10-19 15:04:30 -04:00

187 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.
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.