Bereitstellung des Diensts
In diesem Thema werden Schritte zum Bereitstellen des KI-Dienstes und des OTel Collectors im AKS beschrieben, der nach dem Vorgang unter Bereitstellung der Infrastruktur unter Verwendung eines vorkonfigurierten Docker-Images bereitgestellt wird.
Annahmen
Die folgenden Schritte setzen voraus, dass die kundenseitig gehostete Codebeamer KI Infrastruktur (Terraform IaC) erfolgreich bereitgestellt wurde.
Es wird vorausgesetzt, dass alle erforderlichen Azure-Ressourcen und -Abhängigkeiten verfügbar und ordnungsgemäß konfiguriert sind.
Schritt 1: OTel Collector-Dienst bereitstellen
Stellen Sie OpenTelemetry Collector auf dem im Rahmen von Bereitstellung der Infrastruktur erstellten AKS bereit.
Ein Helm-Beispieldiagramm für den OTel Collector-Stack wird mit dem Servicepaket helm-otel-chd/ bereitgestellt. Dies wird als Referenzimplementierung bereitgestellt. Prüfen und aktualisieren Sie es vor der Bereitstellung gemäß Ihrer Umgebung.
1. Importieren Sie Docker-Images in Ihre private Azure Container Registry.
Alle vier Images müssen vor der Bereitstellung in Ihrer privaten Azure Container Registry verfügbar sein.
ACR_NAME="<YOUR_ACR_NAME>"
# OTEL Collector
docker pull otel/opentelemetry-collector-contrib:latest
docker tag otel/opentelemetry-collector-contrib:latest ${ACR_NAME}.azurecr.io/otel/opentelemetry-collector-contrib:latest
docker push ${ACR_NAME}.azurecr.io/otel/opentelemetry-collector-contrib:latest
# Zipkin
docker pull openzipkin/zipkin:latest
docker tag openzipkin/zipkin:latest ${ACR_NAME}.azurecr.io/openzipkin/zipkin:latest
docker push ${ACR_NAME}.azurecr.io/openzipkin/zipkin:latest
# Prometheus
docker pull prom/prometheus:latest
docker tag prom/prometheus:latest ${ACR_NAME}.azurecr.io/prom/prometheus:latest
docker push ${ACR_NAME}.azurecr.io/prom/prometheus:latest
# Aspire Dashboard
docker pull mcr.microsoft.com/dotnet/aspire-dashboard:latest
docker tag mcr.microsoft.com/dotnet/aspire-dashboard:latest ${ACR_NAME}.azurecr.io/dotnet/aspire-dashboard:latest
docker push ${ACR_NAME}.azurecr.io/dotnet/aspire-dashboard:latest
2. Beispiel für OTel-Helm-Diagramm per Push in Repository übertragen.
cd /helm-otel-chd
helm package .
helm push <helm-chart-name>-<version>.tgz oci://<ACR_NAME>.azurecr.io/<target_repo>
3. Konfigurieren Sie helm-otel-chd/values-azure.yaml.
 |
Ersetzen Sie alle <PLACEHOLDER>-Werte in helm-otel-chd/values-azure.yaml.
|
acrToken:
enabled: true
registry: "<YOUR_ACR_NAME>.azurecr.io"
tokenName: "<TOKEN_NAME>"
tokenPassword: "<TOKEN_PASSWORD>"
secretName: "<SECRET_NAME>"
otelCollector:
image:
repository: <YOUR_ACR_NAME>.azurecr.io/otel/opentelemetry-collector-contrib
prometheus:
image:
repository: <YOUR_ACR_NAME>.azurecr.io/prom/prometheus
zipkin:
image:
repository: <YOUR_ACR_NAME>.azurecr.io/openzipkin/zipkin
aspireDashboard:
image:
repository: <YOUR_ACR_NAME>.azurecr.io/dotnet/aspire-dashboard
ACR-Token
Passen Sie den Abschnitt acrToken entsprechend Ihrer Registry an. Verwenden Sie die Token‑Konfiguration, wenn Sie Azure Container Registry (ACR) verwenden. Wenn Sie eine andere Container-Registry verwenden, aktualisieren oder deaktivieren Sie acrToken und verwenden Sie die entsprechende Authentifizierung. Beispiel: imagePullSecrets.
▪ acrToken.registry – > . Wählen Sie Ihren ACR-Namen aus.
▪ acrToken.tokenName – > >
▪ acrToken.tokenPassword – Zuvor generiertes ACR-Token-Passwort.
▪ acrToken.secretName – Name des Kubernetes-Geheimnisobjekts; muss sich vom cb-ai-service Geheimnisnamen unterscheiden.
Repository-Name für Komponenten
Aktualisieren Sie die image.repository für jede Komponente mit Ihrem ACR-Anmeldeserver.
4. Stellen Sie den OTel-Stack mithilfe von Helm bereit.
a. Rufen Sie Anmeldeinformationen für den AKS-Cluster ab.
az aks get-credentials \
--resource-group <AKS_RESOURCE_GROUP> \
--name <AKS_NAME>
b. Überprüfen Sie die Konnektivität.
kubectl get namespace
c. Führen Sie den Helm‑Installationsbefehl aus.
helm upgrade --install <release_name> \
oci://<ACR_NAME>.azurecr.io/<PATH_TO_HELM_REPO> \
--version <VERSION> -n <NAMESPACE> --create-namespace -f values-azure.yaml
5. Konfigurieren Sie cb-ai-service so, dass Telemetriedaten gesendet werden.
Legen Sie in der Datei helm-chd/values-azure-customer-hosted.yaml Folgendes fest:
otel:
enableOtelCollector: true
otelExporterEndpoint: "otel-collector-chd.cbai-otel.svc.cluster.local:4317"
|
|
Der vollständige FQDN, <service>.<namespace>.svc.cluster.local, ist erforderlich, da cb-ai-service im cb-ai-service Namespace ausgeführt wird, während der OTel-Stack im cbai-otel Namespace ausgeführt wird.
|
Konfiguration der Exportprogramme
Der OTel-Collector verwendet drei Pipelines, um Telemetriedaten zu routen. Diese sind in der Datei values.yaml unter otelCollector.config vorkonfiguriert und erfordern keine manuellen Änderungen.
◦ Verwenden Sie für Traces Zipkin.
exporters:
zipkin:
endpoint: "http://ZIPKIN_SERVICE:9411/api/v2/spans"
format: json
▪ Sendet verteilte Traces zur Visualisierung an Zipkin.
▪ ZIPKIN_SERVICE ist ein Platzhalter. Helm ersetzt es zum Zeitpunkt der Bereitstellung automatisch durch otel-collector-chd-zipkin.
◦ Verwenden Sie für Metriken Prometheus.
exporters:
prometheus:
endpoint: "0.0.0.0:8889"
namespace: "cbai"
send_timestamps: true
resource_to_telemetry_conversion:
enabled: true
▪ OTel Collector Sammler stellt Metriken für :8889 bereit. Prometheus scraped den Endpunkt alle 15 Sekunden.
▪ namespace: cbai ist ein Metriknamenspräfix. Metriken werden als cbai_* angezeigt.
◦ Verwenden Sie für Protokolle das Aspire-Dashboard.
exporters:
"otlp/aspire":
endpoint: "ASPIRE_SERVICE:18889"
tls:
insecure: true
▪ Leitet Protokolle über OTLP oder gRPC an das Aspire-Dashboard weiter.
▪ ASPIRE_SERVICE wird bei der Bereitstellung automatisch durch otel-collector-chd-aspire-dashboard ersetzt.
Schritt 2: ZIP-Datei des Image-Archivs herunterladen
Laden Sie die Datei cb-ai-chd-service-<Version>.zip unter PTC Software-Download - Codebeamer AI herunter.
Überprüfen Sie die Prüfsumme des heruntergeladenen Artefakts mit dem publizierten Wert .sha256 unmittelbar nach dem Herunterladen und vor dem Entpacken, Bereitstellen oder Ausführen.
Schritt 3: Docker-Image in Docker laden
Entpacken Sie das Image-Archiv, und laden Sie das Image in Ihrem lokalen Docker.
docker load -i cbai-chd-1.1.0-r1-snapshot-<build_number>.tar.gz
Nachfolgend finden Sie eine erwartete Ausgabe.
Loaded image: cb-ai-service-chd:<tag>
Schritt 4: Docker-Image verifizieren
Bestätigen Sie, dass das Image lokal verfügbar ist.
docker images | grep cb-ai-service-chd
Nachfolgend finden Sie eine erwartete Ausgabe.
cb-ai-service-chd 1.1.0-r1-snapshot-b4507 <image-id> <time> <size>
Schritt 5: Image per Push an Container Registry übergeben
1. Versehen Sie das Image für die Container Registry mit Tags.
Bevor das Image in die Container Registry (ACR) gepusht wird, muss es korrekt getaggt werden.
Verwenden Sie das geladene Image-Tag unverändert nach dem Laden von Docker. Referenzieren Sie die Ausgabe für Schritt 4 für das Tag.
docker tag cb-ai-service-chd:<tag> <ACR_NAME>.azurecr.io/<REPOSITORY_NAME>:<tag>
Generische Container Registry:
docker tag <source-image>:<tag> <registry>/<repository>:<tag>
Beispiel:
docker tag cb-ai-service-chd:1.1.0-r1-snapshot-b4507 mycustomeracr.azurecr.io/cb-ai-service-chd:1.1.0-r1-snapshot-b4507
2. Melden Sie sich bei Container Registry an.
Authentifizieren Sie z.B. Docker für die ACR.
az acr login --name <ACR_NAME>
3. Pushen Sie das getaggte Image an ACR.
Beispiel: docker push <ACR_NAME>.azurecr.io/cb-ai-service-chd:<tag>.
4. Pushen Sie das Helm-Chart an ACR oder das Repository.
cd /helm-chd
helm package .
helm push <helm-chart-name>-<version>.tgz oci://<ACR_NAME>.azurecr.io/<target_repo>
Schritt 6: Helm-Chart für KI-Dienst konfigurieren
Wechseln Sie in das Helm‑Chart‑Verzeichnis im Repository.
cd /helm-chd
Konfigurieren Sie values-azure-customer-hosted.yaml.
Aktualisieren Sie die Datei helm-chd/values-azure-customer-hosted.yaml.
Beispielkonfiguration:
# -------------------------------
# ACR Token Configuration
# -------------------------------
acrToken:
enabled: true
registry: "<ACR_NAME>.azurecr.io"
tokenName: "<ACR_TOKEN_USERNAME>"
tokenPassword: "<ACR_TOKEN_PASSWORD>"
secretName: "<secret_name>"
# -------------------------------
# Image Configuration
# -------------------------------
image:
domain: "<ACR_NAME>.azurecr.io"
repository: "<repository_name>"
pullPolicy: IfNotPresent
tag: "<IMAGE_TAG>"
# -------------------------------
# Workload Identity
# -------------------------------
workloadIdentity:
enabled: true
clientId: "<USER_ASSIGNED_MANAGED_IDENTITY_CLIENT_ID>"
tenantId: "<AZURE_TENANT_ID>"
tokenExpirationSeconds: 3600
# -------------------------------
# Azure Configuration
# -------------------------------
azure:
openai:
baseUrl: "https://<OPENAI_RESOURCE_NAME>.openai.azure.com/"
auth:
tenantId: "<AZURE_TENANT_ID>"
audience: "<APP_REGISTRATION_CLIENT_ID>"
ACR-Token
Passen Sie den Abschnitt acrToken entsprechend Ihrer Registry an. Verwenden Sie die Token‑Konfiguration, wenn Sie Azure Container Registry (ACR) verwenden. Wenn Sie eine andere Container-Registry verwenden, aktualisieren oder deaktivieren Sie acrToken und verwenden Sie die entsprechende Authentifizierung. Beispiel: imagePullSecrets.
◦ acrToken.registry - > >
◦ acrToken.tokenName - > >
◦ acrToken.tokenPassword – Zuvor generiertes ACR-Token-Passwort
◦ acrToken.secretName – Name des geheimen Kubernetes-Objekts
Image-Konfiguration
◦ image.domain - > > .
◦ image.repository – Muss mit dem Repository-Namen aus Schritt 5 für Ihre ACR übereinstimmen.
◦ image.tag - Muss mit dem Image-Tag aus Schritt 5 für Ihre ACR übereinstimmen.
Workloadidentität
◦ workloadIdentity.clientId -
▪ Aus > >
oder
▪ Aus Terraform-Ausgabe der Infrastrukturbereitstellung: managed_identity_client_id.
◦ workloadIdentity.tenantId – Ihre Azure-Mandanten-ID
Azure
◦ azure.openai.baseUrl
▪ > > .
oder
▪ Aus Terraform-Ausgabe der Infrastrukturbereitstellung: openai_endpoint.
◦ azure.auth.tenantId – Ihre Azure-Mandanten-ID
◦ azure.auth.audience - Terraform-Ausgabezielgruppe
Schritt 7: cb-ai-service mit Helm bereitstellen
AKS-Anmeldeinformationen abrufen
Verbinden Sie Ihren lokalen Computer mit dem AKS-Cluster.
az aks get-credentials \
--resource-group <AKS_RESOURCE_GROUP> \
--name <AKS_NAME>
Überprüfen Sie die Konnektivität.
kubectl get namespace
Helm‑Installationsbefehl ausführen
helm upgrade --install cb-ai-service \
oci://<ACR_NAME>.azurecr.io/<PATH_TO_HELM_REPO> \
--version <VERSION> -n <NAMESPACE> -f values-azure-customer-hosted.yaml
Bereitstellung verifizieren
Prüfen Sie den Pod-Status.
kubectl get pods -n cb-ai-service
Alle Pods sollten ausgeführt werden.
Anwendungsprotokolle prüfen
kubectl logs <pod_name> -n cb-ai-service
JWT für die Funktionsverifizierung generieren
Führen Sie die folgenden Schritte aus, um ein JWT-Token zu generieren und den bereitgestellten cb-ai-service zu validieren.
1. Erstellen Sie ein Client-Geheimnis.
Führen Sie den folgenden Befehl aus, und speichern Sie das zurückgegebene Client-Geheimnis (password), das für die Generierung von JWT erforderlich ist, an einem sicheren Ort:
az ad app credential reset \
--id <client_id> \
--display-name "cbai-client-secret" \
--years 1
2. Führen Sie das Skript aus.
▪ Für Python: get_customer_hosted_token.py
▪ Führen Sie den folgenden Befehl aus:
python get_customer_hosted_token.py \
--client-id "<client_id>" \
--client-secret "<client_secret>" \
--tenant-id "<tenant_id>" \
--scope "api://<client_id>/.default" \
--json
|
Parameter
|
Beschreibung
|
|---|---|
|
--client-id
|
Anwendungs-ID (Client-ID) aus der Azure-App-Registrierung.
|
|
--client-secret
|
Zuvor erstelltes Client-Geheimnis.
|
|
--tenant-id
|
Azure AD-Mandanten-ID
|
|
--scope
|
API-Umfang. Dieser muss mit der in Helm konfigurierten Zielgruppe übereinstimmen.
|
|
--json
|
Geben Sie das Token im JSON-Format aus.
|
▪ Testen Sie das JWT-Token.
Überprüfen Sie die IP-Adresse des Dienstes, rufen Sie das JWT-Token aus dem obigen Befehl ab, und führen Sie den folgenden curl-Befehl aus:
curl --location 'http://<SERVICE_IP>/cb-ai-service/requirement-evaluation/v1' --header 'Accept-Language: string' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <TOKEN>' --data '{
"requirement": {
"summary": "Advanced Navigation",
"description": {
"value": "Die Batteriesoll dem Bordcomputer dem Autos eine Spannung von fast 28 VDC liefern.",
"valueType": "TEXT"
}
},
"standards": [
"INCOSE_RULES_4_0"
],
"ruleFilters": {
"INCOSE_RULES_4_0": {
"en": "R34,R18-R34,R12",
"de": "R7,R33,R27"
}
}
}'
|
|
Es wird empfohlen bei neuen Bereitstellungen zunächst mit Pay‑As‑You‑Go‑SKUs wie DataZoneStandard oder GlobalStandard zu beginnen und erst in einem nachfolgenden Terraform‑apply auf PTU umzusteigen, sobald die Bereitstellung stabil ist.
Die Bereitstellung von PTU‑Modellen dauert im Vergleich zu Pay-As-You-Go‑Bereitstellungen länger. Wenn Terraform das Cognitive‑Services‑Konto, den privaten Endpunkt, die private DNS‑Zone und die PTU‑Bereitstellung in einem einzigen "apply" erstellt, kann die Bereitstellung der PTU in Azure 5–20 Minuten oder länger dauern – selbst nachdem Terraform bereits eine erfolgreiche Bereitstellung gemeldet hat. Während dieser Zeit ist die DNS‑Auflösung des privaten Endpunkts für die PTU‑Bereitstellung noch nicht vollständig propagiert, was dazu führt, dass API‑Aufrufe vom cb‑ai‑service fehlschlagen.
Fehler in cb-ai-service pod Protokollen oder curl:
{"event": "Error code: 403 - {'error': {'code': '403', 'message': 'Traffic is not from an approved private endpoint.'}}", "dd.trace_id": "ecfb4368512eba7e0b2a0aa20caf24a3", "dd.span_id": "563883118223141984", "timestamp": "2026-04-06 04:16:45", "level": "error", "logger": "cbai.cb_ai_service.exception_handlers"}
Dies ist ein Zeitproblem. Die Private-Link-Integration der PTU-Bereitstellung wird weiterhin propagiert, während Anforderungen gesendet werden. In den meisten Fällen behebt sich der Fehler nach 45–60 Minuten von selbst, abhängig von der Azure‑Bereitstellungsdauer.
|