Skip to content

Connections Reference

Connections are reusable endpoint and credential definitions. The MeshFlows Orchestrator uses these definitions to handle low-level protocol details, authentication, and connection pooling.

Connection Schema by Type

http

Used for API integrations. Supports standard HTTP/HTTPS and OAuth 2.0.

  • base_url: Prefix for step URLs.
  • default_headers: (Optional) Map of headers added to every request.
  • oauth: (Optional) OAuthClientCredentials object for automatic token management.
  • token_url: The OAuth 2.0 token endpoint.
  • client_id: Client identifier.
  • client_secret: Client secret.
  • scope: Space-separated string of requested scopes.

Bearer Caching: When OAuth is configured, the orchestrator automatically caches the bearer token and refreshes it 30 seconds before expiry.

ssh

Remote command execution via the SSH egress (egress.ssh.exec, …).

  • host: Target hostname or IP.
  • port: Default is 22.
  • username: Login user.
  • password: (Optional) Login password.
  • private_key_pem: (Optional) SSH private key in PEM format.

Example in repo: flows/connections/example_secret_ssh.yaml (type: ssh).

sftp

File transfer over SSH/SFTP (sftp.list / download / upload, or egress.ssh.sftp). Same host/auth fields as SSH, but type: sftp — not interchangeable with ssh for capability connection_type matching.

Example: flows/connections/sftp_demo.yaml.

ftp

Legacy FTP/FTPS transfers (egress.ftp / FTP capability).

  • protocol: e.g. ftps
  • host, port (default 21), username, password

Example: flows/connections/example_secret_ftp.yaml (type: ftp).

s3

Object storage (AWS S3-compatible, including in-cluster MinIO).

  • endpoint: Service URL (e.g. http://orchestrator-minio:9000)
  • region: e.g. us-east-1
  • secure: TLS to endpoint (true/false)
  • default_bucket: Default bucket name
  • Optional access_key / secret_key via $secret: (omitted for pod-default MinIO demos)

Examples: flows/connections/s3.yaml, flows/connections/minio_demo.yaml (type: s3).

postgres

PostgreSQL for SQL capability providers.

  • host, port (default 5432), database, username, password
  • sslmode: e.g. prefer

Example: flows/connections/postgres.yaml.

joke-api

Official Joke API provider connection (type: joke-api). No base URL credentials in the demo file — reference as connection: joke-api on egress.joke-api.* steps.

Example: flows/connections/joke-api.yaml.

rabbitmq

Configuration for AMQP 0.9.1 integration.

  • url: Full AMQP connection URL (e.g., amqp://user:pass@host:5672/vhost).
  • exchange: Default exchange for publishing (default: meshflows.events).
  • exchange_type: topic, direct, fanout, or headers.

imap

Used for reading e-mails from an IMAP mailbox.

  • host: IMAP server hostname (e.g. imap.gmail.com).
  • port: Default is 993.
  • username: Mailbox username/e-mail address.
  • password: Mailbox password or app-specific token.
  • use_ssl: (Optional) Default is true.

Gmail-specific requirements: - Use host: imap.gmail.com and port: 993 with use_ssl: true. - Enable IMAP in Gmail settings for the mailbox. - Enable Google 2-Step Verification and use an App Password. - Do not use the regular Google account password for IMAP; it is rejected. - Store the App Password as a secret and reference it as $secret:<name> in the connection.

smtp

Used for sending e-mails via an SMTP server.

  • host: SMTP server hostname (e.g. smtp.gmail.com).
  • port: Default is 587.
  • username: SMTP username.
  • password: SMTP password.
  • use_tls: (Optional) Use STARTTLS (port 587 default). Default is true.
  • use_ssl: (Optional) Use Implicit SSL (port 465 default). Default is false.
  • default_from: (Optional) Default "From" address if not specified in the step.

google_workspace

Used for Gmail, Calendar, and Drive connector steps through the dedicated egress-google-workspace microservice.

  • service_account_key: Full Google service-account JSON string (recommended via $secret: reference).
  • impersonate_user: (Optional) User e-mail for domain-wide delegation (sub claim).
  • scopes: OAuth scopes granted for this connection.

Authentication model:

  1. Orchestrator resolves connection + secrets.
  2. Orchestrator calls egress-google-workspace with connection auth payload.
  3. Egress service signs JWT with service-account private key.
  4. Egress service exchanges JWT for Google access token.
  5. Token is cached and reused until expiry.

Recommended setup:

  • Store service-account JSON in runtime secrets ($secret:google-workspace-sa-key).
  • Keep scopes least-privilege per connection (calendar only, drive only, etc.).
  • Enable domain-wide delegation only when required.
  • Never commit raw private keys to Git.

positionstack

Geocoding via the egress-positionstack capability provider (registry discovery, no orchestrator URL env).

  • access_key: Positionstack API access key (use $secret: reference).
name: positionstack
type: positionstack
access_key: "$secret:positionstack-access-key"

Workflow steps use service_call with capabilities such as egress.positionstack.forward or egress.positionstack.reverse. See Egress Positionstack.

weatherstack

Weather data via the egress-weatherstack capability provider (registry discovery, no orchestrator URL env).

  • access_key: Weatherstack API access key (use $secret: reference).
name: weatherstack
type: weatherstack
access_key: "$secret:weatherstack-access-key"

Workflow steps use service_call with capabilities such as egress.weatherstack.current, egress.weatherstack.historical, or egress.weatherstack.forecast. See Egress Weatherstack.

azure-servicebus

Azure Service Bus topics + subscriptions via egress-azure-servicebus.

  • auth: connection_string (default) or workload_identity (ADR 0012)
  • connection_string: SAS string (use $secret:). Required when auth is connection_string.
  • fully_qualified_namespace: myns.servicebus.windows.net. Required when auth is workload_identity.
  • client_id: optional user-assigned MI client id (otherwise the pod AZURE_CLIENT_ID)
  • Optional defaults: topic, subscription

Example: flows/connections/azure-servicebus.yaml. Cluster federation example: engine/deploy/k8s/azure-workload-identity.example.yaml.

Custom types from capability providers

New connection type values come from a provider’s workflow_connection registration (metadata.designer.connection_type), not from a hard-coded Orchestrator enum. To add one: register the connection capability, ship flows/connections/<name>.yaml, and reference connection: on service_call — Integration end-to-end, Contract — workflow connection example.

Management via Dashboard

The Dashboard (Connections tab) displays these connections grouped by their type. You can: - View Current State: See the merged configuration (Git + Overrides). - In-place Edit: Update specific fields like host or base_url directly via the YAML editor. - Audit: Verify which connections are active in the current deployment.