Adding --gcp-cloud-run-scale-down-stabilization-duration flag

[seanbollin]

Related issues

Closes: https://temporalio.atlassian.net/browse/COM-241

What changed?

Adds --gcp-cloud-run-scale-down-stabilization-duration to
temporal worker deployment create-version and
temporal worker deployment update-version-compute-config.

UX difference: the GCP Cloud Run scaler's scale-down stabilization window was
previously hard-coded to 90s, so a worker pool running long or bursty activities
could be scaled down out from under in-flight work. Users can now configure it:

# before: not settable — always 90s
# after:
temporal worker deployment create-version ... \
    --gcp-cloud-run-scale-down-stabilization-duration 10m   # hold capacity 10m after demand

Details:

• The flag is a duration (90s, 5m, 10m), matching the CLI's convention
  for time-valued flags (cliext.FlagDuration, like --schedule-to-close-timeout,
  --retention). It joins the existing all-or-none GCP Cloud Run scaler group, so
  --gcp-cloud-run-min-instances, --gcp-cloud-run-max-instances,
  --gcp-cloud-run-initial-instances, --gcp-cloud-run-utilization-target, and
  --gcp-cloud-run-scale-down-stabilization-duration must all be set together.
• Behavior: after the scaler last saw unmet task demand, it waits this long before
  it may scale the pool down. Defaults to 90s when unset; 0s disables the wait.
• The CLI converts the duration to milliseconds and sends it under the rate-based
  scaler's existing no_sync_quiet_ms config key, which the server (WCI) already
  validates and applies — no server-side change is required.
• describe-version surfaces the value as a duration string (JSON
  scaleDownStabilization, e.g. "5m 0s", formatted the same way as schedule
  durations; the text summary shows the same).

Checklist

Stability

• Breaking changes are marked with 💥 in the PR title and release notes — no breaking changes; the flag joins an as-yet-unreleased flag group
• Changes to JSON output (-o json / -o jsonl) are treated as breaking changes — describe-version gains an additive scaleDownStabilizationMs field; the GCP scaler JSON block is not in a tagged release yet, so no released output changes

Design

• This feature does not depend on Cloud-only APIs or behavior (it works against an OSS server)
• New commands follow temporal <noun> <verb> structure — no new commands; flag added to existing commands
• New flags are named after the API concept, not the implementation mechanism — scale-down-stabilization-duration names the behavior (cf. k8s HPA "stabilization window"), not the internal no_sync_quiet_ms key
• New flags don't duplicate an existing flag that serves the same purpose
• New flags do not have short aliases without strong justification — no alias
• Experimental features are marked with (Experimental) in commands.yaml — both commands already carry a "This is an experimental feature" note

Help text (see style guide at the top of commands.yaml)

• All flags shown in help text and examples are implemented and functional — the GCP examples include all five flags so they stay copy-pasteable
• Summaries use sentence case and have no trailing period — no new command summaries
• Long descriptions end with a period and include at least one example invocation
• Examples use long flags (--namespace, not -n), one flag per line
• Placeholder values use YourXxx form (YourWorkflowId, YourNamespace)

Behavior

• Results go to stdout; errors and warnings go to stderr
• Error messages are lowercase with no trailing punctuation

Tests

• Added functional test(s) (SharedServerSuite) — group/negative/sub-millisecond/wrong-provider cases in TestCreateWorkerDeploymentVersion_Errors; carried in ...UpdateModes
• Added unit test(s) (func TestXxx) — TestGCPCloudRunScalerDetails, TestFormatComputeConfigProto_ScalerBounds

Manual tests

Setup

temporal server start-dev --headless

A full --gcp-cloud-run-* create also needs a real Cloud Run worker pool +
service account (the server validates the provider). The error-path checks
below run entirely against the dev server (they fail client-side, before the
RPC). The runtime effect was verified separately via an in-process WCI
integration test.

Happy path

$ temporal worker deployment create-version \
    --deployment-name YourDeployment \
    --build-id YourBuildId \
    --gcp-cloud-run-project YourGcpProject \
    --gcp-cloud-run-region us-central1 \
    --gcp-cloud-run-worker-pool YourWorkerPool \
    --gcp-cloud-run-service-account YourServiceAccount@YourGcpProject.iam.gserviceaccount.com \
    --gcp-cloud-run-min-instances 0 \
    --gcp-cloud-run-max-instances 10 \
    --gcp-cloud-run-initial-instances 2 \
    --gcp-cloud-run-utilization-target 0.8 \
    --gcp-cloud-run-scale-down-stabilization-duration 5m
Successfully created worker deployment version

$ temporal worker deployment describe-version \
    --deployment-name YourDeployment \
    --build-id YourBuildId
# summary: gcp-cloud-run (min 0, initial 2, max 10, utilization 0.8, scale-down-stabilization 5m 0s)
# --output json includes "scaleDownStabilization": "5m 0s" on the scaler

Error case

# incomplete group (all five must be set together):
$ temporal worker deployment create-version \
    --deployment-name YourDeployment --build-id YourBuildId \
    --gcp-cloud-run-project YourGcpProject --gcp-cloud-run-region us-central1 \
    --gcp-cloud-run-worker-pool YourWorkerPool \
    --gcp-cloud-run-service-account YourServiceAccount@YourGcpProject.iam.gserviceaccount.com \
    --gcp-cloud-run-scale-down-stabilization-duration 5m
Error: --gcp-cloud-run-min-instances, --gcp-cloud-run-max-instances, --gcp-cloud-run-initial-instances, --gcp-cloud-run-utilization-target, and --gcp-cloud-run-scale-down-stabilization-duration must be set together
$ echo $?
1

# negative (incl. sub-millisecond, which must not silently truncate to 0):
$ temporal worker deployment create-version \
    --deployment-name YourDeployment --build-id YourBuildId \
    --gcp-cloud-run-project YourGcpProject --gcp-cloud-run-region us-central1 \
    --gcp-cloud-run-worker-pool YourWorkerPool \
    --gcp-cloud-run-service-account YourServiceAccount@YourGcpProject.iam.gserviceaccount.com \
    --gcp-cloud-run-min-instances 0 --gcp-cloud-run-max-instances 10 \
    --gcp-cloud-run-initial-instances 2 --gcp-cloud-run-utilization-target 0.8 \
    --gcp-cloud-run-scale-down-stabilization-duration=-1us
Error: --gcp-cloud-run-scale-down-stabilization-duration cannot be negative

# sub-millisecond precision is rejected rather than silently rounded:
$ temporal worker deployment create-version ... \
    --gcp-cloud-run-scale-down-stabilization-duration 500us
Error: --gcp-cloud-run-scale-down-stabilization-duration must be a whole number of milliseconds

# on a non-GCP provider:
$ temporal worker deployment create-version \
    --deployment-name YourDeployment --build-id YourBuildId \
    --aws-lambda-function-arn YourFunctionArn \
    --aws-lambda-skip-role-and-external-id \
    --gcp-cloud-run-scale-down-stabilization-duration 5m
Error: the Cloud Run scaling flags are only valid with --gcp-cloud-run-worker-pool

Composition

# Raise the stabilization window on an existing version (all five flags are
# re-supplied, since they are one all-or-none group), then confirm via describe.
$ temporal worker deployment update-version-compute-config \
    --deployment-name YourDeployment --build-id YourBuildId \
    --gcp-cloud-run-worker-pool YourWorkerPool \
    --gcp-cloud-run-min-instances 0 --gcp-cloud-run-max-instances 10 \
    --gcp-cloud-run-initial-instances 2 --gcp-cloud-run-utilization-target 0.8 \
    --gcp-cloud-run-scale-down-stabilization-duration 10m
Successfully updated worker deployment version compute config

$ temporal worker deployment describe-version \
    --deployment-name YourDeployment --build-id YourBuildId --output json
# scaler now shows "scaleDownStabilization": "10m 0s"

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37bae511f3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 99856f6bd4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[gcristea-temporal]

This looks good, thank you for taking adding the extra argument.

Not sure whether my review approval alone is enough for you to merge.

[chaptersix]

please use the PR template that demos the UX difference.

[jaypipes]

I would suggest using --scale-down-stabilization-window or --scale-down-stabilization-duration to align with the identical Kubernetes autoscaler settings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eb1ac89aa4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[jaypipes]

❤️