Documentation
¶
Overview ¶
Package cloud is DockTail's optional reporting module for DockTail Cloud. It is completely inert unless DOCKTAIL_CLOUD_KEY is set: with no key, none of it runs and no connection is opened. When enabled, it subscribes to the reconciler's results, periodically self-discovers Docker services for an authoritative cloud snapshot, watches docker failure signals, runs local-vantage checks, and streams metadata to the cloud over an outbound WSS link.
The protocol is metadata-only by design (see ./proto): there are no exec/deploy/shell message types and this module never executes anything on the host. It depends only on the reconciler, the docker/tailscale clients, and the proto package — never on the proprietary cloud.
Index ¶
Constants ¶
const ( EnvKey = "DOCKTAIL_CLOUD_KEY" // EnvURL overrides the baked-in ingest endpoint (proto.DefaultEndpoint). // It is a documented local-development escape hatch, not production // customer configuration. EnvURL = "DOCKTAIL_CLOUD_URL" // EnvAllowInsecure permits an explicitly configured ws:// endpoint whose // host is not loopback. It is a development-only escape hatch. EnvAllowInsecure = "DOCKTAIL_CLOUD_ALLOW_INSECURE" EnvLogLevel = "DOCKTAIL_LOG_LEVEL" EnvCheckPeriod = "DOCKTAIL_CHECK_INTERVAL" )
Environment variables. The operator's required config is exactly one var (DOCKTAIL_CLOUD_KEY); everything else has a sane default.
const ( DefaultCheckInterval = 30 * time.Second DefaultLogLevel = "info" MinCheckInterval = time.Duration(proto.MinCheckIntervalMS) * time.Millisecond MaxCheckInterval = time.Duration(proto.MaxCheckIntervalMS) * time.Millisecond )
Defaults.
const ( LinkConnecting = "connecting" // no connection accepted yet LinkConnected = "connected" // an accepted connection is up LinkDisconnected = "disconnected" // lost the connection or cannot reach the cloud; retrying LinkRejected = "rejected" // the cloud refused the last attempt (Reason names why) )
Link states reported by Collector.LinkStatus, for DockTail's local health status (see ../health).
const EnvHostRoot = "DOCKTAIL_HOST_ROOT"
EnvHostRoot names a read-only bind mount of the HOST's filesystem root (`- /:/host:ro`), which is what makes the host's other filesystems visible from inside the agent container. It defaults to /host when that path holds a readable host mount table and is otherwise empty — the zero-configuration case, in which the agent reports only the filesystem backing its own root.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector is DockTail's cloud reporting module. It implements reconciler.Observer: it receives the reconciler's computed services and the docker event stream, maps them to wire messages, and streams them over an outbound WSS connection it manages itself. It also runs local-vantage checks and a heartbeat while connected.
func NewCollector ¶
func NewCollector(ctx context.Context, cfg Config, dc *docker.Client, ts tailnetSource, logger zerolog.Logger) (*Collector, error)
NewCollector builds a Collector, reading the host fingerprint (docker engine ID) and versions up front. Returns an error only if the engine ID can't be read — without it there is no stable host identity. ts reads the local tailscale daemon (node identity, MagicDNS name) and, when API credentials are configured, the Tailscale control plane behind the tailnet vantage; pass nil to run without any tailnet signals.
func (*Collector) Fingerprint ¶
Fingerprint is the docker engine ID used as the host identity.
func (*Collector) LinkStatus ¶
func (c *Collector) LinkStatus() LinkStatus
LinkStatus reports the current cloud connection state.
func (*Collector) OnEvent ¶
OnEvent maps a docker event to wire events and sends them, capturing a log excerpt for opted-in services on down signals.
It runs whether or not the agent is connected: with no connection the frames go to the offline spool and are replayed on the next one (see spool). A docker failure signal is not periodic state — nothing later re-derives it, so a container that dies and recovers inside a network blip would otherwise produce no incident and no alert at all.
func (*Collector) OnReconcile ¶
func (c *Collector) OnReconcile(ctx context.Context, services []*apptypes.ContainerService)
OnReconcile receives the reconciler's freshly computed services, enriches them with runtime detail, stores them, and (if connected) sends a snapshot.
func (*Collector) Run ¶
Run is the reconnect loop. It blocks until ctx is cancelled. Each iteration dials, performs the hello handshake, and (on accept) serves until the connection drops, then backs off. A rejection decides the pace (see helloRejection); a terminal one parks the collector in stopped, which keeps repeating the reason until the container restarts.
type Config ¶
type Config struct {
Key string // workspace key (dtc_...). Empty means disabled.
URL string // WSS ingest endpoint.
AllowInsecure bool // development-only non-loopback ws:// escape hatch.
LogLevel string // zerolog level name (informational; main owns logging).
CheckInterval time.Duration // how often local-vantage checks run.
}
Config is the resolved cloud-module configuration.
func LoadConfig ¶
func LoadConfig() Config
LoadConfig reads the cloud configuration from the environment, applying defaults.
func (Config) ZerologLevel ¶
ZerologLevel maps the configured level name onto a zerolog.Level.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package proto defines the wire contract between the DockTail agent (OSS, AGPL, github.com/marvinvr/docktail) and the DockTail Cloud agent-plane (proprietary).
|
Package proto defines the wire contract between the DockTail agent (OSS, AGPL, github.com/marvinvr/docktail) and the DockTail Cloud agent-plane (proprietary). |