Documentation
¶
Overview ¶
Package controller implements Kubernetes controllers for Gateway API resources.
The package provides two main controllers:
GatewayReconciler: Watches Gateway resources and manages cloudflared deployment via Helm when --manage-cloudflared is enabled. Updates Gateway status with the tunnel CNAME address for external-dns integration.
HTTPRouteReconciler: Watches HTTPRoute resources and synchronizes them to Cloudflare Tunnel ingress configuration via the Cloudflare API. Performs full synchronization on startup and on any route change.
Architecture ¶
The controllers follow the standard controller-runtime reconciliation pattern:
┌─────────────┐ watch ┌─────────────────────────┐
│ HTTPRoute │─────────────>│ HTTPRouteReconciler │
│ resources │ │ │
└─────────────┘ └───────────┬─────────────┘
│
┌─────────────┐ watch │ Cloudflare API
│ Gateway │─────────────>│ │
│ resources │ │ ▼
└─────────────┘ │ ┌─────────────────┐
│ │ │ Tunnel Config │
│ │ └────────┬────────┘
▼ │ │
┌─────────────────────────┐ │ ▼
│ GatewayReconciler │ │ ┌─────────────────┐
│ (optional Helm mgmt) │ │ │ cloudflared │
└─────────────────────────┘ │ │ (hot reload) │
│ └─────────────────┘
Configuration ¶
Controllers are configured via the Config struct which accepts settings from CLI flags or environment variables (CF_* prefix).
Leader Election ¶
When running multiple replicas for high availability, enable leader election via --leader-elect flag to ensure only one controller actively reconciles resources at a time.
Index ¶
- Constants
- func Run(ctx context.Context, cfg *Config) error
- func SecretMatchesConfig(secret *corev1.Secret, cfg *v1alpha1.GatewayClassConfig) bool
- type Config
- type ConfigMapper
- type GRPCRouteReconciler
- type GatewayClassConfigReconciler
- type GatewayReconciler
- type HTTPRouteReconciler
- type RequestsFunc
- type RouteSyncer
- type RouteUpdateFunc
- type SyncResult
Constants ¶
const ( // ConditionTypeValid indicates whether the GatewayClassConfig is valid. ConditionTypeValid = "Valid" // ConditionTypeSecretsResolved indicates whether all referenced secrets exist. ConditionTypeSecretsResolved = "SecretsResolved" )
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run initializes and starts the controller manager with the provided configuration. It sets up the config resolver, creates Gateway and HTTPRoute controllers, and blocks until the context is cancelled or an error occurs.
The function performs the following steps:
- Initializes controller-runtime manager with metrics and health endpoints
- Registers GatewayClassConfig CRD scheme
- Creates ConfigResolver for reading GatewayClassConfig
- Sets up GatewayReconciler and HTTPRouteReconciler with watches
- Optionally initializes Helm manager for cloudflared deployment
- Starts the manager and blocks until shutdown
func SecretMatchesConfig ¶ added in v0.0.4
func SecretMatchesConfig(secret *corev1.Secret, cfg *v1alpha1.GatewayClassConfig) bool
SecretMatchesConfig checks if a Secret is referenced by the GatewayClassConfig.
Types ¶
type Config ¶
type Config struct {
// ClusterDomain is the Kubernetes cluster domain for service DNS resolution.
// Defaults to "cluster.local".
ClusterDomain string
// GatewayClassName is the name of the GatewayClass to watch.
// Only Gateways referencing this class will be reconciled.
GatewayClassName string
// ControllerName is the controller name reported in GatewayClass status.
ControllerName string
// MetricsAddr is the address for the Prometheus metrics endpoint.
MetricsAddr string
// HealthAddr is the address for health and readiness probe endpoints.
HealthAddr string
// LeaderElect enables leader election for high availability.
// Required when running multiple replicas.
LeaderElect bool
// LeaderElectNS is the namespace for the leader election lease.
LeaderElectNS string
// LeaderElectName is the name of the leader election lease.
LeaderElectName string
}
Config holds all configuration options for the controller manager. Values are typically populated from CLI flags or environment variables.
type ConfigMapper ¶ added in v0.0.4
type ConfigMapper struct {
Client client.Client
GatewayClassName string
ConfigResolver *config.Resolver
}
ConfigMapper provides shared mapping logic for GatewayClassConfig and Secret events.
func (*ConfigMapper) MapConfigToRequests ¶ added in v0.0.4
func (m *ConfigMapper) MapConfigToRequests(getRequests RequestsFunc) func(context.Context, client.Object) []reconcile.Request
MapConfigToRequests returns a mapper function for GatewayClassConfig events.
func (*ConfigMapper) MapSecretToRequests ¶ added in v0.0.4
func (m *ConfigMapper) MapSecretToRequests(getRequests RequestsFunc) func(context.Context, client.Object) []reconcile.Request
MapSecretToRequests returns a mapper function for Secret events.
type GRPCRouteReconciler ¶ added in v0.8.0
type GRPCRouteReconciler struct {
client.Client
// Scheme is the runtime scheme for API type registration.
Scheme *runtime.Scheme
// GatewayClassName filters which routes to process.
GatewayClassName string
// ControllerName is reported in GRPCRoute status.
ControllerName string
// RouteSyncer provides unified sync for both HTTP and GRPC routes.
RouteSyncer *RouteSyncer
// contains filtered or unexported fields
}
GRPCRouteReconciler reconciles GRPCRoute resources and synchronizes them to Cloudflare Tunnel ingress configuration.
Key behaviors:
- Watches all GRPCRoute resources in the cluster
- Filters routes by parent Gateway's GatewayClass
- Uses shared RouteSyncer for unified sync with HTTPRoutes
- Updates GRPCRoute status with acceptance conditions
func (*GRPCRouteReconciler) SetupWithManager ¶ added in v0.8.0
func (r *GRPCRouteReconciler) SetupWithManager(mgr ctrl.Manager) error
type GatewayClassConfigReconciler ¶ added in v0.0.4
type GatewayClassConfigReconciler struct {
client.Client
Scheme *runtime.Scheme
DefaultNamespace string
}
GatewayClassConfigReconciler reconciles GatewayClassConfig resources. It validates the configuration and updates status conditions.
func (*GatewayClassConfigReconciler) SetupWithManager ¶ added in v0.0.4
func (r *GatewayClassConfigReconciler) SetupWithManager(mgr ctrl.Manager) error
SetupWithManager sets up the controller with the Manager.
type GatewayReconciler ¶
type GatewayReconciler struct {
client.Client
// Scheme is the runtime scheme for API type registration.
Scheme *runtime.Scheme
// GatewayClassName is the name of the GatewayClass to watch.
GatewayClassName string
// ControllerName is reported in Gateway status conditions.
ControllerName string
// ConfigResolver resolves configuration from GatewayClassConfig.
ConfigResolver *config.Resolver
// HelmManager handles cloudflared deployment. If nil, cloudflared
// management is disabled regardless of config.
HelmManager *helm.Manager
}
GatewayReconciler reconciles Gateway resources for the cloudflare-tunnel GatewayClass.
It performs the following functions:
- Watches Gateway resources matching the configured GatewayClassName
- Reads configuration from GatewayClassConfig via parametersRef
- Updates Gateway status with tunnel CNAME address (for external-dns integration)
- Manages cloudflared deployment lifecycle via Helm (when enabled in config)
- Handles Gateway deletion with proper cleanup of cloudflared resources
The reconciler uses finalizers to ensure cloudflared is properly removed when a Gateway is deleted.
func (*GatewayReconciler) SetupWithManager ¶
func (r *GatewayReconciler) SetupWithManager(mgr ctrl.Manager) error
SetupWithManager sets up the controller with the Manager.
type HTTPRouteReconciler ¶
type HTTPRouteReconciler struct {
client.Client
// Scheme is the runtime scheme for API type registration.
Scheme *runtime.Scheme
// GatewayClassName filters which routes to process.
GatewayClassName string
// ControllerName is reported in HTTPRoute status.
ControllerName string
// RouteSyncer provides unified sync for both HTTP and GRPC routes.
RouteSyncer *RouteSyncer
// contains filtered or unexported fields
}
HTTPRouteReconciler reconciles HTTPRoute resources and synchronizes them to Cloudflare Tunnel ingress configuration.
Key behaviors:
- Watches all HTTPRoute resources in the cluster
- Filters routes by parent Gateway's GatewayClass
- Uses shared RouteSyncer for unified sync with GRPCRoutes
- Updates Cloudflare Tunnel config via API (cloudflared hot-reloads)
- Updates HTTPRoute status with acceptance conditions
On startup, the reconciler performs a full sync to ensure tunnel configuration matches the current state of route resources. This means any ingress rules created outside of this controller will be replaced.
func (*HTTPRouteReconciler) SetupWithManager ¶
func (r *HTTPRouteReconciler) SetupWithManager(mgr ctrl.Manager) error
type RequestsFunc ¶ added in v0.0.4
RequestsFunc returns reconcile requests for a given context.
type RouteSyncer ¶ added in v0.8.0
type RouteSyncer struct {
client.Client
Scheme *runtime.Scheme
ClusterDomain string
GatewayClassName string
ConfigResolver *config.Resolver
// contains filtered or unexported fields
}
RouteSyncer provides unified synchronization of HTTPRoute and GRPCRoute resources to Cloudflare Tunnel configuration.
Both HTTPRouteReconciler and GRPCRouteReconciler use this to sync routes, ensuring that all route types are collected and synchronized together.
func NewRouteSyncer ¶ added in v0.8.0
func NewRouteSyncer( c client.Client, scheme *runtime.Scheme, clusterDomain string, gatewayClassName string, configResolver *config.Resolver, ) *RouteSyncer
NewRouteSyncer creates a new RouteSyncer.
func (*RouteSyncer) SyncAllRoutes ¶ added in v0.8.0
func (s *RouteSyncer) SyncAllRoutes(ctx context.Context) (ctrl.Result, *SyncResult, error)
SyncAllRoutes synchronizes all HTTPRoute and GRPCRoute resources to Cloudflare Tunnel.
type RouteUpdateFunc ¶ added in v0.8.0
RouteUpdateFunc is called to update status of individual routes after sync.
Source Files