opencode ile Terraform: Pratik Kullanım Rehberi

opencode Terraform projelerinde terminalde opencode komutuyla başlatılan bir kodlama ajanıdır. Terraform’un modül, provider, state ve backend düzenini okuyarak plan-apply döngüsünü kısa tutar; asıl çıktı, sizin inceleyip onayladığınız diff’tir. Bu rehberde opencode’u bir Terraform repo’sunda güvenli ve verimli kullanmanın pratik yollarını anlatıyorum.

Neden opencode Terraform işine uyar

Terraform projeleri çoğu zaman onlarca .tf dosyası, modules klasörleri ve ortam bazlı değişken dosyaları içerir. opencode repo içeriğini okur; HCL bloklarını ve aralarındaki referansları görür. Tek bir istekte birden çok dosyayı tutarlı biçimde güncelleyebilir. Yeni bir module eklerken variables.tf, outputs.tf ve ana kaynak dosyasını birlikte yazar; provider sürümü değiştiğinde required_providers bloklarını ve provider alias kullanımlarını eşitleyebilir. Ayrıca terminal komutlarını kendisi çalıştırabildiği için terraform fmt, terraform validate ve terraform plan çıktılarını görür; hataları tekrar tekrar düzeltir. Bu, özellikle backend ve workspace ayarlarında veya tekrarlayan modül ekleme işlerinde büyük zaman kazandırır.

opencode, state dosyalarını doğrudan düzenlemek yerine terraform komutlarıyla etkileşime girer; böylece state kilitlenmesi ve tutarlılık korunur. Uzak backend kullanıyorsanız, ajan terraform init sonrası plan üretebilir ve plan çıktısındaki kaynak değişikliklerini yorumlayabilir. Özellikle “.terraform.lock.hcl” dosyasını güncellerken provider checksum’larını doğru tutar. Modül bağımlılıklarını takip eder; bir modülün output’unu başka modüle geçirirken gerekli değişiklikleri zincirleme yapar.

Projeyi ajan için hazırlama

opencode proje talimatlarını AGENTS.md dosyasından okur; adım adım kurulum için opencode nasıl kullanılır sayfasına bakabilirsiniz. Terraform repo’sunun köküne, ajanın her oturumda uyması gereken komutları, klasör düzenini ve güvenlik sınırlarını yazın. Bu dosya ne kadar net olursa ajan o kadar az yanlış varsayım yapar. Aşağıdaki örnek tipik bir Terraform projesi için yeterli bir başlangıçtır:

# Terraform repo kuralları

## Dizinler
- Kök: ana modül, provider ve backend tanımları
- modules/: yeniden kullanılabilir modüller; her modülde variables.tf, outputs.tf ve README.md bulunmalı
- environments/dev ve environments/prod: ortam bazlı kök modüller

## Komutlar
- Biçim: terraform fmt -check -recursive
- Doğrulama: terraform validate
- Plan: terraform plan -out=plan.tfplan
- Test: terraform test (varsa test dosyalarını çalıştır)

## Kurallar
- Asla terraform apply -auto-approve çalıştırma; yalnızca plan üret ve kullanıcıya göster.
- State dosyalarına (.tfstate, .tfstate.backup) ve .terraform/ klasörüne dokunma.
- Yeni module eklerken variable description alanlarını doldur, output'ları belgele.
- Provider sürümlerini required_providers içinde sabitle; değişiklik önerirsen önce plan üret.
- Terraform hatalarını sessizce geçme; her hata çıktısını raporla.

Ajan bu dosyayı okuduğunda apply komutundan kaçınır ve değişiklikleri plan aşamasında bırakır. Ortam bazlı özel kuralları environments/prod/AGENTS.md gibi daha alt seviyede de ekleyebilirsiniz; ancak kökteki tek dosya çoğu proje için yeterlidir. Değişken değerleri terraform.tfvars dosyalarında tutuluyorsa, ajanın yalnızca ilgili ortamın tfvars dosyasını değiştirmesi gerektiğini de belirtin. Ayrıca backend "s3" {} gibi blokların parametrelerini değiştirirken state dosyası taşınması gerekebileceğini; bu durumda ajanın yalnızca plan üretip size talimat vermesi gerektiğini ekleyin.

Çalışma döngüsü: plan, küçük adımlar, testler ve diff

Terraform değişikliklerinde ajanla şu döngüyü izleyin: önce küçük bir görev verin; ajan gerekli dosyaları değiştirsin ve terraform plan -out=plan.tfplan çalıştırsın. Siz plan çıktısını ve git diff çıktısını inceleyin; onay verirseniz terraform apply plan.tfplan komutunu kendiniz çalıştırın veya ajanın yalnızca sizin açık onayınızla çalıştırmasına izin verin. Her adımda terraform validate ve terraform fmt -check hatalarını ajan düzeltsin. Aynı anda büyük yeniden yapılandırma yerine tek module veya tek kaynak grubu üzerinde ilerleyin. Aşağıdaki istemler tipik görevler için iyi başlangıçtır:

• modules/networking içindeki VPC modülüne yeni bir private subnet değişkeni ekle; subnet’i oluştur ve outputs’a subnet id’lerini çıkar. Sonra terraform validate çalıştır.
• environments/prod/main.tf içindeki provider sürümünü güncellemeden önce required_providers bloğundaki sürüm kısıtını değiştir; ardından terraform plan -out=plan.tfplan üret ve özetini göster.
• Kök modüldeki backend.tf dosyasını mevcut uzak backend yapılandırmasına taşı; state migration notu ekle ama apply etme.
• Tüm .tf dosyalarını terraform fmt ile biçimlendir; değişiklikleri terraform fmt -diff ile göster, sonra terraform validate çalıştır ve hataları düzelt.
• Aynı provider alias’ını kullanan modülleri tespit et; alias tanımını root modüle taşı ve modüllere outputs üzerinden geçir, ardından terraform plan üret.
• terraform console kullanarak şu ifadeyi değerlendir: module.vpc.public_subnet_ids[0]; çıktıyı bana göster.
• variables.tf içindeki tüm variable’lara type ve description ekle; eksik olanları belirle ve güncelle.

Bu listedeki her görevi tek seferde değil, sırayla verin. Ajan bir görevi bitirdiğinde plan çıktısını inceleyin; sonra bir sonrakine geçin. Böylece geri alma maliyeti düşer.

Tipik Terraform görevleri ve tuzaklar

Aşağıdaki tablo, ajanın güçlü olduğu işler ile Terraform’a özgü dikkat edilmesi gereken yerleri özetler:

Özellikle count ve for_each dönüşümlerinde Terraform, kaynak adresleri değiştiği için kaynakları yeniden yaratmayı önerebilir. Ajanın plan çıktısındaki destroy/create satırlarını tek tek inceleyin; riskli görünen değişiklikleri terraform state mv gibi komutlarla ayrıca ele alın. Ayrıca provider sürümü yükseltmelerinde, terraform providers lock komutu ile lock dosyasını güncelletmek isteyebilirsiniz; bu komutu ajanın çalıştırmasına izin verin ama çıktıyı kontrol edin.

Terraform için test ve doğrulama

Ajanla çalışırken doğrulamayı dört aşamada yapın. Önce terraform fmt -check -recursive ile biçim bozukluklarını yakalayın. Ardından terraform validate ile HCL sözdizimi ve referans hatalarını kontrol edin. Üçüncü olarak terraform plan -out=plan.tfplan ile gerçek kaynak değişikliklerini önizleyin. Son olarak varsa terraform test ile modül testlerini çalıştırın. Ajan her başarısız komutun çıktısını size göstermeli ve düzeltme önerisi sunmalıdır. Ajanın kendi başına apply çalıştırmasına izin vermeyin; planı siz onaylayın ve terraform apply plan.tfplan komutunu terminalinizde çalıştırın. Ayrıca git diff --stat ile değişikliklerin kapsamını kontrol edin. Plan çıktısında # ile başlayan yorum satırlarını okuyun; ajanın özeti kaçırdığı kaynak güncellemeleri veya silmeleri burada görünür. Yeni bir modül eklendiyseniz, modülün kendi terraform.tftest.hcl test dosyasını çalıştırın; ajan bu dosyayı da oluşturabilir.

Birkaç ajanı paralel çalıştırma: AgentVera

Aynı Terraform projesinde birden fazla ajanı paralel çalıştırmak isterseniz AgentVera işe yarar. Her ajan kendi git worktree’sinde çalıştığı için modül dosyaları üzerinde çakışma olmaz. Ajanın turu bitince ikinci bir model otomatik kod incelemesi yapar ve bulgular file:line olarak bağlanır. Her turun anlık görüntüsü (checkpoint) kaydedilir; yanlış bir Terraform değişikliğini tek tıkla geri alabilirsiniz. Token bütçeleri de beklenmedik maliyetleri önler.

Sonuç

opencode, Terraform projelerinde plan ve diff odaklı çalışmayı hızlandıran bir araçtır. AGENTS.md ile net kurallar koyduğunuzda güvenli ve tekrarlanabilir bir iş akışı kurarsınız. Ajanın ürettiği her değişikliği terraform plan ve git diff ile inceleyin; apply komutunu son kontrolü siz yaparak çalıştırın. Detaylı kullanım için opencode nasıl kullanılır sayfasına bakabilirsiniz.