How to Use This Reference
- Use Getting Started for the install sequence
- Use Tuning Guide for slow-cluster and degraded-environment tuning patterns
- Use this document to understand which values are required and which CRs Helm creates
- Use Policy Configuration for detailed strategy and scope examples
- See Multi-Policy Container Rightsizing for how container-scoped policies of the same kind contribute to a workload
- Use Cluster Automation Strategies and Cluster Proactive Policies for cluster-scoped CRD field references
Resources Created by This Chart
Core Components
Generated Custom Resources
Common CR status
Every Kubex custom resource exposes these status fields:
Proposal-managed resources map to
IN_PROGRESS while outcome is missing or stale, APPLIED for current Success, and FAILED for current Failure. Decode, validation, ownership, and Kubernetes apply errors report FAILED immediately.
CR outcome rules
Controllers evaluate the resource configuration, not the presence of work at the moment of reconciliation. A valid policy with no matching workloads, namespaces, nodes, or current action can still reportSuccess.
Notes
- Helm-managed policy generation creates
ClusterAutomationStrategyresources - Helm-managed scope generation creates
ClusterProactivePolicyresources AutomationStrategy,ProactivePolicy,StaticPolicy,ClusterStaticPolicy,PodAffinityPolicy,ContainerArgsPolicy,ClusterAutomationStrategy, andClusterProactivePolicycan all be managed manually outside HelmStaticPolicyandClusterStaticPolicyare supported by the controller, but this chart does not currently generate them from valuesPodAffinityPolicyis also managed outside Helm; see Policy Configuration for behavior details and the eviction-loop warning forspec.affinity.checkCurrentNodeSatisfiesAffinityContainerArgsPolicyis managed outside Helm; see Policy Configuration for argument operations, replacement behavior, and KAI precedence
Required Values
External Credential Secret
If you want to manage the Kubex credential secret outside Helm, disable Helm secret creation and point the gateway sidecar at a pre-created secret:gateway.configSecretName to reference the Secret name. This is the only chart value used to locate an externally managed gateway secret when createSecrets=false.
The Secret must:
- exist in the same namespace as the Helm release
- use the exact key names shown below
- keep the legacy
DENSIFY_BASE_URLkey because the current gateway image still expects it
kubex.url.host set in your values file so the release configuration still documents the target Kubex instance, even when the secret is managed outside Helm.
For non-TLS upstream endpoints, set kubex.url.scheme to http.
Note: kubexCredentials.userSecretName is currently not consumed by this chart. When createSecrets=false, set gateway.configSecretName instead.
Secondary/DR Cluster Mode
Secondary/DR mode is intended for active/passive disaster-recovery deployments where the passive cluster should follow the same sizing guidance as the active cluster. Use Secondary/DR mode only when:- the deployment consists of an active/passive cluster pair
- the passive cluster should consume the same sizing recommendations as the active cluster
- workloads in both clusters have the same topology, including namespaces, workload types, workload names, and container names
- the passive cluster is expected to apply recommendations locally, while the recommendations themselves are generated from the active cluster
secondaryCluster.enabled defaults to false. secondaryCluster.primaryClusterName is required when secondary mode is enabled.
Core Operational Values
Additional Early Pod Mutation
Most installations do not need the additional webhook and should leave it disabled. Enable it when another mutating webhook must see Kubex-updated resource requests or limits to make its admission decision. The early Kubex registration exposes those updates before other mutators run, while the normal late registration restores Kubex-selected resources if an intervening webhook changes them:additionalWebhook.namePrefix and the normal late registration uses namePrefix. Keep defaults 000- and zzz- for intended early and late placement. Both registrations call the same idempotent handler with failurePolicy: Ignore.
Webhook ordering is best-effort. Kubernetes does not define mutating webhook order as a stable API contract, so this setting must not be used when exact ordering is required. Enabling it roughly doubles Pod admission traffic, including dry-run health-probe Pods; size webhook capacity accordingly.
High Availability and Replica Scaling
Leader Election Behavior
The controller uses leader election by default (controllerManager.leaderElection.enabled=true), which ensures only one replica actively reconciles resources at any given time:
- Active reconciliation: Only the leader pod reconciles policy and workload resources, applies recommendations, and executes resource mutations
- Webhook load balancing: All replicas (leader and standby) serve admission webhook requests through the webhook Service, distributing webhook traffic across all pods
- Automatic failover: If the leader pod crashes, is evicted, or becomes unresponsive, another replica automatically acquires the leader lease and takes over reconciliation within the lease duration window (default 15 seconds)
- Coordination mechanism: Leader election uses
coordination.k8s.io/leasesresources in the controller namespace to coordinate active/standby roles
When to Increase Replicas
Consider increasingreplicaCount beyond the default of 1 in these scenarios:
1. High Availability Requirements
Recommended:replicaCount: 2
- Production clusters where automation must remain available during node maintenance, pod evictions, or rolling updates
- Environments with strict uptime SLAs where a brief reconciliation pause during controller restarts is unacceptable
- Clusters where the controller deployment may be subject to pod disruption budgets or preemption
2. High Webhook Request Volume
Recommended: Scale based on webhook latency and pod creation rate- Clusters with high pod creation rates where webhook request volume exceeds a single pod’s capacity
- Environments where webhook timeout errors appear under load (
webhook.timeoutSecondsdefault is 10 seconds) - Large clusters with frequent deployments, job executions, or autoscaling events that trigger many admission requests concurrently
- Monitor webhook latency via the controller
/metricsendpoint (default:8080/metrics) - Check controller logs for webhook timeouts or slow request warnings
- If webhook requests are queueing or timing out, increase replicas to distribute load
3. Zero-Downtime During Updates
Recommended:replicaCount: 2 minimum
- During Helm upgrades or image updates, multiple replicas ensure webhook availability remains uninterrupted while pods are being replaced
- Leader election allows standby replicas to immediately take over reconciliation when the active pod terminates
- Avoids admission webhook downtime that could block pod creation cluster-wide if the webhook
failurePolicyis set toFail
When NOT to Increase Replicas
Do not increase replicas to:- Speed up policy reconciliation (only one replica reconciles at a time due to leader election)
- Process more workloads in parallel (the leader election model serializes reconciliation)
- Reduce reconciliation latency (tune
--max-concurrent-reconcilesinstead; see below)
Scaling Alternatives for Reconciliation Throughput
If reconciliation throughput is insufficient with a single active leader:- Increase concurrent reconcilers: Set
controllerManager.extraArgs: ["--max-concurrent-reconciles=20"]to increase per-controller worker count (default is 10). This allows the leader to process more reconcile requests in parallel. - Tune API client rate limits: Adjust
--kube-api-qpsand--kube-api-burstviacontrollerManager.extraArgsif you observe client-side throttling in logs (messages like “Waited before sending request”). - Review policy scope: Broad selectors or frequent policy changes can create reconciliation bursts; prefer narrow selectors and explicit workload type filters in
scope[].podLabelsandpolicy.policies.<name>.allowedPodOwners.
Example: High-Availability Production Configuration
leaseDuration, renewDeadline, retryPeriod) and other performance settings, refer to the Tuning Guide and monitor your cluster’s behavior under load.
Monitoring Replica Health
When running multiple replicas, verify leader election and webhook distribution:OpenShift Notes
- Installing this chart still requires cluster-scoped permissions because it creates
ClusterRole,ClusterRoleBinding, and admission webhook resources - If you deploy on OpenShift, enable
openshift.enabled=trueto omit the controller’s fixed UID/GID defaults and apply restricted-friendly contexts to the cleanup job and controller-created scheduler/descheduler Pods - OpenShift mode is designed for the built-in
restricted-v2SCC and does not requireanyuidor a custom SCC; setopenshift.fsGrouponly when your storage class or cluster policy requires a fixed group imagePullSecretsare propagated to controller-created scheduler and descheduler Pods for mirrored or private registries- The OpenShift compatibility switch is opt-in so standard Kubernetes installs keep the existing defaults
Global Configuration Values
These render into the defaultGlobalConfiguration resource:
Use Global Configuration Reference for the CR field descriptions and behavior notes behind these values.
The probe uses dry-run Pod admission; no container runs. Probe security defaults come from the chart only. Partial security context values retain the other chart defaults, and explicit values override them. Directly managed
GlobalConfiguration resources must specify these controls themselves under spec.webhookProbe.
Webhook behavior notes:
- The pod mutating webhook is always fail-open. Pod creation continues if the webhook hits Kubernetes API communication errors or internal runtime errors; the effect is missed mutation rather than blocked admission.
- Validating webhooks are fail-open by default because
webhook.failurePolicydefaults toIgnore, but that behavior is configurable. - For operational tuning guidance around these behaviors, see Tuning Guide.
Helm-Managed Policy Values
policy
These values apply to Helm-managed recommendation-driven automation only. If you need namespaced policies, fixed-resource policies, or independently managed cluster policies, create those CRs separately and reference either
AutomationStrategy or ClusterAutomationStrategy as appropriate.
scope
For the generated resource fields behind these values, see Cluster Automation Strategies and Cluster Proactive Policies.
Backward-Compatible Values
The chart still reads selected legacy settings fromdeployment.controllerEnv:
See Advanced Configuration for migration guidance.

