Skip to Content
문서Agent 운영

Agent 운영

Agent 설치에서 다룬 기본 위에, 운영 중에 필요한 세부 내용을 모았어요.

디렉토리 구조

<base>/
├── workflows/        # YAML 파일들 (.yaml | .yml)
├── creds/
│   ├── agent.id      # UUID
│   ├── agent.key     # ED25519 개인키 (chmod 600 필수)
│   └── server.pub    # 서버 공개키
└── logs/
    ├── agent.log     # Agent 자체 로그
    ├── jobs/<jobId>/ # Job별 로그 (JSONL)
    ├── queue/        # 업로드 대기 큐
    ├── limits/       # 워크플로우별 리밋 상태 JSON
    └── files/        # 입력 파일 다운로드 캐시

Job 로그 형식

./logs/jobs/<jobId>/에 JSON Lines 형식으로 저장돼요.

{"seq":0,"stream":"summary","stepName":"Build","level":"info","content":"Build started"}
{"seq":1,"stream":"raw","stepName":"Build","content":"Step 1/5 : FROM node:18\n"}
{"seq":2,"stream":"summary","stepName":"","level":"info","content":"Workflow completed: success"}
stream의미
summary요약 메시지 (level 분류)
raw원본 stdout/stderr (verbose 레벨일 때만)
system시스템 메시지 (타임아웃, 시그널 등)

로그 전송 정책

  • 배치 크기: 64KB 또는 1초 중 빠른 쪽
  • 실패 시 ./logs/queue/에 저장 후 재시도
  • 전송 후에도 로컬 사본은 log_retention(기본 20개) 만큼 유지

Heartbeat

60초마다 다음을 전송해요.

{
  "agent_version": "0.2.0",
  "running_jobs": ["job-id"],
  "workflow_count": 5
}

대시보드의 Agent 상태(connected/disconnected)는 이 값으로 갱신돼요.

워크플로우 스캔

  • 30초마다 ./workflows/ 디렉토리 스캔
  • 변경 감지 시 즉시 서버에 메타 보고
  • Workflows → Refresh 버튼으로 즉시 트리거 가능

업그레이드

sudo systemctl stop deplite-agent
sudo curl -L -o /usr/local/bin/deplite-agent \
  https://releases.deplite.io/agent/<version>/linux-amd64/deplite-agent
sudo chmod +x /usr/local/bin/deplite-agent
sudo systemctl start deplite-agent

agent.id와 agent.key는 그대로 두면 돼요. 재등록 불필요.

백업·복구

백업해야 하는 것안 해도 되는 것
./creds/ 전체 (특히 agent.key)./logs/ (자동 정리됨)
./workflows/ (Git 관리 권장)Agent 바이너리

./creds만 보존하면 같은 Agent 신원으로 다른 머신에서도 복원할 수 있어요.

트러블슈팅

”agent revoked” 후 종료

대시보드에서 회수된 상태예요.
./creds를 비우고 새 Enrollment Token으로 재등록하세요.

sudo systemctl stop deplite-agent
sudo rm -f /var/lib/deplite/creds/*
echo "DEPLITE_TOKEN=enr_NEW..." | sudo tee /etc/deplite/agent.env
sudo systemctl start deplite-agent

SSE가 자꾸 끊겨요

1초→2초→4초… 60초까지 지수 백오프로 재연결돼요. 30초 유휴 시 강제 재연결.
오래 끊긴 채로 있다면 다음을 확인하세요.

  • 방화벽: outbound 443 허용
  • 프록시: HTTP keep-alive 끊기지 않는지
  • 시스템 시간: ±60초 어긋나면 서명 검증 실패 → NTP 점검

Job이 rejected 상태로 빨리 끝나요

rejectReason을 확인하세요.

  • rate_limited → 워크플로우 리밋(limits)
  • queue_full → 동시 실행 한도 초과. Agent 추가 또는 동시성 조정
  • unknown_workflow → 파일명·name 불일치 또는 스캔 누락

시크릿이 로그에 노출됐어요

워크플로우 YAML의 secrets: 목록에 해당 환경변수 이름이 있는지 확인하세요.
값이 base64 인코딩되거나 부분 문자열로 출력되면 마스킹을 못 잡을 수 있어요. 가능한 한 원본 그대로 출력하지 마세요.

디스크 사용량이 커요

./logs/jobs/가 큰 경우가 많아요.
워크플로우의 log_retention을 줄이거나, 별도 cron으로 N일 이상 된 디렉토리를 삭제하세요.

Kubernetes 배포 예시

각 노드에 1개씩 띄우는 DaemonSet 패턴이에요.

# k8s/deplite-agent.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: deplite
---
apiVersion: v1
kind: Secret
metadata:
  name: deplite-creds
  namespace: deplite
type: Opaque
stringData:
  DEPLITE_TOKEN: "enr_..."     # 1회만 필요. 등록 후 제거 가능
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: deplite-workflows
  namespace: deplite
data:
  deploy-prod.yaml: |
    name: deploy-prod
    timeout-minutes: 30
    secrets: [DATABASE_URL]
    steps:
      - name: rollout
        run: kubectl set image deployment/myapp myapp=myapp:$REF
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: deplite-agent
  namespace: deplite
spec:
  selector:
    matchLabels: { app: deplite-agent }
  template:
    metadata:
      labels: { app: deplite-agent }
    spec:
      serviceAccountName: deplite-agent
      containers:
        - name: agent
          image: deplite/agent:0.2.0
          envFrom:
            - secretRef: { name: deplite-creds }
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef: { name: app-secrets, key: db-url }
          volumeMounts:
            - { name: workflows, mountPath: /workflows, readOnly: true }
            - { name: creds, mountPath: /creds }
            - { name: logs, mountPath: /logs }
          resources:
            requests: { cpu: "50m", memory: "64Mi" }
            limits: { cpu: "500m", memory: "256Mi" }
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
      volumes:
        - name: workflows
          configMap: { name: deplite-workflows }
        - name: creds
          persistentVolumeClaim: { claimName: deplite-creds-pvc }
        - name: logs
          emptyDir: {}

주의: creds PVC는 노드마다 독립적이어야 해요(ReadWriteOnce). 노드 교체 시 새 등록이 필요해요.

모니터링 예시

Prometheus로 Agent 상태를 추적하려면 heartbeat 응답이나 Deplite 서버 metrics(향후 제공)에서 다음을 추적하면 좋아요.

지표의미
deplite_agent_running_jobs현재 실행 중인 Job 수
deplite_agent_queue_depthJob 큐 대기 수
deplite_agent_workflow_count등록된 워크플로우 수
deplite_agent_sse_reconnects_totalSSE 재연결 누적
deplite_agent_last_seen_seconds마지막 heartbeat 후 경과 시간

알림 규칙 예 (Alertmanager):

- alert: DepliteAgentDown
  expr: time() - deplite_agent_last_seen_seconds > 300
  for: 2m
  labels: { severity: critical }
  annotations:
    summary: "Agent {{ $labels.agent_id }} unreachable for 5m+"
 
- alert: DepliteQueueBacklog
  expr: deplite_agent_queue_depth > 50
  for: 5m
  labels: { severity: warning }

다음으로

최종 수정 일자:
통합보안