Codex Terraform: Terraform projelerinde Codex kullanımı

Codex, Terraform projelerinde codex komutuyla başlatılan bir kodlama ajanıdır. Proje kökündeki AGENTS.md talimatlarını okuyarak modül, provider, değişken ve state yönetiminde plan öncelikli çalışır. Bu rehber, Terraform bilen geliştiriciler için somut bir çalışma düzeni sunar; kurulum ayrıntıları için Codex sayfasına bakabilirsiniz.

Neden Codex Terraform işine uygun?

Codex, HCL dosyalarını ve modül çağrılarını bir bütün olarak tarayabildiği için tekrarlayan refaktörleri hızlı yapar. Örneğin environments/dev, staging ve prod altında aynı instance_type değişkenini taşırken tüm çağrıları ve varsayılanları güncelleyebilir; aynı işi elle yapmak hem hata riski taşır hem de zaman alır. Ayrıca modül çıktılarını yeni kaynaklara bağlarken depends_on veya for_each gibi yapıları önererek HCL şablonunu tutarlı tutabilir. Asıl değer, değişiklikleri terraform plan çıktısıyla birlikte değerlendirebilmesidir: ajan planı özetleyebilir, zorla değiştirme veya destroy olacak kaynakları ayıklayabilir. Terraform’da değişikliklerin etkisini önceden görmek kritik olduğundan, Codex’in plan çıktısını yorumlama yeteneği iş akışını ciddi şekilde hızlandırır. Ayrıca HCL dosyalarındaki sözdizimi hatalarını, eksik argümanları veya tutarsız değişken adlarını terraform validate çıktısına göre düzeltebilir. Ancak Terraform state ve plan yorumu hâlâ sizin sorumluluğunuzdadır; ajanı karar verici değil, hızlandırıcı olarak kullanın.

Projeyi ajan için hazırlama ve AGENTS.md

Codex proje talimatlarını AGENTS.md dosyasından okur. Terraform projesinde bu dosya; çalıştırma komutlarını, dizin düzenini, state ve plan kurallarını netleştirmelidir. Bağlam mühendisliği prensipleri için Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi yazısına bakılabilir. Aşağıdaki örnek, çok ortamlı tipik bir Terraform deposu için yeterli bir başlangıçtır:

# AGENTS.md

## Komutlar
- Biçimlendir: `terraform fmt -recursive`
- Doğrula: `terraform validate`
- Lint: `tflint`
- Test: `terraform test`
- Plan (asla otomatik apply etme): `terraform plan -out=plan.tfplan`

## Dizin düzeni
- `modules/` altında her modül kendi değişken ve çıktılarıyla bulunur.
- Ortamlar `environments/dev`, `environments/prod` altında ayrı backend yapılandırması kullanır.
- Kök modülde yalnızca ortam çağrıları ve provider sürüm kısıtları tutulur.

## Kurallar
- Değişiklik sonrası önce `terraform validate`, sonra `terraform plan` çalıştır.
- `terraform apply` komutunu asla çalıştırma; yalnızca plan üret.
- State dosyasını elle düzenleme; taşıma/silme için `terraform state mv/rm` kullan.
- Provider ve modül sürümlerini `versions.tf` içinde sabitle.
- Çıktı eklerken hassas değerleri `sensitive = true` yap.

Buradaki en kritik kural terraform apply komutunun yasaklanmasıdır. Codex yalnızca okuma ve doğrulama komutlarını çalıştırmalı; uygulamayı siz terminalde tetiklemelisiniz. Ayrıca provider sürümlerini versions.tf içinde sabitlemek, ajanın plansız sürüm atlaması yapmasını engeller. Ortam değişkenleri için TF_VAR_* kullanıyorsanız bunları AGENTS.md’e yazmayın; yalnızca hangi ortamın hangi backend yapılandırmasını kullandığını belirtin. Ajan, terraform init -backend-config=... gibi komutları çalıştıracağında dosya yolunu bilmelidir. Modül kaynaklarında source adreslerinin doğru sürüm etiketleriyle sabitlenmesi de önemlidir; ajan modül güncellerken bu satırı yanlışlıkla değiştirebilir. Bu yüzden AGENTS.md’e şu kuralı ekleyin: “Modül kaynağındaki ref veya version alanlarını değiştirme, yalnızca açıkça istendiğinde güncelle.” Ayrıca dosya adlarının Türkçe karakter içermemesine ve dizin yapısının Terraform konvansiyonlarına uymasına dikkat edin. Codex bu talimatlara uyarak daha öngörülebilir çalışır.

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

Terraform’da güvenli döngü şudur: önce mevcut planı alın, tek bir değişiklik isteyin, ajan değişikliği yapsın, ardından terraform fmt, terraform validate ve terraform plan çalıştırsın, diff’i ve planı inceleyin, sonra siz uygulayın. Bu döngüyü bozan en yaygın hata, bir oturuşta büyük bir refaktör istemektir. Küçük adımlar, plan çıktısında hangi değişikliğin hangi kaynağa denk geldiğini takip etmeyi kolaylaştırır. Her turdan sonra git diff --stat ile değişen dosyaları özetleyin; plan çıktısıyla birlikte değerlendirin. Codex, önerdiğiniz değişikliği yaptıktan sonra otomatik olarak terraform validate çalıştırabilir, ancak planı siz istemelisiniz. Eğer plan çıktısı beklenmedik bir şey gösteriyorsa, Codex’e hatayı açıklayıp düzeltmesini isteyebilirsiniz; o da planı yeniden üretir. Döngüde test adımını atlamayın: modül testleriniz varsa terraform test çalıştırmak, değişikliğin beklenen davranışı koruduğunu doğrular.

Örnek komut istemleri:

• Mevcut terraform plan çıktısını özetle; destroy edilecek veya zorla yeniden oluşturulacak kaynak var mı?
• modules/networking modülündeki public_subnets değişkenini list(string) yerine map(object({ cidr = string, az = string })) yap ve tüm ortam çağrılarını güncelle.
• aws_instance kaynağına Name etiketi için common_tags yerel değişkenini ekle; dev, staging ve prod ortamlarında kullan.
• Şu terraform validate hatasını çöz: [hata metni].
• terraform plan çıktısında module.rds.aws_db_instance adresinde beklenmeyen bir değişiklik görünüyor; sebebini bul ve gerekli düzeltmeyi yap, planı tekrar üret.
• modules/security_group modülünde giriş kurallarını list(object) yerine map kullanacak şekilde refaktör et; mevcut çıktıları koru.

Bu istemler tek bir kaynak türüne odaklanır, ajanın kapsamı daralır ve plan çıktısını yorumlamak kolaylaşır. Ayrıca aynı anda birden fazla ortamı değiştirmektense önce dev, sonra prod için ayrı turlar yapmak daha güvenlidir.

Codex’in iyi yaptığı işler ve dikkat edilmesi gerekenler

Codex özellikle modül arayüzü değişiklikleri, değişken/çıktı ekleme, provider sürüm yükseltmeleri ve state taşıma komutları yazmada iyidir. Buna karşılık Terraform’a özgü riskler vardır: state dosyasını elle düzenlemek, planı okumadan onaylamak, backend veya provider sürümünü sessizce değiştirmek ve hassas çıktıları sensitive yapmadan bırakmak. Ajan desteklenmeyen bir provider argümanı önerirse terraform validate erken yakalar; bu yüzden validate adımını atlamayın. Aşağıdaki tablo tipik görevleri ve göz önünde bulundurmanız gerekenleri özetler:

Özellikle terraform state komutlarında ajanın yazdığı adresleri mutlaka gözden geçirin; yanlış bir mv state dosyasını bozabilir. Aynı şekilde modül kaynağı değişikliklerinde plan çıktısında # forces replacement satırlarını tek tek kontrol edin. Codex bazen modül kaynağını güncellediğinde çıktıları da değiştirebilir; bunu plan çıktısında module.<ad>.<çıktı> değişiklikleri olarak görürsünüz. Eğer ajan bir kaynağı taşımak istiyorsa, önce adresin doğruluğunu terraform state list ile kontrol edin. Ayrıca ajanın önerdiği terraform import komutlarını da dikkatle inceleyin; import işlemi yanlış adresle mevcut kaynağı bozabilir.

Test ve doğrulama

Codex ile üretilen değişiklikleri doğrulamak için sırasıyla şu komutları kullanın: terraform fmt -recursive -check, terraform validate, tflint ve modül testleri için terraform test. Nihai doğrulama her zaman terraform plan -out=plan.tfplan olmalıdır; planı incelemeden apply etmeyin. Ajan, plan çıktısındaki hataları özetleyebilir ve düzeltebilir; CI akışına bağlamak için CI hatasını yapay zeka düzeltsin, PR yorumunu da yazısındaki yöntem uyarlanabilir. Ayrıca modül testlerinde terraform test dosyalarını Codex’e yazdırmak, kaynak adlarının ve çıktıların doğrulanmasını kolaylaştırır. Plan çıktısını filtrelemek için jq gibi araçları da kullanabilirsiniz; Codex bu tür filtreleri üretebilir. Otomatik testler yoksa, en azından terraform plan çıktısını bir önceki commit ile karşılaştırarak istenmeyen değişiklikleri yakalayın. Ajan, plan çıktısını özetlerken destroy veya replace satırlarını vurgulayabilir; bunları manuel olarak da kontrol edin.

Birden fazla ajanı AgentVera ile çalıştırma

AgentVera, birden fazla Codex oturumunu tek pencerede çalıştırırken Terraform projelerinde en çok şu özellikleriyle işe yarar: ajanlar kendi git worktree’lerinde çalıştığı için aynı .tf dosyalarını ezmez; her tur sonunda ikinci bir model değişiklikleri inceler, böylece plan çıktısındaki destroy/create gibi riskler erken yakalanır; checkpoints sayesinde yanlış bir terraform state mv işlemi geri alınabilir; token bütçeleri ise uzun refaktörlerde maliyeti kontrol altında tutar. Daha fazla kurulum detayı için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara sayfasına bakılabilir; bu dört özellik Terraform state güvenliği açısından öne çıkar.

Özet

Codex, Terraform projelerinde plan öncelikli küçük adımlarla en verimli çalışır. AGENTS.md içinde komutları ve state kurallarını netleştirin; değişiklikleri asla apply etmeden önce planla doğrulayın. Riskli alanlarda (state, provider sürümü, destroy/create) ajanı denetleyin, testleri atlamayın. Böylece Codex günlük Terraform işlerini hızlandırırken altyapı güvenliğini korur.