Apply and manage Pod rightsizing for workloads - CLI

A policy defines the Pod rightsizing behavior that applies to the workloads it matches. All configuration is scoped to the policy.

This topic includes the following sections:

• Apply a Pod rightsizing rightsizing policy to a workload - CLI

• Change or remove existing policies for Pod rightsizing - CLI

• Create and manage custom policies - CLI

• Common CLI commands

Apply a Pod rightsizing policy to a workload - CLI

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

Built-in policies have fixed rightsizing parameter values. After you decide which policy to apply to a workload, you edit the policy selection parameters to match the workloads you want to manage.

To apply a policy to workloads, you define the workload selection parameters in the policy, described in Define workload selection.

Built-in policy fixed parameter values

Built-in policies have fixed parameter values.

You can also create a custom policy, based on a built-in policy. For more information, see Create a custom policy.

Define workload selection

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

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, Pod rightsizing uses 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:

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.

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.

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.

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.

metadata:
  annotations:
    kompass.zesty.co/PodRightsizing/policy: <policy-name>

Behavior:

• The referenced policy matches the workload, and Pod rightsizing applies to that workload.

• Annotation-based matching overrides selector-based selection and priority.

• Removing the annotation removes this explicit match.

User interface and CLI:

• 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 in the cluster (CLI).

Examples

The following table shows example uses of workload selection:

Priority and conflict resolution

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

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: If a workload is matched to a policy by annotation, that policy manages the workload regardless of priority.

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 policy at a time.

To confirm which policy manages a workload:

1. Check whether the workload has a policy annotation.
   If metadata.annotations.<policy-annotation-key> 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 Pod rightsizing is not applied.

Change or remove existing policies for Pod rightsizing - CLI

This section describes how to use the CLI to change or remove the Pod rightsizing policy that manages a workload, and how to create and edit custom policies.

You can change or remove Pod rightsizing on workloads from the cluster.

• To change the policy that manages a workload, edit the policy selectors on the current and the desired policy.

  Tip

  To avoid an unmanaged gap, add the workload to the new policy before removing it from the old policy.

• To remove a policy from a workload, remove the workload from policy selection, using the relevant solution:

  • Remove it from the policy’s  appList selector.

  • Update the policy label selector so it no longer matches the workload.

  • Remove the policy annotation from the workload.

  After removing, the workload may still be managed if it matches a different policy.

Create and manage custom policies - CLI

You can create, edit, and delete custom policies.

After you create a custom policy, you can apply it to workloads from the UI or CLI.

Create a custom policy

When creating a custom policy, all parameters need to be explicitly defined. Duplicating a policy creates a new custom policy resource. The duplicate is editable because it is a custom policy, even if the original policy was built-in.

To create a custom policy:

1. From the cluster, duplicate an existing built-in policy.
   You can see the rightsizing parameters of the built-in policies at Built-in policy fixed parameter values.

2. (Optional) Change parameters.
   You can see the full list of parameters and descriptions at Policy parameters reference.

3. Save the policy with a new name.

Edit or delete a custom policy

When you edit policy parameters, those changes will affect future orchestrations. Running workloads will not be affected until the next orchestration.

You can delete a custom policy only if it is not assigned to any active workloads.

If you attempt to delete a custom policy that is assigned to workloads, the delete operation is blocked with a validation error. The error indicates how many workloads are still assigned to the policy and provides a way to view which workloads they are.

To edit or delete a policy, use Kubernetes CLI.

Common CLI commands

Replace the values inside [ ] with your values.