Charm architecture

At its core, the WireGuard gateway charm is a highly available, high-performance site-to-site VPN solution that can be used to connect multiple network environments.

It uses WireGuard, a modern and secure VPN protocol, to provide encrypted and authenticated tunnels. It also uses BIRD and Keepalived to provide network high availability and link redundancy using OSPF, ECMP, and VRRP.

High-level overview of WireGuard gateway charm deployment

The following diagram shows a typical deployment of the WireGuard gateway charm in three separate network environments, each containing a WireGuard gateway charm. The three WireGuard gateway charms are integrated with charm relations and forward traffic between the three network environments through encrypted WireGuard tunnels.

        C4Context
    title WireGuard gateway charm deployment
    Boundary(network-a, "Network A") {
        Component(wireguard-a, "WireGuard gateway")
    }
    Boundary(network-b, "Network B") {
        Component(wireguard-b, "WireGuard gateway")
    }
    Boundary(network-c, "Network C") {
        Component(wireguard-c, "WireGuard gateway")
    }
    Rel(wireguard-a, wireguard-b, "WireGuard router relation")
    Rel(wireguard-c, wireguard-b, "WireGuard router relation")
    Rel(wireguard-a, wireguard-c, "WireGuard router relation")
    UpdateRelStyle(wireguard-a, wireguard-b, $offsetY="-50", $offsetX="-40")
    UpdateRelStyle(wireguard-a, wireguard-c, $offsetY="-50", $offsetX="-40")
    

Charm architecture

The following diagram shows the architecture of the WireGuard gateway charm:

Metrics

The WireGuard gateway charm provides Prometheus metrics. The full list of metrics can be found here.

Juju events

For this charm, the following Juju events are observed:

1. config-changed

2. upgrade-charm

3. update-status

4. wireguard-router-a-relation-changed

5. wireguard-router-a-relation-broken

6. wireguard-router-a-relation-joined

7. wireguard-router-a-relation-departed

8. wireguard-router-b-relation-changed

9. wireguard-router-b-relation-broken

10. wireguard-router-b-relation-joined

11. wireguard-router-b-relation-departed

During all of those events, the charm runs the same reconciliation process to update the configuration, including relation data, WireGuard configuration, BIRD configuration, and Keepalived configuration, based on the current charm configuration and remote relation data.

Note

See more in the Juju docs: Hook

Charm code overview

The src/charm.py file is the default entry point for the WireGuard gateway charm. It creates an instance of the Charm class, which inherits from ops.CharmBase. ops.CharmBase is the base class from which all charms are derived, provided by Ops (the Python framework for developing charms).

Note

See more in the Juju docs: Charm

The __init__ method of Charm ensures that the charm observes and handles all events relevant to its operation.

For example, when a configuration is changed using the CLI:

1. The user runs the configuration command:

juju config wireguard-gateway advertise-prefixes="10.0.0.0/8"

2. A config-changed event is emitted.

3. In the __init__ method, the handler for this event is defined as follows:

self.framework.observe(self.on.config_changed, self.reconcile)

4. The reconcile method, in turn, takes the necessary actions, such as updating relation(s) and updating WireGuard/BIRD/Keepalived configurations.