Configure optimization settings

Define optimization policy for requests and limits at the cluster, namespace, or workload level

Policy-based optimization ensures consistency across workloads and gives teams the control they need over their work - for example:

  • Platform teams can set organization-wide default optimization values
  • Development teams can fine-tune settings using annotations on namespaces, Deployments, StatefulSets, and other workload resources

This topic explains how to configure optimization settings at the cluster, namespace or workload levels. For a list and description of what you can configure, see the Optimization settings and descriptions topic.

Key points:

  • Think of settings at the cluster, namespace, and workload levels as a hierarchy of configuration.
    • Cluster-level defaults apply to all workloads in a cluster. The cluster administrator defines cluster-wide defaults that are used when a more specific policy is not defined. Default values set at this level have the lowest precedence and can be overridden by values set at the namespace and workload levels.

    • Namespace-level configuration sets default values for all workloads in a namespace, overriding existing cluster defaults. Namespace owners can adjust these policies, or define their own, by using annotations on the namespace.

    • Workload-level configuration customizes the optimization behavior for individual workloads. Workload owners can further adjust or make exceptions to optimization policies, by using annotations on the actual workload objects (Deployments, StatefulSets, and others).

Quickstart: Copy a template

Each tab contains a template that contains the annotations from the table above.

  • Copy the Cluster template to set cluster-level defaults
  • Copy the Namespace template to set namespace-level defaults
  • Copy the Workload template to set workload-specific defaults defaults

To configure default optimization settings for all workloads in a cluster, copy annotations as needed from the sample file below, then pass the file to kubectl apply -f FILENAME.

  • All values shown are optional, none are required. The sample settings may not be correct for your environment. Copy and paste the specific values that you need, and remove the ones you don’t.

Go to the steps for using this template.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-defaults
  namespace: stormforge-system
data:
  cluster-defaults.yaml: |

    # WORKLOAD SETTINGS
    # Specify single values for the whole workload.
    live.stormforge.io/schedule: "@daily"
    live.stormforge.io/cpu.optimization-goal: "Balanced"
    live.stormforge.io/memory.optimization-goal: "Balanced"

    # Main configuration control for auto-deploy
    live.stormforge.io/auto-deploy: "false" # Set to "true" to enable auto-deploy

    # When auto-deploy is false, the following subsettings have no effect 
    live.stormforge.io/auto-deploy.thresholds.cpu.percent: "5"    # 1/2 Paired parameters; set both or neither.
    live.stormforge.io/auto-deploy.thresholds.memory.percent: "5" # 2/2. 
    live.stormforge.io/auto-deploy.thresholds.cpu.unit: "10m"     # 1/2 Paired parameters; set both or neither.
    live.stormforge.io/auto-deploy.thresholds.memory.unit: "20Mi" # 2/2.

    # The following settings have an effect only if an HPA is enabled and the HPA scales on CPU or memory.
    live.stormforge.io/hpa.cpu.target-utilization.min: "20"   
    live.stormforge.io/hpa.cpu.target-utilization.max: "80"   
    live.stormforge.io/hpa.memory.target-utilization.min: "25"  
    live.stormforge.io/hpa.memory.target-utilization.max: "75"  

    # CONTAINER SETTINGS
    # Specify defaults and/or per-container exceptions.
    # E.g. "RequestsOnly,istio-proxy=DoNotOptimize"
    live.stormforge.io/containers.cpu.optimization-policy: "RequestsOnly"
    live.stormforge.io/containers.cpu.requests.min: "20m"
    live.stormforge.io/containers.cpu.requests.max: "16000m"
    live.stormforge.io/containers.cpu.limits.min: "2000m"
    live.stormforge.io/containers.cpu.limits.max: "16000m"
    live.stormforge.io/containers.cpu.limits.limit-request-ratio: "2.0"
    live.stormforge.io/containers.memory.optimization-policy: "RequestsOnly"
    live.stormforge.io/containers.memory.requests.min: "64Mi"
    live.stormforge.io/containers.memory.requests.max: "32Gi"
    live.stormforge.io/containers.memory.limits.min: "512Mi"
    live.stormforge.io/containers.memory.limits.max: "64Gi"
    live.stormforge.io/containers.memory.limits.limit-request-ratio: "2.0"

To configure default optimization settings for all workloads in a namespace, copy annotations as needed from the template below into the metadata.annotations section of a namespace.

  • Annotations are shown with sample values to demonstrate what an active annotation looks like, and may not be correct for your environment. You should review and set appropriate values for each annotation you use.
  • All annotations are optional, none are required. Copy and paste the specific annotations that you need, and remove the ones you don’t.

Go to the steps for using this template.

apiVersion: v1
kind: Namespace
metadata:
  name: example-namespace-name
  annotations:

    # WORKLOAD SETTINGS
    # Specify single values for the whole workload.
    # ---------------------------------------------
    live.stormforge.io/schedule: "@daily"
    live.stormforge.io/cpu.optimization-goal: "Balanced"
    live.stormforge.io/memory.optimization-goal: "Balanced"

    # Main configuration control for auto-deploy
    live.stormforge.io/auto-deploy: "false" # Set to "true" to enable auto-deploy

    # When auto-deploy is false, the following subsettings have no effect 
    live.stormforge.io/auto-deploy.thresholds.cpu.percent: "5"    # 1/2 Paired parameters; set both or neither.
    live.stormforge.io/auto-deploy.thresholds.memory.percent: "5" # 2/2. 
    live.stormforge.io/auto-deploy.thresholds.cpu.unit: "10m"     # 1/2 Paired parameters; set both or neither.
    live.stormforge.io/auto-deploy.thresholds.memory.unit: "20Mi" # 2/2.

    # The following settings have an effect only if an HPA is enabled and the HPA scales on CPU or memory.
    live.stormforge.io/hpa.cpu.target-utilization.min: "20"   
    live.stormforge.io/hpa.cpu.target-utilization.max: "80"   
    live.stormforge.io/hpa.memory.target-utilization.min: "25"  
    live.stormforge.io/hpa.memory.target-utilization.max: "75"  

    # CONTAINER SETTINGS
    # Specify defaults and/or per-container exceptions.
    # E.g. "RequestsOnly,istio-proxy=DoNotOptimize"
    # -------------------------------------------------
    live.stormforge.io/containers.cpu.optimization-policy: "RequestsOnly"
    live.stormforge.io/containers.cpu.requests.min: "20m"
    live.stormforge.io/containers.cpu.requests.max: "16000m"
    live.stormforge.io/containers.cpu.limits.min: "2000m"
    live.stormforge.io/containers.cpu.limits.max: "16000m"
    live.stormforge.io/containers.cpu.limits.limit-request-ratio: "2.0"
    live.stormforge.io/containers.memory.optimization-policy: "RequestsOnly"
    live.stormforge.io/containers.memory.requests.min: "64Mi"
    live.stormforge.io/containers.memory.requests.max: "32Gi"
    live.stormforge.io/containers.memory.limits.min: "512Mi"
    live.stormforge.io/containers.memory.limits.max: "64Gi"
    live.stormforge.io/containers.memory.limits.limit-request-ratio: "2.0"

To configure optimization settings for a workload, copy annotations as needed from the template below into the metadata.annotations section of the workload resource.

  • The template shows annotations defined on a Deployment workload. The same pattern applies for all supported workload types.
  • Annotations are shown with sample values to demonstrate what an active annotation looks like, and may not be correct for your environment. You should review and set appropriate values for each annotation you use.
  • All annotations are optional, none are required. Copy and paste the specific annotations that you need, and remove the ones you don’t.

Go to the steps for using this template.

apiVersion: apps/v1 # // just an example; represents any
kind: Deployment    # \\ supported workload resource type
metadata:
  name: example-workload-name
  annotations:

    # WORKLOAD SETTINGS
    # Specify single values for the whole workload.
    # ---------------------------------------------
    live.stormforge.io/schedule: "@daily"
    live.stormforge.io/cpu.optimization-goal: "Balanced"
    live.stormforge.io/memory.optimization-goal: "Balanced"

    # Main configuration control for auto-deploy
    live.stormforge.io/auto-deploy: "false" # Set to "true" to enable auto-deploy

    # When auto-deploy is false, the following subsettings have no effect 
    live.stormforge.io/auto-deploy.thresholds.cpu.percent: "5"    # 1/2 Paired parameters; Set both or neither
    live.stormforge.io/auto-deploy.thresholds.memory.percent: "5" # 2/2. 
    live.stormforge.io/auto-deploy.thresholds.cpu.unit: "10m"     # 1/2 Paired parameters; set both or neither
    live.stormforge.io/auto-deploy.thresholds.memory.unit: "20Mi" # 2/2.

    # The following settings have an effect only if an HPA is enabled and the HPA scales on CPU or memory.
    live.stormforge.io/hpa.cpu.target-utilization.min: "20"   
    live.stormforge.io/hpa.cpu.target-utilization.max: "80"   
    live.stormforge.io/hpa.memory.target-utilization.min: "25"  
    live.stormforge.io/hpa.memory.target-utilization.max: "75"  

    # CONTAINER SETTINGS
    # Specify defaults and/or per-container exceptions.
    # E.g. "RequestsOnly,istio-proxy=DoNotOptimize"
    # -------------------------------------------------
    live.stormforge.io/containers.cpu.optimization-policy: "RequestsOnly"
    live.stormforge.io/containers.cpu.requests.min: "20m"
    live.stormforge.io/containers.cpu.requests.max: "16000m"
    live.stormforge.io/containers.cpu.limits.min: "2000m"
    live.stormforge.io/containers.cpu.limits.max: "16000m"
    live.stormforge.io/containers.cpu.limits.limit-request-ratio: "2.0"
    live.stormforge.io/containers.memory.optimization-policy: "RequestsOnly"
    live.stormforge.io/containers.memory.requests.min: "64Mi"
    live.stormforge.io/containers.memory.requests.max: "32Gi"
    live.stormforge.io/containers.memory.limits.min: "512Mi"
    live.stormforge.io/containers.memory.limits.max: "64Gi"
    live.stormforge.io/containers.memory.limits.limit-request-ratio: "2.0"

spec:
  template:
    metadata:

When editing annotations:

  • Enclose all values in double quotation marks ("...").
  • Best practice: When editing container-specific resources, specify the value to apply to all or most containers first, followed by container-specific exceptions, as in these examples:
    • When annotating a workload or namespace:
      live.stormforge.io/containers.cpu.optimization-policy: "RequestsAndLimits,logwriter=DoNotOptimize"

Configure optimization defaults for the cluster

Configure default optimization settings for the cluster

Configure optimization defaults for namespaces

Configure optimization settings for namespaces and workloads using annotations

Configure optimization for individual workloads

Configure optimization settings for namespaces and workloads using annotations

Workload-level settings

Review the complete list of workload optimization settings and their descriptions

Container-level settings

Review the complete list of container optimization settings and their descriptions

Last modified May 2, 2024