자동화 오류 해결

먼저 HTTP 상태와 code를 확인하고, 요청이 접수되었다면 명령어 결과를 확인하세요. 코드가 있는 API 오류에는 code가 포함되고, 입력 검증 오류에는 field_errors도 포함될 수 있습니다. 일부 거부 응답에는 gate와 missing이 있지만 모든 오류에 있는 것은 아닙니다. 설정 절차는 서비스 토큰, 연결 옵션은 Ansible을 참고하세요.

이전 CLI에서 로그인 중 401 발생#

v1.7.4보다 오래된 CLI는 로그인 시 alpst- 키를 받아들인 뒤 사용자 프로필 확인에 실패할 수 있습니다. 요청은 401 auth_token_missing을 반환하며 이전 CLI는 다음 메시지를 출력합니다.

Login succeeded but failed to verify user profile: request denied by server. Please try logging in again.

Alpacon CLI v1.7.4 이상을 사용하고 작업 컨테이너나 러너 안의 버전을 확인하세요. 키는 alpacon login ... -t "$ALPACON_SERVICE_TOKEN"으로 전달합니다. CLI는 ALPACON_URL이나 ALPACON_TOKEN을 읽지 않습니다. 이 환경 변수는 Ansible 연결에 사용합니다.

토큰 승인 대기 중 202 발생#

승인이 필요한 서비스 토큰을 생성하면 202가 반환됩니다. 응답에는 key, status: "pending_approval", risk_level, risk_details(각 항목에 scope, reason, level 포함), approval_request_id가 있습니다. 이때 받은 키는 아직 사용할 수 없으며 승인 전까지 401 auth_authentication_failed가 반환됩니다.

admin 역할이 있는 계정이 웹 콘솔에서 위험도가 낮은 scope를 요청한 경우에만 즉시 활성화됩니다. 명령어와 파일 전송 scope는 항상 승인을 기다립니다. 웹 콘솔에서 슈퍼유저나 해당 요청의 승인자에게 승인을 요청하세요. 작업을 시작하기 전에 GET /api/auth/service-tokens/tokens/{id}/에서 activation_state: "active"와 enabled: true를 확인하세요.

보안 설정 변경도 status, risk_level, risk_details, approval_request_id가 포함된 202를 반환하지만 키는 포함하지 않습니다. 승인 전까지 기존 설정이 적용됩니다. 다른 변경이 이미 승인 대기 중이면 400 service_token_update_pending이 반환되므로 먼저 기존 요청을 처리하거나 취소하세요.

사람의 승인을 기다리는 명령어는 명령어 기록에 status: "awaiting_approval"로 표시됩니다. 토큰 생성의 202와는 다릅니다. 웹 콘솔에서 기존 명령어를 검토하세요.

권한 부족으로 403 발생#

토큰에 scope가 없으면 다음 응답을 받을 수 있습니다.

{
  "code": "api_token_scope_missing",
  "gate": "token_scope",
  "missing": "scope:command:create"
}

missing은 문자열 하나 또는 목록입니다. scope나 role, command_preapproval, approval, presence, work_session, plan, approved_account, other_approver, allowed_agent 등의 조건을 나타냅니다. 위 예시에서 CLI는 permission denied: missing scope scope:command:create를 출력합니다.

애플리케이션의 전역 역할과 토큰이 모두 해당 작업을 허용하는지 확인하세요. 필요한 토큰 scope 변경을 요청하고 승인을 기다리세요. 역할 때문에 거부되면 rbac_permission_required 또는 rbac_object_permission_required와 함께 gate: "role", missing: "role"이 반환됩니다. CLI에는 permission denied: missing role이 표시됩니다. 관리자에게 역할 부여 상태를 확인해 달라고 요청하세요. scope를 추가해도 계정, 승인, presence 조건이 충족되지는 않습니다.

요청 수 초과로 429 발생#

서비스 토큰의 요청 수 제한을 넘으면 429와 함께 다음 응답이 반환됩니다.

{"code": "api_rate_limited", "gate": "rate"}

Retry-After 헤더는 재시도 전 기다릴 시간을 초 단위로 알려 줍니다. 제한은 토큰별로 적용되며 별도로 설정하지 않으면 1000/hour입니다. 안내된 시간 이상 기다린 뒤 재시도하고, 동시에 실행하는 조회나 작업 요청을 줄이세요. 토큰의 요청 수 제한을 변경하려면 승인이 필요합니다.

CLI는 too many requests—please try again later를 출력하고 상태 조회 간격을 늘립니다. Ansible은 HTTP 429 오류를 즉시 반환하므로 작업에서 재시도를 처리해야 합니다. 플랜의 월간 한도를 넘으면 429가 아닌 402가 반환되며 이때도 Retry-After가 포함됩니다.

sudo 거부#

Alpacon Cloud에서는 서비스 토큰의 sudo 위험도가 심각(Critical)보다 낮거나 평가되지 않았으면 허용하고, 심각이면 거부합니다. 단, Advisory 워크스페이스에서는 위험도를 이유로 거부하지 않고 판단을 기록합니다. Advisory가 아니면 워크스페이스의 token_exec 규칙으로 위험도 기준을 더 엄격하게 정할 수 있습니다. 워크스페이스의 sudo 설정도 켜져 있어야 하며, 꺼져 있으면 workspace_sudo_with_mfa_disabled로 거부됩니다. 위험도에 따른 거부 코드는 sudo_risk_denied입니다. 전달 전에 명령어 전체가 거절되면 상태가 rejected가 됩니다. 명령어 상세에서 rejection_cause, rejection_gate, rejected_at을 확인하세요. Ansible은 rc: 1을 반환하고 stderr에 rejected를 출력합니다. 명령어는 실행되었지만 sudo에서 실패했다면 출력과 권한 상승의 거부 탭을 확인하세요.

CLI의 위험도 거부 안내는 sudo was denied by runtime risk assessment; this command is not permitted in this work session.입니다. 토큰 명령어에도 같은 문구를 사용합니다. 거부된 작업을 검토하고 애플리케이션이 실행할 수 있는 더 좁은 범위의 명령어를 사용하세요.

기본 설정의 자체 호스팅에서는 위험도와 관계없이 모든 서비스 토큰 sudo가 sudo_command_not_authorized로 거부됩니다. CLI는 이 배포 환경에서 서비스 토큰의 권한을 높일 수 없다고 안내합니다. Ansible은 토큰만 사용하므로 기본 설정의 자체 호스팅에서는 become을 사용할 수 없습니다. sudo 정책은 서비스 토큰에 적용되지 않으며 재시도해도 사람에게 sudo 승인 요청이 생성되지 않습니다.

토큰 만료나 키 교체 후 401 발생#

만료된 서비스 토큰은 401, {"code": "auth_authentication_failed"}, WWW-Authenticate: Token을 반환합니다. 잘못된 키, 비활성화·승인 대기·삭제된 토큰, 애플리케이션이 삭제된 토큰도 같은 응답을 받습니다. 응답만으로는 원인을 구분할 수 없습니다. CLI는 authentication failed: please run 'alpacon login' again을 출력합니다.

웹 콘솔에서 토큰 상태와 만료일을 확인하세요. 만료된 토큰이라면 새 토큰을 발급하고 승인을 받은 뒤 CI 시크릿을 갱신하고 재시도하세요. 키를 교체했다면 CI 시크릿도 즉시 갱신해야 합니다. 교체가 끝나는 순간 기존 키는 무효화됩니다. 만료일은 현재 시점에 교체 주기(기본 90일)를 더한 날짜로 다시 설정되므로 새 날짜도 확인하세요. 비활성화된 토큰은 다시 활성화할 때 승인이 필요합니다. 승인 대기 중이라면 승인을 마친 뒤 재시도하세요.

IP 주소나 접근 시간 거부#

401 auth_ip_not_allowed는 러너의 주소가 토큰의 허용 IP에 없다는 뜻입니다. 401 auth_access_outside_allowed_time은 UTC 기준 허용 시간대나 요일을 벗어났다는 뜻입니다. CLI는 이 오류에 request denied by server를 출력합니다.

러너의 외부 통신 IP와 실행 일정을 토큰의 제한과 비교하세요. 다른 접근 범위가 필요하면 제한 변경을 요청하세요. 변경에는 승인이 필요합니다.

자격 증명 확인 불가#

503 auth_verification_unavailable은 자격 증명이 거부된 것이 아니라 서버가 확인하지 못했다는 뜻입니다. CLI는 the server could not verify your credential right now—it was not rejected, so try again in a moment를 출력합니다. 잠시 뒤 재시도하세요.

서버 계정 오류로 400 발생#

서비스 토큰은 애플리케이션이 소유한 계정으로만 실행할 수 있습니다. 입력 검증 코드와 field_errors를 확인하세요.

Ansible에서는 ansible_user를 명시하세요. 기본값인 root는 서비스 토큰으로 사용할 수 없습니다. ACL 규칙으로 다른 계정의 소유권을 부여할 수는 없습니다.

서버 연결이나 활성화 문제#

단일 server 요청에서 대상 서버가 명령어를 받을 수 없으면 400 server_not_connected 또는 400 server_not_commissioned가 반환됩니다. 연결을 복구하거나 서버를 활성화한 뒤 재시도하세요. servers를 사용하는 요청은 연결이 끊긴 대상에도 대기열에 명령어를 넣을 수 있으므로, 접수되었다는 이유만으로 실행되었다고 판단하지 말고 각 명령어의 상태를 확인하세요.

토큰 scope가 애플리케이션 역할을 초과#

요청한 scope가 애플리케이션의 전역 역할 범위를 넘으면 토큰 생성 시 400 service_token_scope_exceeds_role이 반환됩니다. 권한이 있는 관리자에게 필요한 전역 역할 부여를 요청하거나 scope를 줄인 뒤 토큰을 다시 요청하세요. 나중에 역할을 회수하면 남은 권한을 초과하는 토큰은 비활성화되고 다음 요청에서 401이 반환됩니다.

서버, 명령어, 파일 ACL 거부#

403 api_token_acl_not_allowed는 접근 규칙이 작업을 허용하지 않는다는 뜻입니다. missing 필드는 없습니다. CLI는 denied by token access control—this token may not perform that action; review its rules with 'alpacon token acl'을 출력합니다.

서비스 토큰의 단일 서버 요청에서는 서버가 서버 ACL에 없거나 존재하지 않으면 field_errors.server에 400 does_not_exist가 반환될 수 있습니다. 서버 ID를 확인하고 토큰 승인 후 서버 규칙을 추가하세요. 파일 전송은 경로와 방향(업로드, 다운로드 또는 둘 다)을 허용해야 합니다.

Cloud에서는 사전 승인된 명령에 없는 명령어도 201로 접수된 뒤 rejected로 종료됩니다. 이때 rejection_cause는 command_acl_denied 또는 command_acl_unavailable입니다. Ansible은 이 경우에도 Command was rejected by the approval policy를 출력하므로 명령어 규칙이 없는 것은 아닌지 확인하세요. 자체 호스팅에서 명령어 ACL로 거부되면 403 api_token_acl_not_allowed가 반환됩니다. 제출한 명령어 전체 문자열이 ACL과 일치하는지 확인하세요. Cloud에서는 명령 ACL 관리자에 등록된 관리자에게 웹 콘솔의 서비스 토큰 페이지에서 사전 승인된 명령을 관리해 달라고 요청하세요. Cloud에서 API로 명령어 ACL을 변경하면 405 command_acl_moved가 반환되므로 CLI 안내에 나온 변경 작업을 반복해도 해결되지 않습니다.

명령어에 포함된 자격 증명 거부#

400 command_inline_credential은 제출한 명령어에 자격 증명이 직접 포함되어 있다는 뜻입니다. 명령어 문자열에서 자격 증명을 제거하고 작업의 시크릿 처리 방식으로 전달한 뒤 재시도하세요.

대화형 작업 거부#

403 auth_interactive_channel_requires_presence는 Websh, 터널, 브라우저 편집기 같은 대화형 작업에 토큰을 사용했다는 뜻입니다. 비대화형 명령어에는 alpacon exec를 사용하세요. 대화형 작업은 -t 없이 alpacon login으로 로그인해서 진행하세요.

워크스페이스 정지#

워크스페이스가 정지된 동안 변경 요청은 403 workspace_suspended를 반환합니다. 작업을 다시 시도하기 전에 워크스페이스 관리자에게 정지 사유를 해결해 달라고 요청하세요.

Ansible 설정이나 파일 전송 실패#

ALPACON_URL 또는 ALPACON_TOKEN이 없으면 Ansible이 필수 옵션 오류를 표시합니다. 워크스페이스 URL과 승인된 alpst- 키를 설정하세요. 서버 이름이 여러 대상과 일치하면 Multiple servers match name ...이 표시됩니다. alpacon_server_id에 대상 서버 UUID를 지정하세요. 파일 전송에는 S3 기반 스토리지가 필요하므로 재시도 전에 스토리지와 토큰의 파일 ACL을 확인하세요. 전체 연결 옵션은 Ansible을 참고하세요.