🤖 fix: align template build wait timeout semantics

Address Codex review by aligning aggregated API request timeout defaults with template build waits and preserving timeout/cancel semantics when mapping build wait errors.

- set aggregated API request timeout default to 30m
- distinguish internal build wait expiry from request lifecycle cancellation/deadline
- keep internal wait expiry as BadRequest while returning Timeout for canceled/deadline contexts
- add coverage for request-timeout mapping and config defaults
- document request-timeout relationship in aggregated deployment guide

---

_Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.57`_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh costs=0.57 -->

Author: ThomasK33

docs/how-to/deploy-aggregated-apiserver.md

@@ -103,6 +103,8 @@ The wait behavior is configurable via environment variables on the
 - `CODER_K8S_TEMPLATE_BUILD_INITIAL_POLL_INTERVAL` (default: `2s`)
 - `CODER_K8S_TEMPLATE_BUILD_MAX_POLL_INTERVAL` (default: `10s`)
 
+- Aggregated API request timeout defaults to `30m`; keep it at or above the build wait timeout.
+
 Behavior:
 
 - Polls at the initial interval for the first 2 minutes.

internal/aggregated/storage/storage_test.go

@@ -509,6 +509,110 @@ func TestTemplateStorageUpdateReturnsBadRequestWhenTemplateVersionBuildWaitTimes
 	}
 }
 
+func TestTemplateStorageUpdateReturnsTimeoutWhenRequestContextTimesOut(t *testing.T) {
+	server, state := newMockCoderServer(t)
+	defer server.Close()
+
+	templateStorage := NewTemplateStorage(newTestClientProvider(t, server.URL))
+	baseCtx := namespacedContext("control-plane")
+
+	createObj := &aggregationv1alpha1.CoderTemplate{
+		ObjectMeta: metav1.ObjectMeta{Name: "acme.request-timeout-template"},
+		Spec: aggregationv1alpha1.CoderTemplateSpec{
+			Organization: "acme",
+			Files:        map[string]string{"main.tf": "resource \"null_resource\" \"initial\" {}"},
+		},
+	}
+	createdObj, err := templateStorage.Create(baseCtx, createObj, rest.ValidateAllObjectFunc, nil)
+	if err != nil {
+		t.Fatalf("expected template create to succeed: %v", err)
+	}
+	createdTemplate := createdObj.(*aggregationv1alpha1.CoderTemplate)
+
+	t.Setenv(templateVersionBuildWaitTimeoutEnv, "5s")
+	t.Setenv(templateVersionBuildBackoffAfterEnv, "0s")
+	t.Setenv(templateVersionBuildInitialPollIntervalEnv, "10ms")
+	t.Setenv(templateVersionBuildMaxPollIntervalEnv, "20ms")
+
+	state.setNextCreatedTemplateVersionStatus(codersdk.ProvisionerJobPending)
+
+	updateCtx, cancel := context.WithTimeout(baseCtx, 120*time.Millisecond)
+	defer cancel()
+
+	desiredTemplate := createdTemplate.DeepCopy()
+	desiredTemplate.Spec.Files = map[string]string{"main.tf": "resource \"null_resource\" \"updated\" {}"}
+
+	updatedObj, created, updateErr := templateStorage.Update(
+		updateCtx,
+		desiredTemplate.Name,
+		testUpdatedObjectInfo{obj: desiredTemplate},
+		nil,
+		rest.ValidateAllObjectUpdateFunc,
+		false,
+		nil,
+	)
+	if updateErr == nil {
+		t.Fatal("expected update to fail when request context times out")
+	}
+	if updatedObj != nil {
+		t.Fatalf("expected nil updated object on request timeout, got %T", updatedObj)
+	}
+	if created {
+		t.Fatal("expected update created=false")
+	}
+	if apierrors.IsBadRequest(updateErr) {
+		t.Fatalf("expected non-BadRequest error for request context timeout, got %v", updateErr)
+	}
+	if !apierrors.IsTimeout(updateErr) {
+		t.Fatalf("expected timeout error for request context timeout, got %v", updateErr)
+	}
+	assertTopLevelStatusError(t, updateErr)
+}
+
+func TestMapTemplateVersionBuildWaitErrorMapsRequestContextFailuresToTimeout(t *testing.T) {
+	tests := []struct {
+		name  string
+		cause error
+	}{
+		{
+			name:  "deadline exceeded",
+			cause: context.DeadlineExceeded,
+		},
+		{
+			name:  "canceled",
+			cause: context.Canceled,
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			mappedErr := mapTemplateVersionBuildWaitError(
+				&templateVersionBuildWaitTimeoutError{
+					versionID:   uuid.New(),
+					waitTimeout: time.Minute,
+					lastStatus:  codersdk.ProvisionerJobRunning,
+					cause:       tt.cause,
+				},
+				"acme.template",
+			)
+
+			if mappedErr == nil {
+				t.Fatal("expected mapped timeout error")
+			}
+			if apierrors.IsBadRequest(mappedErr) {
+				t.Fatalf("expected timeout error, got BadRequest: %v", mappedErr)
+			}
+			if !apierrors.IsTimeout(mappedErr) {
+				t.Fatalf("expected timeout error, got %v", mappedErr)
+			}
+			assertTopLevelStatusError(t, mappedErr)
+		})
+	}
+}
+
 func TestLoadTemplateVersionBuildWaitConfigFromEnvDefaults(t *testing.T) {
 	t.Setenv(templateVersionBuildWaitTimeoutEnv, "")
 	t.Setenv(templateVersionBuildBackoffAfterEnv, "")

internal/aggregated/storage/template.go

@@ -50,6 +50,8 @@ var (
 	_ rest.GracefulDeleter      = (*TemplateStorage)(nil)
 	_ rest.Scoper               = (*TemplateStorage)(nil)
 	_ rest.SingularNameProvider = (*TemplateStorage)(nil)
+
+	errTemplateVersionBuildWaitTimeoutExceeded = errors.New("template version build wait timeout exceeded")
 )
 
 // TemplateStorage provides codersdk-backed CoderTemplate objects.
@@ -687,7 +689,14 @@ func mapTemplateVersionBuildWaitError(waitErr error, templateName string) error
 
 	var timeoutErr *templateVersionBuildWaitTimeoutError
 	if errors.As(waitErr, &timeoutErr) {
-		return apierrors.NewBadRequest(timeoutErr.Error())
+		switch {
+		case errors.Is(timeoutErr.cause, errTemplateVersionBuildWaitTimeoutExceeded):
+			return apierrors.NewBadRequest(timeoutErr.Error())
+		case errors.Is(timeoutErr.cause, context.DeadlineExceeded), errors.Is(timeoutErr.cause, context.Canceled):
+			return apierrors.NewTimeoutError(timeoutErr.Error(), 0)
+		default:
+			return apierrors.NewInternalError(timeoutErr)
+		}
 	}
 
 	return coder.MapCoderError(waitErr, aggregationv1alpha1.Resource("codertemplates"), templateName)
@@ -709,7 +718,15 @@ func waitForTemplateVersionBuild(ctx context.Context, sdk *codersdk.Client, vers
 		return waitConfigErr
 	}
 
-	waitCtx, cancel := context.WithTimeout(ctx, waitConfig.waitTimeout)
+	effectiveWaitTimeout := waitConfig.waitTimeout
+	if requestDeadline, hasRequestDeadline := ctx.Deadline(); hasRequestDeadline {
+		remaining := time.Until(requestDeadline)
+		if remaining > 0 && remaining < effectiveWaitTimeout {
+			effectiveWaitTimeout = remaining
+		}
+	}
+
+	waitCtx, cancel := context.WithTimeout(ctx, effectiveWaitTimeout)
 	defer cancel()
 
 	pollInterval := waitConfig.initialPoll
@@ -721,12 +738,17 @@ func waitForTemplateVersionBuild(ctx context.Context, sdk *codersdk.Client, vers
 		version, err := sdk.TemplateVersion(waitCtx, versionID)
 		if err != nil {
 			if waitCtx.Err() != nil {
+				timeoutCause, timeoutCauseErr := templateVersionBuildWaitTimeoutCause(ctx, waitCtx)
+				if timeoutCauseErr != nil {
+					return timeoutCauseErr
+				}
+
 				return &templateVersionBuildWaitTimeoutError{
 					versionID:   versionID,
-					waitTimeout: waitConfig.waitTimeout,
+					waitTimeout: effectiveWaitTimeout,
 					lastStatus:  lastStatus,
 					lastError:   lastError,
-					cause:       waitCtx.Err(),
+					cause:       timeoutCause,
 				}
 			}
 			return fmt.Errorf("fetch template version %q: %w", versionID.String(), err)
@@ -771,21 +793,47 @@ func waitForTemplateVersionBuild(ctx context.Context, sdk *codersdk.Client, vers
 
 		select {
 		case <-waitCtx.Done():
-			if waitCtx.Err() == nil {
-				return fmt.Errorf("assertion failed: wait context finished without an error")
+			timeoutCause, timeoutCauseErr := templateVersionBuildWaitTimeoutCause(ctx, waitCtx)
+			if timeoutCauseErr != nil {
+				return timeoutCauseErr
 			}
+
 			return &templateVersionBuildWaitTimeoutError{
 				versionID:   versionID,
-				waitTimeout: waitConfig.waitTimeout,
+				waitTimeout: effectiveWaitTimeout,
 				lastStatus:  lastStatus,
 				lastError:   lastError,
-				cause:       waitCtx.Err(),
+				cause:       timeoutCause,
 			}
 		case <-time.After(pollInterval):
 		}
 	}
 }
 
+func templateVersionBuildWaitTimeoutCause(requestCtx, waitCtx context.Context) (error, error) {
+	if requestCtx == nil {
+		return nil, fmt.Errorf("assertion failed: request context must not be nil")
+	}
+	if waitCtx == nil {
+		return nil, fmt.Errorf("assertion failed: wait context must not be nil")
+	}
+
+	waitErr := waitCtx.Err()
+	if waitErr == nil {
+		return nil, fmt.Errorf("assertion failed: wait context finished without an error")
+	}
+
+	if requestErr := requestCtx.Err(); requestErr != nil {
+		return requestErr, nil
+	}
+
+	if errors.Is(waitErr, context.DeadlineExceeded) {
+		return errTemplateVersionBuildWaitTimeoutExceeded, nil
+	}
+
+	return waitErr, nil
+}
+
 func loadTemplateVersionBuildWaitConfigFromEnv() (templateVersionBuildWaitConfig, error) {
 	waitTimeout, waitTimeoutErr := parseDurationEnvOrDefault(templateVersionBuildWaitTimeoutEnv, defaultTemplateVersionBuildWaitTimeout)
 	if waitTimeoutErr != nil {

internal/app/apiserverapp/apiserverapp.go

@@ -38,6 +38,8 @@ const (
 	// DefaultSecureServingPort is the secure serving port used by aggregated-apiserver mode.
 	DefaultSecureServingPort = 6443
 	serverName               = "coder-k8s-aggregated-apiserver"
+	// defaultRequestTimeout keeps API request lifetimes above template build wait defaults.
+	defaultRequestTimeout = 30 * time.Minute
 )
 
 // Options configures aggregated-apiserver bootstrap behavior.
@@ -192,6 +194,7 @@ func NewRecommendedConfig(
 	recommendedConfig.RuleResolver = authz
 	recommendedConfig.EffectiveVersion = apiservercompatibility.DefaultBuildEffectiveVersion()
 	recommendedConfig.SkipOpenAPIInstallation = true
+	recommendedConfig.RequestTimeout = defaultRequestTimeout
 
 	definitionNamer := apiserveropenapi.NewDefinitionNamer(scheme)
 	recommendedConfig.OpenAPIConfig = genericapiserver.DefaultOpenAPIConfig(getOpenAPIDefinitions, definitionNamer)

internal/app/apiserverapp/apiserverapp_test.go

@@ -128,6 +128,39 @@ func TestInstallAPIGroupRegistersDiscovery(t *testing.T) {
 	}
 }
 
+func TestNewRecommendedConfigSetsExtendedRequestTimeout(t *testing.T) {
+	t.Helper()
+
+	scheme := NewScheme()
+	if scheme == nil {
+		t.Fatal("expected non-nil scheme")
+	}
+	codecs := serializer.NewCodecFactory(scheme)
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("create test listener: %v", err)
+	}
+	defer func() {
+		_ = listener.Close()
+	}()
+
+	secureServingOptions := genericoptions.NewSecureServingOptions()
+	secureServingOptions.Listener = listener
+	secureServingOptions.BindPort = 0
+	secureServingOptions.ServerCert.CertDirectory = ""
+	secureServingOptions.ServerCert.PairName = ""
+
+	recommendedConfig, err := NewRecommendedConfig(scheme, codecs, secureServingOptions)
+	if err != nil {
+		t.Fatalf("build recommended config: %v", err)
+	}
+
+	if got, want := recommendedConfig.RequestTimeout, defaultRequestTimeout; got != want {
+		t.Fatalf("expected request timeout %s, got %s", want, got)
+	}
+}
+
 func TestBuildClientProviderDefersMissingCoderConfigAsServiceUnavailable(t *testing.T) {
 	t.Parallel()