Provision WAN Hub to Edge (HyOps Blueprint)¶

Purpose: Provision a deterministic BGP/IPsec control plane between GCP Cloud Router and Hetzner VyOS edge peers. Owner: Network/platform engineering
Trigger: New environment bring-up, WAN underlay rebuild, or edge pair replacement
Impact: WAN underlay and cloud hub routing become active for the target environment
Severity: P2 Pre-reqs: hyops init hetzner and hyops init gcp completed for target env; vault decrypt working; WAN_IPSEC_PSK set in vault.
Rollback strategy: Destroy module states in reverse dependency order (org/gcp/wan-vpn-to-edge → org/gcp/wan-cloud-router → org/gcp/wan-hub-network → org/hetzner/vyos-edge-foundation → core/hetzner/vyos-image-seed), or rerun blueprint with corrected inputs.

Context¶

Blueprint ref: networking/wan-hub-edge@v1 Location: hybridops-core/blueprints/networking/wan-hub-edge@v1/blueprint.yml

This blueprint provisions the WAN underlay only: it does not include the edge day-2 routing policy, observability, DNS, or decision control-loop. For the full edge control plane, see networking/edge-control-plane@v1.

Step flow:

core/shared/vyos-image-build: build or register the canonical VyOS artifact (skip_if_state_ok: true)
core/hetzner/vyos-image-seed: seed or discover the Hetzner custom VyOS image (skip_if_state_ok: true)
org/hetzner/vyos-edge-foundation: provision the routed Hetzner edge pair (skip_if_state_ok: true)
org/gcp/wan-hub-network: provision GCP hub VPC and subnets (skip_if_state_ok: true)
org/gcp/wan-cloud-router: provision GCP Cloud Router with BGP ASN (skip_if_state_ok: true)
org/gcp/wan-vpn-to-edge: provision HA VPN tunnels and BGP peers to Hetzner edge (always reconciles)

Rerun safety:

Steps 1–5 are skip_if_state_ok: true: safe to rerun; idempotent when infrastructure is intact.
Step 6 (org/gcp/wan-vpn-to-edge) always reconciles to pick up refreshed edge public IPs after an edge rebuild.
The shipped blueprint now uses the current platform/dev GCP naming contract for hub network, cloud router, and HA VPN resources. Rebuilds must not rename those resources implicitly, because the router is already referenced by live VPN tunnels.
First-boot VyOS behavior: Hetzner custom images perform one intentional reboot after cloud-init writes config.boot. Treat the short initial SSH gap as expected first-boot behavior.

Preconditions and safety checks¶

Validate init readiness for both providers:
```
hyops init status --env <env>
```

Ensure required secrets exist:

hyops secrets ensure --env <env> WAN_IPSEC_PSK

Initialize an env-scoped blueprint overlay:

hyops blueprint init --env <env> \
  --ref networking/wan-hub-edge@v1 \
  --dest-name wan-hub-edge.yml

Steps¶

Edit the env-scoped blueprint overlay

$EDITOR ~/.hybridops/envs/<env>/config/blueprints/wan-hub-edge.yml

Edit ~/.hybridops/envs/<env>/config/blueprints/wan-hub-edge.yml and set:

gcp_wan_hub_network.inputs.context_id: environment or lane identifier
gcp_wan_hub_network.inputs.project_id: target GCP project
gcp_wan_hub_network.inputs.region: GCP region for hub network
gcp_wan_hub_network.inputs.subnet_*_cidr: hub subnet CIDRs
gcp_wan_cloud_router.inputs.router_name: Cloud Router name
gcp_wan_vpn_to_edge.inputs.ha_vpn_gateway_name and external_vpn_gateway_name
gcp_wan_vpn_to_edge.inputs.advertised_prefixes: prefixes the GCP side should advertise
hetzner_edge_foundation.inputs.network_zone: Hetzner network zone
hetzner_edge_foundation.inputs.ssh_key_name: Hetzner SSH key name
hetzner_edge_foundation.inputs.ssh_public_key: public key (required when key does not already exist in Hetzner)
hetzner_edge_foundation.inputs.private_network_* and edge private IPs

Validate and preflight the env-scoped overlay

hyops blueprint validate \
  --file ~/.hybridops/envs/<env>/config/blueprints/wan-hub-edge.yml

hyops blueprint preflight --env <env> \
  --file ~/.hybridops/envs/<env>/config/blueprints/wan-hub-edge.yml

Execute the blueprint

hyops blueprint deploy --env <env> \
  --file ~/.hybridops/envs/<env>/config/blueprints/wan-hub-edge.yml \
  --execute

Track run records while running

Module logs are written under: ~/.hybridops/envs/<env>/logs/module/<module_ref_sanitized>/<run_id>/

Verification¶

Success indicators:

Blueprint summary ends with status=ok.
All steps report status=ok or skipped with valid prior state.
GCP Cloud Router BGP peers reach Established status (BGP session to Hetzner edge public IPs).

Verify state for key steps:

hyops state show --env <env> --module core/hetzner/vyos-image-seed
hyops state show --env <env> --module org/hetzner/vyos-edge-foundation
hyops state show --env <env> --module org/gcp/wan-hub-network
hyops state show --env <env> --module org/gcp/wan-cloud-router
hyops state show --env <env> --module org/gcp/wan-vpn-to-edge

Verify GCP BGP session state in the console or via gcloud:

gcloud compute routers get-status hybridops-hub-router-europe-west2 \
  --region europe-west2 \
  --project <project_id>

Note: learned spoke routes may be 0 until an on-prem/spoke route-originating layer is deployed.

Post-actions and clean-up¶

Update environment state documentation with edge public IPs and tunnel endpoints.
If BGP does not establish, confirm Hetzner floating IP assignment and first-boot settle window has passed.
After edge rebuild, rerun org/gcp/wan-vpn-to-edge step to push refreshed IPs into HA VPN peer config.
To continue to the full edge control plane (day-2 routing policy, observability, DNS, decision service), proceed with networking/edge-control-plane@v1.

References¶

License: MIT-0 for code, CC-BY-4.0 for documentation