mm404/nordvpn-sidecar repository overview

⁠NordVPN Sidecar Container

A lightweight sidecar VPN solution for Kubernetes pods that redirects all pod traffic through NordVPN with optional split tunneling support.

Source: https://github.com/mm503/nordvpn-sidecar/⁠

⁠Availability

• Image name: mm404/nordvpn-sidecar⁠
• Tags:
  • latest
  • <version> (eg. 4.2.3)

⁠Features

• Full Traffic Redirection: Routes all pod traffic through NordVPN
• Split Tunneling: Configurable subnet exclusions (Kubernetes, LAN, etc.)
• Minimal Footprint: Ubuntu LTS base with only NordVPN packages
• Auto-Reconnection: Configurable retry logic for connection stability
• Kill Switch: Prevents traffic leaks when VPN disconnects

⁠Container Details

• Base Image: Ubuntu 26.04 LTS
• Architecture Support: Multi-arch (linux/amd64, linux/arm64)
• Components: Ubuntu + NordVPN packages only
• Customization: Single entrypoint.sh script
• Image Tags: Correspond to NordVPN client versions
• Automated Updates: Renovate bot automatically updates NordVPN versions

⁠Configuration

⁠Required Environment Variables

- name: TOKEN
  valueFrom:
    secretKeyRef:
      name: nordvpn-credentials
      key: token

⁠Optional Environment Variables

⁠Implementation

⁠1. Create NordVPN Credentials Secret

apiVersion: v1
kind: Secret
metadata:
  name: nordvpn-credentials
type: Opaque
data:
  token: <base64-encoded-nordvpn-token>

⁠2. Add Sidecar to Pod Specification

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  initContainers:
  - name: nordvpn-sidecar
    image: mm404/nordvpn-sidecar:latest
    restartPolicy: Always
    env:
    - name: TOKEN
      valueFrom:
        secretKeyRef:
          name: nordvpn-credentials
          key: token
    - name: ALLOW_SUBNETS   # Kubernetes networking, LAN
      value: "10.42.0.0/16,10.43.0.0/16,192.168.1.0/24"
    - name: NORDVPN_COUNTRY
      value: United_States  # Run "nordvpn countries" to see all options
    - name: NORDVPN_CITY    # Run "nordvpn cities United_States" to see city options for US
      value: Miami
    - name: MAX_RECONNECT_ATTEMPTS
      value: "10"
    - name: RECONNECT_INTERVAL
      value: "60"
    securityContext:
      capabilities:
        add:
        - NET_ADMIN         # Required for VPN to work
  containers:
  - name: main-container
    image: your-app:latest

⁠Split Tunneling Configuration

⁠Common Subnet Exclusions

• Kubernetes Pod Network: 10.42.0.0/16 (k3s default)
• Kubernetes Service Network: 10.43.0.0/16 (k3s default)
• Local LAN: 192.168.x.0/24 (adjust to your network)
• Docker Networks: 172.17.0.0/16 (if applicable)

⁠Example ALLOW_SUBNETS Values

# Minimal (Kubernetes only)
ALLOW_SUBNETS: "10.42.0.0/16,10.43.0.0/16"

# With LAN access
ALLOW_SUBNETS: "10.42.0.0/16,10.43.0.0/16,192.168.1.0/24"

⁠Security Considerations

• Required Capability: NET_ADMIN for network manipulation
• Secret Management: Store NordVPN token in Kubernetes secrets
• Network Policies: Consider additional pod network restrictions
• Resource Limits: Set appropriate CPU/memory limits for the sidecar

⁠Troubleshooting

⁠Connection Issues

• Verify NordVPN token validity
• Check country/city name formatting
• Review pod logs for connection errors

⁠Split Tunneling Problems

• Validate subnet CIDR notation
• Ensure subnets don't conflict with VPN routing
• Test connectivity to excluded subnets

⁠Performance Impact

• Monitor sidecar resource usage
• Adjust reconnection parameters for stability
• Consider regional server selection for latency

⁠Versioning

This project uses the NordVPN client version as its release version. Image tags correspond to NordVPN client versions (following semver⁠).

⁠Image Tags

• latest: Most recent stable release
• {version}: NordVPN client version (e.g., 4.2.2)

⁠Release Process

Docker images are built and published automatically via GitHub Actions:

On Push to Main:

1. NORDVPN_VERSION in Dockerfile is detected from the build
2. Multi-arch Docker images are built for linux/amd64 and linux/arm64
3. Images are pushed to Docker Hub with two tags:
   • mm404/nordvpn-sidecar:latest
   • mm404/nordvpn-sidecar:{version}

On Push to Non-Main Branches:

• Multi-arch images are built and pushed to Docker Hub with tag dev-{version}-{branch}-{sha}

The version is automatically extracted from the NORDVPN_VERSION argument in the Dockerfile and embedded in the image via the GIT_REVISION build argument.