스텝 실행 환경

워크플로우의 각 스텝이 어느 머신에서, 어떤 환경으로 실행되는지 정리한 문서예요.
특히 Agent를 Docker로 운용한다면, 스텝이 컨테이너 안이 아니라 호스트에서 실행될 수 있다는 점을 먼저 확인해주세요.

두 가지 실행 모드

실제 배포 스텝은 대부분 docker·ssh·클라우드 CLI 같은 호스트 도구를 호출해요.
Agent 이미지에 기본으로 들어 있는 건 sh·nsenter·ca-certificates·tini뿐이라, 컨테이너 실행 모드에서는 그런 스텝이 종료 코드 127로 실패해요.
그래서 호스트 실행이 권장 구성이고, 컨테이너 실행은 권한을 줄 수 없는 제약 환경에서 스텝이 이미지 안 도구만 쓰는 경우의 대안이에요.

다음처럼 띄우면 호스트 실행 모드로 동작해요.

services:
  deplite-agent:
    image: ghcr.io/deplite/agent:latest
    restart: unless-stopped
    pid: host
    privileged: true
    environment:
      DEPLITE_INSTALL_CODE: <1회용_설치_코드>
    volumes:
      - ./workflows:/workflows:ro
      - ./credentials:/credentials
      - /var/run/docker.sock:/var/run/docker.sock

모드는 어떻게 결정되나요

Agent는 시작할 때 아래 프로브를 실행해서 호스트 네임스페이스로 진입할 수 있는지 확인하고, 결정된 모드를 시작 로그에 남겨요.

nsenter --target 1 --mount --uts --ipc --net --pid -- true

DEPLITE_HOST_EXEC 환경변수로 직접 지정할 수도 있어요.
1·true면 호스트 실행, 0·false면 컨테이너 실행이에요.

호스트 실행일 때 유의할 점

이 모드에서 스텝이 쓰는 명령·자격증명·경로는 모두 호스트 기준이에요.

명령어

스텝이 호출하는 도구는 호스트에 설치되어 있어야 해요.
Agent 컨테이너 이미지에 포함된 도구는 스텝에서 쓰이지 않아요.

자격증명

docker login, SSH 키, 클라우드 CLI 로그인 등은 호스트 사용자 세션의 것이 쓰여요.
컨테이너 안에서 로그인해도 스텝에는 반영되지 않으니, 호스트에서 미리 로그인해주세요.

작업 디렉토리

working-directory는 호스트 파일시스템의 경로로 해석돼요.
컨테이너에 마운트한 경로가 아니라, 호스트에서 보이는 실제 경로를 적어주세요.

환경변수와 PATH

스텝은 Agent 프로세스의 환경변수를 물려받은 뒤, 아래 값이 추가된 상태로 실행돼요.

PATH에 표준 경로가 덧붙는 건, 호스트 실행 모드에서 Agent가 물려받은 PATH가 컨테이너 이미지 기준이라 snap 패키지 같은 호스트 도구를 찾지 못하는 경우를 막기 위해서예요.
기존 항목의 순서는 그대로 유지되니, 워크플로우의 env:에서 PATH를 직접 지정하면 그 값이 우선해요.

전체 환경변수 우선순위는 워크플로우 YAML 스펙에서 다뤄요.

스텝이 실패했을 때

스텝이 실패하거나 시간을 초과하면 시스템 로그에 실행 컨텍스트가 함께 기록돼요.

step context: mode=host namespace shell=/bin/sh cwd=/srv/app uid=0 PATH=/usr/local/sbin:/usr/local/bin:...

mode가 예상과 다르거나, 찾지 못한 명령의 설치 경로가 PATH에 없다면 위 내용을 다시 확인해주세요.

자주 발생하는 경우는 다음과 같아요.

관련 문서