1. GİRİŞ

Terraform kullanarak altyapı kodu yazarken en kritik mimari kararların başında modül (module) tasarımı gelir. İyi tasarlanmış modüller, altyapının sürdürülebilirliğini, yeniden kullanılabilirliğini ve ekipler arası iş birliğini doğrudan iyileştirir; kötü tasarlanmış modüller ise teknik borç, kafa karışıklığı ve hatalı prod değişikliklerine yol açar. Bu makale Terraform modül tasarımının neden önemli olduğunu, hangi ilkelere göre yapılandırılması gerektiğini ve gerçek dünya uygulamalarında hangi pattern'lerin tercih edildiğini mühendis bakış açısıyla anlatır.

Bu konu neden bugün önemli?

• Bulut altyapıları büyüdükçe tekrar eden kaynak konfigürasyonları artıyor; modüller tekrar kullanım ve standardizasyon sağlar.
• Takımlar büyüdükçe governance, versiyonlama ve module ownership gereksinimleri doğuyor.
• GitOps, CI/CD ve IaC'nin olgunlaşmasıyla modüllerin test edilebilir, versiyonlanabilir ve güvenli olması işletme riski azaltır.

Kimler için önemli?

• Platform mühendisleri ve altyapı ekipleri
• DevOps/SRE mühendisleri
• Bulut mimarları ve teknik yönetim

Hangi problemleri çözüyor?

• Tekrarlayan kod ve konfigürasyon sapmaları
• Ortamlar arası tutarsızlıklar ve drift
• Değişikliklerin izlenebilirliği, test edilebilirliği ve güvenli deploy süreçleri

2. KAVRAMSAL TEMELLER

2.1 Terraform modül nedir?

Terraform modülü, bir veya birden fazla kaynak (resource) ve bunlara bağlı input/output tanımlarını kapsayan, tekrar kullanılabilir bir yapı bloğudur. Modüller, altyapıyı fonksiyonel parçalara ayırmak; soyutlamak ve ekipler arasında paylaşılabilir kılmak için kullanılır. Resmi Terraform Registry veya kurum içi git repo'ları aracılığıyla paylaşılabilirler.

2.2 Modül seviyeleri ve sorumluluklar

• Primitive (low‑level) modüller: Tekil kaynak veya küçük kaynak setleri (ör. vm, subnet, security group) oluşturur. Minimal abstraction sağlar.
• Composite (high‑level) modüller: Birden fazla primitive modülü birleştirip belirli bir iş amacı için hazır altyapı sunar (ör. web‑app platform stack: VPC + subnet + ALB + autoscaling + IAM).
• Platform modülleri: Organizasyonel standartları, naming convention ve guardrail'ları içerir; şirket içi reuse için tasarlanır.

2.3 Önemli terminoloji

• Inputs: Modülün aldığı parametreler (variable).
• Outputs: Modülün dışa verdiği değerler (örn. resource IDs).
• Providers: Modülün hangi provider'lar ile etkileşime girdiği (AWS, Azure, GCP, Kubernetes vb.).
• Side effects: Modülün dış dünya üzerinde yaptığı yan etkiler (shared resources, IAM role creation).

3. NASIL ÇALIŞIR? — Teknik Mimari ve Tasarım İlkeleri

3.1 Tek sorumluluk (Single Responsibility) prensibi

Modül tasarımında ilk kriterlerden biri tek sorumluluk prensibidir: bir modül yalnızca bir konseptin sorumluluğunu üstlenmelidir. Örneğin "network" modülü VPC, subnet ve routing ile ilgilenirken; "compute" modülü VM/instance yapılandırması yapar. Bu ayrım, test etmeyi, versiyonlamayı ve reuse'u kolaylaştırır.

3.2 Encapsulation ve minimal surface area

Modülün dışa açtığı inputs ve outputs mümkün olduğunca minimal tutulmalıdır. İç detaylar (naming pattern, tag'ler, alt yapı kaynakları) modülün içinde kapsüllenmelidir. Böylece modül kullanıcıları yalnızca gerekli parametreleri sağlar ve modülün iç yapısına bağımlı olmaz.

3.3 İdempotency ve determinism

Modüller idempotent olmalı; aynı input'lar verildiğinde her zaman aynı sonucu üretmelidir. Random değerler veya timestamp'ler modül içinde kontrolsüz şekilde kullanılmamalı; gerekiyorsa input olarak verilmeli veya deterministik bir şekilde üretilmelidir.

3.4 Input validation ve sane defaults

Modüller, yanlış parametre kullanımını engellemek için input validation (allowed values, format checks) ve mantıklı varsayılan değerler (defaults) sunmalıdır. Bu, kullanıcı deneyimini (DX) iyileştirir ve yanlış konfigürasyon riskini azaltır.

3.5 Avoid side effects — yan etkileri azaltma

Modüller paylaşılan global kaynakları (ör. organization‑wide IAM policies veya shared VPC) doğrudan yaratmaktan kaçınmalı; bunun yerine referans almalı veya platform modülleri aracılığıyla yönetmelidir. Global değişiklikler coordination ve ownerhip gerektirir.

4. GERÇEK DÜNYA KULLANIMLARI — Pattern'ler ve Örnekler

4.1 Primitive + Composite pattern

Çok yaygın bir yaklaşım, düşük seviyeli primitive modüller (network, security_group, compute) oluşturup bunları composite bir modülde birleştirmektir. Örneğin bir "web_service" modülü; "vpc", "subnet", "alb", "autoscaling" primitive'lerini kullanarak tek bir yüksek seviyeli yapı sağlar. Bu pattern ekiplerin ihtiyaçlarına göre customization imkânı verir.

4.2 Platform modülleri ve organisation registry

Kurumlar genellikle bir internal module registry oluşturur. Platform modülleri (ör. standard networking, logging, monitoring) kurum politikalarını uygular ve tüm projelerde reuse edilir. Böylece standardizasyon sağlanır ve security guardrail'ları merkezileştirilir.

4.3 Example: Multi‑account AWS bootstrap

Gerçek dünyada sık kullanılan bir modül seti, yeni AWS account'ları bootstrap eden bir modüldür. Bu modül organization unit yaratma, SCP attach etme, logging/account baseline kurma ve monitoring stack'ini deploy etme gibi adımları kapsar. Bu işlem idempotent ve güvenli olmalıdır; aynı modül CI aracılığıyla multiple account'lara uygulanabilir.

4.4 Example: Kubernetes platform module

Kubernetes ortamı için bir platform modülü; EKS/AKS/GKE cluster provisioning, nodegroup konfigürasyonu, CNI yapılandırması, OIDC ve IAM entegrasyonlarını kapsayabilir. Ancak uygulama seviyesindeki deploy ve manifest'ler ayrı modüller olarak tutulmalıdır.

5. AVANTAJLAR VE SINIRLAMALAR

Avantajlar

• Tekrar kullanılabilirlik: Modüller aynı konfigürasyonu farklı projelerde yeniden kullanmayı sağlar.
• Standardizasyon: Kurum politikalarını modül seviyesinde enforce ederek tutarlılık sağlanır.
• Bakım kolaylığı: Hatalar tek modülde düzeltilir ve versiyon yükseltmesiyle tüm tüketicilere yayılır.

Sınırlamalar

• Aşırı soyutlama: Çok fazla abstraction, debug etmeyi zorlaştırabilir ve beklenmeyen side effect'lere neden olabilir.
• Versiyon bağımlılıkları: Modül versiyonlarını yönetmek karmaşık olabilir; breaking change'ler koordinasyon gerektirir.
• Ownership problemleri: Kimin hangi modülden sorumlu olduğu net değilse governance zayıflar.

6. ALTERNATİFLER VE KARŞILAŞTIRMA

7. EN İYİ PRATİKLER

7.1 Modül organizasyonu ve naming

• Modül isimlendirmesini açık ve anlamlı tutun: "aws_vpc", "aws_security_group", "k8s_cluster" gibi.
• Module repository yapısını netleştirin: primitive vs composite vs platform ayrımı olmalı.
• Semantik versiyonlama kullanın (MAJOR.MINOR.PATCH) ve breaking change politikasını dokümante edin.

7.2 Inputs / Outputs tasarımı

• Minimal ve gerekli input'lar sağlayın; wide‑open parameter list'lerden kaçının.
• Outputs ile sadece dış dünyanın ihtiyacı olan değerleri expose edin (ör. IDs, ARNs, endpoints).
• Optional parametrelerde sane defaults tanımlayın.

7.3 Test ve CI

• Modüller için unit test (terratest/kitchen) ve integration test'ler oluşturun.
• CI pipeline'larında 'terraform init/validate/plan' çalıştırıp plan çıktısını PR'a ekleyin.
• Ephemeral environment'lar ile gerçek kaynaklarda acceptence test'leri çalıştırın ve teardown süreçlerini otomatikleştirin.

7.4 Güvenlik ve policy

• Modüller policy as code ile entegre olmalı (OPA/Sentinel) ve CI'de doğrulanmalıdır.
• Secrets as input yerine secret manager referansları kullanın. State içinde sensitive data saklamaktan kaçının.
• Least privilege prensibi ile modülün oluşturduğu IAM rolleri ve izinlerini sınırlandırın.

7.5 Documentation & Discoverability

• Modül README'lerinde örnek kullanımlar, input/output tablosu ve değişiklik notları olmalı.
• Registry veya iç portal ile modüller discoverable olmalı; örnek snippet'ler ve best practice'ler paylaşılmalı.

8. SIK YAPILAN HATALAR

• Modülü çok genel (over‑abstract) yapmak: esneklikten çok karmaşıklık getirir.
• State'e sensitive output bırakmak: güvenlik açığı yaratır.
• Versiyonlama politikası olmadan modül güncellemek: tüketiciler beklenmeyen kırılmalar yaşar.
• Testleri ihmal etmek: production deploy'ları riskli hale gelir.
• Module ownership ve destek sözleşmeleri olmadan bir modülün enterprise çapında kullanılmasına izin vermek.

9. GELECEK TRENDLER

1. Modül marketplace ve governance: Kurumsal module registry ve otomatik governance akışları daha yaygın olacak.
2. AI destekli modül önerileri: Kod bazlı analizlerle hangi modüllerin ne zaman güncellenmesi gerektiği, optimal default'lar AI ile önerilecek.
3. Infrastructure as Software: Modüller daha sofistike test ve CI süreçleriyle, library gibi geliştirilecek; code review kültürü altyapıya daha sık uygulanacak.

EK BÖLÜMLER

Sık Sorulan Sorular (FAQ)

1. Primitive modül mü yoksa composite modül mü tercih etmeliyim?

   Her iki yaklaşımın yeri vardır. Küçük ekipler ve hızlı prototipleme için composite modüller kullanışlıdır; büyük ölçekli organizasyonlarda primitive modüller ile daha esnek ve test edilebilir bir yapı sağlanır.

2. Modül versiyonlarını nasıl yönetmeliyim?

   Semantik versiyonlama (MAJOR.MINOR.PATCH) uygulayın, breaking change'leri MAJOR ile belirtin ve consumer'lara migration guide sağlayın.

3. Modül repository yapısı nasıl olmalı?

   Mono‑repo veya multi‑repo tercihleri organizasyon ölçeğine göre değişir. Küçük kuruluşlar için mono‑repo başlangıçta yönetimi kolaylaştırır; büyük kuruluşlarda multi‑repo ile erişim ve ownership daha net olur.

4. Modül testlerini nasıl organize ederim?

   Unit test'ler modül mantığını doğrulamalı; integration test'ler ephemeral env'lerde çalıştırılmalı. Terratest ve kitchen‑terraform yaygın araçlardır.

5. Modüllerde secrets ile çalışırken ne yapmalıyım?

   Secrets'ı doğrudan modül input'u olarak göndermeyin; secret manager referansları veya sealed secrets pattern'leri kullanın.

6. Modülün oluşturduğu global kaynakları nasıl yönetmeliyim?

   Global kaynaklar (org wide logging, SCP, central IAM policies) için ayrı platform modülleri ve uygun owner ship modeli oluşturun; application modüllerinin doğrudan global resource yaratmasına izin vermeyin.

7. Modül dokümantasyonu için hangi bilgiler şart?

   Inputs, outputs, example usage, constraints, dependencies ve upgrade/migration yönergeleri mutlaka olmalıdır.

8. Module reuse için en iyi dağıtım yöntemi nedir?

   Terraform Registry veya kurum içi registry (artifact repo) tercih edin; git tag'leri ve release artefaktları üzerinden versiyonlama yapın.

Anahtar Kavramlar

Module

Tekrar kullanılabilir yapı bloğu; inputs/outputs ile soyutlanır.

Primitive vs Composite

Primitive küçük, tek sorumluluklu modüller; composite birden fazla primitive'i birleştirir.

Idempotency

Aynı input ile tekrarlandığında aynı sonucu verme özelliği.

Side effect

Modülün dış dünya üzerinde ürettiği yan etkiler; minimize edilmelidir.

Semantic versioning

Modüller için MAJOR.MINOR.PATCH kurallarını uygulama yöntemi.

Öğrenme Yol Haritası

1. 0–1 ay: Terraform temel komutları, HCL syntax ve basit bir modül oluşturma alıştırması yapın.
2. 1–3 ay: Primitive modüller tasarlayın, input/output pratiklerini öğrenin ve unit test'ler ekleyin.
3. 3–6 ay: Composite modüller, registry kullanımı, CI pipeline'ında plan/validate entegrasyonu ve integration test'ler üzerinde çalışın.
4. 6–12 ay: Enterprise modül governance, semantic versioning, module deprecation stratejileri ve multi‑account, multi‑region senaryolarında modül uygulaması deneyimi kazanın.