App Design Center로 앱을 빠르게 배포

1. 소개

이 Codelab에서는 Google Cloud App Design Center (ADC)를 사용하여 전체 스택 애플리케이션을 배포하는 방법을 알아봅니다. Vue 3 프런트엔드, FastAPI 백엔드, 애플리케이션 데이터를 보유하는 MCP 서버가 포함된 'The Cymbal London Concierge' 애플리케이션을 배포합니다.

ADC를 사용하면 애플리케이션 아키텍처를 시각적으로 정의하고 단일 단위로 배포하여 종속 항목과 연결을 자동으로 관리할 수 있습니다.

실습할 내용

  • App Design Center를 설정합니다.
  • 애플리케이션 구성요소를 시각적으로 조립합니다.
  • 애플리케이션 아키텍처를 배포합니다.
  • 실행 중인 애플리케이션을 확인합니다.
  • 애플리케이션이 App Hub에 등록되었는지 확인합니다.
  • Application Monitoring에서 애플리케이션 측정항목, 트레이스, 로그를 확인합니다.

필요한 항목

  • 웹브라우저(예: Chrome)
  • 결제가 사용 설정된 Google Cloud 프로젝트.

이 Codelab은 초보자를 포함한 모든 수준의 개발자를 대상으로 합니다.

예상 소요 시간: 45분 예상 비용: 2달러 미만

2. 설정

프로젝트 설정

Google Cloud 프로젝트 만들기

  1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
  2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

Cloud Shell 시작

Cloud Shell은 Google Cloud에서 실행되는 명령줄 환경으로, 필요한 도구가 미리 로드되어 제공됩니다.

  1. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
  2. Cloud Shell에 연결되면 인증을 확인합니다.
    gcloud auth list
  3. 프로젝트가 구성되었는지 확인합니다.
    gcloud config get project
  4. 프로젝트가 예상대로 설정되지 않은 경우 설정합니다.
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

3. App Design Center 설정

애플리케이션을 어셈블하려면 먼저 ADC에서 작업공간을 설정해야 합니다.

  1. Google Cloud 콘솔에서 App Design Center를 검색하여 이동합니다.
  2. 이 프로젝트에서 ADC를 처음 사용하는 경우 설정 화면이 표시됩니다.
  3. 설정으로 이동을 클릭합니다.

App Design Center 설정

  1. 필수 API가 아직 사용 설정되지 않은 경우 사용 설정하라는 메시지가 표시됩니다. 계속하려면 사용 설정을 클릭합니다.

API 사용 설정

4. ADC 기능 살펴보기

이 작업에서는 ADC의 핵심 구성요소인 스페이스, 카탈로그, 템플릿을 알아봅니다.

ADC 스페이스

공간은 템플릿을 만들고 앱을 배포하는 곳입니다. 각 스페이스는 Google Cloud 프로젝트에 속합니다. ADC는 초기 설정 중에 기본 스페이스를 만들지만 나중에 다른 리전에 다른 스페이스를 자유롭게 만들 수 있습니다.

터미널을 통해 스페이스를 보려면 다음 단계를 따르세요.

  1. Cloud Shell 툴바에서 편집기 열기를 클릭하거나 터미널을 사용합니다.
  2. 다음 명령어를 실행합니다.
gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

다음과 같은 출력이 표시되어 리전에 default-space가 있음을 나타냅니다.

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5. 템플릿 조립

이 단계에서는 플랫폼팀 엔지니어의 역할을 맡습니다. 목표는 조직에서 에이전트 애플리케이션을 위한 재사용 가능하고 안전하며 규정을 준수하는 템플릿을 만드는 것입니다. 구성요소를 추가하고 제한사항을 구성하여 이 템플릿에서 배포된 애플리케이션이 회사의 클라우드 정책을 준수하도록 합니다.

1. 새 디자인 만들기

  1. ADC 콘솔에서 템플릿 > 템플릿 만들기를 클릭합니다.
  2. 이 템플릿은 Cymbal London Concierge 애플리케이션 및 기타 유사한 애플리케이션을 배포하는 데 사용되므로 템플릿 이름을 simple-3-tier-agentic-app로 지정합니다.템플릿 만들기

2. 데이터 MCP 서버 추가

이 구성요소는 데이터베이스 상호작용과 벡터 검색을 처리합니다.

  1. 구성요소 추가 > Cloud Run (서비스)을 클릭합니다. 이 구성요소를 클릭하면 오른쪽 상단에 구성요소 ID가 표시됩니다. cloud-run-1 형식입니다. 코드 보기에서 수정하여 data-mcp-server로 변경할 수 있지만 (나중에 설명) 그대로 두겠습니다.구성요소 추가
  2. 서비스 이름에 data-mcp-server을 입력합니다.
  3. 고급 설정 표시에서 구성원을 allUsers로 설정합니다. (참고: 프로덕션 환경에서는 이 기능을 제한하는 것이 좋지만 여기서는 Codelab의 단순성을 위해 사용합니다.)
  4. 고급 설정 표시에서 VPC 액세스를 설정하고 이그레스를 PRIVATE_RANGES_ONLY로 설정합니다.
  5. 선택적으로 고급 설정 표시에서 Prometheus 사이드카 사용 설정을 선택 해제합니다.VPC 액세스
  6. 저장을 클릭합니다.

3. 에이전트 백엔드 추가

에이전트 동작을 조정하는 FastAPI 애플리케이션입니다.

  1. 구성요소 추가 > Cloud Run (서비스)을 클릭합니다.
  2. 파일 이름을 agent-backend로 지정합니다.
  3. 고급 필드 표시에서 서비스 계정 만들기를 선택하고 서비스 계정 프로젝트 역할에서 다음 역할을 한 번에 하나씩 추가합니다.
    • roles/monitoring.metricWriter
    • roles/logging.logWriter
    • roles/cloudtrace.agent
    • roles/telemetry.writer
    • roles/serviceusage.serviceUsageConsumer. 이러한 역할을 통해 에이전트가 Cloud Monitoring, Cloud Logging, Cloud Trace를 사용할 수 있습니다. 규정 준수 구성: 플랫폼 팀은 필요한 역할을 명시적으로 나열하여 최소 권한의 원칙을 적용합니다.
    역할
  4. 고급 설정 표시에서 구성원을 allUsers로 설정합니다.
  5. 고급 설정 표시에서 VPC 액세스를 설정하고 이그레스를 PRIVATE_RANGES_ONLY로 설정합니다.
  6. 선택적으로 고급 설정 표시에서 Prometheus Sidecar 사용 설정을 선택 해제합니다.
  7. agent-backend에서 data-mcp-server로 연결을 드래그하여 agent-backend를 data-mcp-server에 연결합니다.
  8. 저장을 클릭합니다.

4. 프런트엔드 추가

프런트엔드 UI입니다.

  1. 구성요소 추가 > Cloud Run (서비스)을 클릭합니다.
  2. 서비스 이름에 frontend을 입력합니다.
  3. 고급 설정 표시에서 서비스 계정 만들기를 선택 해제합니다.
  4. 고급 설정 표시에서 인그레스를 INGRESS_TRAFFIC_INTERNAL_LOADBALANCER로 설정합니다. 규정 준수 구성: 프런트엔드 컨테이너에 대한 직접 공개 액세스가 차단되어 부하 분산기를 통해 트래픽이 강제됩니다.
  5. 고급 설정 표시에서 구성원을 allUsers로 설정합니다.프런트엔드
  6. 선택적으로 고급 설정 표시에서 Prometheus Sidecar 사용 설정을 선택 해제합니다.
  7. 저장을 클릭합니다.
  8. frontend에서 agent-backend로 연결을 드래그하여 frontend를 agent-backend에 연결합니다.

5. Vertex AI 구성요소 추가

  1. 구성요소 추가 > Vertex AI를 클릭합니다.
  2. 파일 이름을 vertex-ai로 지정합니다.
  3. vertex-ai에서 agent-backend 및 data-mcp-server로 각각 두 개의 연결을 드래그하여 agent-backend 및 data-mcp-server에 연결합니다. agent-backend 및 data-mcp-server의 서비스 계정은 Vertex AI 구성요소에 연결되어 있으므로 역할 aiplatform.user이 이미 할당되어 있습니다.

6. 전역 부하 분산기 추가

부하 분산기는 프런트엔드를 공개 인터넷에 노출합니다. ADC에서는 백엔드와 프런트엔드 구성요소로 분할됩니다.

A. 부하 분산기 백엔드 추가

  1. **구성요소 추가 > 글로벌 Cloud Load Balancing (백엔드)**을 클릭합니다.
  2. 파일 이름을 galb-backend로 지정합니다.
  3. 연결 추가를 클릭하고 frontend에 연결합니다.

B. 부하 분산기 프런트엔드 추가

  1. **구성요소 추가 > 글로벌 Cloud Load Balancing (프런트엔드)**을 클릭합니다.
  2. 파일 이름을 galb-frontend로 지정합니다.
  3. 연결 추가를 클릭하고 galb-backend에 연결합니다.
  4. galb-frontend에서 galb-backend로 연결을 드래그하여 galb-frontend를 galb-backend에 연결합니다.

앱 템플릿

카탈로그에서 템플릿 공유

카탈로그를 사용하면 여러 스페이스에서 앱 템플릿을 공유하여 아키텍처 거버넌스를 사용 설정할 수 있습니다. 카탈로그는 플랫폼팀에서 공유를 위해 생성하고 승인한 템플릿의 중앙 저장소 역할을 합니다. 스페이스 간에 카탈로그를 공유하면 공통 프로젝트의 중복된 작업을 방지하고 시작 시간을 간소화할 수 있습니다.

이제 카탈로그에 템플릿을 추가합니다.

  1. 카탈로그 탭을 클릭합니다.
  2. 템플릿 추가를 클릭하고 simple-3-tier-agentic-app 템플릿을 선택합니다.
  3. 카탈로그에 추가를 클릭합니다.카탈로그에 추가

템플릿은 Google 템플릿 (사전 정의된 패턴), 공유 템플릿 (조직 전체에서 공유), 템플릿 (내 스페이스의 맞춤 청사진)의 세 위치에서 찾을 수 있습니다.

6. 애플리케이션 배포

이제 이 템플릿을 사용하여 cymbal-london-concierge 애플리케이션을 배포하려는 앱 개발자의 역할을 수행할 차례입니다.

  1. ADC 콘솔의 템플릿 탭에서 템플릿을 다시 열고 앱 구성 버튼을 클릭합니다.앱 구성
  2. 새 애플리케이션 만들기를 클릭합니다.
  3. 애플리케이션 구성:
    • 애플리케이션 이름: cymbal-london-concierge
    • 배포 프로젝트: 프로젝트 ID
    • 리전: us-central1
    • 입력 속성>환경: Development
    • 입력 속성>중요도: Low
  4. 애플리케이션 만들기를 클릭합니다.프로덕션 배포의 경우 환경에 '프로덕션'을 선택하고 중요도에 '높음'을 선택합니다. 이는 SRE 및 운영팀이 발생하는 문제를 분류하고 작업의 우선순위를 지정하는 데 도움이 되는 태그입니다.
  5. 그러면 애플리케이션 템플릿이 포함된 배포 세부정보 페이지가 열립니다. 이것은 템플릿일 뿐이므로 애플리케이션에 맞는 구성을 추가해야 합니다.
  6. 프런트엔드를 구성해 보겠습니다. 프런트엔드 구성요소를 클릭합니다.
    1. 컨테이너 > 컨테이너 수정을 클릭합니다.
    2. 일반 컨테이너 이미지를 애플리케이션에 사용할 이미지로 바꿔야 합니다.
    3. 컨테이너 이미지를 us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1컨테이너 이미지 변경로 설정합니다.
    4. 포트 http1을 80으로 설정합니다.
    5. 다음 환경 변수를 설정합니다.
      • API_BASE_URL: module.cloud-run-2.service_uri (cloud-run-2이 에이전트 백엔드 구성요소의 이름인지 확인하고, 그렇지 않은 경우 구성요소의 실제 이름으로 대체)
    6. 저장을 클릭합니다.
  7. 에이전트 백엔드를 구성해 보겠습니다. agent-backend 구성요소를 클릭합니다.
    1. 컨테이너 > 컨테이너 수정을 클릭합니다.
    2. 일반 컨테이너 이미지를 애플리케이션에 사용할 이미지로 바꿔야 합니다.
    3. 컨테이너 이미지를 us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1로 설정합니다.
    4. 다음 환경 변수를 설정합니다.
    5. GOOGLE_CLOUD_PROJECT:
    6. GOOGLE_CLOUD_LOCATION: us-central1
    7. DATA_BACKEND_URL: module.cloud-run-1.service_uri (cloud-run-1이 데이터 mcp 서버 구성요소의 이름인지 확인하고, 그렇지 않은 경우 구성요소의 실제 이름으로 대체)
    8. 포트 http1을 8000으로 설정합니다.
    9. 저장을 클릭합니다.
  8. 데이터 mcp 서버를 구성해 보겠습니다. data-mcp-server 구성요소를 클릭합니다.
    1. 컨테이너 > 컨테이너 수정을 클릭합니다.
    2. 일반 컨테이너 이미지를 애플리케이션에 사용할 이미지로 바꿔야 합니다.
    3. 컨테이너 이미지를 us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1로 설정합니다.
    4. 다음 환경 변수를 설정합니다.
    5. GOOGLE_CLOUD_PROJECT:
    6. GOOGLE_CLOUD_LOCATION: us-central1
    7. DB_TYPE: sqlite
    8. EMBEDDING_MODEL: text-embedding-005
    9. 포트 http1을 8002으로 설정합니다.
    10. 저장을 클릭합니다.
    실제 프로덕션 시나리오에서는 CloudSQL 또는 AlloyDB와 같은 데이터베이스를 구성하고 데이터 mcp 서버의 데이터베이스 연결 문자열도 제공합니다. 하지만 이 실습에서는 메모리 내 데이터베이스를 사용합니다. 또한 mcp 서버와 데이터베이스를 비공개로 설정하여 에이전트 백엔드 또는 네트워크 내에서만 액세스할 수 있도록 합니다.
  9. 페이지 상단의 코드 버튼을 클릭하여 애플리케이션의 Terraform 코드를 확인합니다. 코드 가져오기 버튼을 클릭하여 애플리케이션의 Terraform 코드를 다운로드하여 코드베이스에 저장할 수도 있습니다.앱 템플릿
  10. 페이지 오른쪽 상단에 있는 배포 버튼을 클릭하여 애플리케이션을 배포합니다.
  11. 배포 페이지에서 배포 파이프라인의 서비스 계정을 만들거나 기존 계정을 선택하라는 메시지가 표시됩니다. 서비스 계정 만들기를 클릭하면 이름이 자동으로 입력됩니다. 그런 다음 계속을 클릭합니다. 새 서비스 계정을 만드는 데 몇 초 정도 걸립니다.

서비스 계정 만들기

  1. 서비스 계정이 생성되면 페이지가 새로고침되고 '서비스 계정 선택' 옆에 체크표시가 표시됩니다.

생성된 서비스 계정

  1. 그런 다음 페이지 하단의 배포를 클릭합니다.
  2. 완료하는 데 몇 분 정도 걸릴 수 있습니다. 배포가 완료되면 각 구성요소 옆에 녹색 체크표시가 표시됩니다. 로그 링크 버튼을 클릭하여 배포 상태를 확인할 수도 있습니다. 이 버튼을 클릭하면 Cloud Build 로그가 열립니다. 버튼이 표시되는 데 몇 분 정도 걸릴 수 있습니다.
![Deployment Logs](./img/10b_logs.png)
  1. 클라우드 빌드 로그를 확인하여 배포 상태를 확인하거나 애플리케이션을 배포하는 동안 발생할 수 있는 오류가 있는지 확인할 수 있습니다. Google Cloud 콘솔에서 Cloud Build를 검색하고 기록을 클릭하여 Cloud Build 로그로 바로 이동할 수도 있습니다. 애플리케이션을 배포하는 데 5~8분 정도 걸립니다.
![Cloud Build](./img/10c_cloudbuild.png)
  1. 배포가 완료되면 배포 상태 필드 옆에 녹색 체크표시가 표시됩니다.
![Deployment Complete](./img/11_deployed.png)

7. 애플리케이션 확인

에이전트가 활성 상태인지 테스트해 보겠습니다. 배포 세부정보 페이지의 outputs 섹션에 프런트엔드 구성요소의 URL이 표시됩니다. URL을 복사하여 브라우저에 붙여넣습니다. https가 아닌 http를 사용해야 합니다. 프런트엔드에서 http를 사용하므로 브라우저에 표시되는 경고도 수락합니다.

앱과 채팅하고 런던 여행 일정을 만들어 달라고 요청합니다.

프런트엔드

8. App Hub 및 애플리케이션 모니터링

  1. ADC 콘솔에서 페이지의 오른쪽 상단에 있는 App Hub에서 앱 보기 버튼을 클릭합니다.

App Hub

  1. 그러면 App Hub에서 앱이 열립니다. App Hub는 모든 애플리케이션을 확인하고 관리할 수 있는 중앙 위치로, 리소스 중심 뷰에서 애플리케이션 중심 뷰로 전환할 수 있습니다. ADC를 사용하여 앱을 만들면 App Hub에 앱이 자동으로 생성됩니다. 애플리케이션을 구성하는 모든 워크로드와 서비스가 여기에 표시됩니다. 클라우드의 리소스를 개별 리소스로 보는 대신 단일 애플리케이션의 일부로 볼 수 있으므로 관리 및 거버넌스가 간소화됩니다.

App Hub

  1. 관측 가능성에서 보기 버튼을 클릭합니다. 그러면 Observability 콘솔에서 애플리케이션이 열립니다.
  2. 대시보드 보기를 엽니다. 대시보드에서는 요청 비율, 오류율, 지연 시간, 포화도와 같은 4가지 골든 시그널과 같은 측정항목을 제공하여 애플리케이션의 성능과 상태를 개략적으로 보여줍니다. 이 애플리케이션 중심 모니터링은 안정성을 유지하는 데 매우 중요합니다. 애플리케이션의 로그와 트레이스를 볼 수도 있으므로 신호를 상호 연관시키고 병목 현상을 정확히 파악할 수 있습니다. Vertex AI 또는 데이터 MCP 서버의 응답이 느리면 사용자 환경이 저하될 수 있는 이와 같은 복잡한 에이전트 애플리케이션에서는 특히 중요합니다.

대시보드

  1. 가이드 탐색: 앱에서 에이전트에게 구체적인 질문을 합니다 (예: '런던에서 가장 가볼 만한 곳은 어디인가요?'). 그런 다음 관측 가능성 콘솔로 돌아가 Trace 목록을 확인합니다. 요청에 해당하는 트레이스를 찾습니다. 클릭하면 자세한 워터폴 뷰를 확인할 수 있습니다. 프런트엔드, 에이전트 백엔드, Vertex AI 호출에 소요된 시간을 확인할 수 있습니다. 이를 통해 지연 시간이 발생하는 위치를 정확하게 식별할 수 있습니다.

9. 축하합니다

축하합니다. ADC를 사용하여 3계층 애플리케이션 아키텍처를 배포했습니다.

학습한 내용

  • ADC를 사용하여 클라우드 아키텍처를 시각적으로 조립하는 방법
  • UI를 통해 ADC를 설정하고 API를 사용 설정하는 방법
  • ADC를 사용하여 애플리케이션을 배포하는 방법
  • 애플리케이션 중심 리소스 보기를 위해 App Hub를 사용하는 방법
  • 관측 가능성 대시보드를 사용하여 애플리케이션 상태를 모니터링하는 방법

참조 문서