Documentation
¶
Overview ¶
Package annotations provides annotation parsing utilities for cfgate controllers.
It centralizes annotation constants and parsing logic for consistent handling across the shipped cfgate route surface:
- HTTPRoute
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)
Callers may still require an explicit hostname override when they need one:
result := annotations.ValidateRouteAnnotations(route, 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" // Default: "http" // 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. // Deprecated: create CloudflareAccessApplication resources instead. The // HTTPRoute controller only validates and warns for this annotation; it does // not create or link Cloudflare Access resources. // Values: "name" (same namespace) or "namespace/name" // Read from: Routes AnnotationAccessPolicy = AnnotationPrefix + "access-policy" // AnnotationHostname overrides the route hostname when set. // Optional for HTTPRoute and ignored when not supported by the controller. // Values: RFC 1123 hostname // Read from: Routes AnnotationHostname = AnnotationPrefix + "hostname" )
Application-level annotations applied to Gateway API route resources.
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 ( // AnnotationAllowDeepSubdomains suppresses the warning event emitted when a hostname // has multiple subdomain levels relative to its zone (e.g., deep.sub.example.com). // Values: "true", "false" // Default: not set (warning emitted) AnnotationAllowDeepSubdomains = AnnotationPrefix + "allow-deep-subdomains" )
DNS management annotations.
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, }
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 that carries annotations.
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).
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 only when a caller wants to enforce an explicit hostname override. Returns validation result with errors and warnings.
Source Files