에이전트 업그레이드

엔드포인트: /api/servers/servers/{server_id}/agent-upgrades/, /api/servers/agent-upgrades/

워크스페이스의 에이전트 업데이트 정책에 따라 시작된 자동 업그레이드와 에이전트 카드 또는 upgrade_agent 작업으로 시작된 수동 업그레이드 기록을 모두 조회합니다. 콘솔의 업그레이드 이력에도 같은 기록이 표시됩니다.

두 엔드포인트는 읽기 전용입니다. 서버 목록과 마찬가지로 호출자가 볼 수 있는 서버의 기록만 반환하며, API 토큰에는 server:read 범위가 필요합니다. 업그레이드 이력 기능이 도입된 뒤의 기록만 포함되며 이전 업그레이드는 포함되지 않습니다.

서버 한 대

서버별 업그레이드 목록

서버 한 대의 에이전트 업그레이드를 최신순으로 조회합니다.

요청

GET /api/servers/servers/{server_id}/agent-upgrades/

경로 매개변수

매개변수	유형	필수 여부	설명
`server_id`	UUID	예	서버 ID

쿼리 매개변수

매개변수	유형	설명
`page`	정수	페이지 번호
`page_size`	정수	페이지당 결과 수(기본값: 15, 최대: 100)

호출자가 볼 수 없는 서버를 요청하면 404가 반환됩니다.

응답

{
  "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"
      }
    }
  ]
}

각 필드의 의미는 필드를 참고하세요.

예시

curl -X GET "https://your-workspace.ap1.alpacon.io/api/servers/servers/7e3984de-49ab-4cc6-bcdf-21fbd35858b8/agent-upgrades/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

전체 서버

서버 전체의 업그레이드 목록

호출자가 볼 수 있는 모든 서버의 에이전트 업그레이드를 최신순으로 조회합니다.

요청

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)

응답

서버별 업그레이드 목록과 같은 형식의 페이지별 목록을 반환합니다.

예시

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을 제외하고 서버에 경고 업그레이드 실패 알림이 발생합니다. 각 업그레이드는 전송 시점과 종료 시점에 활동 로그에도 기록됩니다.

오류 응답

상태	오류 코드	설명
401	—	인증 정보가 잘못되었거나 없음. 오류 코드 없이 `{"detail": "..."}` 응답이 반환됨
403	`api_token_scope_missing`	API 토큰에 `server:read` 범위가 없음
404	—	서버를 찾을 수 없거나 호출자에게 보이지 않음. 오류 코드 없이 `{"detail": "..."}` 응답이 반환됨