콘텐츠로 이동

관리자 가이드

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

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

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

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

1. 서명 키 생성과 보호

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

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

2. 신뢰 앵커 추출과 기록

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

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

3. 기준선 정책 작성과 서명

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

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

4. 정책 서버 구축

서명 키, 정책, 등록 토큰과 함께 서비스 관리자 아래에서 서버를 실행한다. 앞단에 TLS 종단기를 둔다. systemd 유닛과 전체 명령은 정책 서버 배포와 운영을 참고한다. 버전 경로가 응답하는지 확인한다.

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

5. 등록 토큰 발급

기기별 또는 배치별로 일회용 등록 토큰을 만들고, 선택적으로 조직 레이블에 묶는다. 각 토큰을 세 프로비저닝 진입점 중 하나로 전달한다. 토큰 목록은 운영자만 읽을 수 있게 둔다.

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

packaging/provisioning/provision.example.json을 바탕으로 managementServerUrl과 신뢰 앵커를 채운 provision.json을 만든다. 기기에 도달하는 방식을 정한다. 사용자별 딥링크, 수동 붙여넣기, 또는 OS 관리 경로로의 MDM·설치 관리자 배포다. 기기 등록과 신뢰 앵커를 참고한다.

7. 첫 기기 등록과 검증

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

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

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

N일차: 플릿 운영

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

정책 갱신

정책 문서를 편집한 뒤, 정책 서버를 재시작(또는 서빙 문서를 교체)해 새 버전을 서명·서빙하게 한다. 기기는 다음 폴링에서 새 정책 id를 인지하고 내려받는다. 폴링은 간격 기반(기본 900초)이므로, 변경이 플릿에 도달하기까지 최대 한 폴 간격을 둔다. 위험한 변경은 별도 정책을 서빙하거나 별도 서버를 써서 파일럿 그룹에 먼저 롤아웃하고, 그다음 넓힌다.

서명 키 교체

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

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

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

등록 토큰 교체

등록 토큰은 일회용이며 첫 등록 시 소비된다. 새 기기나 재등록마다 새 토큰을 발급하고, 사용했거나 오래된 토큰을 서버 토큰 목록에서 제거한다. 토큰을 기기 간에 재사용하지 않는다.

기기 등록과 해제

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

오프라인 라이선스 갱신

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

정책 서버 장애 복구

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

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

서명 키 분실 또는 유출 복구

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

운영 체크리스트

1일차 체크리스트

  • 서명 키 생성, 백업, 접근 제한 완료.
  • 신뢰 앵커 추출과 그 id 기록 완료.
  • 기준선 정책 작성, --dry-run 검증, 서빙 완료.
  • 정책 서버가 TLS 뒤 서비스 관리자 아래에서 실행 중이고 버전 경로 확인 완료.
  • 등록 토큰 발급과 안전한 전달 완료.
  • 프로비저닝 프로필 작성과 전달 방식 선택 완료.
  • 첫 기기 등록, 앵커 지문 검증, 관리 상태 확인 완료.
  • 필요 시 오프라인 라이선스 서명·설치 완료, valid 표시.

N일차 체크리스트

  • 정책 변경을 파일럿한 뒤 롤아웃, 전파에 최대 한 폴 간격 허용.
  • 앵커를 겹쳐 서명 키 교체, 라이선스 재서명.
  • 등록 토큰 교체와 사용된 토큰 제거.
  • 문서화된 경로로 기기 등록·해제.
  • 만료 전 라이선스 갱신.
  • 컴플라이언스 기간에 맞춰 감사 기록 수집·보존(감사와 컴플라이언스 참고).
  • 장기 서버 장애가 우려되는 곳에 머신 정책 기준선 배치.