From 463cfffc12fe6c2e2baaad6b0b0adbe5f88cbac7 Mon Sep 17 00:00:00 2001 From: mxab <1607547+mxab@users.noreply.github.com> Date: Thu, 20 Aug 2026 08:45:10 +0000 Subject: [PATCH] docs: update OpenWiki --- openwiki/.last-update.json | 4 ++-- openwiki/operations-testing.md | 9 ++++++++- openwiki/quickstart.md | 1 + openwiki/source-map.md | 4 ++-- 4 files changed, 13 insertions(+), 5 deletions(-) diff --git a/openwiki/.last-update.json b/openwiki/.last-update.json index 02f0136..8a213c5 100644 --- a/openwiki/.last-update.json +++ b/openwiki/.last-update.json @@ -1,7 +1,7 @@ { - "updatedAt": "2026-08-11T09:04:20.688Z", + "updatedAt": "2026-08-20T08:45:01.863Z", "command": "update", - "gitHead": "474dc01bd70e9c80acadad69d72b9360fdd920bf", + "gitHead": "72afb1c68ddf7a86f7720ebbbb5da6e0f460b621", "model": "gpt-5.6-terra", "status": "complete", "language": "en" diff --git a/openwiki/operations-testing.md b/openwiki/operations-testing.md index 4eb8e27..eb48c44 100644 --- a/openwiki/operations-testing.md +++ b/openwiki/operations-testing.md @@ -36,7 +36,14 @@ Run the smallest relevant package test without cached results. The full reposito | Controller sequencing and adapter contracts | `pkg/admissionctrl/controller_test.go` and colocated adapter tests | `go test ./pkg/admissionctrl/... -count=1` | shared configuration or executable wiring changes | | HCL schema/defaults/startup failures | `pkg/config/config_test.go` | `go test ./pkg/config -count=1` | controller construction is changed too | | OTel provider/export and HTTP instrumentation | `pkg/otel/otel_test.go`, `cmd/nacp/nacp_otel_test.go` | `go test ./pkg/otel ./cmd/nacp -count=1` | exporter behavior or metrics schema changes | -| Notation registry/signature behavior | `pkg/admissionctrl/{notation,validator}/` tests | `go test -tags=integration ./pkg/admissionctrl/notation` | the image verification contract crosses packages | +| Notation task selection/errors | `TestNotationValidatorValidate` in `pkg/admissionctrl/validator/notation_validator_test.go` | `go test ./pkg/admissionctrl/validator -count=1` | the verifier, registry, trust-store, credential-store, or image-client boundary changes | +| Notation registry/signature behavior | `TestVerifyImage` in `pkg/admissionctrl/notation/notation_test.go` | `go test -tags=integration ./pkg/admissionctrl/notation` | the image verification contract crosses packages | + +### Notation validation dependency boundary + +The production verifier in `pkg/admissionctrl/notation/notation.go` uses Notation and ORAS to verify a remote artifact; it does not use a Docker client. Its Docker-backed integration test, `TestVerifyImage`, launches a registry, builds and pushes an image, signs it, and verifies both unauthenticated and authenticated registry cases. That test imports the split Moby API/client modules declared in `go.mod` (`github.com/moby/moby/api` and `github.com/moby/moby/client`), which replace the legacy `github.com/docker/docker` module named by the current visible dependency-change commit. + +For a validator-only change, run the ordinary validator package test first. Run the integration command only when changing registry/signature behavior, the test's Docker/Moby client boundary, or the dependency declarations; it requires a usable Docker environment. The result then feeds the `notation` controller contract described in [policy integrations](policy-integrations.md#notation-image-verification). CI in `.github/workflows/go.yml` runs format, `go vet ./...`, build, and `go test -tags=integration -coverprofile=cov.all.out -v ./...`, then excludes generated `o11y/metric.go` from the coverage report before SonarCloud analysis. `sonar-project.properties` also excludes that generated source through `**/o11y/metric.go`. Use that broader path before a cross-package or release handoff, not as the first check for a narrow change. diff --git a/openwiki/quickstart.md b/openwiki/quickstart.md index a01b9ab..9d122c0 100644 --- a/openwiki/quickstart.md +++ b/openwiki/quickstart.md @@ -61,6 +61,7 @@ Use the narrow package command first; `-count=1` avoids a cached success while k | Change mutation ordering, validator behavior, warnings, or errors | [Proxy and admission pipeline](architecture.md#controller-contract) | `pkg/admissionctrl/controller.go` | `JobHandler`, `ApplyAdmissionControllers`, `AdmissionMutators`, `AdmissionValidators` | `TestJobHandler_ApplyAdmissionControllers`, `TestJobHandler_ValidatorsReceiveIsolatedCopyOfMutatedJob` | `go test ./pkg/admissionctrl -count=1` | | Add a controller type or change HCL startup validation | [Policy integrations and configuration](policy-integrations.md#configuration-and-startup-validation) | `pkg/config/config.go`, `cmd/nacp/nacp.go` | `Config.Validate`, `validateMutator`, `validateValidator`, `createMutators`, `createValidators` | `TestConfigValidation`, `TestCreateMutatators`, `TestCreateValidators` | `go test ./pkg/config ./cmd/nacp -count=1` | | Change embedded OPA, bundle, webhook, patch, or Notation result handling | [Policy integrations and configuration](policy-integrations.md) | `pkg/admissionctrl/{opa,mutator,validator,notation,remoteutil}/` | adapter constructors, `types.Payload`, `DecodeJSONResponse` | corresponding colocated `*_test.go` | `go test ./pkg/admissionctrl/... -count=1` | +| Change Notation registry/signature behavior or its Docker/Moby test dependencies | [Operations and testing](operations-testing.md#notation-validation-dependency-boundary) | `pkg/admissionctrl/notation/notation.go`, `pkg/admissionctrl/notation/notation_test.go`, `go.mod` | `NewImageVerifier`, `VerifyImage`, `TestVerifyImage` | `TestVerifyImage` covers unauthenticated and authenticated local registries; `TestNotationValidatorValidate` covers Docker-task selection | `go test -tags=integration ./pkg/admissionctrl/notation` (requires Docker) | | Change listener/upstream TLS, telemetry, CI, or release | [Operations and testing](operations-testing.md) | `cmd/nacp/nacp.go`, `pkg/otel/otel.go`, `.github/workflows/`, `.goreleaser.yaml` | `buildServer`, `buildCustomTransport`, OTel setup | `TestCreateTlsConfig`, `TestBuildCustomTransport`, `TestOtelInstrumentation` | `go test ./cmd/nacp ./pkg/otel -count=1` | | Find an example, fixture, or generated metric source | [Source map](source-map.md) | `example/`, `testdata/`, `pkg/o11y/nacp.yaml` | generated `pkg/o11y/metric.go` | adjacent package tests | `go test ./pkg/o11y/... -count=1` when generator/runtime code changes | diff --git a/openwiki/source-map.md b/openwiki/source-map.md index dae465b..e2c6f8e 100644 --- a/openwiki/source-map.md +++ b/openwiki/source-map.md @@ -34,9 +34,9 @@ The runtime code implements the ordered lifecycle in [architecture](architecture | JSON Patch implementation | `pkg/admissionctrl/mutator/opa_json_patch.go`, `pkg/admissionctrl/mutator/jsonpatcher/` | Embedded OPA patching and patch application. | | OPA SDK/bundle adapters | `pkg/admissionctrl/{validator,mutator}/opa_bundle_*.go` | SDK decision result handling for validation and patch mutation. | | Remote policy adapters | `pkg/admissionctrl/{validator,mutator}/*webhook*.go`, `pkg/admissionctrl/remoteutil/` | Payload serialization, response parsing, forwarded context headers, outbound instrumentation. | -| Image verification | `pkg/admissionctrl/notation/`, `pkg/admissionctrl/validator/notation_validator.go` | Trust policy/store loading and Docker-task image verification. | +| Image verification | `pkg/admissionctrl/notation/`, `pkg/admissionctrl/notation/notation_test.go`, `pkg/admissionctrl/validator/notation_validator.go`, `pkg/admissionctrl/validator/notation_validator_test.go` | Trust policy/store loading, remote verification, Docker-task selection, and the Docker-backed registry integration test. | -These paths implement the controller types listed in [policy integrations](policy-integrations.md#configuration-and-startup-validation). Keep result shape tests adjacent to the adapter that interprets it. +These paths implement the controller types listed in [policy integrations](policy-integrations.md#configuration-and-startup-validation). Keep result shape tests adjacent to the adapter that interprets it. The Docker-backed registry test is an operational, conditional check; its prerequisites and scope are defined in [operations and testing](operations-testing.md#notation-validation-dependency-boundary). ## Operations and generated observability