edge

엣지 플릿 관리, 디바이스 토큰 및 디바이스 인증 기반 자가 등록/하트비트.

이 태그에는 인증 방식이 다른 두 부류가 섞여 있음.

• 플릿 관리 API: 사용자 세션(JWT/쿠키) + X-Tenant + RBAC 권한이 필요. (/fleet, /devices/*, 토큰 발급/회전/폐기, 재시작, 모델 배포 /devices/{id}/deployments)
• 인제스트 API: 사용자 로그인 없이 X-Edge-Token 디바이스 토큰만으로 호출. (/register, /heartbeat, /containers/pull, /models*)

How-To: 엣지 디바이스 온보딩 & 인제스트 호출#

1. 디바이스 등록 (관리자, 1회): 관리자(ADMIN)가 POST /api/v1/edge/devices 로 디바이스를 만들면 응답으로 평문 토큰이 단 한 번 반환됨({"id", "token"}). 서버에는 HMAC-SHA256 해시만 저장되므로 이 토큰을 디바이스에 안전하게 보관하세요. 분실 시 POST /api/v1/edge/devices/{id}/token:rotate 로 재발급.
2. 디바이스에 토큰 설치: 이후 모든 인제스트 요청은 X-Edge-Token: <token> 헤더로 전송. 사용자 로그인/X-Tenant 헤더는 필요 없으며, 테넌트는 토큰에 바인딩되어 자동 적용됨.
3. 자가 등록 핸드셰이크: 부팅 시 POST /api/v1/edge/register 를 호출해 os/sdk_version/location 메타데이터를 갱신하고 디바이스를 ACTIVE로 표시.
4. 텔레메트리 전송: 주기적으로 POST /api/v1/edge/heartbeat 로 cpu/gpu/mem/disk 지표 전송. (토큰에 telemetry:write 스코프 필요)
5. 모델 컨테이너 풀: GET /api/v1/edge/containers/pull?model=&version= 로 배포할 이미지 참조 수신. (토큰에 container:pull 스코프 필요)
6. 모델 조회 & 다운로드: GET /api/v1/edge/models 로 테넌트에 등록된 모델 목록을, GET /api/v1/edge/models/{name}/versions 로 버전 이력을 조회하고, GET /api/v1/edge/models/{name}/{version}/download 로 아티팩트를 내려받음. (토큰에 models:read 스코프 필요)

토큰 스코프: 발급 시 기본값은 telemetry:write, inference:write, container:pull, models:read . 엔드포인트가 요구하는 스코프가 토큰에 없으면 403이 반환됨. 만료(기본 365일)·폐기된 토큰은 401.

Swagger UI에서는 상단 Authorize 버튼의 EdgeToken 항목에 토큰을 입력하면 인제스트 엔드포인트를 바로 시험해 볼 수 있음.

GET /api/v1/edge/fleet#

GET/api/v1/edge/fleet

플릿 상태

호출자의 테넌트에 속한 모든 엣지 디바이스를 파생 상태 및 최신 텔레메트리 스냅샷(cpu/gpu/mem, 마지막 하트비트)과 함께 나열.

필요 권한: VIEW

파라미터

응답

GET /api/v1/edge/devices/{device_id}#

GET/api/v1/edge/devices/{device_id}

디바이스 상세

단일 디바이스의 전체 상세 정보 반환: 파생 상태, OS/SDK 메타데이터, 최신 리소스 스냅샷, 배포된 컨테이너 목록.

필요 권한: VIEW

파라미터

응답

PATCH /api/v1/edge/devices/{device_id}#

PATCH/api/v1/edge/devices/{device_id}

디바이스 정보 수정

디바이스의 설치 위치 변경.

필요 권한: SETTINGS

파라미터

요청 본문: application/json, DeviceUpdate

응답

DELETE /api/v1/edge/devices/{device_id}#

DELETE/api/v1/edge/devices/{device_id}

디바이스 삭제

디바이스와 그에 딸린 모든 기록을 영구 삭제.

필요 권한: SETTINGS

파라미터

응답

GET /api/v1/edge/devices/{device_id}/logs#

GET/api/v1/edge/devices/{device_id}/logs

디바이스 로그

디바이스의 하트비트 페이로드를 최신순 로그 피드로 반환.

필요 권한: OPERATE

파라미터

응답

POST /api/v1/edge/devices#

POST/api/v1/edge/devices

디바이스 + 토큰 등록

호출자의 테넌트 아래에 새 엣지 디바이스를 프로비저닝하고 첫 번째 액세스 토큰 발급.

필요 권한: SETTINGS

요청 본문: application/json, DeviceCreate

응답

POST /api/v1/edge/devices/{device_id}/token:rotate#

POST/api/v1/edge/devices/{device_id}/token:rotate

디바이스 토큰 회전

엣지 디바이스에 새 액세스 토큰을 발급하고 기존 토큰 무효화.

필요 권한: SETTINGS

파라미터

응답

POST /api/v1/edge/devices/{device_id}/token:revoke#

POST/api/v1/edge/devices/{device_id}/token:revoke

디바이스 토큰 폐기

디바이스의 모든 활성 토큰을 폐기하여 인제스트 접근 차단.

필요 권한: SETTINGS

파라미터

응답

PATCH /api/v1/edge/devices/{device_id}/token:scopes#

PATCH/api/v1/edge/devices/{device_id}/token:scopes

디바이스 토큰 스코프 수정

디바이스의 활성 토큰에 부여된 스코프를 토큰 재발급 없이 교체.

필요 권한: SETTINGS

파라미터

요청 본문: application/json, ScopesUpdate

응답

POST /api/v1/edge/devices/{device_id}/restart#

POST/api/v1/edge/devices/{device_id}/restart

디바이스 재시작

대상 디바이스에 대한 재시작 명령을 큐에 등록.

필요 권한: OPERATE

파라미터

응답

POST /api/v1/edge/devices/{device_id}/offline#

POST/api/v1/edge/devices/{device_id}/offline

디바이스 오프라인 차단

대상 디바이스를 서버에서 끊거나(blocked=true) 복원.

필요 권한: OPERATE

파라미터

요청 본문: application/json, OfflineUpdate

응답

POST /api/v1/edge/register#

POST/api/v1/edge/register

디바이스 자가 등록

디바이스 SDK 자가 등록 핸드셰이크.

요청 본문: application/json, RegisterBody

응답

POST /api/v1/edge/heartbeat#

POST/api/v1/edge/heartbeat

텔레메트리 하트비트

디바이스로부터 텔레메트리 하트비트 인제스트.

요청 본문: application/json, HeartbeatBody

응답

GET /api/v1/edge/containers/pull#

GET/api/v1/edge/containers/pull

컨테이너 이미지 해석

디바이스가 풀할 수 있도록 모델 버전에 대한 완전한 형식의 컨테이너 이미지 참조 해석.

파라미터

응답

GET /api/v1/edge/models#

GET/api/v1/edge/models

등록 모델 목록 (디바이스 토큰)

디바이스가 자신의 테넌트에 등록된 모델 목록 조회.

응답

GET /api/v1/edge/models/{name}/versions#

GET/api/v1/edge/models/{name}/versions

모델 버전 이력 (디바이스 토큰)

디바이스가 등록 모델의 버전 이력 조회.

파라미터

응답

GET /api/v1/edge/models/{name}/{version}/download#

GET/api/v1/edge/models/{name}/{version}/download

모델 버전 아티팩트 다운로드 (디바이스 토큰)

디바이스가 모델 버전의 아티팩트를 파일로 내려받음.

파라미터

응답

POST /api/v1/edge/telemetry#

POST/api/v1/edge/telemetry

텔레메트리 배치 인제스트

오프라인 동안 누적된 구조화 레코드를 한 번에 수신.

요청 본문: application/json, TelemetryBatch

응답

POST /api/v1/edge/inference#

POST/api/v1/edge/inference

추론 결과 배치 인제스트

엣지에서 수행한 추론 결과를 배치로 수신.

요청 본문: application/json, InferenceBatch

응답

POST /api/v1/edge/uploads#

POST/api/v1/edge/uploads

파일 업로드 세션 시작

재개 가능한 파일 전송 시작.

요청 본문: application/json, UploadInit

응답

GET /api/v1/edge/uploads/{upload_id}#

GET/api/v1/edge/uploads/{upload_id}

업로드 재개 지점 조회

재시작한 디바이스가 "어디까지 받았나" 를 묻는 자리.

파라미터

응답

PUT /api/v1/edge/uploads/{upload_id}/chunks/{index}#

PUT/api/v1/edge/uploads/{upload_id}/chunks/{index}

업로드 청크 전송

청크 하나 전송 (application/octet-stream).

파라미터

응답

POST /api/v1/edge/uploads/{upload_id}:complete#

POST/api/v1/edge/uploads/{upload_id}:complete

업로드 마감

모든 청크가 도착했음을 알리고 즉시 응답 (202).

파라미터

응답

GET /api/v1/edge/commands#

GET/api/v1/edge/commands

명령 롱폴 수신

대기 중인 명령 조회. 없으면 최대 wait 초 대기.

파라미터

응답

POST /api/v1/edge/commands/{command_id}:ack#

POST/api/v1/edge/commands/{command_id}:ack

명령 처리 결과 보고

명령 처리 결과 보고.

파라미터

요청 본문: application/json, CommandAck

응답

GET /api/v1/edge/config#

GET/api/v1/edge/config

디바이스 정책 조회

이 디바이스에 적용되는 정책(보존·동기화·주기) 반환.

응답

GET /api/v1/edge/devices/{device_id}/telemetry#

GET/api/v1/edge/devices/{device_id}/telemetry

디바이스 텔레메트리 조회

디바이스가 올린 구조화 레코드를 최신순으로 조회 (VIEW).

파라미터

응답

GET /api/v1/edge/devices/{device_id}/inference#

GET/api/v1/edge/devices/{device_id}/inference

디바이스 추론 결과 조회

디바이스가 올린 추론 결과를 최신순으로 조회 (VIEW).

파라미터

응답

GET /api/v1/edge/devices/{device_id}/uploads#

GET/api/v1/edge/devices/{device_id}/uploads

디바이스 업로드 목록

디바이스가 올린(또는 올리는 중인) 파일 전송 나열 (VIEW).

파라미터

응답

GET /api/v1/edge/devices/{device_id}/commands#

GET/api/v1/edge/devices/{device_id}/commands

디바이스 명령 이력

이 디바이스에 내린 명령과 그 결과 나열 (VIEW).

파라미터

응답

POST /api/v1/edge/devices/{device_id}/commands#

POST/api/v1/edge/devices/{device_id}/commands

디바이스 명령 큐잉

디바이스가 다음 폴링 때 가져갈 명령을 큐에 등록 (OPERATE).

파라미터

요청 본문: application/json, CommandCreate

응답

GET /api/v1/edge/devices/{device_id}/policy#

GET/api/v1/edge/devices/{device_id}/policy

디바이스 정책 조회

적용 중인 정책과 리비전 반환 (VIEW).

파라미터

응답

PUT /api/v1/edge/devices/{device_id}/policy#

PUT/api/v1/edge/devices/{device_id}/policy

디바이스 정책 변경

정책을 바꾸고 리비전 갱신 (SETTINGS).

파라미터

요청 본문: application/json, PolicyUpdate

응답

GET /api/v1/edge/devices/{device_id}/models#

GET/api/v1/edge/devices/{device_id}/models

디바이스 모델 현황

기대 모델(가장 최근 배포)과 장비가 마지막 하트비트에서 보고한 모델을 합쳐 반환 (VIEW).

파라미터

응답

GET /api/v1/edge/devices/{device_id}/deployments#

GET/api/v1/edge/devices/{device_id}/deployments

디바이스 모델 배포 이력

이 디바이스에 내린 모델 배포와 그 진행을 최신순으로 나열 (VIEW).

파라미터

응답

POST /api/v1/edge/devices/{device_id}/deployments#

POST/api/v1/edge/devices/{device_id}/deployments

디바이스에 모델 배포

이 디바이스가 모델 버전을 받아 활성화하도록 배포 생성 (DEPLOY).

파라미터

요청 본문: application/json, EdgeDeploymentCreate

응답

GET /api/v1/edge/devices/{device_id}/deployments/{deployment_id}#

GET/api/v1/edge/devices/{device_id}/deployments/{deployment_id}

모델 배포 상세

배포 한 건과, 그것을 실어 나른 명령의 요약 반환 (VIEW).

파라미터

응답

POST /api/v1/edge/devices/{device_id}/deployments/{deployment_id}:rollback#

POST/api/v1/edge/devices/{device_id}/deployments/{deployment_id}:rollback

모델 배포 되돌리기

그 배포가 요청될 때 장비가 돌리고 있던 모델로 복원 (ROLLBACK).

파라미터

응답

POST /api/v1/edge/devices/{device_id}/models:reapply#

POST/api/v1/edge/devices/{device_id}/models:reapply

기대 모델 다시 적용

장비가 기대 모델과 다른 것을 돌리고 있을 때(drift) 기대 모델을 다시 배포 (DEPLOY). drift 가 아니면 409 .

파라미터

응답

POST /api/v1/edge/devices/{device_id}/models/{name}/{version}:remove#

POST/api/v1/edge/devices/{device_id}/models/{name}/{version}:remove

디바이스 캐시에서 모델 삭제

장비의 모델 캐시에서 한 버전을 지우는 remove_model 명령 큐잉 (OPERATE). 기대 모델이거나 장비가 활성으로 보고한 모델이면 409 . 배포 행은 만들지 않음. 결과는 명령 탭에서 조회.

파라미터

응답