feat(clustermesh): add persistentKeepalive support for NAT traversal

[IvanHunters]

Summary

Adds optional persistentKeepalive field to remoteClusters and localCluster entries in the ClusterMesh template.

When set to a non-zero value (e.g. 25), it is forwarded to every WireGuard Peer CRD the operator creates for nodes in that cluster. This keeps the stateful NAT mapping alive and enables bidirectional WireGuard connectivity for clusters behind NAT (e.g. OpenStack tenants without floating IPs).

Usage

addons:
  kilo:
    clusterMesh:
      remoteClusters:
        - name: nuvolos-workload
          podCIDRs: [...]
          persistentKeepalive: 25   # seconds; 0 = disabled (default)

Dependencies

Requires kilo-clustermesh-operator >= 0.6.0 (cozystack/kilo-clustermesh-operator#20) which:

• Adds persistentKeepalive to ClusterEntry and propagates it to Peer CRDs
• Adds discovered-endpoint enrichment so the operator auto-detects the real NAT egress IP from kilo.squat.ai/discovered-endpoints annotations

[gemini-code-assist]

Code Review

This pull request adds support for configuring the WireGuard persistentKeepalive interval in the Kilo ClusterMesh configuration. The changes update the clustermesh.yaml template and the OpenAPI schema in cozyrds.yaml. The review feedback correctly identifies that the localCluster field (and its persistentKeepalive property) is missing from the OpenAPI schema in cozyrds.yaml despite being used in the templates, and suggests adding it to ensure proper validation and documentation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The localCluster field is used in the clustermesh.yaml template and documented in values.yaml, but it is completely missing from the OpenAPI schema in cozyrds.yaml. Defining it in the schema ensures proper validation, documentation, and auto-completion for users configuring the KubernetesSwitchcloud custom resource. Additionally, the new persistentKeepalive field should be documented under both remoteClusters and localCluster properties.

      {"title":"Chart Values","type":"object","properties":{"openstack":{"description":"OpenStack connection settings.","type":"object","default":{},"properties":{"authURL":{"description":"OpenStack identity endpoint.","type":"string","default":""},"regionName":{"description":"OpenStack region name.","type":"string","default":""},"applicationCredentialID":{"description":"Application credential ID.","type":"string","default":""},"applicationCredentialSecret":{"description":"Application credential secret.","type":"string","default":""},"cloudName":{"description":"Cloud name used as key in clouds.yaml.","type":"string","default":"openstack"},"existingSecret":{"description":"Name of existing Secret with clouds.yaml (overrides inline credentials).","type":"string","default":""},"floatingIPNetwork":{"description":"External network for Floating IPs (leave empty to disable FIPs).","type":"string","default":""},"loadBalancer":{"description":"Centralised LoadBalancer feature. When enabled, the management-cluster loadbalancer-controller provisions Octavia LBs for tenant Services of type LoadBalancer using the OpenStack credentials configured above; tenant cluster users never see those credentials directly.","type":"object","default":{},"properties":{"enabled":{"description":"Enable centralised LoadBalancer provisioning for this tenant. Off by default; turn on only after the controller has been deployed to the management cluster.","type":"boolean","default":false},"providerDriver":{"description":"Octavia provider driver. In Switch Cloud zhw only `ovn` is functional (the `amphora` driver has no flavors). Leave empty to use the project default.","type":"string","default":"ovn"},"vipNetworkID":{"description":"REQUIRED when enabled=true. Neutron network ID where the LB VIP port is allocated. Must be a tenant-owned network reachable from the worker nodes (typically the same network as spec.openstack.network.id). In Switch Cloud zhw direct-on-public VIP is not BGP-announced for IPv4, so VIP must live on a tenant network and external access is wired via floatingNetworkID below.","type":"string","default":""},"floatingNetworkID":{"description":"Optional external network ID. When set, the controller allocates a floating IP from this network after the LB becomes ACTIVE and binds it to the LB VIP port; the FIP address is reported back in Service.status.loadBalancer.ingress. Leave empty for internal-only LBs (no external reachability).","type":"string","default":""},"floatingSubnetID":{"description":"Optional Neutron subnet ID within floatingNetworkID. Pins FIP allocation to a specific subnet when the external network has multiple subnets (e.g. dual-stack). Leave empty to let Neutron pick.","type":"string","default":""},"workerSecurityGroupID":{"description":"Optional Neutron security group ID attached to the worker-node ports. When set, the controller manages per-Service ingress rules in this SG (one rule per Service port \u00d7 allowedCIDRs). Required for external traffic to reach the NodePort behind the LB: Octavia's pool members carry the worker port's SG, so without an explicit allow rule the default SG (which only permits intra-SG traffic) drops inbound packets coming from the LB VIP. Leave empty if you prefer to manage SG rules manually outside the controller; operator-managed rules are then your responsibility.","type":"string","default":""},"allowedCIDRs":{"description":"CIDR allowlist for inbound traffic to the LB NodePort. Each Service port gets ingress rules in workerSecurityGroupID for every CIDR listed here. Defaults to 0.0.0.0/0 (publicly reachable); narrow this when only specific networks should reach the Service. Ignored when workerSecurityGroupID is unset.","type":"array","default":["0.0.0.0/0"],"items":{"type":"string"}}}},"network":{"description":"OpenStack network settings. When `id` is set the chart operates in legacy mode and CAPO consumes that pre-existing network. When `id` is empty CAPO auto-manages a per-cluster network/subnet/router on apply and tears them down on cluster delete, giving full L2/L3 isolation between clusters in the same project.","type":"object","default":{},"properties":{"id":{"description":"Pre-existing OpenStack network ID for worker nodes. Legacy mode. Leave empty to enable auto-managed mode below. IMMUTABLE once set: clearing this field would switch a live cluster from legacy to auto-managed and trigger CAPO to provision a brand-new network, orphaning the old one and rerolling all workers (hard outage). Delete and recreate the cluster CR if you really need to switch modes.","type":"string","default":"","x-kubernetes-validations":[{"rule":"self == oldSelf || oldSelf == ''","message":"spec.openstack.network.id is immutable once set: clearing it would switch the cluster from legacy to auto-managed mode and trigger a network re-provision (data loss). Delete and recreate the cluster CR instead."}]},"subnetCIDR":{"description":"IPv4 CIDR for the auto-managed worker subnet. Used only when `id` is empty. Default `10.244.0.0/24` is chosen to NOT overlap the in-cluster default podCIDR `10.243.0.0/16`; pick a non-overlapping range if you mesh multiple clusters via Kilo.","type":"string","default":"10.244.0.0/24"},"externalNetworkID":{"description":"Neutron network ID used as the router's external gateway in auto-managed mode. Leave empty to let CAPO auto-discover the single project-visible external network (Switch Cloud zhw: the `public` network).","type":"string","default":""},"dnsNameservers":{"description":"DNS servers wired into the auto-managed subnet's DHCP. Used only when `id` is empty. Empty list = OpenStack default.","type":"array","default":[],"items":{"type":"string"}}}}}},"version":{"description":"Kubernetes version string (e.g. v1.32.6).","type":"string","default":"v1.32.6"},"talosVersion":{"description":"Talos OS version embedded in the node image.","type":"string","default":"v1.10.0"},"controlPlane":{"description":"Kamaji control-plane configuration.","type":"object","default":{},

[kvaps]

Superseded by #154. The persistentKeepalive template support landed in #152 (clustermesh.yaml migrated to flat allowedNetworks); the CR schema (cozyrds.yaml flat allowedNetworks + persistentKeepalive) and operator 0.6.1 (which stops forcing InternalIP endpoints) are in #154.