Annotations list and descriptions

Review the complete list of annotations and their descriptions

This purpose of this topic is to list and describe the supported annotations.

Using annotations (instead of the UI) to configure default optimization settings is a best practice.

If you already know how to use these annotations, you can copy a template from the appropriate tab below and use it as a starting point.

For details about how to use these annotations and where to add these templates, see the Configuring by using annotations topic.

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

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

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:

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 default optimization settings for all workloads in a cluster, copy as needed from the Helm values template below into your Helm values file, then pass the file to helm install or helm upgrade using the -f flag.

  • Helm values are shown with sample settings that demonstrate what using the value looks like. The sample settings may not be correct for your environment. You should review and choose an appropriate setting for each Helm value you specify.
  • All Helm values shown are optional, none are required. Copy and paste the specific values that you need, and remove the ones you don’t.

Go to the steps for using this template.

---
# Helm values.yaml file

clusterDefaultConfig:
  # All values below are optional; copy/paste only those that you need.
  # ---------------------------------------------
  # WORKLOAD SETTINGS
  # Specify single values for the whole workload.
  # ---------------------------------------------
  schedule: "P1D"
  cpuOptimizationGoal: "Balanced"
  memoryOptimizationGoal: "Balanced"

  # Main configuration control for auto-deploy
  autoDeploy: "false" # Set to "true" to enable auto-deploy

  # When auto-deploy is false, the following subsettings have no effect
  autoDeployThresholdsCpuPercent: "5"     # 1/2 Paired parameters; Set both or neither
  autoDeployThresholdsMemoryPercent: "5"  # 2/2. 
  autoDeployThresholdsCpuUnit: "10m"      # 1/2 Paired parameters; Set both or neither
  autoDeployThresholdsMemoryUnit: "20Mi"  # 2/2.

  # The following settings have an effect only if an HPA is enabled and the HPA scales on CPU or memory.
  hpaCpuTargetUtilizationMin: "20"   
  hpaCpuTargetUtilizationMax: "80"   
  hpaMemoryTargetUtilizationMin: "25"  
  hpaMemoryTargetUtilizationMax: "75" 

  # ---------------------------------------------
  # CONTAINER SETTINGS
  # Specify defaults and/or per-container values.
  # E.g. "RequestsOnly,istio-proxy=DoNotOptimize"
  # ---------------------------------------------
  containersCpuOptimizationPolicy: "RequestsOnly"
  containersCpuRequestsMin: "20m"
  containersCpuRequestsMax: "16000m"
  containersCpuLimitsMin: "2000m"
  containersCpuLimitsMax: "16000m"
  containersCpuLimitsLimitRequestRatio: "2.0"
  containersMemoryOptimizationPolicy: "RequestsOnly"
  containersMemoryRequestsMin: "64Mi"
  containersMemoryRequestsMax: "32Gi"
  containersMemoryLimitsMin: "512Mi"
  containersMemoryLimitsMax: "64Gi"
  containersMemoryLimitsLimitRequestRatio: "2.0"

Available annotations

Annotation Description
Workload-level settings
live.stormforge.io/schedule The schedule on which optimization will run and produce new recommendations. Valid values are ISO 8601 [Duration][duration] strings like "P1D", [cron][cron] format strings like "H H * * *", or macros such as "@daily" (default). See the Schedule examples in the Configure by using annotations topic.
live.stormforge.io/auto-deploy Whether or not to automatically apply new recommended settings produced on a schedule. Valid values are "true" or "false" (default). A best practice is to review recommendations manually the first few times before enabling auto-deployment.
live.stormforge.io/auto-deploy.thresholds.cpu.percent and live.stormforge.io/auto-deploy.thresholds.memory.percent Set a percent-change threshold (positive integer). Set both or neither. You must also set live.stormforge.io/auto-deploy=true. To disable, set both to 0. See the Threshold examples in the Configure by using annotations topic.
live.stormforge.io/auto-deploy.thresholds.cpu.unit and live.stormforge.io/auto-deploy.thresholds.memory.unit Set a unit-change threshold (positive integer + Kubernetes unit). Set both or neither. You must also set live.stormforge.io/auto-deploy=true. To disable, set both to 0. See the Threshold examples in the Configure by using annotations topic.
live.stormforge.io/cpu.optimization-goal and live.stormforge.io/memory.optimization-goal Valid values are "Balanced" (default), "Reliability", or "Savings".
live.stormforge.io/hpa.cpu.target-utilization.min The lower bound of the range Optimize Live can set HPA target utilization to, for CPU. Valid values are 0-100.
live.stormforge.io/hpa.cpu.target-utilization.max The upper bound of the range Optimize Live can set HPA target utilization to, for CPU. Valid values are 0-100.
live.stormforge.io/hpa.memory.target-utilization.min The lower bound of the range Optimize Live can set HPA target utilization to, for memory. Valid values are 0-100.
live.stormforge.io/hpa.memory.target-utilization.max The upper bound of the range Optimize Live can set HPA target utilization to, for memory. Valid values are 0-100.
Container-level settings
live.stormforge.io/containers.cpu.optimization-policy Valid values are "RequestsOnly" (default), "RequestsAndLimits", or "DoNotOptimize".
live.stormforge.io/containers.cpu.requests.min Indicates the lower bound of the range for CPU requests.
live.stormforge.io/containers.cpu.requests.max Indicates the upper bound of the range for CPU requests.
live.stormforge.io/containers.cpu.limits.min Indicates the lower bound of the range for CPU limits.
live.stormforge.io/containers.cpu.limits.max Indicates the upper bound of the range for CPU limits.
live.stormforge.io/containers.cpu.limits.limit-request-ratio Used to calculate limits when optimization policy is set to RequestsAndLimits (See the example in the Configure topic). Valid values include "2.0" (default), "1.0" (Guaranteed QoS), or any value >= "1.0" to a maximum of two decimal places.
live.stormforge.io/containers.memory.optimization-policy Valid values are "RequestsOnly" (default), "RequestsAndLimits", or "DoNotOptimize".
live.stormforge.io/containers.memory.requests.min Indicates the lower bound of the range for memory requests.
live.stormforge.io/containers.memory.requests.max Indicates the upper bound of the range for memory requests.
live.stormforge.io/containers.memory.limits.min Indicates the lower bound of the range for memory limits.
live.stormforge.io/containers.memory.limits.max Indicates the upper bound of the range for memory limits.
live.stormforge.io/containers.memory.limits.limit-request-ratio Used to calculate limits when optimization policy is set to RequestsAndLimits (See the example in the Configure topic). Valid values include "2.0" (default), "1.0" (Guaranteed QoS), or any value >= "1.0" to a maximum of two decimal places.
Last modified February 1, 2024