Gemini CLI와 GCP MCP Server 를 통한 Google Cloud 관리방안

목적 및 배경:
gemini Cli와 Google Cloud MCP Server를 연결하여 복잡한 gcloud CLI 명령어 대신, 일상적인 대화(자연어)를 통해 Google Cloud Platform(GCP) 리소스를 생성, 조회, 수정, 삭제하는 시스템을 구축하는 것을 목표로합니다.

2025년 7월 1일 기준으로 Google Cloud MCP Server 는 Google Cloud의 공식 제품은 없습니다.
각 MCP 서버별로 제약 사항이 다른 상태입니다.
본 문서에서는 기본적인 구축 후 자연어를 이용하여 Cloud Logging을 조회, 분석하는 방안을 작성하였습니다.

 

• PC 설정
  Node.js 설치가 필요합니다.
  
  아래 공식 사이트에 각 운영체제별 설치법이 가이드 되어 있으니 참고하여 설치합니다.
  https://nodejs.org/ko/download
  
  본 문서에서는 MAC환경에서 진행하였으므로 MacOS권장 방법으로 설치 진행합니다.
  

  # nvm 다운로드 및 설치:
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  
  # Node.js 다운로드 및 설치:
  nvm install 22
  
  # Node.js 버전 확인:
  node -v # "v22.17.0"가 출력되어야 합니다.
  nvm current # "v22.17.0"가 출력되어야 합니다.
  
  npm 버전 확인:
  npm -v # 10.9.2가 출력되어야 합니다.

   

1. Gemini CLI 설치
   Gemini CLI는 Google의 Gemini 모델을 커맨드 라인 환경에서 사용할 수 있게 해주는 도구입니다. 이 CLI를 통해 MCP 서버에 자연어 명령을 전달하게 됩니다.
   
   1회성 사용방안 : 
   터미널에 아래 명령어를 입력하여 설치 없이 바로 실행할 수 있습니다.
   ⁠npx https://github.com/google-gemini/gemini-cli
   
   설치 후 사용 :
   CLI를 자주 사용할 경우, 시스템에 전역으로 설치하는 것을 권장합니다.
   ⁠npm install -g @google/gemini-cli
   gemini
   
   더 자세한 설치 방법 및 옵션은 공식 GitHub 저장소에서 확인 부탁드립니다.
   설치 공식 docs : https://github.com/google-gemini/gemini-cli
   
   
2. MCP Server (Google Cloud MCP Server) 설치, 설정
   Google Cloud MCP Server 는 Google Cloud의 공식 제품은 없습니다.
   
   설치 Github docs : https://github.com/eniayomi/gcp-mcp
   설치 Github docs : https://github.com/krzko/google-cloud-mcp
   
   각 MCP Server들은 오픈소스 상태여서 정해진 설치 방안이 없습니다.
   본 문서에서는 제일 간단한 “https://github.com/eniayomi/gcp-mcp“의 MCP Server를 사용합니다.
   
   설치는 간단하게 Git에서 Clone 후 npm 설치를 통해 진행합니다.
   - Git Clone
   ⁠git clone https://github.com/eniayomi/gcp-mcp
   cd gcp-mcp
   
   - Install 
   ⁠npm install
   
   이후 “gcloud auth application-default login” 명령어를 통해 GCP 인증 하여 프로젝트로 접근가능하도록 합니다.
   
   
3. Gemini CLI 설정
   
   - 인증방법
   현재 인증방법으로는 아래와 같이 3가지가 있습니다.
   1) 개인 Google (Gmail)인증
   2) Gemini API (AI Studio) / GCP 프로젝트 빌링연결 필요, 학습내용 공유되는 퍼블릭
   3) Vertex AI (GCP의 AI 서비스) 로 구분됩니다.
   2025년 7월 기준 개인 Google으로도 충분하게 사용할 수 있으므로 Googlg 로그인 하여 인증 후 진행합니다.
   
   

 

현재 Gemini CLI은 출시된지 얼마 안된 상태입니다. 하여 Claude Desktop설정하는 방안과 동일하게 진행합니다.

Gemini CLI 설정파일 위치 : /Users/사용자/.gemini/settings.json

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
-------------------------------------------------
위 쉼표 추가 후에 아래 mcp servers 부분부터 추가합니다.
    "mcpServers": {
      "google-cloud-mcp": {
          "command": "node",
          "args": [
              "/Users/linux1547/Desktop/PDS/google-cloud-mcp/dist/index.js"
          ],
          "env": {
              "GOOGLE_APPLICATION_CREDENTIALS": "/Users/linux1547/.config/gcloud/application_default_credentials.json"
          }
      }
  }
}

gemini CLI를 재실행 후 /mcp 를 입력합니다.

MCP서버의 리스트가 확인되며, 어떤 기능을 사용할 수 있는지도 확인할 수 있습니다.

4. 사용방안
본 문서에서는 MCP서버가 자연어로 문의된 로그를 이해하고, 그것으로 직접 “Cloud Logging”으로 조회하여 정리하는 방안을 테스트 했습니다.
향 후 MCP서버에 기능이 더 추가되고, 안정화 된다면 리소스 추가, 삭제, 수정이 가능할 것입니다.

아래와 같은 자연어로 조회를 하였습니다.

6월 1일 부터 6월 30일까지 "****" 프로젝트에서 발생한 모든 오류(ERROR) 및 경고(WARNING) 로그를 정리
중복된 동일 로그는 각 발생날짜만 표기
로그 내용은 상세하게 주되, 개선과 해결방안이 있으면 정리

아래와 같이 ERROR, WARING 로그만 확인하여 내용을 정리하여 확인할 수 있습니다.

 

아래는 위 화면의 Text 내역 입니다.
로그를 정리하여 종류별 어떤 내용인지 해결방안까지 작성하여 주는 것을 확인할 수 있습니다.

✦ 2025년 6월 10일부터 6월 30일까지 ***** 프로젝트에서 발생한 모든 오류(ERROR) 및 경고(WARNING) 로그를 정리하여 상세히 설명하고 개선 및 해결 방안을
  제시합니다.

  ---


  1. Stackdriver 로깅 에이전트 구성 경고 (WARNING)


   * 발생 날짜: 2025-06-30
   * 로그 메시지:
       * [ warn] [output:stackdriver:stackdriver.1] private_key is not defined, fetching it from metadata server
       * [ warn] [output:stackdriver:stackdriver.1] client_email is not defined, using a default one
       * [ warn] [output:stackdriver:stackdriver.0] private_key is not defined, fetching it from metadata server
       * [ warn] [output:stackdriver:stackdriver.0] client_email is not defined, using a default one
   * 상세 내용:
      이 경고는 Fluent Bit과 같은 로깅 에이전트가 Google Cloud의 Stackdriver(현재 Cloud Logging)로 로그를 전송할 때 필요한 서비스 계정의 private_key와
  client_email이 구성 파일에 명시적으로 정의되어 있지 않음을 나타냅니다. 현재는 VM의 메타데이터 서버에서 해당 정보를 자동으로 가져와 로그 전송이 정상적으로
   이루어지고 있습니다. 따라서 기능적인 문제는 아니지만, 구성의 명확성과 이식성을 높일 수 있습니다.
   * 개선 및 해결 방안:
       * 명시적 서비스 계정 키 사용: 로깅 에이전트의 구성 파일에 서비스 계정 키 파일의 경로를 명시적으로 지정하여 private_key와 client_email을 설정합니다.
         이는 환경 변수나 Secret Manager를 통해 관리할 수도 있습니다.
       * 권한 확인: VM 인스턴스에 연결된 서비스 계정이 roles/logging.logWriter 권한을 가지고 있는지 확인하여 로그를 Cloud Logging에 쓸 수 있도록 합니다.

  2. 스토리지 형식 확인 실패 (ERROR)


   * 발생 날짜: 2025-06-30
   * 로그 메시지:
       * [error] [storage] format check failed: tail.1/1008-1750053958.239491870.flb
   * 상세 내용:
      로깅 에이전트가 내부적으로 사용하는 버퍼 파일(Fluent Bit의 경우 .flb 확장자를 가짐)의 형식이 손상되었거나 유효하지 않다는 오류입니다. 이는 디스크 I/O
   문제, 파일 시스템 손상, 또는 에이전트의 비정상적인 종료로 인해 파일이 제대로 기록되지 않았을 때 발생할 수 있습니다. 이 오류가 발생하면 해당 버퍼 파일에
  저장되어 있던 로그 데이터가 유실될 가능성이 있습니다.
   * 개선 및 해결 방안:
       * 디스크 상태 점검: VM의 디스크 상태를 확인하고, 필요한 경우 디스크 검사 및 복구 작업을 수행합니다.
       * 로깅 에이전트 재시작: 에이전트를 재시작하여 새로운 버퍼 파일을 생성하도록 합니다.
       * 버퍼링 설정 검토: 로깅 에이전트의 버퍼링 설정(예: storage.path, storage.sync)을 검토하여 디스크에 대한 쓰기 안정성을 높일 수 있는지 확인합니다.
       * 에이전트 버전 업데이트: 사용 중인 로깅 에이전트(예: Fluent Bit)의 알려진 버그가 있는지 확인하고, 최신 안정 버전으로 업데이트를 고려합니다.


  3. SSHD 서비스 재로드 오류 (ERROR)


   * 발생 날짜: 2025-06-30
   * 로그 메시지:
       * Error reloading service: Failed to reload-or-restart sshd.service: Unit sshd.service not found..
   * 상세 내용:
      시스템이 sshd.service라는 이름의 SSH 데몬 서비스를 다시 로드하거나 재시작하려고 시도했지만, 해당 서비스 유닛을 찾을 수 없어 실패했습니다. 이는 주로
  다음과 같은 이유로 발생합니다.
       * 서비스 이름 불일치: 운영체제마다 SSH 데몬의 서비스 이름이 다를 수 있습니다 (예: ssh.service 대신 sshd.service를 사용).
       * 서비스 미설치: SSH 데몬이 설치되어 있지 않거나, systemd와 같은 서비스 관리자에 올바르게 등록되지 않았을 수 있습니다.
       * 권한 문제: 서비스를 관리할 권한이 부족할 수 있습니다.
   * 개선 및 해결 방안:
       * 정확한 서비스 이름 확인: VM의 운영체제에 맞는 SSH 데몬 서비스 이름을 확인하고, 해당 서비스를 관리하는 스크립트나 명령어를 수정합니다. (예: sudo
         systemctl status ssh 또는 sudo systemctl status sshd)
       * SSHD 설치 및 활성화: SSH 데몬이 설치되어 있지 않다면 설치하고, 서비스 관리자에 등록하여 활성화합니다.
       * 권한 부여: 서비스를 관리하는 사용자 또는 프로세스에 적절한 권한을 부여합니다.

  4. 만료된 SSH 키 (WARNING)


   * 발생 날짜: 2025-06-27, 2025-06-30
   * 로그 메시지:
       * invalid ssh key entry - expired key: linux1547:ssh-rsa ...
       * invalid ssh key key entry - expired key: linux1547:ecdsa-sha2-nistp256 ...
   * 상세 내용:
      linux1547 사용자의 SSH 키가 만료되어 더 이상 해당 키를 사용하여 VM 인스턴스에 접속할 수 없다는 경고입니다. Google Cloud의 OS Login 기능은 보안 강화를
   위해 SSH 키에 만료 날짜를 설정할 수 있습니다. 이 로그는 해당 키가 설정된 만료 날짜를 지났음을 알립니다.
   * 개선 및 해결 방안:
       * 새로운 SSH 키 생성 및 등록: gcloud compute os-login ssh-keys add 명령어를 사용하여 새로운 SSH 키 쌍을 생성하고, 공개 키를 OS Login 프로필에
         추가합니다.
       * 키 만료 정책 검토: 조직의 보안 정책에 따라 SSH 키의 만료 기간을 적절하게 설정하고, 만료 전에 갱신 절차를 안내합니다.


  5. 메타데이터 감시 오류 (WARNING)


   * 발생 날짜: 2025-06-27, 2025-06-30
   * 로그 메시지:
       * Error watching metadata: context canceled
   * 상세 내용:
      VM 인스턴스가 Google Cloud 메타데이터 서버의 변경 사항을 감시하는 과정에서 연결이 끊겼거나, 감시 작업이 취소되었음을 나타내는 경고입니다. 이는 VM의
  종료, 네트워크 연결 불안정, 또는 메타데이터 서버와의 일시적인 통신 문제로 인해 발생할 수 있습니다. 일반적으로 일시적인 현상일 수 있으나, 반복적으로
  발생한다면 네트워크 또는 VM 상태를 점검해야 합니다.
   * 개선 및 해결 방안:
       * VM 상태 및 네트워크 연결 확인: VM이 정상적으로 실행 중인지, 네트워크 연결에 문제가 없는지 확인합니다.
       * 반복 여부 확인: 이 경고가 지속적으로 발생하는지 모니터링하여 근본적인 원인(예: VM의 불안정성)을 파악합니다.

  6. 엔진 종료 경고 (WARNING)


   * 발생 날짜: 2025-06-27, 2025-06-30
   * 로그 메시지:
       * [ warn] [engine] service will shutdown in max 5 seconds
   * 상세 내용:
      로깅 에이전트(Fluent Bit)의 엔진이 최대 5초 내에 종료될 것이라는 경고입니다. 이 로그는 에이전트가 정상적으로 종료되거나 재시작될 때 발생하는 일반적인
   메시지입니다. VM이 종료되거나 에이전트가 업데이트될 때 나타날 수 있습니다.
   * 개선 및 해결 방안:
       * 이 로그는 일반적으로 정상적인 종료 프로세스의 일부이므로, 특별한 조치가 필요하지 않습니다. 다만, 예상치 못한 시점에 에이전트가 자주 종료된다면
         다른 오류 로그와 함께 원인을 분석해야 합니다.


  7. Cloud Run 애플리케이션 오류 (ERROR)


   * 발생 날짜: 2025-06-27
   * 로그 메시지:
       * Traceback (most recent call last): ... File "/layers/google.python.pip/pip/lib/python3.13/site-packages/flask/app.py", ...
       * Traceback (most recent call last): ... File "/layers/google.python.pip/pip/lib/python3.13/site-packages/gunicorn/arbiter.py", ...
       * Container called exit(3).
       * The request failed because either the HTTP response was malformed or connection to the instance had an error.
       * The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
   * 상세 내용:
      vertexai-api-test Cloud Run 서비스에서 발생한 다양한 애플리케이션 수준의 오류입니다.
       * Traceback (Flask/Gunicorn): Python 애플리케이션(Flask) 및 WSGI 서버(Gunicorn) 내부에서 예외가 발생하여 요청 처리가 실패했음을 나타냅니다. 이는
         코드의 버그, 잘못된 의존성, 또는 리소스 부족으로 인한 충돌일 수 있습니다.
       * 컨테이너 비정상 종료 (`Container called exit(3).`): Cloud Run 컨테이너 인스턴스가 비정상적으로 종료되었음을 의미합니다. 이는 애플리케이션 충돌,
         메모리 한도 초과, 또는 컨테이너 런타임 문제 등 심각한 오류로 인해 발생합니다.
       * 잘못된 HTTP 응답 또는 연결 오류: Cloud Run이 컨테이너로부터 유효한 HTTP 응답을 받지 못했거나, 컨테이너와의 연결에 문제가 있었음을 나타냅니다.
         애플리케이션이 응답을 보내기 전에 충돌하거나, 응답 형식이 잘못되었을 때 주로 발생합니다.
       * 인증되지 않은 요청: 인증이 필요한 Cloud Run 서비스에 인증 헤더 없이 요청이 들어왔음을 의미합니다. 이는 서비스의 IAM 권한 설정 문제 또는 클라이언트
         측의 인증 로직 오류로 인해 발생합니다.
   * 개선 및 해결 방안:
       * 애플리케이션 코드 디버깅: Traceback을 분석하여 Flask/Gunicorn 애플리케이션의 버그를 식별하고 수정합니다. 개발 환경에서 재현하여 디버깅 도구를
         활용하는 것이 좋습니다.
       * 리소스 할당 검토: 컨테이너의 CPU 및 메모리 사용량을 모니터링하고, 필요하다면 Cloud Run 서비스의 리소스 할당(CPU, 메모리)을 늘려 리소스 부족으로
         인한 비정상 종료를 방지합니다.
       * 컨테이너 이미지 최적화: 컨테이너 이미지 크기를 줄이고, 불필요한 의존성을 제거하여 시작 시간을 단축하고 리소스 사용량을 최적화합니다.
       * 인증 설정 확인:
           * 서비스가 공개적으로 접근 가능해야 한다면, Cloud Run 서비스의 IAM 권한에서 "모든 사용자(allUsers)"에게 "Cloud Run 호출자(Cloud Run Invoker)"
             역할을 부여합니다.
           * 서비스가 비공개로 유지되어야 한다면, 클라이언트가 요청 시 올바른 인증 토큰(예: ID 토큰)을 Authorization 헤더에 포함하여 보내도록 수정합니다.

  8. 네트워크 구성 오류 (AuditLog - ERROR)


   * 발생 날짜: 2025-06-27
   * 로그 메시지 (해독된 AuditLog):
       * Invalid value for field 'resource.target': ... The Forwarding Rule and the Target Service Attachment must be in different networks.
   * 상세 내용:
      Google Cloud Compute Engine에서 전달 규칙(Forwarding Rule)을 생성하는 API 호출이 실패했습니다. 이 오류는 Private Service Connect(PSC) 구성과 관련이
  있으며, 전달 규칙과 대상 서비스 연결(Service Attachment)이 서로 다른 VPC 네트워크에 있어야 한다는 규칙을 위반했기 때문에 발생했습니다. 즉, 트래픽을
  보내는 소비자 측의 전달 규칙과 서비스를 제공하는 생산자 측의 서비스 연결이 동일한 네트워크에 설정되려고 시도했습니다.
   * 개선 및 해결 방안:
       * 네트워크 설계 검토: Private Service Connect의 네트워크 설계 원칙을 다시 검토합니다. 전달 규칙은 서비스 소비자 VPC에, 서비스 연결은 서비스 생산자
         VPC에 각각 생성되어야 합니다.
       * 올바른 네트워크 지정: 전달 규칙을 생성할 때, 대상 서비스 연결이 위치한 네트워크와 다른 VPC 네트워크를 명시적으로 지정하여 다시 시도합니다.