feat(deploy): add environment-agent compose profile and Kind

[jenniferubah]

Summary

• Add environment-agent compose profile (shared NATS, in-process embedded SPs, kubeconfig mount)
• Wire Makefile targets to utilities scripts: kind-connect, kubeconfig-for-compose, install-kubevirt, compose network teardown
• Add deploy/docs/environment-agent-kind.md and streamline RUN.md to point at it
• Document agent, cluster, and storage env vars in deploy/.env.example

Type of Change

• New feature (deployment)

Stacked PR Status

• Yes, this is part of a stack:
  • Parent PR: #48 (Base PR - Open for review)

Assisted-By: Cursor AI

[qodo-code-review]

PR Summary by Qodo

Add environment-agent Compose profile and Kind development flow

✨ Enhancement ⚙️ Configuration changes 📝 Documentation 🕐 20-40 Minutes

AI Description

• Replaces standalone provider containers with an environment-agent profile hosting embedded service
 providers.
• Adds Kind networking, kubeconfig, KubeVirt, and deterministic Compose teardown targets.
• Documents the complete local environment-agent setup and configuration.

Diagram

graph TD
  DEV["Developer"] --> MAKE["Make targets"] --> UTIL["Utilities scripts"] --> KIND["Kind cluster"]
  MAKE --> COMPOSE["Compose stack"] --> AGENT["Environment agent"] --> CP["Control plane"]
  AGENT --> NATS["Shared NATS"]
  AGENT --> KIND

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Retain standalone provider profiles

• ➕ Preserves per-provider isolation and independent image upgrades.
• ➕ Avoids migrating existing Compose profile workflows immediately.
• ➖ Maintains duplicated registration, messaging, and kubeconfig configuration.
• ➖ Does not align local deployment with the consolidated environment-agent architecture.

2. Vendor local helper scripts

• ➕ Makes the development workflow self-contained and easier to reproduce.
• ➕ Avoids requiring a sibling utilities checkout.
• ➖ Duplicates shared Kind and network teardown logic.
• ➖ Requires synchronization across repositories when runtime behavior changes.

Recommendation: The consolidated environment-agent profile is the appropriate direction because it matches the new agent architecture and substantially simplifies provider wiring. Reusing utilities scripts also avoids duplication, though their expected version or compatible commit should remain explicit because the workflow depends on a sibling repository.

Files changed (7) +297 / -315

Enhancement (1) +26 / -110

compose.yamlReplace standalone providers with environment-agent profile +26/-110

Replace standalone providers with environment-agent profile

• Removes individual provider and three-tier services in favor of an optional environment-agent service using shared NATS and control-plane registration. Mounts kubeconfig, persists provider registrations, exposes the agent API, and forwards embedded provider settings.

deploy/compose.yaml

Documentation (3) +212 / -140

README.mdAdvertise the environment-agent deployment profile +2/-2

Advertise the environment-agent deployment profile

• Updates the deployment overview and local usage link to identify the environment-agent as the preferred service-provider integration.

README.md

RUN.mdRefocus local deployment guidance on environment-agent +39/-138

Refocus local deployment guidance on environment-agent

• Replaces detailed standalone provider instructions with the environment-agent workflow and dedicated Kind guide. Expands configuration and authentication notes for the agent and its embedded providers.

deploy/RUN.md

environment-agent-kind.mdDocument the environment-agent Kind development workflow +171/-0

Document the environment-agent Kind development workflow

• Adds an end-to-end guide covering Kind creation, KubeVirt installation, kubeconfig rewriting, Compose networking, agent configuration, verification, and teardown. It also explains helper targets and why cross-network Kind access is required.

deploy/docs/environment-agent-kind.md

Other (3) +59 / -65

.gitignoreIgnore generated deployment kubeconfig files +1/-0

Ignore generated deployment kubeconfig files

• Excludes 'deploy/.kube/' artifacts created by the Compose kubeconfig helper from version control.

.gitignore

MakefileAdd environment-agent and Kind orchestration targets +40/-33

Add environment-agent and Kind orchestration targets

• Adds targets for starting the environment-agent profile, installing KubeVirt, preparing kubeconfig, and connecting or disconnecting Kind. Delegates Compose network cleanup to shared utilities scripts and integrates it into teardown.

Makefile

.env.exampleDefine environment-agent and embedded provider settings +18/-32

Define environment-agent and embedded provider settings

• Replaces standalone provider examples with agent identity, kubeconfig, namespace, cluster, and storage settings. Documents the environment-agent image version override and correct 'deploy/.env' location.

deploy/.env.example

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Authenticated stacks can fail to start ✓ Resolved 🐞 Bug ☼ Reliability

Description

The control-plane no longer waits for the Keycloak health check before starting, although
NewOIDCValidator performs OIDC discovery synchronously and exits the process when discovery fails.
When authentication is enabled, PostgreSQL and NATS can satisfy the remaining dependencies before
Keycloak becomes ready, causing the control-plane to terminate during startup.

Code

deploy/compose.yaml[L92-93]

-      keycloak:
-        condition: service_healthy

Evidence

Keycloak can take up to its configured startup and health-check period to become ready, while the
changed control-plane dependency list now waits only for PostgreSQL and NATS. Authentication
initialization performs OIDC discovery immediately and returns from the application with an error if
that request fails.

deploy/compose.yaml[36-41]
deploy/compose.yaml[87-91]
internal/app/run.go[238-243]
internal/auth/jwt.go[32-38]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR removes the control-plane dependency on a healthy Keycloak service. Authentication initialization immediately performs OIDC discovery and terminates the control-plane if Keycloak is not yet ready.

## Issue Context
The Keycloak container has a readiness health check, and the previous Compose configuration waited for it. Restore that ordering while preserving the new environment-agent profile.

## Fix Focus Areas
- deploy/compose.yaml[87-91]
- internal/app/run.go[238-243]
- internal/auth/jwt.go[32-38]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Legacy provider setup stops working ✓ Resolved 🐞 Bug ≡ Correctness

Description

The PR removes compose-up-with-providers and every legacy provider service while retaining a phony
declaration and guides that still invoke those targets and profiles. Running the documented Make
command now succeeds without starting anything, while direct k8s-container and three-tier
profile commands cannot start the providers described by the retained documentation.

Code

Makefile[L57-58]

-compose-up-with-providers:
-	$(COMPOSE) -f $(COMPOSE_FILE) --profile $(PROFILES) up -d --build

Evidence

The current Makefile defines only the base and environment-agent startup recipes but still declares
the removed provider target phony. Retained guides invoke that target or profiles which no longer
exist, and the newly changed README still advertises legacy external-provider profiles.

Makefile[57-63]
Makefile[120-123]
deploy/compose.yaml[105-107]
deploy/docs/k8s-container-sp-kind.md[17-23]
deploy/docs/three-tier-app-kind.md[40-57]
README.md[77-82]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Legacy provider services and their Make recipe were removed, but the repository still advertises and invokes those workflows. Because the removed target remains phony, affected commands can even report success while doing nothing.

## Issue Context
Either restore the legacy services and target if backward compatibility is intended, or remove/update every legacy guide, variable, target declaration, and README claim to direct users to the environment-agent replacement.

## Fix Focus Areas
- Makefile[57-63]
- Makefile[120-123]
- deploy/compose.yaml[105-137]
- deploy/docs/k8s-container-sp-kind.md[17-69]
- deploy/docs/three-tier-app-kind.md[40-57]
- README.md[77-82]
- deploy/RUN.md[173-196]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Default agent starts without providers ✓ Resolved 🐞 Bug ≡ Correctness

Description

The environment-agent service expands an unset AGENT_EMBEDDED_SPS to an empty string even though
both new configuration tables declare container,vm as the default. When the profile is started
without an explicit override, the agent has no embedded service providers, so the documented
provider verification and workload flow are unavailable.

Code

deploy/compose.yaml[116]

+      AGENT_EMBEDDED_SPS: ${AGENT_EMBEDDED_SPS:-}

Evidence

Compose explicitly passes an empty value when the variable is unset, whereas both deployment
configuration tables list container,vm as its default. The Kind guide separately requires users to
set the value manually, demonstrating that the documented default is not implemented.

deploy/compose.yaml[110-120]
deploy/RUN.md[157-162]
deploy/docs/environment-agent-kind.md[74-86]
deploy/docs/environment-agent-kind.md[139-150]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Compose supplies an empty embedded-provider list while the deployment documentation declares `container,vm` as the default. Align runtime behavior and documentation so users receive the documented providers or are clearly required to configure them.

## Issue Context
If enabling providers by default is unsafe without a prepared cluster, document the empty default consistently and make the configuration step explicit. Otherwise, change the Compose fallback to the documented provider list.

## Fix Focus Areas
- deploy/compose.yaml[116-126]
- deploy/RUN.md[157-162]
- deploy/docs/environment-agent-kind.md[139-150]
- deploy/.env.example[18-23]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 16/18, lines 612/200; both must reach the floor). Router rationale: This deployment feature changes Compose service wiring, Makefile orchestration, Kind networking, kubeconfig handling, environment propagation, and teardown across multiple independent paths, creating a dense set of easy-to-miss integration defects.

Tip of the day

💡 Did you know, you can commit Qodo's fix in one click with committable suggestions (GitHub & GitLab)

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[gabriel-farache]

I had to use the container for the agent based on dcm-project/environment-agent#30 for everything to work (specifically https://github.com/dcm-project/environment-agent/pull/30/changes#diff-5fcdf9b4580789697d834d1456a22bcfaa236d668fc180cad4775afc36ed5914R23)

$ curl http://localhost:8080/api/v1alpha1/health
curl http://localhost:8080/api/v1alpha1/agents
curl http://localhost:8081/api/v1alpha1/health
curl http://localhost:8081/api/v1alpha1/providers
{"status":"ok","path":"/api/v1alpha1/health","checks":{"database":"ok","nats":"ok"}}
{"agents":[{"agent_id":"d05d0e75-7f30-48d7-b68a-31b4b2ca7510","cost":"low","create_time":"2026-09-09T14:03:14.47179Z","environment":"dev","health_status":"ready","last_heartbeat":"2026-09-09T14:05:44.475635Z","name":"local-agent","service_types":["container","vm"],"topic_name":"dcm.agent.local-agent","update_time":"2026-09-09T14:05:44.477355Z"}]}
{"path":"health","status":"healthy"}
{"results":[{"create_time":"2026-09-09T14:03:14.4490276Z","endpoint":"embedded://container","id":"307514ec-9d68-4a3d-ba93-7a594ea39d99","last_check_time":"2026-09-09T14:06:04.482467433Z","name":"container","path":"providers/307514ec-9d68-4a3d-ba93-7a594ea39d99","schema_version":"v1alpha1","service_type":"container","status":"Ready","type":"embedded","update_time":"2026-09-09T14:03:14.4490276Z"},{"create_time":"2026-09-09T14:03:14.46313531Z","endpoint":"embedded://vm","id":"6f6294d0-8707-40e1-86ee-942ffc3c81d7","last_check_time":"2026-09-09T14:06:04.482255648Z","name":"vm","path":"providers/6f6294d0-8707-40e1-86ee-942ffc3c81d7","schema_version":"v1alpha1","service_type":"vm","status":"Ready","type":"embedded","update_time":"2026-09-09T14:03:14.46313531Z"}]}

[gciavarrini]

Compose no longer documents the Pet Clinic / three-tier demo after removing the standalone provider profiles. Worth a one-line note in the PR summary so reviewers know it is intentional.

[gciavarrini]

PROFILES is unused after dropping compose-up-with-providers. I think you can remove this

[gciavarrini]

duplicated

[gciavarrini]

compose only picks these up from deploy/.env (step 3 already created it).

If someone runs this in a shell, the agent still starts with empty AGENT_EMBEDDED_SPS.

[gciavarrini]

Gabriel could not get embedded container working with the pulled :main image.
He built the agent locally from environment-agent PR #30 instead, not sure if it's worthing adding the workarounds (set ENVIRONMENT_AGENT_VERSION in deploy/.env to a known-good tag, or build the agent image locally and point ENVIRONMENT_AGENT_VERSION at that tag).

[gabriel-farache]

I think it's not worth it, once the other PR is merged there will be no issue out of the box and if someone wants to test a specific version, they will know to update the tag to point to the locally built image