Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Gateway Fleet to dns-api publication contract (v1)

APT-822 / ADR-0083: these fixtures cross the repository boundary without importing
another repository's `internal` package. They are real source Gateway and
HTTPRoute objects captured after the platform Gateway Fleet `Reconciler` runs,
not hand-authored source status.

## Ownership and regeneration

The producer is platform's
`internal/controllers/gatewayfleet/publication_dns_contract_test.go`,
`TestPublicationDNSContract`. From the platform repository root, regenerate with:

```sh
UPDATE_PUBLICATION_DNS_CONTRACT=1 go test ./internal/controllers/gatewayfleet -run '^TestPublicationDNSContract$' -count=1
```

Without `UPDATE_PUBLICATION_DNS_CONTRACT=1`, the producer compares its complete
normalized output with the golden JSON and verifies `SHA256SUMS`. The generator
writes nothing until every scenario has been produced successfully, and refuses
a run filtered to some scenarios.

Copy this **entire directory byte-for-byte**, including this README and
`SHA256SUMS`, to dns-api's
`internal/go/apps/gatewayendpoint/controllers/gateway/testdata/publication-dns-contract/v1/`.
The consumer there is also named `TestPublicationDNSContract`; it verifies the
checksums and the complete 12-scenario inventory before reconciling anything.
A fixture change must land in **both repositories**. Platform's dns-api import
approval PRs under `hack/upstream-artifacts/...` must check that the imported
revision carries the current, byte-identical copy. A green test in only one
repository is not cross-repository approval. **Known gap:** no CI job fails
today when only one copy changes; each repository checks its own
`SHA256SUMS` only. Tracked as APT-1187 (pin the dns-api copy's checksum in the
import record).

Coverage limits: for dns-api, `leaf-unreachable`/`reconciler-restart` and
`leaf-policy-status-absent`/`policy-rejected` carry identical inputs; they stay
separate because the producer pins different Fleet paths. `route-deleted`
covers a route that is already absent, not one held by its finalizer.

## Wire format

Each JSON document contains `scenario`, `description`, `gateway`, `routes`, and
`expect`. Metadata retains only name, namespace, UID and generation. Gateway spec
and status are captured in full. Routes retain spec hostnames and parentRefs and
status parents. API version and kind are retained. Resource versions, managed
fields and creation timestamps are excluded; condition transition timestamps are
fixed to `2026-01-01T00:00:00Z`. Fixture identities, route order and JSON key order
are deterministic. `SHA256SUMS` covers every JSON fixture (not itself or this
README).

`expect.hostnames` means:

- `retain`: all established names must remain.
- `withdraw-hostnames`: exactly these names must disappear; other names remain.
- `withdraw-all`: all listed established names and the shared set must disappear.

The baseline has 12 source routes and 13 names: `app-00` also publishes
`alias.project.example`. Thus hostname removal tests partial withdrawal within
one route, and route removal/replacement tests unaffected siblings too.

## Current contract, not future wave-3 behavior

The producer captures actual status rather than rewriting it to a desired tuple.
In particular, absent leaf SecurityPolicy status currently closes the edge with
`Accepted=False/RouteClosed` and `PoliciesReady=False/PoliciesNotReady`. This is
the deliberate fence until ADR-0083 wave 3 Q2, not the future `Unknown` behavior.
Under D4, dns-api retains the already receipted hostname for either False or
Unknown route acceptance. Explicit policy rejection has the same DNS outcome.
An explicit observed Gateway rejection instead withdraws the shared set.

The incomplete-pass cases preserve source route status, while Gateway acceptance
can become Unknown. ParentRef removal may leave an old parent status whose
observed generation predates the new route generation: the intent removal, not
that stale status, authorizes DNS withdrawal. APT-1087 backend projection lag is
intentionally not included.

## Consumer restart and provider boundary

The consumer establishes healthy publication using the real gateway-endpoint,
endpointrecordset, ZoneUnit composition and Route 53 reconcilers. It uses the
retention-test harness's HTTP conversion handler and in-memory Route 53 provider.
It requires persisted admission receipts, EndpointRecordSet/child UIDs, and
provider records before taking a snapshot.

Each scenario reconstructs a fresh fake API client and every reconciler from
that snapshot, substitutes only the captured source Gateway/routes, and starts
with a fresh provider adapter holding the existing records. No previous
reconciler or admission cache is reused. Existing source-route incarnations keep
their DNS-owned finalizers. All baseline route keys, including a deleted route's
key, are reconciled. Convergence is bounded to 16 passes and compares all stored
objects, provider records, tags and the provider action log. It ignores only
metadata resourceVersion/managedFields and EndpointRecordSet hostname-condition
lastTransitionTime (the independently tracked APT-1185 status-restamping defect).
Ignored status-only writes are counted and logged for each scenario. Specs,
receipts, annotations, finalizers and every other status field remain compared.

Retain cases require the EndpointRecordSet and every child RecordSet UID/spec to
remain unchanged. Every Route 53 DELETE action is counted, so DELETE followed by
UPSERT cannot hide a transient withdrawal. Withdrawal cases require exactly the
specified provider names and children to disappear, with sibling identities and
records unchanged. Gateway rejection additionally requires the shared
EndpointRecordSet to be gone. No live infrastructure or AWS credentials are used.
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
202163804317467782bf01bc7c04cc809826b823a786d3fbed1759dc52e0bf5a apply-conflict.json
ab6de530bf3de6fdd5e76f545a0c3a425a02bce89843c1fb0a82fc67f4b4c224 gateway-rejected.json
553505c184da41d665bd2c4dd489f24d6a2363c158cb7769f7593eabdaecf425 healthy.json
fd5ead3daaf87db5703522501e411fd5171424586750cbe8cf5cfd1c04518313 hostname-removed.json
cc81d34706db32fb06b2b57eaaa83436ed066da85550064b4a7ce29587cbf908 leaf-policy-status-absent.json
4cfd22fba3cf97aa7a2d642ff26133ec3740dc14babcaee63bbf3503ab3b8bba leaf-route-status-stale.json
779238ad7430a8b6bf6054d1289898c21862111e0807dcfb1b918f37b2118972 leaf-unreachable.json
ae9475a2bd36f22ad71c73aa2e2f0388b40a0a095dc0dd947e49ef2aa81229dc parentref-removed.json
aa66b3f4c91f0711cd56a0387c8881757f25ea870d2aff086ca132ca8be2945d policy-rejected.json
c6dc459f3c135b0f16c5073959e7a7e3cec0dcae071657e8d5e4238bd89538cb reconciler-restart.json
0f26cdaf578ca6c9f967a7c4039097cea7ea4e86f3495f99fb2795ba6599dab4 route-deleted.json
090b06ec4c17bd69bcb697dbfd7305e4979990a3c4034193124e50b3b6e73441 route-replaced.json
Loading
Loading