Variabili e mappatura delle variabili con Runtime SaaS

Questo documento spiega come funzionano le variabili, la mappatura delle variabili e le dipendenze in Runtime SaaS.

Runtime SaaS ti consente di eseguire il deployment e gestire applicazioni SaaS complesse organizzandole in unità modulari. Queste unità, definite dalle configurazioni Terraform all'interno dei blueprint, possono essere interconnesse tramite dipendenze, consentendo un'orchestrazione sofisticata e un provisioning automatizzato. Un aspetto fondamentale della gestione di queste unità e delle loro interazioni è rappresentato dalle variabili e dalla mappatura delle variabili.

Puoi creare deployment complessi, modulari e scalabili con provisioning automatizzato, comunicazione tra unità e opzioni di configurazione flessibili. Valuta attentamente la gerarchia delle variabili, le relazioni di dipendenza e le mappature delle variabili per ottimizzare l'architettura SaaS e i flussi di lavoro di gestione in Runtime SaaS.

Unità e variabili

Le unità sono al centro di Runtime SaaS. Le unità utilizzano le variabili per personalizzare il deployment e il comportamento. Queste variabili sono essenzialmente variabili Terraform che puoi definire nel file variables.tf del blueprint. Ti consentono di parametrizzare le configurazioni Terraform, rendendole riutilizzabili e adattabili in diversi ambienti e deployment.

Variabili obbligatorie per il provisioning delle unità

Sebbene tu possa definire variabili personalizzate per le tue unità, Runtime SaaS si basa anche su un insieme di variabili obbligatorie. Queste variabili vengono riconosciute e gestite automaticamente da Runtime SaaS, anche se non sono definite esplicitamente nella configurazione Terraform.

Le variabili obbligatorie sono:

  • project_id e project_number (o tenant_project_id e tenant_project_id): questa variabile specifica l' Google Cloud ID progetto in cui verranno eseguito il deployment delle risorse dell'unità. Puoi utilizzare project_id e project_number oppure tenant_id e tenant_project_id. Questo campo è necessario per la creazione e la gestione delle risorse all'interno del progetto Google Cloud corretto.

    Puoi trovare l'ID progetto nella Google Cloud console, nella pagina della dashboard. Cerca il campo ID progetto nella scheda Informazioni sul progetto all'interno della sezione Panoramica di Cloud.

  • project_number o tenant_project_number: simile a project_id, questa variabile rappresenta il Google Cloud numero progetto. Puoi utilizzare project_number o tenant_project_number in modo intercambiabile.

    Puoi trovare il numero progetto insieme all'ID progetto nella scheda Informazioni sul progetto all'interno della sezione Panoramica di Cloud della pagina della dashboard della Google Cloud console .

  • actuation_sa: questa variabile rappresenta l'indirizzo email dell' service account di attivazione. Questo account di servizio è un account di servizio gestito dall'utente che Runtime SaaS utilizza (tramite Infrastructure Manager) per eseguire le configurazioni Terraform durante il provisioning, l'aggiornamento o il deprovisioning delle unità.

    Ti consigliamo di utilizzare un account di servizio di attivazione dedicato per ogni tenant (o unità) per implementare il principio del privilegio minimo. In questo modo, si limita il potenziale impatto delle violazioni della sicurezza e si garantisce un migliore isolamento tra i deployment.

    Per saperne di più sulla configurazione e la concessione delle autorizzazioni ai service account di attivazione, consulta la panoramica del prodotto.

Gerarchia delle variabili delle unità

Le variabili delle unità possono essere definite e recuperate da più posizioni. Quando utilizzi Runtime SaaS, è importante comprendere la gerarchia dei valori delle variabili utilizzati durante le operazioni sulle unità.

L'ordine è il seguente (dalla precedenza più bassa a quella più alta):

Runtime SaaS risolve i valori delle variabili in questo ordine:

  1. Variabili di input esistenti nell'unità: se una variabile è già definita nella risorsa dell'unità stessa (ad esempio, da un'operazione o una configurazione precedente), questo valore ha la precedenza più bassa. Se un valore di variabile è impostato direttamente nell'unità, verrà sostituito se viene trovato un valore da origini più in alto nella gerarchia.

  2. Valori predefiniti della release: i valori predefiniti della release vengono applicati se una variabile non è già impostata nell'unità, ma sostituiranno le variabili dell'unità esistenti.

  3. Operazioni sulle unità: quando esegui un'operazione sull'unità come provision o upgrade, puoi fornire esplicitamente le variabili di input come parte della richiesta di operazione. Le variabili fornite in un'operazione sull'unità sostituiranno i valori predefiniti della release e le variabili dell'unità esistenti.

  4. Mappature delle variabili di input delle dipendenze: quando un'unità ha dipendenze da altre unità, le mappature delle variabili definite nel tipo di unità possono recuperare i valori delle variabili dalle variabili di output delle unità di dipendenza. Questa è l'origine di precedenza più alta. Le variabili ottenute tramite le mappature delle dipendenze sostituiranno i valori delle operazioni sulle unità, i valori predefiniti della release e le variabili dell'unità esistenti.

Questo approccio gerarchico offre flessibilità e controllo sulla gestione delle variabili. Puoi stabilire configurazioni persistenti direttamente nell'unità (priorità più bassa), definire i valori predefiniti di base utilizzando le release, personalizzare le operazioni specifiche e recuperare dinamicamente i valori più importanti e sostitutivi dalle dipendenze delle unità (priorità più alta).

Dipendenze delle unità

Runtime SaaS ti consente di definire le dipendenze tra le unità. Questo è importante per creare applicazioni SaaS complesse in cui diversi componenti si basano l'uno sull'altro. Le dipendenze garantiscono che le unità correlate vengano sottoposte a provisioning e gestite in modo coordinato.

Definisci le dipendenze all'interno di un tipo di unità. Quando crei un'unità di un determinato tipo di unità, Runtime SaaS gestisce automaticamente le relative dipendenze.

Definizione delle dipendenze nel tipo di unità

Nella definizione di UnitKind, specifichi un elenco di dipendenze, ognuna delle quali fa riferimento a un altro UnitKind e gli assegna un alias. Questo alias viene utilizzato per fare riferimento alla dipendenza nelle mappature delle variabili:

  message UnitKind {
    // ... other fields ...

    // List of other unit kinds that this release will depend on.
    repeated Dependency dependencies = 4
        [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }

  message Dependency {
    // The unit kind of the dependency.
    string unit_kind = 1 [
      (.google.api.field_behavior) = REQUIRED,
      (.google.api.field_behavior) = IMMUTABLE,
      (.google.api.resource_reference) = {
        type: "saasservicemgmt.googleapis.com/UnitKind"
      }
    ];

    // An alias for the dependency. Used for input variable mapping.
    string alias = 2 [(.google.api.field_behavior) = REQUIRED];
  }

Provisioning automatico delle dipendenze

Quando richiedi il provisioning di un'unità con dipendenze definite in UnitKind, Runtime SaaS verifica automaticamente l'esistenza di queste unità di dipendenza.

Se non viene trovata un'unità di dipendenza, Runtime SaaS ne eseguirà automaticamente il provisioning prima di eseguire il provisioning dell'unità dipendente.

Runtime SaaS garantisce che le unità di dipendenza vengano sottoposte a provisioning prima delle unità dipendenti, mantenendo l'ordine corretto delle operazioni.

Mappatura delle variabili

La mappatura delle variabili è il meccanismo per passare i dati (valori delle variabili) tra le unità dipendenti e le relative dipendenze. Questo è essenziale per configurare le unità dipendenti in base agli output delle relative dipendenze.

La mappatura delle variabili è definita all'interno del tipo di unità dipendente e utilizza FromMapping e ToMapping:

  • FromMapping: FromMapping viene utilizzato per recuperare le variabili di output da un'unità di dipendenza e mapparle alle variabili di input dell'unità dipendente. In questo modo, un'unità dipendente può ottenere informazioni dalle relative dipendenze, come endpoint di connessione o ID risorsa.

    message VariableMapping {
  // ...
  oneof mapping_type {
    // Output variables which will get their values from dependencies
    FromMapping from = 2 [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }
}

message FromMapping {
  // Alias of the dependency that the outputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the outputVariable on the dependency
  string output_variable = 2 [(.google.api.field_behavior) = REQUIRED];
}

    Nell'esempio di codelab fornito, App UnitKind ha un FromMapping per recuperare la variabile di output cluster_endpoint dalla dipendenza Cluster UnitKind. In questo modo, l'applicazione può connettersi al cluster Kubernetes di cui è stato eseguito il provisioning di recente.

  • ToMapping: ToMapping viene utilizzato per passare le variabili di input dall'unità dipendente alle variabili di input di un'unità di dipendenza. In questo modo, puoi configurare le unità di dipendenza in base ai parametri forniti per l'unità dipendente.

    message VariableMapping {
  // ...
  oneof mapping_type {
    // ...
    // Input variables whose values will be passed on to dependencies.
    ToMapping to = 3 [(.google.api.field_behavior) = OPTIONAL];
  }
}

message ToMapping {
  // Alias of the dependency that the inputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the inputVariable on the dependency
  string input_variable = 2 [(.google.api.field_behavior) = REQUIRED];

  // Tells EasySaaS if this mapping should be used during lookup or not
  bool ignore_for_lookup = 3 [(.google.api.field_behavior) = OPTIONAL];
}

    Nel codelab, App UnitKind utilizza ToMapping per passare le variabili di input tenant_project_id e tenant_project_number alla dipendenza Cluster UnitKind. In questo modo, il cluster Kubernetes viene creato all'interno del progetto corretto.

  • ignore_for_lookup in ToMapping: il campo ignore_for_lookup in ToMapping controlla il comportamento di ricerca delle dipendenze. È un valore booleano:

    • false (o non specificato): se impostato su false, Runtime SaaS utilizzerà le variabili di input specificate in ToMapping come chiavi di ricerca per trovare un'unità di dipendenza esistente. Se viene trovata un'unità con variabili di input corrispondenti, verrà riutilizzata come dipendenza. Se non viene trovata un'unità corrispondente, verrà eseguito il provisioning di una nuova unità di dipendenza. Questa opzione è utile per riutilizzare le risorse condivise come i cluster.
    • true: se impostato su true, la variabile di input in ToMapping non verrà utilizzata per la ricerca delle dipendenze. Ciò significa che verrà sempre eseguito il provisioning di una nuova unità di dipendenza, anche se esistono già unità con le stesse variabili di input. Questa opzione è utile quando hai bisogno di dipendenze dedicate e non condivise per ogni unità dipendente.

Esempio: cluster Kubernetes condiviso

Se vuoi riutilizzare un cluster Kubernetes per più unità di applicazioni all'interno dello stesso progetto, devi utilizzare ToMapping con ignore_for_lookup impostato su false e mappare variabili come tenant_project_id e region al tipo di unità cluster. Le unità nello stesso progetto e nella stessa regione riutilizzeranno lo stesso cluster.

Esempio: cluster Kubernetes dedicato per applicazione

Se hai bisogno di un cluster Kubernetes dedicato per ogni unità di applicazioni, devi utilizzare ToMapping con ignore_for_lookup impostato su true o evitare del tutto le variabili di ricerca ToMapping. Ogni unità di applicazioni attiverà il provisioning di un nuovo cluster Kubernetes isolato.

Gestire i secret

Le variabili di Runtime SaaS non sono destinate all'archiviazione di informazioni sensibili come password, chiavi API o certificati. L'archiviazione dei secret direttamente nelle variabili comporta rischi per la sicurezza. I valori delle variabili possono essere registrati e potenzialmente esposti tramite gli output di sistema, aumentando la probabilità di accesso non autorizzato.

Per una gestione sicura dei secret nelle applicazioni Runtime SaaS, ti consigliamo vivamente di utilizzare Secret Manager.

Passaggi successivi