Skip to content

Latest commit

 

History

History
100 lines (76 loc) · 4.42 KB

AGENTS.md

File metadata and controls

100 lines (76 loc) · 4.42 KB

AGENTS.md - ngrok Kubernetes Operator

The ngrok-operator is a Kubernetes Operator that reconciles:

  • Service resources of Type=LoadBalancer
  • Ingress resources
  • Gateway API resources
  • ngrok CRDs

Quick Facts

  • Module: github.com/ngrok/ngrok-operator
  • Type: Kubernetes Operator (kubebuilder v4, multigroup)
  • Domain: k8s.ngrok.com
  • Language: Go

Entry Points & Modes

  • main.go → cmd.Execute()
  • cmd/ contains three operational modes:
    • api-manager.go - Manages ngrok resources via ngrok API (CRDs → ngrok API)
    • agent-manager.go - Runs ngrok agents in-cluster for tunneling
    • bindings-forwarder-manager.go - Manages service bindings and forwarding

Directory Map

api/<group>/v1alpha1/        # CRD definitions (ingress, ngrok, bindings)
internal/controller/<group>/ # Reconcilers organized by API group
internal/controller/base_controller.go  # Common CRUD/finalizers/status helpers
internal/ngrokapi/           # ngrok API client wrappers
internal/ir/                 # Intermediate representation (K8s → ngrok API)
internal/store/              # State management and caching
pkg/managerdriver/           # Manager driver implementations
pkg/bindingsdriver/          # Bindings driver implementations
cmd/                         # CLI and manager entry points
config/                      # Kustomize manifests (CRDs, RBAC, etc.)
helm/ngrok-operator/         # Helm chart

Resource → Controller Map

API Group Resources Controller Location
ingress.k8s.ngrok.com/v1alpha1 Domain, IPPolicy internal/controller/ingress/
ingress.k8s.ngrok.com/v1alpha1 Ingress (networking.k8s.io/v1) internal/controller/ingress/
ngrok.k8s.ngrok.com/v1alpha1 NgrokTrafficPolicy, KubernetesOperator internal/controller/ngrok/
bindings.k8s.ngrok.com/v1alpha1 BindingConfiguration, BoundEndpoint internal/controller/bindings/
gateway.networking.k8s.io/v1 Gateway, GatewayClass, HTTPRoute, TLSRoute, TCPRoute internal/controller/gateway/
core/v1 Service internal/controller/service/
agent AgentEndpoint internal/controller/agent/

Core Patterns

Development Environment

Use the Nix devShell for a consistent development environment:

nix develop                 # Enter devShell with all tools (recommended)

Users with direnv configured will automatically enter the devShell via .envrc.

Run make preflight to verify your environment is configured correctly.

Development Workflow

make help                   # List all available targets
make preflight              # Verify environment (Go version, controller-gen)
make generate               # Generate DeepCopy methods
make manifests              # Generate CRDs, RBAC, webhooks
make build                  # Build binaries
make test                   # Run unit tests
make e2e-tests              # Run E2E tests
make run                    # Run locally (uses kubeconfig)
make deploy                 # Deploy to cluster
make undeploy               # Remove from cluster

Configuration

  • Credentials: helm install requires credentials.apiKey and credentials.authtoken
  • Feature Flags: gateway.enabled=true enables Gateway API support

Rules

  • Always register new APIs with AddToScheme in manager setup
  • Update RBAC markers (// +kubebuilder:rbac:...) when adding permissions
  • Use status subresource (r.Status().Update()) for status-only updates
  • Manage finalizers on resource deletion to clean up external resources
  • Requeue on transient ngrok API errors (return ctrl.Result{Requeue: true})
  • Prefer BaseController helpers over raw client operations