Files
aevolution/deploy/README.md
T
dingoandClaude Opus 5.5 8ef69fab1d Add M8.4 region host deployment, provisioning hook and drill
Deploy evo-region per environment (ADR-0071): one replica with the
Recreate strategy (a rolling update would deadlock on the lease),
/readyz readiness, /livez liveness, no CPU limit and a drain inside the
grace period, with the image digest doubling as the build identity. A
new idempotent evo-world-clone provision subcommand creates genesis from
development_opening (byte-identical to the qualification fixture) as a
Sync hook after the migration. Dev and stage paths include their region;
a dev AppProject allows Deployment and Service; region-drill.sh times
rollout and forced-deletion recovery; the policy check enforces the
host's invariants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:32:56 -04:00

168 lines
9.2 KiB
Markdown

# Build and dev delivery
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.