charmarr-lib-vpn 0.2.2__py3-none-any.whl

charmarr_lib/vpn/__init__.py

@@ -0,0 +1,50 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""VPN gateway charm library for Kubernetes."""
+
+from charmarr_lib.vpn._k8s import (
+    KillSwitchConfig,
+    build_gateway_client_configmap_data,
+    build_gateway_client_patch,
+    build_gateway_patch,
+    is_gateway_client_patched,
+    is_gateway_patched,
+    reconcile_gateway,
+    reconcile_gateway_client,
+    reconcile_kill_switch,
+)
+from charmarr_lib.vpn.constants import (
+    CLIENT_INIT_CONTAINER_NAME,
+    CLIENT_SIDECAR_CONTAINER_NAME,
+    DEFAULT_VPN_BLOCK_OTHER_TRAFFIC,
+    DEFAULT_VPN_INTERFACE,
+    DEFAULT_VXLAN_GATEWAY_FIRST_DYNAMIC_IP,
+    DEFAULT_VXLAN_ID,
+    DEFAULT_VXLAN_IP_NETWORK,
+    GATEWAY_INIT_CONTAINER_NAME,
+    GATEWAY_SIDECAR_CONTAINER_NAME,
+    POD_GATEWAY_IMAGE,
+)
+
+__all__ = [
+    "CLIENT_INIT_CONTAINER_NAME",
+    "CLIENT_SIDECAR_CONTAINER_NAME",
+    "DEFAULT_VPN_BLOCK_OTHER_TRAFFIC",
+    "DEFAULT_VPN_INTERFACE",
+    "DEFAULT_VXLAN_GATEWAY_FIRST_DYNAMIC_IP",
+    "DEFAULT_VXLAN_ID",
+    "DEFAULT_VXLAN_IP_NETWORK",
+    "GATEWAY_INIT_CONTAINER_NAME",
+    "GATEWAY_SIDECAR_CONTAINER_NAME",
+    "POD_GATEWAY_IMAGE",
+    "KillSwitchConfig",
+    "build_gateway_client_configmap_data",
+    "build_gateway_client_patch",
+    "build_gateway_patch",
+    "is_gateway_client_patched",
+    "is_gateway_patched",
+    "reconcile_gateway",
+    "reconcile_gateway_client",
+    "reconcile_kill_switch",
+]

charmarr_lib/vpn/_k8s/__init__.py

@@ -0,0 +1,53 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""StatefulSet patching and NetworkPolicy for pod-gateway VPN routing.
+
+This module provides functions to patch Kubernetes StatefulSets with
+pod-gateway containers for VXLAN overlay VPN routing, plus NetworkPolicy
+kill switch for traffic protection.
+
+Gateway-side patching (for gluetun-k8s):
+- gateway-init: Creates VXLAN tunnel, sets up iptables forwarding
+- gateway-sidecar: Runs DHCP and DNS server for client pods
+
+Gateway client patching (for qbittorrent-k8s, sabnzbd-k8s):
+- vpn-route-init: Creates VXLAN interface, gets IP via DHCP
+- vpn-route-sidecar: Monitors gateway connectivity
+
+Kill switch (for qbittorrent-k8s, sabnzbd-k8s):
+- NetworkPolicy that blocks egress except cluster CIDRs + DNS
+- Prevents traffic leaks if VXLAN routing fails
+
+See ADRs:
+- lib/adr-002-charmarr-vpn.md
+- networking/adr-004-vpn-kill-switch.md
+"""
+
+from charmarr_lib.vpn._k8s._gateway import (
+    build_gateway_patch,
+    is_gateway_patched,
+    reconcile_gateway,
+)
+from charmarr_lib.vpn._k8s._gateway_client import (
+    build_gateway_client_configmap_data,
+    build_gateway_client_patch,
+    is_gateway_client_patched,
+    reconcile_gateway_client,
+)
+from charmarr_lib.vpn._k8s._kill_switch import (
+    KillSwitchConfig,
+    reconcile_kill_switch,
+)
+
+__all__ = [
+    "KillSwitchConfig",
+    "build_gateway_client_configmap_data",
+    "build_gateway_client_patch",
+    "build_gateway_patch",
+    "is_gateway_client_patched",
+    "is_gateway_patched",
+    "reconcile_gateway",
+    "reconcile_gateway_client",
+    "reconcile_kill_switch",
+]

charmarr_lib/vpn/_k8s/_gateway.py

@@ -0,0 +1,189 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Gateway-side StatefulSet patching for pod-gateway.
+
+Adds init container and sidecar to the VPN gateway (gluetun-k8s) StatefulSet
+to handle VXLAN tunnel creation and DHCP/DNS services for client pods.
+
+Based on validated configuration from vxlan-validation-plan.md.
+"""
+
+from typing import Any
+
+from lightkube.models.apps_v1 import StatefulSet
+from lightkube.models.core_v1 import (
+    Capabilities,
+    Container,
+    ContainerPort,
+    EnvVar,
+    SecurityContext,
+)
+
+from charmarr_lib.krm import K8sResourceManager, ReconcileResult
+from charmarr_lib.vpn.constants import (
+    DEFAULT_VXLAN_GATEWAY_FIRST_DYNAMIC_IP,
+    GATEWAY_INIT_CONTAINER_NAME,
+    GATEWAY_SIDECAR_CONTAINER_NAME,
+    POD_GATEWAY_IMAGE,
+)
+from charmarr_lib.vpn.interfaces import VPNGatewayProviderData
+
+
+def _build_gateway_env_vars(data: VPNGatewayProviderData, pod_cidr: str) -> list[EnvVar]:
+    """Build environment variables for gateway containers.
+
+    Args:
+        data: VPN gateway provider data from relation.
+        pod_cidr: Pod network CIDR for iptables rule (e.g., "10.1.0.0/16").
+    """
+    return [
+        EnvVar(name="VXLAN_ID", value=str(data.vxlan_id)),
+        EnvVar(name="VXLAN_IP_NETWORK", value=data.vxlan_ip_network),
+        EnvVar(
+            name="VXLAN_GATEWAY_FIRST_DYNAMIC_IP",
+            value=str(DEFAULT_VXLAN_GATEWAY_FIRST_DYNAMIC_IP),
+        ),
+        EnvVar(name="VPN_INTERFACE", value="tun0"),
+        EnvVar(name="VPN_BLOCK_OTHER_TRAFFIC", value="true"),
+        EnvVar(name="NOT_ROUTED_TO_GATEWAY_CIDRS", value=data.cluster_cidrs),
+        EnvVar(name="POD_CIDR", value=pod_cidr),
+    ]
+
+
+def _build_gateway_init_container(data: VPNGatewayProviderData, pod_cidr: str) -> Container:
+    """Build gateway-init container spec.
+
+    The init container:
+    - Creates VXLAN tunnel interface
+    - Sets up iptables forwarding rules
+    - Adds iptables rule to accept VXLAN packets from pod CIDR (critical fix)
+    - Requires privileged mode for sysctl ip_forward
+    """
+    return Container(
+        name=GATEWAY_INIT_CONTAINER_NAME,
+        image=POD_GATEWAY_IMAGE,
+        command=["/bin/sh", "-c"],
+        args=[f"/bin/gateway_init.sh && iptables -I INPUT -i eth0 -s {pod_cidr} -j ACCEPT"],
+        securityContext=SecurityContext(privileged=True),
+        env=_build_gateway_env_vars(data, pod_cidr),
+    )
+
+
+def _build_gateway_sidecar_container(data: VPNGatewayProviderData, pod_cidr: str) -> Container:
+    """Build gateway-sidecar container spec.
+
+    The sidecar container:
+    - Runs DHCP server for client IP allocation
+    - Runs DNS server for client pods
+    - Requires NET_ADMIN capability (not full privileged)
+    """
+    return Container(
+        name=GATEWAY_SIDECAR_CONTAINER_NAME,
+        image=POD_GATEWAY_IMAGE,
+        command=["/bin/gateway_sidecar.sh"],
+        securityContext=SecurityContext(capabilities=Capabilities(add=["NET_ADMIN"])),
+        env=_build_gateway_env_vars(data, pod_cidr),
+        ports=[
+            ContainerPort(name="dhcp", containerPort=67, protocol="UDP"),
+            ContainerPort(name="dns", containerPort=53, protocol="UDP"),
+        ],
+    )
+
+
+def build_gateway_patch(data: VPNGatewayProviderData, pod_cidr: str) -> dict[str, Any]:
+    """Build strategic merge patch for gateway StatefulSet.
+
+    Adds pod-gateway init container and sidecar to the VPN gateway StatefulSet.
+
+    Args:
+        data: VPN gateway provider data containing VXLAN config.
+        pod_cidr: Pod network CIDR for iptables rule (e.g., "10.1.0.0/16").
+                  This is extracted from cluster_cidrs (first CIDR is typically pods).
+
+    Returns:
+        Strategic merge patch dict for StatefulSet.
+
+    Example:
+        patch = build_gateway_patch(provider_data, "10.1.0.0/16")
+        manager.patch(StatefulSet, "gluetun", patch, "vpn-gateway")
+    """
+    init_container = _build_gateway_init_container(data, pod_cidr)
+    sidecar = _build_gateway_sidecar_container(data, pod_cidr)
+
+    return {
+        "spec": {
+            "template": {
+                "spec": {
+                    "initContainers": [init_container.to_dict()],
+                    "containers": [sidecar.to_dict()],
+                }
+            }
+        }
+    }
+
+
+def is_gateway_patched(sts: StatefulSet) -> bool:
+    """Check if gateway StatefulSet already has pod-gateway containers.
+
+    Args:
+        sts: The StatefulSet to check.
+
+    Returns:
+        True if both gateway-init and gateway-sidecar are present.
+    """
+    if sts.spec is None or sts.spec.template.spec is None:
+        return False
+
+    spec = sts.spec.template.spec
+
+    has_init = False
+    if spec.initContainers:
+        has_init = any(c.name == GATEWAY_INIT_CONTAINER_NAME for c in spec.initContainers)
+
+    has_sidecar = False
+    if spec.containers:
+        has_sidecar = any(c.name == GATEWAY_SIDECAR_CONTAINER_NAME for c in spec.containers)
+
+    return has_init and has_sidecar
+
+
+def reconcile_gateway(
+    manager: K8sResourceManager,
+    statefulset_name: str,
+    namespace: str,
+    data: VPNGatewayProviderData,
+    pod_cidr: str,
+) -> ReconcileResult:
+    """Reconcile pod-gateway containers on a VPN gateway StatefulSet.
+
+    This function ensures the VPN gateway StatefulSet has the required
+    pod-gateway containers for VXLAN tunnel and DHCP/DNS services.
+
+    Idempotent - if containers are already present, no changes are made.
+
+    Args:
+        manager: K8sResourceManager instance.
+        statefulset_name: Name of the StatefulSet (usually self.app.name).
+        namespace: Kubernetes namespace (usually self.model.name).
+        data: VPN gateway provider data containing VXLAN config.
+        pod_cidr: Pod network CIDR for iptables rule (e.g., "10.1.0.0/16").
+
+    Returns:
+        ReconcileResult indicating if changes were made.
+
+    Raises:
+        ApiError: If the StatefulSet doesn't exist or patch fails.
+    """
+    sts = manager.get(StatefulSet, statefulset_name, namespace)
+
+    if is_gateway_patched(sts):
+        return ReconcileResult(changed=False, message="Gateway containers already present")
+
+    patch = build_gateway_patch(data, pod_cidr)
+    manager.patch(StatefulSet, statefulset_name, patch, namespace)
+
+    return ReconcileResult(
+        changed=True,
+        message=f"Added pod-gateway containers to {statefulset_name}",
+    )

charmarr_lib/vpn/_k8s/_gateway_client.py

@@ -0,0 +1,175 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Gateway client StatefulSet patching for pod-gateway.
+
+Adds init container and sidecar to download client StatefulSets (qbittorrent-k8s,
+sabnzbd-k8s) to route traffic through the VPN gateway via VXLAN overlay.
+
+These are the "client" containers that connect TO the gateway - not to be confused
+with API clients or download clients.
+
+Based on validated configuration from vxlan-validation-plan.md.
+
+Note: Client containers use a ConfigMap for settings (K8S_DNS_IPS,
+NOT_ROUTED_TO_GATEWAY_CIDRS) with SPACE-separated CIDRs, unlike gateway
+which uses COMMA-separated. This is a pod-gateway quirk.
+"""
+
+from typing import Any
+
+from lightkube.models.apps_v1 import StatefulSet
+from lightkube.models.core_v1 import (
+    Capabilities,
+    ConfigMapVolumeSource,
+    Container,
+    EnvVar,
+    SecurityContext,
+    Volume,
+    VolumeMount,
+)
+
+from charmarr_lib.krm import K8sResourceManager, ReconcileResult
+from charmarr_lib.vpn.constants import (
+    CLIENT_INIT_CONTAINER_NAME,
+    CLIENT_SIDECAR_CONTAINER_NAME,
+    POD_GATEWAY_IMAGE,
+)
+from charmarr_lib.vpn.interfaces import VPNGatewayProviderData
+
+_CONFIG_VOLUME_NAME = "pod-gateway-config"
+_CONFIG_MOUNT_PATH = "/config"
+
+
+def _build_gateway_client_init_container(gateway_dns_name: str) -> Container:
+    """Build vpn-route-init container spec."""
+    return Container(
+        name=CLIENT_INIT_CONTAINER_NAME,
+        image=POD_GATEWAY_IMAGE,
+        command=["/bin/client_init.sh"],
+        securityContext=SecurityContext(capabilities=Capabilities(add=["NET_ADMIN"])),
+        env=[EnvVar(name="gateway", value=gateway_dns_name)],
+        volumeMounts=[VolumeMount(name=_CONFIG_VOLUME_NAME, mountPath=_CONFIG_MOUNT_PATH)],
+    )
+
+
+def _build_gateway_client_sidecar_container(gateway_dns_name: str) -> Container:
+    """Build vpn-route-sidecar container spec."""
+    return Container(
+        name=CLIENT_SIDECAR_CONTAINER_NAME,
+        image=POD_GATEWAY_IMAGE,
+        command=["/bin/client_sidecar.sh"],
+        securityContext=SecurityContext(capabilities=Capabilities(add=["NET_ADMIN"])),
+        env=[EnvVar(name="gateway", value=gateway_dns_name)],
+        volumeMounts=[VolumeMount(name=_CONFIG_VOLUME_NAME, mountPath=_CONFIG_MOUNT_PATH)],
+    )
+
+
+def _build_config_volume(configmap_name: str) -> Volume:
+    """Build ConfigMap volume for gateway client settings."""
+    return Volume(
+        name=_CONFIG_VOLUME_NAME,
+        configMap=ConfigMapVolumeSource(name=configmap_name),
+    )
+
+
+def build_gateway_client_configmap_data(
+    dns_server_ip: str,
+    cluster_cidrs: str,
+) -> dict[str, str]:
+    """Build ConfigMap data for gateway client pod-gateway settings.
+
+    Args:
+        dns_server_ip: Kubernetes DNS server IP (e.g., "10.152.183.10").
+        cluster_cidrs: Space-separated cluster CIDRs for bypass.
+                       Note: Must be SPACE-separated for client, not comma!
+
+    Returns:
+        Dict with settings.sh content for ConfigMap data field.
+    """
+    settings = f'K8S_DNS_IPS="{dns_server_ip}"\nNOT_ROUTED_TO_GATEWAY_CIDRS="{cluster_cidrs}"'
+    return {"settings.sh": settings}
+
+
+def build_gateway_client_patch(
+    data: VPNGatewayProviderData,
+    configmap_name: str,
+) -> dict[str, Any]:
+    """Build strategic merge patch for gateway client StatefulSet."""
+    init_container = _build_gateway_client_init_container(data.gateway_dns_name)
+    sidecar = _build_gateway_client_sidecar_container(data.gateway_dns_name)
+    config_volume = _build_config_volume(configmap_name)
+
+    return {
+        "spec": {
+            "template": {
+                "spec": {
+                    "initContainers": [init_container.to_dict()],
+                    "containers": [sidecar.to_dict()],
+                    "volumes": [config_volume.to_dict()],
+                }
+            }
+        }
+    }
+
+
+def is_gateway_client_patched(sts: StatefulSet) -> bool:
+    """Check if StatefulSet already has pod-gateway client containers."""
+    if sts.spec is None or sts.spec.template.spec is None:
+        return False
+
+    spec = sts.spec.template.spec
+
+    has_init = False
+    if spec.initContainers:
+        has_init = any(c.name == CLIENT_INIT_CONTAINER_NAME for c in spec.initContainers)
+
+    has_sidecar = False
+    if spec.containers:
+        has_sidecar = any(c.name == CLIENT_SIDECAR_CONTAINER_NAME for c in spec.containers)
+
+    return has_init and has_sidecar
+
+
+def reconcile_gateway_client(
+    manager: K8sResourceManager,
+    statefulset_name: str,
+    namespace: str,
+    data: VPNGatewayProviderData,
+    configmap_name: str,
+) -> ReconcileResult:
+    """Reconcile pod-gateway client containers on a StatefulSet.
+
+    This function ensures the download client StatefulSet has the required
+    pod-gateway containers to route traffic through the VPN gateway.
+
+    Idempotent - if containers are already present, no changes are made.
+
+    Note: The charm must create a ConfigMap with settings BEFORE calling this.
+    Use build_gateway_client_configmap_data() to generate ConfigMap content.
+
+    Args:
+        manager: K8sResourceManager instance.
+        statefulset_name: Name of the StatefulSet (usually self.app.name).
+        namespace: Kubernetes namespace (usually self.model.name).
+        data: VPN gateway provider data from relation.
+        configmap_name: Name of the ConfigMap containing pod-gateway settings.
+
+    Returns:
+        ReconcileResult indicating if changes were made.
+
+    Raises:
+        ApiError: If the StatefulSet doesn't exist or patch fails.
+    """
+    sts = manager.get(StatefulSet, statefulset_name, namespace)
+
+    if is_gateway_client_patched(sts):
+        return ReconcileResult(changed=False, message="Gateway client containers already present")
+
+    patch = build_gateway_client_patch(data, configmap_name)
+    manager.patch(StatefulSet, statefulset_name, patch, namespace)
+
+    return ReconcileResult(
+        changed=True,
+        message=f"Added pod-gateway client containers to {statefulset_name}",
+    )

charmarr_lib/vpn/_k8s/_kill_switch.py

@@ -0,0 +1,212 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""NetworkPolicy kill switch for VPN gateway clients.
+
+Creates a NetworkPolicy that blocks all egress traffic EXCEPT:
+- Traffic to cluster pod CIDR (VXLAN-encapsulated traffic)
+- Traffic to cluster service CIDR (K8s services)
+- DNS traffic to kube-system (CoreDNS)
+
+This is Layer 1 of the two-layer VPN kill switch. If VXLAN routing fails
+(init container error, interface down, routes deleted), traffic cannot escape
+to the internet because the destination IP isn't in the allowed cluster CIDRs.
+
+Why VXLAN traffic passes through:
+- VXLAN encapsulates external traffic with outer destination = gateway pod IP
+- Gateway pod IP is in the cluster pod CIDR
+- NetworkPolicy evaluates outer packet headers, sees cluster CIDR → ALLOWED
+
+See ADR: networking/adr-004-vpn-kill-switch.md
+Validated: vxlan-validation-plan.md (2025-12-11)
+"""
+
+from lightkube.models.meta_v1 import LabelSelector, ObjectMeta
+from lightkube.models.networking_v1 import (
+    IPBlock,
+    NetworkPolicy,
+    NetworkPolicyEgressRule,
+    NetworkPolicyPeer,
+    NetworkPolicyPort,
+    NetworkPolicySpec,
+)
+from lightkube.resources.networking_v1 import NetworkPolicy as NetworkPolicyResource
+from pydantic import BaseModel, Field
+
+from charmarr_lib.krm import K8sResourceManager, ReconcileResult
+
+
+class KillSwitchConfig(BaseModel):
+    """Configuration for VPN kill switch NetworkPolicy.
+
+    Example:
+        config = KillSwitchConfig(
+            app_name="qbittorrent",
+            namespace="downloads",
+            cluster_cidrs=["10.42.0.0/16", "10.96.0.0/12"],
+        )
+    """
+
+    app_name: str = Field(
+        description="Application name for pod selector (app.kubernetes.io/name label)",
+    )
+    namespace: str = Field(
+        description="Kubernetes namespace for the NetworkPolicy",
+    )
+    cluster_cidrs: list[str] = Field(
+        description="List of cluster CIDRs to allow (pod CIDR, service CIDR)",
+    )
+    dns_namespace: str = Field(
+        default="kube-system",
+        description="Namespace containing DNS service (usually kube-system)",
+    )
+
+
+def _policy_name(app_name: str) -> str:
+    """Generate NetworkPolicy name for an application."""
+    return f"{app_name}-vpn-killswitch"
+
+
+def _build_kill_switch_policy(config: KillSwitchConfig) -> NetworkPolicy:
+    """Build a NetworkPolicy for VPN kill switch.
+
+    Creates an egress-only NetworkPolicy that allows:
+    - Traffic to cluster CIDRs (pod/service networks) - each CIDR as separate rule
+    - DNS traffic to kube-system namespace (UDP and TCP port 53)
+
+    Args:
+        config: Kill switch configuration.
+
+    Returns:
+        NetworkPolicy lightkube model ready for apply.
+
+    Example NetworkPolicy produced:
+        apiVersion: networking.k8s.io/v1
+        kind: NetworkPolicy
+        metadata:
+          name: qbittorrent-vpn-killswitch
+          namespace: downloads
+        spec:
+          podSelector:
+            matchLabels:
+              app.kubernetes.io/name: qbittorrent
+          policyTypes:
+            - Egress
+          egress:
+            - to:
+                - ipBlock:
+                    cidr: 10.42.0.0/16
+            - to:
+                - ipBlock:
+                    cidr: 10.96.0.0/12
+            - to:
+                - namespaceSelector:
+                    matchLabels:
+                      kubernetes.io/metadata.name: kube-system
+              ports:
+                - protocol: UDP
+                  port: 53
+                - protocol: TCP
+                  port: 53
+    """
+    egress_rules: list[NetworkPolicyEgressRule] = []
+
+    for cidr in config.cluster_cidrs:
+        egress_rules.append(
+            NetworkPolicyEgressRule(
+                to=[NetworkPolicyPeer(ipBlock=IPBlock(cidr=cidr))],
+            )
+        )
+
+    egress_rules.append(
+        NetworkPolicyEgressRule(
+            to=[
+                NetworkPolicyPeer(
+                    namespaceSelector=LabelSelector(
+                        matchLabels={"kubernetes.io/metadata.name": config.dns_namespace}
+                    )
+                )
+            ],
+            ports=[
+                NetworkPolicyPort(protocol="UDP", port=53),
+                NetworkPolicyPort(protocol="TCP", port=53),
+            ],
+        )
+    )
+
+    return NetworkPolicy(
+        metadata=ObjectMeta(
+            name=_policy_name(config.app_name),
+            namespace=config.namespace,
+        ),
+        spec=NetworkPolicySpec(
+            podSelector=LabelSelector(matchLabels={"app.kubernetes.io/name": config.app_name}),
+            policyTypes=["Egress"],
+            egress=egress_rules,
+        ),
+    )
+
+
+def reconcile_kill_switch(
+    manager: K8sResourceManager,
+    app_name: str,
+    namespace: str,
+    config: KillSwitchConfig | None = None,
+) -> ReconcileResult:
+    """Reconcile VPN kill switch NetworkPolicy.
+
+    When config is provided, creates or updates the NetworkPolicy.
+    When config is None, deletes the NetworkPolicy if it exists.
+
+    Uses server-side apply for clean ownership and idempotent updates.
+
+    Args:
+        manager: K8sResourceManager instance.
+        app_name: Application name (used to derive policy name).
+        namespace: Kubernetes namespace.
+        config: Kill switch configuration, or None to remove the policy.
+
+    Returns:
+        ReconcileResult indicating if changes were made.
+
+    Raises:
+        ApiError: If NetworkPolicy creation/update/deletion fails.
+
+    Example - create/update:
+        config = KillSwitchConfig(
+            app_name="qbittorrent",
+            namespace="downloads",
+            cluster_cidrs=["10.42.0.0/16", "10.96.0.0/12"],
+        )
+        result = reconcile_kill_switch(manager, "qbittorrent", "downloads", config)
+
+    Example - remove (when VPN relation is broken):
+        result = reconcile_kill_switch(manager, "qbittorrent", "downloads", config=None)
+    """
+    policy_name = _policy_name(app_name)
+
+    if config is None:
+        if not manager.exists(NetworkPolicyResource, policy_name, namespace):
+            return ReconcileResult(
+                changed=False,
+                message=f"Kill switch NetworkPolicy {policy_name} not present",
+            )
+        manager.delete(NetworkPolicyResource, policy_name, namespace)
+        return ReconcileResult(
+            changed=True,
+            message=f"Deleted kill switch NetworkPolicy {policy_name}",
+        )
+
+    policy = _build_kill_switch_policy(config)
+    existed = manager.exists(NetworkPolicyResource, policy_name, namespace)
+    manager.apply(policy)
+
+    if existed:
+        return ReconcileResult(
+            changed=True,
+            message=f"Updated kill switch NetworkPolicy {policy_name}",
+        )
+    return ReconcileResult(
+        changed=True,
+        message=f"Created kill switch NetworkPolicy {policy_name}",
+    )

charmarr_lib/vpn/_version.py

@@ -0,0 +1,3 @@
+"""Version for charmarr-vpn package."""
+
+__version__ = "0.2.2"  # x-release-please-version

charmarr_lib/vpn/constants.py

@@ -0,0 +1,22 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Pod-gateway constants and defaults."""
+
+# Pod-gateway container image
+POD_GATEWAY_IMAGE = "ghcr.io/angelnu/pod-gateway:v1.13.0"
+
+# VXLAN defaults
+DEFAULT_VXLAN_ID = 42
+DEFAULT_VXLAN_IP_NETWORK = "172.16.0"
+DEFAULT_VXLAN_GATEWAY_FIRST_DYNAMIC_IP = 20
+
+# Gateway environment variable defaults
+DEFAULT_VPN_INTERFACE = "tun0"
+DEFAULT_VPN_BLOCK_OTHER_TRAFFIC = True
+
+# Container names for StatefulSet patching
+GATEWAY_INIT_CONTAINER_NAME = "gateway-init"
+GATEWAY_SIDECAR_CONTAINER_NAME = "gateway-sidecar"
+CLIENT_INIT_CONTAINER_NAME = "vpn-route-init"
+CLIENT_SIDECAR_CONTAINER_NAME = "vpn-route-sidecar"

charmarr_lib/vpn/interfaces/__init__.py

@@ -0,0 +1,20 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Juju relation interface implementations for VPN gateway."""
+
+from charmarr_lib.vpn.interfaces._vpn_gateway import (
+    VPNGatewayChangedEvent,
+    VPNGatewayProvider,
+    VPNGatewayProviderData,
+    VPNGatewayRequirer,
+    VPNGatewayRequirerData,
+)
+
+__all__ = [
+    "VPNGatewayChangedEvent",
+    "VPNGatewayProvider",
+    "VPNGatewayProviderData",
+    "VPNGatewayRequirer",
+    "VPNGatewayRequirerData",
+]

charmarr_lib/vpn/interfaces/_vpn_gateway.py

@@ -0,0 +1,148 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""VPN gateway interface for VXLAN overlay routing through a VPN gateway."""
+
+from typing import Any
+
+from ops import EventBase, EventSource, Object, ObjectEvents
+from pydantic import BaseModel, Field, ValidationError
+
+from charmarr_lib.vpn.constants import DEFAULT_VXLAN_ID, DEFAULT_VXLAN_IP_NETWORK
+
+
+class VPNGatewayProviderData(BaseModel):
+    """Data published by VPN gateway provider."""
+
+    routing_method: str = Field(
+        default="pod-gateway",
+        description="Routing method: 'pod-gateway' (VXLAN overlay)",
+    )
+    gateway_dns_name: str = Field(
+        description="Service FQDN for client DNS resolution",
+    )
+    vxlan_id: int = Field(
+        default=DEFAULT_VXLAN_ID,
+        ge=1,
+        le=16777215,
+        description="VXLAN tunnel ID (1-16777215)",
+    )
+    vxlan_ip_network: str = Field(
+        default=DEFAULT_VXLAN_IP_NETWORK,
+        description="First 3 octets of VXLAN subnet",
+    )
+    cluster_cidrs: str = Field(
+        description="Comma-separated CIDRs to NOT route through VPN",
+    )
+    vpn_connected: bool = Field(
+        default=False,
+        description="Whether VPN tunnel is established",
+    )
+    external_ip: str | None = Field(
+        default=None,
+        description="Current VPN exit IP for verification",
+    )
+    instance_name: str = Field(
+        description="Juju application name of the gateway",
+    )
+
+
+class VPNGatewayRequirerData(BaseModel):
+    """Data published by VPN gateway requirers."""
+
+    instance_name: str = Field(
+        description="Juju application name of the requirer",
+    )
+
+
+class VPNGatewayChangedEvent(EventBase):
+    """Event emitted when vpn-gateway relation state changes."""
+
+    pass
+
+
+class VPNGatewayProvider(Object):
+    """Provider side of vpn-gateway interface (passive - no events)."""
+
+    def __init__(self, charm: Any, relation_name: str = "vpn-gateway") -> None:
+        super().__init__(charm, relation_name)
+        self._charm = charm
+        self._relation_name = relation_name
+
+    def publish_data(self, data: VPNGatewayProviderData) -> None:
+        """Publish provider data to all relations."""
+        if not self._charm.unit.is_leader():
+            return
+
+        for relation in self._charm.model.relations.get(self._relation_name, []):
+            relation.data[self._charm.app]["config"] = data.model_dump_json()
+
+    def get_connected_clients(self) -> list[str]:
+        """Get list of connected requirer application names."""
+        clients = []
+        for relation in self._charm.model.relations.get(self._relation_name, []):
+            try:
+                app_data = relation.data[relation.app]
+                if app_data and "config" in app_data:
+                    data = VPNGatewayRequirerData.model_validate_json(app_data["config"])
+                    clients.append(data.instance_name)
+            except (ValidationError, KeyError):
+                continue
+        return clients
+
+    def is_ready(self) -> bool:
+        """Check if provider has any relations."""
+        return len(self._charm.model.relations.get(self._relation_name, [])) > 0
+
+
+class VPNGatewayRequirerEvents(ObjectEvents):
+    """Events emitted by VPNGatewayRequirer."""
+
+    changed = EventSource(VPNGatewayChangedEvent)
+
+
+class VPNGatewayRequirer(Object):
+    """Requirer side of vpn-gateway interface."""
+
+    on = VPNGatewayRequirerEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "vpn-gateway") -> None:
+        super().__init__(charm, relation_name)
+        self._charm = charm
+        self._relation_name = relation_name
+        events = charm.on[relation_name]
+        self.framework.observe(events.relation_changed, self._emit_changed)
+        self.framework.observe(events.relation_broken, self._emit_changed)
+
+    def _emit_changed(self, event: EventBase) -> None:
+        self.on.changed.emit()
+
+    def publish_data(self, data: VPNGatewayRequirerData) -> None:
+        """Publish requirer data to the relation."""
+        if not self._charm.unit.is_leader():
+            return
+
+        relation = self._charm.model.get_relation(self._relation_name)
+        if relation:
+            relation.data[self._charm.app]["config"] = data.model_dump_json()
+
+    def get_gateway(self) -> VPNGatewayProviderData | None:
+        """Get gateway provider data if available."""
+        relation = self._charm.model.get_relation(self._relation_name)
+        if not relation:
+            return None
+
+        try:
+            provider_app = relation.app
+            if provider_app:
+                provider_data = relation.data[provider_app]
+                if provider_data and "config" in provider_data:
+                    return VPNGatewayProviderData.model_validate_json(provider_data["config"])
+        except (ValidationError, KeyError):
+            pass
+        return None
+
+    def is_ready(self) -> bool:
+        """Check if gateway is available and VPN is connected."""
+        gateway = self.get_gateway()
+        return gateway is not None and gateway.vpn_connected

charmarr_lib_vpn-0.2.2.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: charmarr-lib-vpn
+Version: 0.2.2
+Summary: VPN gateway charm library for Kubernetes
+Author-email: Adhitya Ravi <adhityashan95@gmail.com>
+License: LGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: charmarr-lib-krm>=0.1
+Requires-Dist: lightkube>=0.15
+Requires-Dist: ops>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="../assets/charmarr-charmarr-lib.png" width="350" alt="Charmarr Lib">
+</p>
+
+<h1 align="center">charmarr-lib-vpn</h1>
+
+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
+
+```bash
+pip install charmarr-lib-vpn
+```
+
+## Usage
+
+### Interfaces
+
+```python
+from charmarr_lib.vpn.interfaces import (
+    VPNGatewayProvider,
+    VPNGatewayRequirer,
+    VPNGatewayProviderData,
+    VPNGatewayRequirerData,
+    VPNGatewayChangedEvent,
+)
+```
+
+### Gateway Patching (VPN gateway side - gluetun)
+
+```python
+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)
+
+```python
+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)
+
+```python
+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
+
+```python
+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,
+)
+```

charmarr_lib_vpn-0.2.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+charmarr_lib/vpn/__init__.py,sha256=nm5l2EeYTXTCth4ItmssQCmncf95WkFtRgKvuK6_nT4,1412
+charmarr_lib/vpn/_version.py,sha256=aB8nHXsa9U2rYEzbBMgYI-KFGyuS8pe2xXtf2OFHYcs,91
+charmarr_lib/vpn/constants.py,sha256=YE3VU_ZLFPBY_3xtqjR57XsQlVH7aSyb10Oro0S0thQ,683
+charmarr_lib/vpn/_k8s/__init__.py,sha256=uVhI_LCNwgMcoV-EcBb5kxy0N1FdGEjFcHkOU61tWZw,1611
+charmarr_lib/vpn/_k8s/_gateway.py,sha256=DCOsC_aLToAUjm1YXMPP6agYAGH25mndv2JHMFpGRWU,6368
+charmarr_lib/vpn/_k8s/_gateway_client.py,sha256=kqsuy3t5oRCswGj8sVAbK2be2dj-IQnAmxbT32I_81U,6024
+charmarr_lib/vpn/_k8s/_kill_switch.py,sha256=1tzvWAT3I_6OuTTscEcqkiHXa8Eqe2tGGrDnXb2eMa4,6847
+charmarr_lib/vpn/interfaces/__init__.py,sha256=stnITzP8difNh9exlyqJkyAcTXyhfhYykxU3T99KRuE,491
+charmarr_lib/vpn/interfaces/_vpn_gateway.py,sha256=ib2aMvvE4SZhlORZR5-YOCcPDoRrv7wEeHOGoUgZKIk,5122
+charmarr_lib_vpn-0.2.2.dist-info/METADATA,sha256=KK2Ix6OkTA63Ux5U1zbTktz7KuLdbzYN3cJYs0BbTls,3390
+charmarr_lib_vpn-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+charmarr_lib_vpn-0.2.2.dist-info/RECORD,,

charmarr_lib_vpn-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any