Ansible'ın Yeni Gizli Dizi Maskeleme API'si: Semaphore UI'a Gizlilikten Arındırılmış Loglar Geliyor

Ansible’da gizli dizi maskeleme #

Ansible playbook’ları sunuculara bağlanmak ve uygulamaları dağıtmak için sıklıkla parolalara ve API belirteçlerine ihtiyaç duyar. Bu değerler, örneğin bir komut parola içeren bir hata döndürdüğünde, görev çıktısında da görünebilir.

Ansible bu duruma yardımcı olmak için gizli dizi maskeleme özelliğini ekliyor. Mesajın geri kalanını okunabilir tutarken, bilinen gizli değerleri çıktı içinde $REDACTED$ ile değiştirir. Görevler orijinal değerleri kullanmaya devam eder.

Bu özellik, 10 Eylül 2026’da birleştirilen Secret Masking API pull request ile eklenmiştir. Bu yazı yazıldığı sırada, ansible-core 2.22 geliştirme sürümlerinde mevcuttur. Henüz kararlı bir sürümün parçası değildir.

Basit bir playbook’a göz atalım, ardından bu özelliği Semaphore UI’da nasıl kullanmayı planladığımızı görelim.

İlk olarak, bir gizli diziyi kaydedin #

Ansible’ın hangi değerleri maskeleyeceğini bilmesi gerekir. Yeni API, kasalanmış (vaulted) değişkenler ve no_log olarak işaretlenmiş modül parametreleri gibi bilinen gizli kaynaklardan gelen değerleri kaydeder.

Sıradan bir değişken için register_secret filtresini kullanabiliriz. --extra-vars aracılığıyla iletilen bir değişkenin de kaydedilmesi gerekir; değişkeni db_password olarak adlandırmak yeterli değildir.

Bu örnek için kurgusal bir veritabanı parolası kullanacağız. masking.yml adlı bir playbook oluşturun:

- name: Try secret masking
  hosts: localhost
  gather_facts: false
  vars:
    db_password: "example-db-password-123456"

  tasks:
    - name: Register the password before using it
      ansible.builtin.set_fact:
        db_password: "{{ db_password | ansible.builtin.register_secret }}"

    - name: Show a message containing the password
      ansible.builtin.debug:
        msg: "Connecting to db.internal with password={{ db_password }}"

İlk görev parolayı kaydeder. Filtre orijinal değeri döndürür, böylece playbook veritabanına bağlanmak için bu değeri kullanmaya devam edebilir. Kayıt işlemi, herhangi bir görev değeri yazdırmadan önce gerçekleşmelidir.

Playbook’u bir ansible-core 2.22 geliştirme sürümüyle çalıştırın:

ansible-playbook -i localhost, -c local masking.yml

İkinci görev şu mesajı gösterecektir:

Connecting to db.internal with password=$REDACTED$

Burada parolayı yalnızca maskelemeyi göstermek için yazdırıyoruz. Gerçek bir playbook’ta parolayı gizli kaynağınızdan alın ve kimlik bilgilerini kasıtlı olarak yazdırmaktan kaçının.

Semaphore UI ile Entegrasyon #

Semaphore UI, hangi değişkenleri gizli dizi olarak işaretlediğinizi zaten bilmektedir. Gelecek sürümlerde bu değerleri Ansible’a otomatik olarak kaydetmek için bu bilgiyi kullanmayı planlıyoruz.

Bunun için Ansible’ın _SECRETS_INPUT_FILES seçeneğini kullanacağız. Bu seçenek _ANSIBLE_SECRETS_INPUT_FILES ortam değişkeni aracılığıyla yapılandırılır ve Ansible’ın bir playbook başlamadan önce gizli dizilerin bir listesini okumasını sağlar.

Girdi YAML veya JSON olabilir. Örnek parolamızı içeren bir belge şuna benzer:

version: 1
secrets:
  - example-db-password-123456

Bu liste Ansible’a neyi maskeleyeceğini söyler. Değişkenlerin kendileri yine de playbook’a ayrı olarak iletilir.

Planlanan entegrasyon şu kaynaklardaki gizli değerleri kapsayacaktır:

• Değişken Grupları (Variable Groups) — görevleriniz tarafından kullanılmak üzere kaydedilen gizli diziler.
• Anketler (Surveys) — bir görevi başlatırken girilen gizli yanıtlar.

Bu değerler için her bir playbook’a bir register_secret görevi eklemeniz gerekmeyecektir.

Bu yaklaşımı bir ansible-core 2.22 geliştirme sürümünde test ettik. Kaydedilen değerler debug mesajlarında, komut sonuçlarında, hata mesajlarında, ayrıntılı (verbose) çıktılarda ve Ansible’ın günlük dosyasında maskelendi. Listenin diske ayrı bir gizli dizi dosyası yazılmadan bir boru (pipe) üzerinden iletilmesi de çalıştı.

Bu seçenek şu anda dahili aşamadadır ve değişebilir. Semaphore UI desteği gelecek bir sürüm için planlanmaktadır ve uyumlu bir Ansible sürümü gerektirecektir.

Örnek: bir uygulamayı dağıtma #

Bir uygulamayı dağıtan bir Görev Şablonumuz olduğunu varsayalım. Dağıtım betiği, bir Değişken Grubunda gizli dizi olarak kaydedilmiş bir API belirtecini kullanır.

Planlanan entegrasyonla görev şu şekilde çalışacaktır:

1. Semaphore UI, belirteci playbook’a iletir.
2. Ayrıca yürütmeden önce belirteci _SECRETS_INPUT_FILES aracılığıyla Ansible’ın maskeleme listesine sağlar.
3. Playbook dağıtım betiğini gerçek belirteçle çalıştırır.
4. Betik bu belirteci çıktısına dahil ederse, Ansible görüntülenen sonuçta bunu maskeler.

Örneğin, süresi dolmuş bir belirteç görev günlüğünde şu mesajı üretebilir:

Deployment rejected: service=payments environment=staging token=$REDACTED$ reason=token expired

Günlüğü okuyan herkese belirteci ifşa etmeden hangi dağıtımın neden başarısız olduğunu görebiliriz. Aynı akış, gizli bir Anket alanı aracılığıyla girilen geçici bir belirteç için de geçerli olacaktır.

Sınırlamalar #

Maskeleme, kayıtlı değerlerle çalışır. Geliştirme uygulaması dört karakterden kısa gizli dizileri atlar ve kodlanmış veya başka şekilde dönüştürülmüş bir değer ayrı bir kayıt gerektirebilir.

Ayrıca süreç argümanlarındaki, bir playbook tarafından yazılan dosyalardaki veya Ansible dışında üretilen günlüklerdeki kimlik bilgilerini korumaz. Tüm çıktısının gizli kalması gereken görevler için no_log: true kullanmaya devam edin.

Bu entegrasyon sayesinde Semaphore UI’da işaretlenen gizli diziler Ansible’ın maskeleme sistemi tarafından da bilinecektir. Bu, sorun giderme için yararlı bilgileri korurken kimlik bilgilerinin görev günlüklerinden uzak tutulmasına yardımcı olacaktır.