> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Kubex Automation Engine

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

# Quick Links

* [Getting Started with Kubex Automation Engine](#getting-started-with-kubex-automation-engine)
* [Quick Links](#quick-links)
  * [Prerequisites](#prerequisites)
  * [Step 1: Prepare Required Settings](#step-1-prepare-required-settings)
  * [Step 2: Container Resource Sizing Guidance](#step-2-container-resource-sizing-guidance)
    * [Controller manager (`resources`)](#controller-manager-resources)
    * [Gateway sidecar (`gateway.resources`)](#gateway-sidecar-gatewayresources)
  * [Step 3: Install the Helm Chart](#step-3-install-the-helm-chart)
  * [Step 4: Verify Controller Health](#step-4-verify-controller-health)
  * [Step 5: Create Your First Strategy and Policy](#step-5-create-your-first-strategy-and-policy)
  * [GitOps Integration](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/gitops-integration.md)
  * [Step 6: Validate Recommendation Application](#step-6-validate-recommendation-application)
  * [Apply Configuration Updates](#apply-configuration-updates)
  * [Uninstall](#uninstall)
    * [Remove externally managed CRs first](#remove-externally-managed-crs-first)
    * [Manually remove finalizers from external CRs only if deletion is stuck](#manually-remove-finalizers-from-external-crs-only-if-deletion-is-stuck)
    * [Uninstall the Helm releases](#uninstall-the-helm-releases)
  * [Next Steps](#next-steps)

***

## Prerequisites

Before you begin, ensure you have:

* Kubernetes 1.28+
* Helm 3+
* `kubectl` access to the target cluster
* The [`kubex-crds` chart](https://github.com/densify-dev/helm-charts/tree/master/charts/kubex-crds) 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](https://github.com/densify-dev/helm-charts/blob/master/charts/kubex-automation-engine/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:

```yaml theme={null}
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:

```yaml theme={null}
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.

```yaml theme={null}
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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/configuration-reference.md#secondarydr-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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/configuration-reference.md#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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/tuning-guide.md)

Example values:

```yaml theme={null}
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:

```bash theme={null}
helm repo add kubex https://densify-dev.github.io/helm-charts
helm repo update
```

Install the CRDs first:

```bash theme={null}
helm install kubex-crds kubex/kubex-crds \
  --namespace kubex \
  --create-namespace
```

Then install the kubex-automation-engine:

```bash theme={null}
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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/migrating-from-helm-managed-config.md). For new installations, proceed to Step 4.

## Step 4: Verify Controller Health

Check the deployment:

```bash theme={null}
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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/gitops-integration.md).

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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/automation-strategies.md)
* Cluster-wide strategy configuration: [Cluster Automation Strategies](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/cluster-automation-strategies.md)
* Recommendation-driven policy configuration: [Proactive Policies](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/proactive-policies.md)
* Cluster-wide recommendation-driven policy configuration: [Cluster Proactive Policies](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/cluster-proactive-policies.md)
* Fixed-resource policy configuration: [Static Policies](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/static-policies.md)
* Strategy and policy model overview: [Policy Configuration](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/policy-configuration.md)

A typical CR workflow looks like this:

1. Install or upgrade the controller with Helm (as done in Step 3).
2. Create one or more `AutomationStrategy` or `ClusterAutomationStrategy` objects for the resize behaviors you want.
3. Create `ProactivePolicy`, `ClusterProactivePolicy`, `StaticPolicy`, or `ClusterStaticPolicy` objects that reference those strategies.
4. 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:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
kubectl get events --sort-by=.lastTimestamp | grep -E 'PolicyEvaluation|ResizeCompleted'
```

Validate controller summary logs:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
kubectl delete proactivepolicy,clusterproactivepolicy,staticpolicy,clusterstaticpolicy -A --all
kubectl delete automationstrategy,clusterautomationstrategy -A --all
```

Wait for those resources to disappear before uninstalling Helm release:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
kubectl get proactivepolicy,clusterproactivepolicy,staticpolicy,clusterstaticpolicy,automationstrategy,clusterautomationstrategy -A
```

### Uninstall the Helm releases

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

```bash theme={null}
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:

```bash theme={null}
helm uninstall kubex-crds --namespace kubex
```

## Next Steps

* Review [Configuration Reference](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/configuration-reference.md) for Helm keys and generated CRs
* Review [Tuning Guide](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/tuning-guide.md) for slow-cluster tolerance, webhook fail-open expectations, and example values
* Review [Policy Configuration](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/policy-configuration.md) for strategy and scope design
* Review [Safety Controls](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/safety-controls.md) for webhook health gating, pause controls, freshness checks, and execution-time safety filters
* Review [Rollback Policies](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/rollback-policies.md) to add health monitoring and automatic rollback for production deployments
* Review [Troubleshooting](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/troubleshooting.md) 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.