---

name: longhorn compatibility: opencode completeness: 95 content-types:

• guidance
• examples
• do-dont
• config description: '"Longhorn in Cloud Native Storage - cloud native architecture, patterns" pitfalls, and best practices' license: MIT maturity: stable metadata: domain: cncf output-format: manifests related-skills: calico, cilium, container-network-interface-cni, contour role: reference scope: infrastructure triggers: cdn, infrastructure as code, longhorn, monitoring, native, storage, cloudformation, cloudfront archetypes:
  • educational
  • strategic anti_triggers:
  • brainstorming
  • vague ideation
  • non-containerized architecture response_profile: verbosity: medium directive_strength: low abstraction_level: strategic version: "1.0.0"

---

Longhorn in Cloud-Native Engineering

Category: storage
Status: Graduated
Stars: 4,800
Last Updated: 2026-04-22
Primary Language: Go
Documentation: https://longhorn.io/

---

Purpose and Use Cases

What Problem Does It Solve?

Longhorn addresses the critical gap in Kubernetes-native storage by providing a distributed block storage system that integrates seamlessly with Kubernetes. Traditional storage solutions were either cloud-specific, complex to deploy, or lacked Kubernetes-native features like automated failover, backups, and snapshots.

When to Use This Project

Use Longhorn when you need:

• Kubernetes-native block storage with PVC support
• Automatic data replication across nodes
• Built-in backup and disaster recovery
• Storage class integration with dynamic provisioning
• High availability for stateful workloads
• Easy management through Kubernetes APIs

Key Use Cases

• Database Storage: Run PostgreSQL, MySQL, MongoDB with persistent, replicated storage
• Stateful Applications: Deploy Redis, Elasticsearch, Kafka with reliable storage
• CI/CD Pipelines: Store build artifacts and caches with redundancy
• AI/ML Workloads: Provide high-throughput storage for training data
• Backup and DR: Automated snapshots and off-cluster backups
• Multi-Cluster Storage: Sync data across multiple Kubernetes clusters

---

Architecture Design Patterns

Core Components

• Engine: Handles block device operations and data replication
• Replica: Individual copy of volume data on a node
• Controller: Manages the engine and coordinates replication
• Instance Manager: Manages engine and replica processes
• Driver: Kubernetes CSI driver for volume provisioning
• Scheduler: Schedules volumes to nodes with available resources
• Reconciler: Ensures desired state matches actual state
• Backup Controller: Manages backup creation and restoration

Component Interactions

1. User → Kubernetes API: Create PVC requesting Longhorn storage
2. Provisioner → Controller: Volume provisioning request
3. Controller → Engine: Engine management for block device
4. Engine → Replicas: Data write operations to all replicas
5. Replica → Instance Manager: Process lifecycle management
6. Instance Manager → Node: Schedule processes on appropriate nodes
7. Reconciler → All Components: Continuously sync desired state
8. Backup Controller → Object Store: Off-cluster backup storage

Data Flow Patterns

1. Volume Creation: PVC request → Provisioner → Controller → Engine → Replicas → Storage
2. Write Operation: Application → Block device → Engine → Replicas (parallel writes)
3. Read Operation: Application → Block device → Engine → Replica (quorum read)
4. Rebuild Process: Failed replica detected → New replica created → Data synced from healthy replicas
5. Backup Process: Trigger backup → Create snapshot → Send to object store → Update backup metadata
6. Restore Process: Restore backup → Download from object store → Create replica → Sync to engine

Design Principles

• Kubernetes-Native: Full CSI driver integration
• Self-Healing: Automatic recovery from node and disk failures
• Data Redundancy: Configurable replica count with automatic rebuild
• Decoupled Architecture: Engine and replica separation for flexibility
• Conflict Detection: Detect and prevent split-brain scenarios
• Backup Integration: Native integration with S3-compatible storage

---

Integration Approaches

Integration with Other CNCF Projects

• Kubernetes: Full CSI integration for PVC management
• Prometheus: Expose metrics for monitoring and alerting
• Grafana: Pre-built dashboards for storage metrics
• Tekton: Storage provisioned for CI/CD pipeline workloads
• Helm: Deploy Longhorn using Helm chart
• Rancher: Manage Longhorn through Rancher UI
• Velero: Backup and restore Longhorn volumes

API Patterns

• CSI RPCs: CreateVolume, DeleteVolume, ControllerPublish/Unpublish, NodeStage/Unstage
• Kubernetes API: PVC, PV, StorageClass, Snapshot, RestoreCRD
• Longhorn API: Direct API for volume management and operations
• Webhook: Admission controller for validation and mutation

Configuration Patterns

• StorageClass: Define Longhorn storage classes with parameters
• Volume Settings: Replica count, data locality, snapshot count
• Backup Configuration: S3 bucket, credential, and policy settings
• Node Tags: Assign nodes to specific storage pools
• Disk Configuration: Allocate disk space on nodes

Extension Mechanisms

• Custom Storage Classes: Create storage classes for specific needs
• Backup Policies: Define custom backup schedules and retention
• Volume Hooks: Execute hooks before/after operations
• Monitoring Integration: Extend metrics with custom queries

---

Common Pitfalls and How to Avoid Them

Configuration Issues

• Insufficient Disk Space: Monitor free space and configure cleanup policies
• Replica Scheduling: Ensure enough nodes have available disk space
• Network Partition: Configure proper network and firewall rules between nodes
• Backup Configuration: Verify S3 credentials and bucket accessibility
• Resource Limits: Set appropriate resource requests for engines and replicas

Performance Issues

• Slow I/O: Check disk utilization and network connectivity between nodes
• Rebuild Delays: Monitor rebuild progress and adjust priority
• Snapshot Overhead: Limit snapshot count and frequency
• Engine Contention: Avoid overprovisioning engines on single node
• Network Bottleneck: Use dedicated network for replica communication

Operational Challenges

• Node Failure: Implement automated recovery and monitoring
• Disk Failure: Replace failed disks and trigger rebuilds
• Data Corruption: Use checksums and detect silent corruption
• Backup Failures: Monitor backup status and retry mechanisms
• Upgrade Complexity: Plan upgrades carefully with rollback strategies

Security Pitfalls

• Access Control: Restrict access to Longhorn API and backend storage
• Secret Management: Use Kubernetes secrets for credentials
• Encryption: Enable encryption at rest for sensitive data
• Network Security: Isolate storage network from public access
• Audit Logging: Enable audit logs for compliance

---

Coding Practices

Idiomatic Configuration

• StorageClass Parameters: Use specific Longhorn parameters for fine-grained control
• Volume Settings: Configure settings at volume level for specific workloads
• Node Management: Tag nodes for storage pool organization
• Backup Policies: Define backup schedules and retention policies

API Usage Patterns

• PVC Creation: Standard Kubernetes PVC with Longhorn StorageClass
• Snapshot Management: Create and manage snapshots through Kubernetes API
• Backup Operations: Trigger backups via Longhorn API or Kubernetes Snapshot
• Restore Operations: Restore from backup through Longhorn API
• Volume Expansion: Expand PVC and trigger volume expansion

Observability Best Practices

• Metrics Collection: Prometheus scrape Longhorn metrics endpoint
• Alerting: Set up alerts for disk space, replica status, and rebuild status
• Dashboard: Use pre-built Grafana dashboards for storage monitoring
• Log Analysis: Monitor Longhorn component logs for issues
• Health Checks: Implement automated health checks for storage availability

Development Workflow

• Local Development: Use Longhorn for local Kubernetes storage needs
• Testing: Test storage operations in staging environment
• CI/CD Integration: Provision storage for CI/CD workloads
• Disaster Recovery: Test backup and restore procedures regularly

---

Fundamentals

Essential Concepts

• Volume: Block device exposed to Kubernetes as PVC
• Replica: Individual copy of volume data on a node
• Engine: Process managing volume I/O and replica coordination
• Snapshot: Point-in-time copy of volume data
• Backup: Snapshot copied to external object storage
• Data Locality: Preference for replicas on same node as pod
• Automated Failover: Automatic volume failover on node failure
• Rebuild: Process of creating new replica after failure

Terminology Glossary

• Volume: Kubernetes PVC backed by Longhorn block storage
• Replica: Individual copy of volume data stored on a node
• Engine: Manages volume I/O and replica coordination
• Controller: Kubernetes CSI controller for Longhorn volumes
• Replica Manager: Manages replica processes on a node
• Snapshot: Point-in-time copy of volume data
• Backup: Snapshot copied to external object storage
• Data Locality: Scheduling preference for pods and replicas
• Auto-Disaster Recovery: Automatic failover for volumes

Data Models and Types

• Volume: Configuration, status, and metadata for block device
• Replica: Disk path, node, status, and sync status
• Snapshot: Creation time, size, children, and backup status
• Backup: Volume name, snapshot name, and S3 metadata
• Node: Disk configuration, tags, and scheduling status
• Setting: Global configuration for Longhorn behavior

Lifecycle Management

• Volume Lifecycle: Create → Attach → Mount → Use → Unmount → Detach → Delete
• Replica Lifecycle: Create → Sync → Healthy → Failed → Rebuild
• Snapshot Lifecycle: Create → Use → Expire → Delete
• Backup Lifecycle: Trigger → Snapshot → Upload → Update → Cleanup

State Management

• Volume State: Creating, attached, detaching, detached, faulted
• Replica State: Running, stopped, error, unknown
• Engine State: Running, stopped, error, unknown
• Backup State: Created, creating, error, completed

---

Scaling and Deployment Patterns

Horizontal Scaling

• Storage Capacity: Add nodes with dedicated disks for Longhorn
• Replica Distribution: Distribute replicas across failure domains
• Volume Distribution: Spread volumes across multiple nodes
• Network Scaling: Use dedicated network for replica communication

High Availability

• Multi-Node Deployment: Deploy across multiple availability zones
• Automatic Failover: Fail volumes to replicas on other nodes
• Disk Failure Recovery: Automatic rebuild on disk replacement
• Node Failure Recovery: Automatic failover and rebuild

Production Deployments

• Production Cluster: Deploy Longhorn with 3+ nodes for redundancy
• Storage Class: Define storage classes for different performance needs
• Backup Destination: Configure off-cluster backup to S3-compatible storage
• Monitoring: Set up Prometheus and Grafana for monitoring

Upgrade Strategies

• Minor Version: In-place upgrade with zero-downtime
• Major Version: Follow upgrade guide with backup and testing
• Rollback Plan: Keep previous version images for rollback
• Pre-Upgrade Check: Run health checks before upgrade

Resource Management

• Disk Space: Monitor and alert on free disk space
• Memory: Configure resource requests for engine and replica processes
• CPU: Balance CPU usage across nodes
• Network: Monitor network utilization between nodes

---

Additional Resources

• Official Documentation: https://longhorn.io/docs/
• GitHub Repository: github.com/longhorn/longhorn
• CNCF Project Page: cncf.io/projects/longhorn/
• Community: Check the GitHub repository for community channels
• Versioning: Refer to project's release notes for version-specific features

---

Troubleshooting

Common Issues

1. Deployment Failures

   • Check pod logs for errors
   • Verify configuration values
   • Ensure network connectivity

2. Performance Issues

   • Monitor resource usage
   • Adjust resource limits
   • Check for bottlenecks

3. Configuration Errors

   • Validate YAML syntax
   • Check required fields
   • Verify environment-specific settings

4. Integration Problems

   • Verify API compatibility
   • Check dependency versions
   • Review integration documentation

Getting Help

• Check official documentation
• Search GitHub issues
• Join community channels
• Review logs and metrics Content generated automatically. Verify against official documentation before production use.

Examples

Basic Configuration

# Basic configuration example
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{project_name}}-config
  namespace: default
data:
  # Configuration goes here
  config.yaml: |
    # Base configuration
    # Add your settings here

Kubernetes Deployment

# Kubernetes deployment for {{project_name}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{project_name}}
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: {{project_name}}
  template:
    metadata:
      labels:
        app: {{project_name}}
    spec:
      containers:
      - name: {{project_name}}
        image: {{project_name}}:latest
        ports:
        - containerPort: 8080
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"

Kubernetes Service

# Kubernetes service for {{project_name}}
apiVersion: v1
kind: Service
metadata:
  name: {{project_name}}
  namespace: default
spec:
  selector:
    app: {{project_name}}
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

---

When to Use

Use this skill when:

• Integrating a CNCF project into Kubernetes infrastructure — You need to configure, deploy, or troubleshoot a cloud-native tool within a cluster
• Designing cloud-native architecture — You are selecting and integrating CNCF tools to solve specific infrastructure challenges
• Resolving operational issues — A CNCF component is misbehaving, underperforming, or needs configuration changes

---

Core Workflow

1. Assess Requirements — Understand the use case, scale, integration needs, and existing infrastructure. Checkpoint: Document requirements, constraints, and success criteria.

2. Design Architecture — Plan component interactions, data flow, and deployment strategy using cloud-native best practices. Checkpoint: Verify the architecture addresses all requirements and follows CNCF conventions.

3. Implement & Configure — Create manifests, configurations, and deployment scripts. Include resource limits, health checks, and observability hooks. Checkpoint: Validate all YAML against schema and test in a staging environment.

4. Deploy & Monitor — Apply manifests to the cluster, verify component health, and confirm observability is working. Checkpoint: Confirm all pods/services are running, probes passing, and metrics/alerts configured.

---

Constraints

MUST DO

• Include at least one complete working YAML manifest example
• Note when content is auto-generated vs. manually verified
• Reference relevant CNCF project documentation

MUST NOT DO

• Deploy manifests without testing in a staging environment first
• Use deprecated API versions (e.g., apps/v1beta1)
• Omit resource limits and requests in Kubernetes manifests