Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Praktik terbaik untuk struktur dasar kode dan organisasi

Struktur dan organisasi basis kode yang tepat sangat penting karena penggunaan Terraform tumbuh di seluruh tim dan perusahaan besar. Basis kode yang dirancang dengan baik memungkinkan kolaborasi dalam skala besar sekaligus meningkatkan pemeliharaan.

Bagian ini memberikan rekomendasi tentang modularitas Terraform, konvensi penamaan, dokumentasi, dan standar pengkodean yang mendukung kualitas dan konsistensi.

Panduan termasuk memecah konfigurasi menjadi modul yang dapat digunakan kembali berdasarkan lingkungan dan komponen, menetapkan konvensi penamaan dengan menggunakan awalan dan sufiks, mendokumentasikan modul dan menjelaskan input dan output dengan jelas, dan menerapkan aturan pemformatan yang konsisten dengan menggunakan pemeriksaan gaya otomatis.

Praktik terbaik tambahan mencakup pengorganisasian modul dan sumber daya secara logis dalam hierarki terstruktur, membuat katalog modul publik dan pribadi dalam dokumentasi, dan mengabstraksi detail implementasi yang tidak perlu dalam modul untuk menyederhanakan penggunaan.

Dengan menerapkan pedoman struktur dasar kode seputar modularitas, dokumentasi, standar, dan organisasi logis, Anda dapat mendukung kolaborasi luas di seluruh tim sambil menjaga Terraform tetap dapat dipertahankan saat penggunaan menyebar di seluruh organisasi. Dengan menegakkan konvensi dan standar, Anda dapat menghindari kompleksitas basis kode yang terfragmentasi.

Menerapkan struktur repositori standar

Kami menyarankan Anda menerapkan tata letak repositori berikut. Standarisasi praktik konsistensi ini di seluruh modul meningkatkan kemampuan ditemukan, transparansi, organisasi, dan keandalan sambil memungkinkan penggunaan kembali di banyak konfigurasi Terraform.

Struktur modul root

Terraform selalu berjalan dalam konteks modul root tunggal. Konfigurasi Terraform lengkap terdiri dari modul root dan pohon modul anak (yang mencakup modul yang dipanggil oleh modul root, modul apa pun yang disebut oleh modul tersebut, dan sebagainya).

Contoh dasar tata letak modul root Terraform:

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

Struktur modul yang dapat digunakan kembali

Modul yang dapat digunakan kembali mengikuti konsep yang sama dengan modul root. Untuk mendefinisikan modul, buat direktori baru untuk itu dan tempatkan .tf file di dalamnya, sama seperti Anda akan mendefinisikan modul root. Terraform dapat memuat modul baik dari jalur relatif lokal atau dari repositori jarak jauh. Jika Anda mengharapkan modul digunakan kembali oleh banyak konfigurasi, letakkan di repositori kontrol versinya sendiri. Sangat penting untuk menjaga pohon modul relatif datar untuk membuatnya lebih mudah untuk menggunakan kembali modul dalam kombinasi yang berbeda.

Contoh dasar tata letak modul Terraform yang dapat digunakan kembali:

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

Struktur untuk modularitas

Pada prinsipnya, Anda dapat menggabungkan sumber daya apa pun dan konstruksi lain ke dalam modul, tetapi terlalu sering menggunakan modul bersarang dan dapat digunakan kembali dapat membuat konfigurasi Terraform Anda secara keseluruhan lebih sulit untuk dipahami dan dipelihara, jadi gunakan modul ini dalam jumlah sedang.

Jika masuk akal, pisahkan konfigurasi Anda menjadi modul yang dapat digunakan kembali yang meningkatkan tingkat abstraksi dengan menjelaskan konsep baru dalam arsitektur Anda yang dibangun dari tipe sumber daya.

Saat Anda memodulasi infrastruktur Anda menjadi definisi yang dapat digunakan kembali, arahkan kumpulan sumber daya yang logis alih-alih komponen individual atau koleksi yang terlalu kompleks.

Jangan membungkus sumber daya tunggal

Anda tidak boleh membuat modul yang merupakan pembungkus tipis di sekitar jenis sumber daya tunggal lainnya. Jika Anda kesulitan menemukan nama untuk modul Anda yang berbeda dari nama tipe sumber daya utama di dalamnya, modul Anda mungkin tidak membuat abstraksi baru―itu menambahkan kompleksitas yang tidak perlu. Sebagai gantinya, gunakan jenis sumber daya secara langsung di modul panggilan.

Merangkum hubungan logis

Kumpulan kumpulan sumber daya terkait seperti fondasi jaringan, tingkatan data, kontrol keamanan, dan aplikasi. Modul yang dapat digunakan kembali harus merangkum bagian infrastruktur yang bekerja sama untuk memungkinkan suatu kemampuan.

Jaga agar warisan tetap rata

Saat Anda membuat modul sarang di subdirektori, hindari kedalaman lebih dari satu atau dua level. Struktur pewarisan yang sangat bersarang memperumit konfigurasi dan pemecahan masalah. Modul harus dibangun di atas modul lain―bukan membangun terowongan melaluinya.

Dengan memfokuskan modul pada pengelompokan sumber daya logis yang mewakili pola arsitektur, tim dapat dengan cepat mengkonfigurasi fondasi infrastruktur yang andal. Seimbangkan abstraksi tanpa rekayasa berlebihan atau penyederhanaan berlebihan.

Sumber referensi dalam output

Untuk setiap sumber daya yang didefinisikan dalam modul yang dapat digunakan kembali, sertakan setidaknya satu output yang mereferensikan sumber daya. Variabel dan output memungkinkan Anda menyimpulkan dependensi antara modul dan sumber daya. Tanpa output apa pun, pengguna tidak dapat memesan modul Anda dengan benar sehubungan dengan konfigurasi Terraform mereka.

Modul terstruktur dengan baik yang memberikan konsistensi lingkungan, pengelompokan berdasarkan tujuan, dan referensi sumber daya yang diekspor memungkinkan kolaborasi Terraform di seluruh organisasi dalam skala besar. Tim dapat merakit infrastruktur dari blok bangunan yang dapat digunakan kembali.

Jangan mengkonfigurasi penyedia

Meskipun modul bersama mewarisi penyedia dari modul panggilan, modul tidak boleh mengonfigurasi pengaturan penyedia sendiri. Hindari menentukan blok konfigurasi penyedia dalam modul. Konfigurasi ini seharusnya hanya dideklarasikan sekali secara global.

Deklarasikan penyedia yang diperlukan

Meskipun konfigurasi penyedia dibagi antar modul, modul bersama juga harus mendeklarasikan persyaratan penyedia mereka sendiri. Praktik ini memungkinkan Terraform untuk memastikan bahwa ada satu versi penyedia yang kompatibel dengan semua modul dalam konfigurasi, dan untuk menentukan alamat sumber yang berfungsi sebagai pengidentifikasi global (modul-agnostik) untuk penyedia. Namun, persyaratan penyedia khusus modul tidak menentukan pengaturan konfigurasi apa pun yang menentukan titik akhir jarak jauh apa yang akan diakses penyedia, seperti. Wilayah AWS

Dengan mendeklarasikan persyaratan versi dan menghindari konfigurasi penyedia hardcode, modul menyediakan portabilitas dan penggunaan kembali di seluruh konfigurasi Terraform menggunakan penyedia bersama.

Untuk modul bersama, tentukan versi penyedia minimum yang diperlukan di blok required_providers di. versions.tf

Untuk menyatakan bahwa modul memerlukan versi AWS penyedia tertentu, gunakan required_providers blok di dalam blok: terraform

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

Jika modul bersama hanya mendukung versi AWS penyedia tertentu, gunakan operator kendala pesimis (~>), yang hanya mengizinkan komponen versi paling kanan untuk bertambah:

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

Dalam contoh ini, ~> 4.0 memungkinkan instalasi 4.57.1 dan 4.67.0 tetapi tidak5.0.0. Untuk informasi selengkapnya, lihat Version Constraint Syntax dalam dokumentasi. HashiCorp

Ikuti konvensi penamaan

Nama yang jelas dan deskriptif menyederhanakan pemahaman Anda tentang hubungan antara sumber daya dalam modul dan tujuan nilai konfigurasi. Konsistensi dengan pedoman gaya meningkatkan keterbacaan bagi pengguna modul dan pengelola.

Ikuti panduan untuk penamaan sumber daya

Ikuti panduan untuk penamaan variabel

Gunakan sumber daya lampiran

Beberapa sumber daya memiliki sumber daya semu yang disematkan sebagai atribut di dalamnya. Jika memungkinkan, Anda harus menghindari penggunaan atribut sumber daya yang disematkan ini dan menggunakan sumber daya unik untuk melampirkan sumber daya semu tersebut. Hubungan sumber daya ini dapat menyebabkan cause-and-effect masalah yang unik untuk setiap sumber daya.

Menggunakan atribut tertanam (hindari pola ini):

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

Menggunakan sumber daya lampiran (lebih disukai):

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

Gunakan tag default

Tetapkan tag ke semua sumber daya yang dapat menerima tag. AWS Penyedia Terraform memiliki sumber data aws_default_tags yang harus Anda gunakan di dalam modul root.

Pertimbangkan untuk menambahkan tag yang diperlukan ke semua sumber daya yang dibuat oleh modul Terraform. Berikut daftar kemungkinan tag untuk dilampirkan:

Memenuhi persyaratan registri Terraform

Repositori modul harus memenuhi semua persyaratan berikut sehingga dapat dipublikasikan ke registri Terraform.

Anda harus selalu mengikuti persyaratan ini bahkan jika Anda tidak berencana untuk mempublikasikan modul ke registri dalam jangka pendek. Dengan demikian, Anda dapat mempublikasikan modul ke registri nanti tanpa harus mengubah konfigurasi dan struktur repositori.

Untuk informasi selengkapnya, lihat Mempersiapkan Repositori Modul dalam dokumentasi Terraform.

Gunakan sumber modul yang direkomendasikan

Terraform menggunakan source argumen dalam blok modul untuk menemukan dan mengunduh kode sumber untuk modul anak.

Kami menyarankan Anda menggunakan jalur lokal untuk modul terkait erat yang memiliki tujuan utama untuk memfaktorkan elemen kode berulang, dan menggunakan registri modul Terraform asli atau penyedia VCS untuk modul yang dimaksudkan untuk dibagikan oleh beberapa konfigurasi.

Contoh berikut menggambarkan jenis sumber yang paling umum dan direkomendasikan untuk berbagi modul. Modul registri mendukung pembuatan versi. Anda harus selalu memberikan versi tertentu, seperti yang ditunjukkan pada contoh berikut.

Registri

Registri Terraform:

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

Dengan menyematkan hash komit, Anda dapat menghindari penyimpangan dari pendaftar publik yang rentan terhadap serangan rantai pasokan.

Terraform HCP:

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Perusahaan Terraform:

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Penyedia VCS

Penyedia VCS mendukung ref argumen untuk memilih revisi tertentu, seperti yang ditunjukkan pada contoh berikut.

GitHub (HTTPS):

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Repositori Git Generik (HTTPS):

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Repositori Git Generik (SSH):

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Ikuti standar pengkodean

Terapkan aturan dan gaya pemformatan Terraform yang konsisten di semua file konfigurasi. Menegakkan standar dengan menggunakan pemeriksaan gaya otomatis di pipa CI/CD. Saat Anda menyematkan praktik terbaik pengkodean ke dalam alur kerja tim, konfigurasi tetap dapat dibaca, dipelihara, dan kolaboratif karena penggunaan menyebar luas di seluruh organisasi.

Ikuti pedoman gaya

Konfigurasikan kait pra-komit

Konfigurasikan kait pra-komit sisi klien yang menjalankanterraform fmt,, tflintcheckov, dan pemindaian kode lainnya serta pemeriksaan gaya sebelum Anda mengizinkan komit. Praktik ini membantu Anda memvalidasi kesesuaian standar sebelumnya dalam alur kerja pengembang.

Gunakan kerangka kerja pra-komit seperti pra-komit untuk menambahkan linting Terraform, pemformatan, dan pemindaian kode sebagai kait pada mesin lokal Anda. Hooks berjalan pada setiap komit Git dan gagal komit jika pemeriksaan tidak lolos.

Memindahkan gaya dan pemeriksaan kualitas ke kait pra-komit lokal memberikan umpan balik cepat kepada pengembang sebelum perubahan diperkenalkan. Standar menjadi bagian dari alur kerja pengkodean.