@@ -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"
299299RELEASE_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