aca-web-publish

ACA Web Publish

Use esta skill para implantar conteúdo estático privado no Azure sem expor o Blob Storage publicamente. O padrão é:

1. O conteúdo estático é enviado para o Azure Blob Storage privado e definido como Cold tier.
2. Uma imagem Docker pequena é executada no Azure Container Apps (ACA).
3. O contêiner implementa autenticação em nível de aplicativo e transmite o conteúdo do Blob através do ACA.
4. O ACA usa uma identidade gerenciada atribuída ao sistema com Storage Blob Data Reader.
5. Os usuários do navegador nunca recebem chaves de blob, URLs SAS ou chaves da conta de armazenamento.
6. O Easy Auth do ACA não é usado.

Modelo de interação obrigatório

A menos que o usuário já tenha fornecido todas as escolhas explicitamente, use a ferramenta ask_user antes de implementar. Reúna:

Decisão	Padrão recomendado
Provedor de autenticação	GitHub
Usuários permitidos	Sem padrão; se vazio, ninguém pode entrar
Modo de registro	Imagem pública GHCR se o repositório puder hospedar um pacote público; ACR se a solução precisar ser privada/autossuficiente
DNS personalizado	Prefira DNS personalizado se o usuário tiver uma zona DNS do Azure
Diretório de conteúdo	Pergunte pelo caminho local
Nomes de recursos do Azure	Gere padrões seguros, mas pergunte antes de alterar infraestrutura existente

Antes de perguntar sobre qualquer ID ou segredo de cliente OAuth, primeiro determine se o hostname público final já é conhecido:

• Com DNS personalizado, pergunte primeiro pelo hostname e zona DNS. Em seguida, forneça ao usuário o link do portal do provedor e as URLs de redirecionamento exatas para aquele hostname personalizado antes de coletar IDs/segredos de cliente.
• Com o hostname interno do ACA, ainda não pergunte por IDs/segredos de cliente OAuth porque o hostname não é conhecido até o ACA existir. Primeiro crie um endpoint ACA de bootstrap, capture sua URL https://<app>.<region>.azurecontainerapps.io, então forneça ao usuário o link do portal do provedor e as URLs de redirecionamento exatas e colete IDs/segredos de cliente.

Nunca peça ao usuário para criar um aplicativo OAuth a partir de URLs de placeholder. Colete IDs/segredos de cliente com ask_user; nunca ecoe segredos na resposta final e nunca os cometa.

Padrões principais

• O provedor de autenticação padrão é github.
• Provedores de autenticação suportados: github, google, entra, none.
• none é apenas para implantações explicitamente públicas ou de teste interno.
• Se a autenticação estiver habilitada e nenhum usuário permitido estiver configurado, negue todos.
• Use uma lista separada por vírgulas de usuários permitidos:
  • GitHub: handles como tkubica12,octocat.
  • Google: endereços de e-mail.
  • Entra: IDs de objeto ou UPN/endereços de e-mail, dependendo da implementação.
• Listas de permissão de e-mail opcionais podem ser usadas para GitHub como defesa em profundidade, mas os handles são a identidade primária do GitHub.
• A conta de armazenamento deve manter publicNetworkAccess=Enabled a menos que o ACA tenha uma rota VNet/private endpoint para o Blob. Mantenha allowBlobPublicAccess=false e allowSharedKeyAccess=false.
• O ACA deve ser pequeno: comece com 0,25 CPU e 0,5Gi de memória.
• O ACA deve escalar para zero com um comportamento de resfriamento/inatividade de 60 minutos onde suportado pela superfície CLI ativa do ACA/KEDA; caso contrário, use réplicas mínimas 0 e documente a limitação.

Escolhas de registro

Modo GHCR

Use GHCR quando a imagem contiver apenas código de proxy/autenticação e nenhum conteúdo. A imagem/package deve ser pública para que o ACA possa puxar sem credenciais. Crie um workflow do GitHub Actions a partir de assets/publish-web-image.yml para construir e enviar a imagem.

Modo ACR

Use ACR quando o usuário quiser uma solução Azure totalmente privada e autossuficiente. Crie um ACR, construa ou envie a imagem para ele e conceda a identidade gerenciada do ACA AcrPull.

Para ACR, evite criar o ACA diretamente da imagem privada antes que AcrPull esteja configurado. Crie o aplicativo primeiro com uma imagem de bootstrap pública e identidade atribuída ao sistema, conceda a essa identidade AcrPull, configure o registro com --identity system e então atualize o aplicativo para a imagem ACR.

Ao construir com az acr build a partir de terminais Windows, use --no-logs para evitar falhas de codificação de console/streaming de log da CLI do Azure; consulte o resultado da construção.

Temporização do hostname OAuth

O registro do aplicativo OAuth deve usar o host final visível no navegador na homepage/origin e URL de callback.

Fluxo de DNS personalizado

1. Pergunte pelo hostname personalizado e zona DNS.
2. Mostre o link de registro do provedor e as URLs exatas, por exemplo https://site.example.com e https://site.example.com/oauth/github/callback.
3. Colete o ID do cliente e o segredo.
4. Implante ACA, DNS, configurações de autenticação, conteúdo e vinculação de certificado.

Fluxo de hostname interno do ACA

1. Implante um endpoint ACA de bootstrap primeiro para descobrir o hostname interno. Use o script de implantação com -BootstrapOnly ou crie o shell do ACA/aplicativo de contêiner manualmente.
2. Mostre o link de registro do provedor e as URLs exatas usando o hostname descoberto, por exemplo https://<fqdn> e https://<fqdn>/oauth/github/callback.
3. Colete o ID do cliente e o segredo.
4. Complete a implantação aplicando configurações de autenticação, enviando conteúdo e alternando para a imagem de proxy se o aplicativo foi inicializado.

Arquivos necessários para copiar ou adaptar

Use estes ativos como pontos de partida para implementação:

• assets/blob_proxy_app.py: Aplicativo FastAPI com proxy de Blob e alternância de provedor.
• assets/requirements.txt: Dependências de runtime Python.
• assets/Dockerfile: Imagem mínima para ACA.
• assets/deploy-aca-web.ps1: Script de implantação Azure opinativo.
• assets/publish-web-image.yml: Workflow do GitHub Actions para publicação GHCR.

Leia estas referências quando necessário:

• references/architecture.md: Arquitetura, regras de armazenamento e notas de escalonamento.
• references/auth.md: Etapas de registro OAuth e variáveis de ambiente.
• references/day-2.md: Adicionar usuários, girar segredos, enviar conteúdo e solucionar problemas.

Lista de verificação de implementação

1. Confirme o diretório de conteúdo e o ponto de entrada do site gerado.
2. Escolha DNS personalizado ou hostname interno do ACA.
3. Escolha o provedor de autenticação.
4. Se o hostname for conhecido, forneça ao usuário links de registro de aplicativo específicos do provedor e URLs de callback exatas; se estiver usando o hostname interno do ACA, inicialize o ACA primeiro e depois forneça essas URLs.
5. Colete os valores de registro do aplicativo.
6. Colete os usuários permitidos.
7. Escolha GHCR ou ACR.
8. Copie/adapte o aplicativo de exemplo e o Dockerfile para o repositório de destino.
9. Se modo GHCR, adicione o workflow e torne o pacote resultante público.
10. Implante ACA, Blob Storage privado, RBAC, segredos, variáveis de ambiente e DNS opcional.
11. Envie conteúdo para o Blob e defina Cold tier.
12. Teste de fumaça:
    • solicitação não autenticada redireciona para o provedor, a menos que AUTH_PROVIDER=none;
    • usuário permitido pode carregar index.html;
    • usuário não permitido recebe 403;
    • solicitações de intervalo de mídia retornam 206 Partial Content;
    • acesso anônimo direto ao Blob falha.

Tratamento de tarefas do dia 2

Para "adicionar usuário", atualize apenas ALLOWED_USERS ou variáveis de ambiente de lista de permissão específicas do provedor e reinicie/revise o ACA.

Para "enviar novo conteúdo", regenere a saída estática local, execute a sincronização do Blob com exclusão habilitada apenas se a saída local for autoritativa, então defina Cold tier.

Prefira AzCopy para sites grandes ou muitos arquivos. Se o AzCopy não estiver disponível e o site for pequeno, az storage blob upload-batch --auth-mode login da CLI do Azure é uma alternativa aceitável; para sites grandes, instale o AzCopy primeiro ou use o script de implantação com -InstallAzCopy.

Para "alternar provedor de autenticação", crie o registro do novo provedor primeiro, defina segredos/variáveis de ambiente, verifique o login, então remova os segredos do provedor obsoleto.

Para "mover de GHCR para ACR", implante ACR, conceda AcrPull, atualize a referência da imagem e mantenha o conteúdo do Blob inalterado.