Skip to content

Capability Provider Deploy Integration

Standalone egress providers (for example Positionstack and Weatherstack) extend MeshFlows without orchestrator code changes. This document covers deploy wiring and automated enforcement.

For registry payload shape and designer metadata, see Capability provider contract.

Principles

  1. Registry-first discovery — the service registers capabilities with capability-registry at startup (register + heartbeat).
  2. Workflow service_call only — workflows reference capability_name, path, and optional connection.
  3. Connection types from capabilities — each provider publishes a workflow_connection capability (for example positionstack.connection) with designer metadata; orchestrator resolves connection schemas from the registry.
  4. No orchestrator URL env vars — unlike egress-google-workspace, providers must not require EGRESS_*_URL on orchestrator. Discovery goes through the registry.
  5. Minimal dependencies — FastAPI + httpx + pydantic only; no imports from orchestrator or other engine services.

Adding a New Provider

Use engine/deploy/engine-images-manifest.yaml as the single integration checklist. New providers must include:

- build_name: egress-example
  image_name: egress-example
  deployment: egress-example
  container: egress-example
  health_service_name: example.service
  capability_provider: true
  service_path: example          # engine/services/example/
  connection_type: example       # flows/connections/example.yaml

Then add the usual deploy surface (k8s deployment/service, kustomize overlays, deploy.yml DEPLOYMENTS, minikube build list, wiki microservice page).

Automated enforcement

engine/tests/test_capability_provider_architecture.py validates every manifest entry with capability_provider: true against:

  • service code + connection YAML + wiki page exist
  • Kubernetes deployment/service manifests and kustomize wiring
  • cluster-health and dashboard RBAC entries
  • deploy.yml and deploy-minikube.ps1 include the deployment
  • orchestrator deployment does not hardcode the provider URL

Run locally:

cd engine
python -m pytest tests/test_capability_provider_architecture.py -q

When Not to Use This Pattern

Use a legacy coupled egress (orchestrator env URL) only when the orchestrator must call the service through a fixed, non-registry code path — for example egress-google-workspace today.

For new integrations, prefer capability providers so deploy and documentation stay manifest-driven.