Foundry Local, yapay zekâ modellerini buluta veri göndermeden kendi altyapınızda çalıştırmanızı sağlıyor. Azure Local üzerinde bunun önerilen yolu, Foundry Local’i Azure Arc’a bağlı bir AKS (Kubernetes) kümesine Azure Arc uzantısı olarak kurmak. Bu yazıda kurulumu Azure CLI ve Azure portal üzerinden adım adım anlatıyorum. Helm ile kurulum da destekleniyor.
Modelleri ileride Foundry Local’deki Agentic Retrieval ile kullanmayı düşünüyorsanız, kurulum sırasında Microsoft Entra ID kimlik doğrulamasını varsayılan hâliyle açık bırakmanız gerekiyor.
Önemli: Foundry Local zaten kuruluysa bu adımlar yerine uzantıyı güncelleme belgesini izleyin. 2610 sürümüne yükseltmek için önce 2609 sürümünde olmanız gerekiyor; daha eski sürümlerden doğrudan yükseltme desteklenmiyor. Bu kısıt ilk kurulum için geçerli değil.
Ön koşullar
- Azure Arc’a bağlı, 1.29 veya üzeri sürümde bir Kubernetes kümesi.
- Kümenin desteklenen bir bölgede bulunması.
- Yetkilendirme ve kimlik doğrulama için bir uygulama kaydı (app registration).
- Kümeye göre yapılandırılmış
kubectl. - Kurulu Helm.
- Kümede bir Gateway API sağlayıcısı. Foundry Local model trafiğini Ingress controller yerine Kubernetes Gateway API üzerinden yönlendiriyor. Desteklenen sağlayıcı, Gateway API controller olarak çalışan Istio (
istio-base+istiod, 1.29 veya üzeri). Sidecar injection ve ambient mode isteğe bağlı; inference operator bunlara ihtiyaç duymuyor. - Gateway API CRD’leri (v1.4.0 veya üzeri).
- Gateway API Inference Extension CRD’leri (v1.5.0 veya üzeri).
- Modellerin uzantının/operator’ün release namespace’inde, normalde
foundry-local-operatoriçinde dağıtılması.
GPU için ek koşullar: GPU iş yükleri çalıştıracaksanız kümede CUDA sürücüleri kurulu NVIDIA GPU düğümleri olmalı ve NVIDIA için Kubernetes device plugin yapılandırılmış olmalı (NVIDIA GPU Operator bu iş için kullanılabilir). NVIDIA Jetson Thor dahil ARM64 model sunma desteği önizleme aşamasında. Jetson Thor dağıtımlarında modelleri kurmadan önce NVIDIA container runtime/RuntimeClass ile sürücü ve cihaz erişimini yapılandırmanız ve kimlik doğrulama ile model önbelleği bileşenleri dahil gerekli ARM64 imajlarını içeren bir uzantı ya da chart sürümü kullanmanız gerekiyor.
1. Adım: Gateway API CRD’leri ve Istio’yu kurun
Foundry Local, küme içi ve dış trafiği yönlendirmek için Kubernetes Gateway API kullanıyor. Önce Gateway API CRD’lerini, ardından Gateway API sağlayıcısı olarak Istio’yu kurun. istiod açılışta CRD’leri keşfediyor ve onları gördüğünde istio GatewayClass’ını kaydediyor. Sırayı ters çevirirseniz istiod‘u yeniden başlatmanız gerekiyor ve bazı kümelerde bu sorunlu olabiliyor.
# 1. Gateway API CRD'lerini kurun (standard channel)
kubectl apply --server-side -f \
https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml
# 2. Gateway API Inference Extension CRD'lerini istiod'dan önce kurun;
# böylece istiod açılışta InferencePool desteğini algılar
kubectl apply --server-side -f \
https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v1.5.0/manifests.yaml
# 3. Istio Helm deposunu ekleyin
helm repo add istio https://istio-release.storage.googleapis.com/charts
helm repo update
# 4. Istio base'i kurun (küme kapsamlı CRD'ler)
helm install istio-base istio/base \
-n istio-system --create-namespace --wait
# 5. istiod kontrol düzlemini kurun
helm install istiod istio/istiod \
-n istio-system \
--set pilot.env.ENABLE_GATEWAY_API_INFERENCE_EXTENSION=true \
--waitENABLE_GATEWAY_API_INFERENCE_EXTENSION=true, istiod‘un InferencePool CRD’sini tanıması için gerekli. Çok replikalı vLLM ModelDeployment’larında ve spec.vllm.epp.enabled: true ayarlanan dağıtımlarda EPP yönlendirmesi varsayılan olarak açık olduğu için bu bayrak önerilen varsayılan. Devam etmeden önce GatewayClass’ın kabul edildiğini doğrulayın:
kubectl get gatewayclass istio
# NAME CONTROLLER ACCEPTED AGE
# istio istio.io/gateway-controller True 1mBu mimaride Istio yalnızca Gateway API sağlayıcısı olarak çalışıyor; sidecar injection, ambient mode ve mesh mTLS gibi özellikler isteğe bağlı. Bağlantısız (ALDO) ortamlarda Istio, Gateway API CRD’leri ve Inference Extension CRD’leri Foundry Local expansion pack içinde geliyor ve edgeartifacts registry’si bunları otomatik olarak içe aktarıyor; internete çıkış gerekmiyor.
2. Adım: cert-manager ve trust-manager’ı kurun
Foundry Local, otomatik sertifika yönetimi için cert-manager ve trust-manager gerektiriyor. Bunları Azure CLI ile cert-manager uzantısı olarak kurabilirsiniz:
az k8s-extension create \
--cluster-name <arc_kume_adi> \
--name "azure-cert-manager" \
--resource-group <arc_kumesinin_resource_group'u> \
--cluster-type connectedClusters \
--extension-type Microsoft.CertManagement \
--scope cluster \
--release-train stable \
--config config.enableGatewayAPI=true \
--config cert-manager.crds.keep=true \
--config trust-manager.defaultPackage.enabled=false \
--config trust-manager.secretTargets.enabled=true \
--config trust-manager.secretTargets.authorizedSecretsAll=truePowerShell kullanıyorsanız satır sonlarındaki \ yerine ters tırnak (`) kullanmanız yeterli; bu yazıdaki diğer komutlar için de aynısı geçerli.
3. Adım: Foundry Local uzantısını kurun
Uzantıyı Azure CLI ya da Azure portal ile kurabilirsiniz. Microsoft Entra ID kimlik doğrulaması varsayılan olarak açık. İleride Agentic Retrieval kullanacaksanız bu varsayılanı koruyun ve Entra uygulama kimliğini girin; Entra ID’yi kapatırsanız Agentic Retrieval dağıttığınız modellere bağlanamıyor.
Seçenek 1: Azure CLI
az k8s-extension create \
--resource-group <arc_kumesinin_resource_group'u> \
--cluster-name <arc_kume_adi> \
--name "inference-operator" \
--extension-type Microsoft.Foundry \
--scope cluster \
--release-namespace "foundry-local-operator" \
--cluster-type connectedClusters \
--auto-upgrade-minor-version true \
--release-train stable \
--config entraAuth.tenantId="<azure_tenant_id>" \
--config entraAuth.clientId="<app_registration_client_id>"Kurulum sırasında şu isteğe bağlı parametreleri de ayarlayabilirsiniz:
| Parametre | Açıklama |
|---|---|
entraAuth.enabled | Boolean, varsayılan true. Açıkken JWT doğrulama ve ARM RBAC yetkilendirmesi için Entra Auth SDK ve msi-adapter sidecar’ları inference pod’larına ekleniyor. Kapalıyken tenantId ve clientId isteğe bağlı. Agentic Retrieval için açık olmalı. |
satAuth.enabled | Boolean, varsayılan true. Kubernetes service account token (SAT) kimlik doğrulamasını seçen ModelDeployment’ları destekliyor. |
satAuth.audience | Kabul edilen service account token’larında aranan audience. Varsayılan foundry-local. |
guardrails.enabled | Varsayılan false. Paketlenmiş Guardrails’i (önizleme) kurup uygun ONNX ve vLLM dağıtımlarında çıkarım taramasını açıyor. |
watch.namespaces | Boş bırakın. Model dağıtımları yalnızca uzantının release namespace’inde destekleniyor; uyumluluk için yalnızca bu namespace’le eşleşen tek bir değer kabul ediliyor. |
storeModel.cacheJob.resources | Model önbellek işinin bellek ayarları; varsayılan istek 16Gi, limit 32Gi. Büyük modelleri indirirken OOM yaşanmaması için yüksek tutulmuş. Kaynakları kısıtlı ortamlarda ya da küçük modellerle requests.memory ve limits.memory düşürülebilir; istek limiti aşmamalı. |
evaluation.enabled | Boolean, varsayılan true. Veri seti yükleme, değerlendirme çalıştırma ve sonuç indirme gibi model değerlendirme özelliklerini açıyor. Kapalıyken kalıcı depolama oluşturulmuyor. |
evaluation.pvc.accessMode | Değerlendirme volume’ünün erişim modu. Varsayılan ReadWriteOnce bileşenleri tek düğümde tutuyor; RWX destekli bir StorageClass varsa ReadWriteMany öneriliyor. Kurulumdan sonra değiştirilemiyor, değiştirmek için uzantıyı silip yeniden kurmak gerekiyor. |
evaluation.pvc.storageClassName | Değerlendirme volume’ünün StorageClass’ı. ReadWriteMany seçildiğinde zorunlu, örneğin azurefile. |
model-store.registry.storage.size | Tüm önbelleğe alınmış model dosyalarını tutan paylaşımlı PVC’nin kapasitesi. Varsayılan 100Gi küçük ve orta modellere uygun. Tek başına 100 GB’ı aşabilen Devstral ya da Magistral gibi büyük GPU/vLLM modellerinde, barındıracağınız tüm modellerin toplamı artı %20–30 pay önerilir. |
Inference API’nin dışa açılması. api.exposure Helm değeri, Foundry Local Inference API kontrol düzlemi endpoint’inin nasıl açılacağını belirliyor. Bu, tek tek modellerin veri düzlemi endpoint’lerini yöneten spec.endpoint.exposure‘dan ayrı bir ayar.
| Değer | Davranış |
|---|---|
internal | Varsayılan. Operator küme içi Gateway üzerinden bir HTTPRoute oluşturuyor ve API küme içinde /inference-api yolunda erişilebiliyor. |
external | API hem küme içi Gateway hem dış LoadBalancer Gateway üzerinden, https://<dis-gateway-adresi>/inference-api adresinde açılıyor. |
none | HTTPRoute oluşturulmuyor; API yalnızca ClusterIP servisi üzerinden, örneğin kubectl port-forward ile erişilebiliyor. |
Seçenek 2: Azure portal
- Azure portalda Azure Local üzerindeki Arc’a bağlı Kubernetes kümenize gidin.
- Settings > Extensions > + Add seçin.
- Listeden Foundry Local on Azure Local‘ı seçip Create‘e tıklayın.
- Basics sekmesinde aboneliği, kümenin resource group’unu, bölgeyi, bağlı Kubernetes kümesini ve uzantı adını (örneğin
foundry) girin, ardından Next‘e tıklayın.
- Configuration sekmesinde Microsoft Entra ID’yi Enabled ya da Disabled olarak seçin. Açıksa uygulama kaydınızın Entra application ID’sini girin. Kubernetes namespaces alanını boş bırakın; model dağıtımları
foundry-local-operatornamespace’inde çalışıyor.
- Review + Create ile parametreleri kontrol edip Create‘e tıklayın.
- Dağıtım bitince Extensions altında uzantının durumunun Succeeded olduğunu doğrulayın.
4. Adım: Operator’ü doğrulayın
Inference operator uzantısının kurulduğunu ve tüm pod’ların çalıştığını kontrol edin:
kubectl get pods -n foundry-local-operator
kubectl get crd | grep foundryDevam etmeden önce tüm pod’ların Running durumuna gelmesini bekleyin. Beklenen çıktı şuna benzer:
5. Adım: Uzantının kimliğine Reader rolü atayın
Inference operator’ün Arc’a bağlı Kubernetes küme kaynağını okuyabilmesi için uzantının managed identity’sine Reader rolü atamanız gerekiyor. Azure CLI ile önce principal ID’yi alın:
az k8s-extension show --resource-group <RESOURCE_GROUP> --cluster-name <CLUSTER_NAME> --cluster-type connectedClusters -n inference-operatorÇıktıdaki identity.principalId değerini kullanarak rolü atayın:
az role assignment create \
--assignee "<PRINCIPAL_ID>" \
--role "Reader" \
--scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Kubernetes/connectedClusters/<CLUSTER_NAME>/Providers/Microsoft.KubernetesConfiguration/extensions/inference-operator"Aynı işlemi portal üzerinden yapmak için:
- Arc’a bağlı kümenizde Settings > Extensions altından
inference-operatoruzantısını seçin. - Properties sekmesinde, Cluster extension details altındaki principal ID’yi kopyalayın.
- Access control (IAM) > + Add > Add role assignment seçin.
- Reader rolünü seçip Next‘e tıklayın.
- Assign access to için User, group, or service principal seçin.
- + Select members ile kopyaladığınız principal ID’yi (adı
inference-operatorolmalı) bulup seçin. - Review + assign‘a iki kez tıklayın ve atamanın bitmesini bekleyin.
Sorun giderme
Kurulumdan sonra bir sorunla karşılaşırsanız şu komutlar işinize yarar:
# ModelDeployment durumu ve olayları
kubectl describe mdep <ad> -n foundry-local-operator
# Operator logları
kubectl logs -f deployment/inference-operator -n foundry-local-operator
# Pod durumu
kubectl get pods -n foundry-local-operator -l app.kubernetes.io/managed-by=inference-operator
kubectl describe pod <pod-adi> -n foundry-local-operator
kubectl logs <pod-adi> -n foundry-local-operator
# Bir dağıtımın oluşturduğu tüm kaynaklar
kubectl get deploy,svc,httproute -n foundry-local-operator -l foundry.azure.com/deployment=<ad>
# Katalog ConfigMap
kubectl get configmap foundry-local-catalog -n foundry-local-operator -o yaml
# Kendi getirdiğiniz (BYO) modeller için Model kaynağı
kubectl get models -n foundry-local-operator
kubectl describe model <kayitli-model-adi> -n foundry-local-operatorKatalog modellerinin Model kaynağı yok; katalog dağıtımları için yukarıdaki ModelDeployment kontrollerini kullanın. Uzantı hazır olduğunda bir sonraki adım ilk modeli dağıtıp çıkarım çalıştırmak.
Kurulumun en çok dikkat isteyen kısmı sıralama: Gateway API ve Inference Extension CRD’leri istiod‘dan önce kurulmalı, aksi hâlde InferencePool desteği devreye girmiyor. Kurulumdan sonra değiştirilemeyen ayarlara da baştan karar vermek gerekiyor; değerlendirme volume’ünün erişim modu bunlardan biri. Agentic Retrieval ihtimali varsa Entra ID’yi açık bırakmak ve büyük vLLM modelleri planlanıyorsa model deposu boyutunu 100Gi varsayılanının üzerinde tutmak sonradan yaşanacak sorunları önler.
