Skip to Content

CLI

deplite-agent는 서버 Agent를 등록하고 실행하는 바이너리예요.
관리와 로컬 실행은 CLI로 진행하고, 외부에서 Workflow를 호출할 때는 이름 기반 API를 사용해주세요.

다음 원라인 명령으로 Agent를 설치하고 등록해주세요.
명령에 발급받은 1회용 설치 코드를 입력해주세요.
Linux와 macOS의 amd64 및 arm64 환경을 지원해요.
자세한 설치 옵션과 서비스 관리는 Agent 운영을 참고해주세요.

curl -fsSL https://deplite.io/install/agent | DEPLITE_INSTALL_CODE=<1회용_설치_코드> sh

서브커맨드

install update uninstall start validate list run add edit cp delete status doctor logs limits version help

명령은 deplite-agent <명령> [옵션] 형식으로 실행해요.
명령별 옵션은 deplite-agent <명령> --help로 확인할 수 있어요.
데이터 디렉토리는 --data-dir 플래그, DEPLITE_DATA_DIR 환경변수, 운영체제별 기본 경로 순서로 결정돼요.
워크플로우 디렉토리는 --workflows-dir 플래그, DEPLITE_WORKFLOWS_DIR 환경변수, <data-dir>/workflows 기본값 순서로 결정돼요.
운영체제별 기본 경로는 Agent 운영을 참고해주세요.

설치와 실행

install

1회용 설치 코드를 영구 자격증명으로 교환해 이 머신을 등록하고 systemd 서비스를 설정해요.

deplite-agent install [--code <1회용_설치_코드>] [--name NAME] [--base-url URL] [--data-dir DIR] [--workflows-dir DIR] [--no-service] [--yes]
옵션설명
--code1회용 설치 코드예요. DEPLITE_INSTALL_CODE 환경변수로도 전달할 수 있어요.
--name콘솔에 표시할 Agent 이름이에요. 생략하면 호스트명을 사용해요.
--base-url백엔드 베이스 URL이에요. 기본값은 Deplite 서비스예요.
--data-dir자격증명과 로컬 상태를 저장할 위치예요.
--workflows-dir워크플로우 디렉토리예요. 기본값은 <data-dir>/workflows예요.
--no-servicesystemd 서비스를 설정하지 않아요.
--yes기존 서비스 설정이 다를 때 확인 없이 교체해요.

처음 등록할 때는 1회용 설치 코드가 필요해요.
자격증명이 이미 있는 디렉토리에서는 코드를 생략하면 등록을 건너뛰고 서비스만 설정해요.
등록된 디렉토리에 코드를 다시 전달하면 재등록을 막기 위해 오류가 발생해요.
서비스를 설정하지 않으려면 --no-service를 지정해주세요.

update

Agent v0.2.0부터 제공돼요.
Agent v0.1.0은 업데이트를 참고해 설치 스크립트로 한 번 업데이트해주세요.

GitHub Releases에서 새 Agent 버전을 내려받아 이 머신의 실행 파일을 교체해요.
실행 파일을 교체할 권한이 필요하므로 sudo로 실행해주세요.

sudo deplite-agent update [--check] [--version VERSION] [--force] [--yes] [--skip-signature]
옵션설명
--check현재 버전과 최신 버전만 확인하고 설치하지 않아요. --version과 함께 사용할 수 없어요.
--version설치할 릴리스 버전이에요. 0.2.1과 v0.2.1 형식을 모두 사용할 수 있어요. 생략하면 최신 버전을 설치해요.
--force실행 중인 job이 끝나길 기다리지 않고 바로 교체하고 재시작해요.
--yes현재보다 낮은 버전으로 바꿀 때 확인 질문을 생략해요.
--skip-signaturecosign 서명 검증을 건너뛰어요. checksum은 항상 확인해요.

--check는 새 버전이 있는지만 알려줘요.

$ sudo deplite-agent update --check 새 버전이 있습니다: 0.2.0 → 0.2.1 sudo deplite-agent update 로 업데이트할 수 있습니다

이미 최신 버전이면 최신 버전입니다 (0.2.1)을 출력해요.

update는 다음 순서로 진행돼요.

  1. GitHub Releases에서 대상 버전의 릴리스 파일과 checksums.txt를 내려받아 sha256을 확인해요. checksums.txt를 받지 못하거나 값이 다르면 중단해요.
  2. 기기에 cosign이 설치되어 있으면 릴리스 서명도 확인하고, 검증에 실패하면 중단해요. cosign이 없으면 서명 검증은 건너뛰어요.
  3. 새 실행 파일이 정상적으로 실행되는지 확인한 뒤 기존 파일을 한 번에 교체해요. 이전 실행 파일은 <실행 파일 경로>.prev로 남겨요.
  4. systemd 서비스가 실행 중이면 서비스를 재시작하고 새 버전으로 실행됐는지 확인해요.
$ sudo deplite-agent update 대상: /usr/local/bin/deplite-agent 0.2.0 → 0.2.1 cosign이 없어 서명 검증은 건너뜁니다 (checksum은 확인했습니다) deplite-agent를 새 버전(0.2.1)으로 다시 시작했습니다

서비스가 job을 실행 중이면 job이 끝날 때까지 최대 10분 기다린 뒤 실행 파일을 교체해요.
10분 안에 끝나지 않으면 교체하지 않고 중단해요.
--force를 지정하면 기다리지 않고 바로 재시작하므로, 실행 중인 job이 중단될 수 있어요.

현재보다 낮은 버전을 --version으로 지정하면 [y/N]로 확인을 받아요.
터미널이 아닌 환경에서 낮은 버전으로 바꾸려면 --yes를 지정해주세요.
이미 같은 버전이면 아무것도 바꾸지 않아요.

update는 실행한 deplite-agent 파일을 교체해요.
systemd 서비스가 다른 경로의 실행 파일을 사용하면 교체하지 않고 서비스의 실행 파일 경로를 알려줘요.
systemd 서비스가 없거나 멈춰 있으면 실행 파일만 교체하고, 다음에 시작할 때 새 버전이 적용돼요.
서비스 없이 실행 중인 Agent가 있으면 직접 다시 시작해주세요.
컨테이너에서 실행 중이면 update 대신 이미지를 새 버전으로 교체해주세요.
릴리스 파일은 GitHub Releases에서 내려받으므로 기기가 github.com에 접속할 수 있는 환경에서 실행해주세요.
업데이트는 보안을 위해 기기에서 직접 실행할 때만 진행되며, 콘솔이나 서버가 Agent를 자동으로 업데이트하지 않아요.

롤백

서비스가 새 버전으로 다시 시작되지 않으면 오류와 함께 롤백 명령을 출력해요.
출력된 명령이나 다음 명령으로 이전 실행 파일을 되돌리고 서비스를 재시작해주세요.
실행 파일 경로는 update 출력의 대상에서 확인할 수 있어요.

sudo mv /usr/local/bin/deplite-agent.prev /usr/local/bin/deplite-agent sudo systemctl restart deplite-agent

원인은 sudo journalctl -u deplite-agent -n 100 --no-pager로 확인해주세요.
.prev 파일은 업데이트할 때마다 직전 버전으로 바뀌어요.
더 이전 버전이 필요하면 sudo deplite-agent update --version 0.2.0처럼 버전을 지정해 설치해주세요.

start

Agent를 실행해 콘솔이 보내는 작업을 처리해요.

deplite-agent start [--data-dir DIR] [--workflows-dir DIR] [--heartbeat 30s] [--deploy-sync=false]
옵션설명
--data-dir자격증명과 로컬 상태를 읽을 데이터 디렉토리예요.
--workflows-dir워크플로우 디렉토리예요. 기본값은 <data-dir>/workflows예요.
--heartbeat하트비트 주기예요. 기본값은 30초예요.
--deploy-sync=false앱 배포 상태 동기화를 꺼요.

자격증명이 없는 상태로 start를 실행하면 실행을 멈추고 안내만 출력해요.

uninstall

systemd 서비스를 중지·제거하고 이 머신의 자격증명과 로컬 상태를 삭제해요.

deplite-agent uninstall [--data-dir DIR] [--keep-logs] [--yes]
옵션설명
--data-dir제거할 Agent의 데이터 디렉토리예요.
--keep-logs작업 로그를 남겨두어요.
--yes확인 질문 없이 진행해요. 스크립트에서 사용할 수 있어요.

확인 질문에 y로 답하면 제거가 진행돼요.
콘솔에 남아 있는 Agent 등록은 콘솔에서 직접 삭제해주세요.
워크플로우 디렉토리는 삭제하지 않아요.

워크플로우

validate

워크플로우 파일을 검사해요.
Agent를 실행하지 않고 문법과 스키마를 확인할 수 있어 배포 전 점검이나 CI에 사용할 수 있어요.

deplite-agent validate [--workflows-dir DIR] [FILE...]

파일을 지정하지 않으면 <data-dir>/workflows 전체를 검사해요.
하나라도 실패하면 종료 코드 1로 끝나요.

OK hello FAIL /root/.config/deplite-agent/workflows/broken.yml workflow "broken": step "nope" missing run 정상 1개, 오류 1개

Agent v0.2.0부터 디렉토리 전체를 검사할 때 파일 경로를 워크플로우 디렉토리 기준으로 표시하고, OK 줄에도 파일 경로를 함께 표시해요.
같은 name을 가진 파일이 둘 이상이면 파일마다 오류와 사유를 표시해요.

list

Agent가 인식한 워크플로우를 보여줘요.
콘솔에 보고되는 목록과 같아서 워크플로우가 콘솔에 표시되지 않을 때 확인할 수 있어요.

deplite-agent list [--workflows-dir DIR] [--json]

Agent v0.2.0부터 표 위에 워크플로우 디렉토리의 절대경로가, 표의 마지막 파일 열에 디렉토리 기준 파일 경로가 표시돼요.
이름이 겹쳐 무효가 된 워크플로우는 표 아래 별도 구역에 표시돼요.
--json은 각 항목에 절대경로 path 필드가 추가돼요.
자세한 내용은 워크플로우 관리를 참고해주세요.

run

워크플로우를 이 머신에서 바로 실행해요.
백엔드에는 작업 정보를 보고하지 않으므로 작업 이력이나 실행 제한에 영향을 주지 않아요.

deplite-agent run <워크플로우_이름> [--param k=v] [--secret k=v] [--dry-run] [--debug]
옵션설명
--param파라미터 값이에요. 여러 번 지정할 수 있고 선언된 타입에 맞춰 변환돼요.
--secret시크릿 값이에요. 지정하지 않은 값은 DEPLITE_SECRET_<KEY>에서 읽어요.
--dry-run실행하지 않고 실행 계획만 출력해요.
--debugverbose: true 스텝의 원본 출력까지 남겨요.
--no-log-mirror로그를 파일로 남기지 않아요.

--dry-run은 확정된 파라미터 값과 시크릿 바인딩 여부, 각 스텝에서 사용할 셸과 제한 시간을 실제 실행 없이 보여줘요.

워크플로우: hello 기본 셸: /bin/sh 파라미터 (3) greeting 안녕 [string] times 3 [number] loud true [boolean] 시크릿 (1) API_TOKEN 미바인딩 (선택) [모든 스텝]

add, edit, cp, delete

Agent v0.2.0부터 제공돼요.
Agent v0.1.0을 사용 중이면 업데이트를 참고해 먼저 업데이트해주세요.

워크플로우 파일을 편집기로 만들고, 고치고, 복사하고, 삭제해요.
저장하기 전에 항상 검사하므로 검사를 통과한 내용만 워크플로우 디렉토리에 반영돼요.

deplite-agent add <이름> [--workflows-dir DIR] [--editor CMD] deplite-agent edit <이름|파일> [--workflows-dir DIR] [--editor CMD] deplite-agent cp <원본_이름> <새_이름> [--workflows-dir DIR] [--edit] [--editor CMD] deplite-agent delete <이름|파일> [--workflows-dir DIR] [--yes]

서비스로 설치한 Agent의 워크플로우를 다룰 때는 sudo로 실행해주세요.
명령별 동작과 편집기 선택 순서는 워크플로우 관리를 참고해주세요.

진단

status

등록 정보와 실행 상태를 보여줘요.

deplite-agent status [--data-dir DIR] [--workflows-dir DIR] [--json]

Agent가 실행 중이면 프로세스 ID와 스트림 연결, 마지막 하트비트, 현재 처리 중인 작업을 함께 표시해요.
Linux에 서비스가 있으면 유닛 경로, 사용자, 활성 상태와 서비스의 데이터 디렉토리도 표시해요.
서비스의 데이터 디렉토리와 현재 명령의 경로가 다르면 안내가 표시돼요.
현재 경로를 확인하고, 서비스 경로를 확인하려면 --data-dir을 지정하거나 서비스 사용자로 다시 실행해주세요.

doctor

설치·연결·권한을 한 번에 점검해요.
설치가 예상대로 되지 않을 때 먼저 실행해주세요.

deplite-agent doctor [--data-dir DIR] [--workflows-dir DIR] [--timeout 10s]

데이터 디렉토리 권한, 자격증명, 백엔드 연결, 워크플로우 파일, 스텝 셸, 서비스, 로그 디렉토리, 실행 중인 Agent를 차례로 확인해요.
하나라도 실패하면 종료 코드 1로 끝나요.

logs

지난 작업의 로그를 확인해요.
기본값은 가장 최근 작업이에요.

deplite-agent logs [--job ID] [--stream system|raw] [--follow] [--list]

system 스트림은 Agent가 남긴 진행 기록이고, raw 스트림은 스텝의 표준 출력이에요.

limits

워크플로우 실행 제한인 cooldown과 bucket의 상태를 확인하거나 초기화해요.

deplite-agent limits [--workflows-dir DIR] [--reset NAME] [--reset-all]

작업이 rate limited로 거절될 때 남은 대기 시간과 토큰을 확인할 수 있어요.

기타

명령설명
version버전과 빌드 정보를 출력해요.
help전체 명령 목록을 출력해요.

스텝에 전달되는 환경변수

워크플로우 호출의 params 값은 스텝 환경에 DEPLITE_PARAM_<이름>으로 주입돼요.
이름은 대문자로 바뀌고 - 문자는 _로 바뀌어요.
예를 들어 image-tag param은 DEPLITE_PARAM_IMAGE_TAG로 읽을 수 있어요.

변수의미
DEPLITE_PARAM_<이름>호출 params에서 전달한 값
DEPLITE_SECRET_<이름>Agent 환경에 설정하고 Workflow에서 선언한 시크릿
DEPLITE_WORKDIR해당 스텝의 임시 작업 디렉토리
DEPLITE_OUTPUTid가 있는 스텝의 출력 캡처 파일 경로
DEPLITE_OUTPUT_DIRWorkflow 전역 출력 디렉토리

스텝 환경변수와 실행 방식은 스텝 실행 환경을 참고해주세요.
환경변수 목록은 Agent 운영, 워크플로우 파일 형식은 워크플로우 작성을 참고해주세요.

관련 문서

최종 수정 일자: