Terraform Mimari Diyagramı: .tf Dosyalarından İnsanların Okuyabileceği Bir Resme

Terraform altyapınızı zaten tanımlıyor: kesin olarak ve sürüm kontrolü altında. Peki neden kimse sistemi koddan anlamıyor? Çünkü bir .tf dosyası "ne var ve nasıl yapılandırılmış" sorusunu yanıtlar; mimari diyagramını okuyanlar ise başka şeyler sorar: trafik nereden giriyor, kim kiminle konuşuyor, veri nerede duruyor ve dışarıya ne açık?

Bu rehber Terraform'dan insanların okuyabileceği bir diyagrama nasıl gidileceğini gösteriyor: terraform graph neden o diyagram değil, kaynaklar çerçevelere ve kartlara nasıl eşlenir, plan JSON ne zaman kullanılır, neler dışarıda bırakılır ve sonuç pull request incelemelerinde nasıl kullanılır.

Kod ve terraform graph neden diyagram değildir

Küçük bir production yığını, birkaç dosya ve modüle dağılmış yüz kadar kaynağa kolayca ulaşır ve bunların çoğu yapıştırıcıdır: IAM politika eklemeleri, rota tablosu ilişkilendirmeleri, güvenlik grubu kuralları, hedef grup eklemeleri. "İnternet veritabanına ulaşabilir mi?" sorusunun yanıtı oradadır, ama bir düzine referansa dağılmış hâldedir.

terraform graph bunu çözmez. DOT dilinde bir graf yazdırır ve Terraform 1.7'den beri varsayılan çıktı, komut referansının ifadesiyle yalnızca kaynakların bağımlılık sırasını anlatan sadeleştirilmiş bir graftır. -type=plan gibi seçenekler, Terraform'un plan oluştururken kullandığı daha kapsamlı grafın yaklaşık bir hâlini gösterir; Terraform 1.16'dan beri -format=mermaid de DOT yerine Mermaid yazdırır.

Bir bağımlılık grafı "ne, neyden önce var olmalı" sorusunu yanıtlar. ECS servisi bir IAM rolüne, bir hedef gruba ve bir görev tanımına bağlıdır; bu yüzden oklar servisten ön koşullarına doğru gider. Bu çoğu zaman trafiğin akış yönünün tersidir ve yapıştırıcı kaynaklar veritabanı kadar yer kaplar. Bir planı ayıklamak için faydalıdır. Mimari diyagramı değildir.

Örnek yığın

AWS üzerinde tipik bir web uygulaması: iki Erişilebilirlik Alanında genel ve özel alt ağları olan bir VPC, bir Application Load Balancer, Fargate üzerinde bir ECS servisi, RDS üzerinde bir PostgreSQL veritabanı ve yüklemeler için bir S3 bucket'ı. Yapılandırmadan bir kesit:

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_subnet" "private_a" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = "10.0.11.0/24"
  availability_zone = "eu-west-1a"
}

resource "aws_lb" "web" {
  name               = "web"
  load_balancer_type = "application"
  subnets            = [aws_subnet.public_a.id, aws_subnet.public_b.id]
  security_groups    = [aws_security_group.alb.id]
}

resource "aws_ecs_service" "app" {
  name            = "app"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.app.arn
  launch_type     = "FARGATE"
  desired_count   = 2

  network_configuration {
    subnets         = [aws_subnet.private_a.id, aws_subnet.private_b.id]
    security_groups = [aws_security_group.app.id]
  }

  load_balancer {
    target_group_arn = aws_lb_target_group.app.arn
    container_name   = "app"
    container_port   = 8080
  }
}

resource "aws_db_instance" "main" {
  identifier                  = "app-db"
  engine                      = "postgres"
  instance_class              = "db.t4g.medium"
  allocated_storage           = 50
  username                    = "app"
  manage_master_user_password = true
  multi_az                    = true
  db_subnet_group_name        = aws_db_subnet_group.main.name
  vpc_security_group_ids      = [aws_security_group.db.id]
}

Terraform'u diyagrama eşlemek

İşin büyük kısmı, hangi kaynakların diyagramda bir öğe, hangilerinin başka öğelerin ayrıntısı olacağına karar vermektir:

.tf dosyaları mı, plan JSON mı

Doğrudan yapılandırmadan ya da bir plandan çalışabilirsiniz:

terraform plan -out plan.out
terraform show -json plan.out > plan.json

.tf dosyaları hızlıdır ve hiçbir şey çalıştırmayı gerektirmez, ama count ve for_each açılmaz, değişkenler bilinmez ve uzak modüller kapalı kalır. Plan JSON'da bunların hepsi çözülmüştür; resource_changes listesi de planın her kaynağa ne yapacağını söyler: ["create"], ["update"], ["delete"] ya da yeniden oluşturma için ["delete", "create"]. Bu da onu bir değişikliği incelemek için daha iyi bir girdi yapar. Dosyaya dikkat edin: terraform show dokümantasyonu, state'teki hassas değerlerin JSON çıktısında düz metin olarak göründüğü konusunda uyarır.

Diyagram

Nasıl okunur:

• Giriş. Kullanıcılar Application Load Balancer'a 443 numaralı porttan HTTPS ile ulaşır. DNS alias kaydı ona yönlendirir.
• Ağ sınırları. VPC iki çerçeve içerir: yük dengeleyici için genel alt ağlar, geri kalan her şey için özel alt ağlar. Özel alt ağlardaki hiçbir şeye internetten ulaşılamaz.
• Yol. Yük dengeleyici trafiği 8080 portundan ECS servisine iletir. Servis PostgreSQL ile 5432 üzerinden konuşur ve yüklemeleri HTTPS ile S3'e yazar.
• Not. Her kartı arkasındaki kaynak adreslerine eşler ve bilerek dışarıda bırakılanları listeler; böylece okuyucu kodu bulabilir.

Önce budayın, sonra Terraform'un bilmediklerini ekleyin

Cesurca budayın. IAM yapıştırıcısı, rota tablosu ilişkilendirmeleri, log grupları ve kural başına güvenlik grubu kaynakları kodda kalmalı. Dağıtılabilir her şey ve her veri deposu için bir kart, çoğu okuyucu için doğru seviyedir.

Ardından Terraform'un size söyleyemeyeceklerini ekleyin:

• Sistemi kimin kullandığını ve trafiğin nereden girdiğini.
• Akış yönünü. Referanslar bir kaynaktan ihtiyaç duyduğu şeye doğru gider; trafik çoğu zaman ters yönde akar.
• Portları ve protokolleri, güvenlik grubu kurallarından alıp kenarların üzerine yazarak.
• Uygulamanın çağırdığı ama bu yapılandırmada yönetilmeyen harici servisleri.
• Bir olay anında önemli olan bilgileri: Multi-AZ, yedekler, istenen sayı.

Pull request incelemelerinde kullanın

Bir pull request'in planından üretilen diyagram, inceleyenlere uzun bir diff yerine değişikliğin şeklini gösterir. Özellikle birkaç şeye bakın:

• Yeni bir genel giriş noktası, örneğin bir yük dengeleyici, bir genel alt ağ ya da 0.0.0.0/0'a açık bir güvenlik grubu.
• Durum tutan bir kaynağın yeniden oluşturulması. Bir veritabanı ya da bucket üzerinde ["delete", "create"] ikinci bir inceleyiciyi hak eder.
• Alt ağlar arasında taşınan ya da özel ağın dışına çıkan kaynaklar.
• Yeni veri depoları; bunların bir sahibi, yedekleri ve veri haritanızda bir kaydı olmalı.

Üretilen diyagramla özenle hazırlanmış mimari diyagramını ayrı tutun. Üretilen diyagram tek bir değişiklik için inceleme yardımcısıdır; özenle hazırlanan ise sistemi anlatan dokümantasyondur.

Güncel tutun

Özenle hazırlanmış diyagrama kod gibi davranın: bir sahibi olsun, modülün README dosyasından ona link verilsin ve bir değişiklik giriş noktası, veri deposu ya da ağ sınırı eklediğinde güncellensin. Eskimeyen mimari diyagramlar yazısı tam bunun için bir iş akışı anlatıyor. Aynı yığının ağ tarafı için AWS VPC diyagramı rehberine, iki bölgede çalıştırmak için de AWS çok bölgeli mimari diyagramı yazısına bakın.

Archboard'da oluşturun

1. Google ya da GitHub ile giriş yapın ve bir diyagram oluşturun.
2. İlk taslak için .tf dosyalarınızı ya da plan JSON'unuzu ücretsiz Terraform'dan diyagrama aracına yapıştırın. Araç VPC'leri ve alt ağları çerçevelere, kaynakları kartlara, referansları bağlantılara dönüştürür; plan JSON'daki planlanan değişiklikleri işaretler ve hedef grup eklemeleri gibi yapıştırıcıları bağlantılara katar. Düzenlemeye devam etmek için Archboard’da aç seçeneğini seçin.
3. Elle çizmek için Ağ paketinden bir VPC çerçevesi ve içine iki Alt ağ çerçevesi ekleyin; genel alt ağlara Bulut paketinden bir Bulut yük dengeleyici, özel alt ağlara da bir Hesaplama ve bir Yönetilen veritabanı düğümü koyun.
4. Bucket için Bulut paketinden bir Nesne depolama düğümü, kullanıcılar için Ağ paketinden bir İnternet düğümü ve alias kaydı için bir DNS düğümü ekleyin.
5. Kenarları portlar ve protokollerle etiketleyin; kartları kaynak adreslerine eşleyen, Temel paketinden bir Markdown bloğu ekleyin.

Örnek 10 diyagram düğümü kullanıyor ve Free planın sınırları içinde kalıyor. Yığınınız CloudFormation ile tanımlıysa CloudFormation'dan diyagrama aracı aynı işi şablonlar için yapar.

SSS

terraform graph bir mimari diyagramı üretebilir mi? DOT ya da Terraform 1.16'dan beri Mermaid biçiminde bir bağımlılık grafı üretir. Bu planları ayıklamak için faydalıdır, ama trafik yerine oluşturma sırasını gösterir ve yapıştırıcı kaynakları da içerir; bu yüzden insanların onu mimari olarak okuyabilmesi için ayıklanması gerekir.

Diyagramı .tf dosyalarından mı, plan JSON'dan mı çizmeliyim? Bir modüle hızlıca bakmak için .tf dosyalarını, bir değişikliği incelemek için plan JSON'u kullanın; çünkü planda sayılar, modüller ve planlanan işlemler çözülmüştür.

Güvenlik gruplarını nasıl gösteririm? Ayrı kutular olarak değil, korudukları kaynaklar arasındaki kenarların üzerinde portlar ve protokoller olarak.

Neyi dışarıda bırakmalıyım? IAM eklemelerini, rota tablosu ilişkilendirmelerini, random_id gibi yardımcı kaynakları ve okuyucunun trafiği, veriyi ya da dışarıya açıklığı anlamasını değiştirmeyen her şeyi.

Diyagramı kodla nasıl senkron tutarım? Bir değişiklik giriş noktası, veri deposu ya da ağ sınırı eklediğinde bir taslağı yeniden üretin ve özenle hazırlanmış diyagramı aynı pull request içinde güncelleyin.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.