cluster

package
v1.10.21 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

Documentation

Overview

Package cluster drives Docker Swarm as Miabi's optional cluster mode, one swarm per cluster. The default cluster follows the local engine and is auto-detected; another cluster becomes a swarm when an admin initializes it over its node's agent tunnel. Plain single-node Docker stays first-class.

Index

Constants

View Source
const (
	SeverityBlocker = "blocker" // multi-node cannot work; do not promise it
	SeverityWarning = "warning" // works, but has a sharp edge worth knowing
	SeverityInfo    = "info"
)

Severity ranks a preflight finding.

View Source
const (

	// AgentLabel marks swarm nodes Miabi already reaches directly (the local socket or their own agent), so
	// the global agent service skips them rather than opening a second tunnel for the same node.
	AgentLabel = "miabi.agent"
)
View Source
const (
	// AgentServiceName is the global service that carries the agent to every swarm member.
	AgentServiceName = "miabi-agent"
)

A swarm member with no Miabi agent runs tasks perfectly well but Miabi holds no Docker client for it, so an app scheduled there has no metrics, stats or shell. Swarm can fix this itself: a GLOBAL service runs one task on every node the constraints allow, including nodes that join later.

Variables

View Source
var (
	// ErrControlURLRequired is returned when the control plane has no address that
	// workers could dial. Without it the agents would start and never connect.
	ErrControlURLRequired = errors.New("MIABI_CONTROL_URL must be set: it is the address the agents dial back on")
	// ErrAgentImageRequired is returned when no agent image is configured.
	ErrAgentImageRequired = errors.New("no agent image is configured")
	// ErrNotSwarmMember is returned when an agent presents a cluster token but the swarm node id it claims
	// is not a member of that cluster's swarm. This is the check that makes a shared token safe.
	ErrNotSwarmMember = errors.New("the agent's swarm node id is not a member of this cluster")
	// ErrBadClusterToken is returned when the presented cluster agent token is unknown.
	ErrBadClusterToken = errors.New("invalid cluster agent token")
)
View Source
var (
	// ErrNotEnabled is returned when a cluster operation needs a swarm the cluster does not run.
	ErrNotEnabled = errors.New("cluster mode is not enabled")
	// ErrAdvertiseAddrRequired is returned when initializing a swarm without an advertise address.
	ErrAdvertiseAddrRequired = errors.New("an advertise address is required to enable cluster mode")
	// ErrManagerNode is returned when an operation that targets a member node is pointed at a manager.
	ErrManagerNode = errors.New("the manager node cannot be used for this operation")
	// ErrManagerAddrUnknown is returned when the manager's swarm address has not been detected yet.
	ErrManagerAddrUnknown = errors.New("manager swarm address is unknown; refresh cluster state")
	// ErrClusterNotFound is returned for a cluster id with no row.
	ErrClusterNotFound = errors.New("cluster not found")
	// ErrNodeHasWorkloads is returned when a node with workloads would enter or leave a remote swarm, whose
	// workspace networks exist only as overlays.
	ErrNodeHasWorkloads = errors.New("the node still has apps, databases or volumes; a remote swarm only takes and releases empty nodes")
	// ErrClusterHasWorkloads is returned when disabling a remote swarm that still holds workloads.
	ErrClusterHasWorkloads = errors.New("the cluster still has apps, databases or volumes; move or delete them before disabling Swarm")
	// ErrNodeInOtherSwarm is returned for a node whose engine already belongs to another swarm.
	ErrNodeInOtherSwarm = errors.New("the node is already in another swarm; remove it from that swarm first")
	// ErrClusterHasForeignWorkloads is returned when dedicating a cluster that still runs other
	// tenants' apps, databases or volumes.
	ErrClusterHasForeignWorkloads = errors.New("this location still runs workloads belonging to other organizations; move or delete them before dedicating it")
	// ErrDedicationAckRequired is returned when a change of owner arrives without the caller
	// confirming it. Who owns a location decides who may see and place in it, so it is not a field
	// that changes as a side effect of saving the form it happens to sit in.
	ErrDedicationAckRequired = errors.New("changing which organization a location is dedicated to must be acknowledged")
)
View Source
var (
	// ErrInvalidExternalDomain is returned for an external domain that is not a DNS name.
	ErrInvalidExternalDomain = errors.New("the external domain must be a DNS name such as apps.eu-central.example.com")
	// ErrExternalDomainTaken is returned when another cluster already generates URLs under the domain.
	ErrExternalDomainTaken = errors.New("another cluster already uses this external domain")
	// ErrExternalCertNotFound is returned for a certificate that is not in the system workspace.
	ErrExternalCertNotFound = errors.New("no such certificate in the system workspace")
	// ErrExternalCertNeedsDomain is returned for a certificate chosen in a cluster without an external domain.
	ErrExternalCertNeedsDomain = errors.New("set the external domain before choosing a certificate for it")
	// ErrExternalCertMismatch is returned for a certificate without the *.<external domain> wildcard.
	ErrExternalCertMismatch = errors.New("the certificate does not cover the external domain's wildcard")
	// ErrExternalCertUnusable is returned for a certificate that is still issuing, failed or expired.
	ErrExternalCertUnusable = errors.New("the certificate is not active or has expired")
	// ErrInvalidCertProvider is returned for a certificate provider that is not a plain provider name.
	ErrInvalidCertProvider = errors.New("the certificate provider must be a provider name from the gateway configuration, e.g. letsencrypt")
	// ErrExternalAccessPinned is returned for a change to a field the environment sets.
	ErrExternalAccessPinned = errors.New("set by MIABI_EXTERNAL_BASE_DOMAIN or MIABI_EXTERNAL_BASE_PROVIDER; change it in the environment")
)
View Source
var (
	ErrGatewayNeedsSwarm       = errors.New("only a swarm cluster other than the default one has a gateway of its own")
	ErrGatewayNodeNotInCluster = errors.New("the gateway node must belong to the cluster")
	ErrGatewayNodeNoGateway    = errors.New("the gateway node must run its own gateway: set its connectivity to edge gateway")
	ErrInvalidIngressIP        = errors.New("the ingress IP is not a valid IP address")
	ErrInvalidIngressHostname  = errors.New("the ingress hostname must be a DNS name such as lb.eu-central.example.com")
)

Errors returned by SetGateway.

View Source
var ErrInvalidAvailability = errors.New("availability must be active, pause or drain")

ErrInvalidAvailability is returned for an availability outside active/pause/drain.

View Source
var ErrInvalidEndpointMode = errors.New("service load balancing must be vip or dnsrr")

ErrInvalidEndpointMode is returned for a service endpoint mode other than "vip" or "dnsrr".

View Source
var ErrInvalidLocationCode = errors.New("the location code must be lowercase letters, digits and hyphens (max 32), e.g. eu-central")

ErrInvalidLocationCode is returned for a location code that is not a short lowercase slug.

View Source
var ErrInvalidVisibility = errors.New("visibility must be all or restricted")

ErrInvalidVisibility is returned for a visibility other than "all" or "restricted".

View Source
var ErrNameTooLong = errors.New("the cluster name is too long (max 40 characters)")

ErrNameTooLong is returned for a name that would not fit where it is shown.

View Source
var ErrNoTLS = errors.New("the control plane is not served over HTTPS; agents need no CA")

ErrNoTLS is returned when the control plane is not served over TLS, so there is no certificate to trust (and the agents need none).

Functions

func ExternalCertProblem added in v1.10.21

func ExternalCertProblem(cert *models.Certificate, domain string) error

ExternalCertProblem reports why a certificate cannot serve the generated URLs under domain, nil when it can.

Types

type AgentOptions added in v1.3.0

type AgentOptions struct {
	InsecureTLS bool
	// CACert is the PEM itself, shipped to the agents in their environment.
	CACert string
	// CACertPath is a CA file that already exists on every node, bind-mounted into each agent. The agent
	// container has its own stock bundle, which is why agents fail while hosts are fine.
	CACertPath string
}

AgentOptions configures how the agents trust the control plane's certificate.

type AgentStatus added in v1.3.0

type AgentStatus struct {
	Deployed bool   `json:"deployed"`
	Running  int    `json:"running_tasks"`
	Image    string `json:"image,omitempty"`
	// InsecureTLS is true when the agents do NOT verify the control plane's certificate, surfaced so a
	// one-off workaround for a self-signed cert cannot quietly become permanent.
	InsecureTLS bool `json:"insecure_tls"`
	// CustomCA is true when the agents verify against an operator-supplied CA.
	CustomCA bool `json:"custom_ca"`
	// CACertPath is set when the CA comes from a file that must exist on every node.
	CACertPath string `json:"ca_cert_path,omitempty"`
}

AgentStatus reports whether the global agent service is deployed, how many of its tasks are up, and whether those agents are skipping TLS verification.

type ClusterPatch added in v1.10.0

type ClusterPatch struct {
	DisplayName  *string
	LocationCode *string
	Visibility   *models.ClusterVisibility
	Cordoned     *bool
	// ExternalBaseDomain and ExternalCertProvider set where generated app URLs live; a change re-hosts them.
	ExternalBaseDomain   *string
	ExternalCertProvider *string
	// ExternalCertificateID serves the generated URLs from a system-workspace certificate; 0 goes back to a
	// certificate per app.
	ExternalCertificateID *uint
	// ServiceEndpointMode switches how the cluster's service apps are reached by name; running services follow.
	ServiceEndpointMode *models.ServiceEndpointMode
	// IngressIP and IngressHostname are where the cluster's public DNS records point.
	IngressIP       *string
	IngressHostname *string
	// OrganizationID dedicates the cluster to one organization; 0 releases it back to shared. Set it
	// together with Visibility "organization" — the handler keeps the two in step.
	OrganizationID *uint
	// Acknowledge confirms the caller accepts what changing the dedication does to the tenants
	// already here. Required whenever OrganizationID actually changes hands: it decides who may see
	// and place in the location, and it strands whatever the new owner does not own.
	Acknowledge bool
}

ClusterPatch edits a cluster's tenant-facing identity and who may place into it. Nil fields are left unchanged.

type ControlPlaneCert added in v1.3.0

type ControlPlaneCert struct {
	// PEM is what goes into MIABI_CA_CERT.
	PEM string `json:"pem"`
	// The fields below are for the operator to eyeball before trusting it. A cert fetched over an unverified
	// connection could, in principle, be an attacker's — showing the subject and fingerprint is what makes
	// the confirmation meaningful rather than ceremonial.
	Subject     string `json:"subject"`
	Issuer      string `json:"issuer"`
	NotAfter    string `json:"not_after"`
	Fingerprint string `json:"fingerprint"` // SHA-256, colon-separated
	// SelfSigned is true when the certificate is its own issuer — the usual case for a
	// homelab control plane, and the case where pinning it IS trusting the CA.
	SelfSigned bool `json:"self_signed"`
	// PubliclyTrusted is true when the chain already verifies against the system pool,
	// in which case no CA needs to be distributed at all and the agents should simply
	// verify normally.
	PubliclyTrusted bool `json:"publicly_trusted"`

	// Hosts are the names the certificate actually vouches for (its SANs).
	Hosts []string `json:"hosts,omitempty"`
	// MatchesHost is whether the certificate names the address the agents will dial. This is the trap in
	// "just trust the CA": adding a certificate to the trust pool does NOT skip the hostname check, so a
	// cert with no SANs fails however well it is trusted. A CA that doesn't name the control plane is useless.
	MatchesHost bool `json:"matches_host"`
	// DialHost is the address the agents dial, so the UI can name it in the failure.
	DialHost string `json:"dial_host"`

	// AnchorIsCA is whether what we can offer is a real certificate AUTHORITY, or merely the server's own
	// leaf. Pinning a leaf works right up until renewal, when the new leaf is a different certificate and
	// every agent drops off at once. When this is false, the honest advice is to paste the actual CA.
	AnchorIsCA bool `json:"anchor_is_ca"`
}

ControlPlaneCert is the certificate the control plane currently serves, offered so the agents can be pinned to it.

type DedicationImpact added in v1.10.4

type DedicationImpact struct {
	ClusterID uint  `json:"cluster_id"`
	Workloads int64 `json:"workloads"`
	// Tenants are the organizations with workloads here, largest first. Name is empty for the
	// workspaces that belong to no organization.
	Tenants []TenantWorkloads `json:"tenants"`
}

DedicationImpact is what a cluster currently holds, broken down by the organization that owns it. The console shows it before an admin changes who the location belongs to: a change of owner decides who may see and place here, and strands whatever the new owner does not own.

type ExternalCertificates added in v1.10.21

type ExternalCertificates interface {
	SystemCertificate(id uint) (*models.Certificate, error)
	ResolveSystem(id uint) (certPEM, keyPEM string, err error)
}

ExternalCertificates reads the certificates kept in the system workspace. Implemented by services/certificate.

type Finding added in v1.3.0

type Finding struct {
	Severity string `json:"severity"`
	Title    string `json:"title"`
	Detail   string `json:"detail"`
}

Finding is one thing the operator should know before enabling cluster mode.

type FirewallRule added in v1.3.0

type FirewallRule struct {
	Port    string `json:"port"`    // "2377/tcp", "esp (ip protocol 50)", …
	Purpose string `json:"purpose"` // what breaks without it
}

FirewallRule is one port (or IP protocol) that must be open between every pair of swarm nodes. These are not advisory: with any blocked, the swarm forms and DNS resolves while the data plane silently drops every packet — apps resolve each other and then time out, the most confusing cluster failure.

type GatewayPatch added in v1.10.0

type GatewayPatch struct {
	ServerID uint
	IP       string
	Hostname string
}

GatewayPatch sets the node serving a swarm cluster's routes and the address its DNS records point at.

type JoinInstructions

type JoinInstructions struct {
	// WorkerToken is the swarm worker join token (a secret; admin-only).
	WorkerToken string `json:"worker_token"`
	// ManagerAddr is the manager address the host dials to join (host:port).
	ManagerAddr string `json:"manager_addr"`
	// Command is a ready-to-run `docker swarm join` command.
	Command string `json:"command"`
}

JoinInstructions are what an operator needs to join a host to a swarm by hand, for a node not reachable over the agent tunnel. The command runs on the host itself.

type Leader added in v1.10.1

type Leader interface {
	Leading() bool
}

Leader reports whether this process leads the control plane. Satisfied by *leader.Elector.

type Member

type Member struct {
	docker.SwarmNode
	// Managed is true when this swarm node maps to a Miabi node.
	Managed bool `json:"managed"`
	// ServerID / ServerName identify the mapped Miabi node (when Managed).
	ServerID   uint   `json:"server_id,omitempty"`
	ServerName string `json:"server_name,omitempty"`
	// IsManager marks the node the control plane drives this swarm through.
	IsManager bool `json:"is_manager"`
}

Member is one swarm node (docker node ls), annotated with the Miabi node it maps to, or marked unmanaged when it has no Miabi record (e.g. a host joined by hand).

type NetCheck added in v1.3.0

type NetCheck struct {
	Network string           `json:"network"`
	Probes  []NetCheckProbe  `json:"probes"`
	Results []NetCheckResult `json:"results"`
	VIP     *NetCheckResult  `json:"vip,omitempty"` // a service virtual IP dialed on the node its task runs on
	OK      bool             `json:"ok"`
	Summary string           `json:"summary"`
}

NetCheck is the whole report.

type NetCheckImages added in v1.3.0

type NetCheckImages interface {
	Ref(key string) string
}

NetCheckImages resolves the probe image (a socat/alpine utility image).

type NetCheckProbe added in v1.3.0

type NetCheckProbe struct {
	ServerID   uint   `json:"server_id"`
	NodeName   string `json:"node_name"`
	Reachable  bool   `json:"reachable"` // Miabi could start a probe here
	Error      string `json:"error,omitempty"`
	OverlayIP  string `json:"overlay_ip,omitempty"`
	OverlayMTU int    `json:"overlay_mtu,omitempty"`
}

NetCheckProbe is one node's participation in the check.

type NetCheckResult added in v1.3.0

type NetCheckResult struct {
	From    string `json:"from"`
	To      string `json:"to"`
	DNS     bool   `json:"dns"`     // the name resolved on the source node
	TCP     bool   `json:"tcp"`     // a connection completed
	Payload bool   `json:"payload"` // a 1400-byte body round-tripped
	IP      string `json:"ip,omitempty"`
	Error   string `json:"error,omitempty"`
	// Verdict names the failure in the operator's terms rather than making them
	// infer it from three booleans.
	Verdict string `json:"verdict"`
}

NetCheckResult is one directed test: can `from` reach `to` over the overlay?

type NodeAction added in v1.10.0

type NodeAction int

NodeAction is what a refused node was about to do.

const (
	// EnableSwarmAction initializes a swarm on the node.
	EnableSwarmAction NodeAction = iota
	// JoinAction joins the node to a swarm other than the default cluster.
	JoinAction
	// LeaveAction takes the node out of such a swarm.
	LeaveAction
)

type NodeDocker

type NodeDocker interface {
	For(serverID uint) (docker.Client, error)
	Local() docker.Client
	LocalID() uint
}

NodeDocker resolves Docker clients per node (0/local = the manager engine).

type NodeRegistrar added in v1.3.0

type NodeRegistrar interface {
	FindBySwarmNodeID(swarmNodeID string) (*models.Server, error)
	RegisterClusterNode(clusterID uint, swarmNodeID, hostname string) (*models.Server, error)
}

NodeRegistrar creates or updates the Miabi node record an agent registers as. Satisfied by services/node.

type NodeWorkloadsError added in v1.10.0

type NodeWorkloadsError struct {
	Node      string
	Action    NodeAction
	Apps      int64
	Databases int64
	Volumes   int64
}

NodeWorkloadsError refuses a node with workloads entering or leaving a swarm other than the default cluster, whose workspace networks are overlays from the start. It names what the node runs and the way forward, and matches ErrNodeHasWorkloads.

func (*NodeWorkloadsError) Error added in v1.10.0

func (e *NodeWorkloadsError) Error() string

func (*NodeWorkloadsError) Is added in v1.10.0

func (e *NodeWorkloadsError) Is(target error) bool

type Nodes

type Nodes interface {
	List(ctx context.Context) ([]models.Server, error)
	Get(id uint) (*models.Server, error)
	SetSwarmNodeID(id uint, swarmNodeID string) error
	SetEngineVersion(swarmNodeID, version string) error
}

Nodes is the slice of the node service the cluster service depends on.

type OrgDefaultAligner added in v1.10.4

type OrgDefaultAligner func(orgID, prefer uint) error

OrgDefaultAligner repoints an organization's default location after its clusters changed. Satisfied by the organization service's AlignDefaultCluster.

type OrgLabels added in v1.10.4

type OrgLabels func(ids []uint) map[uint]string

OrgLabels names organizations in bulk. Satisfied by the organization service.

type Preflight added in v1.3.0

type Preflight struct {
	// EngineOS is the Docker daemon's reported operating system ("Ubuntu 22.04",
	// "Docker Desktop", "OrbStack", …).
	EngineOS string `json:"engine_os"`
	// MultiNodeCapable is false when this engine cannot carry the overlay data plane
	// to other hosts, whatever the firewall says. Single-node cluster mode still
	// works — this is specifically about spanning nodes.
	MultiNodeCapable bool           `json:"multi_node_capable"`
	Findings         []Finding      `json:"findings"`
	Firewall         []FirewallRule `json:"firewall"`
}

Preflight is what we can tell an operator about this host before they turn cluster mode on.

type Service

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

Service tracks each cluster's swarm state and exposes cluster operations.

func NewService

func NewService(clients NodeDocker, nodes Nodes) *Service

NewService builds the cluster service. Call Refresh once at boot to populate the swarm state.

func (*Service) AgentStatus added in v1.3.0

func (s *Service) AgentStatus(ctx context.Context, clusterID uint) AgentStatus

AgentStatus inspects a cluster's global agent service.

func (*Service) AnySwarm added in v1.10.0

func (s *Service) AnySwarm() bool

AnySwarm reports whether any cluster runs a swarm, which is when the service runtime can be offered.

func (*Service) ApplyNetworking added in v1.3.0

func (s *Service) ApplyNetworking(ctx context.Context, clusterID uint) error

ApplyNetworking converts the default cluster's workspace bridges into overlays on demand, for an install already clustered when it upgraded. A remote swarm only ever holds overlays, so there is nothing to apply.

func (*Service) AttachGateway added in v1.10.0

func (s *Service) AttachGateway(ctx context.Context, clusterID uint)

AttachGateway joins a swarm cluster's ingress-node gateway to the cluster's ingress overlay, which is how it reaches apps on the other nodes. Every refresh re-asserts it, in case the attachment was lost.

func (*Service) AttachNodeGateway added in v1.10.0

func (s *Service) AttachNodeGateway(ctx context.Context, dc docker.Client, srv *models.Server, container string)

AttachNodeGateway joins a node's freshly started gateway to its cluster's ingress overlay when the node is the ingress node of a swarm cluster other than the default one. It reads the stored cluster rather than the refreshed swarm state, which still lags when an agent has just reconnected.

func (*Service) AuthenticateAgent added in v1.3.0

func (s *Service) AuthenticateAgent(ctx context.Context, token, swarmNodeID, hostname string) (*models.Server, error)

AuthenticateAgent authorizes an agent that presented a cluster token and returns the Miabi node it is. The token only names the cluster; identity comes from the swarm node id the agent read off its engine, trusted only because that cluster's manager confirms the membership.

func (*Service) CapCluster

func (s *Service) CapCluster() bool

CapCluster reports whether the default cluster's engine is a reachable swarm manager.

func (*Service) Cluster added in v1.10.0

func (s *Service) Cluster(id uint) (*models.Cluster, error)

Cluster returns one cluster with its node count; id 0 is the default cluster.

func (*Service) ClusterIDByUID added in v1.10.0

func (s *Service) ClusterIDByUID(uid string) (uint, error)

ClusterIDByUID resolves a cluster's uid to its id.

func (*Service) ClusterOfServer added in v1.10.0

func (s *Service) ClusterOfServer(serverID uint) uint

ClusterOfServer returns the cluster a node belongs to; 0 is the local node, always in the default cluster.

func (*Service) Clusters added in v1.10.0

func (s *Service) Clusters() ([]models.Cluster, error)

Clusters lists every cluster, the default first, with its node count.

func (*Service) ConfirmGateway added in v1.10.0

func (s *Service) ConfirmGateway(clusterID uint) error

ConfirmGateway records that a node converted from port-forward serves its apps through its own gateway.

func (*Service) Dedication added in v1.10.4

func (s *Service) Dedication(clusterID uint) (*DedicationImpact, error)

Dedication reports what a change of owner would affect in this cluster.

func (*Service) DeployAgents added in v1.3.0

func (s *Service) DeployAgents(ctx context.Context, clusterID uint, opts AgentOptions) error

DeployAgents installs the Miabi agent on every node of a cluster's swarm as a global service. It is an explicit admin action because it grants Miabi the Docker socket, root-equivalent, on every machine that is now, or ever becomes, a member of this swarm.

func (*Service) Disable

func (s *Service) Disable(ctx context.Context, clusterID uint) error

Disable takes a cluster out of swarm mode. Its member nodes leave first and each becomes a standalone cluster of its own; the manager leaves last.

func (*Service) Enable

func (s *Service) Enable(ctx context.Context, clusterID uint, advertiseAddr string) (Status, error)

Enable makes a cluster a swarm. The default cluster initializes (or adopts) the local engine's swarm; any other cluster initializes one on its node, over the agent tunnel. advertiseAddr is the address peers reach the manager on, ignored when adopting a swarm the engine is already managing.

func (*Service) Enrich

func (s *Service) Enrich(servers []models.Server)

Enrich annotates each server's transient fields from its cluster: the swarm role and availability of its last refresh, and whether the cluster is dedicated to an organization. A node outside every swarm shows as standalone while any cluster runs one.

func (*Service) EnsureWorkspaceOverlay added in v1.10.0

func (s *Service) EnsureWorkspaceOverlay(ctx context.Context, clusterID uint, n models.Network) error

EnsureWorkspaceOverlay creates a workspace network as an overlay in a remote swarm, on the network's pool subnet, so a container or database placed there can attach. The default cluster's overlays are created by the network service.

func (*Service) ExternalAccess added in v1.10.0

func (s *Service) ExternalAccess(clusterID uint) (domain, provider string)

ExternalAccess returns the wildcard domain and certificate provider for generated app URLs in a cluster; id 0 is the default cluster. An empty domain means one-click external access is off there.

func (*Service) ExternalApps added in v1.10.0

func (s *Service) ExternalApps(clusterID uint) int64

ExternalApps counts the apps in a cluster holding generated URLs, which a domain change re-hosts.

func (*Service) ExternalCertificatePair added in v1.10.21

func (s *Service) ExternalCertificatePair(clusterID uint) (certPEM, keyPEM string, ok bool)

ExternalCertificatePair returns the certificate a cluster serves its generated URLs from. ok is false when it has none or the one chosen can no longer serve them, and the gateway then falls back to a certificate per app rather than presenting an expired or mismatched one.

func (*Service) FetchControlPlaneCert added in v1.3.0

func (s *Service) FetchControlPlaneCert(ctx context.Context) (ControlPlaneCert, error)

FetchControlPlaneCert dials the control plane and returns the certificate it serves. The dial deliberately skips verification: the whole point is to reach a control plane whose certificate does NOT verify yet. Safe here because we collect a certificate for a human to confirm by fingerprint.

func (*Service) IngressAddress added in v1.10.0

func (s *Service) IngressAddress(clusterID uint) (ip, hostname string)

IngressAddress is where a cluster's public DNS records point: its gateway, or a load balancer in front of it. Id 0 is the default cluster.

func (*Service) IsDefaultCluster added in v1.10.0

func (s *Service) IsDefaultCluster(clusterID uint) bool

IsDefaultCluster reports whether a cluster id names the default cluster, whose apps the control plane serves.

func (*Service) IsSwarm added in v1.10.0

func (s *Service) IsSwarm(clusterID uint) bool

IsSwarm reports whether a cluster runs a swarm the control plane can drive right now.

func (*Service) JoinInstructions

func (s *Service) JoinInstructions(ctx context.Context, clusterID uint) (JoinInstructions, error)

JoinInstructions returns a cluster's manual join command, fetched live from the swarm (never persisted).

func (*Service) JoinNode

func (s *Service) JoinNode(ctx context.Context, clusterID, serverID uint) error

JoinNode joins a node to a cluster's swarm over its agent tunnel, with the worker join token and the manager's advertised address, then moves the node and everything placed on it into that cluster. Idempotent: a node already in this swarm just has its swarm id reconciled.

func (*Service) LearnIngressIP added in v1.10.0

func (s *Service) LearnIngressIP(serverID uint, remoteAddr string)

LearnIngressIP fills a cluster's empty public address with the public source IP its ingress node's agent connected from, so an admin need not type it. A private source address says nothing behind NAT and is ignored.

func (*Service) LeaveNode

func (s *Service) LeaveNode(ctx context.Context, serverID uint, force bool) error

LeaveNode removes a member node from its cluster's swarm, prunes it from the manager's node list, and gives the node a standalone cluster of its own. force is passed to the node-side leave.

func (*Service) LocationLabel added in v1.10.0

func (s *Service) LocationLabel(clusterID uint) string

LocationLabel names a cluster the way tenants see it.

func (*Service) Manager added in v1.10.0

func (s *Service) Manager(_ context.Context, clusterID uint) (docker.Client, error)

Manager returns a Docker client that can issue Swarm and engine calls for the cluster: the local socket for the default cluster, the node itself for a standalone one, and a manager's tunnel for a remote swarm.

func (*Service) Members

func (s *Service) Members(ctx context.Context, clusterID uint) ([]Member, error)

Members returns a cluster's swarm nodes annotated with the Miabi node each maps to. Empty when the cluster runs no swarm.

func (*Service) MirrorCordon added in v1.10.3

func (s *Service) MirrorCordon(ctx context.Context, serverID uint, cordoned bool) error

func (*Service) Name added in v1.3.0

func (s *Service) Name() string

Name returns the default cluster's display name, or "" when unnamed.

func (*Service) NetCheck added in v1.3.0

func (s *Service) NetCheck(ctx context.Context, clusterID uint) (NetCheck, error)

NetCheck probes the cluster's overlay data plane from every node to every other node. It requires cluster mode, runs only on nodes Miabi has a Docker client for (it must start a container there), and cleans up after itself.

func (*Service) OwnGateway added in v1.10.0

func (s *Service) OwnGateway(clusterID uint) (*models.Cluster, bool)

OwnGateway returns a cluster that its own ingress node serves: a swarm outside the default cluster, whose overlay the control-plane gateway cannot join. Read from the stored mode, so routes stay put while a manager is offline.

func (*Service) PinExternalAccess added in v1.10.0

func (s *Service) PinExternalAccess(domain, provider string) error

PinExternalAccess applies MIABI_EXTERNAL_BASE_DOMAIN and MIABI_EXTERNAL_BASE_PROVIDER to the default cluster. A set variable wins on every boot and locks its field; an empty one leaves the field to the console.

func (*Service) Preflight added in v1.3.0

func (s *Service) Preflight(ctx context.Context, clusterID uint) (Preflight, error)

Preflight inspects a cluster's manager engine and reports what an operator needs to know before enabling Swarm there. It never mutates anything, and it works whether or not Swarm is already on.

func (*Service) ReaffirmNode

func (s *Service) ReaffirmNode(ctx context.Context, serverID uint)

ReaffirmNode re-joins a node Miabi already considers a swarm member if it has dropped out, e.g. after the host was rebuilt. It never joins a node that was never a member. Best-effort, for the agent-connect hook.

func (*Service) Refresh

func (s *Service) Refresh(ctx context.Context)

Refresh re-reads every swarm cluster's state from its manager. Cheap and safe on plain Docker. Called at boot and on an interval.

func (*Service) RefreshLoop

func (s *Service) RefreshLoop(ctx context.Context, interval time.Duration)

RefreshLoop refreshes swarm state on the given interval until ctx is done.

func (*Service) RemoveAgents added in v1.3.0

func (s *Service) RemoveAgents(ctx context.Context, clusterID uint) error

RemoveAgents tears a cluster's global agent service down. The node records stay; those nodes simply go back to being unmanaged.

func (*Service) ResyncRoutes added in v1.10.0

func (s *Service) ResyncRoutes(ctx context.Context, clusterID uint)

ResyncRoutes re-syncs a cluster's routes in the background, after the gateway serving them changed.

func (*Service) ServiceEndpointMode added in v1.10.0

func (s *Service) ServiceEndpointMode(clusterID uint) models.ServiceEndpointMode

ServiceEndpointMode is how a cluster's service apps are reached by name; id 0 is the default cluster.

func (*Service) SetAgentDeps added in v1.3.0

func (s *Service) SetAgentDeps(reg NodeRegistrar, controlURL string, images NetCheckImages, fallbackImage string)

SetAgentDeps wires what the global agent service needs (nil-safe; nil disables it).

func (*Service) SetAllocator added in v1.10.0

func (s *Service) SetAllocator(a *netalloc.Service)

SetAllocator wires the subnet pool a remote swarm's workspace overlays are carved from (nil-safe; nil leaves the addressing to Swarm).

func (*Service) SetAvailability added in v1.3.0

func (s *Service) SetAvailability(ctx context.Context, clusterID uint, swarmNodeID, availability string) error

SetAvailability changes a swarm node's scheduling availability: active places new tasks, pause keeps existing tasks running without placing more, and drain reschedules existing tasks off the node.

func (*Service) SetEndpointModeListener added in v1.10.0

func (s *Service) SetEndpointModeListener(fn func(ctx context.Context, clusterID uint, mode models.ServiceEndpointMode))

SetEndpointModeListener is told when a cluster's service endpoint mode changed, so its running services follow.

func (*Service) SetExternalAccessListener added in v1.10.0

func (s *Service) SetExternalAccessListener(fn func(ctx context.Context, clusterID uint))

SetExternalAccessListener is told when a cluster's external domain or certificate provider changed, so the generated app URLs follow.

func (*Service) SetExternalCertificates added in v1.10.21

func (s *Service) SetExternalCertificates(c ExternalCertificates)

SetExternalCertificates wires the certificates a cluster may serve its generated URLs from.

func (*Service) SetGateway added in v1.10.0

func (s *Service) SetGateway(ctx context.Context, clusterID uint, p GatewayPatch) (*models.Cluster, error)

SetGateway picks the node that serves a swarm cluster's routes and the address its DNS records point at.

func (*Service) SetGatewayListener added in v1.10.0

func (s *Service) SetGatewayListener(fn func(ctx context.Context, clusterID uint))

SetGatewayListener is told when a cluster's gateway moves, so the cluster's routes follow it.

func (*Service) SetIngressReconciler

func (s *Service) SetIngressReconciler(fn func(context.Context) error)

SetIngressReconciler wires the callback that re-asserts the central gateway's attachment to the default cluster's ingress overlay, run on every Refresh. Nil-safe.

func (*Service) SetLeader added in v1.10.1

func (s *Service) SetLeader(l Leader)

SetLeader makes Refresh only read swarm state while l does not lead: persisting what it observed and re-asserting memberships, pool labels and gateway attachments is left to the leading process. Without a leader every refresh writes.

func (*Service) SetName added in v1.3.0

func (s *Service) SetName(name string) error

SetName labels the default cluster. An empty name clears it.

func (*Service) SetNetCheckImage added in v1.3.0

func (s *Service) SetNetCheckImage(images NetCheckImages, fallback string)

SetNetCheckImage wires the image the probe containers run.

func (*Service) SetNetworkMigrator added in v1.3.0

func (s *Service) SetNetworkMigrator(migrate, rollback func(context.Context) error, pending func() int)

SetNetworkMigrator wires the default cluster's workspace-network conversion: `migrate` (bridge -> overlay) runs on Enable, `rollback` on Disable, and `pending` counts the networks still on bridges. Nil-safe.

func (*Service) SetNodeJoinedHook added in v1.10.18

func (s *Service) SetNodeJoinedHook(fn func(ctx context.Context, serverID uint, nodeName string, dc docker.Client))

SetNodeJoinedHook wires a callback run after a node joins a cluster, with that node's Docker client. Nil-safe; failures are the hook's own to report and never undo the join.

func (*Service) SetOrgDefaultAligner added in v1.10.4

func (s *Service) SetOrgDefaultAligner(fn OrgDefaultAligner)

SetOrgDefaultAligner wires that realignment. Without it a newly dedicated organization keeps a default location it can no longer place in.

func (*Service) SetOrgLabels added in v1.10.4

func (s *Service) SetOrgLabels(fn OrgLabels)

SetOrgLabels wires how a dedicated cluster's organization is named. Without it a cluster still reports as dedicated, just unnamed.

func (*Service) SetStore added in v1.10.0

func (s *Service) SetStore(st Store)

SetStore wires the cluster rows (nil-safe; nil leaves only the default cluster, unnamed).

func (*Service) Status

func (s *Service) Status(clusterID uint) Status

Status returns a cluster's last-refreshed swarm status.

func (*Service) SyncPoolLabel added in v1.10.0

func (s *Service) SyncPoolLabel(ctx context.Context, srv *models.Server) error

SyncPoolLabel mirrors a node's pool onto its swarm node, where service placement constraints read it. A no-op for a node outside an active swarm.

func (*Service) Tasks added in v1.3.0

func (s *Service) Tasks(ctx context.Context, clusterID uint, swarmNodeID string) ([]docker.SwarmTask, error)

Tasks lists the service tasks the scheduler placed on a swarm node, or on all nodes when swarmNodeID is empty. Only a manager can answer this, which is the only way to see an unmanaged node's workload.

func (*Service) UpdateCluster added in v1.10.0

func (s *Service) UpdateCluster(id uint, p ClusterPatch) (*models.Cluster, error)

UpdateCluster renames a cluster, changes its location code, who may place into it, or its external access.

func (*Service) WorkspaceOverlay added in v1.10.0

func (s *Service) WorkspaceOverlay(clusterID uint, n models.Network) bool

WorkspaceOverlay reports whether a workspace network is an overlay in a cluster. In the default cluster its record decides; a remote swarm only takes empty nodes, so its workspace networks are overlays from the start.

type Status

type Status struct {
	// Enabled reports whether the cluster runs a swarm the control plane can drive.
	Enabled bool `json:"enabled"`
	// Name is the cluster's display name.
	Name string `json:"name,omitempty"`
	// LocalNodeState is the manager engine's swarm state (inactive on plain Docker).
	LocalNodeState string `json:"local_node_state"`
	// ManagerAddr is the address the manager advertises to swarm peers.
	ManagerAddr string `json:"manager_addr,omitempty"`
	NodeID      string `json:"node_id,omitempty"`
	Managers    int    `json:"managers"`
	Nodes       int    `json:"nodes"`
	// IngressNetwork is the attachable overlay a gateway joins to reach service VIPs; set only in cluster mode.
	IngressNetwork string `json:"ingress_network,omitempty"`
	// NetworksPending counts the default cluster's workspace networks still on node-local bridges, which
	// have no cross-node connectivity until cluster networking is applied.
	NetworksPending int `json:"networks_pending,omitempty"`
	// AgentsDeployed reports whether the global agent service is installed, i.e. whether swarm members
	// are managed (metrics, stats, shell, housekeeping) or merely run tasks Miabi cannot see into.
	AgentsDeployed bool `json:"agents_deployed"`
	AgentTasks     int  `json:"agent_tasks,omitempty"`
	// AgentInsecureTLS is true when those agents skip verification of the control plane's certificate.
	AgentInsecureTLS bool `json:"agent_insecure_tls,omitempty"`
	// AgentCustomCA is true when the agents verify against an operator-supplied CA.
	AgentCustomCA bool `json:"agent_custom_ca,omitempty"`
	// AgentCACertPath is set when that CA is a file that must exist on every node.
	AgentCACertPath string `json:"agent_ca_cert_path,omitempty"`
	Error           string `json:"error,omitempty"`
}

Status is a cluster's swarm status as surfaced to the console.

type Store added in v1.10.0

type Store interface {
	List() ([]models.Cluster, error)
	FindDefault() (*models.Cluster, error)
	FindByID(id uint) (*models.Cluster, error)
	FindByName(name string) (*models.Cluster, error)
	FindByAgentTokenHash(hash string) (*models.Cluster, error)
	IDByUID(uid string) (uint, error)
	UpdateColumns(id uint, cols map[string]any) error
	CountWorkloads(clusterID uint) (int64, error)
	CountExternalApps(clusterID uint) (int64, error)
	CountForeignWorkloads(clusterID, orgID uint) (int64, error)
	WorkloadsByOrganization(clusterID uint) (map[uint]int64, error)
	ClearUnusableWorkspaceDefaults() (int64, error)
	CountServerWorkloadsByKind(serverID uint) (apps, databases, volumes int64, err error)
	CreateStandalone(srv *models.Server, name string) (*models.Cluster, error)
	AssignServer(serverID, clusterID uint) error
}

Store reads and writes cluster rows. Satisfied by repositories.ClusterRepository.

type TenantWorkloads added in v1.10.4

type TenantWorkloads struct {
	OrganizationID uint   `json:"organization_id"`
	Name           string `json:"name,omitempty"`
	Workloads      int64  `json:"workloads"`
}

TenantWorkloads is one organization's share of a cluster.

Jump to

Keyboard shortcuts

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