ACA Web Publish

Was macht ACA Web Publish?

Verwenden Sie diesen Skill, um private statische Inhalte auf Azure bereitzustellen, ohne Blob Storage öffentlich verfügbar zu machen. Das Standardmuster ist:

1. Statische Inhalte werden in privaten Azure Blob Storage hochgeladen und auf die kalte Ebene (Cold tier) gesetzt.
2. Ein kleines Docker-Image wird in Azure Container Apps (ACA) ausgeführt.
3. Der Container implementiert eine Authentifizierung auf Anwendungsebene und streamt Blob-Inhalte über ACA.
4. ACA verwendet eine systemseitig zugewiesene verwaltete Identität mit Storage Blob Data Reader.
5. Browserbenutzer erhalten niemals Blob-Schlüssel, SAS-URLs, direkte Blob-URLs oder Speicherkontoschlüssel.
6. ACA Easy Auth wird nicht verwendet.

Verbindliches Interaktionsmodell

Sofern der Benutzer nicht bereits alle Entscheidungen explizit getroffen hat, verwenden Sie vor der Implementierung das Tool ask_user. Sammeln Sie:

Entscheidung	Empfohlener Standardwert
Authentifizierungsanbieter	GitHub
Zugelassene Benutzer	Kein Standardwert; wenn leer, kann sich niemand anmelden
Registry-Modus	GHCR öffentliches Image, wenn das Repository ein öffentliches Paket hosten kann; ACR, wenn die Lösung privat/in sich geschlossen sein muss
Benutzerdefinierter DNS	Benutzerdefinierten DNS bevorzugen, wenn der Benutzer eine Azure DNS-Zone hat
Inhaltsverzeichnis	Nach lokalem Pfad fragen
Azure-Ressourcennamen	Sichere Standardwerte generieren, aber vor Änderungen an bestehender Infrastruktur fragen

Bevor Sie nach einer OAuth-Client-ID oder einem Client-Secret fragen, bestimmen Sie zuerst, ob der endgültige öffentliche Hostname bereits bekannt ist:

• Bei benutzerdefiniertem DNS: Fragen Sie zuerst nach dem Hostnamen und der DNS-Zone. Geben Sie dem Benutzer dann den Link zum Anbieterportal und die genauen Weiterleitungs-URLs für diesen benutzerdefinierten Hostnamen, bevor Sie Client-IDs/-Secrets sammeln.
• Beim integrierten ACA-Hostnamen: Fragen Sie noch nicht nach OAuth-Client-IDs/-Secrets, da der Hostname erst bekannt ist, wenn ACA existiert. Erstellen Sie zuerst einen Bootstrap-ACA-Endpunkt, erfassen Sie dessen https://<app>.<region>.azurecontainerapps.io-URL, geben Sie dem Benutzer dann den Link zum Anbieterportal und die genauen Weiterleitungs-URLs und sammeln Sie Client-IDs/-Secrets.

Bitten Sie den Benutzer niemals, eine OAuth-App mit Platzhalter-URLs zu erstellen. Sammeln Sie Client-IDs/-Secrets mit ask_user; geben Sie Secrets niemals in der endgültigen Antwort aus und committen Sie sie niemals.

Wichtige Standardwerte

• Authentifizierungsanbieter standardmäßig github.
• Unterstützte Authentifizierungsanbieter: github, google, entra, none.
• none ist nur für explizit öffentliche oder interne Testbereitstellungen.
• Wenn Authentifizierung aktiviert ist und keine zugelassenen Benutzer konfiguriert sind, allen den Zugriff verweigern.
• Kommagetrennte zugelassene Benutzer verwenden:
  • GitHub: Handles wie tkubica12,octocat.
  • Google: E-Mail-Adressen.
  • Entra: Objekt-IDs oder UPN/E-Mail-Adressen, je nach Implementierung.
• Optionale E-Mail-Zulassungslisten können für GitHub als Verteidigung in der Tiefe verwendet werden, aber Handles sind die primäre GitHub-Identität.
• Das Speicherkonto muss publicNetworkAccess=Enabled behalten, es sei denn, ACA hat eine VNet/Private-Endpunkt-Route zu Blob. allowBlobPublicAccess=false und allowSharedKeyAccess=false beibehalten.
• ACA sollte klein sein: Beginnen Sie mit 0,25 CPU und 0,5Gi Arbeitsspeicher.
• ACA sollte auf Null herunterskalieren mit einem 60-minütigen Abkühl-/Leerlaufverhalten, wo es von der aktiven ACA/KEDA-CLI-Oberfläche unterstützt wird; andernfalls verwenden Sie minimale Replikas 0 und dokumentieren Sie die Einschränkung.

Registry-Auswahl

GHCR-Modus

Verwenden Sie GHCR, wenn das Image nur Proxy-/Authentifizierungscode und keine Inhalte enthält. Das Image/Paket muss öffentlich sein, damit ACA ohne Anmeldeinformationen pullen kann. Erstellen Sie einen GitHub Actions-Workflow aus assets/publish-web-image.yml, um das Image zu erstellen und zu pushen.

ACR-Modus

Verwenden Sie ACR, wenn der Benutzer eine vollständig private und in sich geschlossene Azure-Lösung wünscht. Erstellen Sie eine ACR, erstellen oder pushen Sie das Image dorthin und gewähren Sie der ACA-verwalteten Identität AcrPull.

Vermeiden Sie bei ACR, ACA direkt aus dem privaten Image zu erstellen, bevor AcrPull konfiguriert ist. Erstellen Sie die App zuerst mit einem öffentlichen Bootstrap-Image und einer systemseitig zugewiesenen Identität, gewähren Sie dieser Identität AcrPull, konfigurieren Sie die Registry mit --identity system und aktualisieren Sie dann die App auf das ACR-Image.

Wenn Sie mit az acr build von Windows-Terminals aus erstellen, verwenden Sie --no-logs, um Unicode-/Konsolenkodierungsfehler beim Azure CLI-Log-Streaming zu vermeiden; fragen Sie stattdessen das Build-Ergebnis ab.

OAuth-Hostname-Zeitplan

Die OAuth-App-Registrierung muss den endgültigen, im Browser sichtbaren Host in der Startseiten-/Ursprungs- und Callback-URL verwenden.

Ablauf mit benutzerdefiniertem DNS

1. Fragen Sie nach dem benutzerdefinierten Hostnamen und der DNS-Zone.
2. Zeigen Sie den Registrierungslink des Anbieters und die genauen URLs an, z. B. https://site.example.com und https://site.example.com/oauth/github/callback.
3. Sammeln Sie die Client-ID und das Secret.
4. Stellen Sie ACA, DNS, Authentifizierungseinstellungen, Inhalte und Zertifikatsbindung bereit.

Ablauf mit integriertem ACA-Hostnamen

1. Stellen Sie zuerst einen Bootstrap-ACA-Endpunkt bereit, um den integrierten Hostnamen zu ermitteln. Verwenden Sie das Bereitstellungsskript mit -BootstrapOnly oder erstellen Sie die ACA-/Container-App-Shell manuell.
2. Zeigen Sie den Registrierungslink des Anbieters und die genauen URLs unter Verwendung des ermittelten Hostnamens an, z. B. https://<fqdn> und https://<fqdn>/oauth/github/callback.
3. Sammeln Sie die Client-ID und das Secret.
4. Schließen Sie die Bereitstellung ab, indem Sie Authentifizierungseinstellungen anwenden, Inhalte hochladen und zum Proxy-Image wechseln, wenn die App gebootstrapt wurde.

Erforderliche zu kopierende oder anzupassende Dateien

Verwenden Sie diese Assets als Ausgangspunkte für die Implementierung:

• assets/blob_proxy_app.py: FastAPI-App mit Blob-Proxy und Anbieterwechsel.
• assets/requirements.txt: Python-Laufzeitabhängigkeiten.
• assets/Dockerfile: Minimales Image für ACA.
• assets/deploy-aca-web.ps1: Meinungsstarkes Azure-Bereitstellungsskript.
• assets/publish-web-image.yml: GitHub Actions-Workflow für GHCR-Veröffentlichung.

Lesen Sie diese Referenzen bei Bedarf:

• references/architecture.md: Architektur, Speicherregeln und Skalierungshinweise.
• references/auth.md: OAuth-Registrierungsschritte und Umgebungsvariablen.
• references/day-2.md: Hinzufügen von Benutzern, Rotieren von Secrets, Hochladen von Inhalten und Fehlerbehebung.

Implementierungs-Checkliste

1. Bestätigen Sie das Inhaltsverzeichnis und den generierten Site-Einstiegspunkt.
2. Wählen Sie benutzerdefinierten DNS oder integrierten ACA-Hostnamen.
3. Wählen Sie den Authentifizierungsanbieter.
4. Wenn der Hostname bekannt ist, geben Sie dem Benutzer anbieterspezifische App-Registrierungslinks und genaue Callback-URLs; wenn der integrierte ACA-Hostname verwendet wird, bootstrapen Sie zuerst ACA und stellen Sie dann diese URLs bereit.
5. Sammeln Sie die App-Registrierungswerte.
6. Sammeln Sie die zugelassenen Benutzer.
7. Wählen Sie GHCR oder ACR.
8. Kopieren/passen Sie die Beispiel-App und die Dockerfile in das Ziel-Repository an.
9. Fügen Sie im GHCR-Modus den Workflow hinzu und machen Sie das resultierende Paket öffentlich.
10. Stellen Sie ACA, privaten Blob Storage, RBAC, Secrets, Umgebungsvariablen und optionalen DNS bereit.
11. Laden Sie Inhalte in Blob hoch und setzen Sie die kalte Ebene (Cold tier).
12. Smoke-Test:
    • nicht authentifizierte Anfrage leitet zum Anbieter weiter, es sei denn, AUTH_PROVIDER=none;
    • zugelassener Benutzer kann index.html laden;
    • nicht zugelassener Benutzer erhält 403;
    • Medienbereichsanfragen geben 206 Partial Content zurück;
    • direkter anonymer Blob-Zugriff schlägt fehl.

Day-2-Aufgabenbehandlung

Für „Benutzer hinzufügen“: Aktualisieren Sie nur ALLOWED_USERS oder anbieterspezifische Zulassungslisten-Umgebungsvariablen und starten/überarbeiten Sie ACA.

Für „Neue Inhalte hochladen“: Generieren Sie die lokale statische Ausgabe neu, führen Sie die Blob-Synchronisierung mit aktiviertem Löschen nur durch, wenn die lokale Ausgabe maßgeblich ist, und setzen Sie dann die kalte Ebene.

Bevorzugen Sie AzCopy für große Websites oder viele Dateien. Wenn AzCopy nicht verfügbar ist und die Website klein ist, ist Azure CLI az storage blob upload-batch --auth-mode login ein akzeptabler Fallback; installieren Sie für große Websites zuerst AzCopy oder verwenden Sie das Bereitstellungsskript mit -InstallAzCopy.

Für „Authentifizierungsanbieter wechseln“: Erstellen Sie zuerst die neue Anbieterregistrierung, setzen Sie Secrets/Umgebungsvariablen, überprüfen Sie die Anmeldung und entfernen Sie dann die alten Anbietersecrets.

Für „Wechsel von GHCR zu ACR“: Stellen Sie ACR bereit, gewähren Sie AcrPull, aktualisieren Sie die Image-Referenz und lassen Sie den Blob-Inhalt unverändert.