개요 — 무엇을 하나
인스턴스는 InfraGuard 가 관리하는 **"운영체제를 가진 접속 가능한 머신"**의 대장(CMDB)입니다. 물리 서버·VM(KVM/VMware/Proxmox)·클라우드 노드(AWS/GCP/Azure) 등 SSH 로 접근 가능한 OS 인스턴스를 한 곳에 등록하고, 검색·필터·정렬·페이지네이션과 모달 기반 추가/편집/삭제를 제공합니다.
이 데이터는 앱이 **자체 소유(read/write)**하는 신규 테이블 infr_instance 에 저장됩니다(레거시 무접두 테이블과 무관). 각 인스턴스는 다음을 갖습니다.
- 식별 — 표시 이름, 호스트명/FQDN(고유), 그리고
alias(메트릭 별칭). - 접속(SSH) — 호스트/포트/사용자/인증 방식 + 자격증명 참조(
cred_ref). 비밀번호·키 원문은 화면으로 되돌려주지 않습니다. - 네트워크 — 대표 내부 IP(필수)·외부 IP(선택) +
nics(JSON): NIC 별 다중 IP. - 분류/수명 — 환경(env)·역할(role)·유형(provider)·중요도(criticality)·상태(status)·패치 트랙(patch_track)·런칭일(launched_on)·담당자·위치·태그.
- 플랫폼 — OS 계열/배포판/커널/아키텍처/CPU·메모리·디스크.
alias는 정규 조인 키입니다. OS 인스턴스를 여러 서브시스템(레거시server_status메트릭, 수집기 메트릭, DB 수집기 등)에 잇는 축이alias입니다. 코드는alias로 조인할 때 정확히 1개 인스턴스가 매칭됨을 전제합니다(대소문자 무시 매칭, 예:BLUE↔blue). 따라서 alias 는 인스턴스마다 고유해야 합니다. 호스트명(hostname)에는 DB UNIQUE 제약이 걸려 있고, alias 유일성은 운영 규약으로 지킵니다.
인스턴스 카드는 [edit]·[ver]·[env]·[param]·[tool]·[fw]·[ssh] 액션과 각 하위 등록 갯수 배지(버전/변수/파라미터/방화벽 룰)를 함께 보여줍니다.
언제 쓰나
- 새 서버·VM·클라우드 노드를 도입해 자산 대장에 등록할 때.
- 라이브 메트릭 화면(서버·헬스)에 노드가 잡히도록
alias를server_status.server_alias와 정렬할 때. - SSH 접속 정보를 표준화하고, 브라우저 터미널·원격 에뮬레이트의 대상으로 삼을 때.
- 인스턴스별 소프트웨어 버전 원장·환경 변수·서버 파라미터·방화벽 룰을 관리할 때.
- 물리 하드웨어(Hardware)와 OS 인스턴스를
instance_id로 연결할 때.
화면 구성
상단 — 검색·필터·정렬 바
| 컨트롤 | 동작 |
|---|---|
검색어(q) |
이름·호스트명·별칭·SSH 호스트·내부/외부 IP·역할·OS·위치·nics(JSON 텍스트)를 부분일치(LIKE) 검색 |
| 필터 | 환경(env)·상태(status)·중요도(criticality)·유형(provider)·담당자(owner) 정확 일치 |
| 정렬 | 이름·호스트·환경·중요도·상태·유형·OS·CPU·메모리·최근 확인·수정일 (화이트리스트) · 방향 asc/desc |
| 페이지 | per(5–100, 기본 20) · page |
기본 정렬은 hostname asc(동률 시 id asc)입니다.
본문 — 인스턴스 카드
각 인스턴스는 2행 카드로 표시되며, 헤더 정보와 함께 다음 액션 아이콘을 갖습니다.
| 액션 | 의미 | 문서 |
|---|---|---|
| edit | 인스턴스 편집(삭제는 편집 모달 푸터) | 아래 §사용법 |
| ver | 소프트웨어 버전 원장(1:N) | 버전 관리 |
| env | 인스턴스별 환경 변수(Crypt) | 환경 변수 |
| param | 서버 파라미터 스냅샷(웹·DB·커널·앱·그외) | 서버 파라미터 |
| tool | 툴박스 — 등록 Tools 를 이 인스턴스 값으로 채워 복사 | 인벤토리 |
| fw | 방화벽 룰(오픈 포트 CMDB) | 방화벽 룰 |
| ssh | 브라우저 터미널(대화형 PTY) | SSH 터미널 |
카드에는 하위 등록 갯수 배지가 붙습니다: ver_count(버전)·env_count(변수)·param_count(파라미터)·fw_count(방화벽 룰). 이 값은 페이지 단위 배치 집계로 N+1 없이 계산됩니다.
사용법
인스턴스 추가/편집
- [인스턴스 추가] 또는 카드의 [edit] 을 누르면 모달이 열립니다.
- 섹션별로 입력합니다: 식별 → 접속·SSH → 네트워크 → 플랫폼 → 분류·메모.
- [저장] 하면
POST /asset/instances/save로 전송됩니다.id가 있으면 수정, 없으면 생성입니다.
주요 필드와 검증:
| 필드 | 규칙 | 비고 |
|---|---|---|
name |
필수, ≤100 | 표시 이름 |
hostname |
필수, ≤150, UNIQUE | OS 호스트명/FQDN |
alias |
선택, ≤60 | 라이브 메트릭 조인 키(server_status) |
env |
필수 | prod·staging·dev·dr |
provider |
필수 | baremetal·vm·kvm·vmware·proxmox·aws·gcp·azure·other |
criticality |
필수 | low·normal·high·critical(=tier) |
status |
필수 | active·maintenance·inactive·retired |
patch_track |
필수 | auto·scheduled·manual·frozen·eol |
launched_on |
선택, date | 런칭일(범용 운영 필드) |
ssh_host |
필수, ≤150 | SSH 접속 주소 |
ssh_port |
필수, 1–65535 | 기본 22 |
ssh_user |
필수, ≤64 | 기본 root |
auth_method |
필수 | key·password |
cred_ref |
선택, ≤120 | 비밀은 저장하지 않고 참조만 |
ip_private |
필수, 유효 IP | 대표 내부 IP |
ip_public |
선택, 유효 IP | 내부 전용 서버는 없음 |
nics |
선택, 배열 | [{name,mac,private[],public[]}] — 각 IP 유효성 검사 |
os_family |
필수 | linux·bsd·windows·macos·other |
arch |
필수 | x86_64·arm64·other |
cpu_cores/mem_mb/disk_gb |
선택, 정수 | 사양 |
owner_ref |
선택 | user:5 / team:3 (담당자 선택기) |
nics(JSON) 는 인터페이스별 다중 IP 를 담습니다. 각 NIC 의 내부/외부 IP 는 쉼표·공백으로 여러 개 입력할 수 있고, 서버가 정규화합니다(빈 행은 스킵).
SSH 개인키(key 인증)
auth_method = key 인스턴스는 편집 폼에 **개인키(PEM/OpenSSH)**를 붙여넣어 저장할 수 있습니다(≤12000자). 서버가 Laravel Crypt(APP_KEY) 로 암호화해 ssh_key_enc 에 보관하고, passphrase 는 ssh_key_pass_enc 에 저장합니다.
- 응답에는 평문 키가 절대 실리지 않습니다 —
has_ssh_key(불리언)만 노출됩니다. - 새 키를 붙여넣으면 교체, 비우면 유지됩니다.
- 저장된 키만 즉시 삭제하려면
ssh_key_clear를 켜거나POST /asset/instances/ssh/key/delete를 호출합니다(감사 기록). - 접속 시 키는 SSH 브리지로만 릴레이되며 브리지에 저장되지 않습니다. 자세한 접속 흐름은 SSH 터미널 참고.
JSON import 로 폼 채우기(프로브)
필드를 손으로 채우는 대신, 대상 호스트에서 로컬 프로브를 실행해 나온 JSON 으로 폼을 일괄 채울 수 있습니다.
- 편집 모달의 JSON import 토글을 켭니다.
- [코드복사] 로
infr_instance_probe.cjs소스를 복사합니다(우선 Inventory ▸ Tools 의 시드 스니펫 본문, 없으면 리포지토리 파일 폴백). - 대상 호스트에서 실행합니다.
# 대상 호스트에서 로컬 실행 — 크리덴셜 불필요, 외부 호출 없음
node infr_instance_probe.cjs # 사람이 보기 좋은 들여쓰기 JSON
node infr_instance_probe.cjs --min # 한 줄(minified)
출력 예시:
{
"hostname": "blue.infra.local",
"os_family": "linux",
"os_name": "Ubuntu 22.04.4 LTS",
"kernel": "5.15.0-105-generic",
"arch": "x86_64",
"cpu_cores": 16,
"mem_mb": 64158,
"disk_gb": 890,
"ip_private": "10.0.0.21",
"ip_public": "203.0.113.10",
"provider": "kvm",
"location": "Asia/Seoul",
"launched_on": "2023-11-02",
"nics": [{ "name": "eth0", "mac": "52:54:00:ab:cd:ef", "private": ["10.0.0.21"], "public": [] }]
}
- JSON 을 붙여넣고 [가져오기] 를 누르면 현재 편집 중인 인스턴스의 폼이 채워집니다(신규 생성 아님). 저장하기 전까지는 반영되지 않습니다.
프로브 병합은 탐지 필드만 대상으로 합니다:
role·os_name·kernel·location·ip_private·ip_public·cpu_cores·mem_mb·disk_gb·provider·patch_track·os_family·arch·launched_on·nics. 사람이 정하는 값(표시 이름·호스트명·alias·환경·중요도·상태·SSH 접속 정보)은 건드리지 않습니다. 서버 측 적용 경로(POST /asset/instances/apply-probe)는 원격 에뮬레이트가 프로브를 원격 실행해 같은 화이트리스트만 병합·저장할 때 쓰입니다.
삭제
편집 모달 푸터의 [삭제] → 확인 → POST /asset/instances/delete. 되돌릴 수 없으며 감사에 기록됩니다.
데이터 소스
| 테이블 | 용도 |
|---|---|
infr_instance |
인스턴스 대장(이 화면이 소유·read/write). 마이그레이션 000600 (+ 000643 SSH 키, 000763 owner_type) |
server_status (레거시) |
alias 로 조인되는 라이브 메트릭 원천(읽기 전용) — Servers/Health가 소비 |
infr_instance_software |
[ver] 버전 원장 갯수(ver_count) |
infr_instance_var |
[env] 환경 변수 갯수(env_count) |
infr_instance_param |
[param] 서버 파라미터 갯수(param_count) |
infr_instance_firewall |
[fw] 방화벽 룰 갯수(fw_count) |
infr_audit_log |
create/update/delete/apply_probe/ssh_key.delete 감사 |
주요 컬럼(발췌):
id, name, hostname(unique), alias(index),
env, role, provider, criticality, status, patch_track, launched_on,
ssh_host, ssh_port(22), ssh_user(root), auth_method, cred_ref,
ssh_key_enc, ssh_key_pass_enc, -- Crypt · $hidden(응답 미노출)
ip_private, ip_public, nics(json),
os_family, os_name, kernel, arch, cpu_cores, mem_mb, disk_gb,
location, owner_id, owner_type, tags(json), note, last_seen_at, created_by, timestamps
권한
| 작업 | 요구 레벨 |
|---|---|
| 조회(index·list) | 로그인(≥1, infr.auth) |
| 저장·삭제·프로브 적용·SSH 키 삭제 | user_level ≥ 2 (canWrite) |
레벨 기준: demo=1, staff=5, admin=10 — 쓰기는 staff 이상이면 충족합니다(2 이상 요구). 파괴적·보안 작업(생성/수정/삭제/프로브 적용/키 삭제)은 모두 infr_audit_log 에 기록됩니다. 자세한 등급 체계는 RBAC 레벨·사용자·팀 참고.
저장된 SSH 개인키·passphrase 는 서버에만 암호화 보관되고 브라우저로 되돌아오지 않습니다(
has_ssh_key불리언만). 자격증명은 인스턴스 필드에 평문으로 넣지 말고cred_ref참조나 인스턴스별 환경 변수(Crypt)를 사용하세요.
문제해결 · FAQ
- [서버]/[헬스]에 노드가 안 보여요.
alias가server_status.server_alias와 일치하는지 확인하세요(대소문자 무시로 매칭하지만 오탈자는 안 됨). 수집기가 그 alias 로 데이터를 넣고 있어야 합니다. - 저장이 403(권한 없음)입니다. user_level ≥ 2 가 필요합니다(레벨 2 이상). demo(1) 계정은 조회만 가능합니다.
- 호스트명 중복 오류.
hostname은 UNIQUE 입니다. 서로 다른 인스턴스면 FQDN 을 구분하세요. - 내부 IP 필수 검증 실패.
ip_private는 유효 IP 가 반드시 필요합니다. 외부 전용처럼 보여도 내부 대표 IP 를 넣으세요. - JSON import 후 변화가 없어요. import 는 폼만 채웁니다 — [저장] 을 눌러야 반영됩니다. 또한 이름·alias·env·중요도·SSH 등은 프로브가 채우지 않습니다(사람이 입력).
- 프로브가 외부 IP 를 비워둡니다. NAT 뒤 호스트는 공인 IP 를 바인딩된 인터페이스에서만 추론합니다. 필요하면 수동 입력하세요.
- 저장된 개인키를 지우고 싶어요. 편집 모달에서 키 삭제 토글을 켜고 저장하거나, SSH 키 삭제 액션을 사용하세요(감사 기록).
관련 항목
- SSH 터미널 — 브라우저 대화형 PTY 콘솔
- 버전 관리 · 환경 변수 · 서버 파라미터 · 방화벽 룰
- 원격 에뮬레이트 — 프로브 원격 실행·적용(apply-probe)
- Hardware — 물리 하드웨어를
instance_id로 연결 - Servers · Health — alias 로 잇는 라이브 메트릭
