설정 레퍼런스
EdgeSettings 전 필드, 설정 파일 탐색 순서, GEO_EDGE_* 환경 변수, 크기 문자열
에이전트 설정은 EdgeSettings 하나. YAML(또는 JSON) 파일과 환경 변수로 지정.
우선순위: 환경 변수 > 파일 > 기본값
같은 키가 여러 곳에 있으면 환경 변수 우선. 토큰 같은 비밀은 /etc/geo-mlops/edge.env 에, 현장 구성(수집기·주소·보존 한도)은 edge.yaml 에 분리해 저장. 이렇게 나누면 토큰 교체 시 YAML 수정 불필요.
policy_source: central(기본값)이면 중앙 정책이 파일보다 우선. 중앙에서 정책을 한 번이라도 저장한 장비(리비전 1 이상)는 시작 뒤 첫 하트비트에서 중앙 정책을 수신해 heartbeat_interval_s·commands_poll_s·retention·sync 전체 교체. 화면에서 수정하지 않은 항목도 서버의 기본 정책 값으로 변경. 파일 값을 유지하려면 policy_source: local 로 설정(명령·정책·보존).
설정 파일 탐색 순서
--config 를 지정하지 않으면 다음 순서로 탐색, 처음 발견한 파일 하나만 읽음.
- 환경 변수
GEO_EDGE_CONFIG가 가리키는 파일. 이 변수가 있으면 탐색은 여기서 종료. 그 파일이 없으면 다른 경로를 찾지 않고 기본값으로 기동. /etc/geo-mlops/edge.yaml- 현재 디렉터리의
edge.yaml
설정 파일이 하나도 없어도 에이전트는 기본값으로 기동. 이때 central 이 비어 있으므로 링크는 계속 offline, 데이터는 로컬에만 누적. geo-mlops-edge config 로 실제 적용된 값 확인.
환경 변수
접두사 GEO_EDGE_ 뒤에 키 이름을 대문자로 붙이고, **중첩 키는 이중 밑줄(__)**로 구분.
GEO_EDGE_CENTRAL__BASE_URL=https://mlops.example.com
GEO_EDGE_CENTRAL__TOKEN=<device-token>
GEO_EDGE_DATA_DIR=/var/lib/geo-mlops-edge
GEO_EDGE_API__TOKEN=<your-secret>
GEO_EDGE_RETENTION__MAX_BYTES=100GiB
GEO_EDGE_LOG_LEVEL=DEBUG목록(collectors, sync.windows, api.cors_origins)은 파일에 작성. 환경 변수로 지정하려면 JSON 문자열(GEO_EDGE_SYNC__WINDOWS='["22:00-06:00"]')로 작성.
크기 문자열
크기 필드에는 바이트 정수 대신 50GiB 같은 문자열 사용 가능. 대소문자 구분 없음.
| 단위 | 배수 | 단위 | 배수 |
|---|---|---|---|
B | 1 | ||
KB | 1000 | KiB | 1024 |
MB | 1000² | MiB | 1024² |
GB | 1000³ | GiB | 1024³ |
TB | 1000⁴ | TiB | 1024⁴ |
적용되는 필드: retention.max_bytes, retention.free_disk_min_bytes, sync.chunk_bytes, sync.max_bytes_per_s, api.max_body_bytes, http 수집기의 max_body_bytes.
전체 필드
최상위
| 키 | 기본값 | 설명 |
|---|---|---|
central | (아래) | 중앙 서버 접속 |
device | (아래) | 장비 이름·위치 |
data_dir | /var/lib/geo-mlops-edge | 큐 DB(edge.db), 파일 스풀(spool/), 모델 캐시(models/)가 모두 이 경로에 저장됨 |
disk_path | "" | 디스크 사용률을 측정하고 보존 한도를 적용할 파일시스템. 비우면 data_dir. |
heartbeat_interval_s | 30 | 하트비트 주기(초) |
commands_poll_s | 25 | 명령 롱폴 대기 시간(초) |
retention | (아래) | 로컬 보존 한도 |
sync | (아래) | 업로드 조절 |
link | (아래) | 연결 감시 |
api | (아래) | 로컬 HTTP API |
collectors | [] | 수집기 목록(데이터 수집기 참고) |
models | (아래) | 모델 캐시 |
policy_source | central | central 이면 중앙에서 수신한 정책이 heartbeat_interval_s·commands_poll_s·retention·sync 를 덮어씀. local 이면 이 파일이 우선. |
log_level | INFO | DEBUG·INFO·WARNING·ERROR |
central
| 키 | 기본값 | 설명 |
|---|---|---|
base_url | "" | 중앙 API 주소(https://mlops.example.com). 비면 오프라인 전용. |
token | "" | 디바이스 토큰. 환경 변수 GEO_EDGE_CENTRAL__TOKEN 으로 지정(파일에 작성해도 읽지만 저장소·백업에 포함되기 쉬움). |
timeout_s | 10.0 | 요청 제한 시간(초) |
verify_tls | true | TLS 인증서 검증 |
base_url 과 token 이 둘 다 있어야 중앙과 통신.
device
| 키 | 기본값 | 설명 |
|---|---|---|
id | "" | 장비 이름. 비면 호스트 이름, 그것도 없으면 edge-<머신ID 앞 8자>. 영문·숫자·.·_·- 외 문자는 - 로 치환되고 64자에서 잘림. |
location | 없음 | 등록 시 중앙에 보고하는 위치. 값이 있으면 등록 시마다 중앙의 위치를 이 값으로 변경. 비우면 중앙 값을 변경하지 않음. |
retention: 로컬 보존 한도
세 조건 중 하나라도 해당하면 정리. max_age_days 를 넘긴 항목은 우선순위와 무관하게 삭제. max_bytes·free_disk_min_bytes 를 넘으면 우선순위가 낮은 것부터, 같은 우선순위에서는 오래된 것부터 삭제. 현재 전송 중인 항목은 삭제하지 않음. 정리는 에이전트 시작 시와, 수집기나 로컬 API(/records·/blobs·push)로 새 항목이 추가될 때 실행.
| 키 | 기본값 | 설명 |
|---|---|---|
max_bytes | 50GiB | 큐 전체 크기 상한 |
max_age_days | 30 | 큐에 추가된 지 이보다 오래된 항목은 삭제. 0 이면 기간 제한 없음. |
free_disk_min_bytes | 5GiB | 디스크 여유 공간이 이보다 적어지면 항목을 삭제해 확보. 0 이면 검사 안 함. |
sync: 업로드 조절
| 키 | 기본값 | 설명 |
|---|---|---|
batch_size | 500 | 한 요청에 전송하는 레코드 수(서버 상한 1000) |
chunk_bytes | 32MiB | 파일 청크 크기 요청값. 실제 크기는 서버가 정해 반환한 값을 사용. |
max_bytes_per_s | 0 | 전송 속도 상한. 0 은 무제한. |
cpu_pause_percent | 85 | 시스템 CPU 가 이 값 이상이면 전송을 일시 중지. 0 이면 검사 안 함. |
windows | [] | 전송 허용 시간대(장비 현지 시각. 컨테이너에서는 컨테이너의 시간대), 예: ["22:00-06:00"]. 비면 항상. |
concurrency | 1 | 레코드 묶음 하나를 전송한 뒤 이어서 전송할 파일 수. 파일은 동시에 전송하지 않고 하나씩 전송. |
urgent_priority | 90 | 이 우선순위 이상은 windows 를 무시하고 전송 |
link: 연결 감시
| 키 | 기본값 | 설명 |
|---|---|---|
probe_interval_s | 5.0 | 중앙 /api/v1/health 를 호출해 확인하는 주기 |
backoff_max_s | 60.0 | 실패가 이어질 때 증가하는 간격의 상한 |
online_after_ok | 2 | online 으로 판단하는 연속 성공 횟수 |
offline_after_fail | 3 | offline 으로 판단하는 연속 실패 횟수 |
현장 회선은 연결 단절과 복구가 잦음. 이 두 값은 우연한 한 번의 성공으로 수십 GB 전송이 시작되는 것을 방지.
api: 로컬 HTTP API
| 키 | 기본값 | 설명 |
|---|---|---|
enabled | true | 로컬 API 실행 여부 |
host | 0.0.0.0 | 바인드 주소. 개발 PC 는 127.0.0.1. |
port | 8600 | 포트 |
token | "" | 비면 인증 없음. 있으면 X-Edge-Api-Token 헤더에 포함 필요. |
cors_origins | ["*"] | 허용할 브라우저 출처 |
max_body_bytes | 2GiB | 요청 본문 상한. 넘으면 413. 0 이면 검사 안 함. |
models: 모델 캐시
| 키 | 기본값 | 설명 |
|---|---|---|
keep_versions | 2 | 모델별로 디스크에 보관할 버전 수. 내려받을 때마다 버전 번호가 큰 것부터 이 수만큼 보관, 나머지 삭제. 0 은 무제한. |
auto_activate | Production | 설정 항목은 있지만 런타임은 이 값을 읽지 않음. 자동 활성화 동작은 모델과 추론 참고. |
예시 전체
central:
base_url: https://mlops.example.com
timeout_s: 10
verify_tls: true
device:
id: edge-line-01
location: line-1
data_dir: /var/lib/geo-mlops-edge
retention:
max_bytes: 50GiB
max_age_days: 30
free_disk_min_bytes: 5GiB
sync:
batch_size: 500
chunk_bytes: 32MiB
max_bytes_per_s: 0
cpu_pause_percent: 85
windows: []
urgent_priority: 90
link:
probe_interval_s: 5
backoff_max_s: 60
online_after_ok: 2
offline_after_fail: 3
heartbeat_interval_s: 30
commands_poll_s: 25
api:
enabled: true
host: 0.0.0.0
port: 8600
token: ""
max_body_bytes: 2GiB
models:
keep_versions: 2
policy_source: central
log_level: INFO
collectors: [] # 데이터 수집기 페이지 참고