Skip to main content

​
Segreti

Kazzle ha un vault crittografato integrato per archiviare chiavi API, credenziali di database, token e altri valori sensibili di cui la tua app ha bisogno. I segreti sono crittografati a riposo con AES-256-GCM utilizzando chiavi di crittografia dei dati avvolte da KMS — i valori in chiaro non toccano mai il database.

​
Concetti

Collections raggruppano segreti correlati insieme (ad es. stripe-keys, database-credentials). Ogni collection ha uno slug (minuscolo, con trattini) che referenzi nei file di configurazione e nei comandi CLI. Environments sono ambiti facoltativi all’interno di una collection (ad es. production, staging). I segreti possono essere limitati a un ambiente specifico o lasciati a livello di collection come valori predefiniti. Ordine di risoluzione: quando si risolvono i segreti per una determinata collection + environment, i segreti specifici dell’ambiente sovrascrivono i segreti a livello di collection con lo stesso nome. Questo ti permette di condividere la maggior parte dei segreti tra gli ambienti mentre sovrascrivi valori specifici per ambiente.

​
Gestione dei segreti

​
Nell’app

Apri Settings > Vault per creare collection, environment e segreti tramite l’interfaccia utente.

​
Con l’AI

L’AI può creare collection, creare environment, archiviare segreti, spostarli tra ambiti ed eliminarli per te. L’AI vede i nomi dei segreti e i metadati ma non i valori crittografati.

​
Con la CLI

​
Referenziare i segreti dalla tua app

Punta l’env di un componente a una collection di segreti e a un environment in kazzle.config.ts. Ogni segreto in quell’ambito viene iniettato come variabile di ambiente di processo il cui nome corrisponde al nome del segreto:
env.collection e env.environment sono slug, non nomi visualizzati. Usa env.include per iniettare solo un sottoinsieme dei segreti della collection:

​
Come i segreti diventano variabili di ambiente

Quando i segreti vengono risolti per un componente:
  1. La collection viene trovata per slug all’interno del tuo space
  2. I segreti limitati all’environment specificato vengono caricati
  3. I segreti a livello di collection (senza environment) vengono inclusi come valori predefiniti
  4. I segreti specifici dell’environment sovrascrivono quelli a livello di collection con lo stesso nome
  5. I riferimenti ai segreti all’interno dei valori vengono risolti
  6. I nomi dei segreti vengono convertiti nel formato di variabile di ambiente: maiuscoli, i caratteri non alfanumerici diventano trattini bassi
Un segreto denominato Stripe Secret Key diventa STRIPE_SECRET_KEY. Ogni segreto ha una body mode che determina come viene iniettato:
  • I segreti string (chiavi API, token, URI) vengono iniettati come stringhe scalari semplici
  • I segreti json (configurazione strutturata) vengono iniettati come stringhe JSON
  • I segreti fields (credenziali di accesso, borse di campi tipizzati) vengono iniettati come stringhe JSON

​
Quando i segreti vengono iniettati

​
Riferimenti ai template

I valori dei segreti possono referenziare altri campi di segreti con la stessa sintassi che Kazzle usa altrove:
Formati supportati:
  • ${secret.<uuid>.<field>} — campo specifico o percorso JSON all’interno di valori di segreti o parametri di strumenti dove i riferimenti al vault sono abilitati.
  • ${secret.<uuid>} — corpo del segreto intero. Usa solo quando uno strumento chiede esplicitamente il segreto grezzo intero; non usare questo nella configurazione/env dell’app.
I riferimenti vengono risolti dopo che i segreti sono stati caricati. I riferimenti circolari o interrotti falliscono invece di tornare silenziosamente indietro.