Configuration

Overview

This page documents the PVPolicy Custom Resource fields, PVC annotations, and Helm values that control Storage Autoscaling behavior. For background on how the configuration layers interact, including the default PVPolicy and policy resolution, see How it works.

PVC annotations override the matched policy on a per-PVC basis.

PVPolicy Custom Resource

PVPolicy is a namespaced Custom Resource Definition in the storage.cast.ai/v1alpha1 API group.

Create PVPolicy CRs in the castai-agent namespace using kubectl apply.

PVPolicy spec

PVC selector

The spec.selector field determines which PVCs a policy applies to. It has two active subfields: namespaces and pvc.

Namespace filter

spec.selector.namespaces is a list of namespace names. When empty, all namespaces are eligible. When non-empty, only PVCs in the listed namespaces are considered.

PVC matcher

spec.selector.pvc defines which PVCs match by name, label, or StorageClass. An empty object (pvc: {}) matches all PVCs in the selected namespaces. When omitted entirely, no PVCs are matched through this selector.

All non-empty fields are AND-ed: a PVC must satisfy every specified condition.

📘

Note

PVCs with no storageClassName set do not match any storageClasses filter. If you need to manage these PVCs, use the names or labels fields instead.

📘

Note

Workload-based matching (spec.selector.workload) is planned for a future release. If set, it is currently ignored.

Policy configuration

The spec.config field contains the autoscaling settings applied to matched PVCs. The dimensions block is required. The storage and performance sub-objects are optional. When you omit a field, it inherits the corresponding global default from Helm values.

Dimensions

spec.config.dimensions controls which autoscaling dimensions are enabled for matched PVCs.

Storage settings

spec.config.storage configures capacity expansion behavior.

Performance settings

spec.config.performance configures IOPS and throughput rightsizing behavior.

Helm values (global defaults)

Helm values provide global defaults that PVPolicy CRs inherit when their config fields are omitted. You can pass a values file with -f values.yaml or use --set for individual overrides.

PVPolicy fields mirror the storage and performance settings documented above. When you set these values in Helm, they serve as the baseline that policies inherit from. For tuning specific PVCs or namespaces, prefer creating PVPolicy CRs over overriding Helm values.

Controller settings

These settings are specific to Helm and do not appear in PVPolicy CRs.

Namespace and label filtering

These Helm-level filters apply globally. PVPolicy selectors are the preferred way to scope management.

Global PVC defaults

These values apply when a PVPolicy's dimension fields are omitted. They can also be overridden per-PVC via annotations.

PVPolicy examples

Example 1: Default policy (automatically created by Helm)

The default PVPolicy is created automatically on controller pod start, if it does not yet exist. It is not updated later by the controller, so any configuration changes diverging from the default profile should be done in the PVPolicy resource.

apiVersion: storage.cast.ai/v1alpha1
kind: PVPolicy
metadata:
  name: default
  namespace: castai-agent
spec:
  priority: 0
  dryRun: true
  selector:
    namespaces: []
    pvc: {}
  config:
    dimensions:
      storageEnabled: true
      iopsEnabled: true
      throughputEnabled: true
    storage:
      thresholdPercent: 80
      thresholdPeriod: "5m"
      growthPercent: 20
      minGrowthStepGiB: 5
      cooldownPeriod: "30m"
    performance:
      target: "max"
      overhead: 0.2
      lookbackPeriod: "6h"
      minWarmupWindow: "30m"
      changeCooldown: "15m"

Example 2: Scope to a specific namespace with custom thresholds

This policy matches PVCs in the production namespace, uses a 90% threshold and 25% growth, and runs in live mode. Because it has a higher priority than the default policy, it takes precedence for production PVCs.

apiVersion: storage.cast.ai/v1alpha1
kind: PVPolicy
metadata:
  name: production
  namespace: castai-agent
spec:
  priority: 10
  dryRun: false
  selector:
    namespaces:
      - production
    pvc: {}
  config:
    dimensions:
      storageEnabled: true
      iopsEnabled: true
      throughputEnabled: true
    storage:
      thresholdPercent: 90
      growthPercent: 25

Example 3: Match by label and StorageClass

This policy matches PVCs with the label app=database and the StorageClass gp3, and disables IOPS rightsizing for them.

apiVersion: storage.cast.ai/v1alpha1
kind: PVPolicy
metadata:
  name: database-gp3
  namespace: castai-agent
spec:
  priority: 20
  dryRun: false
  selector:
    namespaces: []
    pvc:
      labels:
        matchLabels:
          app: database
      storageClasses:
        - gp3
  config:
    dimensions:
      storageEnabled: true
      iopsEnabled: false
      throughputEnabled: true

PVC annotations

Overview

Annotations override the matched policy's settings on a per-PVC basis. The applicable PVPolicy is resolved first, and then annotation overrides are applied on top.

Set a *-enabled annotation to "true" only if you have disabled the feature in the matched policy and want to re-enable it for a specific PVC.

Annotations you set

Status annotations

Storage Autoscaling writes status annotations back to PVCs so you can inspect current state and troubleshoot issues.

PVC annotation examples

GCP / Hyperdisk Balanced: opt out of IOPS/throughput tuning

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-database-pvc
  annotations:
    storage.cast.ai/storage-threshold-percent: "85"
    storage.cast.ai/storage-growth-percent: "25"
    storage.cast.ai/iops-enabled: "false"
    storage.cast.ai/throughput-enabled: "false"
spec:
  storageClassName: hyperdisk-balanced
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 100Gi

AWS / gp3: cap IOPS/throughput ceilings

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-database-pvc-aws
  annotations:
    storage.cast.ai/iops-max: "16000"
    storage.cast.ai/throughput-max-mibps: "500"
spec:
  storageClassName: gp3
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 100Gi

Related resources