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 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

  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 — 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.
  4. 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.
  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       # 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: false so Match shows skip and healthz/readyz still matter.
  • Only set required: true (or list the name in dashboard CLUSTER_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_type is set
  • 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

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.