mesh

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2026 License: GPL-3.0, LGPL-3.0 Imports: 21 Imported by: 0

Documentation

Overview

Package mesh manages the global infrastructure shared across all sind clusters.

Index

Constants

View Source 
const (
	NetworkName      docker.NetworkName   = "sind-mesh"
	DNSContainerName docker.ContainerName = "sind-dns"
	SSHContainerName docker.ContainerName = "sind-ssh"
	SSHVolumeName    docker.VolumeName    = "sind-ssh-config"
)

Default-realm resource names. Production code uses Manager methods; these constants are used in tests as expected values for DefaultRealm.

View Source 
const DNSImage = "coredns/coredns:1.14.7"

DNSImage is the container image used for the mesh DNS server, a pinned CoreDNS release.

View Source 
const DefaultRealm = "sind"

DefaultRealm is the realm name that produces the standard resource names.

View Source 
const LabelDNSIP = "sind.dns.ip"

LabelDNSIP is the label of a mesh network that records the address its DNS container is pinned to (see EnsureMeshNetwork). Meshes created by earlier sind versions lack it: their DNS container gets an address from Docker each time it starts.

View Source 
const LabelRealm = "sind.realm"

LabelRealm is the Docker label applied to mesh resources (network, volumes) so realm-scoped listings can filter by label rather than by name prefix. pkg/cluster defines the same constant for cluster-scoped resources; keeping it local here avoids a pkg/mesh → pkg/cluster import.

Variables

This section is empty.

Functions

func SSHImage 

func SSHImage() string

SSHImage returns the container image of the SSH relay: sind's default node image, which has an ssh client and bash, and which the default cluster pulls anyway. Custom node images need not have an ssh client.

Types

type DNSRecord 

type DNSRecord struct {
	Hostname string `json:"hostname"`
	IP       string `json:"ip"`
}

DNSRecord represents a single A record in the mesh DNS.

type Info added in v0.9.0 

type Info struct {
	Network      string `json:"network"`
	DNSContainer string `json:"dns_container"`
	DNSIP        string `json:"dns_ip"`
	DNSZone      string `json:"dns_zone"`
	DNSImage     string `json:"dns_image"`
	SSHContainer string `json:"ssh_container"`
	SSHVolume    string `json:"ssh_volume"`
	SSHImage     string `json:"ssh_image"`
}

Info holds information about the mesh infrastructure for a realm.

type KnownHostEntry added in v0.9.0 

type KnownHostEntry struct {
	Hostname string
	HostKey  string
}

KnownHostEntry holds a hostname and its SSH host key for batch registration.

type Manager 

type Manager struct {
	Docker  *docker.Client
	Exec    cmdexec.Executor // executor for non-docker system commands (systemctl, resolvectl, etc.)
	Realm   string
	Pull    bool // force fresh image pull (--pull always)
	HostDNS bool // configure host DNS resolution via systemd-resolved

	// OnWarning receives warnings meant for the user, such as a mesh DNS
	// address that containers created earlier no longer use. The sind CLI
	// prints them to stderr. Without it, Warn logs them at warn level.
	OnWarning func(msg string)
	// contains filtered or unexported fields
}

Manager handles global infrastructure resources shared across all clusters.

func NewManager 

func NewManager(docker *docker.Client, realm string) *Manager

NewManager returns a Manager that operates on global resources through the given docker client. The realm determines resource naming: realm "sind" produces names like "sind-mesh", "sind-dns", etc.

func (*Manager) AddDNSRecord 

func (m *Manager) AddDNSRecord(ctx context.Context, hostname, ip string) error

AddDNSRecord adds an A record to the mesh DNS Corefile and reloads CoreDNS. The hostname should be a fully qualified sind DNS name (e.g. "controller.dev.sind.sind"). An existing entry for the hostname is replaced, as AddDNSRecords does.

func (*Manager) AddDNSRecords added in v0.9.0 

func (m *Manager) AddDNSRecords(ctx context.Context, records []DNSRecord) error

AddDNSRecords adds multiple A records to the mesh DNS Corefile and reloads CoreDNS once. Existing entries for the same hostnames are replaced, making the operation idempotent on retry.

func (*Manager) AddKnownHost 

func (m *Manager) AddKnownHost(ctx context.Context, hostname, hostKey string) error

AddKnownHost adds a host key entry to the known_hosts file in the SSH container, replacing an existing entry for the hostname, as AddKnownHosts does. The hostKey should be the full key type and data (e.g. "ssh-ed25519 AAAA...").

func (*Manager) AddKnownHosts added in v0.9.0 

func (m *Manager) AddKnownHosts(ctx context.Context, entries []KnownHostEntry) error

AddKnownHosts adds host key entries to the known_hosts file. Existing entries for the same hostnames are replaced, making the operation idempotent on retry.

func (*Manager) CleanupMesh 

func (m *Manager) CleanupMesh(ctx context.Context) error

CleanupMesh removes all global infrastructure resources. This should only be called when the last cluster is deleted.

func (*Manager) ComposeProject 

func (m *Manager) ComposeProject() string

ComposeProject returns the Docker Compose project name for this realm's mesh.

func (*Manager) Created added in v0.6.0 

func (m *Manager) Created() bool

Created reports whether the last EnsureMesh (or EnsureMeshNetwork) call created the mesh network, that is, the realm had no mesh before. Callers use it to decide whether to remove the mesh again when a create fails. A Manager can serve several creates, so they must still check that no cluster uses the mesh before they remove it.

func (*Manager) DNSContainerName 

func (m *Manager) DNSContainerName() docker.ContainerName

DNSContainerName returns the DNS container name for this realm.

func (*Manager) DNSPolkitAuthorized added in v0.5.0 

func (m *Manager) DNSPolkitAuthorized(ctx context.Context) bool

DNSPolkitAuthorized checks if the current process can configure per-link DNS without interactive authentication.

func (*Manager) EnsureMesh 

func (m *Manager) EnsureMesh(ctx context.Context) error

EnsureMesh creates the global infrastructure resources (mesh network, DNS, SSH volume, SSH container) that do not exist yet, and starts the DNS and SSH containers when they exist but are stopped, as after a host reboot or a Docker daemon restart. 

network ┬→ DNS ────┬→ SSH relay → host DNS
        └→ volume ─┘

The DNS container starts before the relay, which resolves through it.

func (*Manager) EnsureMeshNetwork 

func (m *Manager) EnsureMeshNetwork(ctx context.Context) error

EnsureMeshNetwork creates the shared mesh network if it does not already exist, and records in Created whether it did.

A new mesh network pins the address of the DNS container, which every node and the relay get as their --dns: Docker does not keep a stopped container's address, so after a host reboot a container that starts before the DNS container could take it. Docker accepts a fixed address (--ip) only on a network with a user-configured subnet. EnsureMeshNetwork therefore creates the network without one, so that Docker picks a subnet from its default address pools that avoids the other networks and the host's routes, removes it, and creates it again with that subnet and gateway and the --ip-range that pinnedLayout derives, recording the DNS address in the LabelDNSIP label. When another network takes the subnet in between, it starts over with the subnet Docker picks next, up to meshSubnetAttempts times. A subnet too small for the layout, or no attempt left, leaves the network without a pinned address, as earlier sind versions created it.

A client of the same Docker daemon that does not hold the realm's lock on the daemon (state.LockRealm with LockOptions.Client), such as a library caller, can create the network between the check and the create. Docker's "already exists" error then counts as an existing network, so that the caller's failure handling never removes it.

func (*Manager) GetDNSRecords 

func (m *Manager) GetDNSRecords(ctx context.Context) ([]DNSRecord, error)

GetDNSRecords returns all A records currently served by the mesh DNS.

func (*Manager) GetInfo added in v0.9.0 

func (m *Manager) GetInfo(ctx context.Context) (*Info, error)

GetInfo returns information about the mesh infrastructure for this realm: the DNS container's address (empty while it is stopped) and the images the DNS and SSH containers run (empty without an SSH container). Returns an error containing "no mesh found for realm" if the DNS container does not exist.

func (*Manager) GetSSHKnownHosts added in v0.9.0 

func (m *Manager) GetSSHKnownHosts(ctx context.Context) (string, error)

GetSSHKnownHosts reads the known_hosts file from the SSH container.

func (*Manager) GetSSHPrivateKey added in v0.9.0 

func (m *Manager) GetSSHPrivateKey(ctx context.Context) (string, error)

GetSSHPrivateKey reads the SSH private key from the SSH container.

func (*Manager) GetSSHPublicKey added in v0.9.0 

func (m *Manager) GetSSHPublicKey(ctx context.Context) (string, error)

GetSSHPublicKey reads the SSH public key from the SSH container.

func (*Manager) NetworkName 

func (m *Manager) NetworkName() docker.NetworkName

NetworkName returns the mesh network name for this realm.

func (*Manager) RemoveDNSRecord 

func (m *Manager) RemoveDNSRecord(ctx context.Context, hostname string) error

RemoveDNSRecord removes all A records for the given hostname from the mesh DNS Corefile and reloads CoreDNS.

func (*Manager) RemoveDNSRecords added in v0.9.0 

func (m *Manager) RemoveDNSRecords(ctx context.Context, hostnames []string) error

RemoveDNSRecords removes all A records for the given hostnames from the mesh DNS Corefile and reloads CoreDNS once.

func (*Manager) RemoveKnownHost 

func (m *Manager) RemoveKnownHost(ctx context.Context, hostname string) error

RemoveKnownHost removes all entries for the given hostname from the known_hosts file in the SSH container.

func (*Manager) RemoveKnownHosts added in v0.9.0 

func (m *Manager) RemoveKnownHosts(ctx context.Context, hostnames []string) error

RemoveKnownHosts removes all entries for the given hostnames from the known_hosts file in a single operation.

func (*Manager) ResolvedActive added in v0.5.0 

func (m *Manager) ResolvedActive(ctx context.Context) bool

ResolvedActive checks if systemd-resolved is running.

func (*Manager) SSHContainerName 

func (m *Manager) SSHContainerName() docker.ContainerName

SSHContainerName returns the SSH container name for this realm.

func (*Manager) SSHKeygenName 

func (m *Manager) SSHKeygenName() docker.ContainerName

SSHKeygenName returns the temporary keygen container name for this realm.

func (*Manager) SSHVolumeName 

func (m *Manager) SSHVolumeName() docker.VolumeName

SSHVolumeName returns the SSH volume name for this realm.

func (*Manager) StartMesh added in v0.11.0 

func (m *Manager) StartMesh(ctx context.Context) (dnsIP string, found bool, err error)

StartMesh starts the realm's DNS and SSH relay containers that exist but are not running, as after a host reboot or a Docker daemon restart. It creates nothing: EnsureMesh does. The DNS container starts first, as the relay and the nodes resolve through it, and a restarted DNS container reapplies host DNS (HostDNS), which the host loses with the mesh bridge.

It returns the DNS container's address on the mesh network, and whether the realm has a DNS container. A relay created with another DNS address is reported with Warn (see WarnStaleDNS).

func (*Manager) Warn added in v0.11.0 

func (m *Manager) Warn(ctx context.Context, msg string)

Warn reports a warning for the user through OnWarning, or the context's logger when OnWarning is nil.

func (*Manager) WarnStaleDNS added in v0.11.0 

func (m *Manager) WarnStaleDNS(ctx context.Context, dnsIP string, infos ...*docker.ContainerInfo)

WarnStaleDNS warns about the containers in infos that were created to resolve through the mesh DNS at another address than dnsIP, the DNS container's current one. Docker fixes a container's DNS servers when it creates the container, so these keep asking the old address: names under <realm>.sind and external names no longer resolve in them. Containers created without --dns, and an empty dnsIP, are not checked.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.