Documentation
¶
Overview ¶
Package tunnel provides the TunnelConfigService for managing Cloudflare Tunnel configuration. It aggregates configuration from multiple sources (Tunnel, ClusterTunnel, TunnelBinding, Ingress, Gateway) into a single CloudflareSyncState for synchronized updates.
Package tunnel provides types and service for Tunnel configuration management.
Index ¶
- Constants
- func GetSyncStateName(tunnelName string) string
- type AdoptTunnelOptions
- type CreateTunnelOptions
- type DeleteTunnelOptions
- type IngressRule
- type LifecycleAction
- type LifecycleConfig
- type LifecycleResult
- type LifecycleService
- func (s *LifecycleService) CleanupSyncState(ctx context.Context, tunnelName string) error
- func (s *LifecycleService) GetLifecycleError(ctx context.Context, tunnelName string) (string, error)
- func (s *LifecycleService) GetLifecycleResult(ctx context.Context, tunnelName string) (*LifecycleResult, error)
- func (s *LifecycleService) IsLifecycleCompleted(ctx context.Context, tunnelName string) (bool, error)
- func (s *LifecycleService) RequestAdopt(ctx context.Context, opts AdoptTunnelOptions) (string, error)
- func (s *LifecycleService) RequestCreate(ctx context.Context, opts CreateTunnelOptions) (string, error)
- func (s *LifecycleService) RequestDelete(ctx context.Context, opts DeleteTunnelOptions) (string, error)
- type OriginRequestConfig
- type RegisterRulesOptions
- type RegisterSettingsOptions
- type Service
- func (s *Service) Register(ctx context.Context, opts service.RegisterOptions) error
- func (s *Service) RegisterRules(ctx context.Context, opts RegisterRulesOptions) error
- func (s *Service) RegisterSettings(ctx context.Context, opts RegisterSettingsOptions) error
- func (s *Service) Unregister(ctx context.Context, tunnelID string, source service.Source) error
- func (s *Service) UnregisterConfig(ctx context.Context, opts service.UnregisterOptions) error
- type TunnelConfig
- type TunnelSettings
- type WarpRoutingConfig
Constants ¶
const ( ResultKeyTunnelID = "tunnelId" ResultKeyTunnelName = "tunnelName" ResultKeyTunnelToken = "tunnelToken" ResultKeyCredentials = "credentials" ResultKeyAccountTag = "accountTag" )
Result data keys for TunnelLifecycle SyncState
const ( // ResourceType is the SyncState resource type for tunnel configuration ResourceType = v1alpha2.SyncResourceTunnelConfiguration // PriorityTunnelSettings is the priority for Tunnel/ClusterTunnel settings (highest) PriorityTunnelSettings = 10 // PriorityBinding is the priority for TunnelBinding rules PriorityBinding = 50 // PriorityIngress is the priority for Ingress rules PriorityIngress = 100 // PriorityGateway is the priority for Gateway API rules PriorityGateway = 100 )
const ( // LifecycleResourceType is the SyncState resource type for tunnel lifecycle LifecycleResourceType = v1alpha2.SyncResourceTunnelLifecycle )
Variables ¶
This section is empty.
Functions ¶
func GetSyncStateName ¶ added in v0.24.0
GetSyncStateName returns the SyncState name for a tunnel
Types ¶
type AdoptTunnelOptions ¶ added in v0.24.0
type AdoptTunnelOptions struct {
// TunnelID is the ID of the tunnel to adopt
TunnelID string
// TunnelName is the expected tunnel name
TunnelName string
// AccountID is the Cloudflare account ID
AccountID string
// Source identifies the K8s resource
Source service.Source
// CredentialsRef references the CloudflareCredentials to use
CredentialsRef v1alpha2.CredentialsReference
}
AdoptTunnelOptions contains options for adopting an existing tunnel
type CreateTunnelOptions ¶ added in v0.24.0
type CreateTunnelOptions struct {
// TunnelName is the name of the tunnel to create
TunnelName string
// AccountID is the Cloudflare account ID
AccountID string
// ConfigSrc specifies the configuration source
ConfigSrc string
// Source identifies the K8s resource
Source service.Source
// CredentialsRef references the CloudflareCredentials to use
CredentialsRef v1alpha2.CredentialsReference
}
CreateTunnelOptions contains options for creating a tunnel
type DeleteTunnelOptions ¶ added in v0.24.0
type DeleteTunnelOptions struct {
// TunnelID is the ID of the tunnel to delete
TunnelID string
// TunnelName is the name of the tunnel (for SyncState naming)
TunnelName string
// AccountID is the Cloudflare account ID
AccountID string
// Source identifies the K8s resource
Source service.Source
// CredentialsRef references the CloudflareCredentials to use
CredentialsRef v1alpha2.CredentialsReference
// CleanupRoutes indicates whether to delete associated routes
CleanupRoutes bool
}
DeleteTunnelOptions contains options for deleting a tunnel
type IngressRule ¶
type IngressRule struct {
// Hostname is the public hostname for this rule (e.g., "app.example.com")
Hostname string `json:"hostname,omitempty"`
// Path is the URL path to match (e.g., "/api/*")
Path string `json:"path,omitempty"`
// Service is the backend service URL (e.g., "http://svc.ns.svc:80")
Service string `json:"service"`
// OriginRequest contains optional origin request configuration
OriginRequest *OriginRequestConfig `json:"originRequest,omitempty"`
}
IngressRule represents a single tunnel ingress rule. This is the configuration contributed by Ingress, TunnelBinding, or Gateway controllers.
type LifecycleAction ¶ added in v0.24.0
type LifecycleAction string
LifecycleAction defines the action to perform on a tunnel
const ( // LifecycleActionCreate creates a new tunnel LifecycleActionCreate LifecycleAction = "create" // LifecycleActionDelete deletes an existing tunnel LifecycleActionDelete LifecycleAction = "delete" // LifecycleActionAdopt adopts an existing tunnel LifecycleActionAdopt LifecycleAction = "adopt" )
type LifecycleConfig ¶ added in v0.24.0
type LifecycleConfig struct {
// Action is the lifecycle operation to perform
Action LifecycleAction `json:"action"`
// TunnelName is the name of the tunnel (required for create/adopt)
TunnelName string `json:"tunnelName,omitempty"`
// TunnelID is the existing tunnel ID (required for delete/adopt)
TunnelID string `json:"tunnelId,omitempty"`
// ConfigSrc specifies the configuration source (local/cloudflare)
// If "cloudflare", the tunnel uses remotely managed config
ConfigSrc string `json:"configSrc,omitempty"`
// ExistingTunnelID is the tunnel ID to adopt (for adopt action)
ExistingTunnelID string `json:"existingTunnelId,omitempty"`
}
LifecycleConfig represents the configuration for a tunnel lifecycle operation
func ParseLifecycleConfig ¶ added in v0.24.0
func ParseLifecycleConfig(raw []byte) (*LifecycleConfig, error)
ParseLifecycleConfig parses the lifecycle configuration from raw JSON
type LifecycleResult ¶ added in v0.24.0
type LifecycleResult struct {
// TunnelID is the Cloudflare tunnel ID
TunnelID string `json:"tunnelId"`
// TunnelName is the tunnel name
TunnelName string `json:"tunnelName"`
// TunnelToken is the token used by cloudflared to authenticate
TunnelToken string `json:"tunnelToken,omitempty"`
// Credentials is the base64-encoded tunnel credentials JSON
Credentials string `json:"credentials,omitempty"`
// AccountTag is the Cloudflare account tag (from credentials)
AccountTag string `json:"accountTag,omitempty"`
}
LifecycleResult contains the result of a tunnel lifecycle operation
type LifecycleService ¶ added in v0.24.0
type LifecycleService struct {
*service.BaseService
}
LifecycleService handles Tunnel lifecycle operations through SyncState. It provides methods to request tunnel creation, deletion, and adoption, which are then processed by the TunnelLifecycleSyncController.
func NewLifecycleService ¶ added in v0.24.0
func NewLifecycleService(c client.Client) *LifecycleService
NewLifecycleService creates a new TunnelLifecycleService
func (*LifecycleService) CleanupSyncState ¶ added in v0.24.0
func (s *LifecycleService) CleanupSyncState(ctx context.Context, tunnelName string) error
CleanupSyncState removes the SyncState for a tunnel after successful deletion
func (*LifecycleService) GetLifecycleError ¶ added in v0.24.0
func (s *LifecycleService) GetLifecycleError(ctx context.Context, tunnelName string) (string, error)
GetLifecycleError returns the error message if the lifecycle operation failed
func (*LifecycleService) GetLifecycleResult ¶ added in v0.24.0
func (s *LifecycleService) GetLifecycleResult(ctx context.Context, tunnelName string) (*LifecycleResult, error)
GetLifecycleResult retrieves the result of a lifecycle operation from SyncState. Returns nil if the operation hasn't completed yet.
func (*LifecycleService) IsLifecycleCompleted ¶ added in v0.24.0
func (s *LifecycleService) IsLifecycleCompleted(ctx context.Context, tunnelName string) (bool, error)
IsLifecycleCompleted checks if the lifecycle operation has completed
func (*LifecycleService) RequestAdopt ¶ added in v0.24.0
func (s *LifecycleService) RequestAdopt(ctx context.Context, opts AdoptTunnelOptions) (string, error)
RequestAdopt requests adoption of an existing tunnel. The actual adoption (fetching credentials/token) is performed by TunnelLifecycleSyncController. Returns the SyncState name that can be watched for completion.
func (*LifecycleService) RequestCreate ¶ added in v0.24.0
func (s *LifecycleService) RequestCreate(ctx context.Context, opts CreateTunnelOptions) (string, error)
RequestCreate requests creation of a new tunnel. The actual creation is performed by TunnelLifecycleSyncController. Returns the SyncState name that can be watched for completion.
func (*LifecycleService) RequestDelete ¶ added in v0.24.0
func (s *LifecycleService) RequestDelete(ctx context.Context, opts DeleteTunnelOptions) (string, error)
RequestDelete requests deletion of an existing tunnel. The actual deletion is performed by TunnelLifecycleSyncController. Returns the SyncState name that can be watched for completion.
type OriginRequestConfig ¶
type OriginRequestConfig struct {
// ConnectTimeout is the timeout for establishing a connection to origin
ConnectTimeout *time.Duration `json:"connectTimeout,omitempty"`
// TLSTimeout is the timeout for TLS handshake with origin
TLSTimeout *time.Duration `json:"tlsTimeout,omitempty"`
// TCPKeepAlive is the TCP keepalive interval
TCPKeepAlive *time.Duration `json:"tcpKeepAlive,omitempty"`
// NoHappyEyeballs disables Happy Eyeballs for IPv4/v6 fallback
NoHappyEyeballs *bool `json:"noHappyEyeballs,omitempty"`
// KeepAliveConnections is the max number of idle connections to keep open
KeepAliveConnections *int `json:"keepAliveConnections,omitempty"`
// KeepAliveTimeout is the timeout for idle connections
KeepAliveTimeout *time.Duration `json:"keepAliveTimeout,omitempty"`
// HTTPHostHeader overrides the Host header sent to origin
HTTPHostHeader *string `json:"httpHostHeader,omitempty"`
// OriginServerName overrides the hostname for TLS verification
OriginServerName *string `json:"originServerName,omitempty"`
// CAPool is the path to CA certificates for origin verification
CAPool *string `json:"caPool,omitempty"`
// NoTLSVerify disables TLS certificate verification for origin
NoTLSVerify *bool `json:"noTlsVerify,omitempty"`
// HTTP2Origin enables HTTP/2 to origin (requires HTTPS)
HTTP2Origin *bool `json:"http2Origin,omitempty"`
// DisableChunkedEncoding disables chunked transfer encoding
DisableChunkedEncoding *bool `json:"disableChunkedEncoding,omitempty"`
// BastionMode enables bastion/jump host mode
BastionMode *bool `json:"bastionMode,omitempty"`
// ProxyAddress is the address for SOCKS proxy
ProxyAddress *string `json:"proxyAddress,omitempty"`
// ProxyPort is the port for SOCKS proxy
ProxyPort *uint `json:"proxyPort,omitempty"`
// ProxyType is the proxy type (e.g., "socks")
ProxyType *string `json:"proxyType,omitempty"`
}
OriginRequestConfig contains origin request settings. These settings control how cloudflared connects to the backend service.
type RegisterRulesOptions ¶
type RegisterRulesOptions struct {
// TunnelID is the Cloudflare tunnel ID
TunnelID string
// AccountID is the Cloudflare account ID
AccountID string
// Source identifies the K8s resource contributing this configuration
Source service.Source
// Rules contains the ingress rules
Rules []IngressRule
// Priority determines conflict resolution (lower = higher priority)
Priority int
// CredentialsRef references the CloudflareCredentials to use
CredentialsRef v1alpha2.CredentialsReference
}
RegisterRulesOptions contains options for registering ingress rules.
type RegisterSettingsOptions ¶
type RegisterSettingsOptions struct {
// TunnelID is the Cloudflare tunnel ID
TunnelID string
// AccountID is the Cloudflare account ID
AccountID string
// Source identifies the K8s resource contributing this configuration
Source service.Source
// Settings contains the tunnel settings
Settings TunnelSettings
// CredentialsRef references the CloudflareCredentials to use
CredentialsRef v1alpha2.CredentialsReference
}
RegisterSettingsOptions contains options for registering tunnel settings.
type Service ¶
type Service struct {
*service.BaseService
}
Service handles Tunnel configuration registration. It implements the ConfigService interface for TunnelConfiguration resources.
func NewService ¶
NewService creates a new TunnelConfigService
func (*Service) Register ¶
Register implements the ConfigService interface. It routes to RegisterSettings or RegisterRules based on the config type.
func (*Service) RegisterRules ¶
func (s *Service) RegisterRules(ctx context.Context, opts RegisterRulesOptions) error
RegisterRules registers ingress rules from an Ingress, TunnelBinding, or Gateway controller. Rules from multiple sources are aggregated by the SyncController before syncing to Cloudflare.
func (*Service) RegisterSettings ¶
func (s *Service) RegisterSettings(ctx context.Context, opts RegisterSettingsOptions) error
RegisterSettings registers tunnel settings from a Tunnel or ClusterTunnel controller. Settings include warp routing, fallback target, and global origin request config. These have the highest priority and override settings from other sources.
func (*Service) Unregister ¶
Unregister removes a source's configuration from the SyncState. This is called when the source K8s resource is deleted. If no sources remain, the SyncState is also deleted.
func (*Service) UnregisterConfig ¶
Unregister implements the ConfigService interface.
type TunnelConfig ¶
type TunnelConfig struct {
// Settings contains tunnel-level settings (only from Tunnel/ClusterTunnel)
Settings *TunnelSettings `json:"settings,omitempty"`
// Rules contains ingress rules (from Ingress, TunnelBinding, Gateway)
Rules []IngressRule `json:"rules,omitempty"`
}
TunnelConfig represents the complete configuration from a single source. Each K8s resource (Tunnel, Ingress, TunnelBinding, Gateway) contributes a TunnelConfig to the SyncState.
type TunnelSettings ¶
type TunnelSettings struct {
// WarpRouting controls whether WARP routing is enabled
WarpRouting *WarpRoutingConfig `json:"warpRouting,omitempty"`
// FallbackTarget is the service URL for unmatched requests (e.g., "http_status:404")
FallbackTarget string `json:"fallbackTarget,omitempty"`
// GlobalOriginRequest contains global origin request settings
GlobalOriginRequest *OriginRequestConfig `json:"globalOriginRequest,omitempty"`
}
TunnelSettings contains tunnel-level settings. These are provided by Tunnel/ClusterTunnel controllers and have highest priority.
type WarpRoutingConfig ¶
type WarpRoutingConfig struct {
// Enabled controls whether WARP routing is enabled
Enabled bool `json:"enabled"`
}
WarpRoutingConfig controls WARP routing settings.