NorskManager class

hello

DaemonHello

The daemon’s hello: its wire-protocol version, build label and the protocol skew against this SDK. Set alongside version.

version

VersionInfo

Norsk Runtime version information

abortMigration(jobId, sourceRole, targetRole, reason, migrationId)

Abort an in-flight migration. Manager dispatches NodeControllerMigrationAbort to both the source and target workers (the source resumes output, the target tears its migration state down). migrationId lets a worker ignore an abort that belongs to a predecessor of the migration it is in.

addClusterMember(node, by)

Add a member at run time: a Manager whose node name no config.yaml names. The cluster records that it expects node; the node joins when its Manager starts with the existing members in its own clusterNodes. Idempotent; forwarded to the primary. Returns every member the cluster now expects.

announceControlPlane(url, intervalMs)

Tell this Manager where workers reach the norsk-mgr beside it (its public URL); every worker is told the whole cluster’s list. Answered by the member it is sent to, never forwarded. intervalMs is how often the caller will announce again: the member reports its norsk-mgr stale (getClusterStatus) once three such intervals pass without one, which is how a standby tells the active norsk-mgr is down. Omitted: never stale.

appendAuditEntry(source, kind, payload)

Append a caller-supplied event to the durable audit log — for norsk-mgr-origin actions that don’t pass through another RPC. The daemon assigns the seq and chains it.

close()

Close down the Norsk connection

clusterMemberRegister(req)

Worker-facing call: the worker presents its registration token and tells Manager where to dial back. On success Manager raises Online on its provider bus and dials the worker; on Unauthenticated the token is unknown (or has been deregistered).

Most consumers won’t call this directly — norsk-ctl --mode=worker --token=… --manager-url=… does it on the worker side.

completeJob(jobId)

Stops a running job

connect(settings)

static

Connect to the Norsk Manager

createAwsNode(node)

Spawn a new EC2 instance running the worker image, and make it available for picking up jobs

createBundle(bundle)

Create a bundle (AutoManager v1). The bundle is passed in raw PB form — auto-manager (or any other consumer) is expected to convert its own typed Bundle to PB before calling. Returns the assigned bundleId so the caller can correlate later events.

createCloudHypervisorNode(node)

Spawn a worker as a Cloud Hypervisor microVM on one of the Manager’s host agents, and make it available for picking up jobs

createJob(job)

Create a new job

createOciNode(node)

Spawn a new OCI instance running the worker image, and make it available for picking up jobs

deleteBundle(bundleId)

Delete a bundle (AutoManager v1).

deleteJob(jobId)

Deletes a job

deregisterClusterNode(nodeId)

Remove a cluster slot. If a worker is currently connected on this slot, its gRPC stream is closed and any running jobs are stopped. The token is invalidated.

describeInstanceType(instanceType, options)

Cloud facts for a machine type: vCPU / memory / architectures, from the Manager’s instance-type cache for provider (default "aws"; "oci" reads its shape list; "cloud-hypervisor" reads the host agents' shapes). Authoritative for capacity ≡ vCPUs. With region (an AWS region / OCI availability domain / Cloud Hypervisor host) it also says whether the type is offered there. Returns undefined when the type is unknown to the provider; a provider or region the Manager does not run rejects with FAILED_PRECONDITION, a cache not yet warm with UNAVAILABLE.

eventStream(settings)

Provides a stream of the activity that is happening on the server-side. Reacting to these events is essential for the creation of client-side management logic.

forceStandalone(by)

The Big Red Button: make THIS member a one-member cluster keeping its state, at the next generation, when the cluster has lost its quorum. Rejects with FAILED_PRECONDITION while this member can reach a primary, on a witness, and with no store. On success the Manager restarts itself (the connection drops); the former members rejoin as they come back.

getAuditLog(query)

The most recent audit-log entries (newest first), plus whether the daemon’s hash chain verified on its last boot.

getClusterEvents(query)

This Manager member’s OWN cluster event log: what happened to it (role changes and why, lease failures, members joining or retiring, takeovers settling, …​). Never another member’s; a reader wanting the cluster’s whole picture asks every member and merges by time.

getClusterStatus()

getDiscoveryFleet()

The discovery fleet in force, secrets included, or undefined when none has been published: what a norsk-mgr that does not publish (a standby member’s) needs to start its own replica. Protocol 1.7.

tierSecretAlt and rotationPhase are a tier-secret rotation under way (see rotateDiscoveryTierSecret); both are "" when none is.

getLeaseStatus()

Whether leases are paused, and every lease held now.

getNodeIdleExpiry(nodeId)

What idle expiry applies to a node: idleExpiryMs is the override as set (0 = none), effectiveIdleExpiryMs is what the reaper will actually apply — the override when one is set, otherwise the daemon-wide value.

getStoreInfo()

Every store’s schema version, and what this boot did to the store: a restore of an unreadable database from its latest backup, a migration (with the pre-upgrade backup it took first).

jobById(id)

Search for jobs by id

jobSearch(settings)

Search for jobs by tag/date/etc. See JobSearchSettings

kvCommit(namespace, writes, opts)

Write to the Manager’s key/value store, all or nothing. Each write may name the revision it read (expectedRevision; 0 = the key must not exist) and the namespace’s schema version may be checked and bumped in the same commit — the schema version is the client’s, the Manager only stores and compares it. A mismatch rejects with FAILED_PRECONDITION and changes nothing.

kvGet(namespace, key)

One key of the Manager’s key/value store (decision daemon-kv), or undefined when absent. See kvCommit.

kvList(namespace, keyPrefix)

Every key of a namespace under keyPrefix ("" = all), in key order, with the namespace’s schema version (0 when never set).

leaveQuorum(by)

Leave the quorum: this member’s copy is discarded at its next boot and it runs as a follower only until it has joined a peer that carries a generation or a cluster of more than one. For the hosts an operator can still reach when forceStandalone is pressed elsewhere. The Manager restarts itself on success (the connection drops).

listClusterNodes()

List all registered cluster slots (active + inactive). Includes the tokens — visible to operators so they can re-copy on demand.

listInstanceTypes(options)

Every instance type a provider offers, each with the regions that offer it, for picking one rather than typing it. known is false for a provider that cannot enumerate (aws, oci), with an empty list; the cloud-hypervisor list is its hosts' shape lists (one host’s with region). Protocol 1.10.

listNodes()

Return a list a all the nodes the manager knows about.

listWorkerSecurityGroups(region)

Security groups dev-ops marked selectable for workers (tagged id3as.Norsk.WorkerSecurityGroup = <label>) in the given region — the discovery feed for a launch form’s SG selector, each with its actual ingress rules so the form can hint port coverage. Also carries the region’s base worker SG(s) (always attached, never selectable) so deployment-opened ports count as covered.

markJobFailed(jobId, reason)

Record a durable terminal-failed verdict on a job (AutoManager writeback when it gives up: restart ceiling exceeded / bronze drop). The job is marked terminally failed and persisted so it is not re-placed after a restart.

notifyMigrationCutoverApply(targetJobKey, migrationId, payload)

Tell the target worker "the source stopped output at payload; begin output from there". payload is the source’s own, relayed opaque. The target answers with MigrationTargetAppliedEvent.

notifyMigrationCutoverReady(sourceJobKey, migrationId, payload)

Tell the source worker "the target is ready at payload; stop output at or after it". AutoManager calls this when it receives MigrationTargetReadyEvent from the target; payload is the target’s own, relayed opaque — the job owns its meaning.

notifyMigrationGetState(sourceJobKey, migrationId)

The propose step (Phase F): ask the SOURCE what state it would hand over, before any target has been placed. The source’s answer — a payload, or a refusal — comes back asynchronously on the event stream as migrationState; a refusal ends the migration with nothing started anywhere.

pauseLeases(reason, by)

Lease-protected jobs (protocol 1.6): pause leases for a single Manager’s maintenance. Workers keep their lease-protected jobs without refreshing, and no such job whose holder was lost starts again until resumeLeases. Forwarded to the primary.

prefetchImages(nodeId, imageRefs)

Pre-warm a node (Phase G, warm nodes): tell its worker to pull these image refs now, so a later job start there finds them local. Returns as soon as the worker has been told — the per-ref outcome arrives asynchronously on the event stream as imagesPrefetched, and the node’s heldImages inventory updates right behind it.

A failure on one ref never fails the others; each ref’s result says for itself.

pruneAuditLog(beforeTimestampMs)

Operator-initiated retention prune of the audit log. Clears entries strictly older than beforeTimestampMs (0 = clear everything). The daemon front-prunes, records a checkpoint so the kept chain still verifies, and appends an audit-pruned marker. Returns how many entries were removed and the checkpoint boundary seq.

publishAccessReplica(publication)

Publish norsk-mgr’s role-store replica (norsk-ctl design worker-role-replica.md). A change carries the gzipped snapshot JWS and, when there was a previous version, the delta JWS; nothing changed carries an attestation of the stored version alone. The Manager stores the snapshot and keys, forwards the rest to every connected worker, and refuses (FAILED_PRECONDITION) a publication that does not move forward.

publishDiscoveryFleet(fleet)

Publish the deployment’s discovery fleet: every replica’s address, the leaf token, and the tier secret node tokens are minted from. The Manager keeps it and sends each connected node, and each node at its hello, its own access (every replica address, the leaf token and a node token minted for it); the tier secret never reaches a node. Refused (INVALID_ARGUMENT) when the tier secret is empty or equals the leaf token, or an address is not host:port.

The first tier secret and leaf token published STAY IN FORCE: a later publish carrying different ones keeps them, and the reply says so (secretsKept) and returns the ones in force, which the caller adopts. addresses is protocol 1.7; a fleet with none and an address is the single server of 1.4.

registerClusterNode(nodeName, pool)

Pre-register a cluster slot. Returns a nodeId and a one-shot token that must be handed to a worker — the worker calls clusterMemberRegister with the token + its listen address/port + hardware info. Until the worker calls in, the slot is registered-but-inactive.

reloadExternalConfig()

Re-read the Manager’s overrides file (cloud regions and worker image version tables) and apply it to the running providers, with no Manager restart. Call after writing the file.

removeClusterMember(node)

Retire a Manager from its cluster: remove the member on node (its Erlang node name) from the store’s membership. Removing the primary first hands leadership to another full member. The retired daemon should then be stopped.

renewBundleLease(bundleId, ttlMs)

resumeLeases(by)

Resume leases; every grace then runs from now.

rotateDiscoveryTierSecret(step, newTierSecret)

One step of rotating the discovery fleet’s tier secret, without a moment when any node’s token is refused:

- stage: every replica also accepts the new secret (tierSecretAlt; newTierSecret empty, the Manager makes one); - flip: the new secret is presented and mints node tokens, the old one still accepted; every running node is sent its new token; - finish: the old secret is no longer accepted.

Each norsk-mgr runs its replica with the step it reads, so wait for every replica to have taken one before the next. A step out of order is refused (FAILED_PRECONDITION), as is one before any fleet has been published. Returns the fleet in force after the step. Protocol 1.7.

setBundleStopTime(bundleId, stopAt)

Set (or, with undefined, clear) a bundle’s stop time, in place: no job is touched, so nothing restarts. The Manager deletes the bundle once the time passes (task 118).

setClusterNodePool(nodeId, pool)

Reassign a cluster slot to a different pool. Empty string = unassign. If the slot is currently active, Manager cycles Stopping/Terminated/ Online so the updated tags["pool"] propagates to AutoManager — containers on the worker survive (the worker preserves them across stream drops). Callers should ensure no jobs are currently assigned to the node; the brief reconnect window could otherwise interfere with in-flight placement.

setNodeIdleExpiry(nodeId, idleExpiryMs)

Give ONE node its own grace period before the empty-node reaper terminates it, overriding the daemon-wide value. Pass 0 to clear the override and go back to the daemon-wide value.

The setting is daemon-owned and persisted: it survives a Manager restart, which is exactly when a node deliberately kept warm would otherwise be reaped.

setNodeTags(nodeId, tags)

Merge tags onto a node: a key given here replaces its value, keys not given are untouched. The daemon persists the edit and re-applies it when it rediscovers the node after a restart, pushes it to the provider, and announces the node’s new metadata as a nodeTagsUpdated event. The spare tag is the daemon’s own: refused on an elastic node (FAILED_PRECONDITION — those spares are the AutoManager reconciler’s), while on a local server (cluster provider) spare: "true" marks it as a hot spare (refused while it holds a job) and any other value clears it; warmFor / reservedFor / exclusive beside it are the spare’s spec.

startBundleJob(bundleId, replicaIndex, jobName)

Activate a dormant (start_mode = "manual") bundle job. Manager removes the dormant tag and re-emits jobUpdated; placement picks the job up via the normal flow. See §10.2 of the AutoManager design.

startJob(jobId, role, nodeId, opts)

Start a job on a node

startPreparedJob(jobId, role, nodeId)

Start an instance that was provisioned with deferStart (the stop-then-start migration strategy): every container exists, none is running. Manager forwards start_prepared_job to the worker holding (jobId, role) on nodeId; the worker answers with JobRunning in the job’s history.

stopBundleJob(bundleId, replicaIndex, jobName, opts)

Stop a bundle job and keep it down: the daemon stops every running instance and re-stamps the dormant tag (startMode=manual), so the job is not placed again until NorskManager.startBundleJob(). opts.graceMs is how long its containers get before they are killed.

stopJob(jobId, role, nodeId, opts)

Stop a job running on a node

terminateNode(nodeId)

Forcibly stop a node

updateBundle(bundle)

Update a bundle (AutoManager v1). Same convention as createBundle — caller passes raw PB.

updateJob(job)

Update a job