Workflow Local Development

Quick Reference

Key Commands

Locally Deployed Components

These workflow services are deployed locally as shared dependencies: workflow-catalog, workflow-executions-api, workflow-engine-worker, workflow-consumer, workflow-validator, workflows-worker, standalone-tasks-worker

Utility Scripts

Execute these scripts for common operations:

Check Pod Status

bash .cursor/skills/workflow-local-dev/scripts/check-pods.sh

Restart a Service

bash .cursor/skills/workflow-local-dev/scripts/restart-service.sh <service-name>
# Example: bash .cursor/skills/workflow-local-dev/scripts/restart-service.sh catalog

Tail Service Logs

bash .cursor/skills/workflow-local-dev/scripts/tail-logs.sh <service-name>
# Example: bash .cursor/skills/workflow-local-dev/scripts/tail-logs.sh executions-api

Query Database

bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "<SQL query>"
# Example: bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "SELECT * FROM workflow_engine.workflows ORDER BY created_at DESC LIMIT 5"

Development Workflow

Use this flow primarily when containers fail locally or when you need to debug runtime behavior.

1. Capture current status: kubectl get pods --context kind-kind
2. Rebuild/restart component: tilt trigger workflow-<service>
3. Watch logs or health: kubectl logs -f <pod> --context kind-kind
4. Inspect configuration or data (if needed): bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "<SQL query>"

Troubleshooting

Pod Issues

kubectl get pods --context kind-kind
kubectl describe pod <pod-name> --context kind-kind
kubectl logs -f <pod-name> --context kind-kind

Temporal Workflows

Open http://localhost:8081 (Temporal UI) and search by workflow ID.

Database State

# Use the db-query script (runs psql inside the postgres pod)
bash .cursor/skills/workflow-local-dev/scripts/db-query.sh "SELECT * FROM workflow_engine.workflows ORDER BY created_at DESC LIMIT 5"

Pulsar Messages

pulsar-admin topics stats persistent://public/dap/<topic>
pulsar-client consume persistent://public/dap/<topic> -s test-sub -n 10

Using Kubernetes MCP (When Available)

If the Kubernetes MCP server is enabled, you can use MCP tools instead of shell commands for a more integrated experience. The MCP defaults to the kind-kind context.

List Pods

Tool: pods_list
Arguments: { "labelSelector": "app=workflow-catalog" }

Or list all pods:

Tool: pods_list
Arguments: {}

Get Pod Logs

Tool: pods_log
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default",
  "tail": 100
}

For previous container logs (after crash):

Tool: pods_log
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default",
  "previous": true
}

Execute Commands in Pods (e.g., Database Queries)

Tool: pods_exec
Arguments: {
  "name": "postgres-xxxxx",
  "namespace": "default",
  "command": ["psql", "-U", "postgres", "-d", "temporal", "-c", "SELECT * FROM workflow_engine.workflows ORDER BY created_at DESC LIMIT 5"]
}

Delete Pod (Force Restart)

Tool: pods_delete
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default"
}

Get Pod Details

Tool: pods_get
Arguments: {
  "name": "workflow-catalog-xxxxx",
  "namespace": "default"
}

List Cluster Events (Troubleshooting)

Tool: events_list
Arguments: { "namespace": "default" }

Note: When using MCP tools, you don't need to specify context as it defaults to kind-kind. The MCP approach is useful when you want the agent to directly interact with the cluster without spawning shell processes.

Additional Resources

• For complete service URLs and infrastructure details, see reference.md