# Test Automation Architecture

## Responsibilities

GitLab CI is the orchestrator. It validates the project configuration, starts
tool-specific Kubernetes jobs, collects raw output, invokes normalizers, and
publishes rendered reports. Ansible is one test executor alongside ZAP and
future tools; it is not the pipeline controller.

```mermaid
flowchart LR
    A[assets.yml] --> V[Validate and prepare]
    V --> K[k3s tool jobs]
    K --> AN[Ansible]
    K --> Z[ZAP]
    K --> O[Other tools]
    AN --> R[Raw artifacts]
    Z --> R
    O --> R
    R --> N[Tool adapters]
    N --> J[Normalized JSON]
    J --> D[Markdown / HTML / PDF]
    D --> G[GitLab artifacts]
```

## Data Contracts

- `assets.yml` is the canonical project and asset list. It is valid Ansible
  YAML inventory and is parsed during pipeline preparation for CI metadata.
- Tool output is retained unchanged under `artifacts/raw/<tool>/`.
- Every adapter writes schema-valid reports under `artifacts/normalized/`.
- `schemas/test-report.schema.json` is the versioned interface between tools
  and report generation. Standards mappings belong on individual results, so
  IEC 62443 and OWASP ASVS findings can coexist without flattening semantics.
- Generated Markdown, HTML, and PDF files are stored under
  `artifacts/rendered/` and uploaded as GitLab artifacts.
- `TARGET_ENVIRONMENT` selects GitLab environment-scoped variables and must
  match the environment declared in `assets.yml`. Only tool jobs declare that
  GitLab environment, keeping secrets out of validation and rendering jobs.

## Kubernetes State

The `test-automation` namespace contains reusable platform state. The initial
manifests request one volume using the cluster's default StorageClass:

`tool-cache` is a long-lived, replaceable cache for downloaded vulnerability
databases, scanner rules, and package indexes.

Pipeline evidence is never authoritative on a PVC. GitLab artifacts are the
immutable record and receive an explicit retention policy. Databases that
require transactions or concurrent writers should use a dedicated StatefulSet
and PVC rather than the shared cache. Back up only state that cannot be
reconstructed from an upstream feed.

ZAP jobs are ephemeral and receive no persistent ZAP home by default. This
prevents sessions, authentication state, and target data from leaking between
projects. Only a future explicitly reviewed ZAP add-on cache should use
`tool-cache`.

## Job Isolation

Each GitLab CI job is already an ephemeral pod because `testserv` uses the
Kubernetes executor. Tool jobs receive the checked-out project, narrowly scoped
credentials, resource requests and limits, and the shared tool cache. Output is
written to the GitLab workspace and uploaded directly as pipeline artifacts.
NetworkPolicy should be added once target ranges and proxy requirements are known.

## Required Runner Configuration

The runner manager on `testserv` uses the `ci/gitlab-runner` ServiceAccount.
Configure its Helm values so `[runners.kubernetes].namespace` is
`test-automation`, and mount the `tool-cache` PVC at `/cache/tools`. The
cross-namespace RoleBinding in `platform/kubernetes/runner-rbac.yml` grants only
the pod, attach, log, Secret, Service, and event operations required by GitLab's
Kubernetes executor.

Bootstrap the namespace, storage, and RBAC once with an administrator context:

```bash
kubectl apply -k platform/kubernetes
```

CI tool pods do not need Kubernetes API credentials. The runner manager uses its
in-cluster identity to create and clean them up. Do not copy the admin kubeconfig
into GitLab CI.

## Delivery Sequence

1. Make inventory validation, schema validation, and report rendering mandatory.
2. Run Ansible in its GitLab Kubernetes-executor pod and normalize its JSON.
3. Add ZAP Automation Framework plans and a ZAP-to-common-schema adapter with
   ASVS mappings.
4. Add SBOM generation through Ansible for Windows and Linux targets; preserve
   CycloneDX as a raw artifact and normalize policy findings separately.
5. Add aggregate project reports and quality-gate policies after result semantics
   are stable.