ACA 웹 게시은(는) 무엇을 하나요?
이 스킬을 사용하여 Blob Storage를 공개적으로 노출하지 않고 Azure에 프라이빗 정적 콘텐츠를 배포합니다. 기본 패턴은 다음과 같습니다.
- 정적 콘텐츠가 프라이빗 Azure Blob Storage에 업로드되고 Cold 계층으로 설정됩니다.
- 작은 Docker 이미지가 Azure Container Apps(ACA)에서 실행됩니다.
- 컨테이너는 앱 수준 인증을 구현하고 Blob 콘텐츠를 ACA를 통해 스트리밍합니다.
- ACA는 시스템 할당 관리 ID와
Storage Blob Data Reader역할을 사용합니다. - 브라우저 사용자는 Blob 키, SAS URL, 직접 Blob URL 또는 스토리지 계정 키를 받지 않습니다.
- ACA Easy Auth는 사용되지 않습니다.
필수 상호작용 모델
사용자가 모든 선택 사항을 명시적으로 제공하지 않은 경우, 구현 전에 ask_user 도구를 사용하십시오. 다음 정보를 수집합니다.
| 결정 사항 | 권장 기본값 |
|---|---|
| 인증 제공자 | GitHub |
| 허용된 사용자 | 기본값 없음; 비어 있으면 아무도 로그인할 수 없음 |
| 레지스트리 모드 | 리포지토리가 공개 패키지를 호스팅할 수 있으면 GHCR 공개 이미지; 솔루션이 프라이빗/자체 포함이어야 하면 ACR |
| 커스텀 DNS | 사용자에게 Azure DNS 영역이 있으면 커스텀 DNS 선호 |
| 콘텐츠 디렉토리 | 로컬 경로 요청 |
| Azure 리소스 이름 | 안전한 기본값 생성, 단 기존 인프라를 변경하기 전에 질문 |
OAuth 클라이언트 ID나 시크릿을 요청하기 전에, 먼저 최종 공개 호스트네임이 이미 알려져 있는지 확인하십시오.
- 커스텀 DNS 사용 시: 먼저 호스트네임과 DNS 영역을 요청하십시오. 그런 다음 클라이언트 ID/시크릿을 수집하기 전에 사용자에게 해당 커스텀 호스트네임에 대한 제공자 포털 링크와 정확한 리디렉션 URL을 제공하십시오.
- ACA 내장 호스트네임 사용 시: 호스트네임은 ACA가 존재할 때까지 알 수 없으므로 아직 OAuth 클라이언트 ID/시크릿을 요청하지 마십시오. 먼저 부트스트랩 ACA 엔드포인트를 생성하고,
https://<app>.<region>.azurecontainerapps.ioURL을 캡처한 다음, 사용자에게 제공자 포털 링크와 정확한 리디렉션 URL을 제공하고 클라이언트 ID/시크릿을 수집하십시오.
플레이스홀더 URL로 OAuth 앱을 생성하도록 사용자에게 요청하지 마십시오. 클라이언트 ID/시크릿은 ask_user로 수집하고, 최종 응답에 시크릿을 절대 출력하지 말고 절대 커밋하지 마십시오.
주요 기본값
- 인증 제공자 기본값은
github입니다. - 지원되는 인증 제공자:
github,google,entra,none none은 명시적으로 공개 또는 내부 테스트 배포용으로만 사용합니다.- 인증이 활성화되고 허용된 사용자가 구성되지 않은 경우 모든 사용자를 거부합니다.
- 쉼표로 구분된 허용된 사용자:
- GitHub:
tkubica12,octocat과 같은 핸들 - Google: 이메일 주소
- Entra: 구현에 따라 개체 ID 또는 UPN/이메일 주소
- GitHub:
- GitHub의 경우 심층 방어를 위해 선택적 이메일 허용 목록을 사용할 수 있지만, 핸들이 기본 GitHub 식별자입니다.
- ACA에 Blob에 대한 VNet/프라이빗 엔드포인트 경로가 없는 한 스토리지 계정은
publicNetworkAccess=Enabled로 유지해야 합니다.allowBlobPublicAccess=false및allowSharedKeyAccess=false로 유지합니다. - ACA는 작아야 함:
0.25CPU 및0.5Gi메모리부터 시작합니다. - 활성 ACA/KEDA CLI 표면에서 지원되는 경우 ACA는 60분 쿨다운/유휴 동작으로 0으로 스케일링되어야 합니다. 그렇지 않으면 최소 복제본
0을 사용하고 제한 사항을 문서화합니다.
레지스트리 선택
GHCR 모드
이미지에 프록시/인증 코드만 포함되고 콘텐츠는 포함되지 않은 경우 GHCR을 사용합니다. ACA가 자격 증명 없이 이미지를 가져올 수 있으려면 이미지/패키지가 공개되어야 합니다. assets/publish-web-image.yml에서 GitHub Actions 워크플로를 생성하여 이미지를 빌드하고 푸시합니다.
ACR 모드
사용자가 완전히 프라이빗하고 자체 포함된 Azure 솔루션을 원하는 경우 ACR을 사용합니다. ACR을 생성하고, 이미지를 빌드하거나 푸시하고, ACA 관리 ID에 AcrPull을 부여합니다.
ACR의 경우 AcrPull이 구성되기 전에 프라이빗 이미지에서 직접 ACA를 생성하지 않도록 하십시오. 먼저 공개 부트스트랩 이미지와 시스템 할당 ID로 앱을 생성하고, 해당 ID에 AcrPull을 부여하고, --identity system으로 레지스트리를 구성한 다음, 앱을 ACR 이미지로 업데이트합니다.
Windows 터미널에서 az acr build로 빌드할 때는 Azure CLI 로그 스트리밍 유니코드/콘솔 인코딩 실패를 방지하기 위해 --no-logs를 사용하고, 대신 빌드 결과를 쿼리합니다.
OAuth 호스트네임 타이밍
OAuth 앱 등록은 홈페이지/원본 및 콜백 URL에 최종 브라우저 표시 호스트를 사용해야 합니다.
커스텀 DNS 흐름
- 커스텀 호스트네임과 DNS 영역을 요청합니다.
- 제공자 등록 링크와 정확한 URL(예:
https://site.example.com및https://site.example.com/oauth/github/callback)을 표시합니다. - 클라이언트 ID와 시크릿을 수집합니다.
- ACA, DNS, 인증 설정, 콘텐츠 및 인증서 바인딩을 배포합니다.
ACA 내장 호스트네임 흐름
- 먼저 부트스트랩 ACA 엔드포인트를 배포하여 내장 호스트네임을 검색합니다.
-BootstrapOnly와 함께 배포 스크립트를 사용하거나 ACA/컨테이너 앱 셸을 수동으로 생성합니다. - 검색된 호스트네임을 사용하여 제공자 등록 링크와 정확한 URL(예:
https://<fqdn>및https://<fqdn>/oauth/github/callback)을 표시합니다. - 클라이언트 ID와 시크릿을 수집합니다.
- 인증 설정 적용, 콘텐츠 업로드, 그리고 앱이 부트스트랩된 경우 프록시 이미지로 전환하여 배포를 완료합니다.
복사 또는 조정해야 하는 필수 파일
다음 에셋을 구현 시작점으로 사용하십시오.
assets/blob_proxy_app.py: Blob 프록시 및 제공자 전환이 있는 FastAPI 앱.assets/requirements.txt: Python 런타임 종속성.assets/Dockerfile: ACA용 최소 이미지.assets/deploy-aca-web.ps1: 의견이 반영된 Azure 배포 스크립트.assets/publish-web-image.yml: GHCR 게시용 GitHub Actions 워크플로.
필요할 때 다음 참조를 읽으십시오.
references/architecture.md: 아키텍처, 스토리지 규칙 및 스케일링 참고 사항.references/auth.md: OAuth 등록 단계 및 환경 변수.references/day-2.md: 사용자 추가, 시크릿 순환, 콘텐츠 업로드 및 문제 해결.
구현 체크리스트
- 콘텐츠 디렉토리 및 생성된 사이트 진입점을 확인합니다.
- 커스텀 DNS 또는 ACA 내장 호스트네임을 선택합니다.
- 인증 제공자를 선택합니다.
- 호스트네임이 알려진 경우 사용자에게 제공자별 앱 등록 링크와 정확한 콜백 URL을 제공하고, ACA 내장 호스트네임을 사용하는 경우 먼저 ACA를 부트스트랩한 다음 해당 URL을 제공합니다.
- 앱 등록 값을 수집합니다.
- 허용된 사용자를 수집합니다.
- GHCR 또는 ACR을 선택합니다.
- 샘플 앱 및 Dockerfile을 대상 리포지토리로 복사/조정합니다.
- GHCR 모드인 경우 워크플로를 추가하고 결과 패키지를 공개로 만듭니다.
- ACA, 프라이빗 Blob Storage, RBAC, 시크릿, 환경 변수 및 선택적 DNS를 배포합니다.
- 콘텐츠를 Blob에 업로드하고 Cold 계층으로 설정합니다.
- 스모크 테스트:
- 인증되지 않은 요청은 제공자로 리디렉션됩니다(
AUTH_PROVIDER=none인 경우 제외). - 허용된 사용자는
index.html을 로드할 수 있습니다. - 허용되지 않은 사용자는
403을 받습니다. - 미디어 범위 요청은
206 Partial Content를 반환합니다. - Blob 직접 익명 액세스는 실패합니다.
- 인증되지 않은 요청은 제공자로 리디렉션됩니다(
Day-2 작업 처리
"사용자 추가"의 경우 ALLOWED_USERS 또는 제공자별 허용 목록 환경 변수만 업데이트하고 ACA를 다시 시작/수정합니다.
"새 콘텐츠 업로드"의 경우 로컬 정적 출력을 다시 생성하고, 로컬 출력이 권위 있는 경우에만 삭제가 활성화된 Blob 동기화를 실행한 다음 Cold 계층으로 설정합니다.
대규모 사이트 또는 많은 파일의 경우 AzCopy를 선호합니다. AzCopy를 사용할 수 없고 사이트가 작은 경우 Azure CLI az storage blob upload-batch --auth-mode login이 허용 가능한 대체 방법입니다. 대규모 사이트의 경우 먼저 AzCopy를 설치하거나 -InstallAzCopy와 함께 배포 스크립트를 사용하십시오.
"인증 제공자 전환"의 경우 먼저 새 제공자 등록을 생성하고, 시크릿/환경 변수를 설정하고, 로그인을 확인한 다음, 더 이상 사용되지 않는 제공자 시크릿을 제거합니다.
"GHCR에서 ACR로 이동"의 경우 ACR을 배포하고, AcrPull을 부여하고, 이미지 참조를 업데이트하고, Blob 콘텐츠는 변경하지 않고 유지합니다.