Gemini CLI ile Terraform projeleri nasıl yönetilir?

Gemini CLI, gemini komutuyla proje klasöründe başlatılan bir terminal kodlama ajanıdır. Terraform projesinde doğru bir GEMINI.md ile beslendiğinde terraform init, validate, fmt ve plan gibi komutları sizin onayınızla çalıştırır; modül, değişken ve state değişikliklerini küçük adımlarla önerir. Bu rehberde kurulumdan doğrulamaya, paralel ajan kullanımına kadar somut bir Terraform çalışma düzeni göreceksiniz. Daha genel kurulum için Gemini CLI sayfasına bakabilirsiniz.

Gemini CLI Terraform işine neden uyuyor?

Terraform declarative olduğu için ajanın ürettiği her değişiklik terraform plan çıktısında okunabilir bir diff olarak görünür; bu, kod ajanının kendi özetinden daha güvenilirdir. Gemini CLI terminalde çalıştığından planı kendisi çalıştırabilir, çıktıyı yorumlayıp gereksiz destroy/create olup olmadığını özetleyebilir. Ayrıca tekrarlayan kaynak blokları, değişken tanımları, modül ayıklama ve terraform fmt düzeltmeleri gibi işlerde hız kazandırır. Özellikle büyük ortamlarda veya çok sayıda benzer kaynakta, ajanın önerdiği for_each dönüşümleri ve modül sınırları el ile yazmaktan daha az hata üretir. State ve backend yönetiminde ise ajan önerilerini plan çıktısıyla doğrulamak zorunludur çünkü yanlış bir terraform state komutu planla yakalanamayabilir; bu nedenle state ile ilgili adımları her zaman manuel onaydan önce plan ve terraform state list ile çapraz kontrol edin.

Projeyi ajan için hazırlamak: GEMINI.md

Kök dizindeki GEMINI.md dosyası ajanın her görevde okuyacağı tek kaynak olmalı. İçinde ortam kökleri (environments/dev, environments/prod), modül düzeni, backend bilgisi, zorunlu komutlar ve yasaklar olmalı. Ajanın terraform apply çalıştırmasını istemiyorsanız bunu açıkça yazın; terraform state komutlarını yalnızca plan sonrası önermesini söyleyin. Dosya kısa ve kesin olmalı; ajan her turda aynı komutları aramak yerine doğrudan kurallara uysun. Aşağıdaki örnek kısa ama etkilidir.

# GEMINI.md

## Mimari
- `environments/dev` ve `environments/prod` ortam kökleridir.
- `modules/` altındaki her modül kendi `variables.tf`, `outputs.tf` ve `README.md` dosyasına sahiptir.
- State uzak backenddedir; `terraform init` ilgili ortam klasöründe çalıştırılır.

## Komutlar
- Biçim: `terraform fmt -recursive`
- Lint: `tflint --recursive`
- Doğrulama: `terraform validate`
- Plan: `terraform plan -out=plan.tfplan`
- Test: `terraform test`

## Kurallar
- Asla onaysız `terraform apply` çalıştırma.
- `terraform state` komutlarını yalnızca plan çıktısını gösterdikten sonra öner.
- Modül değişikliklerinde `terraform init -upgrade` gerekirse açıkça belirt.

Bu dosyayı sade tutmak ajanın her turda komutları tekrar etmesini önler. Örneğin tflint çıktısında hata varsa ajanın o hatayı düzeltmesi için ayrıca prompt yazmanız gerekmez; GEMINI.md’de zorunlu komut olarak varsa, ajan kendiliğinden çalıştırıp sonucu size getirir. Kurulum ve ilk kullanım için Gemini CLI nasıl kullanılır? Adım adım rehber yazısına göz atabilirsiniz.

Ajanla çalışma döngüsü ve örnek promptlar

Ajanı serbest bırakmak yerine küçük adımlarla ilerleyin: önce plan alın, sonra diff inceleyin, terraform validate ve tflint çalıştırın, en son terraform plan ile değişikliği doğrulayın. Her adımda ajanın özetini değil, plan çıktısını okuyun. Aşağıdaki tablo tipik görevleri ve kullanabileceğiniz promptları gösterir.

Prompt yazarken mutlaka plan isteyin; ajan size yalnızca kod değişikliği önerirse, ‘bu değişiklik için terraform plan -out çalıştır ve çıktıyı yorumla’ deyin. Aşağıdaki gibi ek promptlar da işleri hızlandırır:

• ‘Module outputs dosyasındaki tüm değerleri sensitive olmayanlar için ayrı ayrı belirt; gereksiz çıktı olmasın.’
• ‘Azure kaynakları için resource grup adını variable’dan alsın, her kaynakta aynı kullanımı sağla.’
• ‘Bu modülün variable listesini README’ye tablo olarak ekle; default değerleri de yaz.’
• ‘Plan çıktısında destroy görünüyorsa nedenini bul ve destroy olmadan nasıl yapılacağını öner.’

Daha iyi prompt yapısı için Kodlama ajanları için prompt nasıl yazılır? başlıklı yazıya bakabilirsiniz.

Ajanın iyi yaptığı işler ve Terraform’a özel riskler

Gemini CLI şu işlerde güvenilirdir: tekdüze kaynak blokları oluşturmak, for_each veya count kullanarak benzer kaynakları çoğaltmak, modül outputs/variables bağlamak, terraform fmt ve tflint çıktısına göre küçük düzeltmeler yapmak. Uzun HCL dosyalarını parçalara ayırıp modül sınırlarını çizmek de verimli olur.

Dikkat edilecek yerler:

• State ve moved blokları: Yanlış moved sonucu kaynak destroy/create görünebilir. Ajan önerisinden sonra terraform plan çıktısında # forces replacement satırlarını arayın. Ayrıca terraform state list ile taşınan adresin hâlâ mevcut olduğunu doğrulayın.
• Provider sürüm yükseltmeleri: Sürüm atlarken deprecation ve yeni zorunlu alanlar oluşabilir. Ajanın önerdiği terraform init -upgrade sonrası mutlaka terraform validate çalıştırın. tflint provider uyarılarına da bakın.
• Backend değişiklikleri: backend bloğundaki değişiklikler terraform init -migrate-state gerektirir; ajan bunu atlayıp yalnızca kod yazarsa state yerel kalabilir. Ajanın önerisinde -migrate-state geçmiyorsa siz ekleyin.
• Sensitive değişkenler: output ve variable tanımlarında sensitive = true eklemeden değerler plan çıktısına sızabilir; ajanın eklediği yeni output’ları bu açıdan denetleyin. Özellikle token, password, private key gibi alanlar için kontrol edin.
• Veri kaynakları ve depends_on: Ajan bazen gereksiz depends_on ekler veya eksik bırakır; plan sırasını ve kaynak bağımlılıklarını kontrol edin. terraform graph çıktısını kullanarak bağımlılıkları görselleştirebilirsiniz.

Ajanla Terraform test ve doğrulama

Ajanın her değişiklikten sonra zorunlu olarak çalıştırması gereken komutları GEMINI.md’ye yazın. Sıra şöyle olmalı: terraform fmt -recursive -check, terraform validate, tflint --recursive, terraform plan -out=plan.tfplan. Ajan bu komutları çalıştırdığında çıktıyı özetler; siz yine de plan.tfplan dosyasını terraform show plan.tfplan ile açıp kaynak adreslerini ve değişiklik sayısını kontrol edin. Plan çıktısında No changes görünüyorsa ajanın önerdiği değişiklik gerçekte hiçbir kaynağı etkilemiyor demektir; bu durumda değişken geçişlerini veya module çağrısını yeniden gözden geçirin.

Test altyapınız varsa terraform test çalıştırmasını isteyin; modül davranışını doğrulayan assertion hatalarını ajana geri iletin. Ajan, test geçene kadar düzeltme önersin; siz yalnızca son onayı verin. Ayrıca CI/CD hattınızda aynı komutların çalıştığından emin olun; ajanın yerel olarak geçtiği her şey CI’da da geçmelidir. Eğer terraform plan çıktısı beklenenden çok kaynak gösteriyorsa, ajanın yanlışlıkla tüm ortamı yeniden oluşturacak bir değişiklik yapmadığını doğrulayın; bu özellikle modül path değişikliklerinde olur.

Aynı Terraform projesinde birden fazla ajan: AgentVera

Terraform projelerinde iki ajan aynı anda aynı .tf dosyalarını düzenlerse state ve plan tutarsızlaşır. AgentVera, her ajanı kendi git worktree’sinde çalıştırıp gerçek terminal komutlarını yan yana gösterir; böylece modül, ortam veya backend işleri paralel yürürken dosya çakışması olmaz. Ajan turu bittiğinde ikinci bir model kod incelemesi yapar ve bulguları dosya:satır olarak bağlar; bu inceleme özellikle moved ve state değişikliklerinde hata yakalar. Ayrıca checkpoint’ler sayesinde yanlış bir terraform state önerisinden sonra tek tıkla geri dönüp turu adım adım izleyebilirsiniz. Token bütçeleri ise ajanın plan üretmeden uzun konuşmalara dalmasını önler.

Kapanış

Gemini CLI’yi Terraform projesine sokmanın yolu katı bir GEMINI.md ve plan odaklı bir döngüdür. Ajan size HCL üretiminde hız kazandırırken, state ve backend gibi geri dönüşü zor katmanlarda son söz terraform plan çıktısında kalmalıdır. Küçük adımlar, zorunlu validate/lint ve ayrı worktree’ler ile aynı projede birkaç ajanı bile güvenle çalıştırabilirsiniz.