--- title: "에이전트 업그레이드 API" description: "API로 Alpacon 에이전트 업그레이드 이력을 조회하는 방법을 안내합니다. 서버별 또는 워크스페이스 전체의 자동·수동 업그레이드를 결과, 버전, 시작한 주체와 함께 확인할 수 있습니다." --- > Full documentation index: https://docs.alpacax.com/llms.ko.txt # 에이전트 업그레이드 **엔드포인트**: `/api/servers/servers/{server_id}/agent-upgrades/`, `/api/servers/agent-upgrades/` 워크스페이스의 [에이전트 업데이트 정책](/use/workspace/settings/agent-updates/)에 따라 시작된 자동 업그레이드와 [에이전트 카드](/use/servers/manage/#에이전트-카드) 또는 [`upgrade_agent` 작업](/reference/api/servers/servers/#에이전트-작업)으로 시작된 수동 업그레이드 기록을 모두 조회합니다. 콘솔의 [업그레이드 이력](/use/servers/manage/#업그레이드-이력)에도 같은 기록이 표시됩니다. 두 엔드포인트는 읽기 전용입니다. 서버 목록과 마찬가지로 호출자가 볼 수 있는 서버의 기록만 반환하며, API 토큰에는 [`server:read`](/reference/scopes/#server-read) 범위가 필요합니다. 업그레이드 이력 기능이 도입된 뒤의 기록만 포함되며 이전 업그레이드는 포함되지 않습니다. ## 서버별 업그레이드 목록 서버 한 대의 에이전트 업그레이드를 최신순으로 조회합니다. ### 요청 ```http GET /api/servers/servers/{server_id}/agent-upgrades/ ``` ### 경로 매개변수 | 매개변수 | 유형 | 필수 여부 | 설명 | |-----------|------|----------|-------------| | `server_id` | UUID | 예 | 서버 ID | ### 쿼리 매개변수 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `page` | 정수 | 페이지 번호 | | `page_size` | 정수 | 페이지당 결과 수(기본값: 15, 최대: 100) | 호출자가 볼 수 없는 서버를 요청하면 `404`가 반환됩니다. ### 응답 ```json { "count": 2, "next": null, "previous": null, "results": [ { "id": "3b1f6f0e-8a52-4c1d-9d6e-5f2a7c9e1b40", "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8", "server_name": "web-server-01", "from_version": "1.4.2", "target_version": "1.5.0", "to_version": "1.5.0", "outcome": "success", "error_class": null, "detail": null, "requested_at": "2026-09-21T02:14:05Z", "acknowledged_at": "2026-09-21T02:14:07Z", "reported_at": "2026-09-21T02:19:40Z", "origin": "scheduled", "policy_mode": "latest", "initiator": { "kind": "policy", "id": null, "label": "Alpacon automatic policy (latest)" } }, { "id": "a0c4d2b7-19e3-4f56-8b0a-2d7e6c1f9a33", "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8", "server_name": "web-server-01", "from_version": "1.4.1", "target_version": null, "to_version": "1.4.1", "outcome": "failed", "error_class": "download_failed", "detail": null, "requested_at": "2026-09-14T09:30:12Z", "acknowledged_at": "2026-09-14T09:30:13Z", "reported_at": "2026-09-14T09:31:02Z", "origin": "manual", "policy_mode": null, "initiator": { "kind": "user", "id": "a540bf0f-8b37-4f03-8546-dd71c6b03329", "label": "admin" } } ] } ``` 각 필드의 의미는 [필드](#필드)를 참고하세요. ### 예시 ```bash curl -X GET "https://your-workspace.ap1.alpacon.io/api/servers/servers/7e3984de-49ab-4cc6-bcdf-21fbd35858b8/agent-upgrades/" \ -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" ``` ## 서버 전체의 업그레이드 목록 호출자가 볼 수 있는 모든 서버의 에이전트 업그레이드를 최신순으로 조회합니다. ### 요청 ```http GET /api/servers/agent-upgrades/ ``` ### 쿼리 매개변수 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `server` | UUID | 서버 ID로 필터링 | | `outcome` | 문자열 | 결과로 필터링: `pending`, `success`, `rolled_back`, `failed`, `timed_out`, `refused` | | `origin` | 문자열 | 자동 업그레이드는 `scheduled`, 수동 업그레이드는 `manual` | | `error_class` | 문자열 | 오류 분류로 필터링([필드](#필드) 참고) | | `requested_at_after` | 날짜·시간 | 이 시각 이후 또는 이 시각에 요청된 업그레이드만 조회 | | `requested_at_before` | 날짜·시간 | 이 시각 이전 또는 이 시각에 요청된 업그레이드만 조회 | | `search` | 문자열 | 서버 이름과 버전에서 검색 | | `ordering` | 문자열 | `requested_at` 또는 `reported_at`; 내림차순은 `-` 사용. 기본값: `-requested_at` | | `page` | 정수 | 페이지 번호 | | `page_size` | 정수 | 페이지당 결과 수(기본값: 15, 최대: 100) | ### 응답 [서버별 업그레이드 목록](#서버별-업그레이드-목록)과 같은 형식의 페이지별 목록을 반환합니다. ### 예시 ```bash curl -X GET "https://your-workspace.ap1.alpacon.io/api/servers/agent-upgrades/?outcome=failed&requested_at_after=2026-09-01T00:00:00Z" \ -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" ``` ## 필드 | 필드 | 유형 | 설명 | |-------|------|-------------| | `id` | UUID | 업그레이드 기록 ID | | `server` | UUID | 서버 ID | | `server_name` | 문자열 | 서버 이름 | | `from_version` | 문자열 또는 `null` | 업그레이드 전 에이전트 버전 | | `target_version` | 문자열 또는 `null` | 에이전트에 설치를 요청한 릴리스. 특정 릴리스 대신 최신 버전으로 업그레이드하라는 일반 요청을 보냈다면 `null` | | `to_version` | 문자열 또는 `null` | 업그레이드 후 에이전트 버전. 에이전트가 결과를 보고하기 전까지는 `null` | | `outcome` | 문자열 | `pending`(진행 중), `success`(성공), `rolled_back`(새 버전이 정상적으로 시작되지 않아 에이전트가 이전 버전으로 돌아감), `failed`(실패), `timed_out`(에이전트가 제때 확인하지 않음), `refused`(에이전트에 전달되기 전에 요청이 철회됨) | | `error_class` | 문자열 또는 `null` | 업그레이드가 적용되지 않은 이유. 오류가 없으면 `null` | | `detail` | 문자열 또는 `null` | 업그레이드가 거부된 이유 등 Alpacon이 제공하는 간단한 설명 | | `requested_at` | 날짜·시간 | 업그레이드를 요청한 시각 | | `acknowledged_at` | 날짜·시간 또는 `null` | 에이전트가 업그레이드를 받은 시각 | | `reported_at` | 날짜·시간 또는 `null` | 에이전트가 결과를 보고한 시각 | | `origin` | 문자열 | 자동 업그레이드는 `scheduled`, 멤버나 토큰이 시작한 업그레이드는 `manual` | | `policy_mode` | 문자열 또는 `null` | 자동 업그레이드에 적용된 업데이트 정책(`latest` 또는 `n_minus_1`). 수동 업그레이드는 `null` | | `initiator` | 객체 | 업그레이드를 시작한 주체(아래 참고) | `initiator`는 업그레이드 요청 시점에 저장한 정보이므로, 멤버나 토큰이 삭제된 뒤에도 이름이 남습니다. | 필드 | 유형 | 설명 | |-------|------|-------------| | `kind` | 문자열 | 자동 업그레이드는 `policy`, 수동 업그레이드는 `user` 또는 `token` | | `id` | 문자열 또는 `null` | 사용자 또는 토큰 ID. `policy`이면 `null` | | `label` | 문자열 | 업그레이드를 시작한 주체의 이름: 멤버의 사용자 이름, 토큰 이름 또는 `Alpacon automatic policy (latest)`(`n_minus_1` 정책에서는 `(N-1)`). 한국어로 요청하면 `Alpacon 자동 정책 (latest)` | `error_class` 값과 콘솔에 표시되는 이름은 다음과 같습니다. | 값 | 콘솔 표시 이름 | 의미 | |-------|---------------|---------| | `signature_invalid` | 서명 불일치 | 릴리스의 서명을 검증하지 못해 에이전트가 설치하지 않음 | | `digest_mismatch` | 다이제스트 불일치 | 다운로드한 패키지가 게시된 체크섬과 일치하지 않음 | | `download_failed` | 다운로드 실패 | 에이전트가 릴리스를 다운로드하지 못함 | | `swap_failed` | 교체 실패 | 에이전트가 바이너리를 새 버전으로 교체하지 못함 | | `health_check_failed` | 상태 확인 실패 | 새 버전이 상태 확인을 통과하지 못함 | | `package_manager` | 패키지 관리자 오류 | 시스템 패키지 관리자에서 오류가 발생함 | | `window_closed` | 유지보수 시간대 밖 | 업그레이드가 에이전트에 도달하기 전에 유지보수 시간대가 닫힘 | | `keys_unavailable` | Alpacon 설정 문제로 조치할 필요 없어요 | Alpacon 측 문제로 서버에서 변경할 사항이 없으며 알림도 발생하지 않음 | | `unknown` | 알 수 없음 | 원인을 알 수 없는 실패 | 업그레이드가 실패하거나 롤백되면 `keys_unavailable`을 제외하고 서버에 경고 [업그레이드 실패 알림](/use/servers/manage/#업그레이드-실패-알림)이 발생합니다. 각 업그레이드는 전송 시점과 종료 시점에 [활동 로그](/use/audit/governance/activity-log/)에도 기록됩니다. ## 오류 응답 | 상태 | 오류 코드 | 설명 | |--------|------------|-------------| | 401 | — | 인증 정보가 잘못되었거나 없음. 오류 코드 없이 `{"detail": "..."}` 응답이 반환됨 | | 403 | `api_token_scope_missing` | API 토큰에 `server:read` 범위가 없음 | | 404 | — | 서버를 찾을 수 없거나 호출자에게 보이지 않음. 오류 코드 없이 `{"detail": "..."}` 응답이 반환됨 | Source: https://docs.alpacax.com/ko/reference/api/servers/agent-upgrades/