Rancher Manager and Downstream Cluster Agent: Provisioning Timeout Logic

Default Provisioning Timeout

In Rancher 2.x, the default timeout before a downstream cluster is marked as failed during the initial agent handshake is 30 minutes (1800 seconds). This applies to both RKE and K3s provisioning workflows. The cluster remains in the Provisioning state until the cluster-agent completes its API handshakes and heartbeats with the Rancher Manager; if that process exceeds the timeout, the cluster transitions to a failed state.

Adjusting the Timeout

Global Override

You can change the timeout for all new cluster creations by setting the CATTLE_CLUSTER_PROVISION_TIMEOUT environment variable on the Rancher Manager deployment (value in seconds). For example, to extend it to 45 minutes:

kubectl set env deployment/rancher -n cattle-system CATTLE_CLUSTER_PROVISION_TIMEOUT=2700

This change affects every cluster created after the Manager restarts. Existing clusters in Provisioning are not retroactively updated.

Per‑Cluster Override

Individual clusters can specify their own timeout by adding a provisioningTimeout field (seconds) to the Cluster custom resource spec. This value overrides the global setting for that cluster only:

apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  provisioningTimeout: 3600  # 60 minutes
  # ... other fields

Verification Steps

1. Check the global value: kubectl get configmap rancher-system -n cattle-system -o yaml | grep CATTLE_CLUSTER_PROVISION_TIMEOUT
2. Inspect a specific cluster: kubectl get cluster <name> -o yaml | grep provisioningTimeout
3. Review Rancher Manager logs for lines containing agent registration timeout to confirm the active timeout.
4. Create a test cluster and measure the time from creation to Active or Failed to validate the effective timeout.

Cautions

• The default and configuration keys may differ between Rancher minor versions; consult the release notes for your exact version.
• An excessively long timeout delays detection of genuine agent connectivity problems (firewall, CA mismatch). An overly short timeout causes false failures in high‑latency environments.
• Per‑cluster settings only apply to clusters created after the spec is applied; they do not affect clusters already in Provisioning.

Need to confirm the exact Rancher version you are running? The default timeout and env‑var name are stable across 2.6+, but earlier 2.x releases used a different key.