관리자 가이드¶

엔터프라이즈 관리 아래에서 Backend.AI GO를 배포하고 운영하는 운영 플레이북이다. 다른 엔터프라이즈 문서의 작업을 1일차 설정과 N일차 운영으로 묶는다. 여기서 시작하고, 각 단계의 세부는 링크를 따른다.

이 가이드가 참조하는 문서는 다음과 같다.

정책 서버 배포와 운영: 서버, 서명 키, 신뢰 앵커.
배포 모델: 머신 정책, 중앙 정책, 프로비저닝과 우선순위.
기기 등록과 신뢰 앵커: 기기 온보딩과 MDM 배포.
에어갭 배포: 오프라인 체크리스트.
오프라인 라이선스: 서명된 엔타이틀먼트 파일.
고정 엔드포인트 배포: 하나의 추론 엔드포인트로 고정.
감사와 컴플라이언스: 강제 기록 수집.
정책 스키마 레퍼런스: 정책이 무엇을 지정·잠금·게이팅할 수 있는지.

1일차: 엔터프라이즈 관리 구축¶

첫날은 신뢰를 세우고 기기 한 대를 엔드투엔드로 관리 상태로 만드는 일이다.

1. 정책 서버 설치¶

비공개 릴리스에서 버전이 일치하는 단일 Linux 바이너리를 설치하거나 전용 패키지를 소스에서 빌드한다. 정책 서버는 데스크톱 설치 관리자나 aigo-server 패키지에 포함되지 않으며 공식 컨테이너 이미지도 게시되지 않는다. 계속하기 전에 aigo-policy-server --version을 확인한다. 정책 서버 배포와 운영을 참고한다.

2. 서명 키 생성과 보호¶

조직의 Ed25519 서명 키를 생성하고 시크릿 매니저나 접근 통제된 파일에 저장한다. 이 키는 전체 플릿의 신뢰 뿌리이므로 백업하고, 정책을 관리하는 운영자에게만 접근을 제한한다.

umask 077
aigo-policy-server --generate-signing-key > policy-signing.pk8.b64

3. 신뢰 앵커 추출과 기록¶

서명 키에서 공개 신뢰 앵커를 출력하고 그 id를 기록한다. 이 앵커를 모든 기기에 배포하며, 기기는 이를 정책과 라이선스 검증에 쓴다.

aigo-policy-server \
    --signing-key-file policy-signing.pk8.b64 \
    --anchor-id org-2026 \
    --print-anchor \
    > trust-anchor.json

4. 기준선 정책 작성과 검증¶

관리 기준선을 정의하는 EnterprisePolicy(덮어쓰고 잠글 설정, 도구 거버넌스, 배포 프로필, 이그레스 상태)를 작성한다. 고유 policyId와 RFC3339 issuedAt을 부여한다. 정책 스키마 레퍼런스를 참고한다. 서빙 전에 검증한다.

aigo-policy-server \
    --signing-key-file policy-signing.pk8.b64 \
    --policy-file policy.json \
    --anchor-id org-2026 \
    --dry-run

5. 등록 토큰과 영속 상태 준비¶

기기 또는 등록 배치마다 무작위 일회용 등록 토큰을 하나 만들고 JSON 토큰 문서에서 선택적 조직 레이블에 매핑한다. 토큰 문서와 서명 키는 서비스 계정 소유, 모드 0600으로 설치한다. users.db, 암호화된 액세스 키, device-registry.json, 소비된 토큰 다이제스트를 보관할 소유자 전용 영속 데이터 디렉터리를 만든다. /tmp는 사용하지 않는다.

6. 로컬 시작과 운영자 접근 부트스트랩¶

TLS 리버스 프록시를 비활성화한 채 명시적인 --data-dir로 서버를 127.0.0.1:8444에서 시작한다. POST /api/v1/setup/register-admin으로 첫 관리자를 만들고, 그 세션으로 POST /admin/keys에서 운영자 키를 만든다. 배포 가이드에는 비밀번호를 프로세스 인자와 셸 히스토리에 남기지 않는 명령이 있다. API 키 비밀은 한 번만 반환되므로 즉시 저장한다.

등록 전 최초 설정 상태를 확인한다.

curl -fsS http://127.0.0.1:8444/api/v1/setup/status

7. TLS 활성화와 정책 서버 검증¶

교정된 systemd 유닛 아래에서 서버를 실행한 뒤 같은 호스트의 TLS 리버스 프록시를 활성화한다. 업스트림 리스너는 루프백에 둔다. 최소 권한 enterprise_read 운영자 키로 공개 HTTPS 이름의 버전 경로가 응답하는지 확인한다.

curl -fsS https://policy.acme.example/api/v1/policy/version \
    -H "Authorization: Bearer <operator-api-key>"

8. 프로비저닝 프로필과 설치 관리자 준비¶

packaging/provisioning/provision.example.json을 바탕으로 managementServerUrl, trust-anchor.json의 공개 앵커, 폴 간격, 무인 등록이라면 새 토큰 하나를 채운 provision.json을 만든다. 기기에 도달하는 방식을 정한다. 사용자별 딥링크, 수동 붙여넣기, 또는 OS 관리 경로로의 MDM·설치 관리자 배포다. 기기 등록과 신뢰 앵커를 참고한다.

9. 첫 기기 등록과 검증¶

기기 한 대를 프로비저닝한 뒤 설정, 조직 순으로 연다. 관리 모드, 조직, 잠긴 설정 개수, 이그레스 상태, 기기 지문을 보여주는지 확인한다. 앵커 지문이 3단계에서 기록한 값과 일치하는지 검증한다.

10. 오프라인 라이선스 설치(필요 시)¶

배포가 서명된 엔타이틀먼트를 요구하면, 조직 서명 키로 라이선스를 서명해 <app_data>/enterprise/license.json에 배포한다. 조직 탭이 라이선스를 valid로 보이는지 확인한다. 오프라인 라이선스를 참고한다.

N일차: 플릿 운영¶

일상 운영은 정책 갱신, 키와 토큰 교체, 기기 수명 주기, 복구다.

정책 갱신¶

정책 문서를 편집하고 새 policyId와 새 issuedAt을 모두 부여한다. 클라이언트는 policyId를 버전 키로 사용하므로, 이 id가 같으면 전체 문서를 내려받지 않는다. 운영 명령에 --dry-run을 붙여 검증하고, 파일을 원자적으로 설치한 뒤 aigo-policy-server를 재시작하며, /api/v1/policy/version이 새 id를 보고하는지 확인한다. 프로세스는 파일을 감시하지 않고 SIGHUP으로 재적재하지도 않는다.

폴링은 간격 기반(기본 900초)이므로, 변경이 플릿에 도달하기까지 최대 한 폴 간격을 둔다. 위험한 변경은 별도 정책 id나 별도 서버를 써서 파일럿 그룹에 먼저 롤아웃하고, 그다음 넓힌다.

서명 키 교체¶

앵커를 겹쳐 단번에 전환하지 않고 서명 키를 교체한다. 단계는 다음과 같다.

새 서명 키를 생성하고 그 앵커를 추출한다.
새 앵커를 프로비저닝 프로필에 추가하고(기기를 재프로비저닝하거나 재등록), 클라이언트가 옛 키와 새 키를 모두 신뢰하게 한다.
정책 서버가 새 키와 새 --anchor-id로 서명하도록 전환한다.
모든 기기가 새 앵커를 신뢰하고 그 앵커로 서명된 정책을 가져온 뒤, 옛 앵커를 폐기한다(또는 notAfter로 만료시킨다).

같은 앵커가 오프라인 라이선스도 검증하므로, 겹치는 기간에 활성 라이선스를 새 키로 다시 서명해 재배포한다.

등록 토큰 교체¶

등록 토큰은 일회용이며 첫 등록 시 소비된다. 새 기기나 재등록마다 새 토큰을 발급하고, 사용했거나 오래된 토큰을 서버의 토큰 문서에서 제거한다. 서버는 이 문서를 모드 0600 파일, AIGO_POLICY_ENROLLMENT_TOKENS, 표준 입력 중 하나에서 읽는다. 세 입력은 시작 시 한 번만 읽으므로 토큰 소스를 바꾼 뒤 서버를 재시작한다. 토큰을 기기 간에 재사용하지 않는다. 소비된 토큰은 서버를 재시작해도 소비된 상태로 남으므로, 문서에서 지우는 것은 정리 작업이지 보안 조치가 아니다.

기기 등록과 해제¶

기기를 등록하려면 세 진입점 중 하나로 프로비저닝 프로필과 새 토큰을 전달한다. 재등록하려면(예: 키 교체 후) 조직 탭의 "기기 재등록" 동작을 새 토큰과 함께 쓴다. 새 앵커는 기존 앵커와 병합된다. 등록을 해제하려면 OS 경로에서 관리 provision.json과 머신 정책을 제거한다. 기기는 다음 실행 시 관리되지 않는 모드로 돌아간다. 기기 등록과 신뢰 앵커를 참고한다.

오프라인 라이선스 갱신¶

기기가 expired 상태에 들어가지 않도록 expiresAt 이전에 라이선스 갱신을 계획한다. 다음 라이선스를 서명하고 기존 파일 위에 배포한 뒤, 조직 탭이 valid로 돌아오는지 확인한다. 변경은 재시작 없이 반영된다. 오프라인 라이선스를 참고한다.

정책 서버 장애 복구¶

관리되는 기기는 정책 서버에 도달할 수 없어도 상태를 잃지 않는다. 마지막으로 검증된 중앙 정책은 <app_data>/enterprise/central_policy.json에 캐시되어 그대로 시행되고, 이그레스 방화벽은 그대로 설치되며, 잠금은 유지된다. 기기는 계속 폴링하다가 서버가 돌아오면 최신 정책을 받는다. 유효하지 않은 라이선스는 아무것도 해제하지 않으므로, 장애가 다운그레이드가 되지 않는다.

장기 장애에 대비하려면 중앙 정책에 같은 기준선을 담은 머신 정책을 짝지운다. 머신 정책은 네트워크 없이 신뢰된 로컬 경로에서 적용되므로, 서버에 한 번도 도달하지 못한 새 설치에서도 하한이 유지된다. 배포 모델을 참고한다.

서명 키 분실 또는 유출 복구¶

서명 키를 잃거나 노출하면 보안 사고로 취급한다. 새 키를 생성하고, 그 앵커를 모든 기기에 배포하며(재프로비저닝이나 재등록), 서버를 새 키로 전환하고, 플릿이 이전을 마치는 대로 옛 앵커를 폐기한다. 옛 앵커를 폐기하기 전까지는 옛 키 보유자가 신뢰하는 기기가 받아들이는 정책을 서명할 수 있으므로, 이전을 신속히 마치고 유출된 앵커에 가까운 notAfter를 설정해 노출을 한정하는 것을 고려한다.

운영 체크리스트¶

1일차 체크리스트¶

버전이 일치하는 Linux 정책 서버 바이너리 설치와 확인 완료.
서명 키 생성, 백업, 접근 제한 완료.
신뢰 앵커 추출과 그 id 기록 완료.
기준선 정책 작성, --dry-run 검증, 서빙 완료.
영속 데이터 디렉터리 생성·백업과 서비스 계정 전용 쓰기 권한 설정 완료.
등록 토큰 발급, 모드 0600 설치, 안전한 전달 완료.
외부 공개 전에 첫 관리자와 최소 권한 운영자 API 키 생성 완료.
정책 서버가 TLS 뒤 서비스 관리자 아래에서 실행 중이고 운영자 키로 버전 경로 확인 완료.
프로비저닝 프로필 작성과 전달 방식 선택 완료.
첫 기기 등록, 앵커 지문 검증, 관리 상태 확인 완료.
필요 시 오프라인 라이선스 서명·설치 완료, valid 표시.

N일차 체크리스트¶

정책 갱신에 새 policyId를 부여하고 --dry-run을 통과한 뒤 재시작으로 활성화.
정책 변경을 파일럿한 뒤 롤아웃, 전파에 최대 한 폴 간격 허용.
앵커를 겹쳐 서명 키 교체, 라이선스 재서명.
등록 토큰 교체와 사용된 토큰 제거, 입력 변경 뒤 서비스 재시작.
문서화된 경로로 기기 등록·해제.
만료 전 라이선스 갱신.
컴플라이언스 기간에 맞춰 감사 기록 수집·보존(감사와 컴플라이언스 참고).
장기 서버 장애가 우려되는 곳에 머신 정책 기준선 배치.
영속 정책 서버 상태를 백업·복구 점검에 포함.