GitLab을 사용한 Google Agent Engine에 대한 안전하고 빠른 배포

Source: GitLab Blog

이 튜토리얼에서는 Google의 Agent Development Kit (ADK) 로 만든 AI 에이전트를 Agent Engine에 GitLab의 기본 Google Cloud 통합 및 CI/CD 파이프라인을 사용해 배포하는 방법을 배웁니다. 다음 내용을 다룹니다:

• IAM 구성
• 파이프라인 설정
• 배포된 에이전트 테스트

Agent Engine이란 무엇이며 왜 중요한가?

Agent Engine은 Google Cloud의 관리형 런타임으로, AI 에이전트를 위해 특별히 설계되었습니다. 이를 에이전트가 살아가고 실행되며 확장되는 프로덕션 환경이라고 생각하면 됩니다—기반 인프라를 직접 관리할 필요가 없습니다.

• 인프라, 스케일링, 세션 관리 및 메모리 저장소를 처리합니다.
• Google Cloud Logging, Monitoring, IAM과 기본적으로 통합됩니다.

에이전트 엔진에 배포하기 위해 GitLab을 사용하는 이유

AI 에이전트를 배포하는 일은 보안 고려사항, CI/CD 오케스트레이션, 클라우드 권한 관리 등으로 인해 복잡할 수 있습니다. GitLab은 전체 과정을 간소화하면서 보안을 강화합니다:

사전 요구 사항

시작하기 전에 다음 항목을 확인하세요:

1. Google Cloud 프로젝트에 다음 API가 활성화되어 있어야 합니다
   • Cloud Storage API
   • Vertex AI API
2. GitLab 프로젝트는 소스 코드와 CI/CD 파이프라인을 위해 필요합니다.
3. Google Cloud Storage 버킷은 배포 스테이징을 위해 필요합니다.
4. Google Cloud IAM 통합이 GitLab에 구성되어 있어야 합니다 (Step 1 아래 참고).

Step 1 – IAM 통합 구성

보안 배포의 기반은 Workload Identity Federation을 사용한 GitLab과 Google Cloud 간의 올바른 IAM 구성입니다.

GitLab에서

1. Settings > Integrations 로 이동합니다.
2. Google Cloud IAM integration 을 찾습니다.
3. 다음 정보를 입력합니다:

GitLab이 스크립트를 생성합니다. 스크립트를 복사하여 Google Cloud Shell 에서 실행하면 두 플랫폼 간에 Workload Identity Federation이 설정됩니다.

필요한 역할 추가

Agent Engine에 배포할 서비스 주체에 다음 역할을 추가합니다:

• roles/aiplatform.user
• roles/storage.objectAdmin

예시 gcloud 명령

# Set variables (replace placeholders with your values)
GCP_PROJECT_ID=""
GCP_PROJECT_NUMBER=""
GCP_WORKLOAD_IDENTITY_POOL=""

# Grant Vertex AI user role
gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
  --member="principalSet://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GCP_WORKLOAD_IDENTITY_POOL}/attribute.developer_access/true" \
  --role='roles/aiplatform.user'

# Grant Cloud Storage object admin role
gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
  --member="principalSet://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GCP_WORKLOAD_IDENTITY_POOL}/attribute.developer_access/true" \
  --role='roles/storage.objectAdmin'

단계 2 – CI/CD 파이프라인 만들기

루트 디렉터리에 .gitlab-ci.yml 파일을 생성합니다.

stages:
  - test
  - deploy

cache:
  paths:
    - .cache/pip
  key: ${CI_COMMIT_REF_SLUG}

variables:
  GCP_PROJECT_ID: ""
  GCP_REGION: "us-central1"
  STORAGE_BUCKET: ""
  AGENT_NAME: "Canada City Advisor"
  AGENT_ENTRY: "canada_city_advisor"

image: google/cloud-sdk:slim

# Security‑scanning templates
include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml
  - template: Jobs/SAST.gitlab-ci.yml
  - template: Jobs/Secret-Detection.gitlab-ci.yml

deploy-agent:
  stage: deploy
  identity: google_cloud          # Enables keyless auth via Workload Identity Federation
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  before_script:
    - gcloud config set core/disable_usage_reporting true
    - gcloud config set component_manager/disable_update_check true
    - pip install -q --no-cache-dir --upgrade pip google-genai google-cloud-aiplatform -r requirements.txt --break-system-packages
  script:
    - gcloud config set project $GCP_PROJECT_ID
    - adk deploy agent_engine \
        --project=$GCP_PROJECT_ID \
        --region=$GCP_REGION \
        --staging_bucket=gs://$STORAGE_BUCKET \
        --display_name="$AGENT_NAME" \
        $AGENT_ENTRY

파이프라인 개요

핵심 참고 사항

• identity: google_cloud는 Workload Identity Federation을 통한 키 없는 인증을 활성화합니다.
• 보안 스캐너는 템플릿으로 포함되어 있어 별도 설정 없이 기본적으로 실행됩니다.
• adk deploy agent_engine은 패키징 및 배포 복잡성을 추상화합니다.
• 캐싱을 통해 pip 의존성을 보존함으로써 이후 실행 속도가 빨라집니다.

Step 3 – 배포 및 검증

1. 에이전트 코드 와 .gitlab-ci.yml 파일을 GitLab에 커밋합니다.

2. CI /CD > Pipelines 로 이동하여 실행 상황을 모니터링합니다.

3. 확인합니다:

   • Test stage – 보안 스캔이 완료되었습니다.
   • Deploy stage – 에이전트가 Agent Engine에 푸시되었습니다.

4. 파이프라인이 성공하면 Google Cloud Console에서 배포를 확인합니다:

   • Vertex AI > Agent Engine 으로 이동합니다.
   • 배포된 에이전트를 찾습니다.
   • 리소스 이름을 확인합니다 (테스트에 필요합니다).

4단계 – 배포된 에이전트 테스트

에이전트를 간단한 curl 요청으로 테스트할 수 있습니다. 다음 세 가지 정보를 준비하세요:

curl 명령 예시

AGENT_ID="projects//locations/us-central1/agents/"
ENDPOINT="https://us-central1-aiplatform.googleapis.com/v1/${AGENT_ID}:predict"

# 액세스 토큰 가져오기 (키가 없는 서비스 계정을 사용하는 경우 이 단계는 건너뛸 수 있습니다)
ACCESS_TOKEN=$(gcloud auth print-access-token)

curl -X POST "${ENDPOINT}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "instances": [
          {"text": "Hello, Agent!"}
        ]
      }'

모든 설정이 올바르게 완료되었다면, 에이전트로부터 JSON 응답을 받게 됩니다.

🎉 완료되었습니다!

이제 다음을 수행했습니다:

• GitLab과 Google Cloud 사이에 보안 IAM 통합을 설정했습니다.
• 보안 스캔을 실행하고 ADK 에이전트를 배포하는 CI/CD 파이프라인을 구축했습니다.
• 에이전트를 Agent Engine에 배포하고 존재를 확인했습니다.
• 간단한 curl 요청으로 실시간 엔드포인트를 테스트했습니다.

에이전트를 자유롭게 반복 개발하고, 새로운 변경을 푸시하면 GitLab이 자동으로 테스트와 배포를 처리합니다. 즐거운 개발 되세요!

프로젝트 구성

• Project ID: Google Cloud 프로젝트
• Location: 배포한 지역 (예: us-central1)

PROJECT_ID=""
LOCATION="us-central1"
AGENT_ID=""
TOKEN=$(gcloud auth print-access-token)

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/reasoningEngines/${AGENT_ID}:streamQuery" \
  -d '{
    "input": {
      "message": "I make $85,000 per year and I prefer cities with mild winters and a vibrant cultural scene. I also want to be near the coast if possible. What Canadian cities would you recommend?",
      "user_id": "demo‑user"
    }
  }' | jq -r '.content.parts[0].text'

모든 것이 올바르게 구성되었다면, 에이전트가 제공된 예산 및 생활 선호도에 기반한 맞춤형 도시 추천을 응답할 것입니다.

이 접근 방식의 보안 이점

• 장기 인증 정보 없음 – 워크로드 아이덴티티 연합은 서비스 계정 키를 완전히 제거합니다.
• 자동 취약점 스캔 – 모든 배포가 프로덕션에 도달하기 전에 스캔됩니다.
• 완전한 감사 추적 – GitLab은 누가 언제 무엇을 배포했는지에 대한 전체 가시성을 유지합니다.
• 최소 권한 원칙 – 세분화된 IAM 역할은 필요한 것만 접근하도록 제한합니다.

요약

AI 에이전트를 프로덕션에 배포하는 것이 복잡할 필요는 없습니다. GitLab의 DevSecOps 플랫폼과 Google Cloud의 Agent Engine을 결합하면 다음을 얻을 수 있습니다:

• 스케일링 및 인프라를 처리하는 관리형 런타임.
• 추가 도구 없이 제공되는 보안 스캔.
• 네이티브 클라우드 통합을 통한 키 없는 인증.
• 최신 AI 개발 워크플로에 맞는 간소화된 배포 프로세스.

전체 데모 보기

[Link to demo video]

직접 사용해 볼 준비가 되셨나요?

이 튜토리얼의 전체 코드 예제를 사용하여 지금 바로 시작하세요.

아직 GitLab 고객이 아니신가요? 무료 체험으로 DevSecOps 플랫폼을 살펴보세요.