{"id":49849516,"url":"https://github.com/temporalio/temporal-auto-scaled-workers","last_synced_at":"2026-05-14T14:09:22.324Z","repository":{"id":347084040,"uuid":"1148286117","full_name":"temporalio/temporal-auto-scaled-workers","owner":"temporalio","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-30T21:05:46.000Z","size":284,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T21:22:26.239Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/temporalio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T19:42:41.000Z","updated_at":"2026-04-23T19:52:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"4a754d0e-5b73-40b1-bbce-221274325be2","html_url":"https://github.com/temporalio/temporal-auto-scaled-workers","commit_stats":null,"previous_names":["temporalio/temporal-auto-scaled-workers"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/temporalio/temporal-auto-scaled-workers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Ftemporal-auto-scaled-workers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Ftemporal-auto-scaled-workers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Ftemporal-auto-scaled-workers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Ftemporal-auto-scaled-workers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/temporalio","download_url":"https://codeload.github.com/temporalio/temporal-auto-scaled-workers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Ftemporal-auto-scaled-workers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33028256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-14T14:09:21.131Z","updated_at":"2026-05-14T14:09:22.312Z","avatar_url":"https://github.com/temporalio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Temporal Auto-Scaled Workers\n\nAutomatically scale Temporal workers in response to workload. This project implements a **Worker Controller Instance (WCI)** — a long-running Temporal workflow that monitors task queue metrics and scales workers across cloud compute providers.\n\n## Overview\n\nEach WCI manages a single deployment version (deployment name + build ID). It:\n\n1. Receives task-add signals from the Temporal Matching Service\n2. Periodically polls task queue backlog and dispatch metrics\n3. Applies a configurable scaling algorithm to decide when to act\n4. Invokes workers on the configured compute provider\n\nMultiple **scaling groups** can be defined per WCI, each mapping a set of task queue types (workflow, activity, nexus) to a compute provider and scaling algorithm. One group can act as a catch-all for task types not claimed by other groups.\n\n## Supported Compute Providers\n\n| Provider | Type string | Launch strategy |\n|---|---|---|\n| AWS Lambda | `aws-lambda` | Invoke (one-off) |\n| AWS ECS | `aws-ecs` | Worker set (managed scaling) |\n| GCP Cloud Run | `gcp-cloud-run` | Worker set |\n| Kubernetes | `k8s` | Worker set |\n| Subprocess | `subprocess` | Invoke (dev/test only) |\n\n**Invoke** providers are called once per scaling event to start a short-lived worker.\n**Worker-set** providers manage a persistent pool whose size is adjusted up or down.\n\n## Supported Scaling Algorithms\n\n| Algorithm | Type string | Description |\n|---|---|---|\n| No-sync | `no-sync` | Scales up when backlog or arrival rate exceeds thresholds; cools down between invocations |\n\n## Configuration\n\n### Dynamic config\n\n| Setting | Default | Description |\n|---|---|---|\n| `WorkerControllerEnabled` | `false` | Enable WCI per namespace |\n| `WorkerControllerMaxInstances` | `100` | Max WCIs per namespace |\n| `WorkerControllerEnabledComputeProviders` | all | Allowed compute provider types |\n| `WorkerControllerEnabledScalingAlgorithms` | all | Allowed scaling algorithm types |\n| `WorkerControllerAWSIntermediaryRoles` | `[]` | IAM role chain for AWS STS |\n| `WorkerControllerGCPIntermediaryServiceAccounts` | `[]` | Service account chain for GCP |\n| `WorkerControllerAWSRequireRoleAndExternalID` | `true` | Enforce role + external ID on AWS configs |\n\n## Spec Format\n\nA WCI spec is a map of named scaling groups:\n\n```json\n{\n  \"scaling_group_specs\": {\n    \"workflows\": {\n      \"task_types\": [\"WORKFLOW\"],\n      \"compute\": {\n        \"provider_type\": \"aws-lambda\",\n        \"config\": {\n          \"arn\": \"arn:aws:lambda:us-east-1:123456789012:function:my-worker\",\n          \"role\": \"arn:aws:iam::123456789012:role/temporal-wci\",\n          \"role_external_id\": \"my-external-id\"\n        }\n      },\n      \"scaling\": {\n        \"scaling_algorithm\": \"no-sync\",\n        \"config\": {\n          \"scale_up_backlog_threshold\": \"5\",\n          \"scale_up_cooloff_ms\": \"500\",\n          \"max_worker_lifetime_ms\": \"300000\"\n        }\n      }\n    },\n    \"activities\": {\n      \"task_types\": [\"ACTIVITY\", \"NEXUS\"],\n      \"compute\": {\n        \"provider_type\": \"aws-ecs\",\n        \"config\": {\n          \"cluster\": \"my-cluster\",\n          \"service\": \"my-worker-service\",\n          \"region\": \"us-east-1\",\n          \"role\": \"arn:aws:iam::123456789012:role/temporal-wci\"\n        }\n      }\n    }\n  }\n}\n```\n\nA group with no `task_types` acts as a catch-all for any task type not claimed by another group. At most one catch-all group is allowed. The `scaling` block is optional; omitting it leaves the group with the default scaling configuration for the given compute provider.\n\n### `no-sync` algorithm config\n\n| Key | Default | Description |\n|---|---|---|\n| `scale_up_backlog_threshold` | `0` | Scale up when backlog exceeds this value |\n| `scale_up_cooloff_ms` | `100` | Minimum milliseconds between scale-up actions |\n| `max_worker_lifetime_ms` | `600000` | Re-invoke workers at least this often (10 min) |\n| `scale_up_dispatch_rate_epsilon` | `0` | Suppress scale-up if dispatch rate is stable within this margin |\n| `metrics_poll_interval_ms` | `60000` | How often to poll task queue metrics |\n\n## Client API\n\n```go\nimport \"go.temporal.io/auto-scaled-workers/wci/client\"\n\n// Register the Fx module in your server\nfx.Provide(client.ClientProvider)\n\n// Use the Client interface\ntype MyComponent struct {\n    wciClient client.Client\n}\n\n// Create or update a WCI\nerr := wciClient.UpdateWorkerControllerInstance(ctx, ns, deploymentVersion, \u0026client.UpdateWorkerControllerInstanceRequest{\n    Spec: \u0026client.Spec{\n        ScalingGroupSpecs: map[string]client.ScalingGroupSpec{\n            \"default\": {\n                Compute: client.ComputeProviderSpec{\n                    ProviderType: \"aws-lambda\",\n                    Config:       map[string]string{\"arn\": \"...\"},\n                },\n            },\n        },\n    },\n})\n\n// List all WCIs\nresp, err := wciClient.ListWorkerControllerInstances(ctx, ns, pageSize, nextPageToken)\n\n// Delete a WCI\nerr := wciClient.DeleteWorkerControllerInstance(ctx, ns, deploymentVersion, conflictToken)\n```\n\nAll mutating operations accept a `ConflictToken` for optimistic concurrency control. Obtain it from `DescribeWorkerControllerInstance` and pass it with updates to detect concurrent modifications.\n\n## Integration with Temporal Server\n\nThe `TaskHookFactory` returned by `ClientProvider` must be registered with the Temporal Matching Service. It intercepts task-add events and signals the appropriate WCI workflow.\n\nEnable per namespace via the `WorkerControllerEnabled` dynamic config setting.\n\n## Building\n\n```bash\n# Build\nmake bins\n\n# Run tests\nmake test\n```\n\n## Run Together with a Local Temporal Server\n\n1. Check out the [Temporal Server](https://github.com/temporalio/temporal) alongside this repository.\n2. Link the two repositories using either a [Go Workspace](https://go.dev/doc/tutorial/workspaces) or a [`replace` directive](https://go.dev/ref/mod#go-mod-file-replace) in the server's `go.mod`.\n3. Compile the Temporal Server: `make bins` (or `make all`).\n4. Start the server: `make start` — this uses the SQLite in-memory backend and runs `temporal-auto-scaled-workers` as part of the system workers.\n\n## Scaling Algorithm Simulators\n\nInteractive simulators for the scaling algorithms are available in [`docs/simulators/`](docs/simulators/).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemporalio%2Ftemporal-auto-scaled-workers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftemporalio%2Ftemporal-auto-scaled-workers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemporalio%2Ftemporal-auto-scaled-workers/lists"}