Installation
This document provides a guide to help you install the CloudPilot AI Workload Autoscaler component.
You can view the list of permissions required by the Workload Autoscaler component through this link: Workload Autoscaler Permissions
Installation
Workload Autoscaler will automatically deploy the cloudpilot-node-agent and cloudpilot-victoria-metrics components during installation.
cloudpilot-node-agent is a DaemonSet. It analyzes and collects runtime data for all containers on each node via eBPF, including (but not limited to) RuntimeLanguage and Application Type.
The standalone installation command generated by the Console includes
export ENABLE_NODE_AGENT=true. To disable the cloudpilot-node-agent component
before deployment, change that assignment in the copied command to:
export ENABLE_NODE_AGENT=falseAn earlier export, including one in Pre Run, is overwritten if the installation command still sets this variable to true.
cloudpilot-victoria-metrics is responsible for storing all collected data. The primary data sources include (but are not limited to) metrics from KubeStateMetrics and cloudpilot-node-agent.

By default, the Workload Autoscaler will automatically calculate recommendations for certain workloads but will not apply updates.
Once the deployment is complete, you can configure an AutoscalingPolicy and RecommendationPolicy to update strategies and adjust workload recommendations.
Workload Group and CronJob setup
Workload Group and CronJob support requires CloudPilot v1.23.0 and later. Install the target release’s matching WA components, CRDs, Kubernetes permissions and membership metrics collection. An automatic image upgrade does not install missing CRDs or permissions; rerun the target release’s WA installer and verify prerequisites.
Custom Helm Values
For WA component tolerations and NodeAgent placement, export
CLOUDPILOT_WA_HELM_VALUES in Settings > Advanced Options > Pre Run Command
before running a supporting installation or manual-upgrade command. You can also
export it directly in the command environment; Universal cluster Settings do not
currently expose the Pre Run editor.
Using saved Pre Run settings for standalone WA installation requires server support for prepending them to the command. That path executes Pre Run only, without Post Run. With an older server, export the YAML directly in the terminal before running the generated command.
See Workload Autoscaler Helm values
for the complete version-specific reference, four independent toleration paths,
Azure Spot examples, and storage/NodeAgent argument precedence. The NA input
CLOUDPILOT_NA_HELM_VALUES does not configure WA. Empty inputs keep target defaults
and existing installer settings; partial maps merge, while lists replace.
Upgrade and Uninstall
The Workload Autoscaler component is upgraded together with the CloudPilot AI version—you do not need to upgrade it separately.
The first HPA-aware release requires the matching APC CRD and a Helm/manual upgrade that adds controller get/list access to HPAs and core limitranges. Image-only or CRD-only upgrades do not deliver these ClusterRole permissions. LimitRange reads resolve missing protected resource defaults in the workload namespace; failed or ambiguous reads hold restoration. Install the release’s CRDs explicitly because Helm does not upgrade existing CRDs from a chart’s crds/ directory.
Similarly, the Workload Autoscaler component is uninstalled together with the CloudPilot AI. If you need to uninstall the Workload Autoscaler component independently, please contact our technical support team for assistance.
Note: Before uninstalling the Workload Autoscaler, please make sure that all AutoscalingPolicies have been deleted or disabled, and confirm that all Workloads have been restored to their original state.
Configure the Update/Evict Limiter
By default, the Workload Autoscaler enables a Limiter that throttles the number of in-place updates and Pod evictions. This helps prevent large clusters from becoming unstable when many Pods are updated or evicted in a short period.
You can tune the Limiter with the environment variables below. If not set, the defaults apply.
| ENV var | Default | What it controls |
|---|---|---|
LIMITER_QUOTA_PER_WINDOW | 5 | Tokens added to the bucket each window. |
LIMITER_BURST | 10 | Maximum tokens allowed in the bucket (peak operations within a window). |
LIMITER_WINDOW_SECONDS | 30 | Window length in seconds; every window adds LIMITER_QUOTA_PER_WINDOW tokens. |
Note: For eviction operations, when attempting to evict a single-replica Deployment without PVCs, we perform a rolling update to avoid service interruption during the update.
New Workloads Proactive Update
The New Workloads Proactive Update setting is a cluster-level configuration that can be enabled through the CloudPilot AI Console (Settings page). When enabled, newly onboarded workloads will automatically have proactive update enabled once their recommendations are ready — eliminating the need to manually enable proactive updates for each workload.
How It Works
- An administrator enables New Workloads Proactive Update on the Console Settings page.
- The system records the timestamp when this setting was turned on.
- A background controller periodically scans for new workloads created after the enablement timestamp.
- For each eligible workload (has ready recommendations, no user override disabling proactive update, not yet auto-optimized), the controller automatically enables proactive update.
Key Behaviors
- Only affects new workloads: Workloads that existed before the setting was enabled are not affected. Use the bulk proactive update action on the Console Workloads page to enable proactive update for existing workloads.
- Respects user overrides: If a workload has the
evpa.cloudpilot.ai/disable-proactive-update: "true"annotation, the auto-optimize controller will not override it. - Timestamp-based: If you disable and re-enable this setting, only workloads created after the latest enablement time are eligible.
Note: This setting is configured exclusively through the CloudPilot AI Console Settings page and is not available as an environment variable or CRD field.
Configure Preempted Pod GC
The Workload Autoscaler can optionally garbage-collect preempted Pods after a configurable TTL. This is useful for clusters where preempted Pods linger and consume resources.
| ENV var | Default | What it controls |
|---|---|---|
ENABLE_PREEMPTED_POD_GC | false | Enables the Preempted Pod GC controller. |
PREEMPTED_POD_GC_TTL | — | TTL duration after which preempted Pods are deleted. |
Service Readiness
The Workload Autoscaler reports ready only after its cache is synchronized and its TLS admission webhook is serving. Liveness remains separate, so waiting for initial certificates does not create a restart loop. The certificate Job is created with the release resources, allowing both first installation and helm --wait upgrades to complete without a post-install hook waiting cycle.