Skip to main content
This document maps the current Helm chart values to the resources created by the chart and to the CRD-based runtime model.

How to Use This Reference


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 report Success.

Notes

  • Helm-managed policy generation creates ClusterAutomationStrategy resources
  • Helm-managed scope generation creates ClusterProactivePolicy resources
  • AutomationStrategy, ProactivePolicy, StaticPolicy, ClusterStaticPolicy, PodAffinityPolicy, ContainerArgsPolicy, ClusterAutomationStrategy, and ClusterProactivePolicy can all be managed manually outside Helm
  • StaticPolicy and ClusterStaticPolicy are supported by the controller, but this chart does not currently generate them from values
  • PodAffinityPolicy is also managed outside Helm; see Policy Configuration for behavior details and the eviction-loop warning for spec.affinity.checkCurrentNodeSatisfiesAffinity
  • ContainerArgsPolicy is 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:
Use 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_URL key because the current gateway image still expects it
Example:
Keep 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
Do not use Secondary/DR mode when the two clusters are managing different workloads, use different naming, or have drifted topology. In those cases, the passive cluster should run with its own recommendations instead. Use these values to enable the feature:
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:
The early registration uses 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/leases resources in the controller namespace to coordinate active/standby roles

When to Increase Replicas

Consider increasing replicaCount 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
Trade-off: Additional memory and CPU overhead for standby replicas that are not actively reconciling.

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.timeoutSeconds default is 10 seconds)
  • Large clusters with frequent deployments, job executions, or autoscaling events that trigger many admission requests concurrently
How to evaluate:
  • Monitor webhook latency via the controller /metrics endpoint (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
Trade-off: Webhook requests are distributed across all replicas, so scaling provides linear improvements in webhook throughput.

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 failurePolicy is set to Fail

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-reconciles instead; 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-qps and --kube-api-burst via controllerManager.extraArgs if 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[].podLabels and policy.policies.<name>.allowedPodOwners.

Example: High-Availability Production Configuration

For tuning leader election parameters (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=true to 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-v2 SCC and does not require anyuid or a custom SCC; set openshift.fsGroup only when your storage class or cluster policy requires a fixed group
  • imagePullSecrets are 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 default GlobalConfiguration 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.failurePolicy defaults to Ignore, 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 from deployment.controllerEnv: See Advanced Configuration for migration guidance.