cluster

package
v0.4.2 Latest Latest
Warning

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

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

Documentation

Overview

Package cluster is the one door for every docker call the panel makes.

A call is either about the swarm (a service, an overlay, the node list), which always goes to the manager's socket, or about one container or volume, which lives on exactly one node and has to be run there. Callers used to decide which by hand, three packages wrote their own copy of the decision, and the postgres provisioner never made it at all: it ran every exec against the local socket, which was right for as long as every managed instance happened to live on the manager (docs/plans/35-cluster.md).

Here the node id is the first argument of every container and volume call and it is required. There is no "empty means here": that convenience is how a forgotten node argument turned into a call against the wrong machine with no error. A caller that means this machine says so with Self.

runtime stays the socket layer and agent stays the client and server. This package is a front over both, not a rewrite of either.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cluster

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

Cluster routes calls to the docker socket or to a node's agent.

func New

func New(rt *runtime.Runtime, nodes *agent.Nodes, store repo.Store) *Cluster

New takes everything a Cluster needs to reach any node, in the signature. There is no optional wiring step: of the thirteen places that used to build the managed-tiles service, one plugged the agent in and twelve ran against the local socket without anyone noticing.

func (*Cluster) AttachServiceNetwork

func (c *Cluster) AttachServiceNetwork(ctx context.Context, name string, n runtime.NetAttach) (bool, error)

func (*Cluster) AttachServiceNetworks

func (c *Cluster) AttachServiceNetworks(ctx context.Context, name string, ns []runtime.NetAttach) (bool, error)

func (*Cluster) Client

func (c *Cluster) Client(ctx context.Context, node string) (*agent.Client, error)

Client is the agent on one node, for the one job that is agent-to-agent by nature: a volume move streams rsync between two workers' agents, and neither end of that is a container call the panel makes. Anything that is a container or volume call has a method on Cluster and must use it.

func (*Cluster) ConnectContainer

func (c *Cluster) ConnectContainer(ctx context.Context, netName, containerID string, aliases []string) error

ConnectContainer attaches a container on the manager to a network. The only caller is the panel joining itself to an instance's overlay, which is itself on the list to be removed altogether.

func (*Cluster) ContainerIsSystem

func (c *Cluster) ContainerIsSystem(ctx context.Context, node, id string) bool

ContainerIsSystem is the guard in front of stop and remove. When it cannot tell, it says yes: refusing a stop is recoverable, stopping the panel or the proxy on a node is not.

func (*Cluster) CreateVolume

func (c *Cluster) CreateVolume(ctx context.Context, node, name string) error

func (*Cluster) CreateVolumeOpts

func (c *Cluster) CreateVolumeOpts(ctx context.Context, node, name, driver string, opts map[string]string) error

CreateVolumeOpts creates a volume with an explicit driver and driver opts, how a storage sub-path becomes an nfs, cifs or bind mount. Same node rule as CreateVolume: the mount is a directory on one host.

func (*Cluster) DeleteVolumeFile

func (c *Cluster) DeleteVolumeFile(ctx context.Context, node, vol, file string) error

func (*Cluster) DetachServiceNetwork

func (c *Cluster) DetachServiceNetwork(ctx context.Context, name, netName string) (bool, error)

func (*Cluster) EnsureOverlay

func (c *Cluster) EnsureOverlay(ctx context.Context, name string) error

func (*Cluster) EnsureService

func (c *Cluster) EnsureService(ctx context.Context, s runtime.ServiceSpec) (created bool, err error)

func (*Cluster) EnsureVolumeTool

func (c *Cluster) EnsureVolumeTool(ctx context.Context) error

func (*Cluster) Exec

func (c *Cluster) Exec(ctx context.Context, node, id string, cmd []string) (string, error)

Exec runs a command in a container on node and returns stdout and stderr interleaved, the way `docker exec` printed them. The convenience over ExecStream for the short psql-style calls that just want the text.

func (*Cluster) ExecShell

func (c *Cluster) ExecShell(ctx context.Context, node, id, command string) (string, error)

ExecShell runs one shell command in a container on node and waits for it.

func (*Cluster) ExecStream

func (c *Cluster) ExecStream(ctx context.Context, node, id string, cmd []string, stdin io.Reader) (io.Reader, func() error, error)

ExecStream runs a command in a container on node and streams its output.

func (*Cluster) ExecTTY

func (c *Cluster) ExecTTY(ctx context.Context, node, id string, cmd []string) (io.ReadWriter, func(w, h uint) error, func(), error)

ExecTTY opens an interactive shell in a container wherever it runs. The return shape is the local one, so handlers/web/wsterm bridges a browser to it without knowing which node answered.

func (*Cluster) HealthStatus

func (c *Cluster) HealthStatus(ctx context.Context, node, id string) (string, error)

func (*Cluster) Info

func (c *Cluster) Info(ctx context.Context, node string) (agent.InfoResp, error)

Info is the docker daemon snapshot of one node plus the host's distro.

func (*Cluster) InspectContainer

func (c *Cluster) InspectContainer(ctx context.Context, node, id string) (*runtime.ContainerDetail, error)

func (*Cluster) InspectVolume

func (c *Cluster) InspectVolume(ctx context.Context, name string) (runtime.VolumeInfo, error)

func (*Cluster) ListAll

func (c *Cluster) ListAll(ctx context.Context, node string) ([]runtime.ManagedContainer, error)

ListAll lists every container on one node.

func (*Cluster) ListByLabel

func (c *Cluster) ListByLabel(ctx context.Context, label, value string) ([]runtime.ManagedContainer, error)

func (*Cluster) ListNodes

func (c *Cluster) ListNodes(ctx context.Context) ([]runtime.Node, error)

func (*Cluster) ListVolumeFiles

func (c *Cluster) ListVolumeFiles(ctx context.Context, node, vol, dir string) ([]runtime.VolumeEntry, error)

func (*Cluster) ListVolumes

func (c *Cluster) ListVolumes(ctx context.Context, node string) ([]runtime.VolumeInfo, error)

func (*Cluster) LocalDigest

func (c *Cluster) LocalDigest(ctx context.Context, ref string) (string, error)

LocalDigest reads the manager's copy of the image, which can differ from what a worker runs.

func (*Cluster) Logs

func (c *Cluster) Logs(ctx context.Context, id string, tail int) (string, error)

Logs is the last tail lines of one container, one shot. Manager-only: the agent streams logs but has no one-shot endpoint, and the only caller is the pre-swarm container fallback below, which lists the manager's own containers by label. Anything following a live tile's logs goes through the service, which swarm collects from every node.

func (*Cluster) NetworkMemberAddr

func (c *Cluster) NetworkMemberAddr(ctx context.Context, netName, containerID string) (ip, cidr string, err error)

func (*Cluster) NodeOf

func (c *Cluster) NodeOf(ctx context.Context, t *repo.Tile) (string, error)

NodeOf is the node a tile's data lives on. It answers through placement, never t.HomeNode directly, because a volume tile has no home node of its own. A tile with no resolvable node is an error here rather than "" one call later, so the message can name the tile.

func (*Cluster) NodeOfStorage

func (c *Cluster) NodeOfStorage(ctx context.Context, s *repo.Storage) (string, error)

NodeOfStorage is the node a storage tile's volumes live on. A storage row is not a tile: it names a server, and the server row carries the swarm node id. Until this existed every storage volume was created and destroyed on the manager whatever server the operator picked, which is the postgres provisioner's bug with a different noun (docs/plans/36-cluster-only.md).

func (*Cluster) PauseContainer

func (c *Cluster) PauseContainer(ctx context.Context, node, id string) error

func (*Cluster) Prune

func (c *Cluster) Prune(ctx context.Context, node string) (string, error)

Prune runs the image and container prune on one node. Every node keeps its own images, so this is per node and not swarm-wide.

func (*Cluster) PullImage

func (c *Cluster) PullImage(ctx context.Context, ref string, logW io.Writer) error

PullImage pulls on the manager. Swarm pulls on the target node itself when the service is scheduled, so this is a warm-up, not the real pull.

func (*Cluster) PullImageAuth

func (c *Cluster) PullImageAuth(ctx context.Context, ref, auth string, logW io.Writer) error

PullImageAuth and PushImageAuth move an image on the manager with a credential supplied per call, so one org's registry token never lands in the node's shared daemon config. See runtime.PullImageAuth.

func (*Cluster) PushImage

func (c *Cluster) PushImage(ctx context.Context, ref string, logW io.Writer) error

func (*Cluster) PushImageAuth

func (c *Cluster) PushImageAuth(ctx context.Context, ref, auth string, logW io.Writer) error

func (*Cluster) Reachable

func (c *Cluster) Reachable(ctx context.Context, node string) bool

Reachable reports whether a node's agent answers, or true for this node.

func (*Cluster) ReadVolumeFile

func (c *Cluster) ReadVolumeFile(ctx context.Context, node, vol, file string) (io.ReadCloser, func() error, error)

func (*Cluster) RemoveImage

func (c *Cluster) RemoveImage(ctx context.Context, ref string) error

RemoveImage and PushImage act on the manager's own image store, which is where the build engine builds and where the registry push reads from.

func (*Cluster) RemoveService

func (c *Cluster) RemoveService(ctx context.Context, name string) error

func (*Cluster) RemoveVolume

func (c *Cluster) RemoveVolume(ctx context.Context, node, name string) error

RemoveVolume destroys a named volume on one node. Purges rather than plain-removes: this is the node page's Delete button, the operator has already said the volume goes, and the stopped containers holding it would otherwise make that impossible.

func (*Cluster) RestartService

func (c *Cluster) RestartService(ctx context.Context, name string, want int) error

func (*Cluster) RunJob

func (c *Cluster) RunJob(ctx context.Context, s runtime.ServiceSpec) (string, error)

func (*Cluster) RunningTasks

func (c *Cluster) RunningTasks(ctx context.Context, service string) ([]runtime.NodeTask, error)

func (*Cluster) RunningTileTasks

func (c *Cluster) RunningTileTasks(ctx context.Context) (map[string]runtime.NodeTask, error)

func (*Cluster) Runtime

func (c *Cluster) Runtime() *runtime.Runtime

Runtime is the manager's own docker socket, for the swarm plumbing packages that take one: envnet, placement, netpool and proxy read and shape swarm state and are the manager's business by definition. It is not a way to reach a container: those calls take a node and live on Cluster, and the grep gate in docs/plans/35-cluster.md step 6 is what keeps them there.

func (*Cluster) ScaleService

func (c *Cluster) ScaleService(ctx context.Context, name string, n int) error

func (*Cluster) Self

func (c *Cluster) Self(ctx context.Context) string

Self is the swarm node the panel runs on. Callers that mean "this machine" pass this, never "".

func (*Cluster) ServiceLogs

func (c *Cluster) ServiceLogs(ctx context.Context, name string, tail int) (string, error)

func (*Cluster) ServiceStatus

func (c *Cluster) ServiceStatus(ctx context.Context, name string) (runtime.ServiceState, error)

func (*Cluster) StartContainer

func (c *Cluster) StartContainer(ctx context.Context, node, id string) error

func (*Cluster) Stats

func (c *Cluster) Stats(ctx context.Context, node, id string) (runtime.ContainerStats, error)

func (*Cluster) StopContainer

func (c *Cluster) StopContainer(ctx context.Context, node, id string) error

func (*Cluster) StopRemove

func (c *Cluster) StopRemove(ctx context.Context, node, id string) error

func (*Cluster) StopService

func (c *Cluster) StopService(ctx context.Context, name string) error

func (*Cluster) StreamLogsMarked

func (c *Cluster) StreamLogsMarked(ctx context.Context, node, id string, tail int) (<-chan string, func(), error)

StreamLogsMarked follows one container's logs on its own node. Most log viewing goes through the service, which the manager collects for every replica; this is the per-container case.

func (*Cluster) StreamServiceLogsMarked

func (c *Cluster) StreamServiceLogsMarked(ctx context.Context, name string, tail int) (<-chan string, func(), error)

func (*Cluster) TarVolume

func (c *Cluster) TarVolume(ctx context.Context, node, vol string, w io.Writer, live bool) error

TarVolume streams a backup of one node's volume, so a pinned tile on a worker backs up the same way one on the manager does.

func (*Cluster) UnpauseContainer

func (c *Cluster) UnpauseContainer(ctx context.Context, node, id string) error

func (*Cluster) UntarVolume

func (c *Cluster) UntarVolume(ctx context.Context, node, vol string, src io.Reader) error

UntarVolume wipes a volume and extracts an archive into it. The wipe is the destructive half of a restore and there is no way back from it, so callers verify the archive before calling, locally and remotely alike.

func (*Cluster) VerifyTar

func (c *Cluster) VerifyTar(ctx context.Context, path string) error

VerifyTar and EnsureVolumeTool act on the manager's own disk and image cache, which is where infra/backup stages archives. Manager-only by design, not by gap.

func (*Cluster) VolumeExists

func (c *Cluster) VolumeExists(ctx context.Context, node, name string) bool

VolumeExists reports whether a node already has a named volume. The agent has no inspect endpoint and this is only ever an existence check, so it reads the node's volume list rather than earning one. Callers run it at attach and edit time, not in a loop.

func (*Cluster) VolumeSize

func (c *Cluster) VolumeSize(ctx context.Context, node, vol string) (int64, error)

func (*Cluster) WaitConverged

func (c *Cluster) WaitConverged(ctx context.Context, name string, timeout time.Duration) error

func (*Cluster) WaitRolled

func (c *Cluster) WaitRolled(ctx context.Context, name string, since time.Time, timeout time.Duration) error

func (*Cluster) WriteVolumeFile

func (c *Cluster) WriteVolumeFile(ctx context.Context, node, vol, file string, src io.Reader) error

Jump to

Keyboard shortcuts

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