Documentation
¶
Overview ¶
Package tailscale runs and supervises tailscaled for each endpoint.
Index ¶
- Constants
- func BundledBinaries() (string, string, error)
- func CertNotAfter(path string) (time.Time, error)
- func CheckAuthKeyMatch(stateDir, authKey string) bool
- func ClearEphemeral(stateDir string) error
- func IsMarkedEphemeral(stateDir string) bool
- func KeyEphemeral(key string) (bool, bool, error)
- func LinkCertsDir(stateDir, shared, parent string) error
- func LogoutState(ctx context.Context, tailscaledBin, stateDir, socket string) error
- func MarkEphemeral(stateDir string) error
- func SaveAuthKeyHash(stateDir, authKey string) error
- func ServiceNames(services []Service) []string
- func StateExists(stateDir string) bool
- func WipeState(stateDir string) error
- type DaemonConfig
- type DaemonSupervisor
- func (s *DaemonSupervisor) Drain() error
- func (s *DaemonSupervisor) DrainAndWait()
- func (s *DaemonSupervisor) Drained() bool
- func (s *DaemonSupervisor) Logout() error
- func (s *DaemonSupervisor) NeedsDrain() bool
- func (s *DaemonSupervisor) Readiness(ctx context.Context) ReadinessReport
- func (s *DaemonSupervisor) Start() error
- func (s *DaemonSupervisor) StartContext(ctx context.Context) error
- func (s *DaemonSupervisor) Status() (SupervisorStatus, int)
- func (s *DaemonSupervisor) Stop() error
- func (s *DaemonSupervisor) WaitForIP(ctx context.Context) (*Status, error)
- type Readiness
- type ReadinessReport
- type ServeEndpoint
- type Service
- type Status
- type SupervisorStatus
Constants ¶
const BundledVersion = "bundled"
BundledVersion is the only supported TS_VERSION: the Tailscale shipped in the plugin image.
const WireGuardPort = 41641
WireGuardPort is the UDP port every tslink tailscaled listens on, each in its container's namespace. The host lets only this port through between tslink's veths (netutil.SetupVethIsolation), so colocated nodes keep a direct path while containers cannot reach each other's other ports.
Variables ¶
This section is empty.
Functions ¶
func BundledBinaries ¶
BundledBinaries returns the paths of the tailscale and tailscaled binaries shipped in the plugin image, so every node runs the same version.
func CertNotAfter ¶
CertNotAfter returns the expiry of the first certificate in a PEM file.
func CheckAuthKeyMatch ¶
CheckAuthKeyMatch checks if the provided auth key matches the stored hash. Returns true if they match or if no hash is stored (new state). Returns false if they don't match (auth key changed).
func ClearEphemeral ¶
ClearEphemeral removes the mark MarkEphemeral set, if any, when stateDir is used by a network whose nodes are not ephemeral.
func IsMarkedEphemeral ¶
IsMarkedEphemeral reports whether stateDir was marked by MarkEphemeral.
func KeyEphemeral ¶ added in v0.2.4
KeyEphemeral reports whether a node registered with key is ephemeral, as far as the key itself says, and whether it says so in an ephemeral attribute. OAuth client secrets register ephemeral nodes unless "?ephemeral=false" is appended; an auth key's ephemerality is set when it is created and cannot be read from it, so it counts as not ephemeral. tailscale up reads attributes only from OAuth client secrets and passes any other key on unchanged, so an attribute appended to an auth key means nothing. The error is that of an OAuth client secret with invalid attributes.
func LinkCertsDir ¶
LinkCertsDir makes the state directory's certs directory a link to shared, creating shared and an ACME account key in it: parent's, if shared is a stack's directory in parent and parent has one. A link elsewhere, as to the shared directory before stacks had their own, is pointed at shared. A certs directory that is not a link, as kept by a non-ephemeral node from before, is left alone. An empty shared leaves tailscaled its own directory.
func LogoutState ¶
LogoutState logs out the node whose state is in stateDir, which deletes an ephemeral node from the tailnet and frees its name, for a node whose container is gone. tailscaled runs on a copy of the state that logoutState sanitized, with userspace networking and its socket at socket, so the node does not come up: it contacts control only to log out. A state without a registered node is nothing to log out.
func MarkEphemeral ¶
MarkEphemeral marks stateDir as holding an ephemeral node.
func SaveAuthKeyHash ¶
SaveAuthKeyHash stores the SHA256 hash of the auth key in the state directory.
func ServiceNames ¶ added in v0.3.5
ServiceNames returns the names of services.
func StateExists ¶
StateExists checks if valid Tailscale state exists in the given directory. Returns true if tailscaled.state file exists and is non-empty.
Types ¶
type DaemonConfig ¶
type DaemonConfig struct {
EndpointID string
StateDir string
SocketPath string // tailscaled socket; defaults to <StateDir>/tailscaled.sock
Hostname string
AuthKey func() (string, error) // Read at each login, so a replaced credential takes effect
CertsDir string // Shared certificate directory; empty for tailscaled's own
NetNSPath string
TailscaledBin string // Path to tailscaled daemon binary
Tags []string // ACL tags for --advertise-tags
Services []Service // Services the node is a backend of, sorted by name
Endpoints []ServeEndpoint // What direct serve serves on the node's own name
Direct bool // Enable direct machine serve (HTTPS on machine hostname)
LoginServer string // Control server URL for --login-server; empty for Tailscale's
ContainerDNS []netip.Addr // DNS servers the container was given, as with docker run --dns
// HostEndpoints returns the endpoints on the host tailscaled advertises
// besides its own (netutil.HostEndpoints); nil for none. Read when
// tailscaled starts, as tailscaled reads them only then, and again by the
// supervisor every hostEndpointsCheckInterval, to detect a change and
// restart tailscaled with the new value.
HostEndpoints func() ([]netip.AddrPort, error)
// Warn records a warning in the endpoint's status under key, or clears it
// if message is empty; nil ignores warnings
Warn func(key, message string)
// ParentCertsDir is the shared certificate directory when CertsDir is a
// stack's directory in it: its ACME account key and the certificates it
// held before stacks had directories of their own are adopted. Empty for
// none.
ParentCertsDir string
// contains filtered or unexported fields
}
DaemonConfig holds configuration for a tailscaled instance.
type DaemonSupervisor ¶
type DaemonSupervisor struct {
// contains filtered or unexported fields
}
DaemonSupervisor manages a Daemon with automatic restart on failure.
func NewDaemonSupervisor ¶
func NewDaemonSupervisor(cfg DaemonConfig) *DaemonSupervisor
NewDaemonSupervisor creates a new supervisor for managing a tailscaled daemon.
func (*DaemonSupervisor) Drain ¶
func (s *DaemonSupervisor) Drain() error
Drain stops new connections to the node's Service backends. They stay drained, even if tailscaled is down and the drain fails: a daemon the supervisor starts later does not advertise them.
func (*DaemonSupervisor) DrainAndWait ¶
func (s *DaemonSupervisor) DrainAndWait()
DrainAndWait drains the node's Service backends, unless that was done, as when the container got its stop signal, and waits for control to learn of it: until control fetched the drained Service list, at least drainAckFloor and at most drainAckTimeout after the drain. A backend never advertised has nothing for control to fetch, and is not waited for. A drain that found nothing advertised waits instead for the removal of Services the container does not name, if there was one.
func (*DaemonSupervisor) Drained ¶
func (s *DaemonSupervisor) Drained() bool
Drained reports whether the node's Service backend has been drained.
func (*DaemonSupervisor) Logout ¶
func (s *DaemonSupervisor) Logout() error
Logout logs the running daemon's node out.
func (*DaemonSupervisor) NeedsDrain ¶ added in v0.3.5
func (s *DaemonSupervisor) NeedsDrain() bool
NeedsDrain reports whether the node may advertise a Service, or did so recently: its container names one, or Services it does not name were removed at start or could not be. Such a node is drained before it goes.
func (*DaemonSupervisor) Readiness ¶
func (s *DaemonSupervisor) Readiness(ctx context.Context) ReadinessReport
Readiness reports how far the node is from serving what its container asks for. A daemon not started, or restarting, is starting.
func (*DaemonSupervisor) Start ¶
func (s *DaemonSupervisor) Start() error
Start begins the supervision loop and waits for initial daemon startup. Returns error if the initial startup fails.
func (*DaemonSupervisor) StartContext ¶ added in v0.2.1
func (s *DaemonSupervisor) StartContext(ctx context.Context) error
StartContext is Start, but cancelling ctx before the initial startup succeeded, as the endpoint leaving does, stops the supervisor and aborts a daemon start in progress, its login included. Once started, the supervisor no longer depends on ctx. The caller still calls Stop after an error.
func (*DaemonSupervisor) Status ¶
func (s *DaemonSupervisor) Status() (SupervisorStatus, int)
Status returns the current supervisor status and restart count.
func (*DaemonSupervisor) Stop ¶
func (s *DaemonSupervisor) Stop() error
Stop gracefully stops the supervisor and daemon.
type Readiness ¶
type Readiness string
Readiness is how far a node is from serving what its container asks for.
const ( ReadyStarting Readiness = "starting" // tailscaled is not up yet ReadyFailed Readiness = "failed" // starting failed for good ReadyLoggedOut Readiness = "logged-out" // the node needs a login ReadyServingPending Readiness = "serving-pending" // the tslink.serve.* config is not applied ReadyCertificatePending Readiness = "certificate-pending" // the Service waits for its certificate ReadyPortsUncovered Readiness = "ports-uncovered" // the Service defines ports not served ReadyAwaitingApproval Readiness = "awaiting-approval" // control has not approved the backend ReadyAwaitingControl Readiness = "awaiting-control" // control has not fetched the Services ReadyDrained Readiness = "drained" // the backend is drained, or the container leaving Ready Readiness = "ready" )
The readiness states, from a node not started to one serving all it should.
type ReadinessReport ¶ added in v0.3.5
type ReadinessReport struct {
State Readiness
Services map[string]Readiness // By Service name; nil without Services
}
ReadinessReport is how far a node is from serving what its container asks for, and how far each of its Services is.
type ServeEndpoint ¶
type ServeEndpoint struct {
Proto string // http, https, tcp, tls-terminated-tcp, tun
Port string // External port Tailscale exposes
Target string // Container port or address to forward to
Path string // L7 only - path prefix (e.g., "/api")
ProxyProtocol string // L4 only - PROXY protocol version sent to the target ("1", "2" or "")
AcceptAppCaps string // L7 only - comma-separated app capabilities forwarded to the target
}
ServeEndpoint represents a single Tailscale serve configuration. Configured via labels like: tslink.serve.443=https:8080/api.
type Service ¶ added in v0.3.5
type Service struct {
Name string // With the svc: prefix, e.g. "svc:web"
Endpoints []ServeEndpoint // What the node serves for it
}
Service is a Tailscale Service the container is a backend of, and what it serves on it.
type SupervisorStatus ¶
type SupervisorStatus string
SupervisorStatus represents the current state of the supervisor.
const ( StatusStopped SupervisorStatus = "stopped" StatusStarting SupervisorStatus = "starting" StatusRunning SupervisorStatus = "running" StatusFailed SupervisorStatus = "failed" StatusCrashLoop SupervisorStatus = "crash_loop" )
Supervisor states.