Azure에서 워크로드를 호스트하는 방법

이 문서에서는 프런트 엔드 전용 아키텍처를 사용하여 Azure에서 패브릭 확장성 도구 키트 워크로드를 호스트하는 방법을 설명합니다. 확장성 도구 키트는 정적 웹 애플리케이션에 최적화된 Azure 서비스와 함께 클라우드 네이티브 배포 방법을 사용합니다.

아키텍처 개요

패브릭 확장성 도구 키트는 Azure 서비스를 사용한 프런트 엔드 배포에 초점을 맞춘 아키텍처를 사용합니다.

확장성 도구 키트 아키텍처

확장성 도구 키트 아키텍처에는 다음과 같은 특성이 포함됩니다.

• 프런트 엔드 전용 배포: 워크로드가 별도의 백 엔드 없이 브라우저에서 완전히 실행됩니다.
• 정적 웹 사이트 호스팅: 호스팅에 Azure Storage 정적 웹 사이트 사용
• Azure Front Door: 글로벌 CDN, SSL 종료 및 라우팅 제공
• 관리되는 서비스: 보안을 위해 Entra ID, Key Vault 및 관리 ID를 활용합니다.
• 단일 배포 프로세스: 제공된 PowerShell 스크립트를 배포에 사용합니다.

사용되는 Azure 서비스

Azure Front Door

Azure Front Door 는 워크로드의 전역 진입점 역할을 합니다. 이 콘솔은 다음과 같은 기능을 제공합니다.

• 전역 부하 분산: 사용자를 가장 가까운 에지 위치로 라우팅
• SSL 종료: HTTPS 인증서를 자동으로 처리합니다.
• WAF(웹 애플리케이션 방화벽): 일반적인 웹 취약성으로부터 보호
• 캐싱: 에지 위치에서 정적 자산을 캐싱하여 성능 향상

확장성 도구 키트의 경우 Front Door는 트래픽을 Azure Storage에서 호스트되는 정적 웹 사이트로 라우팅하여 전 세계적으로 고가용성과 짧은 대기 시간을 보장합니다.

Azure Storage 계정(정적 웹 사이트)

정적 웹 사이트를 호스팅하는 Azure Storage 계정은 빌드된 워크로드 애플리케이션을 호스트합니다. 다음과 같은 기능이 제공됩니다.

• 비용 효율적인 호스팅: 사용된 스토리지 및 대역폭에 대해서만 지불
• 자동 크기 조정: 구성 없이 트래픽 급증 처리
• 글로벌 가용성: 콘텐츠는 Azure의 글로벌 스토리지 인프라에서 제공됩니다.
• 파일 기반 배포: 버전을 배포할 파일 업로드

확장성 도구 키트는 React 애플리케이션을 스토리지 계정에 직접 배포되는 정적 HTML, JavaScript, CSS 및 자산으로 빌드합니다.

Azure Key Vault (애저 키 볼트)

Azure Key Vault 는 중요한 구성 및 비밀을 관리합니다.

• 클라이언트 비밀: Entra ID 애플리케이션 비밀을 안전하게 저장
• API 키: 외부 서비스 API 키 관리
• 구성: 환경별 설정 저장
• 인증서: 필요한 경우 SSL 인증서 관리

워크로드는 보안 자격 증명이 없는 인증을 위해 관리 ID를 통해 Key Vault에 액세스합니다.

Azure Entra ID(Azure Active Directory)

Azure Entra ID 는 인증 및 권한 부여를 제공합니다.

• 앱 등록: 워크로드를 Entra 애플리케이션으로 등록합니다.
• OAuth 2.0 흐름: Fabric을 사용하여 사용자 인증을 수행합니다.
• API 권한: 패브릭 및 Microsoft Graph API에 대한 액세스 관리
• 토큰 관리: API 호출에 대한 보안 액세스 토큰 제공

관리되는 식별

관리 ID는 보안 서비스 대 서비스 인증을 제공합니다.

• 자격 증명 관리 없음: 코드에 비밀을 저장할 필요가 없습니다.
• 토큰 처리: Azure에서 토큰 획득 및 갱신을 처리합니다.
• 보안 액세스: Key Vault 및 기타 Azure 서비스에 안전하게 연결
• ID 수명 주기: 정리를 위해 Azure 리소스에 연결

배포 프로세스

필수 조건

Azure에 배포하기 전에 다음이 있는지 확인합니다.

• 적절한 권한이 있는 Azure 구독
• Azure CLI 설치 및 인증
• 로컬로 복제된 패브릭 확장성 도구 키트 리포지토리
• .\scripts\Build\BuildRelease.ps1을(를) 사용하여 빌드한 업무량

배포 스크립트 사용

확장성 도구 키트에는 배포 프로세스를 자동화하는 PowerShell 배포 스크립트 scripts\Deploy\DeployToAzureWebApp.ps1 가 포함되어 있습니다.

기본 배포

# Deploy to an existing Azure Web App
.\scripts\Deploy\DeployToAzureWebApp.ps1 -WebAppName "my-fabric-workload" -ResourceGroupName "fabric-workload-rg"

추가 배포 옵션

# Deploy to staging slot with custom settings
.\scripts\Deploy\DeployToAzureWebApp.ps1 `
    -WebAppName "my-fabric-workload" `
    -ResourceGroupName "fabric-workload-rg" `
    -SlotName "staging" `
    -Force $true `
    -CreateBackup $true `
    -RestartAfterDeploy $true

배포 스크립트 매개 변수

배포 스크립트 기능

배포 스크립트는 포괄적인 배포 기능을 제공합니다.

유효성 검사 및 안전성

• 필수 구성 요소 확인: Azure CLI 설치 및 인증 유효성 검사
• 리소스 유효성 검사: 대상 웹앱이 존재하고 액세스할 수 있는지 확인합니다.
• 빌드 유효성 검사: 릴리스 디렉터리에 필요한 파일이 포함되어 있는지 확인합니다.
• 백업 만들기: 롤백 기능을 위한 배포 백업 만들기

배포 워크플로

• ZIP 패키지 만들기: 빌드된 애플리케이션을 배포 패키지로 압축
• 크기 보고: 확인을 위한 배포 패키지 크기를 표시합니다.
• 진행률 모니터링: 실시간 배포 상태 업데이트 제공
• 오류 처리: 문제 해결 지침이 포함된 자세한 오류 메시지

배포 후

• 상태 검사: 배포된 애플리케이션이 올바르게 응답했는지 확인합니다.
• URL 보고: 배포된 애플리케이션에 대한 직접 링크를 제공합니다.
• 매니페스트 지침: 패브릭에 매니페스트 업로드를 위한 다음 단계 표시
• 타이밍 메트릭: 총 배포 기간을 보고합니다.

수동 배포

Azure PowerShell 명령을 사용하여 프런트 엔드 애플리케이션을 수동으로 배포할 수도 있습니다.

애플리케이션 빌드

먼저 테스트 환경에 대한 프런트 엔드 애플리케이션을 빌드합니다.

npm run build:test

배포 패키지 만들기

1. build\Frontend 프로젝트의 폴더로 이동합니다.
2. 빌드 디렉터리 아래의 assets 모든 파일 및 폴더 선택
3. .zip 선택한 모든 파일이 포함된 파일 만들기

Azure PowerShell을 사용하여 배포

# Connect to Azure
Connect-AzAccount

# Set your subscription context
Set-AzContext -Subscription "<subscription_id>"

# Deploy the zip file to your web app
Publish-AzWebApp -ResourceGroupName <resource_group_name> -Name <web_app_name> -ArchivePath <zip_file_path>

수동 배포 매개 변수

보안 고려 사항

인증 흐름

워크로드는 표준 OAuth 2.0 흐름을 사용하여 Fabric에서 인증합니다.

1. 사용자가 패브릭을 통해 워크로드에 액세스합니다.
2. Azure 호스팅 애플리케이션으로 패브릭 리디렉션
3. 앱이 인증을 위해 Entra ID로 리디렉션됩니다.
4. Entra ID는 인증 토큰을 반환합니다.
5. 앱이 토큰을 사용하여 패브릭 API에 액세스

보안 구성

• 환경 변수: 코드가 아닌 Azure 앱 설정에 구성 저장
• Key Vault 통합: 관리 ID를 통해 비밀에 액세스
• HTTPS만 해당: 모든 통신에 HTTPS 적용
• CORS 구성: 패브릭 도메인에 적절한 CORS 정책 구성

모범 사례

• 최소 권한: 관리 ID에 필요한 최소 권한 부여
• 비밀 회전: Key Vault에 저장된 비밀을 정기적으로 회전합니다.
• 네트워크 보안: 가능한 경우 프라이빗 엔드포인트 사용
• 모니터링: 보안 모니터링을 위해 Application Insights 사용

배포 후 구성

Azure App Service 구성

배포 후 Azure App Service를 구성합니다.

# Set environment variables for your workload
az webapp config appsettings set --name "my-fabric-workload" --resource-group "fabric-workload-rg" --settings \
    "FABRIC_CLIENT_ID=your-client-id" \
    "FABRIC_TENANT_ID=your-tenant-id" \
    "KEY_VAULT_URL=https://your-keyvault.vault.azure.net/"

Key Vault 설정

중요한 구성을 Key Vault에 저장합니다.

# Store client secret
az keyvault secret set --vault-name "your-keyvault" --name "FabricClientSecret" --value "your-client-secret"

# Store API keys
az keyvault secret set --vault-name "your-keyvault" --name "ExternalApiKey" --value "your-api-key"

관리 ID 구성

Key Vault 액세스에 대한 관리 ID 구성:

# Enable system-assigned managed identity
az webapp identity assign --name "my-fabric-workload" --resource-group "fabric-workload-rg"

# Grant access to Key Vault
az keyvault set-policy --name "your-keyvault" \
    --object-id "managed-identity-principal-id" \
    --secret-permissions get list

매니페스트 배포

Azure에 애플리케이션을 배포한 후에는 매니페스트 패키지를 Fabric에 업로드해야 합니다.

매니페스트 패키지 빌드

먼저 매니페스트 패키지를 빌드합니다.

.\scripts\Build\BuildManifestPackage.ps1

다음은 워크로드 매니페스트가 포함된 release\ManifestPackage.1.0.0.nupkg를 만듭니다.

Fabric 관리 포털에 업로드

1. Microsoft Fabric 관리 포털 열기
2. 워크로드 관리>업로드 워크로드로 이동
3. ManifestPackage.1.0.0.nupkg 파일 업로드
4. 워크로드 설정 및 권한 구성
5. 테넌트의 워크로드를 활성화하십시오

Azure 배포에 대한 매니페스트 업데이트

Azure 배포를 위한 매니페스트 패키지를 빌드하기 전에 파일의 값.env(예: FRONTEND_URLFRONTEND_APPID및 기타 필수 변수)이 Azure 환경에 대해 올바르게 설정되었는지 확인합니다. 이러한 값은 빌드 프로세스 중에 사용자 WorkloadManifest.xml 로 대체됩니다.

필요한 환경 변수의 전체 목록 및 설정에 대한 지침은 일반 게시 요구 사항을 참조하세요.

모니터링 및 문제 해결

Application Insights (애플리케이션 인사이트)

모니터링을 위해 Application Insights를 사용하도록 설정합니다.

• 성능 모니터링: 페이지 로드 시간 및 사용자 상호 작용 추적
• 오류 추적: JavaScript 오류 및 실패한 요청 모니터링
• 사용 현황 분석: 사용자가 워크로드와 상호 작용하는 방법 이해
• 사용자 지정 원격 분석: 비즈니스 논리에 대한 사용자 지정 메트릭 추가

일반적인 문제 및 해결 방법

배포 실패

• 인증 오류: 을 사용하여 Azure CLI 로그인 확인 az account show
• 리소스를 찾을 수 없음: 웹앱 이름 및 리소스 그룹이 올바른지 확인
• 사용 권한 거부: 계정에 리소스 그룹에 대한 기여자 역할이 있는지 확인

런타임 문제

• 흰색 화면: 브라우저 콘솔에서 JavaScript 오류 확인
• 인증 실패: Entra ID 앱 등록 및 리디렉션 URI 확인
• API 호출 실패: CORS 구성 및 API 권한 확인

성능 최적화

• 느린 로드: 압축을 사용하도록 설정하고 번들 크기를 최적화합니다.
• 캐싱 문제: Front Door에서 적절한 캐시 헤더 구성
• 지리적 대기 시간: 전역 라우팅을 위해 Front Door가 올바르게 구성되었는지 확인

관련 가이드

• 워크로드를 게시하고 관리하는 방법 - Fabric에 매니페스트 업로드
• 설치 가이드 - 초기 개발 환경 설정
• 자습서: 시작 - 확장성 도구 키트 시작