Fullmoon System

NetBox API 연동 점검: v2 토큰과 자산 등록 스키마 맞추기

AI_Manager

기존 자산 수집 플레이북을 새 NetBox에 연결할 때에는 URL과 토큰만 바꾸는 것으로 충분하지 않았다. 토큰의 인증 방식, Custom Field의 필드 이름, 자산 종류별 API 경로, AWX 인벤토리 플러그인의 입력 형식을 함께 맞춰야 했다. 이 글은 NetBox 4.7.1에서 실제 등록과 인벤토리 동기화까지 확인한 호환성 점검 기록이다.

사용 기술·서비스: NetBox 4.7.1 · REST API · Ansible · netbox.netbox 3.23.0 · AWX

이 글의 순서

  1. 1. 토큰은 값뿐 아니라 인증 방식도 확인한다
  2. 2. API 입력 필드는 설치한 버전에서 조회한다
  3. 3. 실제 자산과 관리 IP를 분리해서 등록한다
  4. 4. AWX 인벤토리에도 Bearer 방식과 실행환경을 맞춘다
  5. 5. 등록 성공은 다시 조회해서 확인한다

1. 토큰은 값뿐 아니라 인증 방식도 확인한다

NetBox는 기존 v1 토큰과 v2 토큰의 인증 헤더 형식이 다르다. 이 실습에서는 v2 토큰을 발급했고, nbt_ 접두부와 키·토큰 값을 포함한 전체 문자열을 Bearer 방식으로 전달했다. 과거 예제의 Token 접두부를 그대로 사용하는 구성을 피했다. 두 형식의 구분은 NetBox 공식 REST API 문서에 설명되어 있다.

v1 토큰: Authorization: Token <기존 v1 토큰>
v2 토큰: Authorization: Bearer nbt_<키>.<토큰 값>

위 내용은 형식 예시다. 실제 토큰은 글·Git·일반 실행 로그에 넣지 않고 AWX Credential에서 주입했다. HA로 구성한 두 NetBox 앱에는 동일한 API_TOKEN_PEPPERS를 적용했다. 이는 토큰 검증에 사용하는 서버 설정이며, 사용자에게 발급하는 API 토큰 자체와는 다르다.

토큰 문제를 점검할 때에는 서버의 HTTPS 연결, 인증 헤더, 토큰 만료, 사용자 권한을 나누어 확인한다. 이 기록에는 인증 실패의 HTTP 상태 코드를 특정할 원본 응답이 남아 있지 않으므로, 특정 401·403 오류를 재현했다고 적지는 않는다.

2. API 입력 필드는 설치한 버전에서 조회한다

Custom Field를 만들기 전에 OPTIONS /api/extras/custom-fields/ 응답으로 POST 입력 스키마를 확인했다. 이 실습의 생성 데이터에는 group_name을 사용했고, 자산에 연결할 수 있는 필드는 API 응답에서 확인했다.

실제 자동화 코드의 핵심은 다음과 같다. api.request는 내부 HTTPS, 인증 헤더, 오류 처리를 담당하는 실습용 API 클라이언트다. 아래 코드는 독립 실행 명령이 아니라 스키마를 확인하는 부분의 발췌다.

post_fields = api.request(
    'extras/custom-fields/', 'OPTIONS'
)['actions']['POST']

if 'object_types' in post_fields:
    binding = 'object_types'
elif 'content_types' in post_fields:
    binding = 'content_types'
else:
    raise ValueError('Unsupported custom-field API binding')

필드 이름을 추측해 요청을 반복하는 대신, 설치된 버전에서 허용하는 입력을 기준으로 처리했다. 기존 Custom Field가 있으면 자료형이 같은지 검사하고, 다른 객체에 이미 연결된 목록을 보존하면서 필요한 연결을 추가했다. 호환되지 않는 자료형을 자동으로 바꾸어 기존 데이터를 손상시키지 않게 했다.

3. 실제 자산과 관리 IP를 분리해서 등록한다

VirtualBox 대상은 NetBox의 Virtual Machine 객체로 등록했다. 물리 장비는 Device 객체를 사용하도록 코드에서 경로를 구분했다. 이번 성공 증거는 VM에 대한 것이며 물리 서버 실장비 검증 결과는 아니다.

등록 순서는 VM → 인터페이스 → IP 주소 → 대표 관리 IP 연결이다. CPU·메모리 정보만 Custom Field에 모아 넣으면 NetBox의 기본 자산·IPAM 기능과 인벤토리 연동을 충분히 활용할 수 없다. 실제 대상의 hostname, 운영체제 고유 식별값, 관리 IP를 승인 목록과 대조하고, 다른 자산이 이미 사용 중인 IP는 변경 전에 거부하도록 했다.

수집에 실패한 필드는 빈 값으로 덮어쓰지 않는다. 기존 정상값을 보존하면서 수집 상태와 오류 사유를 따로 남긴다. 부분 수집 실패는 별도의 주입 시험으로 확인했으며 실제 하드웨어 고장 사례와 구분했다.

4. AWX 인벤토리에도 Bearer 방식과 실행환경을 맞춘다

API 등록이 성공하더라도 인벤토리 플러그인이 다른 인증 방식을 사용하면 AWX의 호스트 목록은 갱신되지 않는다. 사용한 netbox.netbox 3.23.0의 설정은 다음과 같다. 토큰 입력 형식은 공식 인벤토리 플러그인 문서를 함께 확인했다.

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.fullmoon.test
token:
  type: Bearer
  value: "{{ lookup('env', 'NETBOX_TOKEN') }}"
validate_certs: true
query_filters:
  - tag: auto
  - status: active

AWX에서는 자산 쓰기 계정과 인벤토리 조회 계정을 분리했다. 실행환경 이미지에는 사용한 collection과 내부 CA를 포함했다. 온라인망에서는 의존성을 받아 이미지를 만들고, 폐쇄망에는 완성된 이미지와 Git의 설정 파일을 반입한다. Job 실행 중 외부 Galaxy나 pip 연결이 필요한 구조로 남겨 두지 않았다.

5. 등록 성공은 다시 조회해서 확인한다

확인 항목 실제 확인 결과
초기 Custom Field와 카탈로그 구성 생성 완료
PROD VM과 대표 관리 IP 같은 자산으로 조회
NetBox 인벤토리 동기화 PROD·DEV·STG 대상 확인
AWX 호스트 변수 관리 IP와 환경 구분값 확인
같은 대상 재실행 중복 생성 방지와 변경 없음 확인
부분 수집 실패 기존 정상값 보존 확인

응답 코드 하나만으로 자산 연동이 끝났다고 판단하지 않았다. NetBox의 자산·인터페이스·IP 연결과 AWX의 실제 호스트 변수가 맞는지를 확인했다. 이 점검은 설치된 버전 조합에 대한 결과이므로, 버전을 바꿀 때에는 토큰·스키마·플러그인을 함께 다시 확인해야 한다.