Custom Resources

Specifications for all 7 unbounded-net CRDs.

unbounded-net uses seven Custom Resource Definitions (CRDs) in the net.unbounded-cloud.io API group. For a conceptual introduction to Sites and GatewayPools, see Networking Concepts.

Site

A Site represents a network location containing nodes. Nodes are automatically assigned to sites based on their internal IP addresses matching the site’s nodeCidrs.

Example

apiVersion: net.unbounded-cloud.io/v1alpha1
kind: Site
metadata:
  name: site-east
spec:
  nodeCidrs:
    - "10.0.0.0/16"
    - "10.1.0.0/16"
  podCidrAssignments:
    - assignmentEnabled: true
      cidrBlocks:
        - "100.64.0.0/16"
        - "fdde:1::/48"
      nodeBlockSizes:
        ipv4: 24
        ipv6: 80
      nodeRegex:
        - "^worker-.*"
      priority: 100
  manageCniPlugin: true

Spec Fields

PodCidrAssignment Fields

Status Fields

manageCniPlugin Behavior

Set to false when using an external CNI plugin (e.g., Cilium, Calico) for intra-site networking while unbounded-net handles only cross-site routing.

Admission Validation

• nodeCidrs must be valid CIDRs and cannot overlap across sites.
• Pod CIDR assignment blocks cannot overlap across sites.
• Pod CIDR mask sizes must be consistent within a site.
• IPv6 masks must be no more than 16 bits larger than the pool prefix.
• nodeRegex values must be valid regex patterns.
• Sites with active nodes cannot be deleted.

SiteNodeSlice

Contains a slice of nodes belonging to a site. Each slice holds up to 500 nodes to prevent exceeding Kubernetes object size limits.

Automatically managed by the controller. Do not create, modify, or delete these manually. They are owned by their parent Site and garbage collected when the Site is deleted.

Example

apiVersion: net.unbounded-cloud.io/v1alpha1
kind: SiteNodeSlice
metadata:
  name: site-east-0
  ownerReferences:
    - apiVersion: net.unbounded-cloud.io/v1alpha1
      kind: Site
      name: site-east
siteName: site-east
sliceIndex: 0
nodeCount: 2
nodes:
  - name: node-001
    wireGuardPublicKey: "abc123...="
    internalIPs: ["10.0.1.5"]
    podCIDRs: ["100.64.0.0/24", "fdde:1::100/80"]
  - name: node-002
    wireGuardPublicKey: "def456...="
    internalIPs: ["10.0.1.6"]
    podCIDRs: ["100.64.1.0/24"]

Fields

Deletion is blocked while a slice still references active nodes.

GatewayPool

Defines a pool of gateway nodes selected by labels. Gateway nodes route traffic between sites.

Example

apiVersion: net.unbounded-cloud.io/v1alpha1
kind: GatewayPool
metadata:
  name: main-gateways
spec:
  type: External
  nodeSelector:
    net.unbounded-cloud.io/gateway: "true"
  routedCidrs:
    - "172.16.0.0/12"
  healthCheckSettings:
    enabled: true
  tunnelProtocol: Auto

Spec Fields

Status Fields

Gateway Node Requirements

A node is included in the pool status when it:

1. Matches the nodeSelector labels.
2. Has a WireGuard public key annotation.

Gateway Peer IP Resolution

Deletion is blocked while a pool has active matching nodes.

GatewayPoolNode

Represents an individual node’s membership in a gateway pool. Automatically created by the controller; the node agent patches status with route advertisements and heartbeat timestamps.

Automatically managed. Do not create or modify manually.

Fields

SitePeering

Defines direct peering between sites. When meshNodes is true (default), nodes in peered sites create direct WireGuard tunnels, bypassing gateways.

Example

apiVersion: net.unbounded-cloud.io/v1alpha1
kind: SitePeering
metadata:
  name: east-west-peering
spec:
  sites:
    - "site-east"
    - "site-west"
    - "site-central"
  meshNodes: true
  healthCheckSettings:
    enabled: true
    detectMultiplier: 3
    receiveInterval: 300ms
    transmitInterval: 300ms
  tunnelProtocol: Auto

Spec Fields

Status Fields

Behavior

Use Cases

• Low-latency cross-site: Sites with fast connectivity (same cloud region, dedicated interconnect). Use meshNodes: true for direct WireGuard tunnels.

• Externally peered sites (ExpressRoute, Direct Connect, VPN): Two sites already connected over a private L3 link can be merged into one logical network. Use meshNodes: false and tunnelProtocol: None to route pod traffic directly over the existing connection with zero encapsulation overhead. WireGuard is still available for any other site pairs in the same cluster.

  spec:
    sites:
      - site-on-prem
      - site-azure
    meshNodes: false
    tunnelProtocol: None
  

• Large sites without full mesh: Use meshNodes: false to avoid O(n²) tunnels while still benefiting from internal IP routing via gateways.

SiteGatewayPoolAssignment

Defines which gateway pools serve which sites.

Example

apiVersion: net.unbounded-cloud.io/v1alpha1
kind: SiteGatewayPoolAssignment
metadata:
  name: east-gateways
spec:
  sites:
    - "site-east"
  gatewayPools:
    - "main-gateways"
    - "backup-gateways"
  healthCheckSettings:
    enabled: true
  tunnelProtocol: Auto

Spec Fields

GatewayPoolPeering

Defines peering between gateway pools, enabling cross-pool routing.

Example

apiVersion: net.unbounded-cloud.io/v1alpha1
kind: GatewayPoolPeering
metadata:
  name: east-west-pool-peering
spec:
  gatewayPools:
    - "east-gateways"
    - "west-gateways"
  healthCheckSettings:
    enabled: true
  tunnelProtocol: Auto

Spec Fields

HealthCheckSettings

The healthCheckSettings object is shared across Site, SitePeering, GatewayPool, SiteGatewayPoolAssignment, and GatewayPoolPeering:

Precedence

• Same-site routes: Site.spec.healthCheckSettings
• Peered-site routes: SitePeering.spec.healthCheckSettings
• Gateway pool routes: SiteGatewayPoolAssignment.spec.healthCheckSettings → GatewayPool.spec.healthCheckSettings → Site.spec.healthCheckSettings

If multiple peerings define conflicting settings, peerings are processed in deterministic name order and the first profile is kept.

Labels, Annotations, and Taints

Labels

Annotations

Taints

Short Names

CRD Relationships

Next Steps

• Architecture – System internals and data flows.
• Configuration – All flags and tuning options.
• Operations – Deployment and troubleshooting.