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 ParseNamespacedName(ref string, defaultNS string) (string, string, error)
- 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" // AnnotationOriginH2c enables HTTP/2 cleartext (h2c) to origin. // Values: "true", "false" // Default: "false" AnnotationOriginH2c = AnnotationPrefix + "origin-h2c" )
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") ErrInvalidNamespacedName = errors.New("invalid namespaced name format") ErrEmptyNamespacedNameSegment = errors.New("empty segment in namespaced name") )
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 ParseNamespacedName ¶
ParseNamespacedName parses a reference in "namespace/name" or "name" format. Returns (namespace, name, nil) on success. If ref contains no slash, defaultNS is used as the namespace. Returns an error if ref is empty, contains more than one slash, or has empty segments.
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
// H2c enables HTTP/2 cleartext (h2c) to origin.
H2c 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