KAPICLI: Automazione con Calma Capibara

Ho rilasciato KAPICLI, un tool da riga di comando che uso quotidianamente per automatizzare task ripetitivi.

Non è l’ennesimo framework complesso. È uno strumento pragmatico nato da necessità reali.

Cos’è KAPICLI

KAPICLI è un CLI tool in Python che racchiude script e automazioni che ho accumulato negli anni come SysAdmin e DevOps.

Cosa fa

  • Gestione configurazioni: Template, vault, variabili d’ambiente
  • Deployment automation: Script standardizzati per deploy ricorrenti
  • Backup & restore: Procedure automatizzate con verifica integrità
  • Health check: Controlli rapidi su servizi, API, infrastrutture
  • Log analysis: Parsing e analisi rapida di log comuni

Cosa NON è

  • Non è un orchestratore (usa Ansible, Terraform per quello)
  • Non è un monitoring tool (usa Prometheus, Grafana per quello)
  • Non è un framework complesso da configurare per 3 giorni

È un set di utility rapide per chi lavora ogni giorno su infrastrutture.

Perché l’ho creato

Il problema

Dopo anni di lavoro, mi sono ritrovato con:

  • Decine di script bash sparsi in directory random
  • Funzioni zsh nel mio .zshrc lungo 500 righe
  • Snippet salvati in file notes.txt mai organizzati
  • Procedure mentali che dovevo ricordare ogni volta

Ogni volta che cambiavo macchina o setup, dovevo ricostruire tutto.

Ogni volta che un collega mi chiedeva “come fai quella cosa?”, dovevo cercare, copiare, spiegare.

La soluzione

Un tool CLI unico che:

  1. Centralizza tutte le utility in un comando
  2. Standardizza le procedure in moduli consistenti
  3. Porta con me ovunque via pip install
  4. Documenta automaticamente con help integrato

Filosofia di design

KAPICLI segue principi modalità capibara:

1. Semplicità

# NO: configurazione complessa
kapicli config init --type=yaml --output=/etc/kapi --template=advanced

# YES: default sensati
kapicli config init

Default intelligenti. Override se serve. Pragmatismo first.

2. Modularità

Ogni funzionalità è un modulo indipendente:

kapicli
├── backup      # Gestione backup
├── deploy      # Automation deploy
├── health      # Health check
├── log         # Log analysis
└── vault       # Gestione secrets

Usi solo quello che ti serve. Niente bloat.

3. Sicurezza

  • Secrets mai in chiaro: integrazione con vault
  • Encryption at rest: dati sensibili sempre cifrati
  • Audit log: traccia di ogni comando eseguito
  • Permission check: verifica permessi prima di eseguire

Non è paranoia. È responsabilità.

4. Portabilità

Scritto in Python 3.9+, zero dipendenze esterne obbligatorie.

pip install kapicli

Funziona su Linux, macOS, WSL. Ovunque ci sia Python.

Esempi d’uso

Backup automatico con verifica

# Backup PostgreSQL con compressione e verifica integrità
kapicli backup db --type=postgres --name=mydb --verify

# Output:
# ✓ Database dumped: mydb_20241216_143022.sql.gz
# ✓ Compression: 8.2GB → 1.1GB (87% reduction)
# ✓ Integrity check: PASSED
# ✓ Backup stored: /backups/postgres/mydb_20241216_143022.sql.gz

Health check infrastruttura

# Check rapido servizi
kapicli health check --services=web,db,cache

# Output:
# ✓ web: nginx responding (HTTP 200) - 45ms
# ✓ db: postgresql accepting connections - port 5432 open
# ✗ cache: redis NOT responding - connection refused

Deploy standardizzato

# Deploy con rollback automatico in caso di failure
kapicli deploy run --env=production --rollback-on-error

# Output:
# → Validating deployment config...
# ✓ Config valid
# → Building artifacts...
# ✓ Build completed
# → Running pre-deploy checks...
# ✓ All checks passed
# → Deploying to production...
# ✓ Deployment successful
# → Running post-deploy health check...
# ✓ All services healthy

Gestione secrets

# Encrypt e store secret
kapicli vault set DB_PASSWORD --encrypt

# Retrieve secret (decrypted)
kapicli vault get DB_PASSWORD

# List secrets (valori nascosti)
kapicli vault list
# Output:
# DB_PASSWORD: ********
# API_KEY: ********
# SSH_PRIVATE_KEY: ********

Architettura

Core

  • Click: CLI framework (perché reinventare la ruota?)
  • Rich: Output colorato e formattato
  • Cryptography: Gestione encryption
  • YAML/JSON: Config file support

Moduli

Ogni modulo è una classe indipendente che implementa interfaccia comune:

class KapiModule:
    def validate(self) -> bool:
        """Valida input e prerequisiti"""
        
    def execute(self) -> Result:
        """Esegue l'operazione"""
        
    def rollback(self) -> bool:
        """Rollback in caso di errore"""

Predictable. Testable. Maintainable.

Estendibilità

Puoi creare moduli custom:

# ~/.kapicli/modules/my_module.py

from kapicli import KapiModule

class MyCustomModule(KapiModule):
    def execute(self):
        # Your logic here
        pass

Poi usarlo:

kapicli custom my-module --param=value

Non ti forzo il mio modo. Adatta al tuo.

Roadmap

KAPICLI è work in progress. Prossime feature:

  • Remote execution: Esegui su host remoti via SSH
  • Scheduling: Cron-like scheduling integrato
  • Notifications: Alert su Slack/Discord/Email
  • Plugin system: Marketplace moduli community
  • TUI mode: Interfaccia testuale interattiva

Prova KAPICLI

Installazione

pip install kapicli

Quick start

# Help generale
kapicli --help

# Help modulo specifico
kapicli backup --help

# Esempio: backup database
kapicli backup db --type=postgres --name=mydb

Documentazione completa

kapicli.middei.info

  • Guide per ogni modulo
  • Esempi pratici
  • Best practices
  • FAQ

Contributi

KAPICLI è open source (licenza MIT).

Se vuoi contribuire:

  • Issues: segnala bug o proponi feature
  • PR: contribuisci codice
  • Docs: migliora la documentazione
  • Moduli: crea e condividi moduli custom

Repo: github.com/stanzinofree/kapicli

Perché condividerlo

Perché probabilmente hai anche tu:

  • Script bash sparsi ovunque
  • Procedure che devi ricordare a memoria
  • Task ripetitivi che ti fanno perdere tempo
  • Colleghi che ti chiedono sempre “come si fa?”

KAPICLI potrebbe essere la risposta. O almeno un buon punto di partenza per creare il tuo.

Filosofia capibara applicata

KAPICLI nasce da calma operativa:

  • Non inseguo l’hype (Go, Rust, etc.). Python funziona, è diffuso, è manutenibile.
  • Non creo framework complicati. Creo tool che risolvono problemi reali.
  • Non faccio over-engineering. Faccio ciò che serve, fatto bene.

Modalità capibara: pragmatismo, semplicità, efficacia.

Automatizza con calma. Usa KAPICLI.

🦫

kapicli.middei.info