tunnel

package
v0.42.5 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package tunnel reaches a service inside a cluster over an SSH connection to one of its nodes.

It exists because the services cargoship wants to talk to are frequently not addressable from the machine cargoship runs on. A registry a Zarf deployment stands up records a NodePort or a per-node host port -- an address only a node can reach -- and docs/agent/choice-removed-hosts.md records the repository's position that a cluster whose firewall admits only SSH from outside is an ordinary cargoship deployment. The SSH connection is therefore the one route that can be relied on, and an SSH direct-tcpip channel turns it into a route for arbitrary TCP.

What this deliberately is not is a Kubernetes port-forward, and the reason is the API port rather than the dependency. A port-forward needs the API server reachable, which on a fleet whose firewall admits port 22 and nothing else is the problem rather than the solution.

The dependency half of that argument no longer holds, and pkg/kubetunnel is the port-forward this paragraph used to rule out: k8s.io/client-go/tools/portforward does cost 3.34MiB for its import of k8s.io/api/core/v1, but hand-writing the channel protocol over client-go/transport/websocket costs 132KiB and links no API group. The two packages are both here because they answer different situations -- this one is the only route into an air-gapped fleet, and kubetunnel is the only route into a cluster whose nodes have no sshd at all, which is every k3d, kind and Talos cluster. See docs/agent/choice-dynamic-kube-client.md for the measurements.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoSSH = errors.New("host has no ssh configuration to tunnel through")

ErrNoSSH marks a host that cannot carry a tunnel. It is a distinct error because the cause is always the inventory rather than the network, and the remedy is to configure the host with an `ssh:` block.

Functions

This section is empty.

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is an SSH connection to a node, able to reach any number of services inside the cluster through it. One connection serves them all: a mirror reaches both the Kubernetes API, to read where the registry is, and the registry itself, without authenticating twice.

func Open

func Open(ctx context.Context, cfg *ssh.Config) (*Conn, error)

Open connects to the host cfg describes.

The connection is a second one to the host rather than the live one a phase may already be holding: rig keeps its protocol connection unexported with no accessor (rig/v2/client.go:55), so there is nothing to borrow. Close releases it.

func (*Conn) Address

func (c *Conn) Address() string

Address is the host this connection reaches, for logging.

func (*Conn) Close

func (c *Conn) Close()

Close releases the SSH connection, and with it every connection opened through any Dialer it handed out.

func (*Conn) To

func (c *Conn) To(service string) (*Dialer, error)

To returns a Dialer that reaches service over this connection. service is an address as the node sees it, so "127.0.0.1:31999" for a NodePort.

type Dialer

type Dialer struct {
	// contains filtered or unexported fields
}

Dialer opens connections to one service address inside a cluster, carrying each over an SSH channel to a node.

A Dialer is bound to a single service address, and DialContext sends every connection there regardless of the address it is asked for. That redirection is the whole point rather than a quirk: it is what lets a name be decided separately from the route taken to reach it -- the reference an image is pushed under, or the hostname a server certificate is validated against.

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, network, _ string) (net.Conn, error)

DialContext opens one connection to the Dialer's service address over the SSH channel.

The address it is handed is ignored, by design -- see Dialer. The signature is the one http.Transport.DialContext takes, which is how this reaches an OCI client: see images.ClientOptions.DialContext.

func (*Dialer) Service

func (d *Dialer) Service() string

Service is the address inside the cluster this Dialer reaches, for logging.

Jump to

Keyboard shortcuts

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