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 è tramite le variabili e la mappatura delle variabili.

Puoi creare implementazioni complesse, modulari e scalabili con provisioning automatico, 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 workflow di gestione in Runtime SaaS.

Unità e variabili

Le unità sono al centro di Runtime SaaS. Le unità utilizzano variabili per personalizzare la loro implementazione e il loro 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à

Anche se puoi 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 in modo esplicito nella configurazione Terraform.

Le variabili obbligatorie sono:

  • project_id e project_number (o tenant_project_id e tenant_project_id): questa variabile specifica l'ID progetto Google Cloud in cui verranno implementate le 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 console Google Cloud , 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 numero di progetto Google Cloud . Puoi utilizzare project_number o tenant_project_number in modo intercambiabile.

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

  • actuation_sa: questa variabile rappresenta l'indirizzo email del 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 tenant (o unità) per implementare il principio del privilegio minimo. Ciò limita l'impatto potenziale delle violazioni della sicurezza e fornisce un migliore isolamento tra i deployment.

    Per ulteriori informazioni sulla configurazione e la concessione delle autorizzazioni ai service account di attivazione, consulta la Panoramica del prodotto.

Gerarchia delle variabili unità

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

L'ordine è il seguente (dalla precedenza minima a quella massima):

Runtime SaaS risolve i valori delle variabili in questo ordine:

  1. Variabili di input esistenti nell'unità: se una variabile è già definita nella risorsa unità stessa (ad esempio da un'operazione o configurazione precedente), questo valore ha la precedenza più bassa. Se un valore della variabile viene impostato direttamente sull'unità, verrà sostituito se viene trovato un valore da fonti 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 ignorano le variabili dell'unità esistenti.

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

  4. Mapping delle variabili di input delle dipendenze: quando un'unità ha dipendenze da altre unità, i mapping delle variabili definiti nel tipo di unità possono ricavare i valori delle variabili dalle variabili di output delle unità di dipendenza. Questa è l'origine con la priorità più alta. Le variabili ottenute tramite le mappature delle dipendenze ignorano i valori delle operazioni unità, i valori predefiniti di rilascio e le variabili unità esistenti.

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

Dipendenze delle unità

Runtime SaaS ti consente di definire le dipendenze tra le unità. Questo è importante per la creazione di applicazioni SaaS complesse in cui i diversi componenti dipendono l'uno dall'altro. Le dipendenze garantiscono che le unità correlate vengano sottoposte al provisioning e gestite in modo coordinato.

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

Definizione della dipendenza 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 nel relativo UnitKind, Runtime SaaS verifica automaticamente l'esistenza di queste unità di dipendenza.

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

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

Mappatura delle variabili

Il mapping delle variabili è il meccanismo per trasferire i dati (valori delle variabili) tra le unità dipendenti e le relative dipendenze. È essenziale per configurare le unità dipendenti in base agli output delle loro 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 sue 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 appena sottoposto a provisioning.

  • 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 trasmettere le variabili di input tenant_project_id e tenant_project_number alla dipendenza Cluster UnitKind. In questo modo, il cluster Kubernetes viene creato nel 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, il 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 alcuna unità corrispondente, verrà eseguito il provisioning di una nuova unità di dipendenza. Ciò è utile per riutilizzare risorse condivise come i cluster.
    • true: se impostata 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 applicazione, devi utilizzare ToMapping con ignore_for_lookup impostato su true o evitare del tutto le variabili di ricerca ToMapping. Ogni unità di applicazione attiverebbe quindi il provisioning di un nuovo cluster Kubernetes isolato.

Gestire i secret

Le variabili SaaS Runtime 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 del sistema, aumentando la possibilità di accesso non autorizzato.

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

Passaggi successivi