달빛이 비추는 궁전에서

[GitHub Actions] 온디맨드 Self-Hosted Runner 구축 방안 ( 필요할때만 컴퓨팅 자원 사용)

달빛궁전- — Sun, 26 Jul 2026 23:48:49 +0900

배경 : GitHub Actions의 Self-Hosted Runner를 상시 또는 고정 스케줄(예: 07시 ~ 24시)로 가동하면, 실제 빌드할때만 사용이 되어, 나머지 유휴 시간의 비용이 계속 발생합니다.
물론 낮은사양의 EC2를 켜두거나, AWS EventBridge Scheduler를 사용하여 특정시간에만 동작하는것도 방법입니다. (지난번 포스팅 참조)

이번에는 아예 필요할때만 동작하는 방안에 대해 작성하였습니다.

목적 : 빌드가 있을 때만 러너 머신을 자동으로 기동하고, 잡이 끝나면 스스로 종료되도록 구성하여 유휴 비용을 제거합니다.
본 문서에서는 AWS EC2, GCP GCE, On-Premise 각각의 구축 방안을 정리합니다.

1. 개요

온디맨드 방식은 어떤 플랫폼이든 아래 세 가지 원리로 동작합니다.

켜기 : 꺼진 러너는 자신을 켤 수 없으므로, 러너 외부의 주체가 머신을 기동합니다. 클라우드는 GitHub 호스티드 러너(ubuntu-latest)에서 클라우드 API를 호출하고, On-Premise는 상시 가동 중인 저전력 장비가 Wake-on-LAN을 전송합니다.
큐잉 : runs-on: self-hosted 잡은 러너가 GitHub에 온라인 등록될 때까지 자동으로 큐에서 대기합니다(기본 최대 24시간). 기동 타이밍이 정밀하지 않아도 잡이 유실되지 않으므로, 이것이 온디맨드가 성립하는 핵심 전제입니다.
끄기 : 머신 내부에서 유휴 상태를 감시하다가 일정 시간(예: 15분)이 지나면 스스로 종료합니다. 외부 스케줄러로 끄면 잡 실행 도중 종료될 위험이 있으므로, 잡 프로세스 유무를 직접 확인할 수 있는 머신 내부에서 판단하는 것이 안전합니다.

2. 사전준비 (플랫폼 공통)

러너 머신에는 아래 두 가지를 공통으로 구성합니다.

첫째, 러너를 등록(config.sh)한 뒤 서비스로 설치합니다.

svc.sh로 설치하면 systemd 서비스로 등록되어 부팅 시 자동으로 GitHub에 온라인 등록됩니다.

cd actions-runner
./config.sh --url https://github.com/ORG/REPO --token <등록토큰>
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status    # 상태 확인

둘째, 유휴 감시 스크립트를 크론(5분 주기)으로 등록합니다. 잡 실행 중에는 Runner.Worker 프로세스가 존재한다는 점을 이용합니다.

#!/bin/bash
# /usr/local/bin/runner-idle-check.sh
BUSY_FILE=/var/run/runner-last-busy
if pgrep -f 'Runner.Worker' >/dev/null 2>&1; then
  date +%s > "$BUSY_FILE"; exit 0
fi
[ ! -f "$BUSY_FILE" ] && { date +%s > "$BUSY_FILE"; exit 0; }
NOW=$(date +%s); LAST=$(cat "$BUSY_FILE")
UPTIME=$(awk '{print int($1)}' /proc/uptime)
if [ "$UPTIME" -gt 900 ] && [ $((NOW - LAST)) -gt 900 ]; then
  shutdown -h now      # On-Premise는 systemctl suspend
fi

유의사항 : 부팅 경과 시간(UPTIME) 조건을 함께 확인하는 이유는, 기동 직후 "유휴 15분 경과"로 오판하여 바로 꺼지는 현상을 막기 위함입니다.

워크플로 측에는 깨우는 잡을 재사용 워크플로로 만들어, 모든 셀프호스티드 워크플로의 첫 잡으로 연결합니다.

jobs:
  start-runner:
    uses: ./.github/workflows/runner-start.yml
    secrets: inherit
    permissions:
      id-token: write
      contents: read
  build:
    needs: start-runner
    runs-on: self-hosted
    steps: ...

3. AWS EC2 구성

워크플로 첫 잡이 OIDC로 IAM 롤을 assume하여 EC2를 기동하고, 본 잡은 러너 등록까지 큐에서 대기한 뒤 실행되는 구조입니다.

IAM에 GitHub OIDC 자격 증명 공급자를 등록합니다.

공급자 URL : https://token.actions.githubusercontent.com
Audience   : sts.amazonaws.com

IAM 롤을 생성합니다. 신뢰 정책에는 aud 조건(StringEquals)과 sub 조건이 모두 필요하며, 권한은 ec2:StartInstances, ec2:DescribeInstances로 최소화합니다.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
      "StringLike":   { "token.actions.githubusercontent.com:sub": "repo:ORG/REPO:*" }
    }
  }]
}

깨우는 워크플로(runner-start.yml)를 아래와 같이 작성합니다. configure-aws-credentials는 v6이 현재 권장 버전입니다.

on:
  workflow_call:
permissions:
  id-token: write
  contents: read
env:
  INSTANCE_ID: i-xxxxxxxxxxxxxxxxx
  AWS_REGION: ap-northeast-2
jobs:
  start:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}
      - run: |
          STATE=$(aws ec2 describe-instances --instance-ids "$INSTANCE_ID" \
            --query 'Reservations[0].Instances[0].State.Name' --output text)
          echo "현재 상태: $STATE"
          [ "$STATE" = "running" ] && exit 0
          [ "$STATE" = "stopping" ] && aws ec2 wait instance-stopped --instance-ids "$INSTANCE_ID"
          aws ec2 start-instances --instance-ids "$INSTANCE_ID"
          aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"

EC2 내부에 2장의 공통 구성(러너 서비스 + 유휴 감시 크론)을 설치합니다. Amazon Linux 2023은 cronie가 기본 미설치이므로 dnf install cronie를 먼저 수행합니다.

동작 특성 : 내부 shutdown 시 stopped 상태가 되어 컴퓨팅 과금이 중지되고 EBS 비용만 남습니다. 디스크가 유지되므로 러너 등록 정보, 캐시, 도커 이미지가 보존되며, 콜드 스타트는 30초~1분 수준입니다.

4. GCP GCE 구성

구조는 EC2와 동일하며, 인증(Workload Identity Federation)과 기동 명령이 GCP 방식으로 변경됩니다.

Workload Identity 풀과 GitHub OIDC 프로바이더를 생성합니다. attribute-condition으로 조직(또는 리포지토리)을 반드시 제한합니다.

gcloud iam workload-identity-pools create "github" \
  --project="${PROJECT_ID}" --location="global" \
  --display-name="GitHub Actions Pool"

gcloud iam workload-identity-pools providers create-oidc "my-repo" \
  --project="${PROJECT_ID}" --location="global" \
  --workload-identity-pool="github" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner == '${GITHUB_ORG}'"

서비스 계정을 생성하고 인스턴스 기동 권한을 부여합니다.

gcloud iam service-accounts create runner-starter --project="${PROJECT_ID}"
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:runner-starter@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/compute.instanceAdmin.v1"

유의사항 : 러너 VM에 서비스 계정이 연결되어 있다면, 기동 주체에게 해당 VM 서비스 계정에 대한 roles/iam.serviceAccountUser 권한도 필요합니다.
이 권한이 없으면 instances start가 권한 오류로 실패합니다.
풀의 principalSet이 서비스 계정을 가장(impersonation)할 수 있도록 바인딩합니다. 이 단계가 빠지면 auth 액션 인증이 실패합니다.

WIF_POOL_ID=$(gcloud iam workload-identity-pools describe "github" \
  --project="${PROJECT_ID}" --location="global" --format="value(name)")

gcloud iam service-accounts add-iam-policy-binding \
  "runner-starter@${PROJECT_ID}.iam.gserviceaccount.com" \
  --project="${PROJECT_ID}" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/${WIF_POOL_ID}/attribute.repository/ORG/REPO"

깨우는 워크플로는 아래와 같습니다. auth 액션은 v3이 현재 버전이며, 잡에 id-token: write 권한이 필요합니다.

jobs:
  start:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: projects/<PROJECT_NUM>/locations/global/workloadIdentityPools/github/providers/my-repo
          service_account: runner-starter@<PROJECT_ID>.iam.gserviceaccount.com
      - uses: google-github-actions/setup-gcloud@v3
      - run: gcloud compute instances start RUNNER_VM --zone=asia-northeast3-a

GCE 내부 구성은 EC2와 동일합니다(러너 서비스 + 유휴 감시 크론).

동작 특성 : GCE는 게스트 내부 shutdown 시 TERMINATED 상태가 되며, 이 상태에서는 CPU/메모리 과금이 없고 디스크와 외부 IP 등 연결 리소스만 과금됩니다. gcloud compute instances start로 재기동이 가능합니다.

5. On-Premise 구성

클라우드 API가 없으므로 꺼진 서버를 깨울 주체가 필요합니다. 상시 가동 중인 저전력 장비(라즈베리파이, NAS )가 깨우기를 전담하고, 빌드 서버는 평소 절전 상태로 두는 2계층 구성을 사용합니다.빌드 서버의 BIOS와 NIC에서 Wake-on-LAN을 활성화합니다.
ethtool 설정은 재부팅 시 초기화되므로 systemd 유닛 등으로 부팅 시마다 적용합니다.

sudo ethtool -s eth0 wol g

소형 에이전트에 러너를 wake-agent 라벨로 등록하고, 깨우기 잡만 전담시킵니다.

jobs:
  wake:
    runs-on: [self-hosted, wake-agent]
    steps:
      - run: wakeonlan AA:BB:CC:DD:EE:FF
  build:
    needs: wake
    runs-on: [self-hosted, build]

빌드 서버에 러너를 build 라벨로 등록하고, 공통 구성을 설치합니다. 종료 명령은 systemctl suspend로 변경합니다.
suspend 상태가 WoL 재기동이 가장 확실하며, poweroff에서의 WoL 동작은 메인보드에 따라 다르기 때문입니다.

유의사항 : 서버 유휴 전력이 미미한 경우(미니PC 등)라면 온디맨드 구성 없이 러너를 상시 두는 편이 단순합니다. 온디맨드가 유효한 경우는 고전력 워크스테이션이나 GPU 서버처럼 유휴 전기요금이 실질적인 경우입니다.

사실 저도 테스트때문에 해본거고, 온프레미스는 그냥 켜두는게 나은방향 같습니다.. 일단 WOL이 하드웨어를 좀 타기 때문에 ㅠ

6. 운영 시 유의사항

기동과 종료의 레이스 : 깨우는 잡이 "이미 running"으로 판단하고 넘어간 직후 유휴 크론이 종료해 버리면, 셀프호스티드 잡이 큐에 계속 대기할 수 있습니다.
잡이 오래 queued 상태라면 깨우는 워크플로를 수동 재실행하면 됩니다.
start-instances는 이미 실행 중이어도 오류 없이 동작(멱등)하므로, 상태 확인 없이 항상 호출하는 방식으로 단순화해도 됩니다.
GitHub OIDC 토큰은 수명이 짧으므로(파생 자격증명 포함) 깨우는 잡은 기동 확인까지만 담당하고 길게 대기하지 않도록 합니다.
러너 머신을 교체하면 워크플로에 기록한 인스턴스 ID(또는 MAC 주소)를 갱신해야 합니다.

8. 정리

구분	AWS EC2	GCP GCE	On-Premise
깨우는 주체	GitHub 호스티드 잡 + OIDC IAM 롤	GitHub 호스티드 잡 + WIF 서비스 계정	상시 소형 에이전트 (경량 러너)
인증	configure-aws-credentials@v6	google-github-actions/auth@v3	불필요 (사내망)
기동 명령	aws ec2 start-instances	gcloud compute instances start	Wake-on-LAN 매직 패킷
종료 방법	내부 유휴 크론 -> shutdown	내부 유휴 크론 -> shutdown	내부 유휴 크론 -> suspend
정지 상태	stopped (EBS만 과금)	TERMINATED (디스크/IP만 과금)	절전 (대기 전력)
콜드 스타트	약 30초~1분	약 30초~1분	수십 초 (suspend 복귀는 수 초)

AWS, GCP는 클라우드상에서 동작이기 때문에 인증차이만 있습니다.

Docker Homepage으로 나만의 서비스 대시보드 구성하기

달빛궁전- — Tue, 21 Jul 2026 16:21:14 +0900

여러 서버와 사이드 프로젝트의 접속 주소를 한곳에서 관리하기 위해 Homepage를 Docker로 설치하고, Nginx Reverse Proxy와 Basic Authentication을 적용하여 외부에서도 안전하게 접근할 수 있도록 구성하였습니다.

홈 서버와 개인 프로젝트를 운영하다 보면 접속해야 할 주소가 계속 늘어납니다.

Portainer, Grafana, Proxmox VE 같은 인프라 관리 도구부터 Home Assistant, Synology NAS, n8n, Jupyter Notebook, 직접 만든 사이드 프로젝트까지 각각의 URL을 기억하거나 브라우저 즐겨찾기에서 찾는 것이 점점 불편해졌습니다.

이를 한 화면에 정리하기 위해 오픈소스 애플리케이션 대시보드인 Homepage를 설치하였습니다.

구성한 대시보드 주소:
https://home.seonggi.kr/

현재는 개인 관리 서비스가 포함되어 있어 Nginx Basic Authentication을 적용하였습니다.

Homepage란?

Homepage는 Docker와 다양한 서비스 API 연동을 지원하는 오픈소스 애플리케이션 대시보드입니다.

YAML 파일만으로 서비스, 북마크, 위젯, 레이아웃을 설정할 수 있고 다음과 같은 기능을 제공합니다.

Docker 컨테이너 상태 및 리소스 확인
100개 이상의 서비스 위젯 연동
날짜, 시간, 날씨, 검색 등의 정보 위젯
서비스와 웹 북마크 그룹화
테마, 색상, 레이아웃, Custom CSS/JS 설정
AMD64, ARM64 아키텍처 지원

공식 Docker 이미지:
https://hub.docker.com/r/gethomepage/homepage

gethomepage/homepage - Docker Image

A modern, fully static, fast, secure fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery. Homepage bui

hub.docker.com

공식 문서:
https://gethomepage.dev/

Home - Homepage

gethomepage.dev

구성 목표

이번 구성의 목표는 다음과 같습니다.

여러 서비스의 URL을 역할별로 한 화면에 정리
Docker Compose로 간단하게 배포 및 재시작
로컬 시스템의 CPU, 메모리, 디스크 사용량 표시
home.seonggi.kr 도메인으로 외부 접속
외부 노출 시 인증 없이 관리 화면이 공개되지 않도록 보호

전체 흐름은 아래와 같습니다.

디렉터리 구성

Homepage 자체에는 사용자 인증 기능이 없습니다. 따라서 인터넷에서 접근할 수 있게 구성할 경우 Reverse Proxy 또는 VPN에서 인증, TLS, Host Header 검증을 적용해야 합니다.

디렉터리 구성

homepage-docker
- docker-compose.yml
- nginx.conf
- .htpasswd
- config
  - settings.yaml
  - services.yaml
  - widgets.yaml
  - bookmarks.yaml
  - docker.yaml
  - custom.css
  - custom.js

설정 파일은 컨테이너 외부에 두어 이미지를 업데이트하거나 컨테이너를 다시 생성해도 그대로 유지되도록 구성하였습니다.

Docker Compose 설정

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      # CHANGE_ME: 실제 접속할 도메인과 로컬 포트를 입력
      - HOMEPAGE_ALLOWED_HOSTS=localhost,localhost:7799,127.0.0.1:7799,home.example.com,homepage
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # CHANGE_ME: 리소스 위젯에서 확인할 호스트 경로
      # macOS 예시: /Users/myname:/host:ro
      # Linux 예시: /:/host:ro
      - /Users/CHANGE_ME:/host:ro
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    container_name: homepage-auth
    ports:
      # CHANGE_ME: 7799를 이미 사용 중이라면 다른 포트로 변경
      - "7799:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./.htpasswd:/etc/nginx/.htpasswd:ro
    depends_on:
      - homepage
    restart: unless-stopped

위 예제에서 사용자가 변경해야 하는 값은 다음과 같습니다.

home.example.com: Homepage에 사용할 실제 도메인
7799: 호스트에서 사용할 포트. 다른 서비스와 중복되면 변경
/Users/CHANGE_ME: 리소스 사용량을 확인할 호스트 경로
container_name: 기존 컨테이너 이름과 중복되지 않도록 필요 시 변경
./config: Homepage YAML 설정 파일을 저장할 로컬 디렉터리

도메인을 사용하지 않고 내부에서만 접속한다면 HOMEPAGE_ALLOWED_HOSTS에 실제로 사용하는 IP와 포트를 입력합니다.

environment:
  # 내부 IP가 192.168.0.10인 경우
  - HOMEPAGE_ALLOWED_HOSTS=192.168.0.10,192.168.0.10:7799,localhost:7799,homepage

Homepage의 3000번 포트를 호스트에 직접 공개하지 않고, Nginx 컨테이너를 통해서만 접근하도록 하였습니다.

/var/run/docker.sock은 Docker 연동에 필요하며 읽기 전용(:ro)으로 마운트하였습니다. 호스트 디스크 사용량을 표시하기 위한 경로도 읽기 전용으로 연결하였습니다.

Docker Socket은 Docker 데몬에 접근할 수 있는 민감한 리소스입니다. 필요한 경우에만 마운트하고, 외부에 공개되는 서비스와 권한 범위를 최소화하는 것이 좋습니다.

Nginx Basic Authentication 설정

Homepage는 자체 로그인 기능을 제공하지 않으므로 Nginx에서 Basic Authentication을 적용하였습니다.

server {
    listen 80;
    server_name localhost;

    location / {
        auth_basic "Dashboard Login Required";
        auth_basic_user_file /etc/nginx/.htpasswd;

        proxy_pass http://homepage:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

인증 파일은 htpasswd 명령으로 생성합니다.

htpasswd -c .htpasswd CHANGE_ME_USERNAME

CHANGE_ME_USERNAME에는 대시보드에 로그인할 사용자명을 입력합니다. 명령 실행 후 표시되는 프롬프트에서 비밀번호를 입력하면 됩니다.

비밀번호는 Compose 파일이나 Nginx 설정에 직접 기록하지 않고 .htpasswd 파일로 분리하였습니다. 해당 파일은 Git 저장소에 업로드하지 않도록 .gitignore에도 추가하는 것이 좋습니다.

Homepage 기본 설정

config/settings.yaml에서 제목과 테마를 설정합니다.

title: CHANGE_ME_DASHBOARD_TITLE  # 화면 상단에 표시할 제목
theme: dark
color: zinc
cardBlur: sm

어두운 테마와 zinc 색상을 사용하여 서비스 카드가 한눈에 들어오도록 구성하였습니다.
실제 구성 화면은 아래와 같습니다.

서비스 그룹 구성

config/services.yaml에서 접속할 서비스를 역할별로 분류하였습니다.

로컬 웹 서비스: 직접 만든 웹 서비스와 사이드 프로젝트
개발 및 자동화: n8n, AI Migration, Jupyter Notebook 등
시스템 관리 및 모니터링: Portainer, Grafana, Proxmox VE, Nginx Proxy Manager, Netdata 등
네트워크 및 홈 서버: Synology NAS, Home Assistant, Router Web 등

설정 형식은 아래와 같습니다.

- 시스템 관리 및 모니터링:
    - Portainer:
        icon: portainer
        href: https://CHANGE_ME_PORTAINER_URL
        description: 컨테이너 관리
    - Proxmox VE:
        icon: proxmox
        href: https://CHANGE_ME_PROXMOX_URL
        description: 가상화 시스템 하이퍼바이저

href에는 각 사용자가 운영하는 서비스의 실제 URL을 입력합니다. 공개 도메인이 없다면 http://192.168.0.10:9000과 같은 내부 IP 주소도 사용할 수 있습니다.

서비스 아이콘은 Homepage에서 지원하는 이름을 사용합니다. 아이콘을 찾을 수 없으면 우선 icon 항목을 생략하고 정상적으로 카드가 표시되는지 확인하는 것이 좋습니다.

서비스를 그룹으로 나누니 즐겨찾기 목록보다 찾기 쉽고, 새 서비스가 추가되어도 YAML 항목 하나만 추가하면 됩니다.

시스템 리소스 위젯 설정

날짜와 시간, 호스트의 CPU, 메모리, 디스크 사용량을 상단에서 확인하도록 설정하였습니다.

- datetime:
    format:
      dateStyle: short
      timeStyle: short
    hourCycle: h23

- resources:
    cpu: true
    memory: true
    disk: /host  # Compose에서 마운트한 컨테이너 내부 경로
    expanded: true

호스트 디스크는 Compose에서 호스트 경로:/host:ro로 연결한 경로를 기준으로 표시합니다. disk에는 호스트의 원래 경로가 아니라 컨테이너 내부 마운트 경로인 /host를 입력합니다.

실행

설정 파일을 작성한 후 다음 명령으로 실행합니다.

docker compose up -d

컨테이너 상태와 로그를 확인합니다.

docker compose ps
docker compose logs -f homepage
docker compose logs -f nginx

로컬에서는 아래 주소로 접속합니다.

http://localhost:7799

외부 Reverse Proxy에서는 home.seonggi.kr 요청을 이 주소로 전달하고 HTTPS 인증서를 적용하였습니다.

사용자 환경에서는 아래 항목을 자신의 값으로 설정하면 됩니다.

도메인: home.example.com → 실제 사용할 도메인
Forward Host 또는 IP: Homepage를 설치한 서버의 IP
Forward Port: Compose에서 Nginx에 연결한 포트. 예제에서는 7799
SSL: 실제 도메인 인증서 적용
WebSocket: 사용하는 Reverse Proxy 제품에서 지원한다면 활성화

설치 중 발생한 문제

Host validation failed

외부 도메인과 로컬 포트로 접속하는 과정에서 다음 오류가 발생하였습니다.

Host validation failed for: home.seonggi.kr
Hint: Set the HOMEPAGE_ALLOWED_HOSTS environment variable to allow requests from this host / port.

Homepage는 허용되지 않은 Host Header 요청을 차단합니다. Compose의 HOMEPAGE_ALLOWED_HOSTS에 실제 접속에 사용하는 호스트와 포트를 추가하여 해결하였습니다.

environment:
  - HOMEPAGE_ALLOWED_HOSTS=localhost,localhost:7799,127.0.0.1,127.0.0.1:7799,home.seonggi.kr,homepage

설정 변경 후 컨테이너를 다시 생성합니다.

docker compose up -d --force-recreate

HOMEPAGE_ALLOWED_HOSTS는 인증 기능이 아니라 Host Header 검증 기능입니다. 외부 접근 보호를 위해서는 별도로 Basic Authentication, SSO 또는 VPN을 구성해야 합니다.

보안 구성 시 확인할 점

Homepage의 3000번 포트를 외부에 직접 공개하지 않음
Reverse Proxy에서 HTTPS 적용
Nginx Basic Authentication 또는 별도의 SSO 적용
실제 사용하는 도메인만 HOMEPAGE_ALLOWED_HOSTS에 등록
Docker Socket과 호스트 볼륨은 읽기 전용으로 마운트
.htpasswd와 API Key가 포함된 설정 파일은 Git에 업로드하지 않음
관리자 서비스 URL이 노출되는 범위를 최소화

현재 https://home.seonggi.kr/에 인증 없이 접근하면 401 Authorization Required가 반환되는 것을 확인할 수 있습니다.

정리

서비스가 몇 개 없을 때는 브라우저 즐겨찾기만으로도 충분했지만, 홈 서버와 사이드 프로젝트가 늘어나면서 하나의 시작 화면이 필요해졌습니다.

Homepage를 사용하면 YAML 파일만으로 서비스 주소를 역할별로 정리할 수 있고, Docker 및 시스템 리소스 정보도 함께 확인할 수 있습니다. Docker Compose로 구성하여 업데이트와 재배포도 단순해졌습니다.

다만 Homepage 자체에는 인증 기능이 없으므로 외부에서 접근하도록 구성할 때는 Reverse Proxy의 HTTPS와 인증 설정을 반드시 함께 적용해야 합니다.

앞으로 서비스 상태 위젯과 API 연동을 추가하여 단순한 링크 모음이 아니라 홈랩 전체의 상태를 한눈에 확인할 수 있는 대시보드로 확장해볼 예정입니다.

참고

Homepage Docker Hub: https://hub.docker.com/r/gethomepage/homepage
Homepage 공식 문서: https://gethomepage.dev/
구성한 대시보드: https://home.seonggi.kr/

Web SSH Portal

달빛궁전- — Wed, 15 Jul 2026 01:03:02 +0900

사이드 프로젝트로 SSH 웹 포털을 만들었습니다.

홈서버와 클라우드 서버, 도커가 점점 늘어나면서, 매번 터미널 앱 켜고 접속 정보 찾는 게 귀찮아 졌습니다.

정확히는 한차례의 소동때문이었는데, 테슬라메이트 잘 쓰다가, 갑자기 안되어서 보니 업데이트로 방식이 바뀌었고 3주나 데이터를 못받았습니다.

그래서 접속정보를 찾는데, 한서버가 뚫리면 다 뚫리는걸 방지 한다고 서버마다 id, password를 다르게 했고, 키파일은 또 데스크탑에다가만 넣는데, 지금 육아때문에 데탑을 저기 저 구석에 넣어놓은지라 접속하는데 한 세월이 걸렸네요 ㅠㅠ

그래서 브라우저에서 바로 SSH 접속할 수 있는 걸 만들기로 했습니다.
Antigravity를 사용하여 개발을 진행했습니다.

동작화면은 아래와 같습니다.

메인화면

서버 리스트 확인

서버접속 화면

기술 스택은 Node.js + WebSocket으로 SSH 프록시를 만들고, xterm.js로 터미널 에뮬레이터를 붙였습니다.

Docker 로 사용가능합니다.

주요 기능

서버를 등록해 두고 클릭 한 번으로 웹 터미널 접속
서버 그룹화 + 접기/펴기로 여러 대도 정리해서 관리
IP만 넣으면 SSH 배너 분석 후 자동 접속해서 CPU, 메모리, 디스크, OS 정보를 긁어옴
PBKDF2 SHA-512 해시 + HttpOnly 쿠키 기반 로그인
모바일 반응형 + PWA 지원 (홈 화면에 앱으로 설치 가능)

기획하고 실제 서버 환경에서 테스트 하면서 만들었는데, 처음엔 간단하게 시작했는데 쓰다 보니 자꾸 추가하고 싶은 게 생기더라고요.

보안 로그인, 모바일 대응, 시스템 정보 수집, Docker 단일 배포... 하다 보니 꽤 커졌습니다.

Docker만 있으면 바로 쓸 수 있습니다.
아래 Github에서 다운 및 설치가 가능합니다.

https://github.com/SeongGi/web-ssh

GitHub - SeongGi/web-ssh

Contribute to SeongGi/web-ssh development by creating an account on GitHub.

github.com

[일상 기록] 2026년, 아빠가 되었고 개발자가 되었습니다.

달빛궁전- — Tue, 14 Jul 2026 11:54:28 +0900

벌써 한 해의 절반이 지났습니다. 지난 반년은 제 인생에서 가장 스펙터클하고 많은 변화가 있었던 시기로 기억될 것 같습니다. 오랜만에 블로그에 생존 신고 겸 근황을 남겨봅니다.

기적처럼 찾아온 선물

가장 큰 변화는 저희 가족에게 새 생명이 찾아왔다는 것입니다. 40줄을 훅 넘긴 나이, 용희와 저 둘이서 거의 3년을 노력해도 안 되어서 '작년 말까지 해보고 소식 없으면 그냥 우리 둘이서 재밌게 살자'고 마음먹었었죠.

그런데 정말 기적처럼 타이밍을 맞춰 작년 11월에 임신 소식을 알게 되었고, 지난 6월 중순에 무사히 출산을 마쳤습니다. 요즘은 육아용품을 사느라 평소 자주 가던 커뮤니티의 핫딜 게시판을 문지방이 닳도록 드나들며 도움을 톡톡히 받고 있네요. 육아가 몸은 참 힘들지만, 아기가 집에 있으니 양가 어른들 얼굴에도 모두 웃음꽃이 피어납니다. 정말 행복합니다.

(물론... 천사처럼 곤히 자는 모습을 볼 때가 제일 행복하긴 합니다 ㅋㅋㅋㅋ)

17년 차 인프라 엔지니어, 개발자로 전향하다

그리고 그 반년 사이에 커리어에도 큰 전환점이 있었습니다. 17년 동안 몸담았던 IT 인프라 엔지니어라는 직함을 내려놓고, 개발자로 전향하게 되었습니다. 아 인프라도 하고 개발도 하는거죠

처음엔 AI나 Next.js, Docker 등을 활용해서 사이드 프로젝트로 가볍게 만지작거리던 것이 시작이었습니다. 그러다 회사와 조율이 잘 되어 아예 전체 개발을 맡아보기로 했죠. 사실 제가 모든 코드를 다 꿰뚫고 있는 것도 아닌데 이렇게 하는 게 맞나 싶어 매일 고민의 연속이지만, 새로운 걸 배우는 재미가 아주 쏠쏠해서 무척 만족하고 있습니다.

IT 인프라 업계 특성상 늘 '을, 병, 정'으로 사람에게 치이는 일이 많아 피로감이 컸는데, 사람들과 조금 떨어져서 코드에 집중하니 업무 만족도가 훨씬 높아졌습니다. 예전에 어느 커뮤니티에서 봤던 '사람이 싫다 필터'가 딱 제 심정이 아니었나 싶습니다.

현실은 육아 하드코어 모드

회사에는 "일과 육아, 두 마리 토끼를 다 잡겠습니다!"라고 호기롭게 외치며 육아휴직 대신 진행해보기로 했는데 지난달의 제 자신을 찾아가 멱살이라도 잡고 싶을 만큼 하루하루가 눈코 뜰 새 없이 굴러가고 있습니다. 왜 그랬을까요 ㅠㅠ

육아템들의 도움을 받아가며, 코딩과 팩폭 육아의 콜라보 속에서 어떻게든 든든하게 해내고 있습니다. 몸은 고되지만 인생의 새로운 챕터를 열어가는 기분이라 벅차고 참 기분이 요묘합니다.

혹시라도 아기를 기다리시는 분들이 계신다면 좋은 기운 듬뿍 받아가시길 바라며, 제 블로그에 오시는 분들 모두 오늘 하루도 꽉 차게 행복하시길 바랍니다!

Github Runner - EC2 Self-Hosted Runner 설정

달빛궁전- — Tue, 30 Jun 2026 16:50:18 +0900

개요
GitHub Actions는 무료 플랜 기준 월 2,000분의 러너 실행 시간을 제공합니다. 최근 AI 활용을 비롯한 빌드 파이프라인 사용량 증가로 인해 제공량이 조기 소진됨에 따라, 유료 플랜 전환 대신 비용 효율적인 대안으로 AWS EC2 기반의 Self-Hosted Runner를 구축하고자 합니다.

본 문서에서는 AWS EC2를 GitHub Actions Runner로 등록하여 빌드 및 컴파일 작업을 EC2 인프라에서 처리하는 방법을 다룹니다. 특히 인프라 운영 비용을 최소화하기 위해 아래 두 가지 방안을 비교 및 정리했습니다.

AWS EC2 온디맨드(On-Demand) 인스턴스를 활용한 기본 구성
AWS EC2 스팟(Spot) 인스턴스 + AWS EventBridge Scheduler 조합을 통해 업무 시간대에만 인스턴스를 운영하는 비용 최적화 구성

Step 1: 기존 VPC 및 Public Subnet ID 조회하기

새로 만드는 것이 아니라 기존 VPC의 서브넷을 사용해야 하므로, 먼저 현재 리전에 있는 서브넷 목록을 조회하여 ID를 확인

1. 서브넷 목록 및 정보 조회

아래 명령어를 실행하면 해당 리전의 모든 서브넷 ID, CIDR 블록, 그리고 퍼블릭 IP 자동 할당 여부(MapPublicIpOnLaunch)가 표 형태로 출력

aws ec2 describe-subnets \
  --region ap-northeast-2 \
  --query "Subnets[*].[SubnetId, VpcId, CidrBlock, MapPublicIpOnLaunch, Tags[?Key=='Name'].Value | [0]]" \
  --output table

- **확인할 부분:** 출력된 표에서 `True` 표시가 있거나 이전에 생성해 둔 Public Subnet의 `subnet-xxxxxxxxxxxxxxxxx` (SubnetId)와 `vpc-xxxxxxxxxxxxxxxxx` (VpcId)를 기록
- _여기서 얻은 VpcId는 다음 단계의 보안 그룹 생성에 사용_

Step 2: Key Pair (키 페어) 생성하기

EC2에 접속할 때 사용할 인증 키 파일(ra-portal-runner-key.pem)을 로컬 PC에 생성하고 다운로드합니다.

# 1. 키 페어 생성 및 파일 저장
aws ec2 create-key-pair \
  --key-name ra-portal-runner-key \
  --region ap-northeast-2 \
  --query 'KeyMaterial' \
  --output text > ra-portal-runner-key.pem

# 2. 키 파일 권한 변경 (Mac/Linux 환경 필수)
chmod 400 ra-portal-runner-key.pem

결과물 (<your-key-pair>): ra-portal-runner-key

Step 3: Security Group (보안 그룹) 생성 및 규칙 설정

인스턴스에 적용할 방화벽인 보안 그룹을 생성합니다. 단계 1에서 확인한 VPC ID를 <vpc-id> 자리에 입력하세요.

1. 보안 그룹 생성

aws ec2 create-security-group \
  --group-name ra-portal-runner-sg \
  --description "Security group for GitHub Runner" \
  --vpc-id <단계1에서-확인한-vpc-id> \
  --region ap-northeast-2 \
  --query 'GroupId' \
  --output text

위 명령어를 실행하면 sg-xxxxxxxxxxxxxxxxx 형태의 보안 그룹 ID가 화면에 출력됩니다. 이를 메모합니다.

aws ec2 create-security-group \
  --group-name ra-portal-runner-sg \
  --description "Security group for GitHub Runner" \
  --vpc-id vpc-0deea1bdec4f02c3f \
  --region ap-northeast-2 \
  --query 'GroupId' \
  --output text

2. 인바운드 규칙 추가 (SSH 22번 포트 허용)

인스턴스 관리를 위해 내 IP 또는 전체 IP(0.0.0.0/0)로부터의 SSH 접속을 허용합니다. (방금 얻은 sg- ID를 입력)

aws ec2 authorize-security-group-ingress \
  --group-id <방금-생성된-sg-id> \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0 \
  --region ap-northeast-2

aws ec2 authorize-security-group-ingress \
  --group-id sg-0d4fd499ccf5ed14c \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0 \
  --region ap-northeast-2

참고: GitHub Runner는 기본적으로 아웃바운드(성공 시 외부로 나가는 통신) 기반으로 동작하므로, 단순 러너 구동이 목적이고 웹서버 등의 외부 접속이 필요 없다면 보안을 위해 22번 포트 조차 열지 않거나 본인의 공인 IP만 지정하는 것이 안전합니다.

EC2 생성 명령어

위 단계들에서 수집한 값을 매핑한 최종 구동 스크립트 형태입니다. 대괄호 토큰들을 실제 값으로 바꾸어 실행

일반 VM

aws ec2 run-instances \
  --image-id [AMI_ID] \
  --instance-type t3.small \
  --key-name [KEY_PAIR_NAME] \
  --security-group-ids [SECURITY_GROUP_ID] \
  --subnet-id [SUBNET_ID] \
  --associate-public-ip-address \
  --block-device-mappings '[{"DeviceName":"/dev/xvda","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=[INSTANCE_NAME]}]' \
  --region [REGION_NAME]

스팟(Spot) VM

aws ec2 run-instances \
  --image-id [AMI_ID] \
  --instance-type t3.small \
  --key-name [KEY_PAIR_NAME] \
  --subnet-id [SUBNET_ID] \
  --security-group-ids [SECURITY_GROUP_ID] \
  --associate-public-ip-address \
  --instance-market-options '{"MarketType":"spot","SpotOptions":{"SpotInstanceType":"persistent","InstanceInterruptionBehavior":"stop"}}' \
  --block-device-mappings '[{"DeviceName":"/dev/xvda","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=[INSTANCE_NAME]}]' \
  --query "Instances[0].InstanceId" \
  --output text \
  --region [REGION_NAME]

또는 AWS Console에서 수동 생성이 편하면:

설정	값
AMI	Ubuntu 22.04 LTS (amd64)
Instance type	t3.small
VPC	기존 ra-portal VPC
Subnet	Public subnet (인터넷 접근 필요)
Public IP	자동 할당
Storage	30GB gp3
Security Group	outbound 전부 허용, inbound SSH만 (22)
Key pair	기존 것 또는 새로 생성
Name tag	`"원하는 name tag"`

Step 4: EC2에 SSH 접속 후 환경 세팅

ssh -i <your-key.pem> ec2-user@<ec2-public-ip>

1. Docker 설치

sudo dnf install -y docker
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker ec2-user

2. Node.js 20

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs
node --version

3. Python 3.12

sudo dnf install -y python3 pip
python3 --version

4. Terraform 1.10.0

sudo dnf install -y unzip wget
wget https://releases.hashicorp.com/terraform/1.10.0/terraform_1.10.0_linux_amd64.zip
unzip terraform_1.10.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/
rm terraform_1.10.0_linux_amd64.zip
terraform --version

5. jq + git

sudo dnf install -y jq git

6. uv (AgentCore용)

curl -LsSf https://astral.sh/uv/install.sh | sh

7. Docker 그룹 반영

sudo usermod -aG docker ec2-user
newgrp docker
docker ps

Step 3: GitHub Actions Runner 설치 & 등록

# runner 전용 디렉토리
mkdir ~/actions-runner && cd ~/actions-runner

# libicu 패키지 설치
sudo dnf install -y libicu

# 최신 runner 다운로드 (x64 Linux)
curl -o actions-runner-linux-x64-2.323.0.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.323.0/actions-runner-linux-x64-2.323.0.tar.gz
tar xzf ./actions-runner-linux-x64-2.323.0.tar.gz

# GitHub에서 토큰 발급 후 등록
# GitHub repo → Settings → Actions → Runners → New self-hosted runner에서 토큰 복사
캡쳐화면에 있는 Configure 복사

# systemd 서비스로 등록 (재부팅 시 자동 시작)
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

Step 4: Workflow 파일 수정

모든 workflow에서 runs-on: ubuntu-latest → runs-on: self-hosted로 변경

Step 5: AWS EventBridge Scheduler 등록

07시 On, 12시 Off 스케줄

# 1. IAM Role 생성
aws iam create-role \
  --role-name [PROJECT_NAME]-runner-scheduler-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "scheduler.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# 2. IAM Policy 추가
aws iam put-role-policy \
  --role-name [PROJECT_NAME]-runner-scheduler-role \
  --policy-name [PROJECT_NAME]-ec2-startstop \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["ec2:StartInstances", "ec2:StopInstances"],
      "Resource": "arn:aws:ec2:ap-northeast-2:[AWS_ACCOUNT_ID]:instance/[EC2_INSTANCE_ID]"
    }]
  }'

# 3. 계정 ID로 Role ARN 확인
ROLE_ARN="arn:aws:iam::[AWS_ACCOUNT_ID]:role/[PROJECT_NAME]-runner-scheduler-role"

# 4. 스케줄 생성 — 07:00 KST Start
aws scheduler create-schedule \
  --name [PROJECT_NAME]-runner-start \
  --schedule-expression "cron(0 7 * * ? *)" \
  --schedule-expression-timezone "Asia/Seoul" \
  --flexible-time-window '{"Mode": "OFF"}' \
  --target "{
    \"Arn\": \"arn:aws:scheduler:::aws-sdk:ec2:startInstances\",
    \"RoleArn\": \"$ROLE_ARN\",
    \"Input\": \"{\\\"InstanceIds\\\": [\\\"[EC2_INSTANCE_ID]\\\"]}\"
  }" \
  --region ap-northeast-2

# 5. 스케줄 생성 — 00:00 KST Stop (자정)
aws scheduler create-schedule \
  --name [PROJECT_NAME]-runner-stop \
  --schedule-expression "cron(0 0 * * ? *)" \
  --schedule-expression-timezone "Asia/Seoul" \
  --flexible-time-window '{"Mode": "OFF"}' \
  --target "{
    \"Arn\": \"arn:aws:scheduler:::aws-sdk:ec2:stopInstances\",
    \"RoleArn\": \"$ROLE_ARN\",
    \"Input\": \"{\\\"InstanceIds\\\": [\\\"[EC2_INSTANCE_ID]\\\"]}\"
  }" \
  --region ap-northeast-2

추가: 보안 고려사항

항목	대응
IAM 권한	EC2에 IAM Instance Profile 부여 (기존 `github-deploy-role`과 동일 권한) → OIDC 대신 Instance Profile 사용 가능
Security Group	Inbound: SSH(22)만. Outbound: 전체 허용 (GitHub API, ECR, etc.)
GitHub Secrets	Self-hosted runner에서도 `${{ secrets.* }}` 그대로 사용 가능
OIDC 인증	Self-hosted runner에서도 OIDC 동작함. 또는 Instance Profile로 대체 가능

GCP Landing Zone Advisor

달빛궁전- — Thu, 18 Jun 2026 09:00:21 +0900

GCP, AWS, Azure를 비롯한 모든 클라우드에서는 Landing Zone 구성을 권고합니다.
사실 권고라기보다는 클라우드를 제대로 쓰기 위해 필수로 해야 하는 기본 작업에 가깝습니다.
벤더마다 개념이나 구현 방안은 조금씩 다르지만, 처음 클라우드를 시작하는 기업들에게 안정적인 초기 환경을 구축한다는 목표는 같습니다.

이러한 GCP 랜딩존 지침을 참고하여, 아키텍처 설계를 가이드해 주는 Landing Zone Advisor 웹을 만들어 보았습니다.

https://gcp-check.seonggi.kr/

GCP Landing Zone Advisor

gcp-check.seonggi.kr

이 서비스는 다음과 같은 방식으로 동작합니다.

- GCP 권고 가이드와 실무에서 필요한 요구사항을 결합했습니다.
- 국내외 보안 컴플라이언스(ISMS-P, PIPA, HIPAA 등) 기준도 반영합니다.
- LLM의 도움을 받아 최적의 설계 방안을 추천해 줍니다.
- draw 스타일의 아키텍처 구성도 예시도 함께 생성합니다.
- (물론 실서비스 구성도 수준의 디테일은 더 채워나가야 합니다 ^^;;;)

GCP를 처음 도입하거나 설계를 점검하고 싶을 때 상황을 입력해 도움을 받을 수 있습니다.
개인 API 키로 제공하다 보니 한도가 금방 초과되어, 각자 Google AI Studio에서 무료로 발급받은 API 키를 입력해 테스트해 보실 수 있도록 구성했습니다. (Gmail 계정만 있으면 즉시 발급 가능합니다.)

화면 오른쪽 상단에는 참고용 RAG(검색 증강 생성) 링크 설정 기능도 마련해 두었습니다.
참고할 문서 URL이나 구체적인 요구사항을 텍스트로 넣어주면 해당 내용을 반영해 답변해 줍니다.

네트워크 구성도

편하게 의견 남겨주세요.

GCP Agent Runtime (Agent Engine) - PSC to PSC-Interface을 통한 연결 방안

달빛궁전- — Tue, 12 May 2026 08:00:04 +0900

목표
On-premise에서 VPN, Interconnect를 통하여 private망을 통해 접근 후 PSC를 통해 GCP Agent Engine과 연동합니다.
그 이후 Agent Engine은 VPN을 통해 외부에 있는 MCP Server와 연동하여 응답을 제공할 수 있는 아키텍처 설명과 실행 방안에 대해 작성합니다.

3가지로 구분되어 진행됨
- 실행하는 단말기 설정
- GCP 설정
PSC network-attachment 설정
Agent Engine 설정 VPN 설정 - MCP Server와 통신하여 처리 VPN, PSC를 제외하고는 대부분 Python코드로 진행되어야함

전체 구성도

FAQ
- Agent Engine 서브넷 관련 Docs
- PSC-Interface 생성방안 Docs

On-premise 요청하는 사용자 설정- /etc/hosts 수정하거나, On-premise DNS에서 수정필요
인증 (oauth2), AI부분에 대해 PSC로 요청하도록 DNS 수정

100.100.100.254 asia-northeast3-aiplatform.googleapis.com
100.100.100.254 oauth2.googleapis.com

- GCP Login
테스트 방안시에는 GCP의 ADC 사용
gcloud auth application-default login

테스트 이후 실 사용시에는 sa key(json)이나 GCP Workload Identity Federation (WIF) 사용

2. Agent Engine을 배포할 단말기 설정

GCP Login
gcloud auth application-default login
GCE사용시에는 모든 API or Vertex AI API 설정
Python 가상환경 설정
python3 -m venv .venv
source .venv/bin/activate

- Vertex AI SDK 설치
pip install google-cloud-aiplatform
pip install python-dotenv
pip install "google-cloud-aiplatform[agent_engines]"

3. 네트워크 작업

서브넷 생성
gcloud compute networks subnets create my-ae-psc-subnet --range=192.168.10.0/28 --network=psc-i-vpc --region=asia-northeast3
Network Attachment 생성
gcloud compute network-attachments create my-ae-psc-attachment \
--region=asia-northeast3 \
--connection-preference=ACCEPT_AUTOMATIC \
--subnets=my-ae-psc-subnet
PSC용 사설 IP 예약
gcloud compute addresses create "psc-ip-name" \
    --global \
    --purpose=PRIVATE_SERVICE_CONNECT \
    --addresses="IP address" \
    --network="your-vpc-network-name" \
    --project="your-project-id"
실제 값 입력시

gcloud compute addresses create vertex-psc-ip \
    --global \
    --purpose=PRIVATE_SERVICE_CONNECT \
    --addresses=100.100.100.254 \
    --network=psc-i-vpc \
    --project=ctu-gcp-dsa2-unit

PSC 엔드포인트(Forwarding Rule) 생성

gcloud compute forwarding-rules create "forwarding runl name" (유의사항 띄어쓰기, 하이픈안됨) \
    --global \
    --network=your-vpc-network-name \
    --address="PSC IP예약한 name" \
    --target-google-apis-bundle=all-apis \
    --project="your-project-id"

실제 값 입력시

gcloud compute forwarding-rules create vertexpscendpoint \
    --global \
    --network=psc-i-vpc \
    --address=vertex-psc-ip \
    --target-google-apis-bundle=all-apis \
    --project=ctu-gcp-dsa2-unit

IAM 권한 필요 (Network Attachment 생성)

Vertex AI Service Agent인 gcp-sa-aiplatform.iam.gserviceaccount.com 에 roles/compute.networkadmin 추가 필요

4. MCP-Server 작업

Python 가상환경 설정
python3 -m venv .venv
source .venv/bin/activate
라이브러리 설치
pip install "fastapi[standard]"
MCP Server 실행python onprem_mcp_server.py

파일

.env                    # 환경변수 설정
onprem_mcp_server.py    # [온프레미스 실행] MCP 서버
deploy_mcp_agent.py     # [Cloud Shell 실행] 배포 스크립트

`.env` (환경변수 설정)

실제 본인의 프로젝트 ID와 Network Attachment 경로, 온프레미스 사설 IP로 수정

GOOGLE_CLOUD_PROJECT="project id"
GOOGLE_CLOUD_LOCATION=asia-northeast3
GOOGLE_CLOUD_STAGING_BUCKET=gs://"your bucket name"
ONPREMISE_MCP_HOST=http://"MCP Server IP"
ONPREMIS  
# [선택] PSC-i 연결 시 미리 만들어둔 네트워크 연결(Network Attachment) 이름을 기입하세요 (예: my-network-attachment)
NETWORK_ATTACHMENT_NAME=my-ae-psc-attachment

`onprem_mcp_server.py` (온프레미스 실행용)

온프레미스 서버에서 실행하여 에이전트의 요청을 기다립니다.

기본적으로 8000 포트로 실행하였고, 방화벽에서 Agent Engine의 IP를 허용해야 합니다.

from fastapi import FastAPI
import psutil
import platform

app = FastAPI(title="On-premise MCP Server")

@app.get("/api/v1/system_status")
def get_system_status():
    """
    현재 On-premise 서버의 CPU, 메모리, 데몬(프로세스 수 등) 현황을 리턴합니다.
    """
    cpu_usage = psutil.cpu_percent(interval=1)
    memory = psutil.virtual_memory()
    disk = psutil.disk_usage('/')

    # 간단히 데몬/프로세스 수 확인 및 주요 프로세스 이름 추출
    process_count = len(psutil.pids())
    daemons = []
    for proc in psutil.process_iter(['name', 'username']):
        try:
            if proc.info['username'] == 'root' or proc.info['username'] == 'systemd':
                daemons.append(proc.info['name'])
        except (psutil.NoSuchProcess, psutil.AccessDenied):
            pass
    active_daemons = list(set(daemons))[:10] # 대표적인 데몬 10개만 리스트업

    return {
        "status": "success",
        "data": {
            "hostname": platform.node(),
            "os": platform.system(),
            "cpu_usage_percent": cpu_usage,
            "memory_total_gb": round(memory.total / (1024**3), 2),
            "memory_used_gb": round(memory.used / (1024**3), 2),
            "memory_usage_percent": memory.percent,
            "disk_usage_percent": disk.percent,
            "running_daemons_count": process_count,
            "sample_daemons": active_daemons,
            "message": "On-premise 서버 리소스가 정상적으로 수집되었습니다."
        }
    }

if __name__ == "__main__":
    import uvicorn
    # 기본 포트 8000번에서 실행
    uvicorn.run(app, host="0.0.0.0", port=8000)

`deploy_mcp_agent.py` (배포와 실행 파일)

import os
import vertexai
from vertexai.agent_engines import AgentEngine
from google.cloud import aiplatform
from dotenv import load_dotenv

load_dotenv()

# --- [에이전트 정의] ---
class McpOnPremiseAgent:
    def __init__(self, project_id: str, location: str, host: str, port: str):
        self.project_id = project_id
        self.location = location
        self.host = host
        self.port = port

    def set_up(self):
        import vertexai
        vertexai.init(project=self.project_id, location=self.location)

    def query(self, input: str = None, message: str = None) -> str:
        """호환성을 위해 input과 message 인자를 모두 수용합니다."""
        import socket
        import requests
        from vertexai.generative_models import GenerativeModel

        user_query = input or message
        if not user_query:
            return "질문이 입력되지 않았습니다."

        model = GenerativeModel("gemini-2.5-flash")

        conn_status = "Unknown"
        telemetry_data = "데이터 없음"

        if any(kw in user_query.lower() for kw in ["체크", "상황", "현황", "상태", "mcp"]):
            sock = None
            try:
                # 호스트에서 프로토콜 제거 및 IP 추출
                clean_host = self.host.replace("http://", "").replace("https://", "").split("/")[0].split(":")[0]
                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
                sock.settimeout(10.0)

                if sock.connect_ex((clean_host, int(self.port))) == 0:
                    conn_status = "Online"
                    try:
                        resp = requests.get(f"http://{clean_host}:{self.port}/api/v1/system_status", timeout=10.0)
                        if resp.status_code == 200:
                            telemetry_data = resp.text
                        else:
                            telemetry_data = f"[API Error {resp.status_code}]"
                    except Exception as api_e:
                        telemetry_data = f"[API Connect Fail] {api_e}"
                else:
                    conn_status = "Offline"
            except Exception as e: 
                conn_status = f"Connectivity Error: {e}"
            finally: 
                if sock: sock.close()

        prompt = f"사용자 질문: {user_query}\n\n[결과]\n상태: {conn_status}\n데이터: {telemetry_data}\n\n이 정보를 바탕으로 상세 보고서를 한국어로 작성하세요. 만약 Offline 상태라면 PSC-i 네트워크 연결을 점검하라고 안내하세요."
        response = model.generate_content(prompt)
        return response.text

# --- [배포 및 테스트 로직] ---
PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION", "asia-northeast3")
STAGING_BUCKET = os.environ.get("GOOGLE_CLOUD_STAGING_BUCKET")
ATTACHMENT = os.environ.get("NETWORK_ATTACHMENT_NAME")

def deploy():
    if not ATTACHMENT:
        print("[오류] NETWORK_ATTACHMENT_NAME이 설정되지 않았습니다.")
        return

    vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

    target_host = os.environ.get("ONPREMISE_MCP_HOST", "127.0.0.1")
    target_port = os.environ.get("ONPREMISE_MCP_PORT", "8000")
    clean_host = target_host.replace("http://", "").replace("https://", "").split("/")[0]

    agent = McpOnPremiseAgent(PROJECT_ID, LOCATION, clean_host, target_port)
    attachment_path = f"projects/{PROJECT_ID}/regions/{LOCATION}/networkAttachments/{ATTACHMENT}"
    psc_config = {"network_attachment": attachment_path}

    print(f"--- 에이전트 배포 시작 ---")
    print(f"PSC Attachment: {attachment_path}")

    # 안정적인 AgentEngine.create 사용
    remote_app = AgentEngine.create(
        agent_engine=agent,
        requirements=["google-cloud-aiplatform[agent_engines]", "requests"],
        display_name="mcp-agent-psc-final",
        psc_interface_config=psc_config
    )

    print(f"\n[성공] 에이전트 배포 완료: {remote_app.resource_name}")

def query_remote(resource_name: str, text: str):
    vertexai.init(project=PROJECT_ID, location=LOCATION)
    remote = AgentEngine(resource_name)
    print(f"[{LOCATION}] 질의 중: {text}")
    print(f"\n[Response]\n{remote.query(input=text)}")

if __name__ == "__main__":
    import sys
    if len(sys.argv) > 1 and sys.argv[1] == "deploy":
        deploy()
    elif len(sys.argv) > 3 and sys.argv[1] == "query":
        query_remote(sys.argv[2], sys.argv[3])
    else:
        print("Usage: python deploy_mcp.py [deploy|query <resource_name> <text>]")

해당 Endpoint 단말에서 PSC를 통해 Agent Engine 실행

"python3 deploy.py query Agent URL(projects/361709030411/locations/asia-northeast3/reasoningEngines/234523452345) "온프레미스 서버 상태 체크해줘""

import vertexai
from vertexai.preview import reasoning_engines

# 1. 초기화 (프로젝트와 리전 설정)
vertexai.init(project="project id", location="asia-northeast3")

# 2. 배포된 Agent Engine ID (콘솔이나 배포 로그에서 확인된 ID)
AGENT_ID = "https://asia-northeast3-aiplatform.googleapis.com/v1/projects/project-id/locations/asia-northeast3/reasoningEngines/28708247040:query" 

# 3. 에이전트 불러오기
agent_engine = reasoning_engines.ReasoningEngine(AGENT_ID)

# 4. 테스트 쿼리
print("--- 에이전트로부터 응답을 기다리는 중 ---")
response = agent_engine.query(input="온프레미스 서버 상태 어때?")
print(f"응답: {response}")

질의 후 성공시 화면
사용자 -> VPN -> GCP Agent Runtime(Agent Engine) -> 외부 (On-premise, Cloud) MCP 서버
위와 같은 흐름을 통해 응답을 받아 처리를 할 수 있습니다.

GCP PSC(Priave Service Connect) 에서 VPC-SC 사용하여 Gemini API 보호

달빛궁전- — Mon, 11 May 2026 10:00:57 +0900

Gemini API사용시 PSC를 사용하여 보안성을 높이고, VPC-SC로 상세 보안을 더한 부분을 설명합니다.

VPC SC를 통한 보안방법
https://cloud.google.com/blog/ko/products/ai-machine-learning/ai-private-service-connect-vpc-service-controls-gemini-api

VPC - SC 생성

보호할 리소스

보호서비스 선택

PSA 여부

허용 IP

테스트코드

# 1. 변수 설정
PROJECT_ID="shared-vpc-test-2-"
LOCATION="us-central1"
MODEL_ID="gemini-2.5-flash"

# 2. 토큰 갱신
ACCESS_TOKEN=$(gcloud auth print-access-token)

# 3. Gemini API 호출 (진짜 명령어)
curl -X POST \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent" \
  --resolve ${LOCATION}-aiplatform.googleapis.com:443:100.100.100.10 \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "Hello, Gemini! If you receive this, answer with: PSC Connection Successful!" }]
    }]
  }'

서비스 차단시
PERMISSION_DENIED으로 실행할 수 없으며, 사유(Type)는 VPC_SERVICE_CONTROLS 때문이다.

VPN IP 허용시
Access Contex Manager로 이동
→ 액세스 수준 생성

조건 작성방법
IP 서브네트워크 → 비공개 IP → VPC에 HostNetwork VPC 추가
VPN을 통해 들어오는 패킷들이 HostNetwork VPC로 왔기에 허용됨

보안을 더 세밀하게 설정시

액세스 수준대신
인그레스 정책에서 ID + 소스 + 타켓을 설정하여 더 좁혀서 설정

네트워크 보안 관점

Access Manager Context 서비스와 같이 VPC SC를 사용하면 위치정보, IP, 기기정보(유료) 외부에서 오는 네트워크와 내부 VPC 트래픽으로 오는 것을 네트워크적으로 (외부IP → Vertex AI (Gemini Model API) 로 허용, 차단 하는 것은 가능합니다.

다만 VPC SC는 VPN으로 들어오는 On-presmise/VPN IP의 네트워크단 제어를 지원하지를 않음

On-premise → GCP (Host VPC)로 들어오기에 해당 VPC를 허용하면, 해당 VPC의 트래픽은 허용처리가 가능함

즉 VPN을 통해 들어오는 패킷들이 HostNetwork VPC로 왔기에 허용할 수 있는 있으며

이는 해당 VPC 에서 VM을 만든다면, 해당 VM에서 호출이 가능할 수 있습니다.
(물론 SA에 Vertex API 권한이 있어야하지만, 호출될 가능성이 있다는 점입니다.)

네트워크 IP와 Port로 제어를 원하신다면, Azure측에서 → GCP (PSC IP)에 대해 Egress 를 차단하는 정책을 두는 것이 방법이라 생각됩니다.

네트워크 외 다른 방안은 인그레스 정책 방안이 있습니다.

VPC-SC는 다양한 조건 조합이 가능하고 고객사마다 지향하는 보안 요건이 상이하므로, 특정 방식만이 '유일한 정답'이라고 정의하기는 어려우며, VPC-SC 에 대해 상세하게 확인하고 싶다면 “VPC SC 관련 정리” 문서 참조

https://seonggi.kr/315

GCP VPC-SC(VPC Service Controls) 정리

정의: IAM(ID 기반 보안)과는 독립적으로, 컨텍스트 기반의 경계 보안을 제공하는 추가 보안 계층 목적: 데이터 무단 반출 방지: 권한이 있는 내부자가 데이터를 외부 버킷으로 복사하거나 유출하

seonggi.kr

참조 :

https://cloud.google.com/blog/ko/products/ai-machine-learning/ai-private-service-connect-vpc-service-controls-gemini-api

Google Cloud PSC(Private Service Connect)를 사용하여 Vertex AI Gemini 비공개 접근 구성하기 | Google Cloud 블로

긴 여정을 정리하면 PSC와 VPC-SC가 서로 다른 역할을 수행하면서 안전한 비공개 구성을 구현하였습니다. PSC는 '통신 경로'를 공개 인터넷에서 비공개로 전환하여 공개 인터넷에 노출되지 않는 통

cloud.google.com

GCP VPC-SC(VPC Service Controls) 정리

달빛궁전- — Fri, 8 May 2026 11:18:39 +0900

정의:
IAM(ID 기반 보안)과는 독립적으로, 컨텍스트 기반의 경계 보안을 제공하는 추가 보안 계층

목적:
데이터 무단 반출 방지: 권한이 있는 내부자가 데이터를 외부 버킷으로 복사하거나 유출하는 것을 차단
도용된 인증 정보 보호: 외부에서 훔친 계정으로 접근하더라도, 승인되지 않은 네트워크라면 API 호출을 차단
공용 노출 방지: IAM 설정 실수로 데이터가 외부에 공개되더라도, VPC SC 경계가 2차 방어선 역할을 하여 접근을 차단

구성도

GCP 내부 동작

VPN 연결을 통한 동작아래 그림은 PGA를 사용해서 제어하는 구성

단순 인터넷 제어

각 서비스별 설정방안

PGA로 오는 서비스를 제어

모든 서비스 : 모두 통과
서비스 없음 : 모두 차단
제한된 모든 서비스 : 제한된 서비스로 선택한 리소스만 사용가능
서비스 선택 : PGA를 사용할 서비스를 직접 선택
보호할 리소스

프로젝트 : 프로젝트 내부에 존재하는 리소스들을 지킨다. (VPC도 포함)
VPC : VPC내부에 있는 VM들이 외부로 나가는 것을 차단
공유VPC → VPC를 공유해서 쓰는 여러 서비스 프로젝트들 중 해당 VPC를 타고 들어오는 트래픽만 제어

제한된 서비스

보호할 서비스들 설정 (API단위)
액세스 수준

내부 : VPC, Subnet 설정
외부 : Public IP 설정
인그레스정책
경계 외부의 API 클라이언트가 경계 내에 있는 리소스에 액세스할 수 있도록 허용하는 규칙

시작(from) → 종료(To)

구분	상세 설정 항목 (무엇을 넣는가?)	비고
출발지	1. ID 및 그룹: 사용자 이메일, 서비스 계정(SA)	AND 조건으로 결합됨
	2. 소스 (액세스 수준): 허용된 IP 대역, 국가, 기기 상태	(ID + 소스 모두 맞아야 통과)
	3. 소스 (리소스): 허용된 다른 프로젝트 또는 VPC 네트워크
목적지	1. 프로젝트: 경계 내 보호받고 있는 특정 프로젝트	AND 조건으로 결합됨
	2. 서비스: 허용할 구글 서비스 (예: Storage, BigQuery)	(해당 프로젝트의 특정 기능을 허용)
	3. 작업: 허용할 구글 API의 구체적 동작 (예: Get, List, Write)

이그레스 정책
경계 내부에 있는 API 클라이언트 또는 리소스가 경계 외부의 Google Cloud 리소스에 액세스할 수 있도록 허용하는 규칙
경계가 서드 파티 API 또는 인터넷의 서비스에 대한 액세스를 차단하지 않습니다.
← 중요!! API 방화벽으로 네트워크는 차단하지 않는다는점
네트워크 차단은 방화벽 차단필요

구분	상세 설정 항목 (무엇을 넣는가?)	비고
출발지	1. ID 및 그룹: 내부의 누가 요청하는가? (보통 서비스 계정 등)	AND 조건 결합
출발지	2. 소스 (액세스 수준): 어떤 환경에서 요청하는가? (IP, 기기 조건 등)	(요청자가 누구인지 확인)
목적지	1. 프로젝트: 성벽 밖의 어떤 프로젝트에 접근할 것인가?	AND 조건 결합
	2. 서비스: 외부의 어떤 서비스를 쓸 것인가? (예: 외부 GCS)	(어디로 나가는지 확인)
	3. 작업: 외부 리소스에서 어떤 동작을 할 것인가? (예: Write 등)

단 BigQuery Omni와 같이 타사 스토리지(AWS S3, Azure Blob)를 직접 조회하는 구글의 특정 서비스 기능을 쓸 때만 해당 외부 리소스를 제어 가능함
→ 세부 설정방안은 테스트 필요

- 네트워크 보안 관점으로 재설명

Access Manager Context 서비스와 같이 VPC SC를 사용하면 위치정보, IP, 기기정보(유료) 외부에서 오는 네트워크와 내부 VPC 트래픽으로 오는 것을 네트워크적으로 (외부IP → Vertex AI (Gemini Model API) 로 허용, 차단 하는 것은 가능합니다.

다만 VPC SC는 VPN으로 들어오는 On-presmise/VPN IP의 네트워크단 제어를 지원하지를 않음

On-premise → GCP (Host VPC)로 들어오기에 해당 VPC를 허용하면, 해당 VPC의 트래픽은 허용처리가 가능함

즉 VPN을 통해 들어오는 패킷들이 HostNetwork VPC로 왔기에 허용할 수 있는 있으며

이는 해당 VPC 에서 VM을 만든다면, 해당 VM에서 호출이 가능할 수 있습니다.
(물론 SA에 Vertex API 권한이 있어야하지만, 호출될 가능성이 있다는 점입니다.)

네트워크 IP와 Port로 제어를 원한다면, On-premise 측에서 → GCP (PSC IP)에 대해 Egress 를 차단하는 정책을 두는 것이 방법이라 판단됨

네트워크 외 다른 방안은 인그레스 정책 방안이 있습니다.

인그레스정책

경계 외부의 API 클라이언트가 경계 내에 있는 리소스에 액세스할 수 있도록 허용하는 규칙

네트워크(VPC)방안도 일부 포함하나, 사용자, 서비스 계정(SA)으로도 사용이 가능합니다.

GCP Docs는 아래와 같습니다.

https://docs.cloud.google.com/vpc-service-controls/docs/ingress-egress-rules?hl=ko

위의 조건을 풀어서 보면 아래와 같습니다.

구분	상세 설정 항목 (무엇을 넣는가?)	비고
출발지	1. ID 및 그룹: 사용자 이메일, 서비스 계정(SA)	AND 조건으로 결합
	2. 소스 (액세스 수준): 허용된 IP 대역, 국가, 기기 상태 (모든소스 선택가능)	(ID + 소스 모두 맞아야 통과)
	3. 소스 (리소스): 허용된 다른 프로젝트 또는 VPC 네트워크
목적지	1. 프로젝트: 경계 내 보호받고 있는 특정 프로젝트 (모든 프로젝트 가능)	AND 조건으로 결합
	2. 서비스: 허용할 GCP 서비스 (예: Storage, BigQuery)	(해당 프로젝트의 특정 기능을 허용)
	3. 작업: 허용할 GCP API의 구체적 동작 (예: Get, List, Write)

목적지의 경우 Gemini API를 사용할 프로젝트를 선택하면 됩니다.

서비스 차단시
VPC차단이나 위의 ID(그룹)으로 차단하면 아래의 결과와 같이 차단되며 상세 설명은 다음과 같습니다.
PERMISSION_DENIED으로 실행할 수 없으며, 사유(Type)는 VPC_SERVICE_CONTROLS 인 것을 알 수 있습니다.

VPC-SC는 다양한 조건 조합이 가능하고 고객사마다 지향하는 보안 요건이 상이하므로, 특정 방식만이 '유일한 정답'이라고 정의하기는 어려움

다만, 고객사의 On-premise 자원과 결합하여 상호 보완적인 구성이 가장 효과적일 것으로 판단

On-premise/타Cloud 측 (네트워크 제어): PSC Endpoint IP로만 통신이 가능하도록 방화벽(Egress) 규칙을 적용하여 네트워크 레벨의 접근을 1차로 통제

GCP 측 (신원 제어): VPC-SC 인그레스 정책을 통해, 승인된 특정 서비스 계정(SA)만 Vertex AI API를 호출할 수 있도록 Identity 기반의 보안을 적용

GCP Agent Engine - PSC-Interface을 통한 MCP Server 사용방안

달빛궁전- — Sun, 3 May 2026 16:14:28 +0900

목표

GCP Agent Engine에서 PSC-Interface -> 외부 MCP Server를 사용하는 방안을 정리

3가지로 구분되어 진행됩니다.

- Agent Engine 실행(배포)하는 단말기의 설정
- GCP 설정
PSC network-attachment 설정
Agent Engine 설정
VPN 설정

- MCP Server와 통신하여 처리

VPN을 제외하고는 대부분 Python코드로 진행되어야함

전체구성도

FAQ
- Gemini Enterprise -> Agent Engine간 통신

https://docs.cloud.google.com/architecture/multi-agent-private-networking-patterns?hl=ko

- Gemini Enterprise 앱은 VPC 네트워크 외부이지만 Google 네트워크 내의 호스팅 환경에서 작동하는 관리 리소스입니다.
- Vertex AI Agent Engine의 커스텀 에이전트:
Vertex AI Agent Engine에서 전송된 트래픽은 연결의 서브넷 IP 주소에서 시작된 것처럼 VPC 네트워크에 표시됩니다. 그러면 VPC 네트워크에서 트래픽을 적절한 대상 IP 주소로 라우팅합니다.

- Agent Engine 서브넷 관련 [Docs](https://docs.cloud.google.com/agent-builder/agent-engine/private-service-connect-interface)
- PSC-Interface 생성방안 [](https://docs.cloud.google.com/agent-builder/agent-engine/deploy)[Docs](https://docs.cloud.google.com/agent-builder/agent-engine/deploy)

Agent Engine을 배포할 단말기 설정
- GCP Login
  gcloud auth application-default login
  GCE사용시에는 모든 API or Vertex AI API 설정
- Python 가상환경 설정
  python3 -m venv .venv
  source .venv/bin/activate
  
  - Vertex AI SDK 설치
  pip install google-cloud-aiplatform
  pip install python-dotenv
  pip install "google-cloud-aiplatform[agent_engines]"

네트워크 작업
- PSC-interface용 서브넷 생성
  gcloud compute networks subnets create my-ae-psc-subnet --range=192.168.10.0/28 --network=psc-i-vpc --region=asia-northeast3
- Network Attachment 생성
  gcloud compute network-attachments create my-ae-psc-attachment \
  --region=asia-northeast3 \
  --connection-preference=ACCEPT_AUTOMATIC \
  --subnets=my-ae-psc-subnet
- IAM 권한 필요 (Network Attachment 생성)
  
  Vertex AI Service Agent인 gcp-sa-aiplatform.iam.gserviceaccount.com 에 roles/compute.networkadmin 추가필요
MCP-Server 작업
- Python 가상환경 설정
  python3 -m venv .venv
  source .venv/bin/activate
- 라이브러리 설치
  pip install "fastapi[standard]"
- MCP Server 실행python onprem_mcp_server.py

파일

.env                    # 환경변수 설정
onprem_mcp_server.py    # [온프레미스 실행] MCP 서버
deploy_mcp_agent.py     # [Cloud Shell 실행] 배포 스크립트

`.env` (환경변수 설정)

실제 본인의 프로젝트 ID와 Network Attachment 경로, 온프레미스 사설 IP로 수정

GOOGLE_CLOUD_PROJECT=ctu-gcp-dsa2-unit
GOOGLE_CLOUD_LOCATION=asia-northeast3
GOOGLE_CLOUD_STAGING_BUCKET=gs://ctu-gcp-dsa2-unit-agent-staging
ONPREMISE_MCP_HOST=http://10.10.10.100
ONPREMIS  
# [선택] PSC-i 연결 시 미리 만들어둔 네트워크 연결(Network Attachment) 이름을 기입하세요 (예: my-network-attachment)
NETWORK_ATTACHMENT_NAME=my-ae-psc-attachment

`onprem_mcp_server.py` (온프레미스 실행용)

온프레미스 서버에서 실행하여 에이전트의 요청을 기다립니다.

기본적으로 8000 포트로 실행하였고, 방화벽에서 Agent Engine의 IP를 허용해야 합니다.

from fastapi import FastAPI
import psutil
import platform

app = FastAPI(title="On-premise MCP Server")

@app.get("/api/v1/system_status")
def get_system_status():
    """
    현재 On-premise 서버의 CPU, 메모리, 데몬(프로세스 수 등) 현황을 리턴합니다.
    """
    cpu_usage = psutil.cpu_percent(interval=1)
    memory = psutil.virtual_memory()
    disk = psutil.disk_usage('/')

    # 간단히 데몬/프로세스 수 확인 및 주요 프로세스 이름 추출
    process_count = len(psutil.pids())
    daemons = []
    for proc in psutil.process_iter(['name', 'username']):
        try:
            if proc.info['username'] == 'root' or proc.info['username'] == 'systemd':
                daemons.append(proc.info['name'])
        except (psutil.NoSuchProcess, psutil.AccessDenied):
            pass
    active_daemons = list(set(daemons))[:10] # 대표적인 데몬 10개만 리스트업

    return {
        "status": "success",
        "data": {
            "hostname": platform.node(),
            "os": platform.system(),
            "cpu_usage_percent": cpu_usage,
            "memory_total_gb": round(memory.total / (1024**3), 2),
            "memory_used_gb": round(memory.used / (1024**3), 2),
            "memory_usage_percent": memory.percent,
            "disk_usage_percent": disk.percent,
            "running_daemons_count": process_count,
            "sample_daemons": active_daemons,
            "message": "On-premise 서버 리소스가 정상적으로 수집되었습니다."
        }
    }

if __name__ == "__main__":
    import uvicorn
    # 기본 포트 8000번에서 실행
    uvicorn.run(app, host="0.0.0.0", port=8000)

`deploy_mcp_agent.py` (배포와 실행 파일)

import os
import vertexai
from vertexai.agent_engines import AgentEngine
from google.cloud import aiplatform
from dotenv import load_dotenv

load_dotenv()

# --- [에이전트 정의] ---
class McpOnPremiseAgent:
    def __init__(self, project_id: str, location: str, host: str, port: str):
        self.project_id = project_id
        self.location = location
        self.host = host
        self.port = port

    def set_up(self):
        import vertexai
        vertexai.init(project=self.project_id, location=self.location)

    def query(self, input: str = None, message: str = None) -> str:
        """호환성을 위해 input과 message 인자를 모두 수용합니다."""
        import socket
        import requests
        from vertexai.generative_models import GenerativeModel

        user_query = input or message
        if not user_query:
            return "질문이 입력되지 않았습니다."

        model = GenerativeModel("gemini-2.5-flash")

        conn_status = "Unknown"
        telemetry_data = "데이터 없음"

        if any(kw in user_query.lower() for kw in ["체크", "상황", "현황", "상태", "mcp"]):
            sock = None
            try:
                # 호스트에서 프로토콜 제거 및 IP 추출
                clean_host = self.host.replace("http://", "").replace("https://", "").split("/")[0].split(":")[0]
                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
                sock.settimeout(10.0)

                if sock.connect_ex((clean_host, int(self.port))) == 0:
                    conn_status = "Online"
                    try:
                        resp = requests.get(f"http://{clean_host}:{self.port}/api/v1/system_status", timeout=10.0)
                        if resp.status_code == 200:
                            telemetry_data = resp.text
                        else:
                            telemetry_data = f"[API Error {resp.status_code}]"
                    except Exception as api_e:
                        telemetry_data = f"[API Connect Fail] {api_e}"
                else:
                    conn_status = "Offline"
            except Exception as e: 
                conn_status = f"Connectivity Error: {e}"
            finally: 
                if sock: sock.close()

        prompt = f"사용자 질문: {user_query}\n\n[결과]\n상태: {conn_status}\n데이터: {telemetry_data}\n\n이 정보를 바탕으로 상세 보고서를 한국어로 작성하세요. 만약 Offline 상태라면 PSC-i 네트워크 연결을 점검하라고 안내하세요."
        response = model.generate_content(prompt)
        return response.text

# --- [배포 및 테스트 로직] ---
PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION", "asia-northeast3")
STAGING_BUCKET = os.environ.get("GOOGLE_CLOUD_STAGING_BUCKET")
ATTACHMENT = os.environ.get("NETWORK_ATTACHMENT_NAME")

def deploy():
    if not ATTACHMENT:
        print("[오류] NETWORK_ATTACHMENT_NAME이 설정되지 않았습니다.")
        return

    vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

    target_host = os.environ.get("ONPREMISE_MCP_HOST", "127.0.0.1")
    target_port = os.environ.get("ONPREMISE_MCP_PORT", "8000")
    clean_host = target_host.replace("http://", "").replace("https://", "").split("/")[0]

    agent = McpOnPremiseAgent(PROJECT_ID, LOCATION, clean_host, target_port)
    attachment_path = f"projects/{PROJECT_ID}/regions/{LOCATION}/networkAttachments/{ATTACHMENT}"
    psc_config = {"network_attachment": attachment_path}

    print(f"--- 에이전트 배포 시작 ---")
    print(f"PSC Attachment: {attachment_path}")

    # 안정적인 AgentEngine.create 사용
    remote_app = AgentEngine.create(
        agent_engine=agent,
        requirements=["google-cloud-aiplatform[agent_engines]", "requests"],
        display_name="mcp-agent-psc-final",
        psc_interface_config=psc_config
    )

    print(f"\n[성공] 에이전트 배포 완료: {remote_app.resource_name}")

def query_remote(resource_name: str, text: str):
    vertexai.init(project=PROJECT_ID, location=LOCATION)
    remote = AgentEngine(resource_name)
    print(f"[{LOCATION}] 질의 중: {text}")
    print(f"\n[Response]\n{remote.query(input=text)}")

if __name__ == "__main__":
    import sys
    if len(sys.argv) > 1 and sys.argv[1] == "deploy":
        deploy()
    elif len(sys.argv) > 3 and sys.argv[1] == "query":
        query_remote(sys.argv[2], sys.argv[3])
    else:
        print("Usage: python deploy_mcp.py [deploy|query <resource_name> <text>]")

다른 PC에서 Agent Engine 실행시

python3 deploy.py query Agent URL(projects/361709030411/locations/asia-northeast3/reasoningEngines/8342038700401623040) "온프레미스 서버 상태 체크해줘"

import vertexai
from vertexai.preview import reasoning_engines

# 1. 초기화 (프로젝트와 리전 설정)
vertexai.init(project="ctu-gcp-dsa2-unit", location="asia-northeast3")

# 2. 배포된 Agent Engine ID (콘솔이나 배포 로그에서 확인된 ID)
AGENT_ID = "https://asia-northeast3-aiplatform.googleapis.com/v1/projects/ctu-gcp-dsa2-unit/locations/asia-northeast3/reasoningEngines/2870868840588247040:query" 

# 3. 에이전트 불러오기
agent_engine = reasoning_engines.ReasoningEngine(AGENT_ID)

# 4. 테스트 쿼리
print("--- 에이전트로부터 응답을 기다리는 중 ---")
response = agent_engine.query(input="온프레미스 서버 상태 어때?")
print(f"응답: {response}")

질의 후 성공시
PC(단말) -> GCP Agent Engine -> VPN -> On-premise or Cloud 에 존재하는 MCP서버(SSE) 에서 응답 받아 Agent Engine에서 응답을 주게 됩니다.

GCP VPC간 Classic VPN 생성 스크립트

달빛궁전- — Wed, 22 Apr 2026 16:13:30 +0900

목표

VPN간 테스트를 위해 GCP VPC 간 VPN을 구축하는 스크립트
추가적으로 Private Service Connect (PSC)연결을 위해 PSC IP 라우팅을 추가한 설치 쉘스크립트를 설명합니다.

사용방법
소스코드를 Cloud Shell, ADC인증을 받은 local CLI(CMD)에서 실행합니다.

쉘스크립트는 gcloud 명령을 이용하여, 인증된 GCP 프로젝트의 VPC를 조회하고, 선택된 VPC의 subnet을 조회합니다.
사용자는 각 VPC, Subnet을 선택합니다.

PSC를 테스트 할 경우 해당 PSC IP대역을 입력하면 On-premise (VPC2번측)에서 PSC대역으로 찾아가도록 자동으로 GCP VPC 경로를 추가해줍니다.
아래는 실행시 예제 화면 입니다.

- 스크립트 실행

- 스크립트 실행 완료

- PSC 자동 경로 추가

- VPN 생성확인

2. Shell Script 소스코드

#!/bin/bash

# --- 색상 정의 ---
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
NC='\033[0m'

echo -e "${BLUE}======================================================${NC}"
echo -e "${BLUE}   GCP VPC간 VPN 테스트를 위한 스크립트 (정적 라우팅 기반)       ${NC}"
echo -e "${BLUE}======================================================${NC}"

# 1. 인프라 정보 수집
PROJECT_ID=$(gcloud config get-value project)
REGION="asia-northeast3"

VPC_LIST=($(gcloud compute networks list --format="value(name)"))
echo -e "\n${YELLOW}--- 1. VPC 네트워크 선택 ---${NC}"
for i in "${!VPC_LIST[@]}"; do echo "[$i] ${VPC_LIST[$i]}"; done
read -p "VPC 1 (Agent측) 번호 선택 [0]: " IDX1
VPC1_NAME=${VPC_LIST[${IDX1:-0}]}
read -p "VPC 2 (Onprem측) 번호 선택 [1]: " IDX2
VPC2_NAME=${VPC_LIST[${IDX2:-1}]}

echo -e "\n${YELLOW}--- 2. VPC 1 서브넷 선택 ---${NC}"
S_CIDRS1=($(gcloud compute networks subnets list --network=$VPC1_NAME --regions=$REGION --format="value(ipCidrRange)"))
S_NAMES1=($(gcloud compute networks subnets list --network=$VPC1_NAME --regions=$REGION --format="value(name)"))
for i in "${!S_CIDRS1[@]}"; do echo "[$i] ${S_NAMES1[$i]} (${S_CIDRS1[$i]})"; done
read -p "VPC 1에서 전파할 서브넷 번호들 (예: 0,1) [0]: " S_IDXS_STR
S_IDXS_STR=${S_IDXS_STR:-0}

SELECTED_CIDRS=()
IFS=',' read -ra ADDR <<< "$S_IDXS_STR"
for idx in "${ADDR[@]}"; do SELECTED_CIDRS+=("${S_CIDRS1[$idx]}") ; done
VPC1_SUBNETS_STR=$(IFS=, ; echo "${SELECTED_CIDRS[*]}")

echo -e "\n${YELLOW}--- 3. VPC 2 서브넷 선택 ---${NC}"
S_CIDRS2=($(gcloud compute networks subnets list --network=$VPC2_NAME --regions=$REGION --format="value(ipCidrRange)"))
for i in "${!S_CIDRS2[@]}"; do echo "[$i] ${S_CIDRS2[$i]}"; done
read -p "VPC 2 서브넷 번호 선택 [0]: " S_IDX2
VPC2_CIDR=${S_CIDRS2[${S_IDX2:-0}]}

echo -e "\n${YELLOW}--- 4. PSC IP 라우팅 설정 ---${NC}"
read -p "Vertex AI PSC IP (예: 100.100.100.254 / 대역 가능): " PSC_IP

# CIDR 형식이 아니면 /32 자동 추가
if [[ -n "$PSC_IP" && "$PSC_IP" != *"/"* ]]; then
    PSC_IP_TF="$PSC_IP/32"
else
    PSC_IP_TF="$PSC_IP"
fi

# 테라폼용 리스트 변환 (["10.1", "10.2"])
VPC1_SUBNETS_TF=$(echo $VPC1_SUBNETS_STR | sed 's/,/","/g' | sed 's/^/["/' | sed 's/$/"]/')

# 2. Terraform 생성 (세미콜론 완전 제거)
echo -e "\n${YELLOW}[3/4] Terraform 소스 생성 중...${NC}"

cat <<EOF > main.tf
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.0"
    }
  }
}

provider "google" {
  project = "$PROJECT_ID"
  region  = "$REGION"
}

resource "random_string" "shared_secret" {
  length  = 24
  special = false
}

data "google_compute_network" "vpc1" {
  name = "$VPC1_NAME"
}

data "google_compute_network" "vpc2" {
  name = "$VPC2_NAME"
}

resource "google_compute_address" "ip1" {
  name   = "vpn-ip-1"
  region = "$REGION"
}

resource "google_compute_address" "ip2" {
  name   = "vpn-ip-2"
  region = "$REGION"
}

resource "google_compute_vpn_gateway" "gw1" {
  name    = "vpn-gw-1"
  network = data.google_compute_network.vpc1.id
  region  = "$REGION"
}

resource "google_compute_vpn_gateway" "gw2" {
  name    = "vpn-gw-2"
  network = data.google_compute_network.vpc2.id
  region  = "$REGION"
}

resource "google_compute_forwarding_rule" "fr1_esp" {
  name        = "fr1-esp"
  region      = "$REGION"
  ip_protocol = "ESP"
  ip_address  = google_compute_address.ip1.address
  target      = google_compute_vpn_gateway.gw1.id
}

resource "google_compute_forwarding_rule" "fr1_u500" {
  name        = "fr1-u500"
  region      = "$REGION"
  ip_protocol = "UDP"
  port_range  = "500"
  ip_address  = google_compute_address.ip1.address
  target      = google_compute_vpn_gateway.gw1.id
}

resource "google_compute_forwarding_rule" "fr1_u4500" {
  name        = "fr1-u4500"
  region      = "$REGION"
  ip_protocol = "UDP"
  port_range  = "4500"
  ip_address  = google_compute_address.ip1.address
  target      = google_compute_vpn_gateway.gw1.id
}

resource "google_compute_forwarding_rule" "fr2_esp" {
  name        = "fr2-esp"
  region      = "$REGION"
  ip_protocol = "ESP"
  ip_address  = google_compute_address.ip2.address
  target      = google_compute_vpn_gateway.gw2.id
}

resource "google_compute_forwarding_rule" "fr2_u500" {
  name        = "fr2-u500"
  region      = "$REGION"
  ip_protocol = "UDP"
  port_range  = "500"
  ip_address  = google_compute_address.ip2.address
  target      = google_compute_vpn_gateway.gw2.id
}

resource "google_compute_forwarding_rule" "fr2_u4500" {
  name        = "fr2-u4500"
  region      = "$REGION"
  ip_protocol = "UDP"
  port_range  = "4500"
  ip_address  = google_compute_address.ip2.address
  target      = google_compute_vpn_gateway.gw2.id
}

resource "google_compute_vpn_tunnel" "t1_to_2" {
  name                    = "tunnel1-to-2"
  region                  = "$REGION"
  peer_ip                 = google_compute_address.ip2.address
  shared_secret           = random_string.shared_secret.result
  target_vpn_gateway      = google_compute_vpn_gateway.gw1.id
  ike_version             = 2
  local_traffic_selector  = ["0.0.0.0/0"]
  remote_traffic_selector = ["0.0.0.0/0"]
  depends_on              = [
    google_compute_forwarding_rule.fr1_esp,
    google_compute_forwarding_rule.fr1_u500,
    google_compute_forwarding_rule.fr1_u4500
  ]
}

resource "google_compute_vpn_tunnel" "t2_to_1" {
  name                    = "tunnel2-to-1"
  region                  = "$REGION"
  peer_ip                 = google_compute_address.ip1.address
  shared_secret           = random_string.shared_secret.result
  target_vpn_gateway      = google_compute_vpn_gateway.gw2.id
  ike_version             = 2
  local_traffic_selector  = ["0.0.0.0/0"]
  remote_traffic_selector = ["0.0.0.0/0"]
  depends_on              = [
    google_compute_forwarding_rule.fr2_esp,
    google_compute_forwarding_rule.fr2_u500,
    google_compute_forwarding_rule.fr2_u4500
  ]
}

resource "google_compute_route" "r1_to_2" {
  name                = "route-1-to-2"
  network             = data.google_compute_network.vpc1.name
  dest_range          = "$VPC2_CIDR"
  priority            = 1000
  next_hop_vpn_tunnel = google_compute_vpn_tunnel.t1_to_2.id
}

resource "google_compute_route" "r2_to_1_subnets" {
  for_each            = toset($VPC1_SUBNETS_TF)
  name                = "route-2-to-1-sub-\${replace(each.value, "/[/.]/", "-")}"
  network             = data.google_compute_network.vpc2.name
  dest_range          = each.value
  priority            = 1000
  next_hop_vpn_tunnel = google_compute_vpn_tunnel.t2_to_1.id
}

resource "google_compute_route" "r2_to_1_psc" {
  count               = "$PSC_IP_TF" != "" ? 1 : 0
  name                = "route-2-to-1-psc"
  network             = data.google_compute_network.vpc2.name
  dest_range          = "$PSC_IP_TF"
  priority            = 500
  next_hop_vpn_tunnel = google_compute_vpn_tunnel.t2_to_1.id
}
EOF

echo -e "\n${YELLOW}[4/4] Terraform 시작...${NC}"
terraform init && terraform apply -auto-approve

echo -e "\n${GREEN}=== 모든 작업이 완료되었습니다. ===${NC}"
echo -e "테스트 종료 후 삭제방안: ${YELLOW}terraform destroy -auto-approve${NC}"

GCP 메일 계정과 도메인

달빛궁전- — Mon, 20 Apr 2026 20:25:41 +0900

GCP는 조직 = 도메인 이란 개념을 사용합니다.

seonggi.kr / seonggi.com / seonggi.co.kr 모두 개별의 조직으로 운영할 수 있습니다.

(물론 대표도메인 하나만 사용하고, 나머지는 alias(별칭)으로 둘 수 도 있습니다.)

사용자의 메일이 계정이 되기 때문에 꼭 메일을 수발신 되어야 하는지에 대한 물음이 있습니다.

그에 대한 설명을 정리하였습니다.

도메인에 대한 문의

Cloud ID 가입 시 입력하는 도메인은 메일 도메인 기준으로 진행해야 하는지
별도의 도메인을 사용해도 되는지
사용할 도메인은 메일 서버(MX) 구성 없이 도메인만 보유한 상태

이 경우에도 TXT 기반 도메인 소유권 인증만으로 Cloud ID 설정/운영이 가능한지

도메인 인증 및 메일 서버(MX) 구성 관련
Cloud ID 생성 시 TXT 레코드 인증만 완료되면 메일 서버(MX)가 없어도 도메인 등록 및 운영은 기술적으로 가능

다만 공식 Docs에는 아래의 내용으로 가이드 되고 있습니다.
https://docs.cloud.google.com/identity/docs/how-to/set-up-email-with-your-domain?hl=ko

“Cloud ID에 가입할 경우 새 계정을 통해 이메일을 수신할 수 있어야 합니다. 이메일 주소는 도메인의 사용자 이름 (예: you@your-company.com)입니다. Google에서는 Cloud ID 계정에 대한 메일을 이 이메일 주소로 보냅니다.”

되도록 생성할 도메인과 메일주소가 있는 것을 권장 합니다.

다만 현 상황이 조직용 도메인과 실제 사용할 메일주소가 다르다면, 원활한 계정 관리(비밀번호 재설정 등) 및 시스템 알림 수신을 위해 다음과 같은 구성으로 할 수가 있습니다.

예시로 아래와 같이 “hun1547@seonggi.kr” 은 이메일이 수/발신 되지 않습니다. (메일서버, MX레코드가 없습니다.)

보조이메일을 보면 “sgchoi1547@gmail.com” 연결하여 사용하고 있습니다.

메일 주소가 꼭 필요한 사유 : 구글클라우드 시스템은 'ID=이메일 주소'로 인식하여 알림을 발송합니다. 메일 서버가 없는 도메인을 사용하실 경우, Cloud ID의 '보조(복구) 이메일' 설정 기능을 통해 실제 수신 가능한 외부 메일(예: 기존 회사 메일)을 연결하여 운영 리스크를 해소할 수 있습니다.
관련 공식 문서:
- 도메인 소유권 확인 가이드
- 관리자 계정 복구 설정(복구 이메일)

Model Armor 실시간 알림 설정 방안

달빛궁전- — Wed, 1 Apr 2026 16:09:00 +0900

개요

Google Cloud의 Model Armor는 LLM(대규모 언어 모델) 서비스 이용 시 발생할 수 있는 보안 위협을 실시간으로 탐지하고 차단하는 핵심 보안 솔루션입니다.

프롬프트 인젝션, 탈옥(Jailbreak) 시도, 개인정보(PII) 유출 및 부적절한 콘텐츠 생성 등의 위협은 기업의 데이터 자산과 서비스 신뢰도에 직접적인 타격을 줄 수 있습니다.

본 가이드는 Model Armor를 통해 생성되는 SanitizeOperation 로그를 실시간으로 탐지하고 , 복잡한 JSON 형식의 감사 로그를 파싱하여 운영자가 즉시 위협 상황을 인지할 수 있도록 알림 체계를 구축하는 방안을 제시합니다.

구성도

Log Explorer 이동 Log 검색

resource.type="modelarmor.googleapis.com/SanitizeOperation"

Model Armor 로 차단, 허용된 내용이 출력됩니다. 추가적으로 차단된 내용만 보고싶다면 아래 필터를 추가합니다.

resource.type="modelarmor.googleapis.com/SanitizeOperation"
jsonPayload.sanitizationResult.sanitizationVerdict="MODEL_ARMOR_SANITIZATION_VERDICT_BLOCK"

로그싱크 생성 싱크 이름과 설명작성

Pub/Sub 을 생성 합니다.topic만 옵션없이 생성해도 됩니다.

로그 라우팅 싱크, Pub/Sub Topic을 제대로 만들었는지 체크합니다.

Cloud Run으로 이동합니다.

서비스 이름, 리전 선택후 런타임은 Python 으로 선택합니다.
트리거 설정은 아래에 있으며, Log 발생시에만 필요하기 때문에 “요청 기반"과 수동 확장 (1대)로 설정했습니다.
이는 서비스 사용량에 따르게 설정하면 됩니다.

트리거 설정은 처음 만들 Pub/Sub을 연결하여 줍니다.

requirements.txt

functions-framework==3.*
requests==2.31.0

main.py

import base64
import json

def model_armor_notification_handler(request):
    try:
        request_json = request.get_json(silent=True)
        if not request_json: return "No Data", 200

        # Pub/Sub 데이터 추출
        raw_data = request_json.get('message', {}).get('data') or request_json.get('data')
        if not raw_data: return "No Data", 200

        pubsub_message = base64.b64decode(raw_data).decode('utf-8')

        try:
            log_data = json.loads(pubsub_message)
            payload = log_data.get('jsonPayload', {})
            result = payload.get('sanitizationResult', {})

            # 1. 기본 정보 추출
            project = log_data.get('resource', {}).get('labels', {}).get('resource_container', 'N/A')
            template = log_data.get('resource', {}).get('labels', {}).get('template_id', 'default')

            # 2. 사용자 입력 텍스트 (Input)
            user_input = payload.get('sanitizationInput', {}).get('text', 'N/A')

            # 3. 차단 결과 및 사유 (Verdict)
            verdict = result.get('sanitizationVerdict', 'UNKNOWN').replace('MODEL_ARMOR_SANITIZATION_VERDICT_', '')

            # 4. 탐지된 필터 상세 (Filter Results) 파싱
            filter_results = result.get('filterResults', {})
            detected = []

            for f_name, f_data in filter_results.items():
                # 필터 구조가 조금씩 다르므로 동적 접근 (pi_and_jailbreak, rai, sdp 등)
                for key in f_data.keys():
                    if 'Result' in key:
                        inner = f_data[key]
                        # matchState가 MATCH_FOUND인 것만 추출
                        if inner.get('matchState') == 'MATCH_FOUND':
                            conf = inner.get('confidenceLevel', 'N/A')
                            detected.append(f"{f_name}({conf})")

            detection_str = ", ".join(detected) if detected else "None"

            # 최종 요약 로그 출력 (IAM_ALERT_SUMMARY 스타일 계승)
            # 이 형식을 Cloud Logging에서 다시 잡아내어 알림으로 보냅니다.
            summary = f"MA_ALERT_SUMMARY | 프로젝트: {project} | 템플릿: {template} | 판결: {verdict} | 탐지필터: {detection_str} | 입력문구: {user_input}"
            print(summary)

        except json.JSONDecodeError:
            print(f"MA_ALERT_SUMMARY | 테스트 메시지 수신: {pubsub_message}")

        return "OK", 200

    except Exception as e:
        print(f"ERROR: {str(e)}")
        return "Internal Error", 500

결과
Log Explorer 이동하여 아래와 같이 로그를 찾습니다.

"textpayload: "MA_ALERT_SUMMARY"

해당 로그는 앞서 만든 Cloud Run으로 Log을 파싱하여 발생되는 로그이며, 아래와 같이
Model Armor 템플릿 이름, 판결 (허용, 차단), 탐지된 필터 내용, 입력된 문구를 정리하여 관리자가 한 눈에 내용을 파악할 수 있게 합니다.

로그의 상세내용은 아래와 같습니다.

GCP OAuth(인증)을 PSC (Private Service Connect)를 통해 사설망으로 연결하는 방안

달빛궁전- — Tue, 31 Mar 2026 16:18:09 +0900

목적 :

GCP 계정인증을 PSC로 사용하기

인증 트래픽의 사설 경로화: 온프레미스(On-Premise) 환경에서 GCP 계정 인증 요청 시, 공인 인터넷이 아닌 Cloud VPN과 PSC를 거치는 사설망 경로를 통해 Google OAuth Server에 도달하도록 구성하는 것

계정 유형별 호환성 검증: 개인 계정(gmail.com)뿐만 아니라 조직 계정(예: mz.co.kr) 등 다양한 도메인의 계정들이 PSC 경로를 통해 문제없이 인증되는지 확인하는 것이 주요 테스트 방안 보안성 강화: 내부 서버가 인터넷 게이트웨이를 통하지 않고도 외부 구글 API 서버와 안전하게 통신할 수 있는 환경을 구축

구성도

테스트 방안

DNS 조작: 온프레미스 서버의 /etc/hosts 파일을 수정하여, 구글 인증 서버 주소인 oauth2.googleapis.com의 IP를 PSC 엔드포인트의 사설 IP(예: 100.100.100.100)로 지정합니다.
인증 액세스 범위(Scopes) 검사: Google API Console을 통해 인증에 필요한 액세스 범위를 검사하며, 이 과정에서 획득한 액세스 토큰을 API에 실어 전송하게 됩니다.
브라우저 기반 인증: 사용자가 gcloud auth login을 실행하면 브라우저 링크가 생성됩니다. 사용자는 이 링크를 통해 구글 로그인 및 권한 승인(Consent)을 진행합니다.
토큰 발급 및 활성화: 인증 완료 후 브라우저에서 제공된 확인 코드(Verification Code)를 터미널에 입력하면, 해당 계정이 활성화(Active Account)되어 GCP 자원에 접근할 수 있는 권한을 얻게 됩니다

테스트 실행결과

VPN 구성
On-premise의 server 구성에서 /etc/hosts 파일에 “oauth2.googleapis.com” PSC IP로 수정
사용자 계정에 대한 인증 진행
개인계정
조직계정

gmail.com외 다른 조직 계정도 모두 인증되는 것을 확인함

https://developers.google.com/identity/protocols/oauth2?hl=ko

OAuth 2.0을 사용하여 Google API에 액세스하기 | Authorization | Google for Developers

의견 보내기 OAuth 2.0을 사용하여 Google API에 액세스하기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요. 참고: Google의 OAuth 2.0 구현 사용은 OAuth 2.0 정책의 적용

developers.google.com

Google의 OAuth 2.0에 대한 설명입니다.
테스트 방안과 동일하게 되어있는건 아니나, 인증 흐름은 동일합니다.

권한 식별: 앱이 필요한 API와 액세스 범위(Scope)를 정의합니다.
사용자 리디렉션: 앱은 요청한 권한 목록과 함께 사용자를 Google 인증 서버로 리디렉션합니다.
사용자 동의: 사용자가 요청된 권한을 검토하고 승인 여부를 결정합니다.
승인 코드 응답: Google 서버는 사용자의 승인을 확인한 후 리디렉션 URI를 통해 앱에 '승인 코드'를 전달합니다.
토큰 교환: 앱은 승인 코드를 Google의 토큰 엔드포인트(oauth2.googleapis.com)에 전송하여 '액세스 토큰' 및 '갱신 토큰'으로 교환합니다.
API 호출: 발급받은 액세스 토큰을 HTTP 헤더에 담아 실제 Google API를 호출합니다.

MacBook 배터리 보호 유틸 - bat-charge-gi

달빛궁전- — Mon, 16 Mar 2026 10:00:50 +0900

MacBook 배터리를 지켜주는 무료 오픈소스 배터리 매니저

bat-charge-gi는 MacBook의 배터리 수명을 극대화하기 위해 만들어진 무료 오픈소스 앱입니다.
완충, 완방을 하지 않기 위해 원하는 충전%까지 제한하기, 배터리 재교정, 마이크로 충전 방지를 위한 보존모드를 지원합니다.

누구나 검증하고 기여할 수 있습니다.

다운로드는 아래 주소에서

github : https://github.com/SeongGi/bat-charge-gi

GitHub - SeongGi/bat-charge-gi: MacBook 배터리 보호 유틸리티

MacBook 배터리 보호 유틸리티. Contribute to SeongGi/bat-charge-gi development by creating an account on GitHub.

github.com

주요 기능

충전 제한 (Charge Limiter)

배터리 충전 상한선을 자유롭게 설정 (예: 80%)
Apple Silicon(M1/M2/M3/M4) Mac의 SMC 레지스터를 직접 제어하여 하드웨어 수준에서 충전을 차단
어댑터가 연결된 상태에서도 설정한 %를 초과하지 않음

강제 방전 (Discharge Mode)

어댑터가 꽂혀 있어도 배터리 전력만 사용하도록 강제
충전 제한 목표치까지 빠르게 배터리를 낮추고 싶을 때 활용

배터리 보존모드 (Sailing Mode)

충전 제한에 도달한 후, 불필요한 마이크로 충전(미세 충전 반복)을 방지
배터리가 설정값에서 10% 이상 떨어질 때까지 전원만 공급받으며 소폭의 방전을 허용하여 배터리 수명 극대화

커스텀 메뉴바 상태 표시

기존 macOS 배터리 아이콘을 완벽히 대체하는 커스텀 메뉴바 아이콘
배터리 사용 시: (잔량별 아이콘 + %)
충전 진행 중: ⚡️ (번개 아이콘 + %)
전원 어댑터만 사용 중(충전 차단 상태): (플러그 아이콘 + %)

하드웨어 알림 (Notification)

USB-C 단일 연결 클램쉘 모드 환경에서 방전 모드 사용 시 모니터 깜빡임 현상을 사전에 경고하는 macOS 알림 센터 연동

배터리 캘리브레이션 (Calibration Mode)

배터리 잔량(%) 표기 오차를 바로잡기 위한 5단계 자동 사이클
[완충 → 대기 → 완전 방전 → 대기 → 재충전] 과정을 백그라운드에서 한 차례 수행
앱을 종료해도 잔여 과정 타이머는 유지됨
참고: 최신 Mac은 자체 배터리 관리가 우선되므로, 잔량 표기 오차가 크게 의심될 때만 선택적으로 사용 권장

실시간 전력 모니터링

전력 분배 흐름: 어댑터 → 시스템 / 배터리 전력 흐름을 실시간 표시
배터리 사이클 수: 현재까지의 배터리 충·방전 사이클 횟수 표시
잔여 시간: 충전 완료 또는 배터리 소진까지의 예상 시간

고급 배터리 통계 (대시보드)

설계 용량, 현재 최대 용량, 배터리 건강도(%)
현재 전압(V), 전류(A), 온도(°C)
제조사, 시리얼번호 등 상세 하드웨어 정보

작동 원리

bat-charge-gi는 Apple Silicon Mac의 SMC(System Management Controller) 레지스터를 직접 제어합니다.

충전 제어: CHTE 레지스터 키를 통해 충전 전류를 하드웨어 수준에서 차단/허용
방전 유도: 충전을 차단한 상태에서 시스템이 배터리 전력만 소모하도록 유도
배터리 정보: IOKit의 AppleSmartBattery 서비스에서 전압, 전류, 온도, 사이클 수 등을 실시간 파싱

앱 본체는 상단 상태바에 상주하며, SMC 제어를 위한 권한 데몬(LaunchDaemon)이 백그라운드에서 별도로 실행됩니다.

시스템 요구사항

항목	요구사항
macOS	macOS 13 (Ventura) 이상
칩셋	Apple Silicon (M1, M2, M3, M4 시리즈)
권한	최초 1회 루트(Root) 데몬 설치 필요

Intel Mac은 SMC 레지스터 구조가 달라 현재 미지원입니다.

설치 방법

Homebrew

이 앱은 Apple 개발자 인증(Notarize)을 받지 않은 오픈소스 앱입니다. Homebrew 전용 저장소(Tap)를 등록한 뒤 설치하며, macOS Gatekeeper를 우회하기 위해 --no-quarantine 옵션이 필요합니다.

brew tap SeongGi/tap
brew install --cask --no-quarantine bat-charge-gi

⚠️ 타 PC 설치 및 업데이트 오류 시 (강제 재설치)

이전 버전(2.7.3 등)의 설치 잔재나 Homebrew 캐시가 남아있어 "Checksum mismatch" 등의 오류가 발생하며 설치가 안 될 경우, 아래 명령어로 기존 Tap 연결을 끊고 최신 상태로 강제 재설치할 수 있습니다.

brew update
brew untap SeongGi/tap
brew tap SeongGi/tap
brew reinstall --cask --no-quarantine bat-charge-gi

수동 설치

Releases 페이지에서 최신 bat-charge-gi.dmg 다운로드
DMG 파일을 열고 앱을 Applications 폴더로 드래그
최초 실행 시 macOS가 차단하면: 시스템 설정 → 개인 정보 보호 및 보안 → "확인 없이 열기" 클릭
앱 내 "백그라운드 제어 권한 허용" 버튼을 클릭하여 Helper 데몬 설치
(앱이 열리지 않거나 차단될 경우): 터미널을 열고 아래 명령어를 입력하여 macOS 보안 차단을 강제로 해제합니다.

bashsudo xattr -rd com.apple.quarantine /Applications/bat-charge-gi.app

안전성

배터리 충전 제어는 macOS 및 Apple의 전원 관리 하드웨어가 항상 최종 안전장치로 기능합니다
SMC 레지스터 조작은 Apple 공식 펌웨어의 보호 범위 안에서 이루어지며, 물리적 손상의 위험은 없습니다
앱을 삭제하면 모든 SMC 설정이 원래 상태로 자동 복원됩니다

달빛이 비추는 궁전에서

[GitHub Actions] 온디맨드 Self-Hosted Runner 구축 방안 ( 필요할때만 컴퓨팅 자원 사용)

1. 개요

2. 사전준비 (플랫폼 공통)

3. AWS EC2 구성

4. GCP GCE 구성

5. On-Premise 구성

6. 운영 시 유의사항

8. 정리

Docker Homepage으로 나만의 서비스 대시보드 구성하기

Homepage란?

구성 목표

디렉터리 구성

Docker Compose 설정

Nginx Basic Authentication 설정

Homepage 기본 설정

서비스 그룹 구성

시스템 리소스 위젯 설정

실행

설치 중 발생한 문제

Host validation failed

보안 구성 시 확인할 점

정리

참고

Web SSH Portal

[일상 기록] 2026년, 아빠가 되었고 개발자가 되었습니다.

기적처럼 찾아온 선물

17년 차 인프라 엔지니어, 개발자로 전향하다

현실은 육아 하드코어 모드

Github Runner - EC2 Self-Hosted Runner 설정

Step 1: 기존 VPC 및 Public Subnet ID 조회하기

1. 서브넷 목록 및 정보 조회

Step 2: Key Pair (키 페어) 생성하기

Step 3: Security Group (보안 그룹) 생성 및 규칙 설정

1. 보안 그룹 생성

2. 인바운드 규칙 추가 (SSH 22번 포트 허용)

EC2 생성 명령어

Step 4: EC2에 SSH 접속 후 환경 세팅

1. Docker 설치

2. Node.js 20

3. Python 3.12

4. Terraform 1.10.0

5. jq + git

6. uv (AgentCore용)

7. Docker 그룹 반영

Step 3: GitHub Actions Runner 설치 & 등록

Step 4: Workflow 파일 수정

Step 5: AWS EventBridge Scheduler 등록

추가: 보안 고려사항

GCP Landing Zone Advisor

GCP Agent Runtime (Agent Engine) - PSC to PSC-Interface을 통한 연결 방안

파일

.env (환경변수 설정)

onprem_mcp_server.py (온프레미스 실행용)

deploy_mcp_agent.py (배포와 실행 파일)

GCP PSC(Priave Service Connect) 에서 VPC-SC 사용하여 Gemini API 보호

GCP VPC-SC(VPC Service Controls) 정리

GCP Agent Engine - PSC-Interface을 통한 MCP Server 사용방안

파일

.env (환경변수 설정)

onprem_mcp_server.py (온프레미스 실행용)

deploy_mcp_agent.py (배포와 실행 파일)

GCP VPC간 Classic VPN 생성 스크립트

GCP 메일 계정과 도메인

Model Armor 실시간 알림 설정 방안

GCP OAuth(인증)을 PSC (Private Service Connect)를 통해 사설망으로 연결하는 방안

MacBook 배터리 보호 유틸 - bat-charge-gi

주요 기능

충전 제한 (Charge Limiter)

강제 방전 (Discharge Mode)

배터리 보존모드 (Sailing Mode)

커스텀 메뉴바 상태 표시

하드웨어 알림 (Notification)

배터리 캘리브레이션 (Calibration Mode)

실시간 전력 모니터링

고급 배터리 통계 (대시보드)

작동 원리

시스템 요구사항

설치 방법

Homebrew

`.env` (환경변수 설정)

`onprem_mcp_server.py` (온프레미스 실행용)

`deploy_mcp_agent.py` (배포와 실행 파일)

`.env` (환경변수 설정)

`onprem_mcp_server.py` (온프레미스 실행용)

`deploy_mcp_agent.py` (배포와 실행 파일)