ACA Web Publish

Que fait ACA Web Publish ?

Utilisez cette compétence pour déployer du contenu statique privé sur Azure sans exposer le stockage Blob au public. Le modèle par défaut est :

1. Le contenu statique est téléchargé dans un stockage Blob Azure privé et défini sur le niveau Cold.
2. Une petite image Docker s'exécute dans Azure Container Apps (ACA).
3. Le conteneur implémente une authentification au niveau de l'application et diffuse le contenu Blob via ACA.
4. ACA utilise une identité managée attribuée par le système avec Storage Blob Data Reader.
5. Les utilisateurs du navigateur ne reçoivent jamais de clés de blob, d'URLs SAS, d'URLs directes de blob ou de clés de compte de stockage.
6. ACA Easy Auth n'est pas utilisé.

Modèle d'interaction obligatoire

À moins que l'utilisateur n'ait déjà fourni tous les choix explicitement, utilisez l'outil ask_user avant d'implémenter. Recueillez :

Décision	Valeur par défaut recommandée
Fournisseur d'authentification	GitHub
Utilisateurs autorisés	Pas de défaut ; si vide, personne ne peut se connecter
Mode de registre	Image publique GHCR si le dépôt peut héberger un package public ; ACR si la solution doit être privée/autonome
DNS personnalisé	Préférer un DNS personnalisé si l'utilisateur dispose d'une zone DNS Azure
Répertoire de contenu	Demander le chemin local
Noms des ressources Azure	Générer des valeurs par défaut sûres, mais demander avant de modifier une infrastructure existante

Avant de demander un ID client OAuth ou un secret, déterminez d'abord si le nom d'hôte public final est déjà connu :

• Avec DNS personnalisé, demandez d'abord le nom d'hôte et la zone DNS. Ensuite, donnez à l'utilisateur le lien vers le portail du fournisseur et les URLs de redirection exactes pour ce nom d'hôte personnalisé avant de collecter les IDs/secrets clients.
• Avec le nom d'hôte intégré ACA, ne demandez pas encore les IDs/secrets clients OAuth car le nom d'hôte n'est pas connu tant qu'ACA n'existe pas. Créez d'abord un endpoint ACA d'amorçage, capturez son URL https://<app>.<region>.azurecontainerapps.io, puis donnez à l'utilisateur le lien vers le portail du fournisseur et les URLs de redirection exactes, et collectez les IDs/secrets clients.

Ne demandez jamais à l'utilisateur de créer une application OAuth à partir d'URLs factices. Collectez les IDs/secrets clients avec ask_user ; ne répétez jamais les secrets dans la réponse finale et ne les validez jamais.

Valeurs par défaut clés

• Le fournisseur d'authentification par défaut est github.
• Fournisseurs d'authentification pris en charge : github, google, entra, none.
• none est uniquement pour les déploiements explicitement publics ou de test interne.
• Si l'authentification est activée et qu'aucun utilisateur autorisé n'est configuré, refusez tout le monde.
• Utilisateurs autorisés séparés par des virgules :
  • GitHub : handles comme tkubica12,octocat.
  • Google : adresses e-mail.
  • Entra : IDs d'objet ou UPN/adresses e-mail, selon l'implémentation.
• Des listes d'autorisation d'e-mail facultatives peuvent être utilisées pour GitHub comme défense en profondeur, mais les handles sont l'identité principale GitHub.
• Le compte de stockage doit conserver publicNetworkAccess=Enabled sauf si ACA dispose d'une route VNet/point de terminaison privé vers Blob. Gardez allowBlobPublicAccess=false et allowSharedKeyAccess=false.
• ACA doit être petit : commencez avec 0.25 CPU et 0.5Gi mémoire.
• ACA doit passer à zéro avec un comportement de temporisation/d'inactivité de 60 minutes là où la surface CLI ACA/KEDA active le prend en charge ; sinon, utilisez un nombre minimal de réplicas 0 et documentez la limitation.

Choix de registre

Mode GHCR

Utilisez GHCR lorsque l'image ne contient que du code proxy/auth et aucun contenu. L'image/package doit être publique pour qu'ACA puisse la récupérer sans informations d'identification. Créez un workflow GitHub Actions à partir de assets/publish-web-image.yml pour construire et pousser l'image.

Mode ACR

Utilisez ACR lorsque l'utilisateur souhaite une solution Azure entièrement privée et autonome. Créez un ACR, construisez ou poussez l'image là-bas, et accordez à l'identité managée d'ACA le rôle AcrPull.

Pour ACR, évitez de créer ACA directement à partir de l'image privée avant que AcrPull ne soit configuré. Créez d'abord l'application avec une image d'amorçage publique et une identité attribuée par le système, accordez à cette identité AcrPull, configurez le registre avec --identity system, puis mettez à jour l'application vers l'image ACR.

Lors de la construction avec az acr build à partir de terminaux Windows, utilisez --no-logs pour éviter les échecs de codage Unicode/console de streaming de logs Azure CLI ; interrogez plutôt le résultat de la construction.

Synchronisation du nom d'hôte OAuth

L'enregistrement de l'application OAuth doit utiliser le nom d'hôte final visible dans le navigateur pour l'URL de la page d'accueil/d'origine et l'URL de rappel.

Flux DNS personnalisé

1. Demandez le nom d'hôte personnalisé et la zone DNS.
2. Affichez le lien d'inscription au fournisseur et les URLs exactes, par exemple https://site.example.com et https://site.example.com/oauth/github/callback.
3. Collectez l'ID client et le secret.
4. Déployez ACA, DNS, les paramètres d'authentification, le contenu et la liaison de certificat.

Flux avec nom d'hôte intégré ACA

1. Déployez d'abord un endpoint ACA d'amorçage pour découvrir le nom d'hôte intégré. Utilisez le script de déploiement avec -BootstrapOnly ou créez manuellement la coque ACA/Container App.
2. Affichez le lien d'inscription au fournisseur et les URLs exactes en utilisant le nom d'hôte découvert, par exemple https://<fqdn> et https://<fqdn>/oauth/github/callback.
3. Collectez l'ID client et le secret.
4. Terminez le déploiement en appliquant les paramètres d'authentification, en téléchargeant le contenu et en basculant vers l'image proxy si l'application a été amorcée.

Fichiers requis à copier ou adapter

Utilisez ces ressources comme points de départ de l'implémentation :

• assets/blob_proxy_app.py : Application FastAPI avec proxy Blob et commutateur de fournisseur.
• assets/requirements.txt : Dépendances d'exécution Python.
• assets/Dockerfile : Image minimale pour ACA.
• assets/deploy-aca-web.ps1 : Script de déploiement Azure opinionné.
• assets/publish-web-image.yml : Workflow GitHub Actions pour la publication GHCR.

Consultez ces références lorsque nécessaire :

• references/architecture.md : Architecture, règles de stockage et notes de mise à l'échelle.
• references/auth.md : Étapes d'enregistrement OAuth et variables d'environnement.
• references/day-2.md : Ajout d'utilisateurs, rotation des secrets, téléchargement de contenu et dépannage.

Liste de contrôle de l'implémentation

1. Confirmez le répertoire de contenu et le point d'entrée du site généré.
2. Choisissez un DNS personnalisé ou un nom d'hôte intégré ACA.
3. Choisissez le fournisseur d'authentification.
4. Si le nom d'hôte est connu, donnez à l'utilisateur les liens d'inscription à l'application spécifique au fournisseur et les URLs de rappel exactes ; si vous utilisez le nom d'hôte intégré ACA, amorcez d'abord ACA, puis fournissez ces URLs.
5. Collectez les valeurs d'enregistrement de l'application.
6. Collectez les utilisateurs autorisés.
7. Choisissez GHCR ou ACR.
8. Copiez/adaptez l'application exemple et le Dockerfile dans le dépôt cible.
9. En mode GHCR, ajoutez le workflow et rendez le package résultant public.
10. Déployez ACA, le stockage Blob privé, le RBAC, les secrets, les variables d'environnement et le DNS optionnel.
11. Téléchargez le contenu sur Blob et définissez le niveau Cold.
12. Test de vérification :
    • une requête non authentifiée redirige vers le fournisseur, sauf si AUTH_PROVIDER=none ;
    • un utilisateur autorisé peut charger index.html ;
    • un utilisateur non autorisé obtient une 403 ;
    • les requêtes de plage média renvoient 206 Partial Content ;
    • l'accès anonyme direct au Blob échoue.

Gestion des tâches de deuxième jour

Pour "ajouter un utilisateur", mettez à jour uniquement ALLOWED_USERS ou les variables d'environnement de liste d'autorisation spécifiques au fournisseur et redémarrez/révisez ACA.

Pour "télécharger du nouveau contenu", régénérez la sortie statique locale, exécutez la synchronisation Blob avec suppression activée uniquement si la sortie locale est faisant autorité, puis définissez le niveau Cold.

Préférez AzCopy pour les grands sites ou de nombreux fichiers. Si AzCopy n'est pas disponible et que le site est petit, az storage blob upload-batch --auth-mode login est un recours acceptable ; pour les grands sites, installez d'abord AzCopy ou utilisez le script de déploiement avec -InstallAzCopy.

Pour "changer de fournisseur d'authentification", créez d'abord le nouveau fournisseur d'enregistrement, définissez les secrets/variables d'environnement, vérifiez la connexion, puis supprimez les secrets de l'ancien fournisseur.

Pour "passer de GHCR à ACR", déployez ACR, accordez AcrPull, mettez à jour la référence de l'image et conservez le contenu Blob inchangé.