Help improve this page
To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.
EKS Auto Mode resource optimization resource reference
EKS Auto Mode resource optimization uses two Kubernetes resources in the eks.amazonaws.com/v1beta1 API group and two annotations that you set on workloads. Every EKS Auto Mode cluster that runs Kubernetes 1.36 or later includes the custom resource definitions. There’s no Amazon EKS API field for resource optimization.
| Kind | Short name | Scope | Who creates it |
|---|---|---|---|
|
|
|
Cluster |
You. A policy turns on resource optimization and selects workloads. |
|
|
|
Namespace |
Resource optimization, one for each workload that a policy selects. You read it, but you don’t create it. |
ClusterResourceOptimizationPolicy
A ClusterResourceOptimizationPolicy selects workloads and sets the mode and profile they get. Policies are the only switch for resource optimization: creating the first policy turns it on, and deleting the last one turns it off. For how several policies combine, see How resource optimization policies select and combine.
Example – ClusterResourceOptimizationPolicy
apiVersion: eks.amazonaws.com/v1beta1 kind: ClusterResourceOptimizationPolicy metadata: name: search-web spec: mode: Apply profile: Balanced namespaceSelector: matchLabels: team: search workloadSelector: matchExpressions: - key: tier operator: In values: - web - api
The smallest valid policy is spec: {}. It selects every Deployment and StatefulSet in every non-system namespace, in Recommend mode with the Balanced profile.
Spec fields
The following table describes the fields that you can set in a policy’s spec.
| Field | Values | Default | Description |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
The sizing targets for recommendations. |
|
|
A Kubernetes label selector |
Not set. Selects every non-system namespace. |
Selects namespaces by their labels. To select namespaces by name, use the |
|
|
A Kubernetes label selector |
Not set. Selects every Deployment and StatefulSet in the selected namespaces. |
Selects workloads by the labels on the Deployment or StatefulSet object, not the labels in its Pod template. |
Status fields
kubectl get crop shows the MODE, PROFILE, READY, and SELECTED columns. The full status has the following fields.
| Field | Description |
|---|---|
|
|
The number of workloads this policy selects that don’t opt out, including any that failed to sync. A workload that more than one policy selects counts on each of them. |
|
|
The number of workloads this policy selects that opt out with the |
|
|
The conditions in the following table. |
The following table describes the conditions of a policy.
| Condition | Reason when False
|
Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
ResourceOptimization
Resource optimization creates a ResourceOptimization object in the workload’s namespace for each Deployment or StatefulSet that a policy selects. The object records the workload’s settings, its recommendations, and conditions that explain what resource optimization is doing. Don’t edit these objects, because resource optimization overwrites their spec from the winning policy. Creating your own ResourceOptimization objects isn’t supported in this preview. To control which workloads resource optimization manages, use a policy’s workloadSelector or the opt-out annotation.
- Name
-
The workload’s name followed by
-deployfor a Deployment or-stsfor a StatefulSet. For example, the object for Deploymentcheckoutischeckout-deploy. If the result would be longer than 253 characters, resource optimization shortens the workload’s name and adds an 8-character hash before the suffix. - Owners
-
Every policy that selects the workload is an owner reference. The winning policy’s owner reference has
controller: true. It’s the same policy named instatus.policySource. - Deletion
-
Resource optimization deletes the object when no valid policy selects the workload, or when the workload opts out. For example, deleting the last policy that selects a workload, changing the workload’s labels, or making a selector invalid deletes the object. This also deletes the workload’s usage history. If the workload is managed again, the wait of about 12 hours for a first recommendation starts over.
Example – ResourceOptimization
The following object is for a Deployment named checkout with one container that declares requests of cpu: 250m and memory: 256Mi and limits of cpu: 500m and memory: 512Mi.
apiVersion: eks.amazonaws.com/v1beta1 kind: ResourceOptimization metadata: name: checkout-deploy namespace: shop ownerReferences: - apiVersion: eks.amazonaws.com/v1beta1 kind: ClusterResourceOptimizationPolicy name: team-shop controller: true uid: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 spec: scaleTargetRef: kind: Deployment name: checkout mode: Apply profile: Balanced objectives: - dimension: Vertical resource: metric: cpu utilization: 87 - dimension: Vertical resource: metric: memory utilization: 70 constraints: - operator: Minimum resources: cpu: 125m memory: 128Mi - operator: Maximum resources: cpu: "1" memory: 1Gi status: policySource: mode: team-shop profile: team-shop recommendations: - type: Vertical verticalRecommendations: - containerName: checkout request: cpu: 140m memory: 300Mi limit: cpu: 280m memory: 600Mi phase: Applied reason: "Vertical scaling recommendation: CPU request: 140m, CPU limit: 280m, Memory request: 300Mi, Memory limit: 600Mi" createTime: "2026-11-18T10:00:00Z" lastUpdateTime: "2026-11-18T10:02:00Z" conditions: - type: Ready status: "True" reason: Ready message: "" lastTransitionTime: "2026-11-17T22:00:00Z" - type: AdmissionSizing status: "True" reason: Sized message: new pods are created at the recommended size lastTransitionTime: "2026-11-18T10:00:00Z"
kubectl get ro shows the KIND, TARGET, POLICY, and MODE columns. POLICY is the policy that supplied the mode.
Spec fields
Resource optimization sets every spec field from the winning policy and the workload’s Pod template. Treat them as read-only. The following table describes each field.
| Field | Description |
|---|---|
|
|
|
|
|
The name of the workload. |
|
|
|
|
|
|
|
|
The utilization targets that the profile sets. With |
|
|
The lowest and highest values that a recommendation can have, calculated from the profile and the requests and limits in the Pod template. Each entry has an |
Status fields
The following table describes the status fields of a ResourceOptimization object.
| Field | Description |
|---|---|
|
|
The policy that supplied each spec field, for example |
|
|
|
|
|
The container that the recommendation is for. Not set for a recommendation for the whole Pod, when the Pod template uses Pod-level resources. |
|
|
The recommended CPU and memory requests. |
|
|
The recommended CPU and memory limits. Resource optimization keeps each container’s ratio of request to limit from the Pod template, so a Pod’s quality of service class doesn’t change. A resource with no limit in the template gets no limit. |
|
|
A description of the recommendation. If a HorizontalPodAutoscaler holds part of the recommendation, the reason ends with the resources that weren’t applied. If the container declares no request for a resource, the reason says that the value is a recommendation only. |
|
|
|
|
|
When the recommendation was created and last changed. |
|
|
Resources that a HorizontalPodAutoscaler scales on, so resource optimization publishes recommendations for them but doesn’t apply them. Each entry has |
|
|
Containers whose memory resource optimization couldn’t raise after an out-of-memory kill because memory is already at its cap. Each entry has |
|
|
Present only for a workload with the |
|
|
Present only for a workload with the |
|
|
See Conditions. |
Recommendation phases
| Phase | Meaning |
|---|---|
|
|
Resource optimization produced the recommendation and isn’t applying it. Either the mode is |
|
|
The mode is |
|
|
Resource optimization is applying the recommendation, or waiting until it can. For example, it waits while a VerticalPodAutoscaler targets the workload, while it can’t read the workload’s autoscalers, or while the Pods run in a sandbox. |
|
|
The kubelet applied the resize. |
Conditions
Most conditions appear only in Apply mode, and only when they apply to the workload. For what to do about each one, see Troubleshoot EKS Auto Mode resource optimization.
| Condition | Reasons | Meaning |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Whether new Pods start at the recommended size. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Startup boost only. |
|
|
|
Startup boost only. |
|
|
|
Startup boost only. |
|
|
|
|
|
|
|
|
Balanced profile
Balanced is the only profile in this preview. The following table shows the values that resource optimization calculates from the workload’s Pod template, as you wrote it.
| Setting | Value |
|---|---|
|
CPU request |
1.15 times the 95th percentile of per-minute average CPU usage. The objective is written as |
|
Memory request |
1.43 times the 95th percentile of per-minute peak memory usage. The objective is written as |
|
|
Half of the smallest request that any container in the Pod declares for the resource. |
|
|
Twice the largest limit that any container in the Pod declares for the resource. If any container declares a request for the resource without a limit, there’s no |
|
Limits |
Each container keeps the ratio of request to limit from its Pod template. Resource optimization doesn’t add a limit to a container that doesn’t have one. |
Every container in the Pod, including sidecars, shares one Minimum and one Maximum for each resource. A container that declares only a limit counts its limit as its request.
A container that declares neither a request nor a limit for a resource still gets a recommendation. Resource optimization never applies that value, because adding a request would change the Pod’s quality of service class.
A workload with the startup-boost annotation has no CPU Minimum, because its declared CPU is the raised startup value. Its CPUFloorWaived condition is True.
Workload annotations
Set these annotations in the metadata.annotations of the Deployment or StatefulSet, not in its Pod template. Annotation values are strings, so quote them in YAML.
| Annotation | Value | Effect |
|---|---|---|
|
|
|
Opts the workload out of resource optimization, whatever the policies select. Resource optimization deletes the workload’s |
|
|
|
Turns on startup boost. Set a raised CPU request in the Pod template for startup. In |