Annotations list and 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.
Copy a template
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 strings like "P1D" , 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. |