본문으로 건너뛰기

VPN 설정

KIOPS에서 VPN 프로파일을 관리하고 원격 인프라에 안전하게 접근하는 방법을 안내합니다.

VPN 관리 페이지

VPN이 왜 필요한가요?​

VPN(Virtual Private Network)은 원격에서 사내 네트워크에 안전하게 접근하기 위한 기술입니다. 인터넷 위에 암호화된 "가상의 전용선"(터널)을 만들어, 트래픽이 중간에서 가로채여도 내용을 알 수 없게 합니다. 원격 근무 시 어디서든 사내망에 접근하고, 데이터를 암호화해 전송하며, 방화벽에서 VPN IP만 허용하면 되고, API를 공개 인터넷에 노출하지 않고 내부 네트워크로만 클러스터에 접근할 수 있습니다.

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 프로파일 추가 버튼을 클릭합니다. VPN 프로파일 설정 모달이 열립니다. (목록이 비어 있는 경우 첫 VPN 프로파일 추가하기 버튼을 클릭합니다.)

Step 3: VPN 유형 선택​

VPN 유형 드롭다운에서 WireGuard를 선택합니다. OpenVPN과 IPSec은 "추후 지원 예정" 표기와 함께 비활성화되어 있어 선택할 수 없습니다.

Step 4: 기본 정보 입력​

VPN 프로파일의 기본 정보를 입력합니다:

  • 프로파일 이름: 프로파일을 식별할 수 있는 이름입니다. (예: datacenter-vpn)
  • 설명: 프로파일에 대한 설명입니다. (예: 데이터센터 접근용 VPN)
  • 서버 주소: VPN 서버의 IP 또는 도메인입니다. (예: vpn.company.com)
  • 포트: VPN 포트입니다. (예: WireGuard 기본값은 51820)

이미 발급받은 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 터널을 통한 SSH 연결이 가능한지 확인합니다. 테스트 시 대상 호스트 IP, SSH 포트, 사용자명, 비밀번호를 입력하며, 결과는 성공/실패 여부와 응답 지연(latency, ms)으로 모달에 표시됩니다. (WireGuard 핸드셰이크 성립 여부 등 단계별 터널 진단은 별도의 세션 진단 기능에서 제공됩니다.)

VPN 연결 활성화하기​

설정된 VPN 프로파일로 연결하는 방법입니다.

Step 1: VPN 프로파일 선택​

[VPN 관리] 페이지의 프로파일 목록에서 연결할 VPN 프로파일을 선택합니다.

Step 2: 연결 시작​

연결 버튼을 클릭합니다.

Step 3: 연결 상태 확인​

연결 상태(연결됨 / 연결 중 / 연결 끊김 / 오류)를 확인합니다. 상태 배지의 의미와 대응은 상태 사전을 참고하세요.

Step 4: 연결 정보 확인​

연결이 완료되면 할당된 내부 IP, 데이터 전송량, 연결 시간, 핸드셰이크 상태를 확인할 수 있습니다.

연결 방식 (VPN / 직접 SSH)​

장비, 런타임, 빌드/배포 등 SSH 명령이 필요한 작업에서 KIOPS는 대상의 접속 경로를 판단하여 연결 방식을 결정합니다.

  • 접속 경로가 하나뿐이면(대상 IP를 커버하는 VPN 프로파일이 없는 경우) 선택 모달 없이 직접 SSH로 자동 연결됩니다.
  • 직접·VPN 모두 가능한 경우(대상 IP가 VPN의 AllowedIPs에 커버되는 경우)에만 연결 방식 선택 모달이 표시되어 사용자가 라우팅을 결정합니다. 선택지는 두 가지입니다.
    • VPN: VPN 터널을 통해 접속합니다. 활성 세션이 없으면 빠른 연결 모달이 떠서 VPN 연결을 유도하며, 대상 IP가 AllowedIPs 범위 밖이면 명확한 오류 메시지로 알려 줍니다.
    • 직접 SSH (Direct): VPN을 사용하지 않고, 등록된 다중 홉(점프 서버 → 타겟) 그대로 직접 접속합니다.

과거의 자동/VPN/직접 SSH 세 가지 모드는 정리되어, 현재는 VPN / 직접 SSH 두 가지 중 사용자가 명시적으로 선택합니다(단일 경로는 자동 직접 연결). 모달의 기본 선택은 활성 VPN 세션이 있으면 VPN, 없으면 직접 SSH입니다.

VPN을 사용하면 점프 서버 자격 증명이 필요 없습니다. VPN 경로에 활성 세션이 있고 대상 IP가 AllowedIPs에 포함되면, KIOPS는 등록된 점프 서버(상위 장비) 홉을 자동으로 건너뛰고 타겟 서버의 SSH 정보만으로 직접 접속합니다. VPN 자체가 점프 서버 역할을 대신하기 때문입니다.

반대로 직접 SSH를 선택하면 등록된 다중 홉이 그대로 사용되므로 점프 서버와 타겟 양쪽의 자격 증명이 모두 필요합니다. 한 번 입력한 자격증명은 서버에 암호화 저장되어 자동으로 재사용됩니다.

단, 장비가 여러 단계로 등록된 환경에서 점프 서버를 자동으로 건너뛰려면 활성 VPN의 endpoint 가 등록된 게이트웨이 홉 중 하나와 일치해야 합니다. 일치하지 않으면 KIOPS는 다른 사이트의 같은 사설 IP 대역과 충돌할 위험을 피하기 위해 점프 서버를 건너뛰지 않고 VPN 모드를 안내 메시지와 함께 거부하므로, 이 경우 직접 SSH를 사용하세요.

VPN을 통한 인프라 접근 설정​

VPN을 통해서만 접근 가능한 클러스터를 등록하는 방법입니다.

사전 조건: VPN 프로파일이 설정되어 활성 세션이 있어야 합니다.

Step 1: VPN 연결 활성화​

대상 네트워크에 접근 가능한 VPN에 먼저 연결합니다. 헤더의 VPN 상태 표시기가 활성으로 표시되는지 확인하세요.

Step 2: 런타임 환경 페이지 이동​

좌측 메뉴에서 [런타임 환경]을 클릭합니다.

Step 3: 외부 런타임 가져오기​

외부 런타임 가져오기 버튼을 클릭합니다. 대상이 VPN에 커버되면 연결 방식 선택 모달이 나타나며, 활성 세션이 있는 VPN 프로파일이 자동 매칭되어 VPN 모드가 기본 선택됩니다. 필요하면 직접 SSH로 바꾸거나, 다른 매칭 프로파일이 있을 때 드롭다운에서 변경할 수 있습니다.

Step 4: 클러스터 연결 정보 입력​

VPN 내부 네트워크 주소를 사용하여 클러스터 연결 정보를 입력합니다. (예: 192.168.1.100:6443) 점프 서버 정보를 별도로 입력할 필요는 없습니다 — VPN 터널이 게이트웨이 역할을 대체합니다.

Step 5: 연결 테스트 및 저장​

VPN을 통한 클러스터 연결을 테스트합니다. 연결 성공 시 저장합니다. 테스트가 실패하면 다음 두 가지 경우를 의심해 보세요.

  • 대상 IP가 VPN의 AllowedIPs 범위에 포함되지 않은 경우 → VPN 프로파일의 AllowedIPs 설정을 보강합니다.
  • 활성 VPN 의 endpoint 가 등록 게이트웨이 홉과 다른 경우 → 다른 VPN 프로파일을 선택하거나 직접 SSH 모드를 사용합니다.

WireGuard .conf 가져오기/내보내기​

VPN 설정 파일을 통해 프로파일을 빠르게 등록하거나, 등록된 프로파일을 다른 클라이언트에서 사용할 수 있도록 내보내는 방법입니다.

.conf 파일 가져오기​

[VPN 관리] 페이지에서 VPN 프로파일 추가 모달을 연 뒤, 키 정보 섹션 안내문 아래의 ".conf에서 가져오기" 버튼을 클릭하여 WireGuard 설정 파일을 업로드합니다. 파일에 정의된 다음 항목이 폼에 자동으로 채워집니다.

  • 서버 Endpoint 및 포트
  • 클라이언트 Private Key
  • 서버 Public Key, Preshared Key
  • 클라이언트 내부 주소(Address), AllowedIPs, PersistentKeepalive

자동으로 채워지지 않은 항목(프로파일 이름, 설명 등)만 직접 입력한 뒤 저장하면 됩니다.

참고: 현재 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 관리] 페이지에서 삭제할 VPN 프로파일을 클릭합니다.

Step 2: 연결 해제 확인​

프로파일이 연결된 상태라면 먼저 연결을 해제합니다.

Step 3: 프로파일 삭제​

삭제 버튼을 클릭합니다. 확인 대화상자에서 삭제를 클릭합니다.

Step 4: 연관 리소스 확인​

이 VPN을 사용하는 런타임 환경이 있는지 확인하세요. 연관된 런타임의 연결이 실패할 수 있습니다.

자주 묻는 질문​

VPN 연결이 실패합니다​

원인 및 해결 방법:

  • 서버 주소 오류: IP 또는 도메인이 올바른지 확인하세요.
  • 포트 차단: 방화벽에서 WireGuard 포트(기본 51820/UDP)를 허용하세요.
  • 인증 정보 오류: Private Key, 서버 Public Key가 올바른지, 서버 측에 내 Public Key가 피어로 등록되어 있는지 확인하세요.
  • 서버 다운: VPN 서버가 실행 중인지 확인하세요.

[VPN 관리] 페이지의 연결 테스트는 VPN 터널을 통한 SSH 도달성을, 세션 진단은 WireGuard 핸드셰이크 성립 여부 등 터널 상태를 점검합니다. 실패 시 원인이 함께 표시되므로 일반 클라이언트보다 빠르게 원인을 파악할 수 있습니다.

VPN 연결이 자주 끊깁니다​

  • Keep-alive 설정: WireGuard는 PersistentKeepalive = 25 설정 권장
  • 네트워크 변경: 와이파이 ↔ 모바일 전환 시 재연결 필요
  • NAT 타임아웃: 공유기 NAT 세션 타임아웃 확인

VPN을 통해 클러스터 접근이 안 됩니다​

다음 세 가지를 확인하세요.

  1. 허용 IP 범위: 클러스터 네트워크(예: 10.0.0.0/8)가 Allowed IPs에 포함되어 있는지
  2. 라우팅 설정: VPN 서버에서 클러스터 네트워크로의 라우팅이 설정되어 있는지
  3. DNS 해석: 클러스터 내부 도메인이 해석되는지 (VPN DNS 설정 확인)

속도가 느립니다​

  • MTU 조정: 기본값보다 낮은 MTU(1280~1400)를 시도해 보세요
  • 서버 위치: 가까운 지역의 VPN 서버를 사용하세요
  • AllowedIPs 범위: 너무 넓은 범위(예: 0.0.0.0/0)로 설정하면 모든 트래픽이 VPN을 거치므로 느려질 수 있습니다. 필요한 사내망 대역만 지정하세요

관련 가이드​