Ringkasan catatan keputusan arsitektur

Last reviewed 2024-08-16 UTC

Untuk membantu menjelaskan mengapa tim infrastruktur atau aplikasi Anda membuat pilihan desain tertentu , Anda dapat menggunakan catatan keputusan arsitektur (ADR). Dokumen ini menjelaskan kapan dan bagaimana cara menggunakan ADR saat Anda membangun dan menjalankan aplikasi di Google Cloud.

ADR mencatat opsi utama yang tersedia, persyaratan utama yang mendorong sebuah keputusan, dan keputusan desain itu sendiri. Anda sering menyimpan ADR dalam file Markdown di dekat codebase yang relevan dengan keputusan tersebut. Jika seseorang perlu memahami latar belakang keputusan arsitektur tertentu, seperti alasan Anda menggunakan cluster Google Kubernetes Engine (GKE) regional, mereka dapat meninjau ADR dan kemudian kode terkait.

ADR juga dapat membantu Anda menjalankan aplikasi dan layanan yang lebih andal. ADR membantu Anda memahami status saat ini dan memecahkan masalah saat terjadi masalah. ADR juga membuat kumpulan keputusan rekayasa untuk membantu deployment dan pilihan keputusan di masa mendatang.

Kapan harus menggunakan ADR

Anda menggunakan ADR untuk melacak area utama yang menurut Anda penting untuk deployment. Kategori berikut mungkin ada di ADR Anda:

  • Pilihan produk tertentu, seperti pilihan antara Pub/Sub dan Cloud Tasks.
  • Opsi dan konfigurasi produk tertentu, seperti penggunaan cluster GKE regional dengan Multi Cluster Ingress untuk aplikasi yang sangat tersedia.
  • Panduan arsitektur umum, seperti praktik terbaik untuk manifes Dockerfile.

Beberapa contoh spesifik yang mungkin meminta Anda untuk membuat ADR adalah untuk pilihan berikut:

  • Bagaimana dan mengapa Anda menyiapkan ketersediaan tinggi (HA) untuk instance Cloud SQL?
  • Bagaimana cara Anda menangani waktu beroperasi cluster GKE? Apakah Anda menggunakan cluster regional? Apakah Anda menggunakan rilis terbatas? Apa alasannya?

Saat Anda mengevaluasi produk yang akan digunakan, ADR membantu menjelaskan setiap keputusan Anda. Anda dapat melihat kembali ADR seiring perkembangan tim dan mempelajari lebih lanjut stack dan keputusan tambahan dibuat atau disesuaikan. Jika Anda melakukan penyesuaian, sertakan keputusan sebelumnya dan mengapa perubahan dilakukan. Histori ini menyimpan catatan tentang perubahan arsitektur seiring berkembangnya kebutuhan bisnis, atau ketika ada persyaratan teknis baru atau solusi yang tersedia.

Petunjuk berikut membantu Anda mengetahui waktu untuk membuat ADR:

  • Saat Anda memiliki tantangan atau pertanyaan teknis, dan tidak ada dasar untuk mengambil keputusan, seperti solusi yang direkomendasikan, prosedur operasi standar, cetak biru, atau code base.
  • Saat Anda atau tim menawarkan solusi yang tidak didokumentasikan di tempat yang dapat diakses oleh tim.
  • Ketika ada dua atau beberapa opsi engineering dan Anda ingin mendokumentasikan pemikiran dan alasan di balik pilihan tersebut.

Saat Anda menulis ADR, ada baiknya untuk mempertimbangkan calon pembaca. Pembaca utama adalah anggota tim yang menangani teknologi yang dicakup oleh ADR. Grup calon pembaca ADR yang lebih luas mungkin terdiri dari tim pendamping yang ingin memahami keputusan Anda, seperti tim arsitektur dan keamanan.

Anda juga harus mempertimbangkan bahwa aplikasi dapat mengubah pemilik atau menyertakan anggota tim baru. ADR membantu kontributor baru memahami latar belakang pilihan rekayasa yang dibuat. ADR juga memudahkan merencanakan kperubaha di masa depan.

Format ADR

ADR biasanya terdiri dari sekumpulan bab. ADR harus membantu menangkap hal yang Anda rasa penting bagi aplikasi dan organisasi. Beberapa ADR mungkin sepanjang satu halaman, sedangkan yang lain memerlukan penjelasan yang lebih panjang.

Contoh kerangka ADR berikut menunjukkan cara memformat ADR untuk menyertakan informasi yang penting bagi lingkungan Anda:

  • Penulis dan tim
  • Konteks dan masalah yang ingin Anda selesaikan
  • Persyaratan fungsional dan non-fungsional yang ingin Anda tangani
  • Potensi perjalanan penting pengguna (CUJ) yang dipengaruhi oleh keputusan
  • Ringkasan opsi utama
  • Keputusan Anda dan alasan di balik pilihan yang diterima

Untuk membantu menyimpan data keputusan, Anda dapat menyertakan stempel waktu untuk setiap keputusan yang ditampilkan kapan pilihan dibuat.

Cara kerja ADR

ADR berfungsi paling baik saat engineer, developer, atau pemilik aplikasi dapat dengan mudah mengakses informasi yang ada di dalamnya. Ketika mereka memiliki pertanyaan tentang mengapa sesuatu dilakukan dengan cara tertentu, mereka dapat melihat ADR untuk menemukan jawabannya.

Agar ADR dapat diakses, beberapa tim menghostingnya di wiki pusat yang juga dapat diakses oleh pemilik bisnis, bukan di repositori kontrol sumber. Ketika seseorang memiliki pertanyaan tentang keputusan rekayasa tertentu, ADR ada untuk memberikan jawaban.

ADR berfungsi dengan baik dalam skenario berikut:

  • Orientasi: Anggota tim baru dapat dengan mudah mempelajari project, dan mereka dapat meninjau ADR jika memiliki pertanyaan saat mempelajari codebase baru.
  • Evolusi arsitektur: Jika ada transfer technology stack antartim, pemilik baru dapat meninjau keputusan sebelumnya untuk memahami status saat ini. Tim juga dapat meninjau keputusan sebelumnya jika ada teknologi baru yang tersedia untuk mereka. ADR dapat membantu tim menghindari pengulangan poin diskusi yang sama, dan dapat membantu memberikan konteks historis saat tim meninjau kembali topik.
  • Membagikan praktik terbaik: Tim dapat menyelaraskan praktik terbaik di seluruh organisasi saat ADR menjelaskan alasan keputusan tertentu dibuat dan alternatif ditetapkan.

ADR sering kali ditulis dalam Markdown agar tetap ringan dan berbasis teks. File Markdown dapat disertakan dalam repositori kontrol sumber bersama kode aplikasi Anda.

Simpan ADR di dekat kode aplikasi, idealnya di sistem kontrol versi yang sama. Saat melakukan perubahan pada ADR, Anda dapat meninjau versi sebelumnya dari kontrol sumber sesuai kebutuhan.

Anda juga dapat menggunakan media lain seperti Google Dokumen bersama atau wiki internal. Lokasi alternatif ini mungkin lebih mudah diakses oleh pengguna yang bukan bagian dari tim ADR. Opsi lainnya adalah membuat ADR di repositori kontrol sumber, tetapi mencerminkan keputusan utama ke dalam wiki yang lebih mudah diakses.

Langkah selanjutnya