docs: network adapter deployment modes -- ADR-0001, READMEs, CHANGELOGs, Postman (#55, #66)

api-collection/OpenAgriNet.network-adapter.local-environment.json

@@ -0,0 +1,162 @@
+{
+  "id": "oan-local-environment-single",
+  "name": "OpenAgriNet local (single mode)",
+  "values": [
+    {
+      "key": "consumer-adapter-host",
+      "value": "http://127.0.0.1:9201",
+      "enabled": true,
+      "type": "default",
+      "description": "Where discover and select enter. Single mode: the one adapter, so all three adapter hosts are the same URL. NETWORK_ADAPTER_PORT in .env."
+    },
+    {
+      "key": "provider-adapter-host",
+      "value": "http://127.0.0.1:9201",
+      "enabled": true,
+      "type": "default",
+      "description": "Where publish enters. Single mode: the same adapter as consumer-adapter-host. NETWORK_ADAPTER_PORT in .env."
+    },
+    {
+      "key": "network-adapter-host",
+      "value": "http://127.0.0.1:9201",
+      "enabled": true,
+      "type": "default",
+      "description": "Used only by the health check. Single mode: the same adapter; its network tier sits under /_internal/ and is not called from Postman. NETWORK_ADAPTER_PORT in .env."
+    },
+    {
+      "key": "discovery-host",
+      "value": "http://127.0.0.1:8090",
+      "enabled": true,
+      "type": "default",
+      "description": "The catalogue index. Reached through an adapter, not directly, so only its health check is here. DISCOVERY_PORT in .env."
+    },
+    {
+      "key": "registry-host",
+      "value": "http://127.0.0.1:8081",
+      "enabled": true,
+      "type": "default",
+      "description": "Participants and capability bindings, seeded by bin/setup.py. HOST ONLY: the API base is /api/v1, so a request spells it out. REGISTRY_PORT in .env."
+    },
+    {
+      "key": "keycloak-host",
+      "value": "http://127.0.0.1:8080",
+      "enabled": true,
+      "type": "default",
+      "description": "Issues the registry write token, and authenticates nothing else -- it is Sunbird RC's, not the network's. KEYCLOAK_PORT in .env."
+    },
+    {
+      "key": "keycloak-realm",
+      "value": "sunbird-rc",
+      "enabled": true,
+      "type": "default",
+      "description": "KEYCLOAK_REALM in .env."
+    },
+    {
+      "key": "keycloak-client-id",
+      "value": "registry-frontend",
+      "enabled": true,
+      "type": "default",
+      "description": "The client that logs a user in. admin-api is the one that mints tokens and is not used from here. KEYCLOAK_CLIENT_ID in .env."
+    },
+    {
+      "key": "registry-user",
+      "value": "no-user",
+      "enabled": true,
+      "type": "default",
+      "description": "REGISTRY_ADMIN_USER in .env. A shipped default, so it is public until changed."
+    },
+    {
+      "key": "registry-password",
+      "value": "no-user-password",
+      "enabled": true,
+      "type": "default",
+      "description": "REGISTRY_ADMIN_PASSWORD in .env. A shipped default, so it is public until changed."
+    },
+    {
+      "key": "consumer-participant-id",
+      "value": "consumer.oan.dev",
+      "enabled": true,
+      "type": "default",
+      "description": "The consumer adapter's network identity, and what its signatures verify against. CONSUMER_SUBSCRIBER_ID in .env."
+    },
+    {
+      "key": "consumer-base-url",
+      "value": "https://consumer.oan.dev",
+      "enabled": true,
+      "type": "default",
+      "description": "The address PEERS are told to POST to, published in the registry row. Nothing in this stack resolves it, so a wrong value costs nothing locally and everything on a shared network -- and the registry cannot correct it. CONSUMER_BASE_URL in .env."
+    },
+    {
+      "key": "consumer-participant-key",
+      "value": "",
+      "enabled": true,
+      "type": "default",
+      "description": "EMPTY ON PURPOSE. The public half lives in quick-start/keys/keys.json, which bin/setup.py generates; paste it in before registering. setup.py has already registered this participant, so it is normally not needed."
+    },
+    {
+      "key": "mausamgram-participant-id",
+      "value": "mausamgram",
+      "enabled": true,
+      "type": "default",
+      "description": "IMD Mausamgram, the weather upstream. Half of its binding key. MAUSAMGRAM_PARTICIPANT_ID in .env."
+    },
+    {
+      "key": "mausamgram-capability",
+      "value": "openagrinet:WeatherObservation",
+      "enabled": true,
+      "type": "default",
+      "description": "MAUSAMGRAM_CAPABILITY in .env."
+    },
+    {
+      "key": "mausamgram-binding-key",
+      "value": "mausamgram|openagrinet:WeatherObservation",
+      "enabled": true,
+      "type": "default",
+      "description": "<participant-id>|<capability>. Used to look up the binding's osid. The provider adapter builds this from the incoming payload, so it must match the registry row exactly -- a mismatch is a 404."
+    },
+    {
+      "key": "mausamgram-base-url",
+      "value": "https://mausamgram.imd.gov.in",
+      "enabled": true,
+      "type": "default",
+      "description": "MAUSAMGRAM_BASE_URL in .env."
+    },
+    {
+      "key": "mausamgram-path",
+      "value": "/nwpapi/get-daily",
+      "enabled": true,
+      "type": "default",
+      "description": "MAUSAMGRAM_PATH in .env."
+    },
+    {
+      "key": "mausamgram-mapping-url",
+      "value": "https://raw.githubusercontent.com/OpenAgriNet/helmcharts/0.0.1/quick-start/config/mappings/mausamgram/weather-observation.select.yaml",
+      "enabled": true,
+      "type": "default",
+      "description": "What the binding row publishes and the provider adapter fetches. A TAG ref, so what a running stack reads is fixed at 0.0.1 and a later push does not move it. MAUSAMGRAM_MAPPING_URL in .env."
+    },
+    {
+      "key": "capability-code",
+      "value": "openagrinet:WeatherObservation",
+      "enabled": true,
+      "type": "default",
+      "description": "WHICH CAPABILITY THE 4. Capability Schemas FOLDER OPERATES ON -- the one variable to change to work on another, because the schemaUrl and the display name are derived from it rather than written down. The four this deployment serves are openagrinet:WeatherObservation, openagrinet:MandiPrice, openagrinet:KnowledgeAdvisory and openagrinet:AgricultureFacility; network-specs carries four more packs no capability uses yet."
+    },
+    {
+      "key": "schema-pack-ref",
+      "value": "main",
+      "enabled": true,
+      "type": "default",
+      "description": "The ref in OpenAgriNet/network-specs that a derived schemaUrl points at. SCHEMA_PACK_REF in .env, which is what bin/setup.py seeds the rows from -- keep the two the same or a create here disagrees with a seeded row. MAIN IS A 404 FOR THESE PATHS TODAY; only schema-packs-v0.1 serves them. The registry checks the URL's shape and never fetches it, so a row stores either way, and main is the ref that becomes correct once the packs merge."
+    },
+    {
+      "key": "schema-pack-version",
+      "value": "v0.1",
+      "enabled": true,
+      "type": "default",
+      "description": "The pack version, and the row's version field. All eight packs are v0.1 today. Per capability in setup.py rather than one setting for all four, because a capability can move to v0.2 while the others stay -- so if you point capability-code at one that has, change this too."
+    }
+  ],
+  "_postman_variable_scope": "environment",
+  "_postman_exported_using": "hand-written, tracked in this repo"
+}

charts/adapter-service/CHANGELOG.md

@@ -5,6 +5,85 @@ All notable changes to this chart are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this chart adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-10-09
+
+### Added
+- **Two deployment modes, with single as the default.**
+  `deploymentMode: single-adapter | multi-adapter` (default `single-adapter`), read by
+  role `network-adapter` only. In single, role `network-adapter` is the Network Adapter Layer: the consumer, network and provider tiers as four
+  modules of one process (`/` for the consumer, `/publish`,
+  `/_internal/network/`, `/_internal/provider/`), one release called `network-adapter`. In multi,
+  `provider`, `network` and `consumer` run one release per tier, unchanged.
+- `config/single-adapter/network-adapter-config.yaml`: the layer's adapter config, mounted
+  like any role's file (an outbound connection pool and log level info on
+  every module). Each module is its tier's module, so a change to
+  a tier file that should apply to both deployment modes is made in both. Its routing
+  is generated at render time from `config/multi-adapter/routing-*.yaml`
+  (`routing-network-adapter-{consumer,provider}.yaml`), with tier hosts rewritten
+  to `http://localhost:<targetPort>/_internal/<tier>`, so tier hops stay inside the pod. The render fails if `http.port` differs from `service.targetPort`.
+- Three identities: each module signs as its own tier from
+  `adapterKeys.{consumer-adapter,network-adapter,provider-adapter}`, defaulting to
+  `consumer-adapter-keys`, `network-adapter-keys` and `provider-adapter-keys`
+  (`adapterKeys.extraSubstitutions` for extra placeholders). A literal
+  private key in the config, including a `config:` override, fails the render.
+- Flat paths: `/discover`, `/publish`, `/<action>` and `/health`, the
+  same URLs as the multi deployment mode. The network and provider tiers are mounted
+  under `/_internal/`, which only the process itself calls.
+- Ingress for the layer may expose only single-segment `/<action>`, as literal
+  paths with `pathType` Prefix or Exact and no `use-regex` / `rewrite-target`
+  annotation; `/`, `/publish` and `/_internal*` are refused. `routing.config` fails the render for this
+  role.
+- `examples/network-adapter.yaml` serves both modes: in single mode the chart adds
+  `adapterKeys.upstreamSecret` (default `provider-upstream`) to `envFrom`,
+  so only `--set deploymentMode` changes. `ci/network-adapter-values.yaml`
+  renders single mode in CI.
+- `deploymentMode` is set only in `values.yaml` (default `single-adapter`);
+  examples and CI values do not set it. `ci/lint-values.yaml` (role `network-adapter`)
+  therefore renders single mode.
+- `SETUP.md`: setup for both modes, including the openbao-secrets changes for multi.
+
+### Changed
+- **Breaking:** `role: network` now defaults to the single deployment mode.
+  An existing network-tier release must set `deploymentMode:
+  multi-adapter` (e.g. `--set deploymentMode=multi-adapter`), or the upgrade turns it into the
+  Network Adapter Layer. That pod then waits on the consumer and provider key
+  Secrets, which a multi environment does not mirror into `network-adapter`.
+- Docs, `values.yaml` and the example headers say single is the default
+  deployment mode and multi is optional.
+- Naming: in single mode the release, Service, app name and namespace are
+  `network-adapter`, the same as the multi network tier's (telemetry service
+  `oan-network-adapter`, set in `config/single-adapter/network-adapter-config.yaml`).
+  Switching modes upgrades that release in place.
+
+### Fixed
+- Liveness and readiness probes now render. Values used `probes.liveness` /
+  `probes.readiness`, which `common.probes` never read, so no adapter pod had a
+  readiness probe. Upgrading rolls every adapter pod once.
+- The startup probe bounds first boot at 180s (`periodSeconds: 5` x
+  `failureThreshold: 36`) and holds off liveness until `/health` answers.
+  Pods that had no probe before now get a liveness probe, and the adapter
+  fetches `beckn.yaml` at boot, so without this a slow or proxied egress
+  would get a cold start killed after about 70s.
+- NOTES.txt in single mode no longer prints `registry.url` and
+  `otel.*`: that role mounts `config/single-adapter/network-adapter-config.yaml` as is, so those
+  values never reached the pod and NOTES reported the opposite of what it ran.
+  The example and CI values no longer set them.
+- The Ingress annotations merge tolerates `ingress.annotations: null`.
+  `ci/network-adapter-values.yaml` turns the Ingress on, so CI renders the path guard.
+
+### Removed
+- **Breaking:** the `probes.liveness` and `probes.readiness` values keys, renamed to
+  `livenessProbe` / `readinessProbe`, plus a new `startupProbe`, on by
+  default. The liveness and readiness timings are unchanged. An environment
+  that overrides `probes.*` must rename those keys; the old keys never took
+  effect and are now silently ignored, which is why this is a minor bump
+  rather than a patch.
+
+### Unchanged
+- Roles `provider`, `network`, `consumer`: same config, routing and manifests
+  apart from the probes (the chart version label and the config checksum
+  annotation also change with the version).
+
 ## [0.5.2] - 2026-09-29
 
 ### Changed