charmarr-lib-vpn

VPN gateway charm library for Kubernetes.

Features

• VPN gateway Juju relation interface
• StatefulSet patching utilities for pod-gateway integration
• NetworkPolicy kill switch implementation
• Reusable beyond Charmarr ecosystem

Installation

pip install charmarr-lib-vpn

Usage

Interfaces

from charmarr_lib.vpn.interfaces import (
    VPNGatewayProvider,
    VPNGatewayRequirer,
    VPNGatewayProviderData,
    VPNGatewayRequirerData,
    VPNGatewayChangedEvent,
)

Gateway Patching (VPN gateway side - gluetun)

from charmarr_lib.vpn import (
    reconcile_gateway,
    build_gateway_patch,
    is_gateway_patched,
)
from charmarr_lib.krm import K8sResourceManager

manager = K8sResourceManager()
provider_data = VPNGatewayProviderData(
    vxlan_id=42,
    vxlan_ip_network="172.16.0.0/24",
    cluster_cidrs="10.1.0.0/16,10.152.183.0/24",
)

# Idempotent reconciliation
result = reconcile_gateway(
    manager=manager,
    statefulset_name="gluetun",
    namespace="vpn-gateway",
    data=provider_data,
    pod_cidr="10.1.0.0/16",
)

Client Patching (Download client side - qBittorrent)

from charmarr_lib.vpn import (
    reconcile_gateway_client,
    build_gateway_client_patch,
    build_gateway_client_configmap_data,
    is_gateway_client_patched,
)

# Create client-side VPN routing
result = reconcile_gateway_client(
    manager=manager,
    statefulset_name="qbittorrent",
    namespace="download-clients",
    data=requirer_data,
    configmap_name="qbittorrent-vpn-config",
)

Kill Switch (NetworkPolicy)

from charmarr_lib.vpn import (
    KillSwitchConfig,
    reconcile_kill_switch,
)

# Create NetworkPolicy that blocks non-VPN egress
config = KillSwitchConfig(
    app_name="qbittorrent",
    namespace="download-clients",
    cluster_cidrs=["10.1.0.0/16", "10.152.183.0/24"],
    dns_namespace="kube-system",
)
reconcile_kill_switch(manager, "qbittorrent", "download-clients", config)

# Remove kill switch on relation-broken
reconcile_kill_switch(manager, "qbittorrent", "download-clients", None)

Constants

from charmarr_lib.vpn import (
    POD_GATEWAY_IMAGE,
    DEFAULT_VXLAN_ID,
    DEFAULT_VXLAN_IP_NETWORK,
    GATEWAY_INIT_CONTAINER_NAME,
    GATEWAY_SIDECAR_CONTAINER_NAME,
    CLIENT_INIT_CONTAINER_NAME,
    CLIENT_SIDECAR_CONTAINER_NAME,
)