스텝 실행 환경
서버 Agent의 모든 워크플로우 스텝은 Agent를 실행한 사용자의 권한으로 호스트에서 직접 실행돼요.
컨테이너 실행 경로나 네임스페이스 전환 모드는 제공되지 않아요.
워크플로우 디렉토리 기본값은 <data-dir>/workflows예요.
OS별 데이터 경로는 Agent 운영을 참고해주세요.
호스트 실행
스텝은 Agent 프로세스를 실행한 사용자의 권한으로 동작해요.
systemd 서비스를 사용하면 스텝도 서비스 유닛의 User로 실행되고, 이 사용자는 설치 명령을 실행한 사용자예요.
root로 설치했다면 root로 실행돼요.
스텝에서 사용하는 명령과 파일 경로는 Agent가 실행 중인 호스트에서 접근할 수 있어야 해요.
working-directory에 지정한 경로도 호스트 파일시스템의 경로예요.
HOME은 서비스 사용자의 홈 디렉토리예요.
docker login, SSH 키, 클라우드 CLI 인증 정보도 이 홈을 기준으로 읽어요.
서비스 사용자와 다른 계정에서 로그인했다면 서비스 사용자의 홈에 인증 정보를 설정해주세요.
working-directory의 ~와 $HOME은 서비스 사용자 홈으로 해석돼요.
명령을 찾을 수 없거나 파일 접근이 거부되면, 호스트에 필요한 도구가 있는지와 Agent를 실행한 사용자의 권한을 확인해주세요.
스텝 키
스텝에서 사용할 수 있는 키는 다음과 같아요.
| 키 | 용도 |
|---|---|
id | 스텝 식별자이며, 출력 캡처 환경변수 제공에 사용 |
name | 사람이 읽을 스텝 이름 |
run | 실행할 명령 |
verbose | 상세 출력 설정 |
timeout-minutes | 스텝 실행 제한 시간 |
working-directory | 스텝의 호스트 작업 디렉토리 |
env | 스텝에 추가할 환경변수 |
shell | 명령 실행에 사용할 셸 |
continue-on-error | 실패 후 다음 스텝을 계속 실행할지 설정 |
retry | 재시도 설정 |
환경변수와 PATH
스텝에는 Agent 프로세스의 환경변수와 아래 값이 전달돼요.
| 변수 | 값 |
|---|---|
PATH | Agent의 PATH 뒤에 표준 시스템 경로와 /snap/bin이 추가돼요. |
DEPLITE_WORKDIR | 해당 작업 전용 임시 디렉토리예요. |
TMPDIR, TMP | DEPLITE_WORKDIR과 같은 경로예요. |
DEPLITE_OUTPUT | id가 지정된 스텝의 출력 파일 경로예요. |
DEPLITE_OUTPUT_DIR | Workflow 전역 출력 디렉토리예요. |
DEPLITE_PARAM_<이름> | 워크플로우 params:로 전달된 값이에요. |
DEPLITE_SECRET_<이름> | 워크플로우 secrets:로 전달된 값이에요. |
systemd 기본 PATH에는 /usr/local/bin이 포함되지만 /snap/bin은 없으므로 Agent가 표준 경로를 덧붙여요.
YAML에 export PATH를 추가하지 않아도 돼요.
워크플로우 env:에 PATH를 지정하면 기본 PATH보다 우선해요.
스텝의 env: 값은 워크플로우 값을 덮어써요.
시크릿과 추가 환경변수는 <데이터 디렉토리>/agent.env에 KEY=value 형식으로 둘 수 있어요.
파일 권한은 0600으로 설정해주세요.
수정한 뒤에는 systemctl restart deplite-agent를 실행해주세요.
자세한 설정은 Agent 운영을 참고해주세요.
Deplite는 params 값을 run 문자열에 직접 보간하지 않아요.
각 param은 DEPLITE_PARAM_* 환경변수로만 전달돼요.
워크플로우 출력 문서
실패 기록과 실행 문제 확인
스텝이 실패하거나 제한 시간을 넘기면 실행 환경을 확인할 수 있는 로그가 남아요.
다음 예시에서 셸, 작업 디렉토리, 사용자 ID, PATH를 확인할 수 있어요.
step context: shell=/bin/sh cwd=/srv/app uid=1000 PATH=/usr/local/bin:/usr/bin:...command not found가 나타나면 명령이 호스트에 설치되어 있고 서비스 사용자가 실행할 수 있는지 확인해주세요.
로그인 또는 인증에 실패하면 서비스 사용자 계정의 홈에 자격증명이 있는지 확인해주세요.
경로 오류가 발생하면 working-directory가 호스트에서 유효하고 접근 가능한 경로인지 확인해주세요.
시크릿 값을 확인해야 한다면 Workflow에 해당 시크릿 이름이 선언되어 있는지 살펴봐주세요.