$ show thelastpickle/cassandra-medusa
Cassandra Medusa is a production-grade backup and restore tool for Apache Cassandra and DSE, designed to operate at cluster scale. It supports full and differential backups, with storage backends for local filesystems, S3-compatible object stores, Google Cloud Storage, Azure Blob Storage, and IBM Cloud. The tool operates in two modes: a CLI that orchestrates backups across nodes via parallel SSH (pssh), and a gRPC service for Kubernetes sidecar deployments. Backups are stored as indexed blobs (token maps, manifests, schemas) in the chosen storage, with configurable retention and purge policies. It also provides integrity verification (MD5 checksums), monitoring integration (DogStatsD), and snapshot management via nodetool, Jolokia, or the DSE Management API. The architecture is modular: storage backends inherit from an abstract async base class, snapshot creation is abstracted via a service factory, and monitoring is pluggable. Configuration is loaded from INI files, environment variables, and Kubernetes secrets. The codebase uses asyncio for concurrent uploads/downloads with configurable concurrency, tenacity for retry logic, and protocol buffers for the gRPC interface. While primarily an operational tool, its design patterns (abstract storage, factory-based snapshot services, monitoring abstractions) are cleanly separated and could serve as a reference for similar infrastructure tools. Medusa is actively maintained with frequent releases, a comprehensive test suite (unit + integration behave tests), and support for Python 3.10–3.12. The codebase demonstrates solid engineering practices: strong typing (namedtuples), separation of concerns, and minimal framework boilerplate. The integration tests cover multiple storage providers, encryption modes, and cluster topologies, providing high confidence in production readiness.
The LLM identified 5 files worth highlighting for reuse:
Defines an abstract async base class for cloud storage backends. Provides generic implementations for list, upload, download, delete operations with retries via tenacity, MD5 hash generation, multipart ETag comparison, and human-readable size parsing. All concrete storage drivers (S3, GCS, Azure, local) inherit from this class, making it a clean, reusable interface for any object storage integration.
Base class for creating and deleting Cassandra snapshots via different mechanisms (nodetool, Jolokia, DSE Management API, CCM). Implements a factory pattern (from_config) that selects the appropriate implementation based on configuration (Kubernetes mode, CCM, etc.). This isolation allows snapshot logic to be swapped without affecting backup orchestration, and the pattern can be reused for other service abstractions.
Abstract monitoring interface that defines methods for emitting metrics (backup start/end, restore, purge, etc.). Implementations include a noop (default), local logging, and DogStatsD (Datadog). The pattern allows adding new monitoring backends without modifying core backup logic, and can be extracted for use in other systems requiring pluggable monitoring.
Loads configuration from INI files, environment variables (with MEDUSA_ prefix), and CLI defaults into typed namedtuples (StorageConfig, CassandraConfig, etc.). Handles Kubernetes secret injection, boolean parsing, and fallback chains. The pattern of converting a flat config dict into strongly typed namedtuples is a reusable idiom for any Python CLI tool needing structured, hierarchical configuration.
Encapsulates hostname/IP resolution logic, including special handling for Kubernetes (uses POD_IP) and fqdn derivation. Provides a simple interface to get the node's address. This small, self-contained module can be reused in any multi-node or Kubernetes-aware tool that needs consistent hostname resolution.