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 ¶
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 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
// ClusterDomain is used for building service URLs (e.g., "cluster.local").
ClusterDomain string
// GatewayClassName filters which routes to process.
GatewayClassName string
// ControllerName is reported in HTTPRoute status.
ControllerName string
// ConfigResolver resolves configuration from GatewayClassConfig.
ConfigResolver *config.Resolver
// 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
- Reads configuration from GatewayClassConfig via parametersRef
- Performs full synchronization on any route change (not incremental)
- 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 HTTPRoute 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