Volume Class¶

The Volume class manages persistent storage in Kubernetes. It provides volume creation, mounting, and management capabilities for applications that require persistent data storage.

Overview¶

from celestra import Volume

# Basic volume
volume = Volume("app-data").size("10Gi").storage_class("fast-ssd")

# Production volume with backup
volume = (Volume("production-data")
    .size("100Gi")
    .storage_class("premium-ssd")
    .backup_enabled(True)
    .encryption_enabled(True)
    .access_mode("ReadWriteOnce"))

Core API Functions¶

Volume Configuration¶

Volume Size¶

Set the volume size.

# Basic size
volume = Volume("app-data").size("10Gi")

# Large volume
volume = Volume("database-data").size("1Ti")

# Small volume
volume = Volume("config-data").size("1Gi")

Storage Class¶

Set the storage class for the volume.

# SSD storage
volume = Volume("app-data").storage_class("fast-ssd")

# HDD storage
volume = Volume("backup-data").storage_class("standard-hdd")

# Premium storage
volume = Volume("database-data").storage_class("premium-ssd")

Access Mode¶

Set the access mode for the volume.

# Single node read/write
volume = Volume("app-data").access_mode("ReadWriteOnce")

# Multiple nodes read/write
volume = Volume("shared-data").access_mode("ReadWriteMany")

# Multiple nodes read-only
volume = Volume("config-data").access_mode("ReadOnlyMany")

Mount Path¶

Set the mount path for the volume.

# Application data
volume = Volume("app-data").mount_path("/app/data")

# Database data
volume = Volume("database-data").mount_path("/var/lib/postgresql/data")

# Configuration data
volume = Volume("config-data").mount_path("/etc/config")

Volume Types¶

Persistent Volume¶

Configure as persistent volume.

volume = Volume("app-data").persistent_volume()

Ephemeral Volume¶

Configure as ephemeral volume.

volume = Volume("temp-data").ephemeral_volume()

Empty Directory Volume¶

Configure as empty directory volume.

volume = Volume("cache-data").empty_dir_volume()

Host Path Volume¶

Configure as host path volume.

volume = Volume("host-data").host_path_volume("/host/data")

ConfigMap Volume¶

Configure as ConfigMap volume.

volume = Volume("config-data").config_map_volume("app-config")

Secret Volume¶

Configure as Secret volume.

volume = Volume("secret-data").secret_volume("app-secret")

Storage Features¶

Backup Enabled¶

Enable backup for the volume.

# Enable backup
volume = Volume("app-data").backup_enabled(True)

# Disable backup
volume = Volume("temp-data").backup_enabled(False)

Backup Schedule¶

Set backup schedule.

# Daily backup
volume = Volume("app-data").backup_schedule("0 2 * * *")

# Weekly backup
volume = Volume("app-data").backup_schedule("0 2 * * 0")

Backup Retention¶

Set backup retention period.

# 30 days retention
volume = Volume("app-data").backup_retention(30)

# 90 days retention
volume = Volume("app-data").backup_retention(90)

Encryption Enabled¶

Enable encryption for the volume.

# Enable encryption
volume = Volume("app-data").encryption_enabled(True)

# Disable encryption
volume = Volume("temp-data").encryption_enabled(False)

Encryption Key¶

Set encryption key for the volume.

volume = Volume("app-data").encryption_key("my-encryption-key")

Performance Configuration¶

IOPS Configuration¶

Set IOPS for the volume.

# High IOPS
volume = Volume("database-data").iops(3000)

# Standard IOPS
volume = Volume("app-data").iops(1000)

Throughput Configuration¶

Set throughput for the volume.

# High throughput
volume = Volume("database-data").throughput("500Mi")

# Standard throughput
volume = Volume("app-data").throughput("125Mi")

Performance Tier¶

Set performance tier.

# Premium tier
volume = Volume("database-data").performance_tier("premium")

# Standard tier
volume = Volume("app-data").performance_tier("standard")

# Basic tier
volume = Volume("backup-data").performance_tier("basic")

Volume Mounting¶

Mount Options¶

Set mount options for the volume.

# NFS mount options
volume = Volume("nfs-data").mount_options(["nfsvers=4", "noatime"])

# Local mount options
volume = Volume("local-data").mount_options(["noatime", "nodiratime"])

Sub-Path Mounting¶

Set sub-path for volume mounting.

# Mount specific subdirectory
volume = Volume("config-data").sub_path("app/config")

Read-Only Volume¶

Set volume as read-only.

# Read-only volume
volume = Volume("config-data").read_only(True)

# Read-write volume
volume = Volume("app-data").read_only(False)

Volume Expansion¶

Allow Expansion¶

Allow volume expansion.

# Allow expansion
volume = Volume("app-data").allow_expansion(True)

# Disable expansion
volume = Volume("fixed-data").allow_expansion(False)

Expansion Policy¶

Set expansion policy.

# Automatic expansion
volume = Volume("app-data").expansion_policy("automatic")

# Manual expansion
volume = Volume("app-data").expansion_policy("manual")

Expansion Threshold¶

Set expansion threshold percentage.

# Expand at 80% usage
volume = Volume("app-data").expansion_threshold(0.8)

# Expand at 90% usage
volume = Volume("app-data").expansion_threshold(0.9)

Volume Snapshots¶

Snapshot Enabled¶

Enable volume snapshots.

# Enable snapshots
volume = Volume("app-data").snapshot_enabled(True)

# Disable snapshots
volume = Volume("temp-data").snapshot_enabled(False)

Snapshot Schedule¶

Set snapshot schedule.

# Daily snapshots
volume = Volume("app-data").snapshot_schedule("0 1 * * *")

# Hourly snapshots
volume = Volume("critical-data").snapshot_schedule("0 * * * *")

Snapshot Retention¶

Set snapshot retention count.

# Keep 7 snapshots
volume = Volume("app-data").snapshot_retention(7)

# Keep 30 snapshots
volume = Volume("critical-data").snapshot_retention(30)

Volume Replication¶

Replication Enabled¶

Enable volume replication.

# Enable replication
volume = Volume("critical-data").replication_enabled(True)

# Disable replication
volume = Volume("temp-data").replication_enabled(False)

Replication Factor¶

Set replication factor.

# 3x replication
volume = Volume("critical-data").replication_factor(3)

# 2x replication
volume = Volume("app-data").replication_factor(2)

Replication Zones¶

Set replication zones.

# Multi-zone replication
volume = Volume("critical-data").replication_zones(["us-west1-a", "us-west1-b", "us-west1-c"])

Advanced Configuration¶

Namespace¶

Set the namespace for the volume.

volume = Volume("app-data").namespace("production")

Add Label¶

Add a label to the volume.

volume = Volume("app-data").add_label("environment", "production")

Add Labels¶

Add multiple labels to the volume.

labels = {
    "environment": "production",
    "team": "platform",
    "tier": "storage"
}
volume = Volume("app-data").add_labels(labels)

Add Annotation¶

Add an annotation to the volume.

volume = Volume("app-data").add_annotation("description", "Application data volume")

Add Annotations¶

Add multiple annotations to the volume.

annotations = {
    "description": "Application data volume for production",
    "owner": "platform-team",
    "backup-schedule": "daily"
}
volume = Volume("app-data").add_annotations(annotations)

Node Affinity¶

Set node affinity for the volume.

# Affinity to specific nodes
affinity = {
    "requiredDuringSchedulingIgnoredDuringExecution": {
        "nodeSelectorTerms": [{
            "matchExpressions": [{
                "key": "storage-type",
                "operator": "In",
                "values": ["ssd"]
            }]
        }]
    }
}
volume = Volume("fast-data").node_affinity(affinity)

Pod Affinity¶

Set pod affinity for the volume.

# Affinity to specific pods
affinity = {
    "preferredDuringSchedulingIgnoredDuringExecution": [{
        "weight": 100,
        "podAffinityTerm": {
            "labelSelector": {
                "matchExpressions": [{
                    "key": "app",
                    "operator": "In",
                    "values": ["database"]
                }]
            },
            "topologyKey": "kubernetes.io/hostname"
        }
    }]
}
volume = Volume("database-data").pod_affinity(affinity)

Output Generation¶

generate() -> VolumeGenerator¶

Generate the volume configuration.

# Generate Kubernetes YAML
volume.generate().to_yaml("./k8s/")

# Generate Helm values
volume.generate().to_helm_values("./helm/")

# Generate Terraform
volume.generate().to_terraform("./terraform/")

Complete Example¶

Here's a complete example of a production-ready volume configuration:

from celestra import Volume

# Create comprehensive volume configuration
production_volume = (Volume("production-data")
    .size("100Gi")
    .storage_class("premium-ssd")
    .access_mode("ReadWriteOnce")
    .mount_path("/app/data")
    .persistent_volume()
    .backup_enabled(True)
    .backup_schedule("0 2 * * *")
    .backup_retention(30)
    .encryption_enabled(True)
    .encryption_key("production-encryption-key")
    .iops(3000)
    .throughput("500Mi")
    .performance_tier("premium")
    .mount_options(["noatime", "nodiratime"])
    .allow_expansion(True)
    .expansion_policy("automatic")
    .expansion_threshold(0.8)
    .snapshot_enabled(True)
    .snapshot_schedule("0 1 * * *")
    .snapshot_retention(7)
    .replication_enabled(True)
    .replication_factor(3)
    .replication_zones(["us-west1-a", "us-west1-b", "us-west1-c"])
    .namespace("production")
    .add_labels({
        "environment": "production",
        "team": "platform",
        "tier": "storage"
    })
    .add_annotations({
        "description": "Production data volume",
        "owner": "platform-team@company.com",
        "backup-schedule": "daily"
    }))

# Generate manifests
production_volume.generate().to_yaml("./k8s/")

Volume Patterns¶

Database Volume Pattern¶

# Database volume with high performance
db_volume = (Volume("database-data")
    .size("500Gi")
    .storage_class("premium-ssd")
    .access_mode("ReadWriteOnce")
    .mount_path("/var/lib/postgresql/data")
    .iops(5000)
    .throughput("1Gi")
    .performance_tier("premium")
    .backup_enabled(True)
    .backup_schedule("0 2 * * *")
    .backup_retention(90)
    .encryption_enabled(True)
    .replication_enabled(True)
    .replication_factor(3))

Application Data Volume Pattern¶

# Application data volume
app_volume = (Volume("app-data")
    .size("50Gi")
    .storage_class("fast-ssd")
    .access_mode("ReadWriteOnce")
    .mount_path("/app/data")
    .backup_enabled(True)
    .backup_schedule("0 3 * * *")
    .backup_retention(30)
    .encryption_enabled(True)
    .allow_expansion(True)
    .expansion_threshold(0.8))

Shared Volume Pattern¶

# Shared volume for multiple pods
shared_volume = (Volume("shared-data")
    .size("200Gi")
    .storage_class("standard-ssd")
    .access_mode("ReadWriteMany")
    .mount_path("/shared/data")
    .backup_enabled(True)
    .backup_schedule("0 4 * * *")
    .backup_retention(60)
    .replication_enabled(True)
    .replication_factor(2))

Config Volume Pattern¶

# Configuration volume
config_volume = (Volume("config-data")
    .size("1Gi")
    .storage_class("standard-ssd")
    .access_mode("ReadOnlyMany")
    .mount_path("/etc/config")
    .read_only(True)
    .backup_enabled(True)
    .backup_schedule("0 5 * * *")
    .backup_retention(90))

Best Practices¶

1. Choose Appropriate Storage Class¶

# ✅ Good: Use appropriate storage class
volume = Volume("database-data").storage_class("premium-ssd")  # For databases
volume = Volume("app-data").storage_class("fast-ssd")          # For applications
volume = Volume("backup-data").storage_class("standard-hdd")   # For backups

# ❌ Bad: Use wrong storage class
volume = Volume("database-data").storage_class("standard-hdd")  # Slow for database

2. Enable Backup for Important Data¶

# ✅ Good: Enable backup for important data
volume = Volume("app-data").backup_enabled(True).backup_schedule("0 2 * * *")

# ❌ Bad: No backup for important data
volume = Volume("app-data")  # No backup

3. Use Encryption for Sensitive Data¶

# ✅ Good: Enable encryption for sensitive data
volume = Volume("app-data").encryption_enabled(True)

# ❌ Bad: No encryption for sensitive data
volume = Volume("app-data")  # No encryption

4. Allow Volume Expansion¶

# ✅ Good: Allow volume expansion
volume = Volume("app-data").allow_expansion(True).expansion_threshold(0.8)

# ❌ Bad: No expansion capability
volume = Volume("app-data")  # No expansion

5. Use Appropriate Access Modes¶

# ✅ Good: Use appropriate access mode
volume = Volume("database-data").access_mode("ReadWriteOnce")  # Single node
volume = Volume("shared-data").access_mode("ReadWriteMany")    # Multiple nodes

# ❌ Bad: Use wrong access mode
volume = Volume("database-data").access_mode("ReadWriteMany")  # Can cause issues

6. Set Appropriate Size¶

# ✅ Good: Set appropriate size with room for growth
volume = Volume("app-data").size("50Gi")

# ❌ Bad: Set too small size
volume = Volume("app-data").size("1Gi")  # Too small

App - For stateless applications
StatefulApp - For stateful applications
ConfigMap - For configuration data
Secret - For sensitive data
Service - For service discovery

Next Steps¶

ConfigMap - Learn about configuration management
Components Overview - Explore all available components
Examples - See real-world examples
Tutorials - Step-by-step guides