Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (59 loc) · 2.54 KB

AGENTS.md

File metadata and controls

79 lines (59 loc) · 2.54 KB
Raw

AGENTS.md

This file provides context for AI coding agents working on this project.

Project Overview

kube-edge-router is a Kubernetes Operator that automates the exposure of LoadBalancer services through remote Edge VPS nodes. It bridges internal MetalLB VIPs to public IPv4 addresses via WireGuard tunnels.

Architecture

This project follows Hexagonal Architecture (Ports & Adapters):

├── cmd/                          # Application entrypoints
│   └── controller/               # Main controller binary
├── internal/
│   ├── domain/                   # Core business logic (no external deps)
│   │   ├── edge.go               # EdgeNode entity
│   │   ├── allocation.go         # IP allocation logic
│   │   └── ports.go              # Interface definitions
│   ├── application/              # Use cases / Services
│   │   └── reconciler.go         # Main reconciliation service
│   └── adapters/
│       ├── kubernetes/           # K8s client, CRD handling
│       ├── ssh/                  # SSH client for Edge commands
│       └── nftables/             # nftables rule generation
├── api/v1alpha1/                 # CRD type definitions
└── config/                       # Kustomize manifests

Key Concepts

Term Description
EdgeNode CRD representing a VPS with public IPs available for routing
Allocation Mapping of a public IP to a Kubernetes Service
Internal VIP MetalLB-assigned IP in the Core cluster (private)
Public IP Internet-routable IP on the Edge VPS

Technology Stack

  • Language: Go 1.22+
  • Framework: Kubebuilder / controller-runtime
  • CRDs: EdgeNode (cluster-scoped)
  • Edge Tools: nftables, SSH
  • Tunnel: WireGuard (pre-configured, not managed by this controller)

Security Model

Important

The Edge VPS is considered untrusted infrastructure.

  • Control flow: Core → Edge only (SSH push model)
  • SSH: Private key stored as K8s Secret in Core
  • No secrets on Edge: Only forwarding rules, no sensitive data

Development Commands

# Run tests
make test

# Generate CRD manifests
make manifests

# Build controller binary
make build

# Deploy to cluster
make deploy

Code Style

  • Use internal/ for all non-public packages
  • Interfaces (ports) defined in domain/ports.go
  • Adapters implement domain interfaces
  • No business logic in adapters
  • Errors should be wrapped with context