This guide walks through installing the chart and validating the current CRD-based automation flow.

Quick Links

Getting Started with Kubex Automation Engine
Quick Links

Prerequisites

Before you begin, ensure you have:

Kubernetes 1.28+
Helm 3+
kubectl access to the target cluster
The kubex-crds chart installed in the target cluster before installing kubex-automation-engine
Kubex connection details from the Automation tab in the Kubex UI
A target workload that already has valid Kubex recommendations

Important:

Proactive rightsizing only works when a valid recommendation exists for the in-scope container
Recommendations are typically available about 24 hours after data collection starts

Step 1: Prepare Required Settings

Use the provided kubex-automation-values.yaml template as your starting point and update it with your environment-specific settings. At minimum, make sure these required fields are set:

kubex:
  url:
    host: your-instance.kubex.ai
  clusterName: my-cluster


kubexCredentials:
  username: your-username
  epassword: your-encrypted-password

If you already manage the Kubex credential secret externally, use this minimal configuration:

createSecrets: false

gateway:
  configSecretName: kubex-gateway-config

kubex:
  url:
    host: your-instance.kubex.ai
  clusterName: my-cluster

If this cluster is acting as a passive (DR) cluster, configure secondaryCluster so it follows recommendations from the active cluster.

secondaryCluster:
  enabled: true
  primaryClusterName: primary-cluster

Use this only for active/passive cluster pairs where both clusters run the same workloads with the same namespaces, workload names, workload types, and container names. If the passive cluster has different workloads or different naming, do not enable this mode. For more detail, see Secondary/DR Cluster Mode. Then create the referenced Secret in the same namespace as the Helm release using the exact keys username, epassword, url, and DENSIFY_BASE_URL. For the full Secret format, see External Credential Secret. If you are deploying on OpenShift, also set openshift.enabled: true in your values file to apply the chart’s restricted-friendly OpenShift defaults.

Step 2: Container Resource Sizing Guidance

Container resource requests and limits should be adjusted based on the number of managed containers in the cluster. Use these values as a starting point and tune them based on workload churn, recommendation volume, and webhook traffic.

Controller manager (`resources`)

Resource	Small (0-1K)	Medium (1K-10K)	Large (10K+)
CPU Request	25m	200m	400m
Memory Request	500Mi	2Gi	4Gi
Memory Limit	1Gi	4Gi	6Gi

Gateway sidecar (`gateway.resources`)

Resource	Small (0-1K)	Medium (1K-10K)	Large (10K+)
CPU Request	15m	15m	25m
Memory Request	40Mi	60Mi	90Mi
Memory Limit	250Mi	350Mi	500Mi

Sizing notes:

Small means up to 1,000 managed containers
Medium means 1,000 to 10,000 managed containers
Large means more than 10,000 managed containers
The chart currently exposes sizing controls for the controller manager and gateway sidecar; the older webhook and Valkey components do not apply to this chart
For slow API servers, webhook latency, restrictive admission environments, or placement resilience, continue with the Tuning Guide

Example values:

resources:
  requests:
    cpu: 200m
    memory: 2Gi
  limits:
    memory: 4Gi

gateway:
  resources:
    requests:
      cpu: 15m
      memory: 60Mi
    limits:
      memory: 350Mi

Step 3: Install the Helm Chart

Add the Kubex Helm repository on the machine where you run Helm:

helm repo add kubex https://densify-dev.github.io/helm-charts
helm repo update

Install the CRDs first:

helm install kubex-crds kubex/kubex-crds \
  --namespace kubex \
  --create-namespace

Then install the kubex-automation-engine:

helm install kubex-automation-engine kubex/kubex-automation-engine \
  --namespace kubex \
  --create-namespace \
  -f kubex-automation-values.yaml

Note: If you are migrating from the previous Kubex Automation Controller that used Helm values to manage automation configuration, see Migrating from Helm-Managed Configuration. For new installations, proceed to Step 4.

Step 4: Verify Controller Health

Check the deployment:

kubectl get pods -n kubex
kubectl get globalconfiguration global-config -o yaml

Confirm:

The controller pod is running
spec.automationEnabled is true
Review the full status block, not just status.conditions
status.conditions[type=PodAdmissionWebhookHealthy].status is True
Any additional status fields that report controller readiness, webhook health, last sync, or reconciliation errors reflect the expected healthy state for your environment

If webhook health is not ready, automation stays paused until probe success reaches the configured threshold.

Step 5: Create Your First Strategy and Policy

Strategy and policy CRs should be managed separately from the Helm chart using kubectl, GitOps, or another external delivery workflow. This approach keeps the chart focused on installing and operating the controller while allowing strategy and policy configurations to evolve independently of chart upgrades. For a detailed explanation of GitOps ownership and why pod-level resizing does not create drift in the original workload manifest, see GitOps Integration. The main CR patterns are:

AutomationStrategy / ClusterAutomationStrategy: define how resizing is allowed to happen, including enablement rules, in-place resize behavior, eviction fallback, and safety checks.
ProactivePolicy / ClusterProactivePolicy: define where recommendation-driven automation applies and which strategy to reference.
StaticPolicy / ClusterStaticPolicy: define where fixed request/limit values should be enforced and which strategy to reference.

Choose the scope based on ownership boundaries:

Use namespaced CRs when a team should manage automation within its own namespace.
Use cluster-scoped CRs when a platform team needs one policy model across many namespaces.

Start with these guides, each with field references and fuller examples:

Strategy configuration: Automation Strategies
Cluster-wide strategy configuration: Cluster Automation Strategies
Recommendation-driven policy configuration: Proactive Policies
Cluster-wide recommendation-driven policy configuration: Cluster Proactive Policies
Fixed-resource policy configuration: Static Policies
Strategy and policy model overview: Policy Configuration

A typical CR workflow looks like this:

Install or upgrade the controller with Helm (as done in Step 3).
Create one or more AutomationStrategy or ClusterAutomationStrategy objects for the resize behaviors you want.
Create ProactivePolicy, ClusterProactivePolicy, StaticPolicy, or ClusterStaticPolicy objects that reference those strategies.
Apply and reconcile those manifests through kubectl, GitOps, or another external workflow.

For a minimal start-to-finish example, use a cluster strategy that can resize requests and existing limits up or down, and a cluster proactive policy that targets a few namespaces:

apiVersion: rightsizing.kubex.ai/v1alpha1
kind: ClusterAutomationStrategy
metadata:
  name: getting-started-strategy
spec:
  enablement:
    cpu:
      requests:
        downsize: true
        upsize: true
        setFromUnspecified: true
      limits:
        downsize: true
        upsize: true
        setFromUnspecified: false
    memory:
      requests:
        downsize: true
        upsize: true
        setFromUnspecified: true
      limits:
        downsize: true
        upsize: true
        setFromUnspecified: false
---
apiVersion: rightsizing.kubex.ai/v1alpha1
kind: ClusterProactivePolicy
metadata:
  name: getting-started-apps
spec:
  scope:
    namespaceSelector:
      operator: In
      values:
        - team-a
        - team-b
        - staging
  automationStrategyRef:
    name: getting-started-strategy

Apply it with:

kubectl apply -f getting-started-policy.yaml
kubectl get clusterautomationstrategy getting-started-strategy
kubectl get clusterproactivepolicy getting-started-apps

The strategy can set requests when none are specified, but it only resizes limits that already exist. Add or remove values in the policy selector to change which namespaces it affects. This pattern lets you tune strategy behavior and policy scope independently from Helm upgrades.

Step 6: Validate Recommendation Application

Check policy objects:

kubectl get proactivepolicy,clusterproactivepolicy,staticpolicy,clusterstaticpolicy -A
kubectl get automationstrategy,clusterautomationstrategy -A
kubectl get events -A --field-selector reason=PrecheckFailed

Validate admission annotations on a new pod:

kubectl get pod <pod-name> -n <namespace> -o go-template='{{range $k,$v := .metadata.annotations}}{{printf "%s\n" $k}}{{end}}' | grep -E 'rightsizing\\.kubex\\.ai/|automation-webhook\\.kubex\\.ai/pod-rightsizing-info'

Validate pod events:

kubectl get events --sort-by=.lastTimestamp | grep -E 'PolicyEvaluation|ResizeCompleted'

Validate controller summary logs:

kubectl logs -n kubex -l control-plane=controller-manager -c manager --since=10m | grep 'rightsizing summary'

Look for results such as RESIZED, EVICTED, BLOCKED_RETRYING, or BLOCKED.

Apply Configuration Updates

Re-apply chart changes with:

helm upgrade --install kubex-automation-engine kubex/kubex-automation-engine \
  --namespace kubex \
  --create-namespace \
  -f charts/kubex-automation-engine/kubex-automation-values.yaml

Uninstall

Use this sequence when you want to remove the controller without leaving policy or strategy resources stuck in Terminating.

Remove externally managed CRs first

If you manage policies and strategies outside Helm, first request deletion of those CRs before uninstalling the chart so the running controller can process their cleanup logic. This matters most for ProactivePolicy and ClusterProactivePolicy resources. Deleting them while the controller is still running gives the controller a chance to remove Kubex annotations it previously placed on workloads.

kubectl delete proactivepolicy,clusterproactivepolicy,staticpolicy,clusterstaticpolicy -A --all
kubectl delete automationstrategy,clusterautomationstrategy -A --all

Wait for those resources to disappear before uninstalling Helm release:

kubectl get proactivepolicy,clusterproactivepolicy,staticpolicy,clusterstaticpolicy,automationstrategy,clusterautomationstrategy -A

Manually remove finalizers from external CRs only if deletion is stuck

The chart’s pre-delete hook removes finalizers from Helm-managed custom resources created by this release so helm uninstall can complete while the controller is shutting down. CRs managed outside Helm are not part of that hook. Do not clear finalizers before attempting deletion, because that can bypass controller cleanup. Only if a policy or strategy CR stays in Terminating after the delete step above should you manually clear its finalizers, and you should do that before helm uninstall:

for resource in \
  proactivepolicies \
  clusterproactivepolicies \
  staticpolicies \
  clusterstaticpolicies \
  automationstrategies \
  clusterautomationstrategies; do
  kubectl get "${resource}" --all-namespaces \
    -o 'go-template={{range .items}}{{.metadata.namespace}}{{"\t"}}{{.metadata.name}}{{"\n"}}{{end}}' | \
  while IFS=$(printf '\t') read -r namespace name; do
    [ -n "${name}" ] || continue
    if [ -n "${namespace}" ]; then
      kubectl patch "${resource}" "${name}" -n "${namespace}" --type=merge -p '{"metadata":{"finalizers":[]}}'
    else
      kubectl patch "${resource}" "${name}" --type=merge -p '{"metadata":{"finalizers":[]}}'
    fi
  done
done

Recheck until no policy or strategy CRs remain:

kubectl get proactivepolicy,clusterproactivepolicy,staticpolicy,clusterstaticpolicy,automationstrategy,clusterautomationstrategy -A

Uninstall the Helm releases

After external CR cleanup is complete, remove the controller chart:

helm uninstall kubex-automation-engine --namespace kubex

If you also want to remove the CRDs from the cluster, uninstall the CRD chart after all custom resources are gone:

helm uninstall kubex-crds --namespace kubex

Next Steps

Review Configuration Reference for Helm keys and generated CRs
Review Tuning Guide for slow-cluster tolerance, webhook fail-open expectations, and example values
Review Policy Configuration for strategy and scope design
Review Safety Controls for webhook health gating, pause controls, freshness checks, and execution-time safety filters
Review Rollback Policies to add health monitoring and automatic rollback for production deployments
Review Troubleshooting if rightsizing is selected but not applied
Use externally managed CRs for StaticPolicy and ClusterStaticPolicy until Helm-managed generation is added for those resource types

Getting Started

Kubernetes Optimization

Public Cloud Optimization

API Reference

Release Notes

Administration

Getting Started with Kubex Automation Engine

Quick Links

Prerequisites

Step 1: Prepare Required Settings

Step 2: Container Resource Sizing Guidance

Controller manager (`resources`)

Gateway sidecar (`gateway.resources`)

Step 3: Install the Helm Chart

Step 4: Verify Controller Health

Step 5: Create Your First Strategy and Policy

Step 6: Validate Recommendation Application

Apply Configuration Updates

Uninstall

Remove externally managed CRs first

Manually remove finalizers from external CRs only if deletion is stuck

Uninstall the Helm releases

Next Steps

​Quick Links

​Prerequisites

​Step 1: Prepare Required Settings

​Step 2: Container Resource Sizing Guidance

​Controller manager (resources)

​Gateway sidecar (gateway.resources)

​Step 3: Install the Helm Chart

​Step 4: Verify Controller Health

​Step 5: Create Your First Strategy and Policy

​Step 6: Validate Recommendation Application

​Apply Configuration Updates

​Uninstall

​Remove externally managed CRs first

​Manually remove finalizers from external CRs only if deletion is stuck

​Uninstall the Helm releases

​Next Steps

Quick Links

Prerequisites

Step 1: Prepare Required Settings

Step 2: Container Resource Sizing Guidance

Controller manager (`resources`)

Gateway sidecar (`gateway.resources`)

Step 3: Install the Helm Chart

Step 4: Verify Controller Health

Step 5: Create Your First Strategy and Policy

Step 6: Validate Recommendation Application

Apply Configuration Updates

Uninstall

Remove externally managed CRs first

Manually remove finalizers from external CRs only if deletion is stuck

Uninstall the Helm releases

Next Steps