Terraform Import 2.0: Mevcut Altyapınızı Kolayca Terraform’a Dahil Edin

Terraform Import Bloğu, Terraform 1.5 sürümüyle tanıtılan ve mevcut altyapı kaynaklarının Terraform’un durum dosyasına (terraform.tfstate) aktarılmasını sağlayan bir özelliktir. Geleneksel “terraform import” komutunun aksine, import bloğu sayesinde mevcut olan bir kaynağın içe aktarılması doğrudan Terraform plan ve apply süreçlerinin doğal bir parçası haline gelir​. Bu sayede import işlemi, doğrudan state dosyasına yapılan ayrı bir müdahale yerine, diğer Infrastructure as Code (IaC) işlemleri gibi kod üzerinden yönetilir ve plan aşamasında önizlenebilir hale gelir​.

Özetle, Terraform import bloğu mevcut altyapıyı Terraform’a daha kolay yönetilebilir ve kontrollü bir biçimde kazandırmak için getirilmiştir. Bu sayede Terraform, önceden oluşturulmuş kaynakları da kendi yönetim döngüsüne alırken daha az sürpriz ve daha fazla kontrol imkanı sunar​.

“Import Block” kavramı nedir?

Import bloğunu kullanabilmek için, öncelikle ilgili kaynağın Terraform yapılandırma dosyalarına bir resource bloğu olarak tanımlanmış olması gerekir. Terraform, import sırasında bu resource bloğuna bakarak state dosyasına ekleme yapar. Eğer kodda resource tanımı yoksa, import bloğu tek başına yeterli değildir çünkü Terraform neyi yöneteceğini bilemez. Geleneksel terraform import komutunda bu süreç önce komutla state dosyasına kaynak ekleme, ardından da aynı kaynağın kodunu elle yazma şeklindeydi.

Terraform import block örnek söz dizimi aşağıdaki gibidir​.

import {
  to = <resource_address>
  id = <resource_identifier>
}

• to: Mevcut kaynağı Terraform state'ine eklerken verilecek adresi belirtir. Yani, import edeceğiniz kaynağa Terraform kodunda hangi resource blok'u karşılık geliyorsa onu işaret eder.
• id: Mevcut kaynağın provider API'sindeki benzersiz tanımını belirtir​. Bu genellikle kaynağın ID'si veya adı olur. Her sağlayıcı için format farklıdır. Bu değerinin doğru ve plan aşamasında bilinir olması gerekir, aksi takdirde import işlemi gerçekleştirilemez.

Çalışma Mekanizması

Import bloğunu Terraform yapılandırmasına ekledikten sonra, normal Terraform plan ve apply komutlarını kullanarak kaynağı Terraform yönetimine alabilirsiniz. Apply tamamlandığında, ilgili kaynak Terraform state dosyasına “imported” olarak eklenmiş olacaktır. Terraform, state dosyası içinde bu kaynağı artık sanki Terraform tarafından yönetiliyormuş gibi tutar, ancak Terraform, import bloğu sayesinde bu kaynağın önceden oluşturulmuş olduğunu, yani Terraform tarafından yaratılmadığını anlayabilir. Terraform dokümantasyonuna göre, import işlemi gerçekleştikten sonra isterseniz import bloğunu kodunuzdan kaldırabilirsiniz veya kaynakların kökenini belgelemek için bırakabilirsiniz. Her iki durumda da, kaynak artık state dosyasında kayıtlı olduğu için Terraform onu yönetmeye devam edecektir.

Terraform Import 1.0'ın Sorunları Neydi?

Klasik terraform import komutu, bir kaynağı Terraform'un state dosyasına eklerdi; ancak .tf dosyalarında o kaynağa ait bir kod oluşturmazdı. Bu nedenle, bir kaynağı import ettikten sonra, kullanıcıların elle doğru bir resource bloğu yazmaları gerekiyordu. Eğer yazılan bu kod, gerçek altyapıdaki kaynakla tam uyumlu olmazsa, terraform plan komutu hatalı değişiklikler önerebilir veya beklenmedik sonuçlar doğurabilirdi. Örneğin, bazı ayarlar eksik ya da farklı tanımlanırsa, Terraform bu değerleri sıfırlamaya ya da değiştirmeye çalışabilirdi. Bu sorunlar, mevcut kaynakları Terraform ile sorunsuz şekilde yönetmeyi güçleştiriyordu.

Import 2.0 ile Gelen Yenilikler

Terraform 1.5 ile birlikte, kaynak tanımı ve import talimatı yazıp apply edildiğinde, hem state dosyası güncellenir hem de kaynak zaten kodda tanımlı olduğu için sonraki işlemlere hazır hale gelir. Bu yöntem, sık tekrarlanan veya çok sayıda kaynağın dahil edilmesi senaryolarında daha kullanışlı ve hatasızdır; eski yöntem ise genellikle tek seferlik veya elle müdahale gereken durumlarda kalır​.

Import bloğu, planlama aşamasında çalıştığı için CI/CD süreçlerine sorunsuz kullanılabilir. Artık ayrı bir manuel komut çalıştırmaya gerek kalmadan, pipeline içinde Terraform apply komutu import işlemini de otomatik olarak yapacaktır​. Bu da otomasyonu artırır ve insan hatasını azaltır.

Klasik terraform import komutu doğrudan state dosyasını günceller ve önizleme imkanı vermezken, import bloğu ile yaptığımızda terraform plan çıktısında import edilecek kaynaklar ve olası konfigürasyon farkları önceden görülebilir​. Terraform, import edilecek kaynağın mevcut durumunu okuyup plan içinde gösterir. Bu sayede herhangi bir değişiklik uygulamadan önce, import sonucunda neler olacağını inceleyebilirsiniz.

Import işlemi kod içinde tanımlandığından, versiyon kontrol sistemlerinde değişiklik olarak kaydedilir​. Ayrıca yeni ekip üyeleri kodu incelediğinde, import bloklarını görüp bazı kaynakların Terraform tarafından sonradan yönetilmeye alındığını anlayabilirler. Bu durum, altyapı yönetiminde bilgi paylaşımını kolaylaştırır.

Eğer birden fazla kaynağı Terraform’a almak istiyorsanız, her biri için ayrı CLI komutu çalıştırmak zahmetli olabilir. Import blokları, gerek birden fazla ayrı kaynak için birden çok blok yazarak, gerekse *for_each* meta-argümanını kullanarak toplu import** işlemlerini kolaylaştırır​.

Azure Üzerinde Terraform Import Bloğu Kullanım Örneği: Storage Account

Bu örnekte, rg-trf-example adlı resource group içerisinde önceden oluşturulmuş olan strgtrfexample isimli bir Storage Account’u, “Germany West Central” bölgesinde konumlandırılmış haliyle Terraform yönetimine nasıl dahil edebileceği gösterilecektir.

Bu kaynağı Terraform ile yönetmeye almak istiyoruz. Kaynağı silmeden veya yeniden oluşturmadan sadece Terraform’un state dosyasına dahil edeceğiz.

Azure CLI ile kaynak ID’sini öğreniyoruz:

az storage account show -n strgtrfexample -g rg-trf-storage --query id -o tsv

Örnek çıktı: /subscriptions/<SubscriptionID>/resourceGroups/rg-trf-storage/providers/Microsoft.Storage/storageAccounts/strgtrfexample

Bu ID’yi import bloğunda kullanacağız.

Terraform Dosyasını Oluşturma

1. Klasik yapıda kullanım

resource "azurerm_storage_account" "example" {
  name                     = "strgtrfexample"
  location                 = "germanywestcentral"
  resource_group_name      = "rg-trf-storage"
  account_tier             = "Standard"
  account_replication_type = "LRS"
  account_kind             = "StorageV2"
}

import {
  to = azurerm_storage_account.example
  id = "/subscriptions/<SubscriptionID>/resourceGroups/rg-trf-storage/providers/Microsoft.Storage/storageAccounts/strgtrfexample"
}

Bu örnekte resource tanımını doğrudan .tf dosyamızın içinde oluşturuyoruz. Import bloğunu da aynı dosyada kullanabiliriz. terraform plan ve terraform apply komutları ile kaynak başarıyla Terraform state dosyasına eklenir.

2. Modül kullanımı

Daha büyük projelerde genellikle modüler yapı tercih edilir. Bu durumda kaynak tanımı modül içinde yer alır ve import bloğu root seviyesinde yazılır:

module "storage" {
  source = "./modules/storage"

  storage_account_name = var.storage_account_name
  resource_group_name  = var.resource_group_name
  location             = var.location
}

import {
  to = module.storage.azurerm_storage_account.example
  id = "/subscriptions/<SubscriptionID>/resourceGroups/rg-trf-storage/providers/Microsoft.Storage/storageAccounts/strgtrfexample"
}

Bu yapıda, kaynak tanımı stacks/azure-infra dizinindeki bir Terraform modülünün içinde yer alır. Import bloğu ise dışarıdan bu kaynağa referans vererek işlemi root seviyeden başlatır. Böylece kod temizliğini bozmadan kaynakları modül yapısında yönetmeye devam edebiliriz.

Dikkat Edilmesi Gerekenler

Import blokları yalnızca Terraform v1.5.0 ve sonrasında desteklenir​. Daha eski Terraform sürümlerinde bu blok tanınmayacaktır. Dolayısıyla, bu özelliği kullanmak isteyenlerin Terraform’u güncellemesi gerekmektedir.

Mevcut Kaynak Tanımı Şart: Önceki bölümlerde belirtildiği üzere, import işlemi için Terraform kodunda ilgili kaynağın bir resource bloğu ile önceden tanımlanmış olması gerekir. Terraform, yalnızca kendisine açıkça tanımlanmış kaynağı import edebilir​. Bu da kullanıcıya, mevcut altyapının Terraform’daki karşılığını doğru şekilde tanımlama sorumluluğu yükler. Import bloğu, kaynağın Terraform kodunu oluşturmaz, bu kodu kullanıcının yazması gerekir.

Koşullu veya Dinamik Kullanım Yok: Import bloğu, yalnızca önceden belirlenmiş ve sabit değerlerle çalışır. Plan aşamasında değişkenler veya koşullu ifadeler kullanılamaz, yani bir kaynağın import edilip edilmeyeceği dinamik olarak belirlenemez. Import bloğu ya kodda yer alır ve çalışır, ya da hiç yer almaz. Çoklu import işlemleri için for_each kullanılabilir ancak girdileri plan aşamasında tamamen belirlenmiş olmalıdır. Bu sınırlamalar import işlemlerinin öngörülebilir ve tutarlı olmasını sağlamak amacıyla getirilmiştir.

Desteklenmeyen Kaynak Tipleri: Çoğu Terraform provider’ı kaynak importunu destekler; ancak bazı özel veya eski resource türleri henüz bu özelliği desteklemiyor olabilir. Bu gibi durumlarda, import bloğu doğru yazılmış olsa bile apply aşamasında hata alınabilir.

Konfigürasyon Uyumluluğu (Drift Sorunu): Import bloğu, mevcut kaynağı Terraform state’ine ekler. Ancak Terraform kodundaki yapılandırma, kaynağın gerçek durumu ile uyumsuzsa apply sırasında değişiklik önerebilir. Örneğin, kodda tanımlı olan kaynak türü veya performans seviyesi (örneğin SKU: Standard yerine Premium) mevcut yapıdaki ile farklıysa, Terraform bunu değiştirmeye çalışabilir; bazı durumlarda kaynak tamamen silinip yeniden oluşturulabilir. Bu nedenle plan çıktısı mutlaka kontrol edilmelidir.

• https://developer.hashicorp.com/terraform/language/import#:~:text=Note%3A%20Import%20blocks%20are%20only,0%20and%20later
• https://spacelift.io/blog/terraform-import-block#:~:text=In%20contrast%2C%20when%20the%20,transitioning%20infrastructure%20into%20Terraform%20management
• https://www.env0.com/blog/terraform-import-commands-example-tips-and-best-practices#:~:text=Plan%3A%201%20to%20import%2C%200,added%2C%201%20changed%2C%200%20destroyed
• https://developer.hashicorp.com/terraform/language/import#:~:text=The%20,record%20of%20the%20resource%27s%20origin
• https://developer.hashicorp.com/terraform/language/import