[kelvinprabhu]

Closes #55
Closes #66
Refs OpenAgriNet/network-adapter#55
Parent: OpenAgriNet/engineering-tracker#171

Objective

Run the consumer, network and provider tiers as one adapter process, the Network Adapter, and make it the default (single). The three-adapter setup stays as the optional multi mode, unchanged. Available in both quick-start (Docker Compose) and Helm (charts/adapter-service). Decision record: docs/adr/0001-single-network-adapter-deployment-mode.md.

Existing vs proposed

Existing (only the multi-adapter architecture): three containers or pods, a network hop and a DNS lookup between tiers, three of every Kubernetes object.

flowchart LR
  app[App] --> C[consumer-adapter :9202]
  C -- discover --> N[network-adapter :9201] --> D[(discovery)]
  C -- select --> P[provider-adapter :9200] --> U[(upstream APIs)]
  P -- publish --> N

Loading

Proposed (single as the default, the separate adapters kept as the optional multi): one container or pod on :9201 (the multi network tier's port), tier hops on localhost:9201 inside it. One Deployment, Service, PDB and ConfigMap.

flowchart LR
  app[App] --> C
  subgraph NA["network-adapter :9201 (one service)"]
    C["consumer  /:action"]
    N["network  /_internal/network/*"]
    P["provider  /_internal/provider/*"]
    PP["provider-publish  /publish"]
    C -- discover --> N
    C -- select --> P
    PP -- publish --> N
  end
  N --> D[(discovery)]
  P --> U[(upstream APIs)]
  cat[Catalogue publisher] --> PP

Loading

Each module keeps its own tier identity (keys, keyId, registry row), so nothing changes in the registry. The paths are flat and the same as multi: /discover, /publish, /<action>, /health; only host and port change. The network and provider tiers sit under /_internal/, which only the process itself calls; /publish and /_internal are never exposed (Helm Ingress guard, quick-start server_proxy.conf deny).

Choosing the mode

	single (default)	multi (optional)
Quick-start	make up-core / make up	make up-core-multi / make up-multi
Compose profile	network	multi
Helm	release network-adapter, namespace network-adapter-layer, -f examples/network-adapter.yaml	releases consumer-, network-, provider-adapter, one namespace each
Helmfile value	networkAdapterDeploymentMode: single	networkAdapterDeploymentMode: multi
Ports	:9201	9200 provider, 9201 network, 9202 consumer

Switching in quick-start is running the other target; it removes the running mode's adapters first. In Helm, install the other mode next to the current one, repoint the app, then remove the old releases.

File structure

charts/
├── adapter-service/
│   ├── config/network-adapter-config.yaml   + one config, four modules (each its tier's module)
│   ├── templates/_network-adapter.tpl       + routing generated, tier hosts -> localhost:<port>/_internal/<tier>
│   ├── templates/{_helpers,configmap,deployment,ingress}   ~ role network-adapter-layer; Ingress path guard; 5 unused helpers removed
│   ├── templates/NOTES.txt                  ~ mode and full address
│   ├── examples/network-adapter.yaml        + install once
│   ├── ci/network-adapter-values.yaml       + CI lint: generated routing, Ingress guard, PDB, spread
│   ├── values.yaml                          ~ networkAdapterLayer.keys.*, probe keys fixed, startupProbe on
│   └── README.md, CHANGELOG.md, Chart.yaml  ~ 0.6.0 (breaking: probe keys)
└── openbao-secrets/values.yaml              ~ reflect keys into network-adapter-layer (0.1.1)

quick-start/
├── docker-compose.yml                       ~ service network-adapter-layer (profile network); the three tiers -> profile multi
├── config/adapters/
│   ├── network-adapter.yaml.tmpl            + single-mode config
│   └── routing-network-adapter-{consumer,provider}.yaml   +
├── config/reverse-proxy/npm-custom/server_proxy.conf     ~ deny /publish and /_internal on every host
├── bin/stack.sh, Makefile                   ~ MODE=single|multi, up-multi, restart follows the running mode
├── bin/setup.py                             ~ renders network-adapter.yaml too
├── bin/bootstrap-ubuntu.sh                  ~ clones development
├── .env.example                             ~ COMPOSE_PROFILES=network; registry baseUrl note for single mode
└── README.md                                ~ install steps for both modes, "Two modes" section

docs/adr/                                    + ADR log, template, ADR-0001
api-collection/OpenAgriNet.network-adapter.local-environment.json  + single-mode environment (same collection)

+ new, ~ changed.

How documentation is done

Doc	Covers
docs/adr/0001-…	why single by default: context, decision, alternatives rejected, consequences
quick-start/README.md	install steps for both modes; "Two modes": when to use which, how to switch, single-mode wiring
charts/adapter-service/README.md	"Choosing a deployment mode", install commands, helmfile snippet
charts/adapter-service/CHANGELOG.md, openbao-secrets/CHANGELOG.md	chart changes, 0.6.0 and 0.1.1
NOTES.txt, values.yaml header, examples/network-adapter.yaml header	mode and address shown at install time

Not in this PR (forward looking)

• In-process transport instead of HTTP on localhost between modules (prototyped on network-adapter feat/55). Measure first: the localhost hop was already sub-millisecond on Docker.

[kelvinprabhu]

Please confirm: Module Paths and Naming

Can we finalize the following module paths and naming conventions for the single network layer adapter so the Helm chart, quick-start, and documentation remain consistent?

1. Module paths — one process, one listener on :9200

Module | Path | Exposure -- | -- | -- Consumer | / | Public, unsigned Network | /network/ | Internal, never exposed Provider | /provider/ | Approved signed actions only Provider publish | /provider/publish | Internal, never exposed

Request flow

App -> /discover -> Consumer -> /network
App -> /select   -> Consumer -> /provider
Publisher        -> /provider/publish -> /network/publish

Keeping the consumer at / preserves compatibility with the existing consumer-adapter URLs. Ingress allows only /<action> and approved /provider/<action> routes, blocking /, /network*, /provider and /provider/publish*.

2. Naming conventions

• Name: single-network-layer

• Helm role: single-network-layer

• Helm values: singleNetworkLayer.*

• Release/namespace: single-network-layer-adapter

• Config: config/single-network-layer-config.yaml

• Routing: routing-single-network-layer-{consumer,publish}.yaml

• Quick-start: docker-compose.single-network-layer.yml

• Make targets: up-single-network-layer, down-single-network-layer

Are we aligned on these paths and naming conventions? If there are no objections, I'll retain them and remove outdated unified and network-layer references from the documentation where they refer to this deployment mode, while preserving references to the actual network module.

@manjudr @ameersohel45

[manjudr]

Re-reviewed at edc8654. I rendered and diffed rather than only reading: scripts/lint-charts.sh is green, helm template with ci/network-adapter-values.yaml produces the four modules with the right generated routing, all 19 placeholders substitute, docker compose config -q passes on both the network and multi profiles, and the three existing roles render identically to merge-base apart from the chart version, the config checksum and the new probes.

Every one of the 16 code comments is addressed.

Comment	Where it landed
Autoscaling off by default / does it work	enabled: false in both the example and CI values, with a note that it needs metrics-server
/network/, /provider/ off the public tree	now /_internal/network/, /_internal/provider/ in the chart config and the quick-start template
/provider/publish to top level	/publish, matching multi mode
Say in-file that consumer-at-/ is load-bearing	network-adapter-config.yaml:72-76
Inert values	dropped from the example and CI values, with a pointer to the config file
Five dead helpers	deleted; zero include sites remain
Patch bump hides a breaking change	0.5.2 → 0.6.0
Liveness with no startup probe	startupProbe on, failureThreshold: 36 → a 180s first-boot budget
merge guard, ingress never rendered in CI	`
Both .gitignores	root one out of the diff, quick-start down to one real line
SETUP.md stale branch and Compose version	file removed; README.md:65 states Compose v2.20+, README.md:72 clones development
Why both openbao namespaces	answered at values.yaml:60-67
What is smoke	removed; no references left
Flat path scheme	public surface is /<action>, /publish, /health; server_proxy.conf uncomments the /publish deny and adds location ^~ /_internal { deny all; }; the registry baseUrl decision is recorded at .env.example:151-158

I also checked the invariant this config sets for itself — that each module is its tier's module — by parsing both files and diffing module by module. Three of the four are exact apart from the per-tier key placeholders, the router filename and httpClientConfig. The fourth has one gap; inline comment below.

Still to do before this merges:

1. Commit hygiene. All ten commits since 14 Oct carry a ticket number. The 24 before it do not (b42f82d Refactor code structure for improved readability and maintainability, 40a273b chore: add /dev_docs to .gitignore, and others). Unless this is squash-merged they land on development as-is. Squash-merge is fine by me — say which you prefer.
2. The flat-path caveat is in the wrong place. It is written up at charts/adapter-service/README.md:31-37, and the content is right. I asked for it in the PR description, which still lists only the in-process-transport item under "Not in this PR".
3. The description says Closes #55 only. Commits also say Fixes #65 and Fixes #66, so merging closes two issues the description does not name. List all three.
4. api-collection/OpenAgriNet.network-adapter.local-environment.json is a second environment file beside the existing OpenAgriNet.local-environment.json, though ba54a2d is titled "one Postman collection for both modes". Fold it in or say why it has to stay separate.
5. quick-start/bin/bootstrap-ubuntu.sh:113 still clones -b feat/4-docker-compose — the same bug fixed in SETUP.md and the README. Pre-existing on development and out of this PR's scope, but it is the surviving copy and worth picking up here.
6. Nothing on any thread. Eight are still unresolved even though the code is fixed, so the PR reads as unaddressed at a glance. Reply and resolve as you go.

Two notes, neither blocking: both network-adapter config files end without a trailing newline, and preStopSleepSeconds: 10 in the CI values needs Kubernetes 1.30 or later — the example values say so, but nothing fails the render on an older cluster.

[ameersohel45]

Three identities in single mode
The one container still signs as three participants (consumer, network, provider), with three keys, three keyIds and three registry rows. setup.py fills in all three tiers' keys for network-adapter.yaml. That clashes with #82's one entry and one key, and both PRs rewrite the same render loop in setup.py, so they will conflict.

[ameersohel45]

Single and multi consumer validate differently
quick-start/config/adapters/network-adapter.yaml.tmpl:124 turns extendedSchema_enabled on for the consumer module, but the multi consumer.yaml.tmpl:95 keeps it off on purpose (it fetches each resource's @context per request). So the same request is validated differently depending on the mode. Should this be "false" to match multi?

[ameersohel45]

1. Three Secrets → one
The pod mounts three tier Secrets, and openbao-secrets copies all three into the new namespace. With #82's single network identity, this should be one Secret.

[ameersohel45]

2. Namespace name
Let's use network-adapter instead of network-adapter-layer; the release, Service and container already use that name. With one Secret, there's no reason to keep a separate namespace.

[ameersohel45]

3. No real single/multi knob
networkAdapterDeploymentMode exists only as a sample helmfile in the README, and nothing reads it. Can we make it an actual setting?

[ameersohel45]

4. Separate folders per mode, no generated routing
Let's keep the config and routing files for each mode in their own folder, for example config/single/ and config/multi/. Single mode would then have its own routing files written by hand, not generated from the multi ones at render time. They can drift, so whenever one mode changes, the other needs a matching update in the same PR.

[ameersohel45]

5. Probe keys
Renaming probes: to livenessProbe and the others turns health checks on for every role, and breaks any values file that still uses probes:. Please note this in the CHANGELOG as a breaking change for multi releases.

[ameersohel45]

6. CI values duplicate the example
ci/network-adapter-values.yaml is nearly a copy of examples/network-adapter.yaml. Could CI use the example directly?

[ameersohel45]

7. Retest
The ADR says the k3d run happened before the final paths and port 9201. Please rerun it before merging.

[kelvinprabhu]

1. Three Secrets → one The pod mounts three tier Secrets, and openbao-secrets copies all three into the new namespace. With #82's single network identity, this should be one Secret.

Agreed on the direction. #82 is quick-start only and targets NetworkofNetwork, so on development the chart still has three tier identities. Once #82 lands, the quick-start single adapter picks up the one identity with no template change; only the setup.py render loop needs a small merge. For the chart, I'd collapse networkAdapterLayer.keys and the openbao copies to one Secret in a follow-up, when #82's single identity reaches development, so single and multi stay consistent.

[kelvinprabhu]

6. CI values duplicate the example ci/network-adapter-values.yaml is nearly a copy of examples/network-adapter.yaml. Could CI use the example directly?

the CI file turns on ingress with annotations: null to test the path guard