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
- Variables
- func ExternalCertProblem(cert *models.Certificate, domain string) error
- type AgentOptions
- type AgentStatus
- type ClusterPatch
- type ControlPlaneCert
- type DedicationImpact
- type ExternalCertificates
- type Finding
- type FirewallRule
- type GatewayPatch
- type JoinInstructions
- type Leader
- type Member
- type NetCheck
- type NetCheckImages
- type NetCheckProbe
- type NetCheckResult
- type NodeAction
- type NodeDocker
- type NodeRegistrar
- type NodeWorkloadsError
- type Nodes
- type OrgDefaultAligner
- type OrgLabels
- type Preflight
- type Service
- func (s *Service) AgentStatus(ctx context.Context, clusterID uint) AgentStatus
- func (s *Service) AnySwarm() bool
- func (s *Service) ApplyNetworking(ctx context.Context, clusterID uint) error
- func (s *Service) AttachGateway(ctx context.Context, clusterID uint)
- func (s *Service) AttachNodeGateway(ctx context.Context, dc docker.Client, srv *models.Server, container string)
- func (s *Service) AuthenticateAgent(ctx context.Context, token, swarmNodeID, hostname string) (*models.Server, error)
- func (s *Service) CapCluster() bool
- func (s *Service) Cluster(id uint) (*models.Cluster, error)
- func (s *Service) ClusterIDByUID(uid string) (uint, error)
- func (s *Service) ClusterOfServer(serverID uint) uint
- func (s *Service) Clusters() ([]models.Cluster, error)
- func (s *Service) ConfirmGateway(clusterID uint) error
- func (s *Service) Dedication(clusterID uint) (*DedicationImpact, error)
- func (s *Service) DeployAgents(ctx context.Context, clusterID uint, opts AgentOptions) error
- func (s *Service) Disable(ctx context.Context, clusterID uint) error
- func (s *Service) Enable(ctx context.Context, clusterID uint, advertiseAddr string) (Status, error)
- func (s *Service) Enrich(servers []models.Server)
- func (s *Service) EnsureWorkspaceOverlay(ctx context.Context, clusterID uint, n models.Network) error
- func (s *Service) ExternalAccess(clusterID uint) (domain, provider string)
- func (s *Service) ExternalApps(clusterID uint) int64
- func (s *Service) ExternalCertificatePair(clusterID uint) (certPEM, keyPEM string, ok bool)
- func (s *Service) FetchControlPlaneCert(ctx context.Context) (ControlPlaneCert, error)
- func (s *Service) IngressAddress(clusterID uint) (ip, hostname string)
- func (s *Service) IsDefaultCluster(clusterID uint) bool
- func (s *Service) IsSwarm(clusterID uint) bool
- func (s *Service) JoinInstructions(ctx context.Context, clusterID uint) (JoinInstructions, error)
- func (s *Service) JoinNode(ctx context.Context, clusterID, serverID uint) error
- func (s *Service) LearnIngressIP(serverID uint, remoteAddr string)
- func (s *Service) LeaveNode(ctx context.Context, serverID uint, force bool) error
- func (s *Service) LocationLabel(clusterID uint) string
- func (s *Service) Manager(_ context.Context, clusterID uint) (docker.Client, error)
- func (s *Service) Members(ctx context.Context, clusterID uint) ([]Member, error)
- func (s *Service) MirrorCordon(ctx context.Context, serverID uint, cordoned bool) error
- func (s *Service) Name() string
- func (s *Service) NetCheck(ctx context.Context, clusterID uint) (NetCheck, error)
- func (s *Service) OwnGateway(clusterID uint) (*models.Cluster, bool)
- func (s *Service) PinExternalAccess(domain, provider string) error
- func (s *Service) Preflight(ctx context.Context, clusterID uint) (Preflight, error)
- func (s *Service) ReaffirmNode(ctx context.Context, serverID uint)
- func (s *Service) Refresh(ctx context.Context)
- func (s *Service) RefreshLoop(ctx context.Context, interval time.Duration)
- func (s *Service) RemoveAgents(ctx context.Context, clusterID uint) error
- func (s *Service) ResyncRoutes(ctx context.Context, clusterID uint)
- func (s *Service) ServiceEndpointMode(clusterID uint) models.ServiceEndpointMode
- func (s *Service) SetAgentDeps(reg NodeRegistrar, controlURL string, images NetCheckImages, ...)
- func (s *Service) SetAllocator(a *netalloc.Service)
- func (s *Service) SetAvailability(ctx context.Context, clusterID uint, swarmNodeID, availability string) error
- func (s *Service) SetEndpointModeListener(fn func(ctx context.Context, clusterID uint, mode models.ServiceEndpointMode))
- func (s *Service) SetExternalAccessListener(fn func(ctx context.Context, clusterID uint))
- func (s *Service) SetExternalCertificates(c ExternalCertificates)
- func (s *Service) SetGateway(ctx context.Context, clusterID uint, p GatewayPatch) (*models.Cluster, error)
- func (s *Service) SetGatewayListener(fn func(ctx context.Context, clusterID uint))
- func (s *Service) SetIngressReconciler(fn func(context.Context) error)
- func (s *Service) SetLeader(l Leader)
- func (s *Service) SetName(name string) error
- func (s *Service) SetNetCheckImage(images NetCheckImages, fallback string)
- func (s *Service) SetNetworkMigrator(migrate, rollback func(context.Context) error, pending func() int)
- func (s *Service) SetNodeJoinedHook(fn func(ctx context.Context, serverID uint, nodeName string, dc docker.Client))
- func (s *Service) SetOrgDefaultAligner(fn OrgDefaultAligner)
- func (s *Service) SetOrgLabels(fn OrgLabels)
- func (s *Service) SetStore(st Store)
- func (s *Service) Status(clusterID uint) Status
- func (s *Service) SyncPoolLabel(ctx context.Context, srv *models.Server) error
- func (s *Service) Tasks(ctx context.Context, clusterID uint, swarmNodeID string) ([]docker.SwarmTask, error)
- func (s *Service) UpdateCluster(id uint, p ClusterPatch) (*models.Cluster, error)
- func (s *Service) WorkspaceOverlay(clusterID uint, n models.Network) bool
- type Status
- type Store
- type TenantWorkloads
Constants ¶
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.
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" )
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 ¶
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") )
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") )
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") )
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.
var ErrInvalidAvailability = errors.New("availability must be active, pause or drain")
ErrInvalidAvailability is returned for an availability outside active/pause/drain.
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".
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.
var ErrInvalidVisibility = errors.New("visibility must be all or restricted")
ErrInvalidVisibility is returned for a visibility other than "all" or "restricted".
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.
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
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
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
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
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
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
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
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 ¶
CapCluster reports whether the default cluster's engine is a reachable swarm manager.
func (*Service) Cluster ¶ added in v1.10.0
Cluster returns one cluster with its node count; id 0 is the default cluster.
func (*Service) ClusterIDByUID ¶ added in v1.10.0
ClusterIDByUID resolves a cluster's uid to its id.
func (*Service) ClusterOfServer ¶ added in v1.10.0
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
Clusters lists every cluster, the default first, with its node count.
func (*Service) ConfirmGateway ¶ added in v1.10.0
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
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 ¶
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 ¶
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 ¶
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
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
ExternalApps counts the apps in a cluster holding generated URLs, which a domain change re-hosts.
func (*Service) ExternalCertificatePair ¶ added in v1.10.21
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
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
IsDefaultCluster reports whether a cluster id names the default cluster, whose apps the control plane serves.
func (*Service) IsSwarm ¶ added in v1.10.0
IsSwarm reports whether a cluster runs a swarm the control plane can drive right now.
func (*Service) JoinInstructions ¶
JoinInstructions returns a cluster's manual join command, fetched live from the swarm (never persisted).
func (*Service) JoinNode ¶
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
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 ¶
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
LocationLabel names a cluster the way tenants see it.
func (*Service) Manager ¶ added in v1.10.0
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 ¶
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 (*Service) Name ¶ added in v1.3.0
Name returns the default cluster's display name, or "" when unnamed.
func (*Service) NetCheck ¶ added in v1.3.0
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
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
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
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 ¶
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 ¶
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 ¶
RefreshLoop refreshes swarm state on the given interval until ctx is done.
func (*Service) RemoveAgents ¶ added in v1.3.0
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
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
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
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
SetGatewayListener is told when a cluster's gateway moves, so the cluster's routes follow it.
func (*Service) SetIngressReconciler ¶
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
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
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
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
SetStore wires the cluster rows (nil-safe; nil leaves only the default cluster, unnamed).
func (*Service) SyncPoolLabel ¶ added in v1.10.0
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
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
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.