tunnel

package
v0.27.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 19, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

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

View Source
const (
	ResultKeyTunnelID    = "tunnelId"
	ResultKeyTunnelName  = "tunnelName"
	ResultKeyTunnelToken = "tunnelToken"
	ResultKeyCredentials = "credentials"
	ResultKeyAccountTag  = "accountTag"
)

Result data keys for TunnelLifecycle SyncState

View Source
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
)
View Source
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

func GetSyncStateName(tunnelName string) string

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

func NewService(c client.Client) *Service

NewService creates a new TunnelConfigService

func (*Service) Register

func (s *Service) Register(ctx context.Context, opts service.RegisterOptions) error

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

func (s *Service) Unregister(ctx context.Context, tunnelID string, source service.Source) error

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

func (s *Service) UnregisterConfig(ctx context.Context, opts service.UnregisterOptions) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL