Agent 운영
서버 Agent는 노드의 워크플로우 YAML에 선언된 동작을 실행해요.
외부에서 이름으로 호출할 Workflow는 YAML에 on: webhook을 선언해야 해요.
설치와 등록
콘솔의 에이전트 화면에서 1회용 설치 코드를 발급해주세요.
아래 명령의 DEPLITE_INSTALL_CODE=<1회용_설치_코드> 부분에 발급받은 코드를 입력해주세요.
curl -fsSL https://deplite.io/install/agent | DEPLITE_INSTALL_CODE=<1회용_설치_코드> shLinux에서는 바이너리 설치와 Agent 등록, systemd 서비스 설정 및 시작까지 한 번에 진행돼요.
systemd가 없는 macOS 등의 환경에서는 등록 후 deplite-agent start로 실행해주세요.
Linux와 macOS의 amd64 및 arm64 환경을 지원해요.
설치 스크립트는 릴리스의 checksums.txt로 내려받은 파일을 검증하고, 검증할 수 없으면 설치를 중단해요.
다른 디렉토리를 지정하거나 이미 등록된 머신의 서비스만 설정할 때는 다음 명령을 사용해주세요.
deplite-agent install [--code <1회용_설치_코드>] \
[--name NAME] [--base-url URL] [--data-dir DIR] [--workflows-dir DIR] [--no-service] [--yes]| 옵션 | 설명 |
|---|---|
--code | 1회용 설치 코드예요. DEPLITE_INSTALL_CODE 환경변수로도 전달할 수 있어요. |
--name | 콘솔에 표시할 Agent 이름이에요. 생략하면 호스트명을 사용해요. |
--base-url | 백엔드 베이스 URL이에요. 기본값은 Deplite 서비스예요. |
--data-dir | 자격증명과 로컬 상태를 저장할 디렉토리예요. |
--workflows-dir | 워크플로우 디렉토리예요. 기본값은 <data-dir>/workflows예요. |
--no-service | systemd 서비스를 설정하지 않아요. |
--yes | 기존 서비스 설정이 다를 때 확인 없이 교체해요. |
처음 등록할 때는 1회용 설치 코드가 필요해요.
이미 등록된 데이터 디렉토리에서 코드를 생략하고 deplite-agent install을 실행하면 등록을 건너뛰고 서비스 설정만 다시 적용해요.
등록된 데이터 디렉토리에 코드를 다시 전달하면 재등록을 막기 위해 오류가 발생해요.
systemd 서비스를 설정하지 않으려면 --no-service를 지정해주세요.
실제 데이터와 워크플로우 경로는 deplite-agent status로 확인해주세요.
다른 명령과 옵션은 CLI 레퍼런스를 참고해주세요.
데이터와 워크플로우 디렉토리
데이터 디렉토리는 --data-dir 플래그, DEPLITE_DATA_DIR 환경변수, 운영체제별 기본 경로 순서로 결정돼요.
| 운영체제 | 기본 데이터 디렉토리 |
|---|---|
| Linux root 사용자 | /root/.config/deplite-agent |
| Linux 일반 사용자 | XDG_CONFIG_HOME이 있으면 $XDG_CONFIG_HOME/deplite-agent, 없으면 ~/.config/deplite-agent |
| macOS | ~/Library/Application Support/deplite-agent |
워크플로우 디렉토리는 --workflows-dir 플래그, DEPLITE_WORKFLOWS_DIR 환경변수, <data-dir>/workflows 기본값 순서로 결정돼요.
root로 설치하면 기본 워크플로우 디렉토리는 /root/.config/deplite-agent/workflows예요.
별도 설정 파일은 없으며, 플래그나 환경변수로 경로를 지정해주세요.
워크플로우 파일 변경은 파일 감지로 반영돼요.
Agent v0.2.0부터 하위 디렉토리 안의 파일 변경도 바로 반영돼요.
워크플로우 파일은 deplite-agent add, edit, cp, delete로 관리할 수 있어요.
자세한 내용은 워크플로우 관리를 참고해주세요.
<data-dir>/
└── workflows/
└── <workflow>.yaml서비스 관리
설치가 끝나면 Linux의 systemd가 Agent를 시작하고 다시 실행을 관리해요.
systemctl status deplite-agent
systemctl restart deplite-agent
journalctl -u deplite-agent -fCLI에서 상태와 최근 작업 기록을 확인하거나 설치 상태를 점검할 수 있어요.
deplite-agent status
deplite-agent logs --follow
deplite-agent doctoragent.env 설정
<데이터 디렉토리>/agent.env 파일에 시크릿과 추가 환경변수를 설정할 수 있어요.
이 파일은 설치 명령이 만들지 않으며, 파일이 없어도 서비스는 시작돼요.
DEPLITE_SECRET_REGISTRY_PASSWORD=값
DEPLITE_ARTIFACT_VERIFY=require
DEPLITE_SHELL=/bin/bash아티팩트 검증 모드는 auto, require, off를 사용할 수 있고, 알 수 없는 값은 auto로 처리돼요.
시크릿을 보호할 수 있도록 파일 권한을 0600으로 설정해주세요.
파일을 수정한 뒤에는 systemctl restart deplite-agent를 실행해주세요.
업데이트
Agent v0.2.0부터 deplite-agent update로 Agent를 업데이트할 수 있어요.
GitHub Releases에서 새 버전을 내려받아 checksum을 확인한 뒤 실행 파일을 교체하고, 서비스가 실행 중이면 재시작해요.
이전 실행 파일은 <실행 파일 경로>.prev로 남아 있어 문제가 생기면 되돌릴 수 있어요.
sudo deplite-agent update --check
sudo deplite-agent update--check는 새 버전이 있는지만 확인해요.
업데이트는 보안을 위해 기기에서 직접 실행할 때만 진행되며, 콘솔이나 서버가 Agent를 자동으로 업데이트하지 않아요.
옵션과 동작, 롤백 방법은 CLI 레퍼런스를 참고해주세요.
Agent v0.1.0에는 update 명령이 없어요.
설치 스크립트를 한 번 다시 실행하면 최신 버전으로 업데이트되고, 서비스가 실행 중이면 새 버전으로 재시작돼요.
이때 설치 코드는 필요하지 않아요.
설치 스크립트는 실행 중인 job을 기다리지 않고 서비스를 재시작하므로, 실행 중인 작업이 없을 때 실행하는 것을 추천드려요.
curl -fsSL https://deplite.io/install/agent | sh제거
deplite-agent uninstall은 systemd 서비스를 중지하고 제거한 뒤, 데이터 디렉토리의 자격증명과 로컬 상태를 삭제해요.
확인 없이 진행하려면 --yes를 지정해주세요.
워크플로우 디렉토리와 안의 YAML 파일은 삭제하지 않아요.
콘솔에 등록된 Agent는 콘솔에서 직접 삭제해주세요.
deplite-agent uninstall [--data-dir DIR] [--keep-logs] [--yes]환경변수
| 변수 | 설명 |
|---|---|
DEPLITE_INSTALL_CODE | 설치 시 사용할 1회용 설치 코드예요. |
DEPLITE_BASE_URL | 백엔드 베이스 주소예요. 기본값은 Deplite 서비스예요. |
DEPLITE_DATA_DIR | 자격증명·상태·로그를 저장할 데이터 디렉토리예요. |
DEPLITE_WORKFLOWS_DIR | 워크플로우 디렉토리예요. 기본값은 <data-dir>/workflows예요. |
DEPLITE_SECRET_<KEY> | 워크플로우 secrets:에 선언된 키의 값이에요. |
DEPLITE_SHELL | 스텝 실행 셸이에요. 기본값은 /bin/sh예요. |
DEPLITE_LOG_DIR | Agent 로그 파일 디렉토리예요. |
DEPLITE_ARTIFACT_VERIFY | 아티팩트 서명 검증 모드예요. 자세한 내용은 아티팩트 검증을 참고해주세요. |
DEPLITE_ARTIFACT_KEY_DIR | 아티팩트 서명 공개키 디렉토리예요. 기본값은 /etc/deplite/keys예요. 아티팩트 검증을 참고해주세요. |
DEPLITE_ARTIFACT_TRUST_SERVER_KEY | 기기에 공개키가 없을 때 서버가 보낸 공개키를 신뢰할지 설정해요. 아티팩트 검증을 참고해주세요. |
CLI 명령과 옵션은 CLI 레퍼런스를 참고해주세요.
스텝 실행
서버 Agent의 스텝은 Agent를 실행한 사용자 권한으로 호스트에서 직접 실행돼요.
systemd 서비스로 설치하면 설치 명령을 실행한 사용자 권한으로 스텝이 실행돼요.
따라서 스텝에서 사용하는 명령과 경로는 해당 호스트에서 접근할 수 있어야 해요.
자세한 실행 환경은 스텝 실행 환경에서 확인해주세요.
운영 시 확인할 점
Agent가 오프라인일 때 wait: true로 실행 요청을 보내면 요청은 큐에 쌓이지 않고 rejected 상태와 agent_offline 사유로 즉시 반환돼요.
응답 결과가 필요한 호출은 wait: true를 사용하고, 비동기 요청 결과는 응답의 consoleUrl에서 확인해주세요.
스텝에서 command not found가 발생하면 해당 명령이 호스트에 설치되어 있고 Agent를 실행한 사용자에게 실행 권한이 있는지 확인해주세요.
working-directory에 지정한 경로도 호스트 파일시스템에 존재하고 해당 사용자가 접근할 수 있어야 해요.