---
title: "Apply MDA optimization with YAML"
slug: "apply-mda-optimization-with-yaml"
updated: 2026-07-19T13:03:14Z
published: 2026-07-19T13:03:14Z
canonical: "docs.zesty.co/apply-mda-optimization-with-yaml"
---

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

# Apply MDA optimization with YAML

This section describes how to apply and manage optimization policies from the cluster using YAML.

Policies are configured declaratively using Kubernetes Policy custom resources (CRs). A policy defines optimization behavior and how the policy selects workloads.

Policies select workloads using an appList selector, label selectors, or a policy annotation on the workload.

Each workload can be managed by at most one Pod rightsizing and one Replica optimization policy at a time. When multiple policies of the same type match the same workload, precedence rules determine which policy manages it.

If no policy manages a workload, optimization is not applied to it.

#### Workflow description

Use the following workflow to apply Pod rightsizing from the cluster:

1. [Select a policy](/v1/docs/apply-mda-optimization-with-yaml#step-1-select-a-policy).
2. [Define workload selection](/v1/docs/apply-mda-optimization-with-yaml#step-2-define-workload-selection).

> [!NOTE]
> No Policy resources?
> 
> If your cluster does not show Policy resources, rather APC and JPC resources, you are running an older version of the Insights agent. See [Deprecated Pod rightsizing topics](/v1/docs/deprecated-pod-rightsizing-topics).

## Step 1. Select a policy

Kompass provides built-in policies, and you can also [create custom policies](/v1/docs/custom-policies#create-a-custom-policy1).

### Pod rightsizing policies

The following sections describe the Pod rightsizing policy parameters, built-in policy values, and Pod rightsizing-specific capabilities.

#### Pod rightsizing policy resource structure

**Policy structure, sample, and parameter reference**

Pod rightsizing behavior is configured through policy resources.

Each policy must include a complete set of configuration parameters. Policies do not inherit values from cluster-level defaults.

#### Pod rightsizing configuration sample

Values inside `[ ]` are user-specified placeholders.

```yaml
apiVersion: rightsizing.kompass.zesty.co/v1alpha1
kind: Policy
metadata:
  # [string] Unique name identifier for this policy instance.
  name: balanced
spec:
  # [integer] Policy priority. If a workload matches multiple policies,
  # the policy with the lower numeric value has higher priority.
  priority: 0

  # [string] Human-readable description explaining the operational
  # target and behavior of this policy.
  description: "Balances cost and stability for general workloads by using moderate buffers and stable recommendations."

  # [array] Explicit list of workloads managed by this policy.
  # Leave empty to select workloads using appSelector.
  appList: []

  # [object] Selects workloads managed by this policy based on workload
  # labels and namespaces.
  appSelector:
    labels:
      matchLabels: {}
      matchExpressions: []
    namespaces:
      operator: Include
      values: []

  # [string] Period of historical workload metrics that Kompass uses to
  # generate recommendations.
  lookbackPeriod: "24h"

  # [string] Minimum time between consecutive rightsizing changes to the
  # same workload. Longer periods promote greater stability.
  cooldownPeriod: "2h"

  # [integer] Minimum percentage of the lookback period for which metrics
  # must be available before Kompass generates a Pod rightsizing recommendation.
  dataCoveragePercentage: 80

  # CPU resource tuning and optimization settings.
  cpu:
    # [string] Specifies how CPU usage samples are aggregated over the
    # lookback period when generating recommendations.
    optimizationStrategy: "p95"

    # [string] Specifies how CPU usage is aggregated across Pod replicas
    # for each sample.
    replicaAggregationMethod: "max"

    # [integer] Percentage added to the recommended CPU request as a
    # safety buffer.
    bufferPercentage: 20

    # [integer] Minimum percentage difference between the current and
    # recommended CPU requests required for Kompass to apply a change.
    minimumImpactPercentage: 10

    # [string] Minimum increase in CPU request that Kompass can apply in
    # a scale-up change.
    minimumStepForScaleUp: 100m

    # [string] Minimum CPU request that Kompass can set in a scale-down
    # change.
    minimumValueForScaleDown: 10m

    # [boolean] Specifies whether CPU throttling events are ignored when
    # evaluating rollback of a rightsizing change.
    ignoreThrottlingEvent: false

  # Memory resource tuning and optimization settings.
  memory:
    # [string] Specifies how memory usage samples are aggregated over the
    # lookback period when generating recommendations.
    optimizationStrategy: "p99"

    # [string] Specifies how memory usage is aggregated across Pod replicas
    # for each sample.
    replicaAggregationMethod: "max"

    # [integer] Percentage added to the recommended memory request as a
    # safety buffer.
    bufferPercentage: 30

    # [integer] Minimum percentage difference between the current and
    # recommended memory requests required for Kompass to apply a change.
    minimumImpactPercentage: 10

    # [string] Minimum increase in memory request that Kompass can apply
    # in a scale-up change.
    minimumStepForScaleUp: 256Mi

    # [string] Minimum memory request that Kompass can set in a scale-down
    # change.
    minimumValueForScaleDown: 256Mi

    # [boolean] Specifies whether out-of-memory events are ignored when
    # evaluating rollback of a rightsizing change.
    ignoreOomEvent: false

  # [boolean] Specifies whether in-place resource updates are preferred
  # when supported. In-place updates require Kubernetes 1.33 or later.
  preferInPlace: true

  # [boolean] Specifies whether to evict a Pod when an in-place rightsizing
  # action results in Deferred status.
  evictPodsInDeferredState: true
```

#### **Pod rightsizing policy parameters reference**

All parameters are validated when a policy is created or updated. Policies with missing or invalid parameters cannot be applied.

| **Parameter** | **Description** | **Value** |
| --- | --- | --- |
| `spec.priority` | Policy priority. If a workload matches multiple policies, the policy with the lower numeric value has higher priority. | Integer (priority values start at `0`) |
| `spec.appList` | Explicit list of workloads managed by this policy. | List of workload references |
| `spec.appSelector.labels` | Label selector used to select workloads managed by this policy. | Label selector |
| `spec.appSelector.namespaces.operator` | Specifies whether the namespaces in `spec.appSelector.namespaces.values` are included in or excluded from workload selection. | `Include` \| `Exclude` |
| `spec.appSelector.namespaces.values` | Namespaces to include in or exclude from workload selection. | List of strings |
| `spec.lookbackPeriod` | Period of historical workload metrics that Kompass uses to generate recommendations. | Duration, for example, `1d`, `12h`, or `5m` |
| `spec.cooldownPeriod` | Minimum time between consecutive rightsizing changes to the same workload. Longer periods promote greater stability. | Duration, for example, `2h`, `30m`, or `0s` |
| `spec.dataCoveragePercentage` | Minimum percentage of the lookback period for which metrics must be available before Kompass generates a Pod rightsizing recommendation. | Percentage (integer `0–100`) |
| `spec.cpu.optimizationStrategy` | Specifies how CPU usage samples are aggregated over the lookback period when generating recommendations. | `p85` \| `p95` \| `max` |
| `spec.cpu.replicaAggregationMethod` | Specifies how CPU usage is aggregated across Pod replicas for each sample. You can configure custom methods. For more information, see the “Define custom replica aggregation method values” section after this table. | `p85` \| `p95` \| `max` \| `custom1` \| `custom2` |
| `spec.cpu.bufferPercentage` | Percentage added to the recommended CPU request as a safety buffer. | Percentage (integer `0–100`) |
| `spec.cpu.minimumImpactPercentage` | Minimum percentage difference between the current and recommended CPU requests required for Kompass to apply a change. Higher values increase stability but may reduce optimization effectiveness. | Percentage (integer `0–100`) |
| `spec.cpu.minimumStepForScaleUp` | Minimum increase in CPU request that Kompass can apply in a scale-up change. | CPU quantity, for example, `100m` |
| `spec.cpu.minimumValueForScaleDown` | Minimum CPU request that Kompass can set in a scale-down change. | CPU quantity, for example, `10m` |
| `spec.cpu.ignoreThrottlingEvent` | Specifies whether CPU throttling events are ignored when evaluating rollback of a rightsizing change. | `true` \| `false` |
| `spec.memory.optimizationStrategy` | Specifies how memory usage samples are aggregated over the lookback period when generating recommendations. | `p95` \| `p99` \| `max` |
| `spec.memory.replicaAggregationMethod` | Specifies how memory usage is aggregated across Pod replicas for each sample. You can configure custom methods. For more information, see the “Define custom replica aggregation method values” section after this table. | `p95` \| `p99` \| `max` \| `custom1` \| `custom2` |
| `spec.memory.bufferPercentage` | Percentage added to the recommended memory request as a safety buffer. | Percentage (integer `0–100`) |
| `spec.memory.minimumImpactPercentage` | Minimum percentage difference between the current and recommended memory requests required for Kompass to apply a change. Higher values increase stability but may reduce optimization effectiveness. | Percentage (integer `0–100`) |
| `spec.memory.minimumStepForScaleUp` | Minimum increase in memory request that Kompass can apply in a scale-up change. | Memory quantity, for example, `256Mi` |
| `spec.memory.minimumValueForScaleDown` | Minimum memory request that Kompass can set in a scale-down change. | Memory quantity, for example, `256Mi` |
| `spec.memory.ignoreOomEvent` | Specifies whether out-of-memory (OOM) events are ignored when evaluating rollback of a rightsizing change. | `true` \| `false` |
| `spec.preferInPlace` | Specifies whether in-place resource updates are preferred when supported. In-place updates require Kubernetes `1.33` or later. | `true` \| `false` |
| `spec.evictPodsInDeferredState` | Specifies whether to evict a Pod when an in-place rightsizing action results in `Deferred` status. | `true` \| `false` |
| `spec.startupBoost.cpu.multiplier` | Value by which the CPU request is multiplied during the startup boost. **Note**: this parameter is not part of a built-in policy. Add it for Startup boost, as described in [Startup boost](/v1/docs/apply-mda-optimization-with-yaml#pod-rightsizing-policy-advanced-capabilities). | Decimal, minimum value: `1` |
| `spec.startupBoost.duration` | Length of time the startup boost is applied after a Pod is created or a container is restarted. **Note**: this parameter is not part of a built-in policy. Add it for Startup boost, as described in [Startup boost](/v1/docs/apply-mda-optimization-with-yaml#pod-rightsizing-policy-advanced-capabilities). | Duration, for example, `2m`, `5m`, or `10m` |
| `spec.startupBoost.memory.multiplier` | Value by which the memory request is multiplied during the startup boost. **Note**: this parameter is not part of a built-in policy. Add it for Startup boost, as described in [Startup boost](/v1/docs/apply-mda-optimization-with-yaml#pod-rightsizing-policy-advanced-capabilities). | Decimal, minimum value: `1` |

#### Define custom replica aggregation method values

You can define custom values for the CPU and memory replica aggregation method. This can be useful if the fixed values are overly aggressive.

To define custom aggregation method figures, you define values for `custom1 `and `custom2 `in Helm **values.yaml**, then define the value in the policy configuration as `custom value 1 `or **custom value 2**.

**To define custom values**:

1. Add the custom definition to Helm **values.yaml**:

```yaml
rightsizing:
  config:
    customReplicaAggregationMethods:
      cpu:
        custom1: 70
        custom2: 71
      memory:
        custom1: 80
        custom2: 81
```

Note that both CPU and memory are in the same section.
2. In the policy on the cluster, change the value to the desired value.

For example, to set the memory value to 80, change the value in the policy `spec.memory.replicaAggregationMethod` to `custom value 1`.

#### Built-in Pod rightsizing policy fixed parameter values

**Built-in policy fixed parameter values**

The following table shows the fixed parameter values in the Pod rightsizing built-in policies:

| **Parameter hierarchy** | **Balanced** | **Stability-focused** | **Cost-focused** |
| --- | --- | --- | --- |
| `spec:` |  |  |  |
| ` cooldownPeriod` | 2h | 2h | 2h |
| ` cpu:` |  |  |  |
| ` bufferPercentage` | 20 | 30 | 5 |
| ` ignoreThrottlingEvent` | false | false | false |
| ` minimumImpactPercentage` | 10 | 10 | 0 |
| ` minimumStepForScaleUp` | 100m | 100m | 100m |
| ` minimumValueForScaleDown` | 10m | 10m | 10m |
| ` optimizationStrategy` | p95 | max | p85 |
| ` replicaAggregationMethod` | max | max | p85 |
| ` dataCoveragePercentage` | 80 | 90 | 50 |
| ` evictPodsInDeferredState` | true | true | true |
| ` lookbackPeriod` | 24h | 24h | 12h |
| ` memory:` |  |  |  |
| ` bufferPercentage` | 30 | 40 | 10 |
| ` ignoreOomEvent` | false | false | false |
| ` minimumImpactPercentage` | 10 | 10 | 0 |
| ` minimumStepForScaleUp` | 256Mi | 256Mi | 64Mi |
| ` minimumValueForScaleDown` | 256Mi | 256Mi | 64Mi |
| ` optimizationStrategy` | p99 | max | p95 |
| ` replicaAggregationMethod` | max | max | p95 |
| ` preferInPlace` | true | true | true |
| ` priority` | 0 | 1 | 2 |

You cannot delete or change built-in policies parameters.

To create a custom policy, see [Create a custom policy](/v1/docs/custom-policies#create-a-custom-policy1).

#### Pod rightsizing policy advanced capabilities

To have full control of policy parameters, you can create a **custom policy**. With custom policies you can also take advantage of the following:

- Boost startup resources to temporarily increase resources during Pod initialization.
- Select whether to right-size only CPU or only memory resources, not both.

**Advanced capabilities**

#### Boost startup resources

Some workloads require higher CPU or memory during initialization than during normal operation. To accommodate this, you would need to manually assign extra resources for startup (to prevent OOM or throttling) and then to reduce those assignments for ongoing operation.

With Pod rightsizing and Startup boost, you can temporarily increase CPU and memory resources for new Pods during initialization. After a configured duration, the resources automatically revert to initial values and then Pod rightsizing is applied.

With Startup boost:

- Startup-related spikes are excluded from the steady state recommendation logic.
- Steady-state requests are aligned with actual runtime usage.

You apply Startup boost to a workload by adding `startupBoost` to a custom Pod rightsizing policy that manages the workload.

```yaml
spec:
   startupBoost:
 	duration: 5m
 	cpu:
   	  multiplier: 1.5
 	memory:
   	  multiplier: 3
```

**Startup boost limitations and considerations**

- Applies to all containers in a Pod.
- Requires in-place Pod mutation support.
- Cannot be used if `preferInPlace: false`
- If a Pod needs to be evicted to a different node due to insufficient node capacity, it will be evicted even if the policy includes: `spec.evictPodsInDeferredState = false`

To create a custom policy, see [Create a custom policy](/v1/docs/custom-policies#create-a-custom-policy1).

#### Selective Pod rightsizing

There may be cases where you want to manually manage workload memory resources while allowing Pod rightsizing to manage **CPU** resources, or vice versa.

For example, you may want separate control for memory-critical or CPU-critical applications (such as Java applications), or for testing purposes.

With **Selective Pod rightsizing**, you can apply Pod rightsizing to only one resource while manually managing the other resource.

To use Selective Pod rightsizing, create a custom policy and remove the entire configuration block for the resource that you want to manage manually.

To create or edit a custom policy, see [Create a custom policy](/v1/docs/custom-policies#create-a-custom-policy1).

For example, to apply Pod rightsizing only to CPU resources, remove the entire memory section from the policy:

```yaml
memory:
  bufferPercentage: 40
  ignoreOomEvent: false
  minimumImpactPercentage: 10
  minimumStepForScaleUp: 256Mi
  minimumValueForScaleDown: 256Mi
  optimizationStrategy: max
  replicaAggregationMethod: max
```

### Replica optimization policies

The following sections describe the Replica optimization policy parameters and built-in policy values.

#### Replica optimization policy resource structure

The Replica optimization policy is dependent on the Pod rightsizing policy.

**Policy **dependency**, structure, sample, and parameter reference**

Replica optimization behavior is configured through policy resources.

Each policy must include a complete set of configuration parameters. Policies do not inherit values from cluster-level defaults.

Replica optimization can be applied only to workloads that are already managed by a **Pod rightsizing policy**.

If a Replica optimization policy matches a workload that is not managed by a Pod rightsizing policy, the Replica optimization policy is **not** applied to that workload. The policy remains valid and no validation error is generated.

When a workload is managed by both a Pod rightsizing policy and a Replica optimization policy, the workload operates in MDA mode.

#### Replica optimization configuration sample

Values inside [ ] are user-specified placeholders.

This sample is for the Balanced, built-in policy.

```yaml
apiVersion: horizontalscaling.kompass.zesty.co/v1alpha1
kind: Policy
metadata:
  name: balanced
spec:
  # Replica optimization does not reduce minimum replicas below this value.
  absoluteMinimumReplicas: 2
  appSelector:
    labels: {}
    namespaces:
      operator: Include
      values: []
  description: Balanced setup with stable recommendations for production environments.
  # Lower values have higher priority.
  priority: 0
```

### Replica optimization policy parameters reference

All parameters are validated when the policy is created or updated.

| **Parameter** | **Description** | **Value** |
| --- | --- | --- |
| `spec.priority` | Policy priority. If a workload matches multiple Replica optimization policies, the policy with the lower numeric value has higher priority. | Integer (priority values start at 0) |
| `spec.appList` | Explicit list of workloads to manage with this policy. | List of workload references |
| `spec.appSelector.labels` | Label selector used to select workloads managed by this policy. | Label selector |
| `spec.appSelector.namespaces.operator` | Specifies whether to include or exclude the namespaces listed in `spec.appSelector.namespaces.values`. | Include \| Exclude |
| `spec.appSelector.namespaces.values` | Namespaces to include in or exclude from workload selection. | List of strings |
| `spec.absoluteMinimumReplicas` | Lowest minimum replica count that Replica optimization can apply to a workload. Replica optimization does not reduce a workload’s minimum replicas below this value. | Integer, minimum value: `1` |

### 

#### Built-in Replica optimization policy fixed parameter values

**Built-in policy fixed parameter values**

The following table shows the fixed parameter values in the Replica optimization built-in policies:

| **Parameter hierarchy** | **Balanced** | **Stability- focused** | **Cost- focused** |
| --- | --- | --- | --- |
| `spec:` |  |  |  |
| `  absoluteMinimumReplicas` | 2 | 3 | 1 |
| ` priority` | 0 | 1 | 2 |

You cannot delete or change built-in policies parameters.

To create a custom policy, see [Create a custom policy](/v1/docs/custom-policies#create-a-custom-policy1).

## Step 2. Define workload selection

You define which workloads a policy matches using selector fields in the policy and a policy annotation on the workload.

**Workload selection options**

**In-policy selection (configured in the policy):**

- **appList** — explicitly match specific workloads by kind, name, and namespace
- **appSelector.labels** — match workloads dynamically based on Kubernetes labels
- **appSelector.namespaces** — filter the label-matched workloads by namespace

**Workload-side matching (configured on the workload)**

- **Policy annotation** — explicitly match a workload to a policy by referencing the policy name in an annotation

When multiple selection mechanisms apply to the same workload, optimization policies use priority and conflict resolution rules to determine which policy manages it.

If neither `appList `nor `appSelector.labels `is defined, the policy does not match any workloads through selectors; workloads can still be matched by annotation.

Use `appList `or `appSelector.labels` to target workloads, and use `appSelector.namespaces` to narrow that selection.

**Common policy selection use cases**

The following table shows common policy selection use cases:

| **To do this** | **Use these mechanisms** |
| --- | --- |
| Target a single workload | Use **appList** to explicitly include a `deployment`, `statefulset`, or other workload type by name and namespace |
| Target workloads by label | Use **appSelector.labels.matchLabels** to include workloads that share a specific metadata label, such as `environment=production` |
| Target workloads by multiple label rules | Use **matchExpressions** to combine rules, for example: select workloads with `tier=frontend` AND exclude those with `version=beta` |
| Exclude a namespace | Use **appSelector.namespaces.operator: Exclude** to prevent optimization policies from affecting sensitive workloads in namespaces such as` critical-services` or` secret-ops` |
| Include only a namespace | Use **appSelector.namespaces.operator: Include** to limit optimization to one or two namespaces, such as `default `or `staging` |
| Explicitly assign one workload to a specific policy (override selectors and priority) | Use the workload policy annotation (`metadata.annotations.<policy-annotation-key>: <policy-name>`) to explicitly bind a workload to a policy, regardless of whether it matches any `appList `or `appSelector` rules |

**Explicit workload inclusion (appList)**

Explicit workload inclusion (`appList`) matches specific workloads by kind, name, and namespace.

In this topic, **appList** refers to the explicit workload inclusion mechanism, which is configured using the `appList `field in the policy.

Use `appList `to target specific workloads by kind, name, or namespace.

```yaml
appList:
  - kind: <workload-kind>
    name: <workload-name>
    namespace: <namespace>
```

Behavior:

- Matches the workloads specified in the `appList `entry.
- Takes precedence over label-based matching.
- If only `namespace `is specified, the policy matches all supported workloads in that namespace.
- `name `and `kind `can’t be used by themselves; specify them together with `namespace`.

**Label-based selection**

Label-based selection (`appSelector.labels`) dynamically matches workloads based on Kubernetes labels.

```yaml
appSelector:
  labels:
    matchLabels:
      <label-key>: <label-value>
    matchExpressions:
      - key: <label-key>
        operator: <operator>
        values:
          - <value>
```

Supported operators: `In`, `NotIn`, `Exists`, `DoesNotExist`

**Behavior**:

- `matchLabels `and `matchExpressions `are evaluated using AND logic.
- Multiple `matchExpressions `are also evaluated using AND logic.
- Only workloads that match all conditions are matched to the policy.

**Namespace filtering**

Namespace filtering (`appSelector.namespaces`) scopes label-based selection to specific namespaces by including or excluding namespaces.

```yaml
appSelector:
  namespaces:
    operator: <Include | Exclude>
    values:
      - <namespace>
```

**Behavior**:

- Applies only to workloads matched by label selectors.
- The `kube-system` namespace is always excluded.

**Annotation-based matching**

A workload can be explicitly matched to a policy using a Kubernetes annotation.

**Pod rightsizing**

```yaml
metadata:
  annotations:
    rightsizing.kompass.zesty.co/policy: <any rightsizing policy>
```

**Replica optimization**

```yaml
metadata:
  annotations:
    horizontalscaling.kompass.zesty.co/policy: <any horizontal scaling policy>
```

Behavior:

- The referenced policy matches the workload, and the corresponding optimization applies to that workload.
- Annotation-based matching overrides selector-based selection and priority.
- Removing the annotation removes this explicit match.

User interface and YAML:

- The UI assigns a policy to a workload by creating or updating the workload’s policy annotation.
- You can manage or modify Pod rightsizing in the UI only for workloads matched to a policy by annotation.
- For workloads matched by `appList `or label selectors, make changes using YAML.

**Examples**

The following table shows example uses of workload selection:

| To match this | Use this |
| --- | --- |
| Match one `Deployment `in one namespace | `appList` |
| Match all workloads with `app=payments` and `environment=prod` | `appSelector.labels` |
| Include `prod `and exclude `critical-services` namespaces | `appSelector.namespaces` |
| Override selector-based selection and priority. | set `metadata.annotations.&lt;policy-annotation-key&gt;: &lt;policy-name&gt;` on a single workload |

#### **Priority and conflict resolution**

When multiple policies match the same workload, Pod rightsizing uses policy priority to determine which policy manages the workload.

**Policy priority and resolution**

**Priority rules**

- A policy must define a `priority `value.
- Lower numeric values indicate higher priority. For example, priority 1 takes precedence over priority 2.
- Priority values must be unique per cluster. If you create or update a policy with a priority value that is already used, the request is rejected with a validation error.

**Policy resolution order**

Pod rightsizing determines the managing policy using the following resolution order:

1. **Annotation-based resolution:** Annotation-based assignment overrides selector-based matching and priority independently for Pod rightsizing and Replica optimization policies.
2. **Selector-based resolution**: If a workload matches multiple policies through `appList `or label selectors, the policy with the highest priority manages the workload.

A workload is managed by at most one Pod rightsizing policy and one Replica optimization policy at a time.

**To confirm which policy manages a workload**:

1. Check whether the workload has a policy annotation. If `metadata.annotations.&lt;policy-annotation-key&gt;` is set, the referenced policy manages the workload (and overrides selector-based selection and priority).
2. If no policy annotation exists, determine which policies match the workload via `appList `and `appSelector `rules.
3. If multiple policies match, the policy with the lowest `priority `value manages the workload.
4. If the workload is not matched by any policy, it is unmanaged and no optimization is applied.