From 9ef33abde19423c58487736e409ff59aae2f574d Mon Sep 17 00:00:00 2001
From: Haihan Jiang <haihanj99@gmail.com>
Date: Fri, 29 May 2026 20:42:35 -0700
Subject: [PATCH] Document gke-deploy timeout overrides

---
 gke-deploy/doc/app/cloudbuild-no-configs.yaml |  2 ++
 .../doc/app/cloudbuild-with-configs.yaml      |  2 ++
 gke-deploy/doc/deploying-with-cloud-build.md  | 25 ++++++++++++++++++-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/gke-deploy/doc/app/cloudbuild-no-configs.yaml b/gke-deploy/doc/app/cloudbuild-no-configs.yaml
index d5cdc5e25..0ade59261 100644
--- a/gke-deploy/doc/app/cloudbuild-no-configs.yaml
+++ b/gke-deploy/doc/app/cloudbuild-no-configs.yaml
@@ -24,6 +24,7 @@ steps:
   - '--namespace=$_K8S_NAMESPACE'
   - '--cluster=$_GKE_CLUSTER'
   - '--location=$_GKE_LOCATION'
+  - '--timeout=$_GKE_DEPLOY_TIMEOUT'
 images:
 - '$_IMAGE_NAME:$_IMAGE_VERSION'
 substitutions:
@@ -35,6 +36,7 @@ substitutions:
   _K8S_APP_NAME:
   _K8S_NAMESPACE:
   _OUTPUT_PATH:
+  _GKE_DEPLOY_TIMEOUT: 5m0s
 options:
   substitution_option: 'ALLOW_LOOSE'
 tags: ['$_K8S_APP_NAME']
diff --git a/gke-deploy/doc/app/cloudbuild-with-configs.yaml b/gke-deploy/doc/app/cloudbuild-with-configs.yaml
index 362471433..be2ea1674 100644
--- a/gke-deploy/doc/app/cloudbuild-with-configs.yaml
+++ b/gke-deploy/doc/app/cloudbuild-with-configs.yaml
@@ -24,6 +24,7 @@ steps:
   - '--namespace=$_K8S_NAMESPACE'
   - '--cluster=$_GKE_CLUSTER'
   - '--location=$_GKE_LOCATION'
+  - '--timeout=$_GKE_DEPLOY_TIMEOUT'
 images:
 - '$_IMAGE_NAME:$_IMAGE_VERSION'
 substitutions:
@@ -36,6 +37,7 @@ substitutions:
   _K8S_APP_NAME:
   _K8S_NAMESPACE:
   _OUTPUT_BUCKET_PATH:
+  _GKE_DEPLOY_TIMEOUT: 5m0s
 options:
   substitution_option: 'ALLOW_LOOSE'
 tags: [$_K8S_APP_NAME]
diff --git a/gke-deploy/doc/deploying-with-cloud-build.md b/gke-deploy/doc/deploying-with-cloud-build.md
index fb5eaa65a..f4f65a705 100644
--- a/gke-deploy/doc/deploying-with-cloud-build.md
+++ b/gke-deploy/doc/deploying-with-cloud-build.md
@@ -101,12 +101,35 @@ sed -i "s#@IMAGE_NAME@#$IMAGE_NAME#g" config/deployment.yaml
 sed -i "s#@NAMESPACE@#$NAMESPACE#g" config/namespace.yaml
 
 # Run build, replacing substitution variables accordingly.
-gcloud builds submit . --project=$PROJECT --config cloudbuild-with-configs.yaml --substitutions=_IMAGE_NAME=gcr.io/$PROJECT/$APP,_IMAGE_VERSION=$VERSION,_GKE_CLUSTER=$CLUSTER,_GKE_LOCATION=$LOCATION,_K8S_YAML_PATH=config,_K8S_APP_NAME=$APP,_K8S_NAMESPACE=$NAMESPACE,_OUTPUT_PATH=$BUCKET_PATH
+gcloud builds submit . --project=$PROJECT --config cloudbuild-with-configs.yaml --substitutions=_IMAGE_NAME=gcr.io/$PROJECT/$APP,_IMAGE_VERSION=$VERSION,_GKE_CLUSTER=$CLUSTER,_GKE_LOCATION=$LOCATION,_K8S_YAML_PATH=config,_K8S_APP_NAME=$APP,_K8S_NAMESPACE=$NAMESPACE,_OUTPUT_BUCKET_PATH=$BUCKET_PATH
 ```
 
 You can replace the GCS url with a UNIX file path if you do not
 want to store configs to a bucket.
 
+### Increase the deploy wait timeout
+
+`gke-deploy apply` waits up to five minutes for applied Kubernetes objects to
+be ready. If your rollout needs more time, pass a larger `--timeout` value to
+the `gke-deploy` step:
+
+```yaml
+- name: 'gcr.io/cloud-builders/gke-deploy'
+  id: 'Apply deploy'
+  args:
+  - 'apply'
+  - '--filename=$_K8S_YAML_PATH'
+  - '--cluster=$_GKE_CLUSTER'
+  - '--location=$_GKE_LOCATION'
+  - '--timeout=20m0s'
+  timeout: 1260s
+```
+
+The `--timeout` flag controls how long `gke-deploy` waits for Kubernetes
+objects to become ready. The Cloud Build step `timeout` controls how long Cloud
+Build lets the entire build step run, so it should be slightly longer than the
+`gke-deploy` timeout.
+
 Builds can use `$SHORT_SHA` instead of an explicit `$_IMAGE_VERSION` for the
 image and app versions if executed via a trigger. Follow [these
 instructions](automated-deployments.md) to set up a trigger.