Documentation
¶
Overview ¶
Package annotations provides annotation parsing utilities for cfgate controllers.
It centralizes annotation constants and parsing logic for consistent handling across all cfgate route controllers:
- HTTPRoute
- TCPRoute
- UDPRoute
- GRPCRoute
Annotation placement follows Gateway API semantics per external-dns patterns:
- Infrastructure-level annotations (tunnel target) go on Gateway/CloudflareTunnel
- Application-level annotations (protocol, ttl, proxied) go on Routes
The package provides:
- Constants for all cfgate annotation keys
- Parsing functions with sensible defaults (GetAnnotation, GetAnnotationBool, etc.)
- Validation functions for user feedback (ValidateOriginProtocol, ValidateTTL, etc.)
- ValidationResult aggregation for route validation
Example usage:
protocol := annotations.GetAnnotation(route, annotations.AnnotationOriginProtocol)
if err := annotations.ValidateOriginProtocol(protocol); err != nil {
log.Info("invalid protocol", "error", err.Error())
}
sslVerify := annotations.GetAnnotationBool(route, annotations.AnnotationOriginSSLVerify, true)
timeout := annotations.GetAnnotationDuration(route, annotations.AnnotationOriginConnectTimeout, 30*time.Second)
TCPRoute and UDPRoute require the hostname annotation since Gateway API has no spec.hostnames field for L4 routes:
result := annotations.ValidateRouteAnnotations(tcpRoute, true) // requireHostname=true
if !result.Valid {
// Handle validation errors
}
Index ¶
- Constants
- Variables
- func GetAnnotation(obj client.Object, key string) string
- func GetAnnotationBool(obj client.Object, key string, defaultValue bool) bool
- func GetAnnotationDuration(obj client.Object, key string, defaultValue time.Duration) time.Duration
- func GetAnnotationInt(obj client.Object, key string, defaultValue int) int
- func ValidateHostname(value string) error
- func ValidateOriginProtocol(value string) error
- func ValidateTTL(value string) error
- type DNSConfig
- type OriginConfig
- type ValidationResult
Constants ¶
const ( // AnnotationTunnelTarget specifies the tunnel endpoint. // Example: "uuid.cfargotunnel.com" // Read from: Gateway, CloudflareTunnel AnnotationTunnelTarget = AnnotationPrefix + "tunnel-target" // AnnotationTunnelRef references the CloudflareTunnel resource. // Format: "namespace/name" or "name" (same namespace) // Read from: Gateway AnnotationTunnelRef = AnnotationPrefix + "tunnel-ref" )
Infrastructure-level annotations (CloudflareTunnel/Gateway).
const ( // AnnotationOriginProtocol specifies the origin protocol. // Values: "http", "https", "tcp", "udp" // Default: "http" for HTTPRoute, "tcp" for TCPRoute, "udp" for UDPRoute // Read from: Routes AnnotationOriginProtocol = AnnotationPrefix + "origin-protocol" // AnnotationOriginSSLVerify enables/disables SSL certificate verification. // Values: "true", "false" // Default: "true" // Read from: Routes AnnotationOriginSSLVerify = AnnotationPrefix + "origin-ssl-verify" // AnnotationTTL specifies the DNS record TTL in seconds. // Values: "1" to "86400" (1 second to 24 hours) // Special: "1" means "auto" (Cloudflare managed) // Default: "1" (auto) // Read from: Routes AnnotationTTL = AnnotationPrefix + "ttl" // AnnotationCloudflareProxied enables/disables Cloudflare proxy (orange cloud). // Values: "true", "false" // Default: "true" // Read from: Routes AnnotationCloudflareProxied = AnnotationPrefix + "cloudflare-proxied" // AnnotationAccessPolicy references a CloudflareAccessPolicy. // Values: "name" (same namespace) or "namespace/name" // Read from: Routes AnnotationAccessPolicy = AnnotationPrefix + "access-policy" // AnnotationHostname specifies the hostname for routes without spec.hostnames. // REQUIRED for TCPRoute and UDPRoute (Gateway API has no hostnames field for these). // Optional for HTTPRoute/GRPCRoute (overrides spec.hostnames). // Values: RFC 1123 hostname // Read from: Routes AnnotationHostname = AnnotationPrefix + "hostname" )
Application-level annotations (HTTPRoute/TCPRoute/UDPRoute/GRPCRoute).
const ( // AnnotationOriginConnectTimeout specifies origin connection timeout. // Values: duration string (e.g., "30s", "1m") // Default: "30s" AnnotationOriginConnectTimeout = AnnotationPrefix + "origin-connect-timeout" // AnnotationOriginHTTPHostHeader overrides the Host header sent to origin. // Values: hostname string AnnotationOriginHTTPHostHeader = AnnotationPrefix + "origin-http-host-header" // AnnotationOriginServerName specifies the TLS SNI server name. // Values: hostname string AnnotationOriginServerName = AnnotationPrefix + "origin-server-name" // AnnotationOriginCAPool specifies path to CA certificate pool. // Values: file path string AnnotationOriginCAPool = AnnotationPrefix + "origin-ca-pool" // AnnotationOriginHTTP2 enables HTTP/2 to origin. // Values: "true", "false" // Default: "false" AnnotationOriginHTTP2 = AnnotationPrefix + "origin-http2" )
Origin configuration annotations (processed by cloudflared-builder).
const ( // MaxTTL is the maximum allowed TTL value in seconds. MaxTTL = 86400 // MinTTL is the minimum allowed TTL value in seconds. // Value 1 is special (Cloudflare auto TTL). MinTTL = 1 // MaxHostnameLength is the maximum length of a hostname per RFC 1123. MaxHostnameLength = 253 // MaxLabelLength is the maximum length of a DNS label per RFC 1123. MaxLabelLength = 63 )
Validation constants.
const AnnotationPrefix = "cfgate.io/"
AnnotationPrefix is the prefix for all cfgate annotations.
Variables ¶
var ( ErrMissingHostnameAnnotation = errors.New("missing required hostname annotation") ErrInvalidHostnameFormat = errors.New("invalid hostname format") ErrInvalidProtocol = errors.New("invalid origin protocol") ErrInvalidTTL = errors.New("invalid TTL value") ErrMissingTunnelRef = errors.New("missing tunnel reference annotation") ErrInvalidTunnelRefFormat = errors.New("invalid tunnel reference format") )
Standard errors for annotation validation.
var ValidOriginProtocols = map[string]bool{ "http": true, "https": true, "tcp": true, "udp": true, }
ValidOriginProtocols defines the allowed origin protocol values.
Functions ¶
func GetAnnotation ¶
GetAnnotation retrieves an annotation value from an object's metadata. Returns empty string if annotation not present or object is nil. Works with any client.Object (HTTPRoute, TCPRoute, Gateway, etc.).
func GetAnnotationBool ¶
GetAnnotationBool parses a boolean annotation value. Returns defaultValue if annotation not present or not a valid boolean. Accepts: "true", "false", "1", "0", "yes", "no" (case-insensitive)
func GetAnnotationDuration ¶
GetAnnotationDuration parses a duration annotation value. Returns defaultValue if annotation not present or not a valid duration. Accepts Go duration strings: "30s", "5m", "1h30m"
func GetAnnotationInt ¶
GetAnnotationInt parses an integer annotation value. Returns defaultValue if annotation not present or not a valid integer.
func ValidateHostname ¶
ValidateHostname validates a hostname annotation value. Returns error if hostname format is invalid per RFC 1123. Empty value returns an error (use requireHostname=false in ValidateRouteAnnotations to allow empty hostnames).
func ValidateOriginProtocol ¶
ValidateOriginProtocol validates the origin protocol annotation value. Returns error if value is not a valid protocol. Empty value is valid (will use default).
func ValidateTTL ¶
ValidateTTL validates the TTL annotation value. Returns error if value is not a valid TTL (1-86400 seconds). Empty value is valid (will use default).
Types ¶
type DNSConfig ¶
type DNSConfig struct {
// TTL is the DNS record TTL in seconds.
// Value 1 means Cloudflare auto TTL.
TTL int
// Proxied enables Cloudflare proxy (orange cloud).
Proxied bool
}
DNSConfig represents the parsed DNS configuration from route annotations.
func ParseDNSConfig ¶
ParseDNSConfig extracts DNS configuration from route annotations.
type OriginConfig ¶
type OriginConfig struct {
// Protocol is the origin protocol (http, https, tcp, udp).
Protocol string
// SSLVerify enables/disables SSL certificate verification.
SSLVerify bool
// ConnectTimeout is the origin connection timeout.
ConnectTimeout time.Duration
// HTTPHostHeader overrides the Host header sent to origin.
HTTPHostHeader string
// ServerName specifies the TLS SNI server name.
ServerName string
// CAPool specifies path to CA certificate pool.
CAPool string
// HTTP2 enables HTTP/2 to origin.
HTTP2 bool
}
OriginConfig represents the parsed origin configuration from route annotations.
func ParseOriginConfig ¶
func ParseOriginConfig(obj client.Object, defaultProtocol string) OriginConfig
ParseOriginConfig extracts origin configuration from route annotations. Uses sensible defaults when annotations are not present.
type ValidationResult ¶
type ValidationResult struct {
// Valid indicates whether all validations passed.
Valid bool
// Errors contains validation error messages.
Errors []string
// Warnings contains non-fatal warning messages (e.g., deprecated annotations).
Warnings []string
}
ValidationResult holds the result of annotation validation.
func ValidateRouteAnnotations ¶
func ValidateRouteAnnotations(obj client.Object, requireHostname bool) ValidationResult
ValidateRouteAnnotations validates all cfgate annotations on a route object. Set requireHostname=true for TCPRoute/UDPRoute (no spec.hostnames in Gateway API). Returns validation result with errors and warnings.
Source Files