Claude Code, Foundry ve APIM ile kurumsal kontrol

Geliştiricilere Claude Code verirken kimlik, model erişimi, bütçeler ve özel ağı kurumsal kontrol altında nasıl tutarsınız? Microsoft Tech Community’deki bu mühendislik rehberinin yazarı, bu soruya yanıt olarak Claude Code on Foundry (CCOF) adlı bir uygulama geliştirmiş ve bunu birden fazla kurumda canlıya aldığını söylüyor. Rehber; geliştiricilerin ve yöneticilerin ne elde ettiğini, bileşenlerin nasıl bir araya geldiğini ve genişletmeden önce tek bir kullanıcının nasıl dağıtılıp test edileceğini anlatıyor.

Önemli not: CCOF yazarın kendi uygulaması ve GitHub deposunda yayımlanıyor; bir Microsoft ürünü değil. Ekran görüntüleri müşteri ortamlarından değil kayıtlı laboratuvar çalışmalarından alınmış, adlar ve kimlikler değiştirilmiş ya da maskelenmiş. Yazar, kurumsal dağıtım deneyiminin her iş yükü için doğrulanmış bir kapasite anlamına gelmediğini de vurguluyor.

1. Geliştiriciler ve yöneticiler ne elde ediyor?

Erişim grup üyeliğinden geliyor; bir istemci yapılandırma dosyası tek başına erişim vermiyor.

2. Mimari: tek ağ geçidi, ayrı sorumluluklar

Resolver bir geliştirici uç noktası değil; yalnızca ağ geçidinin managed identity’sini kabul ediyor. APIM de Foundry’yi kendi managed identity’si ve hesap kapsamlı Cognitive Services User rolüyle çağırıyor. Normal istek akışı şöyle:

• Kullanıcı Entra’ya giriş yapıyor; bir yardımcı araç Claude Code’a ağ geçidi için kısa ömürlü bir token veriyor.
• APIM tenant’ı, hedef kitleyi (audience), istemci uygulamayı ve devredilmiş kapsamı doğruluyor.
• Önbellekte yoksa APIM yetkili grubu ve modelleri belirlemek için resolver’ı çağırıyor.
• APIM kişi ve grup limitlerini uygulayıp isteği Foundry’ye iletiyor.
• Kullanım telemetrisi kişi, grup, model ve maliyet bilgisini taşıyor; arka plandaki uzlaştırma bütçeleri güncelliyor.

Varsayılan izin önbelleği 120 saniye ve ayarlanabiliyor. Birden fazla gruptaki bir kişi x-ccof-project başlığına grubun Object ID’sini yazarak grup seçebiliyor; seçici yoksa bu ay en çok harcama kaydedilen grup, ardından daha düşük öncelik numarası seçiliyor. Ayrıntılar için mimari ve güven sınırları belgesine bakılabilir.

3. Azure ve Entra ön koşulları

Başlamadan önce platform, ağ ve Entra sahipleri şunlarda anlaşmalı:

• Azure aboneliği, kaynak grubu ve bölgeler.
• APIM katmanı, ağ erişimi ve kapasite. Özel bir arka uç için erişilebilir özel ağ yolu gerekiyor.
• Birincil ve yedek Foundry dağıtımları, tam dağıtım adları ve çıkarım coğrafyası.
• İstenirse Cosmos bölge kapasitesi ve pilot için throughput.
• Alt ağ yetkilendirmesi, DNS, yönlendirme ve giden erişim.
• Mevcut Entra grup Object ID’leri, test üyeleri ve bütçeler.
• Azure rol atamalarını kimin oluşturacağı ve Microsoft Graph uygulama izinlerini kimin vereceği.

Otomatik eşitleme için sync kimliği GroupMember.Read.All, kullanıcıların etkin/devre dışı durumunu okumak için User.Read.All kullanıyor. Bunlar geliştiricilere değil, Function App’in managed identity’sine verilen Microsoft Graph uygulama izinleri. Yönetici grup araması için ayrıca onaylı Graph okuma izinleri gerekiyor. Yeni managed identity izinlerinin önbellekteki token’lara yansıması saatler sürebileceği için bunları dağıtım penceresinden önce vermek öneriliyor.

Özel IP’ler arka uç URL’sine değil DNS’e aittir. Hesabın host adını kullanın:

https://<foundry-account>.services.ai.azure.com/anthropic

Özel DNS bunu private endpoint IP’sine çözüyor. Host adını https://10.x.x.x ile değiştirmek host adı tabanlı TLS doğrulamasını bozuyor. Özel DNS bölgeleri globaldir; önemli olan APIM ağının hangi bölgeyi çözdüğü ve dönen IP’ye ulaşıp ulaşamadığı. Peering tek başına DNS yönlendirmesi sağlamıyor.

APIM herkese açık erişimi kapatılırsa hem kabul testi makinesinin hem geliştirici makinelerinin kurumsal ağ, VPN ya da VDI yolu ve özel DNS’e ihtiyacı var. Bir operatör internetten ARM ile dağıtım yapabilir ama yine de özel ağ geçidini çağıramayabilir.

4. Aşamalı dağıtım

Dağıtım günü runbook’u sırayı ve beklenen çıktıları, yapılandırma rehberi ise her seçimi açıklıyor.

Depo klonunda, PowerShell 7 ile:

$cfg = Join-Path $HOME 'ccof-private/staged.config.json'
$run = Join-Path (Get-Location) 'infra/staged/Invoke-StagedDeployment.ps1'
pwsh -File $run -Stage 0 -ConfigPath $cfg

# Preview, review, then apply one stage at a time.
pwsh -File $run -Stage 1 -ConfigPath $cfg
pwsh -File $run -Stage 1 -ConfigPath $cfg -Apply

Bir sonraki aşamaya ancak önceki başarılı olduktan sonra geçin; yapılandırmayı ve kaydedilen durumu birlikte saklayın. 1. aşama yalnızca oluşturma yapıyor, bu yüzden yüksek erişilebilirlik seçeneklerine bu aşama tamamlanmadan karar verin.

Mevcut bir APIM kullanılırsa ağ ayarları, birimleri ve mevcut API’leri korunuyor. Kullanılmayan CCOF adları seçin (örneğin apiId: ccof-claude-messages, apiPath: ccof, arka uç kimliği ccof-foundry). Global politikası yine geçerli ve servis düzeyi tanılama diğer API’leri de içerebilir; bu kapsamı ve maliyeti sahibiyle gözden geçirin.

Runbook, ön koşullardan sonra 2-3 saatlik bir çalışma penceresi öngörüyor. Kayıtlı provada iki gruplu, fiyatlı API hedefi yaklaşık 2 saat 12 dakika, ilk gerçek Claude Code yanıtı yaklaşık 2 saat 28 dakika sürmüş. Yazar bunların kurulum süresi garantisi değil, laboratuvar gözlemi olduğunu belirtiyor.

5. Bir Entra grubunu dahil edin

Yönetim konsolunda Groups → Onboard ile:

• Onaylı mevcut grubu bulun ya da Object ID’sini girin.
• Aylık kişi başı bütçeyi belirleyin ve grubun toplam bir tavanı olup olmayacağına karar verin.
• İzin verilen modelleri, arka ucu ve limitleri seçin.
• Planı gözden geçirip gönderin.

Bütçe, token kotası ve sağlayıcı kapasitesi farklı kontroller. Örneğin günde iki milyon token’lık grup kotası, 2.000 kişi paylaştığında kişi başına yalnızca 1.000 token demek. Grup limitlerini demo değerlerini kopyalamak yerine bilinçli belirleyin. Otomatik eşitleme için test kullanıcısını Entra grubuna ekleyip başarılı bir eşitleme çalışmasını kontrol edin; “Enabled” görünen bir zamanlayıcı kabulün kanıtı değil, üyelik verisinin gerçekten Cosmos’a yansıması gerekiyor.

6. Claude Code ve CLI yapılandırması

7. aşama bir istemci yapılandırması dışa aktarıyor. Bu dosyayı kurumun onaylı kanalıyla paylaşın; asla bir kullanıcının token’ını ya da Azure oturum önbelleğini paylaşmayın.

Windows (depo klonunda, geliştirici olarak):

npm ci --prefix .\client --no-audit --no-fund
$env:CCOF_CONFIG_FILE = (Resolve-Path '<client-config.json>').Path
pwsh -NoProfile -File .\scripts\client\Set-ClaudeCodeGateway.ps1 -ConfigPath $env:CCOF_CONFIG_FILE -Confirmed -UsageStatusLine
& "$env:USERPROFILE\.claude\ccof-token.cmd" login

Son satır Azure CLI ile oturum açan bir yapılandırma için; kurulumun yazdırdığı tam oturum açma komutunu kullanın.

macOS (CCOF burada signInMethod: azure-cli kullanıyor; Azure CLI ve PowerShell 7 kurulu olmalı):

npm ci --prefix ./client --no-audit --no-fund
New-Item -ItemType Directory -Force ~/.config/ClaudeGateway | Out-Null
Copy-Item '<client-config.json>' ~/.config/ClaudeGateway/config.json
pwsh -NoProfile -File ./scripts/client/Set-ClaudeCodeGateway.ps1 -Confirmed -UsageStatusLine
& "$HOME/.claude/ccof-token" login

Yardımcı araç, istemci yapılandırmasının yanında kendi Azure CLI profilini kullanıyor ve token’ı ayarlara yazmadan Claude Code’a veriyor. Önemli, gizli olmayan ayarlar aşağıdaki gibi; dağıtım adları örnek ve Foundry’deki adlarla birebir eşleşmeli:

{
  "apiKeyHelper": "'/Users/alex/.claude/ccof-token' token",
  "model": "claude-sonnet-5",
  "env": {
    "ANTHROPIC_BASE_URL": "https://ccof-sample.azure-api.net/ccof",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "240000"
  }
}

Bu alıntı kurulumun tamamı değil: Script ayrıca çakışan sağlayıcı değişkenlerini, kullanıcı başına yapılandırmayı, model listelerini ve isteğe bağlı kullanım entegrasyonunu ele alıyor. İlgisiz ayarları koruyor; yönetilen politikalar her zaman önceliği koruyor.

Yazar, uyumluluk uyarılarının gizlenmemesi ve dağıtılan modellere uygun bir istemci sürümü ile model eşlemesi kullanılması gerektiğini belirtiyor. Etkileşimli Claude Code’da küçük bir prompt gönderip izinli bir /model seçimi deneyin ve bağlantıyı kontrol edin. Kurulan CCOF kullanım skill’i kişinin bütçesini gösterebiliyor; bazı Claude Code sürümlerinde yerleşik bir /usage da olduğu için hangisinin çağrıldığını doğrulayın.

VS Code’da Claude Code: Kurulum, eklentinin gizli olmayan ortam ayarlarını yapıyor ve harici kimlik doğrulama için barındırılan oturum açma istemini kapatıyor. VS Code penceresini yeniden yükleyip Claude Code panelini kullanın; etkin ağ geçidini ve modeli, iç faturalandırmada bir isteği doğrulayın. Eklentiyi açmak tek başına yönlendirmenin kanıtı değil.

7. Claude Desktop ayrı bir yapılandırma

Depodaki Desktop yükleyicisi Windows’u destekliyor ve kurulu sürümün yapılandırma şemasını kontrol ediyor:

pwsh -NoProfile -File .\scripts\client\Set-ClaudeDesktopGateway.ps1 -ConfigPath $env:CCOF_CONFIG_FILE -Confirmed

Desteklenen sürüme ve oturum açma yöntemine göre uyumlu bir yardımcı script ya da harici kimlik sağlayıcı profili seçiyor; yönetilen çıkarım politikasını atlamıyor. Bu, CLI için ANTHROPIC_BASE_URL ayarlamaktan farklı.

Desktop’ı tamamen kapatıp yeniden başlatın, desteklenen bağlantı/profil ayarlarını inceleyin, ağ geçidi profilini seçip küçük bir prompt gönderin ve CCOF telemetrisiyle eşleştirin. Yazar, runbook kanıtlarında doğrulanmış başarılı bir yerel Desktop sohbeti bulunmadığını ve bunu sunmadığını açıkça belirtiyor. macOS Desktop kurulumu bu deponun yükleyicisi tarafından desteklenmiyor. Ayrıntılar: istemci yapılandırması ve uyumluluk.

8. Dağıtımı değil, kullanıcı yolunu test edin

Kullanıcının makinesinden, gerekli ağda ve oturum açtıktan sonra:

pwsh -NoProfile -File ./scripts/client/Test-ClientGatewayAccess.ps1 -Confirmed

Bu komut token yardımcısını kontrol ediyor, ağ geçidine küçük bir istek gönderiyor ve kurulu Claude Code CLI’ı çalıştırıyor. gateway_result için httpStatus: 200, claude_code_result için ok: true beklenmeli; not_installed sonucu bir Claude Code testi sayılmaz.

Bir reconciler çalışmasından sonra kişinin bütçesini kontrol edin. Yönetim konsolunda Budgets → Snapshots → People ve Chargeback → Developers bölümlerini açın.

Kullanım dışa aktarımları 5.000 satırla sınırlı ve kesilme durumunu raporluyor; büyük raporları filtrelerle bölün. Konsolda adlar onaylı Graph izinleriyle çözülebiliyor, dışa aktarımlar ise object ID kullanıyor.

Üyelik zamanlayıcısı sağlıklı mı? CCOF Log Analytics çalışma alanında şu sorguyu çalıştırın:

FunctionAppLogs
| where TimeGenerated > ago(1h)
| where Message has "ccof.sync.run.v1"
| extend r = parse_json(substring(Message, indexof(Message, "{")))
| project TimeGenerated, outcome=tostring(r.outcome),
          membersAdmitted=tolong(r.counts.membersAdmitted),
          writeFailures=tolong(r.counts.writeFailures),
          reasons=tostring(r.reasons)
| order by TimeGenerated desc
| take 10

Beklenen üye sayılarına sahip, açıklanamayan yazma hatası olmayan yakın tarihli başarılı bir çalışma görmelisiniz. graph_permission_missing hatası, Graph izninin geliştirici uygulama kaydına değil sync kimliğine verilmesi gerektiğini gösteriyor.

9. Yüksek erişilebilirlik ve ölçekleme sınırları

• Bölge yedekli APIM ve Functions, kapasite ve sürekli hazır hesaplama maliyetiyle birlikte bir erişilebilirlik bölgesi arızasına karşı koruyor.
• İkinci bir Cosmos bölgesi kayıt erişilebilirliğini korumaya yardım ediyor; bölge ayarları ve servis kapasitesi ayrı konular.
• Bir Foundry öncelik havuzu, yapılandırılan devre kesici açıldığında yedeğe geçebiliyor.

Aynı abonelikteki Foundry hesapları model kota havuzunu paylaşıyor; ikinci bir hesap kota eklemiyor. Kota izolasyonu ayrı aboneliklerle sağlanabilir. APIM v2 ve Function App’ler tek bölgeli bir yığın olarak kalıyor: Cosmos ve yedek Foundry hesabı ayakta kalsa bile (örnekteki) Central India bölgesindeki bir kesinti servisi durdurabilir. Diyagram otomatik çok bölgeli ağ geçidi kurtarması olarak okunmamalı.

Bir pilotla başlayın ve başarılı model isteklerini, gerçekçi streaming’i, ağ geçidi CPU’sunu, Cosmos throttling’i, eşitleme süresini ve reconciler güncelliğini ölçün. Boyutlandırma rehberi laboratuvar ölçümlerini iş yükü tahminlerinden açıkça ayırıyor.

Bütçeler kesin fatura tavanı değil. Uzlaştırma gecikmeli; streaming’deki prompt cache kategorileri ağ geçidinin canlı defterinde bilinmiyor. Gösterilen harcamayı alt sınır olarak görün ve faturayla ayrıca uzlaştırın.

Kaynaklar

• CCOF deposu
• Geliştirici ve filo ekleme
• Bütçeler ve koruma davranışı
• Yüksek erişilebilirlik ve kurtarma sınırları
• Claude Code: LLM ağ geçidine bağlanma
• Microsoft Learn: APIM token-limit politikası
• Microsoft Learn: Foundry’de Claude kotaları

CCOF’u dağıtmak faturalandırılan Azure kaynakları oluşturuyor. Yazar, uygulamanın kurumun güvenlik, ağ ve kapasite incelemeleriyle birlikte kullanılmasını ve ekran görüntülerinin her kurumsal yapılandırma için bir sertifika olmadığını vurguluyor.

Rehberin değeri, Claude Code’u kurumsal kimlik ve bütçe kontrolüne bağlarken nelerin ayrı kontroller olduğunu dürüstçe ayırması: bütçe, kota ve kapasite farklı şeyler; harcama alt sınır; Desktop başarısı doğrulanmamış. CCOF resmi bir Microsoft ürünü olmadığı için destek ve bakım sorumluluğu da onu dağıtan ekipte kalıyor.

Kaynak: https://techcommunity.microsoft.com/blog/azure-ai-foundry-blog/an-engineering-guide-to-claude-code-on-microsoft-foundry-with-azure-api-manageme/4569334