VPN 설정
KIOPS에서 VPN 프로필을 관리하고 원격 인프라에 안전하게 접근하는 방법을 안내합니다.
VPN이 왜 필요한가요?
VPN(Virtual Private Network)은 원격에서 사내 네트워크에 안전하게 접근하기 위한 기술입니다.
- 원격 근무: VPN 없이는 사내 시스템에 접근할 수 없지만, VPN 사용 시 어디서든 사내망에 접근 가능합니다.
- 데이터 전송: VPN 없이는 평문 전송으로 도청 위험이 있지만, VPN 사용 시 암호화된 터널로 안전하게 전송됩니다.
- IP 화이트리스트: VPN 없이는 각 IP별로 방화벽 규칙을 추가해야 하지만, VPN 사용 시 VPN IP만 허용하면 됩니다.
- 클러스터 접근: VPN 없이는 공개 인터넷에 API를 노출해야 하지만, VPN 사용 시 내부 네트워크로만 접근합니다.
VPN 터널은 인터넷 상에서 암호화된 "가상의 전용선"을 만듭니다. 모든 트래픽이 암호화되어 전송되므로 중간에서 데이터를 가로채도 내용을 알 수 없습니다.
VPN 지원 유형
현재 KIOPS는 WireGuard를 정식 지원합니다. OpenVPN과 IPSec은 향후 지원을 위해 UI에 자리만 표시되어 있으며, 현재는 선택할 수 없습니다.
- WireGuard (정식 지원): 경량 프로토콜로 빠른 속도와 간편한 설정이 장점입니다. 키페어 기반 인증,
.conf파일 가져오기/내보내기, 모바일 호환성 모두 KIOPS에서 그대로 활용할 수 있습니다. - OpenVPN (추후 지원 예정): 기존 OpenVPN 인프라와의 호환성을 위해 향후 추가될 예정입니다. 현재 프로필 생성 폼에서는 선택이 비활성화되어 있습니다.
- IPSec (추후 지원 예정): 기업 표준 프로토콜로, OpenVPN과 함께 향후 지원이 검토되고 있습니다.
지금 단계에서는 선택할 필요 없이 WireGuard를 그대로 사용하시면 됩니다. 보안성·성능·운영 편의성 모두 검증된 프로토콜이며, 모바일 환경에서도 잘 작동합니다.
VPN 프로필 생성하기
원격 인프라에 접근하기 위한 VPN을 설정하는 방법입니다.
필요 권한: vpn 권한
Step 1: VPN 관리 페이지 이동
좌측 메뉴에서 **[VPN 관리]**를 클릭합니다.
Step 2: 새 VPN 프로필 추가
프로필 추가 버튼을 클릭합니다. VPN 프로필 설정 모달이 열립니다.
Step 3: VPN 유형 선택
VPN 유형 드롭다운에서 WireGuard를 선택합니다. OpenVPN과 IPSec은 "추후 지원 예정" 표기와 함께 비활성화되어 있어 선택할 수 없습니다.
Step 4: 기본 정보 입력
VPN 프로필의 기본 정보를 입력합니다:
- 프로필 이름: 프로필을 식별할 수 있는 이름입니다. (예:
datacenter-vpn) - 설명: 프로필에 대한 설명입니다. (예:
데이터센터 접근용 VPN) - 서버 주소: VPN 서버의 IP 또는 도메인입니다. (예:
vpn.company.com) - 포트: VPN 포트입니다. (예: WireGuard 기본값은
51820)
.conf 파일이 이미 있다면이미 발급받은 WireGuard 설정 파일(.conf)이 있다면 키 정보 섹션 안내문 아래의 ".conf에서 가져오기" 버튼으로 한 번에 입력할 수 있습니다. 파일을 업로드하면 서버 주소·포트·키·내부 IP·허용 IP·Keepalive 값이 모두 자동으로 채워집니다.
Step 5: 인증 정보 설정
WireGuard 인증에 필요한 키 정보를 입력합니다.
- Private Key (클라이언트 개인 키): 입력란 옆 "Client 키페어 생성" 버튼을 누르면 KIOPS가 안전한 Curve25519 키페어를 즉시 생성하고, Private Key는 자동으로 입력란에 채워지며 함께 생성된 Public Key는 별도 안내 영역에 표시됩니다. 표시된 Public Key는 VPN 서버 관리자에게 전달하여 피어로 등록해야 합니다. 외부에서 발급받은 키가 있다면 직접 붙여 넣어도 됩니다.
- Public Key (서버 공개 키): 접속할 VPN 서버의 Public Key입니다. 서버 관리자에게서 받은 값을 입력합니다. (위 단계에서 KIOPS가 생성한 클라이언트 Public Key와 다른 값입니다.)
- Preshared Key: 사전 공유 키입니다. 서버에서 PSK를 사용하는 경우에만 입력합니다. (선택사항, 추가 보안)
KIOPS는 Private Key를 저장 시 AES-256-GCM으로 암호화합니다. 한번 저장 후에는 마스킹되어 다시 조회할 수 없으므로, 백업이 필요하다면 "Client 키페어 생성" 직후 표시되는 화면에서 따로 보관하세요.
Step 6: 네트워크 설정
VPN 네트워크 설정을 입력합니다:
- 내부 IP: VPN 내에서 할당받을 IP입니다. (예:
10.0.0.2/24) - 허용 IP: VPN을 통해 라우팅할 네트워크입니다. (예:
10.0.0.0/8, 192.168.0.0/16) - DNS: VPN에서 사용할 DNS 서버입니다. (예:
10.0.0.1) - PersistentKeepalive: NAT 환경에서 연결을 유지하기 위한 keepalive 간격입니다. (기본 25초, 권장)
Step 7: 저장 및 테스트
저장 버튼을 클릭합니다. 저장 후 프로필 목록에서 해당 행의 연결 테스트 버튼으로 핸드셰이크가 정상적으로 이루어지는지 확인합니다. 테스트 결과는 모달에 단계별 진단 정보(서버 도달성, 핸드셰이크 성공 여부, 라우팅 확인)로 표시됩니다.
VPN 연결 활성화하기
설정된 VPN 프로필로 연결하는 방법입니다.
Step 1: VPN 프로필 선택
[VPN 관리] 페이지의 프로필 목록에서 연결할 VPN 프로필을 선택합니다.
Step 2: 연결 시작
연결 버튼을 클릭합니다.
Step 3: 연결 상태 확인
연결 상태를 확인합니다:
- 연결됨: VPN이 활성화되어 사용 가능한 상태입니다.
- 연결 중: 연결을 시도하는 중입니다.
- 연결 끊김: VPN이 비활성화된 상태입니다.
- 오류: 연결에 실패했습니다. 설정을 확인하세요.
Step 4: 연결 정보 확인
연결이 완료되면 다음 정보를 확인할 수 있습니다:
- 할당된 내부 IP
- 데이터 전송량
- 연결 시간
- 핸드셰이크 상태
연결 방식 (자동 / VPN / 직접 SSH)
장비, 런타임, 빌드/배포 등 SSH 명령이 필요한 모든 작업에서 KIOPS는 연결 방식 선택 모달로 사용자가 라우팅을 결정할 수 있게 합니다. 모드는 세 가지입니다.
- 자동 (Auto): 대상 인프라에 매칭되는 VPN 프로파일이 있고 활성 세션이 있으면 VPN 터널을 통해 접속하고, 그렇지 않으면 직접 SSH로 폴백합니다. 일반적인 상황에서 권장되는 기본값입니다.
- VPN: 항상 VPN 터널을 통해 접속합니다. 활성 세션이 없으면 즉시 빠른 연결 모달이 떠서 VPN 연결을 유도하며, 대상 IP가 AllowedIPs 범위 밖이면 명확한 오류 메시지로 알려 줍니다.
- 직접 SSH (Direct): VPN을 사용하지 않고, 등록된 다중 홉(점프 서버 → 타겟) 그대로 직접 접속합니다. VPN 프로파일이 있어도 무시됩니다.
자동/VPN 모드에서 활성 세션이 있고 대상 IP가 VPN의 AllowedIPs에 포함되면, KIOPS는 자동으로 등록된 점프 서버(상위 장비) hop을 건너뛰고, 타겟 서버의 SSH 정보만으로 직접 접속합니다. 즉, VPN 자체가 점프 서버 역할을 대체하므로 점프 서버 비밀번호/키를 따로 관리할 필요가 없습니다.
반대로 직접 SSH 모드를 선택하면 등록된 다중 홉이 그대로 사용되므로, 점프 서버와 타겟 서버 양쪽의 자격 증명이 모두 필요합니다.
다중 홉 인프라(예: 점프 서버 → 내부 타겟)에서 자동 hop strip이 동작하려면, 활성 VPN의 endpoint 가 등록된 게이트웨이 hop 중 하나와 일치해야 합니다. 일치하지 않으면 KIOPS는 다른 사이트의 같은 사설 IP 대역과 충돌할 위험을 피하기 위해 strip 을 하지 않으며, 자동 모드는 직접 SSH 폴백, VPN 모드는 안내 메시지와 함께 거부됩니다.
VPN을 통한 인프라 접근 설정
VPN을 통해서만 접근 가능한 클러스터를 등록하는 방법입니다.
사전 조건: VPN 프로파일이 설정되어 활성 세션이 있어야 합니다.
Step 1: VPN 연결 활성화
대상 네트워크에 접근 가능한 VPN에 먼저 연결합니다. 헤더의 VPN 상태 표시기가 활성으로 표시되는지 확인하세요.
Step 2: 런타임 환경 페이지 이동
좌측 메뉴에서 **[런타임 환경]**을 클릭합니다.
Step 3: 외부 런타임 가져오기
외부 런타임 가져오기 버튼을 클릭합니다. 연결 방식 선택 모달이 나타나면, 활성 세션이 있는 VPN 프로파일이 자동 매칭되어 자동 모드가 기본 선택됩니다. 필요하면 VPN 모드로 강제하거나, 다른 매칭 프로파일이 있을 때 드롭다운에서 변경할 수 있습니다.
Step 4: 클러스터 연결 정보 입력
VPN 내부 네트워크 주소를 사용하여 클러스터 연결 정보를 입력합니다. (예: 192.168.1.100:6443) 점프 서버 정보를 별도로 입력할 필요는 없습니다 — VPN 터널이 게이트웨이 역할을 대체합니다.
Step 5: 연결 테스트 및 저장
VPN을 통한 클러스터 연결을 테스트합니다. 연결 성공 시 저장합니다. 테스트가 실패하면 다음 두 가지 경우를 의심해 보세요.
- 대상 IP가 VPN의 AllowedIPs 범위에 포함되지 않은 경우 → VPN 프로파일의 AllowedIPs 설정을 보강합니다.
- 활성 VPN 의 endpoint 가 등록 게이트웨이 hop과 다른 경우 → 다른 VPN 프로파일을 선택하거나 직접 SSH 모드를 사용합니다.
WireGuard .conf 가져오기/내보내기
VPN 설정 파일을 통해 프로필을 빠르게 등록하거나, 등록된 프로필을 다른 클라이언트에서 사용할 수 있도록 내보내는 방법입니다.
.conf 파일 가져오기
[VPN 관리] 페이지에서 프로필 추가 모달을 연 뒤, 키 정보 섹션 안내문 아래의 ".conf에서 가져오기" 버튼을 클릭하여 WireGuard 설정 파일을 업로드합니다. 파일에 정의된 다음 항목이 폼에 자동으로 채워집니다.
- 서버 Endpoint 및 포트
- 클라이언트 Private Key
- 서버 Public Key, Preshared Key
- 클라이언트 내부 주소(Address), AllowedIPs, PersistentKeepalive
자동으로 채워지지 않은 항목(프로필 이름, 설명 등)만 직접 입력한 뒤 저장하면 됩니다.
.conf 파일 내보내기 / OpenVPN Config / QR 코드현재 KIOPS UI에는 .conf 다운로드 버튼이 제공되지 않습니다. 등록된 프로필을 다른 클라이언트에서 사용하려면 CLI 도구로 내보내는 방식만 지원되며, OpenVPN Config 형식 내보내기와 QR 코드 다운로드는 OpenVPN 정식 지원 시점에 함께 검토될 예정입니다.
VPN 빠른 연결 (Quick Connect)
장비나 런타임 작업을 시작하려는 시점에 VPN이 연결되어 있지 않다면, KIOPS는 페이지를 떠나지 않고도 VPN을 활성화할 수 있도록 Quick Connect 모달을 제공합니다.
- 장비 관리 / 런타임 환경 / 서비스 관리 페이지에서 VPN이 필요한 동작을 시도하면 자동으로 모달이 표시됩니다.
- 모달에서 사용 가능한 VPN 프로필을 선택하고 연결을 클릭하면 즉시 핸드셰이크가 진행됩니다.
- 헤더 우측의 VPN 상태 표시기가 색상과 아이콘으로 현재 활성 세션 수와 연결 상태를 알려 주므로, 어디서든 VPN 상태를 한눈에 확인할 수 있습니다.
KIOPS의 VPN 세션은 idle timeout 없이, 사용자가 명시적으로 연결 해제하거나 로그아웃할 때까지 유지됩니다. 장시간 작업 중 갑자기 끊길까봐 keepalive를 짧게 줄일 필요가 없습니다.
장비별 VPN 검증
VPN 프로필이 실제로 대상 장비에 도달 가능한지 한 번에 확인하는 기능입니다.
Step 1: 장비별 검증 모달 열기
[VPN 관리] 페이지의 프로필 목록에서 검증할 프로필 행의 장비 검증 버튼을 클릭합니다.
Step 2: 대상 장비 선택
해당 VPN을 통해 접근하는 등록 장비 목록이 표시됩니다. 한 번에 여러 장비를 선택할 수 있습니다.
Step 3: 검증 실행
검증 시작 버튼을 클릭합니다. KIOPS는 각 장비에 대해 다음을 순차적으로 점검합니다.
- 핸드셰이크 성공 여부
- 장비 IP/포트 도달성(TCP 연결)
- 등록된 SSH 자격 증명으로의 접속 성공 여부
각 항목별 결과는 통과/실패 색상으로 표시되며, 실패 시 원인(예: Connection refused, Permission denied)이 함께 노출됩니다.
VPN 연결 모니터링
VPN 연결 상태를 모니터링하는 방법입니다. [VPN 모니터링] 페이지는 PlatformAdmin 전용 메뉴이며, 일반 사용자에게는 별도의 vpn:monitor 권한 코드가 부여되지 않습니다.
Step 1: VPN 모니터링 페이지 이동
좌측 메뉴의 [VPN 모니터링] 페이지로 이동합니다. 화면 상단에 두 개의 탭이 있습니다.
- 활성 세션 (Active Sessions) 탭
- 이벤트 타임라인 (Event Timeline) 탭
Step 2: 활성 세션 확인
활성 세션 탭에서 현재 연결된 VPN 세션 정보를 확인합니다.
- 사용자: 세션을 보유한 사용자입니다.
- 프로필: 사용 중인 VPN 프로필입니다.
- 할당 IP: 세션이 부여받은 내부 IP입니다.
- 핸드셰이크 시각: 마지막 핸드셰이크가 이루어진 시간입니다.
- 트래픽: 세션의 송수신 누적 바이트입니다.
필요 시 행의 세션 종료 버튼으로 특정 세션을 강제 해제할 수 있습니다.
Step 3: 이벤트 타임라인 확인
이벤트 타임라인 탭에서 연결/해제/재핸드셰이크/오류 이벤트를 시간순으로 확인할 수 있습니다.
- 이벤트 종류 필터: 연결, 해제, 핸드셰이크 실패 등 종류별 필터링
- 사용자 필터: 특정 사용자의 이벤트만 조회
- 기간 필터: 최근 1시간/24시간/7일 등 기간 선택
VPN 프로필 삭제
더 이상 사용하지 않는 VPN 프로필을 삭제하는 방법입니다.
Step 1: 삭제할 프로필 선택
[VPN 관리] 페이지에서 삭제할 VPN 프로필을 클릭합니다.
Step 2: 연결 해제 확인
프로필이 연결된 상태라면 먼저 연결을 해제합니다.
Step 3: 프로필 삭제
삭제 버튼을 클릭합니다. 확인 대화상자에서 삭제를 클릭합니다.
Step 4: 연관 리소스 확인
이 VPN을 사용하는 런타임 환경이 있는지 확인하세요. 연관된 런타임의 연결이 실패할 수 있습니다.
자주 묻는 질문
VPN 연결이 실패합니다
원인 및 해결 방법:
- 서버 주소 오류: IP 또는 도메인이 올바른지 확인하세요.
- 포트 차단: 방화벽에서 WireGuard 포트(기본
51820/UDP)를 허용하세요. - 인증 정보 오류: Private Key, 서버 Public Key가 올바른지, 서버 측에 내 Public Key가 피어로 등록되어 있는지 확인하세요.
- 서버 다운: VPN 서버가 실행 중인지 확인하세요.
[VPN 관리] 페이지의 연결 테스트 / 장비 검증 버튼은 KIOPS 백엔드의 진단 로직을 통해 핸드셰이크, 라우팅, SSH 도달성을 단계별로 점검해 줍니다. 실패 단계와 원인이 함께 표시되므로, 일반 클라이언트보다 훨씬 빠르게 원인을 파악할 수 있습니다.
VPN 연결이 자주 끊깁니다
- Keep-alive 설정: WireGuard는
PersistentKeepalive = 25설정 권장 - 네트워크 변경: 와이파이 ↔ 모바일 전환 시 재연결 필요
- NAT 타임아웃: 공유기 NAT 세션 타임아웃 확인
VPN을 통해 클러스터 접근이 안 됩니다
- 허용 IP 범위: 클러스터 네트워크(예:
10.0.0.0/8)가 Allowed IPs에 포함되어 있는지 - 라우팅 설정: VPN 서버에서 클러스터 네트워크로의 라우팅이 설정되어 있는지
- DNS 해석: 클러스터 내부 도메인이 해석되는지 (VPN DNS 설정 확인)
속도가 느립니다
- MTU 조정: 기본값보다 낮은 MTU(1280~1400)를 시도해 보세요
- 서버 위치: 가까운 지역의 VPN 서버를 사용하세요
- AllowedIPs 범위: 너무 넓은 범위(예:
0.0.0.0/0)로 설정하면 모든 트래픽이 VPN을 거치므로 느려질 수 있습니다. 필요한 사내망 대역만 지정하세요