Variabel dan pemetaan variabel dengan SaaS Runtime

Dokumen ini menjelaskan cara kerja variabel, pemetaan variabel, dan dependensi dalam SaaS Runtime.

Runtime SaaS memungkinkan Anda men-deploy dan mengelola aplikasi SaaS yang kompleks dengan mengaturnya ke dalam unit modular. Unit ini, yang ditentukan oleh konfigurasi Terraform dalam blueprint, dapat saling terhubung melalui dependensi, sehingga memungkinkan orkestrasi yang canggih dan penyediaan otomatis. Aspek utama dalam mengelola unit ini dan interaksinya adalah melalui variabel dan pemetaan variabel.

Anda dapat membangun deployment yang kompleks, modular, dan skalabel dengan penyediaan otomatis, komunikasi antar-unit, dan opsi konfigurasi yang fleksibel. Pertimbangkan dengan cermat hierarki variabel, hubungan dependensi, dan pemetaan variabel untuk mengoptimalkan arsitektur SaaS dan alur kerja pengelolaan Anda dalam SaaS Runtime.

Unit dan variabel

Inti dari SaaS Runtime adalah unit. Unit menggunakan variabel untuk menyesuaikan deployment dan perilakunya. Variabel ini pada dasarnya adalah variabel Terraform yang dapat Anda tentukan dalam file variables.tf cetak biru. Dengan variabel, Anda dapat memparameterisasi konfigurasi Terraform, sehingga dapat digunakan kembali dan disesuaikan di berbagai lingkungan dan deployment.

Variabel wajib untuk penyediaan unit

Meskipun Anda dapat menentukan variabel kustom untuk unit, SaaS Runtime juga mengandalkan serangkaian variabel wajib. Variabel ini secara otomatis dikenali dan ditangani oleh SaaS Runtime, meskipun tidak didefinisikan secara eksplisit dalam konfigurasi Terraform Anda.

Variabel wajibnya adalah:

  • project_id dan project_number (atau, tenant_project_id dan tenant_project_id): Variabel ini menentukan Google Cloud project ID tempat resource unit Anda akan di-deploy. Anda dapat menggunakan project_id dan project_number, atau tenant_id dan tenant_project_id. Kolom ini diperlukan untuk pembuatan dan pengelolaan resource dalam project yang benar. Google Cloud

    Anda dapat menemukan project ID di konsol Google Cloud pada halaman Dasbor. Cari kolom Project ID di kartu Project info dalam bagian Cloud overview.

  • project_number atau tenant_project_number: Mirip dengan project_id, variabel ini merepresentasikan nomor Google Cloud project. Anda dapat menggunakan project_number atau tenant_project_number secara bergantian.

    Anda dapat menemukan nomor project di samping project ID di kartu Project info dalam bagian Cloud overview di Google Cloud halaman Dasbor konsol.

  • actuation_sa: Variabel ini mewakili alamat email akun layanan aktivasi. Akun layanan ini adalah akun layanan yang dikelola pengguna yang digunakan SaaS Runtime (melalui Infrastructure Manager) untuk mengeksekusi konfigurasi Terraform Anda saat menyediakan, memperbarui, atau membatalkan penyediaan unit.

    Sebaiknya gunakan akun layanan aktuasi khusus per tenant (atau unit) untuk menerapkan prinsip hak istimewa terendah. Hal ini membatasi potensi dampak pelanggaran keamanan dan memberikan isolasi yang lebih baik di antara deployment Anda.

    Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi dan memberikan izin ke akun layanan aktuasi, lihat Ringkasan produk.

Hierarki variabel unit

Variabel unit dapat ditentukan dan bersumber dari beberapa lokasi. Saat menggunakan SaaS Runtime, Anda harus memahami hierarki nilai variabel yang digunakan selama operasi unit.

Urutannya adalah sebagai berikut (dari prioritas terendah hingga tertinggi):

Runtime SaaS menyelesaikan nilai variabel dalam urutan ini:

  1. Variabel input yang ada di unit: Jika variabel sudah ditentukan di resource unit itu sendiri (misalnya, dari operasi atau konfigurasi sebelumnya), nilai ini memiliki prioritas terendah. Jika nilai variabel ditetapkan langsung di unit, nilai tersebut akan diganti jika nilai ditemukan dari sumber yang lebih tinggi dalam hierarki.

  2. Default rilis: Nilai default rilis diterapkan jika variabel belum ditetapkan di unit, tetapi nilai tersebut akan menggantikan variabel unit yang ada.

  3. Operasi unit: Saat melakukan operasi unit seperti provision atau upgrade, Anda dapat memberikan variabel input secara eksplisit sebagai bagian dari permintaan operasi. Variabel yang disediakan dalam operasi unit akan menggantikan default rilis dan variabel unit yang ada.

  4. Pemetaan variabel input dependensi: Jika unit memiliki dependensi pada unit lain, pemetaan variabel yang ditentukan dalam jenis unit dapat mengambil nilai variabel dari variabel output unit dependensi. Ini adalah sumber dengan prioritas tertinggi. Variabel yang diperoleh melalui pemetaan dependensi akan mengganti nilai dari operasi unit, default rilis, dan variabel unit yang ada.

Pendekatan hierarkis ini memberikan fleksibilitas dan kontrol atas pengelolaan variabel Anda. Anda dapat membuat konfigurasi persisten langsung di unit (prioritas terendah), menentukan default dasar menggunakan rilis, menyesuaikan untuk operasi tertentu, dan secara dinamis mengambil nilai yang paling penting dan menggantikan dari dependensi unit (prioritas tertinggi).

Dependensi unit

SaaS Runtime memungkinkan Anda menentukan dependensi antar-unit. Hal ini penting untuk membangun aplikasi SaaS yang kompleks di mana berbagai komponen saling bergantung satu sama lain. Dependensi memastikan unit terkait disediakan dan dikelola secara terkoordinasi.

Anda menentukan dependensi dalam jenis unit. Saat Anda membuat unit jenis unit tertentu, SaaS Runtime akan otomatis mengelola dependensinya.

Definisi dependensi dalam jenis unit

Dalam definisi UnitKind, Anda menentukan daftar dependensi, yang masing-masing mereferensikan UnitKind lain dan menetapkan alias. Alias ini digunakan untuk mereferensikan dependensi dalam pemetaan variabel:

  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];
  }

Penyediaan dependensi otomatis

Saat Anda meminta untuk menyediakan unit yang memiliki dependensi yang ditentukan dalam UnitKind-nya, SaaS Runtime akan otomatis memeriksa keberadaan unit dependensi tersebut.

Jika unit dependensi tidak ditemukan, SaaS Runtime akan otomatis menyediakannya sebelum menyediakan unit dependen.

Runtime SaaS memastikan bahwa unit dependensi disediakan sebelum unit yang bergantung padanya, sehingga mempertahankan urutan operasi yang benar.

Pemetaan variabel

Pemetaan variabel adalah mekanisme untuk meneruskan data (nilai variabel) antara unit dependen dan dependensinya. Hal ini penting untuk mengonfigurasi unit dependen berdasarkan output dari dependensinya.

Pemetaan variabel ditentukan dalam jenis unit dependen dan menggunakan FromMapping dan ToMapping:

  • FromMapping: FromMapping digunakan untuk mengambil variabel output dari unit dependensi dan memetakannya ke variabel input unit dependen. Dengan cara ini, unit dependen dapat memperoleh informasi dari dependensinya, seperti endpoint koneksi atau ID resource.

    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];
}

    Dalam contoh codelab yang diberikan, App UnitKind memiliki FromMapping untuk mengambil variabel output cluster_endpoint dari dependensi Cluster UnitKind. Hal ini memungkinkan aplikasi terhubung ke cluster Kubernetes yang baru disediakan.

  • ToMapping: ToMapping digunakan untuk meneruskan variabel input dari unit dependen ke variabel input unit dependensi. Hal ini memungkinkan Anda mengonfigurasi unit dependensi berdasarkan parameter yang diberikan untuk unit dependen.

    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];
}

    Dalam codelab, App UnitKind menggunakan ToMapping untuk meneruskan variabel input tenant_project_id dan tenant_project_number ke dependensi Cluster UnitKind. Tindakan ini memastikan cluster Kubernetes dibuat dalam project yang benar.

  • ignore_for_lookup di ToMapping: Kolom ignore_for_lookup di ToMapping mengontrol perilaku pencarian dependensi. Nilainya adalah boolean:

    • false (atau tidak ditentukan): Jika disetel ke false, SaaS Runtime akan menggunakan variabel input yang ditentukan dalam ToMapping sebagai kunci penelusuran untuk menemukan unit dependensi yang ada. Jika unit dengan variabel input yang cocok ditemukan, unit tersebut akan digunakan kembali sebagai dependensi. Jika tidak ada unit yang cocok, unit dependensi baru akan disediakan. Hal ini berguna untuk menggunakan kembali resource bersama seperti cluster.
    • true: Jika disetel ke true, variabel input di ToMapping tidak akan digunakan untuk pencarian dependensi. Artinya, unit dependensi baru akan selalu disediakan, meskipun unit dengan variabel input yang sama sudah ada. Hal ini berguna saat Anda memerlukan dependensi khusus yang tidak dibagikan untuk setiap unit dependen.

Contoh: Cluster Kubernetes bersama

Jika Anda ingin menggunakan kembali cluster Kubernetes untuk beberapa unit aplikasi dalam project yang sama, Anda akan menggunakan ToMapping dengan ignore_for_lookup yang ditetapkan ke false dan memetakan variabel seperti tenant_project_id dan region ke jenis unit cluster. Unit dalam project dan region yang sama kemudian akan menggunakan kembali cluster yang sama.

Contoh: Cluster Kubernetes khusus per aplikasi

Jika Anda memerlukan cluster Kubernetes khusus untuk setiap unit aplikasi, Anda dapat menggunakan ToMapping dengan ignore_for_lookup yang ditetapkan ke true atau menghindari variabel pencarian ToMapping sama sekali. Setiap unit aplikasi kemudian akan memicu penyediaan cluster Kubernetes baru yang terisolasi.

Mengelola secret

Variabel SaaS Runtime tidak ditujukan untuk menyimpan informasi sensitif seperti sandi, kunci API, atau sertifikat. Menyimpan secret secara langsung dalam variabel menimbulkan risiko keamanan. Nilai variabel dapat dicatat dan berpotensi terekspos melalui output sistem, sehingga meningkatkan kemungkinan akses tidak sah.

Untuk pengelolaan secret yang aman di aplikasi SaaS Runtime Anda, sebaiknya gunakan Secret Manager.

Langkah berikutnya