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 a minimal provider in Python, Go, or C#, see Add a Capability Provider. For registry payload shape and designer metadata, see Capability provider contract.
Principles¶
- Registry-first discovery — the service registers capabilities with
capability-registryat startup (register + heartbeat). - Workflow
service_callonly — workflows referencecapability_name,path, and optionalconnection. - Connection types from capabilities — providers that need credentials publish a workflow_connection capability (for example positionstack.connection) with designer metadata; orchestrator resolves connection schemas from the registry. Step-only demos (echo C# / Go) skip this and omit connection_type in the manifest.
- No orchestrator URL env vars — providers must not require EGRESS_URL on orchestrator. Discovery goes through CAPABILITY_REGISTRY_URL. Google Workspace uses the same registry/service_call path; leftover EGRESS keys in old manifests are unused by orchestrator Python.
- 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 # optional; required only with a workflow_connection + flows/connections/example.yaml
Then add the usual deploy surface (k8s deployment/service, kustomize overlays, deploy.yml DEPLOYMENTS, minikube build list, wiki microservice page).
Cluster Health visibility¶
Registered providers show up on Dashboard → Cluster Health automatically (discovery via capability-registry).
For external / third-party providers that do not share MeshFlows build tags:
- Prefer service registration metadata
metadata.cluster_health.check_version: falseso Match showsskipand healthz/readyz still matter. - Only set
required: true(or list the name in dashboardCLUSTER_HEALTH_REQUIRED_SERVICES) if a down provider should fail overall cluster health.
If the provider cannot register (or you want a static probe target), configure the dashboard:
CLUSTER_HEALTH_EXTRA_SERVICES_JSON='[{"name":"acme.provider","url":"http://acme:8080","check_version":false}]'
Version pin matching uses Kubernetes image tags only for services in the dashboard CLUSTER_HEALTH_DEPLOYMENT_MAP. Without that entry, expected version is fallback/empty — check_version: false is the usual choice for externals.
See Dashboard — Cluster Health.
Automated enforcement¶
engine/tests/test_capability_provider_architecture.py validates every manifest entry with capability_provider: true against:
- service code + wiki page exist; connection YAML only when
connection_typeis set - Kubernetes deployment/service manifests and kustomize wiring
- cluster-health and dashboard RBAC entries
deploy.ymlanddeploy-minikube.ps1include 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¶
Do not add new orchestrator-hardcoded egress URL paths. All new integrations are capability providers with register + heartbeat.
Platform-owned control steps (if, context_set, parallel, …) stay in the orchestrator; everything else is service_call.