REST API로 자동화하기

애플리케이션이 수행하는 자동화 작업에는 서비스 토큰을 사용합니다. 이 예제에서는 토큰에 접근 권한이 있는 서버 목록을 읽습니다. 요청과 응답 필드는 서버 API 참조를 확인하세요.

애플리케이션과 토큰 준비

server:read scope를 가진 애플리케이션과 서비스 토큰을 만드세요. 작업에 필요한 서버에만 접근을 허용합니다. 다른 작업에 필요한 scope는 scope 참조에서 확인할 수 있습니다. 개인 API 토큰은 소유자의 권한으로 작동하며, 새 토큰에는 명령 실행이나 파일 전송 scope를 부여할 수 없습니다.

서비스 토큰을 안전하게 보관하세요. 승인을 기다리는 토큰은 활성화된 뒤에 요청에 사용합니다. 토큰이 만료되었거나 허용된 IP 또는 시간 범위를 벗어나도 요청이 거부됩니다.

인증하기

워크스페이스 URL과 토큰을 Authorization 헤더에 넣습니다. 예시 값을 실제 값으로 바꾸세요. token은 소문자로 써야 하며 Bearer 형식은 사용할 수 없습니다.

bash
export ALPACON_URL='https://your-workspace.ap1.alpacon.io'
read -r -s -p 'Service token: ' SERVICE_TOKEN
printf '\n'
curl --fail-with-body --silent --show-error \
  "$ALPACON_URL/api/servers/servers/?page_size=15" \
  -H "Authorization: token=\"$SERVICE_TOKEN\""

응답 읽기

응답의 results에 서버가 들어 있고, next에는 다음 페이지 번호가 표시됩니다. next가 null이 될 때까지 해당 페이지를 요청하세요. 페이지 형식과 상태 코드는 API 개요를 확인하세요. 일부 서버만 필요하다면 서버 목록 필터를 사용합니다.

명령 실행이나 파일 전송에는 필요한 scope와 접근 규칙을 갖춘 서비스 토큰을 사용하세요. 요청 필드는 명령 API 또는 해당 파일 API 참조를 확인합니다. 토큰의 서버 접근 범위와 명령 또는 파일 규칙도 적용됩니다.

만료와 요청 거부 처리

401 응답이 오면 토큰의 활성화 상태와 만료 시점, 허용 IP와 시간 범위를 확인하세요. 403이면 scope나 다른 접근 규칙이 부족할 수 있습니다. 응답에 code, gate, missing이 있다면 해당 필드를 확인합니다. 요청 횟수 제한에는 Retry-After를 따르세요. 자동화 분기는 사람이 읽는 message나 hint가 아닌 구조화된 필드로 판단합니다. 자세한 내용은 API 거부 응답을 확인하세요.

API로 명령 실행하기

명령 자동화에는 ci-deploy 같은 애플리케이션 계정을 만들고, 필요한 명령 scope를 가진 서비스 토큰을 발급하세요. 대상 서버와 실행할 명령 전체를 토큰의 접근 규칙에 허용하고, 이 계정이 배포 디렉터리를 사용할 수 있도록 준비합니다. 다음은 명령 API 예제입니다.

bash
curl --fail-with-body --silent --show-error \
  -X POST "$ALPACON_URL/api/events/commands/" \
  -H "Authorization: token=\"$SERVICE_TOKEN\"" \
  -H 'Content-Type: application/json' \
  -d '{"server":"7e3984de-49ab-4cc6-bcdf-21fbd35858b8","line":"deploy","username":"ci-deploy","purpose":"Run the approved deployment"}'

API가 요청을 받아도 명령은 승인이나 계정 준비를 기다릴 수 있습니다. 명령 기록에서 최종 상태를 확인하세요. 규칙이 명령 전체와 어떻게 일치하는지는 서비스 토큰 명령 가이드를 참고하세요.

같은 작업을 CLI로 실행할 수도 있습니다.

bash
alpacon exec ci-deploy@production "cd /app && git pull && npm install && pm2 restart"
for server in web1 web2 web3; do
  alpacon exec "ci-deploy@$server" "sudo systemctl restart nginx"
done

두 번째 예제에는 sudo systemctl restart nginx 전체 명령과 일치하는 규칙이 필요합니다. Alpacon Cloud에서는 워크스페이스 sudo 설정이 허용하는 경우 서비스 토큰 실행의 기본 규칙에 따라 위험도가 심각 미만인 서비스 토큰 sudo를 허용하지만, 더 엄격한 워크스페이스 규칙이 있으면 거부될 수 있습니다. 기본 설정의 자체 호스팅 환경에서는 서비스 토큰 sudo를 거부합니다. 정확한 판단 조건은 접근 규칙 참조를 확인하세요.

최종 수정: