node

package
v1.10.13 Latest Latest
Warning

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

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

Documentation

Overview

Package node manages Docker host (server) records and their reachability.

Index

Constants

View Source
const IngressOverlay = "miabi-ingress"

IngressOverlay is the single shared, attachable Swarm overlay the central Goma gateway joins to reach every clustered app's service VIP. Cluster apps attach to it in addition to their per-workspace overlay. It carries only gateway-to-VIP traffic, so east-west isolation between workspaces is unaffected.

Variables

View Source
var (
	ErrNodeNotFound = errors.New("node not found")
	ErrNameRequired = errors.New("node name is required")
	ErrLocalNode    = errors.New("the local node cannot be modified this way")
	ErrBadToken     = errors.New("invalid agent token")
	ErrNodeCordoned = errors.New("node is cordoned and cannot accept new placements")
	// ErrConnectivityAckRequired is returned when an update changes the node's
	// reachability settings without the caller acknowledging the impact.
	ErrConnectivityAckRequired = &connectivityAckError{}
	ErrInvalidPool             = errors.New("a pool name is lowercase letters, digits and hyphens (max 32), e.g. pro")
	// ErrSwarmNotMirrored reports a cordon that was saved but not passed on to the swarm scheduler.
	// Not a failure of the cordon itself, so it is surfaced as a warning rather than an abort.
	ErrSwarmNotMirrored    = errors.New("the node was updated, but its swarm scheduling availability could not be changed — Swarm may still place service tasks on it")
	ErrInvalidConnectivity = errors.New("a node either runs its own gateway (edge-gateway) or, as a swarm member, is served by its cluster's gateway (cluster)")
)
View Source
var AppNetwork = stack.DefaultNetwork

AppNetwork is the shared Docker network Goma Gateway and managed app containers join (the proxy gateway network). Configurable via MIABI_PROXY_NETWORK; set once at startup with SetAppNetwork.

View Source
var ErrEdgeGatewayInDefaultCluster = errors.New("a node of the default cluster is served by the control-plane gateway and cannot run one of its own; remove it from the swarm to give it its own cluster")

ErrEdgeGatewayInDefaultCluster is returned for a node of the default cluster set to run its own gateway.

Functions

func AppAlias

func AppAlias(app *models.Application) string

AppAlias is the stable network DNS alias for an application's active container, used as the reverse-proxy upstream so it survives redeploys. It is the app's stored Alias ("mb-app-<token>-<id>"); legacy apps with no stored alias fall back to "mb-app-<id>".

func CanaryAlias

func CanaryAlias(app *models.Application) string

CanaryAlias is the network DNS alias for an application's canary container, run alongside the stable release during a canary deployment. Only the stable release answers AppAlias, so the proxy can split weighted traffic between the two distinct aliases.

func NewAppAlias

func NewAppAlias(token string, appID uint) string

NewAppAlias builds a fresh stable alias for a newly created app.

func PublicIP added in v1.10.0

func PublicIP(raw string) string

PublicIP returns raw as a normalized IP only when it is a routable public address; loopback/private/link-local/unspecified sources return "". raw may carry a port (RemoteAddr fallback), which is stripped.

func ResolveAppNetwork added in v1.10.13

func ResolveAppNetwork(ctx context.Context, dc docker.Client, configured string) string

ResolveAppNetwork returns the proxy network name: configured when set, otherwise the one found on the local engine, so an install created before the rename keeps the network its apps are attached to. Only an engine with no proxy network at all gets stack.DefaultNetwork.

func SetAppNetwork

func SetAppNetwork(name string)

SetAppNetwork overrides the gateway network name (call once at startup, before Bootstrap or any deploy).

Types

type NodeInput

type NodeInput struct {
	// DisplayName is the free-text label, and the only name a caller supplies. The URL-safe handle is derived
	// from it at creation and never settable: it is what /api/v1/provider/{name} is built from, a deployed edge
	// gateway polls that URL, and nothing is gained by letting an operator change a value they never type again.
	DisplayName  string
	Address      string
	Connectivity models.ServerConnectivity
	AccessMode   models.ServerAccessMode
	// DockerEndpoint is the host for non-agent modes (unix://… / tcp://host:2376).
	DockerEndpoint string
	TLSCACert      string // api, optional (PEM)
	TLSCert        string // api, optional (PEM)
	TLSKey         string // api, optional (PEM; stored encrypted)
	// Acknowledge confirms the caller accepts that a reachability change may
	// briefly interrupt the workloads running on the node. Required whenever the
	// update actually changes connectivity/access mode/endpoint/address/TLS.
	Acknowledge bool
}

NodeInput is the create/update payload for a remote node. The TLS key is plaintext on input and encrypted at rest.

type NodeLimitError

type NodeLimitError struct{ Limit int }

NodeLimitError is returned when registering a node would exceed the edition's node cap. It exposes a stable Code() and a curated Message() so the API envelope surfaces NODE_LIMIT_REACHED with an upgrade-oriented message rather than the generic status word.

func (*NodeLimitError) Code

func (e *NodeLimitError) Code() string

func (*NodeLimitError) Error

func (e *NodeLimitError) Error() string

func (*NodeLimitError) Message

func (e *NodeLimitError) Message() string

type Service

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

func NewService

func NewService(repo *repositories.ServerRepository, dockerClient docker.Client) *Service

func (*Service) AdoptGateway

func (s *Service) AdoptGateway(id uint, container, image, configYAML string) (*models.Server, error)

AdoptGateway tracks a pre-existing gateway container as this node's gateway. It records the container name and image, optionally copies the gateway's existing config into the node's stored config, switches the node to edge-gateway connectivity, and stamps the deploy time — without recreating anything. A node that cannot run its own gateway is refused, as it would be when changing its connectivity directly.

func (*Service) Authenticate

func (s *Service) Authenticate(token string) (*models.Server, error)

Authenticate resolves the node an agent token belongs to (constant-time-ish via hash lookup).

func (*Service) AuthenticateProvider

func (s *Service) AuthenticateProvider(slug, token string) (*models.Server, error)

AuthenticateProvider resolves the node a Goma HTTP-provider request belongs to, accepting either the agent join token or the node's gateway token. The slug in the URL must match the resolved node.

func (*Service) Bootstrap

func (s *Service) Bootstrap(ctx context.Context, endpoint string)

Bootstrap registers the local node, pings the daemon to set its status, and ensures the managed Docker network exists. Non-fatal: logs and continues if Docker is unreachable so the API can still serve.

func (*Service) CreateNode

func (s *Service) CreateNode(in NodeInput) (*models.Server, string, error)

CreateNode registers a remote node. For agent mode it returns a one-time join token (only its hash is stored); other modes return an empty token.

func (*Service) DeleteNode

func (s *Service) DeleteNode(id uint) error

DeleteNode removes a remote node record.

func (*Service) FindBySwarmNodeID added in v1.3.0

func (s *Service) FindBySwarmNodeID(swarmNodeID string) (*models.Server, error)

FindBySwarmNodeID resolves the node backing a swarm node id.

func (*Service) GatewayRedisPassword

func (s *Service) GatewayRedisPassword(id uint) (string, error)

GatewayRedisPassword returns the per-node edge-gateway Redis password (decrypted), minting and persisting one (encrypted) on first use. Stable across redeploys so the gateway and its Redis keep matching credentials.

func (*Service) GatewayToken

func (s *Service) GatewayToken(id uint) (string, error)

GatewayToken returns the node's edge-gateway provider token (decrypted), minting and persisting one (encrypted) on first use. Unlike the join token it is recoverable, so the gateway can be (re)deployed on demand.

func (*Service) Get

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

Get returns a node by id.

func (*Service) IDByUID

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

IDByUID resolves a node's portable uid to its numeric id.

func (*Service) LearnSwarmNodeID added in v1.3.0

func (s *Service) LearnSwarmNodeID(id uint, swarmNodeID string)

LearnSwarmNodeID records the swarm node id the agent read from its own Docker engine at connect. This is how a node gets mapped to its swarm node in every case, not just when Miabi did the joining — a host joined by hand stayed unmapped forever, and an unmapped node cannot be resolved from a service's task.

func (*Service) List

func (s *Service) List(ctx context.Context) ([]models.Server, error)

List returns all servers, refreshing the local node's live status.

func (*Service) MarkConnected

func (s *Service) MarkConnected(id uint, agentVersion string)

MarkConnected records that a node's agent connected.

func (*Service) MarkDisconnected

func (s *Service) MarkDisconnected(id uint)

MarkDisconnected records that a node's agent dropped.

func (*Service) MarkGatewayDeployed

func (s *Service) MarkGatewayDeployed(id uint)

MarkGatewayDeployed stamps the node's last successful gateway deploy time and clears any imported-gateway tracking (a fresh install supersedes an import).

func (*Service) NameBySwarmNodeID

func (s *Service) NameBySwarmNodeID(swarmNodeID string) string

NameBySwarmNodeID resolves a swarm node id to a node's Miabi display name, so a cluster app's real replica placement can be shown by name. Returns "" when no node record carries that swarm id (the caller then falls back to a short id).

func (*Service) Placeable

func (s *Service) Placeable(serverID uint) error

Placeable validates that a node can accept a new resource (app/db/volume). The local node (0) is always placeable; a remote node must exist and not be cordoned. (Reachability is enforced separately when the operation runs.)

func (*Service) RegenerateToken

func (s *Service) RegenerateToken(id uint) (string, error)

RegenerateToken issues a fresh join token for a node, invalidating the old one.

func (*Service) RegisterClusterNode added in v1.3.0

func (s *Service) RegisterClusterNode(clusterID uint, swarmNodeID, hostname string) (*models.Server, error)

RegisterClusterNode creates the record for a swarm worker that registered itself through the global agent service. The caller has already verified the swarm node id is a member of THIS swarm, so this is not an open registration endpoint. The node is marked AutoJoined: the cluster brought it in, an admin did not.

func (*Service) ReleaseGateway

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

ReleaseGateway stops tracking an imported gateway without touching the container. The image and config the import copied stay as the node's gateway settings for a later install, and connectivity is unchanged.

func (*Service) SetClusters added in v1.10.0

func (s *Service) SetClusters(r *repositories.ClusterRepository)

SetClusters wires the cluster rows every node belongs to (nil-safe; nil leaves new nodes unassigned, which resolves to the default cluster).

func (*Service) SetConnectivity added in v1.10.0

func (s *Service) SetConnectivity(id uint, c models.ServerConnectivity) (*models.Server, error)

SetConnectivity changes only how a node's apps are served, leaving its other reachability settings alone.

func (*Service) SetCordoned

func (s *Service) SetCordoned(ctx context.Context, id uint, cordoned bool) error

SetCordoned toggles a node's drain flag (no new placements when cordoned). On a swarm member the flag is mirrored onto the node's swarm availability, since Miabi's own placement decisions bind only container apps — Swarm schedules service tasks itself and would ignore the cordon.

The flag is saved even when the mirror fails, and ErrSwarmNotMirrored reports that: the caller must surface it, because a cordon Swarm never heard about still takes work.

func (*Service) SetEngineVersion added in v1.9.6

func (s *Service) SetEngineVersion(swarmNodeID, version string) error

SetEngineVersion persists a node's Docker daemon version, keyed by its swarm node id (the stable handle the cluster refresh has for every node, including ones with no Miabi client). Column-scoped so it never clobbers a field the agent-connect path writes concurrently.

func (*Service) SetGatewayConfig

func (s *Service) SetGatewayConfig(id uint, config string) (*models.Server, error)

SetGatewayConfig stores a node's custom edge-gateway config (empty resets to the rendered default). Returns the updated node.

func (*Service) SetGatewayImage

func (s *Service) SetGatewayImage(id uint, image string) (*models.Server, error)

SetGatewayImage stores a node's edge-gateway image override (empty resets to the resolved default). Returns the updated node.

func (*Service) SetGatewayUpdate

func (s *Service) SetGatewayUpdate(id uint, p *models.GatewayUpdateProgress) error

SetGatewayUpdate persists the node's in-flight gateway update progress (nil clears it). Used by the safe-update flow so progress survives a reconnect.

func (*Service) SetNodeLimit

func (s *Service) SetNodeLimit(fn func() int)

SetNodeLimit wires the resolved edition node cap (manager + remotes). The closure is re-evaluated on every node registration, so a license install or lapse takes effect without a restart. A nil closure or a negative return means unlimited.

func (*Service) SetOrphanHandler added in v1.10.2

func (s *Service) SetOrphanHandler(fn func(serverID uint))

SetOrphanHandler wires the reconciler run after a node is deleted (nil-safe).

func (*Service) SetPool added in v1.10.0

func (s *Service) SetPool(id uint, pool string) (*models.Server, error)

SetPool puts a node in a pool, or in none for an empty name. A plan bound to a pool places its workspaces' workloads only on that pool's nodes.

func (*Service) SetSwarmCordon added in v1.10.3

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

SetSwarmCordon wires the swarm-availability mirror (nil-safe; nil leaves the cordon Miabi-side only).

func (*Service) SetSwarmNodeID

func (s *Service) SetSwarmNodeID(id uint, swarmNodeID string) error

SetSwarmNodeID records (or clears) the Docker Swarm node ID a node maps to, so the Nodes page can correlate it to `docker node ls`. Idempotent: a no-op when the value is unchanged, to avoid write churn on every cluster refresh.

func (*Service) StoredGatewayRedisPassword added in v1.10.10

func (s *Service) StoredGatewayRedisPassword(id uint) (string, error)

StoredGatewayRedisPassword returns the node's gateway Redis password without minting one

func (*Service) UpdateNode

func (s *Service) UpdateNode(id uint, in NodeInput) (*models.Server, error)

UpdateNode edits a remote node's reachability settings. Credential fields are only replaced when non-empty (so an unchanged form keeps existing secrets).

func (*Service) WorkloadImpact

func (s *Service) WorkloadImpact(id uint) (apps int64, databases int64, err error)

WorkloadImpact reports how many applications and database instances are placed on the node, so the UI can warn what a connectivity change would affect.

Jump to

Keyboard shortcuts

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