Agent 운영

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

디렉토리 구조

Agent는 하나의 데이터 디렉토리를 가져요. 기본값은 OS의 사용자 설정 경로(os.UserConfigDir()/deplite-agent)이고, DEPLITE_DATA_DIR 환경변수나 --data-dir 플래그로 바꿀 수 있어요.


<DataDir>/
├── identity.json    # Agent ID·organizationId·baseUrl·serverPublicKeyPem (0600)
├── agent.key        # Agent 개인키 PEM (0600)
└── workflows/       # YAML 파일들 (.yaml | .yml)

워크플로우 디렉토리만 따로 둘 수도 있어요. DEPLITE_WORKFLOWS_DIR 환경변수나 --workflows-dir 플래그로 오버라이드돼요. 디렉토리 자체 권한은 0700, 파일은 0600으로 자동 설정돼요.

로그

Agent는 stdout으로 구조화 로그(slog)를 그대로 흘려요.
운영체제 로그 시스템에 위임하는 게 표준 패턴이에요.


# systemd 환경에서 보기
sudo journalctl -u deplite-agent -f

Job 단위 로그(step의 stdout/stderr)는 디스크에 따로 쌓지 않고, 곧바로 서버 API(POST /v1/agent/jobs/:id/logs)로 스트리밍돼요.
대시보드의 Jobs 화면에서 볼 수 있어요.

stream	의미
`raw`	step의 원본 stdout/stderr
`system`	시작·종료·타임아웃·시그널 같은 시스템 메시지

서버 측 시크릿 마스킹은 Agent가 처리해요.
워크플로우의 secrets: 목록에 선언된 환경변수 값은 stdout/stderr에 노출되어도 ***로 자동 마스킹돼요.

Heartbeat

Agent는 기본 30초 간격으로 서명된 빈 본문 POST를 /v1/agent/heartbeat로 보내요(서버가 살아있는지 표시하는 용도). --heartbeat-interval 플래그로 조정할 수 있어요.
대시보드의 Agent 상태(connected·disconnected)는 이 신호를 기준으로 갱신돼요.

워크플로우 디렉토리 감시

Agent는 워크플로우 디렉토리를 파일시스템 이벤트(fsnotify)로 실시간 감시해요.
파일이 추가·수정·삭제되면 500ms debounce 후 다시 스캔하고, 변경된 메타데이터를 즉시 서버에 보고해요.

폴링이 아니라 이벤트 기반이라 별도 주기 설정은 없어요.

환경변수와 명령

자세한 환경변수·CLI 옵션은 CLI 페이지에서 다뤄요.

업그레이드


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

identity.json과 agent.key는 그대로 두면 돼요.
새 바이너리도 동일한 자격을 그대로 이어 받기 때문에 재등록은 필요하지 않아요.

백업·복구

백업해야 하는 것	안 해도 되는 것
`<DataDir>/identity.json` + `<DataDir>/agent.key`	journalctl 로그 (자동 순환)
워크플로우 디렉토리 (Git 관리 추천)	Agent 바이너리

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

트러블슈팅

”agent revoked” 후 종료

대시보드에서 회수된 상태예요.
데이터 디렉토리를 비우고 새 1회용 설치 코드로 재등록해주세요.


sudo systemctl stop deplite-agent
sudo rm -rf /var/lib/deplite/identity.json /var/lib/deplite/agent.key
DEPLITE_INSTALL_CODE="<NEW_1회용_설치_코드>" sudo -E /usr/local/bin/deplite-agent install
sudo systemctl start deplite-agent

SSE가 자꾸 끊겨요

Agent는 지수 백오프(1초→2초→…→최대 60초)로 자동 재연결해요.
오래 끊긴 채로 있다면 다음을 확인해주세요.

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

Job이 누락된 것 같아요

Agent의 동시 실행 큐 크기는 기본 4입니다.
큐가 가득 찬 상태에서 새 deploy 이벤트가 도착하면 Agent가 silent drop하고 로컬 로그(job queue full; rejecting)에만 기록해요.
서버에는 rejected job으로 보고되지 않아요.

대시보드와 Agent 로그가 어긋나면 journalctl에서 job queue full 메시지를 먼저 확인하고, 필요하면 Agent 인스턴스를 추가해주세요.

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

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

디스크 사용량이 커요

Agent 자체는 로그를 디스크에 쌓지 않아요. journalctl 로테이션이 작동하는지(journalctl --disk-usage) 확인해주세요.

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_INSTALL_CODE: "<1회용_설치_코드>"   # 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:$DEPLITE_PARAM_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:<version>
          envFrom:
            - secretRef: { name: deplite-creds }
          env:
            - name: DEPLITE_DATA_DIR
              value: /credentials
            - name: DEPLITE_WORKFLOWS_DIR
              value: /workflows
            - name: DEPLITE_SECRET_DATABASE_URL
              valueFrom:
                secretKeyRef: { name: app-secrets, key: db-url }
          volumeMounts:
            - { name: workflows, mountPath: /workflows, readOnly: true }
            - { name: credentials, mountPath: /credentials }
          resources:
            requests: { cpu: "50m", memory: "64Mi" }
            limits: { cpu: "500m", memory: "256Mi" }
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
      volumes:
        - name: workflows
          configMap: { name: deplite-workflows }
        - name: credentials
          persistentVolumeClaim: { claimName: deplite-creds-pvc }

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