Skip to content

Commit 31cfdab

Browse files
committed
add multi agent replicas info
1 parent 9f5eb56 commit 31cfdab

File tree

1 file changed

+24
-1
lines changed

1 file changed

+24
-1
lines changed

platform/configure/config.mdx

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -293,7 +293,7 @@ Even if you disable automatic deployment, the platform agent is still required i
293293

294294
### Install the agent manually {#manual-agent-installation}
295295

296-
To manually install the platform agent:
296+
Use the following command to manually install the platform agent from Helm releases:
297297

298298
```bash title="Manual agent installation"
299299
RELEASE_NAME=vcluster-platform
@@ -308,6 +308,29 @@ helm upgrade $RELEASE_NAME vcluster-platform \
308308
--set agentOnly=true \
309309
${PLATFORM_VERSION:+--version $PLATFORM_VERSION}
310310
```
311+
### Multiple agent replicas deployment
312+
313+
For high availability and scalability, the platform agent can be deployed with multiple replicas. However, certain agent tasks must be executed by only one pod
314+
at a time to prevent duplicate actions, race conditions, or data corruption. Other tasks, such as concurrent background processing, can safely run in parallel
315+
across replicas.
316+
317+
#### Leader election
318+
319+
Before scaling the platform agent beyond a single replica, you must enable leader election. This ensures that only one pod performs “singleton” tasks while
320+
others act as standby or worker agents. Without leader election, multiple pods may perform the same critical operation, leading to inconsistent or
321+
conflicting results.
322+
323+
#### Recommended operational practices
324+
- Enable leader election prior to scaling the agent above one replica.
325+
- For sensitive operations (e.g., storage migrations or major version upgrades), temporarily scale the agent to a single replica, complete and validate the operation, then scale back up with leader election enabled.
326+
327+
The agent is deployed and managed as a Helm release when the platform connects to a cluster. Configure replicas and leader election settings through Helm values,
328+
not manual scaling, to ensure consistent configuration and reliable leader election.
329+
330+
:::warning Avoid manual scaling of agent replicas
331+
Do not manually scale Deployment replicas outside of Helm. Doing so can start extra pods without the expected flags or config, resulting in no leader
332+
being elected, race conditions, or duplicate execution of singleton activities.
333+
:::
311334

312335
## Configure the agent {#agent-configuration}
313336

0 commit comments

Comments
 (0)