yq ile YAML Yapılandırma Dosyalarını Düzenleme

yq, jq'nin JSON'u işlemesine benzer şekilde çalışan, taşınabilir bir komut satırı YAML işlemcisidir. Python veya Ruby ile betik yazmadan YAML dosyalarını okumanızı, filtrelemenizi ve düzenlemenizi sağlar.

yq adını taşıyan iki popüler araç vardır:

• mikefarah/yq (Go) — etkin olarak bakımı yapılır; YAML, JSON, XML ve TOML destekler. Bu derste bu sürüm kullanılır.
• kislyuk/yq (Python) — YAML için bir jq sarmalayıcısıdır; söz dizimi farklıdır.

Go sürümünü yükleyin:

• macOS'ta brew install yq
• Linux'ta snap install yq
• Veya ikili dosyayı indirin: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Doğrulayın: yq --version, v4.x.x yazdırmalıdır. 4. sürümü, v3'ten farklı bir ifade söz dizimi kullanır; bu nedenle sürüm önemlidir.

Herhangi bir şeyi düzenlemeden önce YAML alanlarını okumayı öğrenin. Bir Kubernetes Deployment verildiğinde, nokta gösterimli yollarla iç içe geçmiş tüm değerleri çıkarabilirsiniz.

Örnek deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: my-app:1.0.0

Temel okuma komutları:

• yq '.metadata.name' deployment.yaml — my-app yazdırır
• yq '.spec.replicas' deployment.yaml — 3 yazdırır
• yq '.spec.template.spec.containers[0].image' deployment.yaml — my-app:1.0.0 yazdırır

Çıktı varsayılan olarak düz metindir (tırnak işareti yoktur). Betiklerde ham dizelere ihtiyacınız varsa -r bayrağını ekleyin veya | yq -r kullanın.

Gerçek dünyadaki kullanım için en önemli bayrak -i (yerinde) bayrağıdır. Bu bayrak olmadan yq, sonuçları standart çıktıya yazdırır ve dosyayı değiştirmeden bırakır.

Söz dizimi:

• Yalnızca okuma (standart çıktı): yq '.spec.replicas' file.yaml
• Yerinde düzenleme: yq -i '.spec.replicas = 5' file.yaml

Atama işleci = bir değer belirler. İfade tam bir yq filtresidir; bu nedenle okuma ve yazma işlemlerini tek geçişte birleştirebilirsiniz.

Önemli: yq -i dosyanın tamamını yeniden yazar. Alanla aynı satıra yerleştirilen açıklamalar genellikle korunur, ancak bağımsız açıklama blokları taşınabilir. Toplu yerinde düzenlemeleri çalıştırmadan önce YAML dosyanızı her zaman sürüm denetimine kaydedin.

Önce -i olmadan test edin, ardından çıktıyı beğendiğinizde ekleyin.

Çok yaygın bir CI görevi, yeni bir imaj oluşturulduktan sonra Kubernetes bildirimindeki Docker imaj etiketini artırmaktır. yq ile bu işlem tek satırlık bir komuta dönüşür.

Desen şöyledir:

• Dizi 0 dizinini sabit kodlamaktan kaçınmak için kapsayıcıyı adına göre select() kullanarak hedefleyin.
• Yeni değeri belirlemek için |= (güncelleme işleci) veya = kullanın.

Dizi dizinini kullanma (kapsayıcı listesi değişirse kırılgan olur):

• yq -i '.spec.template.spec.containers[0].image = "my-app:2.1.0"' deployment.yaml

select() kullanma (sağlamdır):

• yq -i '(.spec.template.spec.containers[] | select(.name == "app")).image = "my-app:2.1.0"' deployment.yaml

Bir CI işlem hattında etiketi bir kabuk değişkeni olarak geçirirsiniz:

Mevcut alanları güncellemenin yanı sıra yq, yeni anahtarlar ekleyebilir veya mevcut anahtarları silebilir.

Alan ekleme:

• Var olmayan bir yola doğrudan atama yapın: yq -i '.metadata.labels.version = "v2"' file.yaml
• Üst anahtar (labels) eksikse yq bunu otomatik olarak oluşturur.

Alan silme:

• del() işlevini kullanın: yq -i 'del(.metadata.annotations)' file.yaml
• Dizi öğesini dizinine göre silin: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Diziye öğe ekleme:

• yq -i '.spec.template.spec.containers += [{"name": "sidecar", "image": "envoy:latest"}]' file.yaml

Kubernetes bildirimleri çoğu zaman tek bir dosyada, --- ile ayrılmış birden çok kaynağı bir araya getirir. Varsayılan olarak yq, böyle bir dosyadaki tüm belgeleri işler.

Temel teknikler:

• Tüm belge türlerini listeleyin: yq '.[].kind' multi.yaml — belgeler üzerinde yineleme yapmak için baştaki .[] ifadesine dikkat edin.
• Türe göre belirli bir belgeyi hedefleyin: yq 'select(.kind == "Service")' multi.yaml
• Yalnızca eşleşen belgeleri yerinde düzenleyin:

yq -i 'select(.kind == "Deployment").spec.replicas = 2' multi.yaml

select() koşuluyla eşleşmeyen belgeler değiştirilmeden aktarılır; böylece Service, ConfigMap ve diğer kaynaklarınız olduğu gibi kalır.

Birden çok belgeli bir dosyayı tek tek dosyalara ayırmak için yq çıktısı üzerinde döngü kurabilir veya şunu kullanabilirsiniz:

• yq -s '.kind' multi.yaml — her belge için .kind değerinin adını taşıyan bir dosya yazar.

CI yapılandırma dosyaları (.github/workflows/*.yml, .gitlab-ci.yml) de YAML'dır. Aynı yq komutları çalışır, ancak yollar derin biçimde iç içe olabilir.

Yaygın CI yama görevleri:

• Çalıştırıcı sürümünü sabitleme: tüm işler genelinde runs-on değerini güncelleyin.
• Eylem sürümünü güncelleme: belirli bir eylemi kullanan adımları bulun ve uses alanındaki sürümü artırın.
• Bir bayrağı açıp kapatma: iş akışı düzeyindeki bir ayarı etkinleştirin veya devre dışı bırakın.

Örnek: actions/checkout kullanan tüm adımları v4'e güncelleyin:

yq -i '(.jobs[].steps[] | select(.uses == "actions/checkout@v3")).uses = "actions/checkout@v4"' .github/workflows/ci.yml

Bu deyim — [] ile yineleme yapma, select() ile daraltma, = ile atama — yapılandırılmış her YAML düzenlemesi için temel desendir.

yq ifadelerinde değerleri sabit kodlamak betikleri kırılgan hale getirir. yq, kabuk değişkenlerini env() işlevi veya strenv() kısa yazımı ile eklemeyi destekler.

• env(VAR_NAME) — ortam değişkenini okur ve uygun YAML türüne dönüştürür (sayı sayı olarak, dize dize olarak kalır).
• strenv(VAR_NAME) — her zaman bir dize döndürür; imaj etiketleri için kullanışlıdır.

Bu yaklaşım, YAML yolları içeren çift tırnaklı kabuk dizelerinin içine değişken yerleştirirken yaşanan tırnaklama kâbusunu önler.

Desen:

export IMAGE_TAG="my-app:3.0.0"
yq -i '.spec.template.spec.containers[0].image = strenv(IMAGE_TAG)' deployment.yaml

replicas gibi sayısal alanları ayarlarken YAML türünün korunması (tırnak içine alınmış dize değil, tam sayı) için env() kullanın.

Bazen bir yama dosyasını (küçük bir geçersiz kılma YAML'ı) temel yapılandırmaya uygulamanız gerekir — örneğin Kustomize tarzı iş akışlarında ortama özgü geçersiz kılmalar için.

yq, * birleştirme işleci kullanarak iki dosyayı birleştirebilir:

• yq '. *= load("patch.yaml")' base.yaml — yamayı temel dosyayla derinlemesine birleştirir ve sonucu standart çıktıya yazar.
• Temel dosyayı yerinde güncellemek için -i ekleyin: yq -i '. *= load("patch.yaml")' base.yaml

Birleştirme davranışı:

• Yamadaki skaler değerler temel dosyadakilerin üzerine yazılır.
• Eşlemeler derinlemesine birleştirilir (yamada bulunmayan anahtarlar korunur).
• Diziler varsayılan olarak değiştirilir, sonuna eklenmez. Bunun yerine ekleme yapmak için *+ kullanın.

Bu yaklaşım, boşluk değişikliklerinde bozulan kırılgan sed betiklerinin yerini alır.

Yama uygulanmış bir YAML'ı kümeye uygulamadan önce onu doğrulamak ve isteğe bağlı olarak diğer araçlar için JSON'a dönüştürmek iyi bir uygulamadır.

Söz dizimini doğrulama:

• yq '.' file.yaml && echo "Valid" — yq ayrıştırma hatalarında 1 koduyla çıkar; bu nedenle CI geçitlerinde kullanılabilir.

YAML'ı JSON'a dönüştürme:

• yq -o=json '.' file.yaml — biçimlendirilmiş JSON çıktısı verir.
• Daha ileri JSON işleme için jq'ya yönlendirin: yq -o=json '.' file.yaml | jq '.metadata.name'

JSON'u YAML'a dönüştürme:

• yq -P '.' file.json — giriş JSON olduğunda -P seçeneği YAML (biçimlendirilmiş) çıktısını zorunlu kılar.

Bu dönüştürmeler, yq'yu YAML yerel araçları (Helm, kubectl) ile JSON yerel araçları (Terraform, AWS CLI, jq) arasında bir köprü hâline getirir.

Tüm teknikleri bir araya getirelim: GitOps işlem hattının parçası olarak bir Kubernetes Deployment bildirimine yama uygulayan gerçek bir CI betiği.

Betik şunları yapar:

1. Giriş YAML'ını üzerinde işlem yapmadan önce doğrular.
2. Tüm değişken ikameleri için env() / strenv() kullanır.
3. İsim tabanlı bir select() kullanarak kapsayıcı imajı etiketini günceller.
4. Çoğaltma sayısını artırır.
5. Geçerli zaman damgasıyla bir deploy-time açıklaması ekler.
6. Göndermeden önce çıktıyı yeniden doğrular.

Bu yaklaşım, işlem hattı eşzamanlı çalışsa bile her adımın atomik ve denetlenebilir olmasını sağlar.

yq ile çok belgeli Kubernetes YAML dosyalarını düzenleme konusundaki anlayışınızı sınayın.

YAML yapılandırma dosyalarını yq ile düzenleme dersini tamamladınız. İşlenen konuların kısa özeti aşağıdadır:

• Kurulum: mikefarah/yq Go ikilisini (v4) kullanın. yq --version ile doğrulayın.
• Okuma: .spec.replicas gibi nokta gösterimli yollar; [0] veya [] yinelemesiyle dizi erişimi.
• Yerinde düzenleme: -i seçeneği dosyayı yeniden yazar. Önce her zaman -i olmadan önizleme yapın.
• Sağlam hedefleme: Sabit dizi dizinleri yerine select(.name == "app") kullanmayı tercih edin.
• Ekleme / silme: Yeni bir yol oluşturmak için bu yola değer atayın; alanları kaldırmak için del() kullanın.
• Çok belgeli dosyalar: Bir kaynağı hedeflemek ve diğerlerine dokunmamak için select(.kind == "...") kullanın.
• CI değişkenleri: Dizeler için strenv(VAR), türü belirlenmiş değerler için env(VAR) kullanın — kabuk tırnaklama hatalarını önler.
• Birleştirme: . *= load("patch.yaml"), yama uygulanmamış anahtarları kaybetmeden bir geçersiz kılma dosyasını derinlemesine birleştirir.
• Doğrulama ve dönüştürme: Bir lint geçidi olarak yq '.'; biçim dönüştürme için -o=json ve -P.

CI'daki herhangi bir YAML yaması için temel yaklaşım şudur: doğrula → seç → ata → doğrula. Bunu strenv() ve select() ile birleştirdiğinizde kırılgan tek satırlık sed komutlarına bir daha ihtiyaç duymazsınız.