포스트

WireGuard로 Private API 연결하기

WireGuard로 Private API 연결하기

클라우드 환경의 애플리케이션이 사내 네트워크에 놓인 API 서버를 호출해야 했다. 해당 서버는 정해진 애플리케이션만 사용하므로 인터넷에 공개할 이유가 없었다. 간단하게 정리하자면, 두 호스트 사이에 필요한 경로만 만들고 싶었다.

이를 위해 WireGuard로 사설 터널을 구성하고, API 컨테이너는 WireGuard Sidecar와 Network Namespace를 공유하도록 했다.

이 글에서는 WireGuard의 기본 개념부터 NAT 뒤의 서버를 연결한 구조, 간단한 설정과 운영 중 확인한 주의점을 정리한다. 실제 구성에서 사용한 제품명, Cloud Provider, 주소, Port, Key와 서비스 이름은 모두 일반화했으며 아래 설정값은 설명을 위한 예시다.


I. 연결 요구사항

1. API Port를 공개하지 않는다

가장 중요한 요구사항은 사내 서버의 API Port를 인터넷에 공개하지 않는 것이었다. TLS와 애플리케이션 인증을 적용하더라도 Public Endpoint가 생기면 관리 지점이 필연적으로 늘어난다.

연결 범위도 최소화하고 싶었다. Cloud Network 전체와 사내 Network 전체를 연결하는 것이 아니라, 애플리케이션 호스트와 연산 호스트가 서로의 Tunnel IP 하나만 알면 충분했다.

요구사항선택 기준
외부 노출Application API Port는 공개하지 않는다
연결 범위두 Peer의 Tunnel IP만 연결한다
NATNAT 뒤의 연산 서버가 먼저 Tunnel을 연다
인증VPN과 별개로 기존 Application 인증을 유지한다
배포API는 기존 Container 배포 방식을 유지한다
운영Linux Host에서 직접 상태를 확인할 수 있어야 한다

2. WireGuard가 요구사항과 맞았던 이유

WireGuard가 모든 환경에서 정답이라서 선택한 것은 아니다. 이번에는 다음 조건이 요구사항과 맞았다.

  • 두 Linux Host 사이에 하나의 Private 연결만 필요했다.
  • NAT 뒤의 Peer가 외부 Endpoint로 연결을 시작할 수 있어야 했다.
  • VPN을 위해 Application Container의 구현을 바꾸고 싶지 않았다.
  • 전체 Network가 아니라 Peer별 Tunnel Address 범위만 명시하고 싶었다.
  • Handshake와 전송 상태를 Host에서 직접 확인할 수 있어야 했다.

II. WireGuard의 기본 개념

1. 암호화된 Layer 3 Tunnel을 만든다

WireGuard는 운영체제에 가상 Network Interface를 만들고, 그 Interface로 들어온 IP Packet을 암호화해 UDP로 전달한다. 애플리케이션은 일반적인 IP 주소로 통신하고, WireGuard가 암·복호화와 Peer 전달을 맡는다.

1
2
3
4
5
6
7
8
Application Packet
  → Routing Table
  → WireGuard Interface
  → Encrypt
  → UDP
  → Peer
  → Decrypt
  → Destination

WireGuard에는 고정된 Server와 Client 역할이 없다. 양쪽 모두 Peer이며, 외부에서 도달 가능한 쪽이 UDP Endpoint를 제공하고 NAT 뒤의 Peer가 그 Endpoint로 먼저 Handshake를 보낼 수 있다.

WireGuard Protocol은 Curve25519, ChaCha20-Poly1305, BLAKE2s와 같은 고정된 암호학적 구성요소를 사용한다. 운영자가 Cipher Suite 조합을 선택하는 대신 Protocol이 사용할 조합을 작게 유지한다.

2. Public Key와 AllowedIPs로 Peer를 찾는다

각 Peer는 Private Key와 Public Key 한 쌍을 가진다. Private Key는 자신의 Host에만 보관하고, 상대에게는 Public Key만 전달한다.

WireGuard의 중요한 특징은 Public Key와 Tunnel IP Route를 함께 연결하는 Cryptokey Routing이다. 설정의 AllowedIPs는 송신 시 목적지 IP를 어느 Peer에게 보낼지 정하고, 수신 시 해당 Peer가 사용할 수 있는 Source IP를 검사한다.

1
2
Peer Public Key A ↔ AllowedIPs 10.200.0.1/32
Peer Public Key B ↔ AllowedIPs 10.200.0.2/32

이 구성에서는 각 Peer가 상대의 Tunnel IP 하나만 담당한다. 0.0.0.0/0처럼 모든 트래픽을 한 Peer에게 보내지 않고, 상대의 Tunnel IP만 해당 Peer와 연결한다.

다만 AllowedIPs가 Application Firewall이나 사용자 권한을 대신하지는 않는다. Tunnel에 들어온 요청도 기존 API Token과 권한 검사를 그대로 통과하도록 했다.

3. NAT 뒤에서는 Keepalive가 필요할 수 있다

NAT 장비는 일정 시간 Packet이 없으면 UDP Mapping을 제거할 수 있다. 그 이후 외부 Peer가 먼저 Packet을 보내면 NAT 뒤의 Peer까지 도달하지 못한다.

이 경우 NAT 뒤의 Peer에 PersistentKeepalive를 설정하면 주기적으로 인증된 빈 Packet을 보내 Mapping을 유지한다. WireGuard Quick Start는 일반적인 Firewall에서 무난한 간격으로 25초를 안내한다.

1
PersistentKeepalive = 25

Keepalive는 모든 Peer에 무조건 넣는 옵션이 아니다. NAT 또는 Stateful Firewall 뒤에서 외부 Peer의 선제 통신을 받아야 하는 쪽에만 적용하는 편이 낫다.


III. 선택한 연결 구조

1. NAT 뒤의 Peer가 Tunnel을 시작한다

최종 구조에서는 외부에 WireGuard용 UDP Endpoint만 두고, Application API Port는 공개하지 않았다. NAT 뒤의 연산 서버가 UDP Endpoint로 Handshake를 시작하면 Cloud Peer가 실제 Endpoint를 학습하고 양방향으로 통신한다.

flowchart LR
    subgraph CLOUD[Cloud Private Network]
        APP[Application]
        CWG[WireGuard Peer<br/>wg0]
        APP -->|Tunnel IP로 요청| CWG
    end

    EDGE[Public UDP Endpoint<br/>WireGuard only]
    NAT[NAT / Firewall]

    subgraph REMOTE[Remote Compute Host]
        RWG[WireGuard Sidecar<br/>wg0]
        API[Private API<br/>No Host Port]
        RWG ---|Network Namespace 공유| API
    end

    CWG --- EDGE
    EDGE <-->|WireGuard UDP| NAT
    NAT --- RWG

외부에는 WireGuard UDP 수신 Port만 노출하고, 유효한 Peer의 Packet만 WireGuard가 인증해 처리한다. Cloud에서 보내는 Application 요청과 응답에는 Tunnel IP를 사용한다.

2. AllowedIPs를 /32로 제한한다

양쪽 AllowedIPs에는 상대 Peer의 Tunnel IP를 /32로 등록했다. 따라서 Subnet 전체나 Default Route를 Peer와 연결하지 않고, 상대의 Tunnel IP 하나만 해당 Public Key에 대응시킨다.

1
2
3
4
5
6
7
Cloud Peer
  Interface Address = 10.200.0.1/24
  Peer AllowedIPs   = 10.200.0.2/32

Remote Peer
  Interface Address = 10.200.0.2/24
  Peer AllowedIPs   = 10.200.0.1/32

Interface Address의 Prefix와 AllowedIPs의 역할은 다르다. Linux는 Interface Prefix를 바탕으로 Connected Route를 만들 수 있지만, WireGuard는 목적지와 일치하는 AllowedIPs가 있는 Peer에게만 Packet을 암호화해 보낸다.

VPN을 만들었다는 사실보다 어떤 주소를 Peer와 연결하지 않았는지가 더 중요했다. 새로운 연결 대상이 필요하면 넓은 CIDR을 미리 등록하지 않고 Peer의 AllowedIPs를 명시적으로 추가하도록 했다.

3. API와 WireGuard Sidecar가 Network Namespace를 공유한다

연산 서버에서는 WireGuard를 별도 Container로 실행했다. API Container는 network_mode: service:wireguard 방식으로 WireGuard Sidecar의 Network Namespace를 공유한다.

flowchart TB
    subgraph HOST[Remote Compute Host]
        subgraph NS[Shared Network Namespace]
            WG[wg0<br/>10.200.0.2]
            SIDECAR[WireGuard Sidecar Process<br/>NET_ADMIN]
            API[API Process<br/>Private Listener]
            SIDECAR -.->|creates and configures| WG
            WG --> API
        end
    end

    PEER[Cloud Peer] -->|Tunnel Traffic| WG

이 구조에서는 API Container에 NET_ADMIN Capability를 줄 필요가 없다. Network Interface 생성과 WireGuard 설정은 Sidecar만 담당하고, API는 같은 Namespace 안에서 평소처럼 Port를 Listen한다.

Compose의 ports를 선언하지 않아 Docker가 API Port를 Host에 Bind하거나 Publish하지 않는다. Tunnel에서 10.200.0.2로 들어온 요청은 같은 Namespace 안의 API Listener에 도달한다.


IV. 간단한 설정 가이드

1. 각 Host에서 Key Pair를 만든다

두 Host에서 각각 별도의 Key Pair를 만든다. 공식 Quick Start와 같이 생성 전에 umask를 제한하면 새 파일이 다른 사용자에게 공개되는 것을 막을 수 있다.

1
2
umask 077
wg genkey | tee private.key | wg pubkey > public.key

public.key만 상대 Peer에 전달한다. private.key는 Repository, Container Image, CI Log와 일반 환경 변수 파일에 넣지 않고 해당 Host의 제한된 Secret 경로에 보관한다.

2. 외부에서 도달 가능한 Peer를 설정한다

아래 주소와 Port는 예시다. Cloud 쪽 Peer는 UDP를 Listen하고, NAT 뒤의 Peer가 사용할 Tunnel IP만 허용한다.

1
2
3
4
5
6
7
8
9
# /etc/wireguard/wg0.conf
[Interface]
Address = 10.200.0.1/24
ListenPort = 51820
PrivateKey = <CLOUD_PRIVATE_KEY>

[Peer]
PublicKey = <REMOTE_PUBLIC_KEY>
AllowedIPs = 10.200.0.2/32

Private Key를 설정 파일에 넣는다면 파일 권한을 반드시 제한한다.

1
2
3
sudo chmod 600 /etc/wireguard/wg0.conf
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

3. NAT 뒤의 Peer를 설정한다

NAT 뒤의 Peer에는 외부 UDP Endpoint와 Keepalive를 추가한다.

1
2
3
4
5
6
7
8
9
[Interface]
Address = 10.200.0.2/24
PrivateKey = <REMOTE_PRIVATE_KEY>

[Peer]
PublicKey = <CLOUD_PUBLIC_KEY>
Endpoint = vpn.example.com:51820
AllowedIPs = 10.200.0.1/32
PersistentKeepalive = 25

이 Peer가 먼저 Handshake를 보내면 반대쪽은 NAT가 변환한 현재 Source Address를 Endpoint로 사용할 수 있다.

4. Container에서는 Key를 File로 주입한다

Sidecar를 사용한다면 Compose 구조는 다음과 같이 단순화할 수 있다. 아래 예시는 전체 실행 설정이 아니라 Network Namespace와 권한 경계를 보여 주는 일부다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
services:
  wireguard:
    build: ./wireguard
    cap_add:
      - NET_ADMIN
    volumes:
      - ${WIREGUARD_PRIVATE_KEY_FILE}:/run/secrets/wg-private.key:ro

  private-api:
    image: example/private-api:latest
    network_mode: "service:wireguard"
    depends_on:
      - wireguard
    # ports는 선언하지 않는다.

Sidecar의 Entry Point에서는 ip link add wg0 type wireguard로 Interface를 만들고, wg set으로 File에 Mount한 Private Key와 Peer 정보를 적용할 수 있다. Host Kernel이 WireGuard를 지원하는지 먼저 확인해야 하며, NET_ADMIN은 Interface를 관리하는 Sidecar에만 부여한다.

5. VPN 위에도 Application 인증을 유지한다

WireGuard Public Key는 Host Peer를 식별한다. 그 Host 안에서 어떤 Process나 사용자가 요청했는지까지 증명하지는 않는다.

따라서 다음 방어를 함께 유지했다.

  • Public Firewall에는 WireGuard UDP만 허용하고, 가능한 경우 Source 범위도 제한한다.
  • AllowedIPs에는 상대 Peer가 담당할 Tunnel Address만 등록한다.
  • Private API는 기존 Token과 권한을 계속 검증한다.
  • Private Key는 Host별로 분리하고 접근 권한과 교체 절차를 관리한다.
  • 환경별 Key와 Peer 설정을 분리하고 필수 설정이 없으면 배포를 중단한다.
  • Provisioning Script와 진단 Log에 Key 또는 전체 WireGuard 설정을 남기지 않는다.

V. 연결 흐름과 검증

1. Handshake 이후 API 요청이 흐른다

NAT 뒤의 Peer가 먼저 Handshake를 만든 뒤에는 Cloud Application이 Tunnel IP로 API를 호출할 수 있다.

sequenceDiagram
    participant App as Cloud Application
    participant Cloud as Cloud WireGuard
    participant Remote as Remote WireGuard
    participant API as Private API

    Note over Cloud,Remote: UDP Packet은 Public Endpoint와 NAT를 통과
    Remote->>Cloud: Handshake Initiation
    Cloud-->>Remote: Handshake Response
    Remote->>Cloud: Persistent Keepalive

    App->>Cloud: 10.200.0.2의 API 요청
    Cloud->>Remote: 암호화된 Tunnel Packet
    Remote->>API: 복호화된 HTTP 요청
    API-->>Remote: HTTP 응답
    Remote-->>Cloud: 암호화된 Tunnel Packet
    Cloud-->>App: HTTP 응답

2. Transport와 Application을 나누어 확인한다

연결 검증은 한 번의 API 성공 여부만 보지 않고 계층별로 나눴다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Host에서 실행하는 Peer의 최근 Handshake와 양방향 전송량
sudo wg show wg0

# Sidecar 안에서 실행하는 Peer의 상태
docker exec <WIREGUARD_SIDECAR> wg show wg0

# Cloud Host의 목적지 경로 확인
ip route get 10.200.0.2

# ICMP를 허용한 경우 Peer 도달성 확인
ping -c 3 10.200.0.2

# Application 인증도 그대로 동작하는지 확인
curl -i http://10.200.0.2:<API_PORT>/protected-resource

Token 없이 보호된 Endpoint를 호출했을 때 401 또는 403이 반환된다면 Tunnel을 지나 API까지 도달했고 Application 인증도 우회되지 않았다는 뜻이다. ICMP를 차단한 환경에서는 ping 실패만으로 Tunnel 실패를 판단하지 않는다.

Public Interface에서는 API Port가 Listen되지 않는지도 별도로 확인한다. WireGuard Handshake 성공과 API Public Port 미노출은 서로 다른 검증 항목이다.

3. 운영 중 마주친 문제

증상확인할 항목
Handshake가 전혀 없음UDP Ingress, Endpoint 주소, 양쪽 Public Key와 Listen Port
송신 Byte만 증가함Return Path, Source NAT와 UDP 전달 경로의 비대칭
Handshake는 있으나 Peer IP에 접근할 수 없음양쪽 AllowedIPs, Route와 Interface Address
Peer IP는 되지만 API가 응답하지 않음Listener Address, Sidecar Namespace와 Application 상태
한동안 유휴 상태 후 접근 불가NAT 쪽 PersistentKeepalive와 UDP Mapping 수명

특히 Public UDP Forwarding을 거치는 환경에서는 요청이 들어온 주소와 응답 Packet의 Source Address가 달라질 수 있다. UDP Endpoint는 열려 있는데 수신 Byte가 계속 0이라면 WireGuard 설정만 반복해서 바꾸기 전에 Return Path와 Source NAT를 확인해야 한다.

또 하나의 주의점은 Container 생명주기다. API Container가 network_mode: service:wireguard로 Sidecar의 Network Namespace를 공유하면 Sidecar 재생성 시 Namespace도 바뀐다. 이 경우 Sidecar만 다시 띄우지 않고 API Container도 함께 재생성해야 한다.


VI. 적용 결과와 한계

1. Public Endpoint를 만들지 않고 Private 연결을 추가했다

최종 구조에서 확인한 결과는 다음과 같다.

항목NAT 뒤 Host의 API를 직접 공개했다면선택한 WireGuard 구조
외부 노출Application API EndpointWireGuard UDP Endpoint만 노출
Application PortHost Port 또는 Proxy 연결 경로 필요Host에 Publish하지 않음
WireGuard Peer 범위해당 없음Peer별 /32 AllowedIPs
NAT 뒤 Peer직접 노출 시 Port Forwarding 등 필요Outbound Handshake로 Endpoint 형성
Application 인증필요그대로 유지

검증 환경에서는 Handshake 이후 양방향 전송량이 증가했고, Tunnel IP를 통한 보호 API 호출도 정상적으로 완료됐다. API를 위한 Public Endpoint는 만들지 않았고, 기존 Host Port Publish도 제거했다.

다만 도입 전후를 같은 조건에서 반복 측정한 Network Benchmark는 아니었다. 이번 적용의 결과는 성능 향상이 아니라 Public API Endpoint 미생성, Host Port Publish 제거와 Peer Address 범위 제한으로 보는 것이 정확하다.

2. WireGuard가 해결하지 않는 것도 있다

WireGuard는 Private Network 경로를 만들지만 다음 문제까지 자동으로 해결하지는 않는다.

  • 사용자의 신원과 Application 권한
  • Peer Private Key의 배포, 회전과 폐기
  • 다수 Peer의 중앙 관리와 설정 동기화
  • Application 수준의 Rate Limit과 Audit Log
  • Tunnel과 Sidecar의 Monitoring 및 Alert
  • UDP가 제한된 Network에서의 대체 경로

Peer가 소수이고 연결 대상이 명확할 때는 설정이 단순하다. 반대로 사용자 단위 접근 제어, 많은 지점과 자동화된 Device 관리가 필요하다면 Managed VPN이나 WireGuard 기반 관리 계층을 함께 검토해야 한다.


VII. 정리

이번 구성에서 WireGuard를 선택한 이유는 VPN 자체가 목적이어서가 아니었다. Cloud Application과 NAT 뒤 연산 서버 사이에 API Port를 공개하지 않는 가장 작은 Network 경로가 필요했기 때문이다.

핵심은 다음 네 가지였다.

  1. NAT 뒤의 Peer가 Handshake를 시작하고 필요할 때 PersistentKeepalive로 Mapping을 유지한다.
  2. AllowedIPs를 /32로 제한해 상대의 Tunnel IP 하나만 Peer와 연결한다.
  3. API Container가 WireGuard Sidecar의 Network Namespace를 공유하고 Host Port는 Publish하지 않는다.
  4. WireGuard 위에서도 Application 인증과 권한 검사를 그대로 유지한다.

설정 파일 자체는 짧았지만 실제 운영에서는 Return Path, NAT와 Container 생명주기를 함께 이해해야 했다. WireGuard의 Peer·Route 경계와 Container Network Namespace의 실행 경계를 함께 설계해야 원하는 만큼만 연결할 수 있었다.


VIII. 참고

  1. WireGuard 공식 사이트
  2. WireGuard Quick Start
  3. WireGuard Protocol & Cryptography
  4. wg(8) Manual
  5. wg-quick(8) Manual
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.