서비스 제어

mac pull, mac build, mac start, mac stop, mac restart, mac status, mac logs, mac info, mac test, mac clean.

`mac pull`

설정된 레지스트리에서 컨테이너 이미지를 받아옵니다. 모드는 반드시 지정해야 합니다.

~$ mac pull all       # 마스터 + 에이전트 이미지 전체
~$ mac pull master    # 마스터 이미지만
~$ mac pull agent     # 에이전트 이미지만

이미지의 버전은 패키지 버전 (/usr/share/mango-ai-center/VERSION 참고)에 맞춰 고정됩니다. 프라이빗 미러를 쓰려면 MAC_REGISTRY를 설정하세요 — 환경 참고.

--local (또는 MAC_IMAGE_SOURCE=local)을 주면 mac pull은 MAC 이미지를 소스에서 빌드하고, 외부 이미지 전용 서비스 (Prometheus, Loki, GPU 벤더 익스포터, mango-sdk-agent)만 레지스트리에서 받아옵니다.

`mac build`

소스 체크아웃에서 MAC 이미지를 로컬로 빌드합니다. 모드는 반드시 지정해야 합니다.

~$ mac build all       # 마스터 + 에이전트 이미지 빌드
~$ mac build master    # 마스터 이미지만
~$ mac build agent     # 에이전트 이미지만

빌드된 이미지는 레지스트리 참조와 동일한 태그가 붙으므로, mac start <mode> --local이 방금 빌드한 이미지를 그대로 실행합니다. mac pull --local과 달리 외부 이미지 전용 서비스는 받아오지 않습니다. MAC_CONFIG_DIR가 체크아웃의 deploy/ 디렉터리를 가리켜야 합니다 — 패키지 없이 실행 참고.

`mac start`

MAC 서비스를 기동합니다. 모드는 반드시 지정해야 합니다.

~$ mac start all       # 이 호스트에서 마스터 + 에이전트
~$ mac start master    # 마스터만 (웹 UI, API, Prometheus)
~$ mac start agent     # 에이전트만 (익스포터, sdk-agent, bmc-agent)

mac start는 누락된 이미지를 자동으로 받아오고, 컨테이너를 detached 모드로 띄운 뒤, 접속 URL을 출력합니다. agent 모드에서는 MASTER_IP가 가리키는 마스터에 이 호스트를 함께 등록합니다 — 인터페이스가 여러 개인 (multi-homed) 호스트에서는 커널 라우팅 테이블에 마스터까지 도달하는 로컬 주소를 물어 그 주소로 등록합니다.

플래그:

--local — 이미지를 소스에서 빌드해 실행 (MAC_IMAGE_SOURCE=local)
--registry — 배포된 이미지를 강제 사용 (기본값)

~$ mac start master --local    # 로컬 마스터 이미지를 빌드 + 실행

`mac stop`

실행 중인 서비스를 중지합니다. 모드는 반드시 지정해야 합니다.

~$ mac stop all
~$ mac stop master
~$ mac stop agent

mac stop agent는 마스터에 통보해 노드를 인벤토리에서 해제 합니다. 서버를 폐기할 때 적절한 명령입니다. 재부팅이나 유지보수처럼 일시적인 정지라면 호스트를 그냥 재기동해도 됩니다 — 그저 오프라인이 된 에이전트는 등록 상태를 유지하므로 인벤토리도 그대로 보존됩니다.

`mac restart`

mac stop <mode>와 mac start <mode>를 묶어 실행하는 편의 명령입니다. 모드는 반드시 지정해야 합니다.

~$ mac restart all
~$ mac restart master
~$ mac restart agent
~$ mac restart master --local   # 로컬 빌드 이미지로 재기동

mac env set으로 변수를 수정한 뒤, 새 값이 컨테이너에 반영되도록 이 명령을 사용하세요. --local / --registry 플래그는 start 단계로 그대로 전달됩니다.

`mac status`

~$ mac status
NAME                STATUS    PORTS
mac-api-server      running   0.0.0.0:28080->28080/tcp
mac-web-ui          running   0.0.0.0:23000->80/tcp
mac-prometheus      running   0.0.0.0:29090->9090/tcp
mac-metrics-bridge  running   0.0.0.0:29199->29199/tcp
mac-loki            running   0.0.0.0:29210->3100/tcp
mac-switch-exporter running   0.0.0.0:29400->29400/tcp

`mac logs`

정확한 docker-compose 호출을 외우지 않고도 컨테이너 로그를 볼 수 있습니다.

~$ mac logs                    # 모든 MAC 컨테이너의 마지막 20줄
~$ mac logs api-server         # 서비스 하나의 마지막 100줄
~$ mac logs api-server -f      # 서비스 하나를 실시간 follow (--follow도 가능)

`mac info`

현재 호스트의 설치 상태를 한 화면으로 요약합니다 — CLI 버전, 호스트네임, OS와 커널, Docker / Docker Compose 버전, 설정 디렉터리, 그리고 이 호스트에서 감지된 GPU 프로파일 — nvidia, amd, nvidia, amd (두 벤더 모두), 또는 none detected. 노드가 이상 동작을 보일 때 가장 먼저 살펴볼 진단 명령입니다.

~$ mac info
Mango AI Center v0.4.1
========================================
  Hostname:         gpu-server-04
  Kernel:           6.8.0-45-generic
  OS:               Ubuntu 22.04.4 LTS
  Docker:           27.0.3
  Docker Compose:   2.27.0
  Config Dir:       /etc/mango/mac
  GPU Profile:      nvidia
========================================

`mac test`

이미 실행 중인 스택을 대상으로 MAC 운영자 테스트를 실행합니다. mac test는 실행 중인 배포를 점검만 하므로, 먼저 mac start로 스택을 띄워야 합니다. test는 상위 명령이며, 현재 유일한 하위 명령이자 기본값은 sanity입니다. 따라서 mac test와 mac test sanity는 동일합니다:

~$ mac test           # 새너티 테스트 실행 (기본값)
~$ mac test sanity    # 위와 동일 (명시적)

올인원 배포 (mac start all — 마스터와 에이전트를 같은 호스트에서 실행)에서는 새너티 테스트가 해당 노드의 모든 MAC 서비스 상태를 한 번에 점검하고, 여기에 핵심 클러스터 API 체크 (에이전트 레지스트리, 알림 규칙, Prometheus 도달성)를 더합니다. 노드별 [PASS]/[FAIL]/[SKIP] 표와 요약 줄을 출력합니다. 마스터가 로컬이므로 그 노드에서 바로 실행하면 되며, 로그인도 MASTER_IP 설정도 필요 없습니다.

정상 상태의 올인원 노드 출력 예시:

~$ mac test
Mango AI Center — Cluster Sanity Test
========================================
Node: gpu-server-01 (10.1.5.7)
  [PASS] api-server         (docker_health: healthy)
  [PASS] bmc-agent          (docker_health: healthy)
  [SKIP] loki               (skip: no healthcheck declared (by design))
  [PASS] mango-sdk-agent    (docker_health: healthy)
  [PASS] metrics-bridge     (docker_health: healthy)
  [PASS] nic-exporter       (docker_health: healthy)
  [PASS] prometheus         (docker_health: healthy)
  [PASS] rocm-exporter      (running_only: running)
  [PASS] sw-exporter        (docker_health: healthy)
  [PASS] switch-exporter    (docker_health: healthy)
  [PASS] sys-exporter       (docker_health: healthy)
  [PASS] sys-manager        (docker_health: healthy)
  [PASS] web-ui             (docker_health: healthy)
Cluster API checks:
  [PASS] GET /api/v1/agents (1 agents registered)
  [PASS] GET /api/v1/alert-rules (15 rules configured)
  [PASS] GET /api/v1/alert-rules/defaults (15 default rules)
  [PASS] Prometheus reachable
========================================
RESULT: ALL PASSED (1 nodes, 17 checks)

올인원 노드는 마스터 서비스 (api-server, web-ui, metrics-bridge, prometheus, loki, switch-exporter)와 에이전트 서비스 (sys-exporter, bmc-agent, nic-exporter, sw-exporter, mango-sdk-agent, 그리고 이 호스트의 GPU 익스포터 — AMD는 rocm-exporter, NVIDIA는 dcgm-exporter), 그리고 모든 노드에서 실행되는 sys-manager를 나란히 실행하므로, 이들이 모두 한 노드 아래에 나타납니다. 서비스는 알파벳순으로 나열됩니다. 노드가 자기 자신을 에이전트로 등록하므로 에이전트 수는 1로 표시됩니다.

표 읽는 법:

[PASS] — 서비스가 정상 (docker_health: healthy)이거나, Docker 헬스체크가 없는 서드파티 이미지 (예: GPU 벤더 익스포터)의 경우 단순히 실행 중 (running_only: running)입니다.
[SKIP] — 의도적으로 헬스체크를 두지 않은 서비스 (예: loki)입니다. 실패가 아니며, 투명성을 위해 표시됩니다.
[FAIL] — 서비스가 없거나, 중지되었거나, 비정상입니다. [FAIL]이 하나라도 있으면 전체 실행이 실패로 간주되고 요약 줄에 표시됩니다. 예:
```
RESULT: 1 FAILED — gpu-server-01: rocm-exporter
```

스택이 아직 실행되지 않았거나 로컬 api-server가 아직 뜨지 않았으면 해당 사실을 알리고 2로 종료합니다. 이는 헬스 체크 실패와 구별되며 실패로 해석해서는 안 됩니다. 먼저 mac start all로 스택을 띄운 뒤 mac test를 다시 실행하세요:

~$ mac test
Error: could not reach the MAC master at http://localhost:28080/api/v1/cluster/sanity-check: dial tcp [::1]:28080: connect: connection refused

'mac test sanity' aggregates results from the master node's cluster-wide
view. Run it on the master node, or point it at the master explicitly:
  mac env set MASTER_IP=<master-ip>   (and MASTER_API_PORT if non-default)

종료 코드 (스크립트 친화적):

코드	의미
`0`	모든 체크 통과
`1`	하나 이상의 체크 실패
`2`	마스터에 도달할 수 없음

`mac version`

~$ mac version
mac version 0.4.0

~$ mac -v
~$ mac --version

CLI 버전만 출력하고 종료합니다 — 설치된 MAC 버전에 따라 동작을 분기해야 하는 스크립트에 유용합니다.

`mac clean`

모든 것을 제거합니다 — 컨테이너, MAC 도커 네트워크, 명명 볼륨 (Prometheus 시계열 DB와 Loki 로그 포함), 로컬에 캐시된 MAC 이미지까지. 완전히 새로 시작할 때 사용하세요.

~$ mac clean

경고

mac clean은 파괴적이며 되돌릴 수 없습니다. 과거 메트릭을 보존하려면 먼저 Prometheus 볼륨을 백업해 두세요.

mac pull​

mac build​

mac start​

mac stop​

mac restart​

mac status​

mac logs​

mac info​

mac test​

mac version​

mac clean​