콘텐츠로 이동

에어갭 배포

Backend.AI GO는 완전 에어갭 관리형 설치를 지원한다. 단일 정책 플래그 egress.airGapped는 페일클로즈드 마스터 스위치로, 관리자가 명시적으로 허용한 호스트를 제외한 모든 외부 네트워크 경로를 비활성화한다. 이 문서는 스위치가 정확히 무엇을 비활성화하는지, 이그레스 허용 목록과 어떻게 함께 동작하는지, 에어갭 사이트를 엔드투엔드로 구축하는 방법을 설명한다.

에어갭과 이그레스 필드의 스키마 세부는 정책 스키마 레퍼런스를 참고한다. 오프라인 머신으로 모델을 옮기는 방법은 오프라인 전용 설정을 참고한다. 이 문서는 거기에 관리형 및 정책 서버 경로를 더한다.

에어갭 마스터 스위치

egress.airGapped는 엔드포인트별 네트워크 제어 위에 위치한다. 적용된 정책에서 true로 두면, 방화벽과 엔드포인트별 disabled 모드가 닿지 못하는 네트워크 경로를 한 번의 전환으로 닫는다. 사용자에게 읽기 전용이며, 정책만 설정한다. 이 필드를 생략한 기존 정책은 에어갭이 아닌 상태로 역직렬화되므로, 정책이 없는 설치는 영향을 받지 않는다.

플래그는 egress 영역에 둔다. 방화벽이 시작 시 가장 먼저 설치되어 외부 이그레스 차단의 마스터 보증 역할을 하는 바로 그 영역이다.

{
  "egress": {
    "enforce": true,
    "allowedHosts": ["models.internal", "policy.internal"],
    "airGapped": true
  }
}

무엇을 비활성화하는가

에어갭 상태에서는 다음이 한꺼번에 성립한다.

  • 이그레스 방화벽이 강제로 적용된다. egress.enforce는 기록된 값과 무관하게 true로 취급되므로, 정책이 에어갭이면서 강제되지 않는 방화벽을 설치할 수 없다. 설치본은 egress.allowedHosts의 호스트에만 도달한다.
  • 모든 서비스 엔드포인트가 disabled로 해석된다. default 모드 엔드포인트가 공개 기본 URL로 폴백하는 일이 없다. 모델 허브, 엔진 및 런타임 레지스트리, 웹 검색 제공자, 채널 커넥터, 업데이트 피드, 추론 API가 모두 해당한다.
  • 엔드포인트 리졸버 밖에서 동작하는 베어 클라이언트 네트워크 경로는 소켓을 열기 전에 거부되며, 각각 명확한 "에어갭 모드에서 비활성화됨" 오류를 반환한다. OAuth 디바이스 플로우(OpenAI Codex, Google Calendar), continuum-router 버전 프로브, 에이전트 URL 가져오기 도구, http_request 에이전트 도구, 에이전트 및 스쿼드 템플릿 카탈로그 레지스트리가 여기에 해당한다.
  • 클라우드 제공자 OAuth 디바이스 플로우 로그인이 차단되고 제공자는 API 키 인증으로 폴백한다. OAuth 디바이스 플로우 진입점은 UI에서 숨겨진다.
  • 익명 텔레메트리는 강제로 꺼지고 잠긴다. 토글은 "조직에서 관리함" 배지와 함께 비활성화되며, 활성화를 시도하는 쓰기는 거부된다.
  • 인앱 업데이터와 "업데이트 확인" 기능은 UI에서 숨겨진다.

스위치는 구조적으로 실패 시 닫힌다. 방화벽을 강제로 켜지 않고 에어갭 정책을 설치하는 코드 경로가 없으며, 각 베어 클라이언트 경로는 URL을 파싱하거나 소켓을 열기 전에 플래그를 확인한다.

이그레스 허용 목록

에어갭 모드는 방화벽을 강제로 켜지만, 어떤 내부 호스트에 도달할지는 여전히 운영자가 정한다. 이그레스 필드는 두 개다.

  • egress.enforce: 방화벽이 허용 목록 밖 호스트를 차단할지 여부. 에어갭 모드는 이를 true로 강제한다.
  • egress.allowedHosts: 설치본이 도달할 수 있는 호스트. 항목은 호스트명, *.internal.example 같은 와일드카드, 10.0.0.0/8 같은 CIDR 범위가 될 수 있다.

에어갭 모드에서 allowedHosts가 비어 있으면 모든 호스트를 거부한다. 설치본은 외부 연결을 전혀 하지 않는다. 설치본이 정말 필요한 내부 호스트, 보통 정책 서버와 내부 모델 또는 추론 엔드포인트만 나열한다. 방화벽은 시작 시 네트워크 호출 전에 설치되므로, 앱이 처음 실행되는 순간부터 보증이 유지된다.

엔드투엔드 오프라인 구축

에어갭 배포에는 두 가지 형태가 있다. 네트워크에 맞는 쪽을 고른다.

내부 정책 서버가 있는 사이트

에어갭 사이트에 도달 가능한 정책 서버를 갖춘 내부 네트워크가 있으면, 에어갭을 켠 채로 중앙 정책 모델을 운영한다.

  1. 내부 네트워크에 정책 서버를 세운다. 정책 서버 배포와 운영을 참고한다.
  2. egress.airGapped: true와, 내부 정책 서버 및 내부 추론·모델 호스트만 나열한 egress.allowedHosts로 정책을 작성한다.
  3. 모든 추론을 하나의 내부 엔드포인트로 보내야 하면 fixed_endpoint 배포와 함께 쓴다. 고정 엔드포인트 배포를 참고한다.
  4. managementServerUrl이 내부 정책 서버를 가리키고 trustAnchors가 공개 앵커를 담은 provision.json으로 기기를 프로비저닝한다. 기기 등록과 신뢰 앵커를 참고한다.
  5. 조직 탭에서 설치가 관리되고, 이그레스 방화벽이 강제되며, 에어갭 표시가 켜졌는지 확인한다.

완전 오프라인 머신(내부 서버 없음)

머신에 네트워크가 전혀 없으면, 서버를 결코 접촉하지 않도록 머신 정책을 쓴다.

  1. egress.airGapped: true와 필요한 allowedHosts(흔히 비어 있거나 로컬호스트 추론 포트만)로 EnterprisePolicy를 작성한다.
  2. 머신 정책 경로(Linux의 /etc/aigo/policy.json, 또는 OS별 동등 경로)에 둔다. 배포 모델을 참고한다.
  3. 오프라인 전용 설정의 .baimodel 워크플로로 모델과 엔진을 머신에 옮긴다.
  4. 필요하면 서명된 오프라인 라이선스를 추가해 설치본이 파일만으로 엔타이틀먼트를 증명하게 한다. 오프라인 라이선스를 참고한다.
  5. 앱을 실행하고 조직 탭이 에어갭 표시가 켜진 관리 모드를 보고하는지 확인한다.

검증 체크리스트

구축 후 앱과 상태 표면에서 상태를 확인한다.

  • 조직 설정 탭이 설치를 관리 모드로, 에어갭 표시가 켜지고, 이그레스 방화벽이 강제되며, 예상한 허용 호스트 개수로 보여준다.
  • 상태 표면(get_managed_status 또는 GET /api/v1/enterprise/status)이 egress.airGapped: true와 egress.enforce: true를 보고한다.
  • 제공자 설정 UI에 OAuth 디바이스 플로우 진입점이 없고, "업데이트 확인" 기능이 사라졌다.
  • 내부 또는 로컬 엔드포인트를 상대로 모델 로드와 채팅 왕복이 성공해, 허용 목록이 올바른지 확인된다.

다음 단계