Skip to Content
가이드Agent 설치

Agent 설치

빠른 시작에서는 포그라운드로 한 번 실행해 봤어요.
이 문서는 실제 프로덕션 환경에서 안정적으로 Agent를 운영하는 방법을 다뤄요.

디렉토리 레이아웃

Agent는 세 디렉토리를 사용해요. 각각의 역할을 알아 두면 백업·권한 설정이 수월해져요.

경로역할백업
./workflows실행할 YAML 워크플로우 파일들필수 (Git 관리 권장)
./credsagent.id, agent.key(개인키), server.pub필수, 권한 600
./logsJob 로그(JSONL), 레이트리밋 상태선택 (retention 자동 정리)

중요: ./creds/agent.key는 Agent의 신원이에요.
유출되면 즉시 대시보드에서 해당 Agent를 revoke하고 새 Enrollment Token으로 재등록하세요.

환경변수

변수설명기본값
DEPLITE_TOKENEnrollment Token. 최초 등록 시 1회만 필요해요.(없음)
DEPLITE_WORKFLOWS_DIR워크플로우 디렉토리 경로./workflows

등록이 끝나면 DEPLITE_TOKEN은 더 이상 필요 없어요.

systemd로 운영하기

/etc/systemd/system/deplite-agent.service

[Unit]
Description=Deplite Agent
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=deplite
Group=deplite
WorkingDirectory=/var/lib/deplite
ExecStart=/usr/local/bin/deplite-agent
Restart=always
RestartSec=5
EnvironmentFile=-/etc/deplite/agent.env
 
# 보안 hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/deplite
ProtectHome=true
PrivateTmp=true
 
[Install]
WantedBy=multi-user.target
sudo useradd --system --home /var/lib/deplite --shell /usr/sbin/nologin deplite
sudo mkdir -p /var/lib/deplite/{workflows,creds,logs}
sudo chown -R deplite:deplite /var/lib/deplite
sudo chmod 700 /var/lib/deplite/creds
 
echo "DEPLITE_TOKEN=enr_..." | sudo tee /etc/deplite/agent.env
sudo chmod 600 /etc/deplite/agent.env
 
sudo systemctl daemon-reload
sudo systemctl enable --now deplite-agent
sudo systemctl status deplite-agent

Docker로 운영하기

# docker-compose.yml
services:
  agent:
    image: deplite/agent:0.2.0
    restart: unless-stopped
    environment:
      DEPLITE_TOKEN: ${DEPLITE_TOKEN}
    volumes:
      - ./workflows:/workflows:ro
      - ./creds:/creds
      - ./logs:/logs
DEPLITE_TOKEN=enr_... docker compose up -d
docker compose logs -f agent

주의: workflows 볼륨을 :ro로 마운트하면, Agent 컨테이너 내부에서 워크플로우 파일이 수정되지 않도록 보호돼요. Git에서 pull하는 별도 사이드카를 두면 깔끔해요.

Kubernetes로 운영하기

각 노드에 1개씩 띄우는 DaemonSet 패턴이 일반적이에요.
Secrets와 PVC로 creds를 관리하고, ConfigMap이나 Git-sync로 workflows를 동기화하세요.

(상세 예제는 Agent 운영 문서를 참고하세요.)

업그레이드

새 버전의 바이너리로 교체한 뒤 재시작하면 끝이에요.
agent.id와 agent.key가 그대로 유지되므로 재등록은 필요하지 않아요.

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

문제 해결

  • 등록 실패: DEPLITE_TOKEN이 만료되었거나 이미 사용됐을 수 있어요. 대시보드에서 새 토큰을 발급하세요.
  • “agent revoked”: 서버에서 Agent를 회수한 상태예요. ./creds/를 비우고 새 토큰으로 재등록하세요.
  • SSE 끊김: 1초→60초 지수 백오프로 자동 재연결돼요. 30초 유휴 시 재연결 트리거. 네트워크/방화벽 점검을 해보세요.

다음으로

최종 수정 일자:
빠른 시작첫 워크플로우