Secret'lar

Özet

Bir workspace secret'ı, bir backend'in değeriyle değil ID'siyle referans verdiği, adlandırılmış, workspace'in sahip olduğu bir üçüncü taraf kimlik bilgisidir — bir takımın LLM token'ı, bir müşterinin Stripe anahtarı, kapılı bir model hub token'ı. Değer asla bir backend grafında, backend'in geçmişinde, bir CLI yanıtında, bir REST yanıtında veya herhangi bir agent modu JSON'unda görünmez.
Bir component yazarı, bir parametreyi config_schema girdisine secret: true ekleyerek bir secret olarak bildirir. Parametre tipi String olarak kalır; bir backend yazarının daha sonra bağladığı değer, secret'ın ID'sidir ve platform o ID'yi deploy zamanında değere çözer.
Bir backend yazarı, bildirilen parametreyi bir workspace secret'ına ppl backend change-parameter ile, secret'ın ID'sini geçerek bağlar. İstek ID'yi taşır, asla kimlik bilgisinin kendisini değil.
Secret'lar ppl secret list ile (veya workspace UI'da, Workspace → Secrets) meta veriyle listelenir; bunları oluşturmak, güncellemek, döndürmek ve silmek, yalnızca etkileşimli bir ppl login oturumundan çalışan bir workspace mutasyonudur, çünkü değerin girildiği yer orasıdır.
Bir secret'ı adını yeniden kullanarak döndürmek ID'yi sabit tutar, böylece o ID'ye bağlı her backend, bir graf düzenlemesi olmadan bir sonraki deploy'unda yeni değeri alır.

Workspace secret'ları gerçekte nedir

Bir workspace secret'ı, adlandırılmış, workspace'e kapsamlandırılmış bir üçüncü taraf kimlik bilgisidir — takımın LLM API token'ı, bir müşterinin Stripe anahtarı, kapılı bir model hub token'ı. Bunlar, bir backend'in konuştuğu harici hizmetler için kiracının kendi kimlik bilgileridir, platform altyapı kimlik bilgileri değil. Workspace sınırında, herhangi bir backend'den ayrı olarak yaşarlar.

Akışın üç rolü vardır. Bir component yazarı, hangi parametrelerin secret taşıdığını secret: true ile bildirir. Bir backend yazarı, o parametreleri belirli workspace secret'larına ID ile bağlar. Platform, her ID'yi deploy zamanında değerine çözer. Backend grafı, backend'in geçmişi, her CLI yanıtı (yalnızca meta veri döndüren ppl secret list dahil) ve her API yüzeyi yalnızca ID'yi taşır; değer bir component'e yalnızca deploy zamanında ulaşır.

Secret'lara workspace'ler sahiptir

Bir workspace, çok kiracılı sınırdır: her component, backend, runtime, file, secret ve takım üyesi tam olarak bir workspace'e aittir ve kiracı izolasyonu bu tek sahiplikten doğar. CLI bir seferde tek bir aktif workspace'e bağlanır — ppl workspace switch <workspace_id> onu yeniden bağlar, ppl workspace list üye olduğunuz workspace'leri gösterir ve ppl workspace update --add-user / --remove-user üyeliği ayarlar. Secret deposu workspace'e kapsamlandırıldığı için, değiştirmek hangi secret'ları gördüğünüzü değiştirir ve başka bir workspace'teki bir takım arkadaşı bunun secret'larını asla görmez.

Güvenlik garantisi

Garanti spesifiktir: bir workspace secret'ının değeri şurada asla görünmez:

backend graf tanımında, dışa aktarılmış, çatallanmış veya incelenmiş herhangi bir biçim dahil;
herhangi bir ppl komutunun çıktısında, agent modu JSON dahil;
REST API yanıtlarında;
backend'in geçmişini gösteren herhangi bir görünümde;
herhangi bir etkinlik akışında.

Değer, platform bağlanmış ID'yi çözdüğünde, deploy zamanında çalışan component'e ulaşır. O noktadan itibaren, başına gelenler component'in sorumluluğundadır — platform, bir component yazarının onu günlüğe kaydetmesini veya bir çıktı akışı aracılığıyla açığa çıkarmasını engelleyemez. Secret işleyen component'ler onları günlüğe kaydetmemelidir.

Sunucuda tutulan bir secret'ın iletildiği hedef, bir istek tarafından değil, platform tarafından sabitlenir: istemci tarafından sağlanan bir URL, değerin nereye gönderildiğini yeniden yönlendiremez.

Bir secret'ı döndürmek — değerini aynı ad altında yeniden ayarlamak — ID'yi sabit tutar, böylece backend'in bağlaması sağ kalır; değişen şey, ID'nin çözümlendiği değerdir. O ID'ye bağlı herhangi bir backend'in bir sonraki deploy'u yeni değeri alır; mevcut canlı deployment'lar yeniden deploy edilene kadar orijinal değerlerini korur.

Zihinsel model — ID ile bağla

   Workspace UI                       Component
   ┌──────────────────────┐           ┌──────────────────────────┐
   │ secret  hf_prod      │           │ reads config.hf_token    │
   │   id:  <secret_id>   │           │ as plain String          │
   └──────────┬───────────┘           │ (resolved at deploy time)│
              │ bind by ID            └─────────────▲────────────┘
                                                    │ value at
   ┌──────────────────────────────┐                 │ deploy time
   │ Backend  ·  vertex 3         │                 │
   │   parameter  hf_token        │                 │
   │     type:   String           │                 │
   │     value:  <secret_id>      ├─────────────────┘
   └──────────────────────────────┘

Üç rol, üç sınır. Workspace, secret'a ve onu yönetmek için kullanılan UI'a sahiptir. Backend yazarı bir parametreyi bir secret ID'sine bağlar. Component, çözümlenmiş değeri deploy zamanında, diğer herhangi bir yapılandırma değeri gibi okur. Sınırlar, değeri ulaşması gereken tek yer dışındaki her yüzeyden uzak tutan şeydir.

Component yazarı parametreyi bildirir

Bir kimlik bilgisine ihtiyaç duyan bir component tasarlarken bu çerçeveyi kullanın.

Bir component yazarı, config_schema girdisine secret: true ekleyerek hangi parametrelerin secret taşıdığını bildirir. Parametre tipi String olarak kalır. secret: true bayrağı platforma iki şey söyler: parametrenin, bir backend bağladığında bir değişmez değer yerine bir secret ID'sini kabul ettiğini ve platformun o ID'yi deploy zamanında değerine çözdüğünü.

config_schema:  hf_token:    type: String    secret: true    description: Hugging Face token for gated model repos.

Component, config.hf_token'ı deploy zamanında düz bir String olarak, diğer herhangi bir string parametresiyle aynı şekilde okur. Component ID'yi asla görmez. Component yazarının bakış açısından, bir secret, manifestte secret: true bayrağı olan, yapılandırılmış bir string'tir. Yazar hangi parametrelerin secret olduğunu bildirir; yazar herhangi bir secret değeri girmez — değerler daha sonra, etkileşimli bir oturumdan veya workspace UI'dan oluşturulur.

Bir secret parametresi ayrıca Maybe<String> (isteğe bağlı bir secret, varsayılan olarak Nothing ()) veya List<String> (bir secret kümesi, örneğin bir döndürme penceresi sırasında kabul edilen anahtarlar) olarak da bildirilebilir. Bağlanmamış bırakılan isteğe bağlı bir secret, component'e hiç geçilmez; bir List<String> secret'ı, component'e bağlama sırasıyla çözümlenmiş değerlerin bir List<String>'i olarak ulaşır. Diğer her bildirilen tip secret: true için reddedilir.

Sınıflandırma component yazarının kararıdır: değeri hiçbir yüzeyde görünmemesi gereken bir parametre secret: true alır; diğer her şey normal bir parametre olarak kalır. Platform bayrağı bağlama zamanında zorlar — secret: true bildirilen bir parametre değişmez değerleri reddeder ve secret: true bildirilmeyen bir parametre secret ID'leri reddeder.

Backend yazarı ID ile bağlar

Bir backend'in bir secret parametresi ayarlaması gerektiğinde bu çerçeveyi kullanın.

Bağlama, normal bir parametre mutasyonudur — diğer herhangi bir parametreyi ayarlayan aynı ppl backend change-parameter fiili, değer bir değişmez yerine secret'ın ID'si olmak üzere:

ppl backend change-parameter <bid> --vertex <v> \    --name hf_token --type String --value "<secret_id>"

Tip sistemi bağlamayı change-parameter çağrısında doğrular. Bir secret: true yuvası değişmez görünen değerleri reddeder; secret olmayan bir yuva secret ID'lerine çözülen değerleri reddeder. Bir uyumsuzluk, herhangi bir deploy'dan önce, düzenleme zamanında başarısız olur.

ID, ppl secret list'ten (veya workspace UI'dan) gelir. Listeleme yalnızca meta veri döndürür — ID, ad, açıklama, son güncelleme — asla bir değer değil. Bir secret oluşturmak ID'sini döndürür ve o ID, backend yazarının bağladığı şeydir. Secret'ları oluşturmak, güncellemek, döndürmek ve silmek, yalnızca etkileşimli bir ppl login oturumundan çalışan workspace mutasyonlarıdır — bu, değerin gerçekten girildiği tek işlem kümesidir ve o giriş, onu komut geçmişine veya otomasyon günlüklerine yansıtmayan bir yüzeye aittir.

Döndürme graf düzenlemeleri olmadan nasıl çalışır

Bir kimlik bilgisinin değişmesi gerektiğinde bu çerçeveyi kullanın.

Bir secret değerini döndürmek bir backend düzenlemesi gerektirmez. Bir secret'ı mevcut adı altında yeniden ayarlamak, döndürmeler boyunca ID'yi sabit tutar, backend'in o ID'ye bağlaması geçerli kalır ve o ID'ye bağlı herhangi bir backend'in bir sonraki deploy'u yeni değeri alır. Mevcut canlı deployment'lar yeniden deploy edilene kadar eski değerlerini korur.

Bu, takım ölçeğinde önemlidir. Birçok backend aynı hub token'ına bağlandığında, token'ı döndürmek tek bir işlemdir ve her backend yeni değeri bir sonraki deploy'unda alır. Bağlama bir ID'yedir, bu yüzden bir değer değişikliği ona referans veren her grafa görünmezdir.

Tasarımın şekli

"workspace değere sahiptir" ile "backend değere referans verir" arasındaki ayrım, tasarımın geri kalanını işlevsel kılan şeydir. Aynı workspace'teki iki backend aynı secret ID'sini bağlayabilir ve deploy anında aynı değeri alabilir. Başka bir workspace'e klonlanmış bir backend, grafla seyahat eden hiçbir değer olmadan, farklı bir secret ID'sine yeniden bağlanır. Kimlik bilgilerini taşıyan bir takım, onları workspace sınırında taşır ve onlara bağlı backend'ler çalışmaya devam eder. ID sözleşmedir; değer, yönetimi workspace'e ait olandır.

Maliyet, fazladan bir kavram (workspace secret'ı) ve bağlama akışında fazladan bir adımdır (ID'yi ppl secret list'ten veya UI'dan okumak). Karşılığında, değer asla olmaması gereken bir yüzeye girmez, döndürme kimlik bilgisi başına tek bir işlemdir ve secret/secret-olmayan sınıflandırması platformun tip sistemi tarafından bağlama zamanında zorlanır.

Bunun yeri

Workspace secret'ları, kiracının sahip olduğu üçüncü taraf kimlik bilgileri için platformun birinci sınıf mekanizmasıdır. ID-ile-bağla tasarımı, ortak işlemleri basit bırakırken değeri her kullanıcıya görünür yüzeyden uzak tutar. Component yazarı hangi parametrelerin secret olduğunu bildirir, backend yazarı ID'leri bağlar, workspace sahibi değerleri yönetir ve platform ID'leri deploy zamanında çözer. Her rolün bir işi vardır ve aralarındaki sınır, değeri kontrol altında tutan şeydir.

İlgili

Backend'ler — secret ID'sinin bir vertex parametresine bağlandığı yer.
Component'ler — secret: true'nun bildirildiği yer.
Tipler — bağlamanın doğruladığı parametre-tip sistemi.
Solution'lar — sevk edilen bir ürün içinde üçüncü taraf kimlik bilgilerine ihtiyaç duyan backend'ler.