{"id":49225427,"url":"https://github.com/tonicai/structural-worker-autoscaler-chart","last_synced_at":"2026-04-24T07:01:53.358Z","repository":{"id":328357031,"uuid":"1110683055","full_name":"TonicAI/structural-worker-autoscaler-chart","owner":"TonicAI","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-09T00:47:09.000Z","size":50,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T02:34:55.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go Template","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TonicAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2025-12-05T15:05:12.000Z","updated_at":"2026-04-09T00:47:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TonicAI/structural-worker-autoscaler-chart","commit_stats":null,"previous_names":["tonicai/structural-worker-autoscaler-chart"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TonicAI/structural-worker-autoscaler-chart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TonicAI%2Fstructural-worker-autoscaler-chart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TonicAI%2Fstructural-worker-autoscaler-chart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TonicAI%2Fstructural-worker-autoscaler-chart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TonicAI%2Fstructural-worker-autoscaler-chart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TonicAI","download_url":"https://codeload.github.com/TonicAI/structural-worker-autoscaler-chart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TonicAI%2Fstructural-worker-autoscaler-chart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32212808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-24T07:01:52.724Z","updated_at":"2026-04-24T07:01:53.347Z","avatar_url":"https://github.com/TonicAI.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tonicai/structural-worker-autoscaler\n\nThis chart installs a kubernetes operator that automatically creates structural\nworkers in response to queued jobs.\n\n## chart values\n\n* `nameOverride`: explicitly set chart name\n* `fullnameOverride`: explicitly set the full chart name\n* `installation`: configures installation details\n* `installation.imagePullSecrets`: a list of image pull secrets to use\n* `installation.imagePullSecrets.*.name`: a name of an image pull secret in the namespace\n* `installation.imagePullSecrets.*.value`: a base64 `.dockerconfigjson` value, optional. When provided the chart creates this secret\n* `installation.crds.installWorkerPool`: boolean, default is true. If false the chart does not install the operator's CRD\n* `operator`: options for the operator deployment\n* `operator.configuration`: options for the operator\n* `operator.configuration.className`: default null. Sets the class name for the operator\n* `operator.configuration.defaultClass`: boolean, default true. Sets if the operator is the default for its scope\n* `operator.configuration.scope`: Either `namespace` or `cluster`, sets the scope of the operator\n* `operator.serviceAccount`: options for the operator's service account\n* `operator.serviceAccount.create`: boolean, default true. Controls if the chart creates the operator's service account\n* `operator.serviceAccount.name`: explicitly set the service account name\n* `operator.serviceAccount.annotations`: key value pair annotations to apply to the service account\n* `operator.serviceAccount.labels`: key value pay labels to apply to the service account\n* `operator.rbac`: options for the operator's rbac\n* `operator.rbac.create`: default true. sets if the chart creates rbac resources\n* `operator.rbac.name`: explicitly sets rbac resource names\n* `operator.pod.affinity`: sets the affinity property on the operator's pod\n* `operator.pod.annotations`: sets the annotations property on the operator's pod\n* `operator.pod.labels`: sets the labels property on the operator's pod\n* `operator.pod.nodeSelector`: sets the nodeSelector property on the operator's pod\n* `operator.pod.securityContext`: sets the securityContext property on the operator's pod\n* `operator.pod.tolerations`: sets the tolerations property on the operator's pod\n* `operator.pod.volumes`: sets the volumes property on the operator's pod\n* `operator.container.env`: a list of k8s `env` definitions\n* `operator.container.envFrom`: a list of k8s `envFrom` definitions\n* `operator.container.image.repository`: Image repository for the operator image.  Default: quay.io/tonicai/structural-worker-autoscaler\n* `operator.container.image.pullPolicy`: Image pull policy for the operator image. Always\n* `operator.container.image.tag`: Tag for the operator image. Default: Chart App Version\n* `operator.container.resources`: k8s resource definition for the operator container\n* `operator.container.securityContext`: k8s container securityContext definition for the operator container\n* `operator.container.volumeMounts`: list of k8s volumeMount definitions for the operator container\n\n\n\n\n## Operator\n\nThe tonic structural worker pool operator monitors the generation queue of a\nstructural installation and creates worker pods automatically when jobs are\nreported in the queue. The operator enforces a ceiling on the total number of\nworker pods it will create for a pool, which is set by `poolCapacity` property.\nIf the operator finds worker pods in a `Pending` status it assumes none of them\nhave picked up work from the queue, i.e. the following results in 1 new worker\nbeing created:\n\n- Running: 1\n- Pending: 4\n- Queue Size: 5\n- Current Capacity: 15\n\nThe operator does not delete running worker pods unless it is transitioned to\n`Shutdown` or the pool resource is deleted. Instead, worker pods created by\nthis operator have an idle timeout enabled, set by `idleTimeoutMinutes`. Worker\npods will wait at least this long between jobs, after that time period if it\nhasn’t picked up work from the queue the worker exits. The operator will\nautomatically clean up these exited workers at each polling interval. The\noperator will also removed errored worker pods during this, but can be\nconfigured to retain these workers by setting `retainFailedWorkers: true`.\n\n\n### Installation\n\n```bash\nhelm upgrade --install \\\n    \"oci://quay.io/tonicai/${STRUCTURAL_WORKER_SCALER_CHART}:${STRUCTURAL_WORKER_SCALER_CHART_VERSION}\" \\\n    -n \"${STRUCTURAL_WORKER_SCALER_NS}\" \\\n    -f \"${VALUES_FILE_PATH}\" \\\n    --wait\n```\n\nBy default this chart installs a CRD. This can be prevented by setting\n`installation.crd.installWorkerPool` to `false`. The operator requires the\nCRD to installed but this option allows it to be managed separately.\n\n```bash\nhelm upgrade --install \\\n    \"oci://quay.io/tonicai/${STRUCTURAL_WORKER_SCALER_CHART}:${STRUCTURAL_WORKER_SCALER_CHART_VERSION}\" \\\n    -n \"${STRUCTURAL_WORKER_SCALER_NS}\" \\\n    -f \"${VALUES_FILE_PATH}\" \\\n    --set-literal 'installation.crd.installWorkerPool=false' \\\n    --wait\n```\n\n### Configuration\n\nOperator can be restricted to its namespace or it can manage every namespace.\nAdditionally, multiple operators can be partitioned by setting the same\n`className` on both the operator and `StructuralWorkerPool` resources in its\nscope. Finally, a single operator in a scope can be the default class and\nwill process `StructuralWorkerPool` resources without a `className` set. By\ndefault, the operator is installed as the default class in its own namespace.\n\n### Algorithm\n\nAt each interval cycle or change to the pool resource, the operator will get\nthe queue size and total number of created workers for a specific pool. Current\ncapacity is total capacity minus *all* pods created by the pool, including\nfailed pods when `retainFailedWorkers: true`\n\n- If there are no jobs in the queue, create 0 workers\n- If there’s no capacity, create 0 workers\n- If  `queueSize - pendingWorkers \u003c= 0` , create 0 workers\n- Otherwise, create `min(capacity, max(0, queueSize - pendingWorkers))` workers\n\n\n## CRD\n\nAfter the operator is installed, three resources need to be created in the\nsame namespace as the structural installation:\n\n1. A `Secret` with a structural api key\n2. A `Deployment` for modeling scaled workers\n3. A `StructuralWorkerPool` resource\n\nThe structural API key requires the \"View Analytics\" permission.\n\n```yaml\napiVersion: v1\ndata:\n  ApiKey: aGV5IGdldCB5b3VyIG93bgo=\nkind: Secret\nmetadata:\n  name: worker-pool-api-key\n  namespace: tonic-structural\ntype: Opaque\n```\n\nThe worker deployment created by the structural helm chart is recommended for\nuse with the autoscaler. If you want only autoscaling workers, the replicas on\nthis source deployment should be set to 0.\n\n\n```yaml\napiVersion: structural.tonic.ai/v1alpha1\nkind: StructuralWorkerPool\nmetadata:\n  name: structural-worker-pool\n  namespace: tonic-structural\nspec:\n  workerPoolClassName: null\n  poolCapacity: 30\n  queue:\n    interval: \"00:00:10\"\n    source:\n      # points to structural api server in same namespace\n      endpoint: https://tonic-web-server/api/job/peek_queue\n      # Secret that contains API key\n      secretName: worker-pool-api-key\n  status: Active\n  workerSpec:\n    idleTimeoutMinutes: 3\n    # source deployment information\n    podTemplate:\n      source:\n        kind: Deployment\n        name: tonic-worker\n      # the name of the structural worker container\n      # additional configuration is applied to this container by the operator\n      containerName: tonic-worker\n    retainFailedWorkers: true\nstatus:\n  currentCapacity: 30\n  failedWorkers: 0\n  managedBy: structural-worker-pool\n  pendingWorkers: 0\n  queueEndpoint: https://tonic-web-server/api/job/peek_queue\n  queueSize: 0\n  runningWorkers: 0\n```\n\n* `spec`: Details this worker pool\n    * `spec.workerPoolClassName`: The class name for a worker pool operator. Optional. When not provided the default class operator will manage this resource.\n    * `spec.poolCapacity`: Ceiling on number of workers this pool supports. Must be non-negative but may be zero.\n        * If this resource is modified to have a lower capacity than the current\n        amount of workers the operator treats it this as an at capacity situation.\n    * `spec.queue`: Details how the operator retrieves job queue information for this pool.\n        * `spec.queue.interval`: How often the operator retrieves job queue information, in `HH:MM:SS` format.\n        * `spec.queue.source.endpoint`: The url of the job queue endpoint for this pool\n        * `spec.queue.source.secretName`: Name of a `Secret` in the same namespace with the structural api key\n    * `spec.status`: Controls this pool's behavior.\n        * `Active`: The operator is responding to load on the job queue\n        * `Paused`: The operator is not responding to load on the job queue but active workers are left running\n        * `Shutdown`: The operator is not responding to load on the job queue but active workers are shutdown and removed\n    * `spec.workerSpec`: Details how this pool's workers are managed\n        * `spec.workerSpec.idleTimeoutMinutes`: An autoscaled worker is allowed to idle without a job before exiting. The minimum value is 1.\n        * `spec.workerSpec.podTemplate.source.name`: The name of a source resource in the same namespace\n        * `spec.workerSpec.podTemplate.source.kind`: Defines what kind of resource is the source, only `Deployment` is supported.\n        * `spec.workerSpec.podTemplate.containerName`: The name of the structural worker container in the source resource\n        * `spec.workerSpec.retainFailedWorkers`: By default the operator will automatically remove worker pods that enter any kind of failed status. This can be set to `true` to disable that behavior.\n* `status`: Details the current status of this pool\n    * `status.currentCapacity`: How many workers this pool can currently support\n    * `status.failedWorkers`: How many worker pods are currently in a `Failed` status\n    * `status.managedBy`: The name of the operator managing this worker pool\n    * `status.pendingWorkers`: How many worker pods are currently in a `Pending` status\n    * `status.queueEndpoint`: The endpoint the operator retrieves queue information from, same as `spec.queue.source.endpoint`\n    * `status.queueSize`: How many jobs are available from processing. This is a subset of all jobs are in the `Queued` status.\n    * `status.runningWorkers`: How many worker pods are in a `Running` status\n\n### Pod Template\n\nThe operator reads a pod template from another resource in the same namespace\nas the pool. Currently only `Deployment` is supported. This allows keeping the\npool in sync with a primary worker template with no effort. Updating this\nsource template does not affect currently running workers.\n\nThe operator makes changes to the source pod template, including setting its\nrestart policy to `Never` , attaching finalizers and owner references, and\nusing a generated name based on the pool the worker pod belongs to.\nAdditionally, the operator will attach a label named\n`structural.tonic.ai/structural-worker-pool`  and the value will be the name of\nthe pool the worker pod belongs to. A pool resource named `cloudworkers` will\ncreate worker pods named `cloudworkers-${RANDOM}` and apply\n`structural.tonic.ai/structural-worker-pool=cloudworkers` as a label to them.\n\n\n## Kubectl\n\nRunning `kubectl get structuralworkerpools` gives an overview of what the operator believes\n\n- Running Workers: The number of pods that have entered running status\n- Pending Workers: Number of pods that aren’t yet running\n- Queue Size: How many total generations are in the queue\n- Current Capacity: How many more workers can this pool support\n    - Failed worker pods kept by `retainFailedWorkers: true` count against the current capacity\n- Worker Pool Class Name: What pool class does this belong to, empty means default\n- Status: The current status of this pool.\n    - Active: Monitoring queue, creating workers\n    - Paused: Monitoring queue, not creating workers, existing workers remain\n    - Shutdown: Not monitoring queue, not creating workers, existing workers are removed\n- Pool Capacity: How many total workers can this pool support\n- Interval: How often the generation queue length is checked\n- Api Root: URI for queue length API\n\n```\nkubectl -n tonic-structural get structuralworkerspools.structural.tonci.ai cloudworkers -o wide\nNAME           RUNNINGWORKERS   PENDINGWORKERS   QUEUESIZE   CURRENTCAPACITY   WORKERPOOLCLASSNAME   STATUS     POOLCAPACITY   INTERVAL   APIROOT\ncloudworkers   0                0                0           1                                    Shutdown   1              00:01:00   https://tonic-worker.tonic-structural:4433\n\n```\n\nThe operator will also attach various events to a pool which can be access by describe\n\n```\nkubectl -n tonic-structural describe structuralworkerpools.structural.tonic.ai cloudworkers\n\nName:         cloudworkers\nNamespace:    tonic-structural\nKind:         StructuralWorkerPool\n[snip]\nEvents:\n  Type    Reason    Age                   From     Message\n  ----    ------    ----                  ----     -------\n  Normal  Adopted   9m53s                 prod-us  adopted by prod-us\n  Normal  Shutdown  49s (x10 over 9m52s)  prod-us  structural worker pool shutdown\n\n```\n\nEvent reasons:\n\n- `Adopted`: An operator has detected this resource and is monitoring its queue\n- `FailedToReconcile`: An error occurred during reconciliation, more details can be found in the operator’s logs\n- `CleanUp` : The operator has removed 1 or more completed workers\n- `FailedWorker`: The operator has detected 1 or more pods in an error status\n- `CapacityReached`: The operator has created its allowed amount of workers but more work remains in the queue\n- `CreatedWorkers`: The operator has created 1 or more workers\n- `Paused`: The pool’s status was changed to `Paused`\n- `Shutdown`: The pool’s status was changed to `Shutdown`\n- `FailedCleanup`: The operator failed to remove resources when deleting this worker pool","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonicai%2Fstructural-worker-autoscaler-chart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftonicai%2Fstructural-worker-autoscaler-chart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonicai%2Fstructural-worker-autoscaler-chart/lists"}