cork

func (*ChallengeMetadata) NeedsInstance ¶

func (cm *ChallengeMetadata) NeedsInstance() bool

NeedsInstance reports whether running instances are part of delivering this challenge. Only "service" challenges need them; artifact-only and flag-only challenges are fully delivered by their builds. An unset DeliveryType (metadata that never passed through the loader or a database read) counts as needing instances, so a missed derivation can never silently skip instance management.

func (LogLevel) String ¶

func (l LogLevel) String() string

String names a level the way CORK_LOGGING spells it.

func (*Manager) AddWorker ¶

func (m *Manager) AddWorker(ip, public string) error

AddWorker registers the worker at the given private IP, with an optional player-facing public address (IP or hostname; empty means players are given the private IP). Workers are keyed by private IP; re-adding an existing one (e.g. to recover a sticky-down worker) tears down its old connection and poller, starts fresh, and replaces the public address with the one given. Either way the box is reconciled before it takes placements: see reconcileWorker.

func (*Manager) BasePinFingerprint ¶

func (m *Manager) BasePinFingerprint() uint32

BasePinFingerprint is the identity contribution of the pins in force here: 0 with pinning off. It is an input to every build's content checksum (contentChecksum), and the one input a daemon taking a hand-over cannot derive for itself, the pins living where the builds are made, so the build plane states it and the daemon recomputes with it (HandOver).

func (*Manager) Build ¶

func (m *Manager) Build(challenge ChallengeId, seeds []int, flagFormat string) ([]*BuildMetadata, error)

Templates out a "challenge" and generates concrete images, flags, and lookup values for the seeds provided which is called a "build" and returns a list of identifiers that can be used to reference the build in other API functions. This function may take a significant amount of time because it will implicitly download base docker images and build the artifacts.

NOTE: if `CORK_REGISTRY` is specified, the generation this build displaces is offered to BuildKit as a cache source and the image produced carries inline cache metadata, so a builder whose local cache was reclaimed recovers the shared layers from the registry rather than re-running every install. See cacheRefsFor and BUILDER.md. (This replaced a per-challenge "freeze" image, which is gone.)

func (*Manager) BuildPlane ¶

func (m *Manager) BuildPlane() string

BuildPlane reports the configured build plane, BuildPlaneLocal or BuildPlaneExternal.

func (*Manager) ContentChecksum ¶

func (m *Manager) ContentChecksum(sourceChecksum uint32, format string, pinFingerprint uint32, challengeType string) uint32

ContentChecksum is the identity a build has under the inputs given: its source generation, its flag format, a base image pin fingerprint and the challenge type whose template it is built from. It is what a hand-over states and what the daemon taking one recomputes (see checkHandOver), so a build plane can ask the same question of its own builds before it hands them over -- a build made under other pins carries an identity these inputs do not give, and would be refused.

func (*Manager) CreateSchema ¶

func (m *Manager) CreateSchema(schema *Schema) []error

Uses the schema as a definition of builds and instances that should be created/started. Prevents management of those builds and instances from other API calls unless explicitly allowed by the schema. This call is likely to be extremely time and resource intensive as it will start creating all of the requested builds immediately and not return until complete.

Schema operations share updateMu with rebuilds (UpdateWithOptions): a converge builds, stops and launches instances of the same builds an update rebuilds and restarts, and the two interleaved would work over each other's instances just as two updates would. The lock is taken here, at the API boundary, and never inside: the unlocked helpers below are what the operations call each other through.

func (*Manager) DeleteSchema ¶

func (m *Manager) DeleteSchema(name string, retire bool) error

Tears down all instances and builds belonging to the schema. Serialized with rebuilds and other schema operations; see CreateSchema. DeleteSchema takes a schema off this daemon. retire says what becomes of the registry tags its builds carry: true removes them, which is what a removal means; false leaves them, which is what a migration to another orchestrator means -- the content is changing hands, not ending, and the tag is content-addressed so the orchestrator taking it resolves the same one.

func (*Manager) Destroy ¶

func (m *Manager) Destroy(build BuildId) error

Destroys the assoicated "build".

func (*Manager) DetectChanges ¶

func (m *Manager) DetectChanges(fp string) *ChallengeUpdates

Traverses the entire directory and captures all valid challenge descriptions it comes across. In general, it will continue even when it encounters errors (permission, poorly formatted JSON, etc.) in order to give the as much feedback as possible to the caller. However, it will fail fast on two challenges with the same name and namespace.

This function does not have any side-effects on the database or built/running challenge state, but changes that it detects will effect new builds. It is important to resolve any issues/errors it raises before making any other API calls for affected challenges. Failure to follow this guidance could result in inconsistencies in deployed challenges.

func (*Manager) DumpState ¶

func (m *Manager) DumpState(challenges []ChallengeId) ([]*ChallengeMetadata, error)

func (*Manager) EnableWorkerPlacement ¶

func (m *Manager) EnableWorkerPlacement()

EnableWorkerPlacement turns on worker selection for new instances. Only corkd calls this; without it, configured workers are still routable for operations on their existing instances, but new instances stay local.

func (*Manager) GetBuildMetadata ¶

func (m *Manager) GetBuildMetadata(build BuildId) (*BuildMetadata, error)

func (*Manager) GetChallengeMetadata ¶

func (m *Manager) GetChallengeMetadata(challenge ChallengeId) (*ChallengeMetadata, error)

func (*Manager) GetDockerfile ¶

func (m *Manager) GetDockerfile(challengeType string) []byte

Returns a byte array with the contents of the Dockerfile associated with `challengeType` (if it exists). If the challenge type does not exist, then an empty array is returned.

func (*Manager) GetInstanceMetadata ¶

func (m *Manager) GetInstanceMetadata(instance InstanceId) (*InstanceMetadata, error)

func (*Manager) GetSchemaState ¶

func (m *Manager) GetSchemaState(name string) ([]*ChallengeMetadata, error)

Returns the fully-nested metadata for the schema from challenges to the associated builds which belong to the schema through to the instances currently running (to include dynamic instances).

func (*Manager) HandOverChallenge ¶

func (m *Manager) HandOverChallenge(id ChallengeId, handOver *HandOver, options UpdateOptions) (*ChallengeUpdates, error)

HandOverChallenge records a challenge and the builds handed over with it, verifying first and writing only then. The verdict comes back the way an update reports one: the challenge in exactly one of Added, Updated, Refreshed, Stale and Unmodified, as recorded, its builds with their ids; and in Errors whatever could not be committed once the writes had begun, per build, as a rebuild reports its failures. An error instead is a refusal that wrote nothing: ErrLocalBuildPlane, ErrHandOverInvalid or ErrNotInRegistry, or the registry or the database not answering.

A build whose row already serves the generation delivered is left as it is, instances included, so handing the same thing over twice changes nothing -- the guarantee an update gives an unmodified challenge.

func (*Manager) ListBasePins ¶

func (m *Manager) ListBasePins() ([]BasePin, error)

ListBasePins reports the current pins alongside how many challenges use each.

func (*Manager) ListChallenges ¶

func (m *Manager) ListChallenges() []*ChallengeMetadata

Obtains a list of challenges with minimal version information filled into the metadata object.

mgr := NewManager(WARN)

for _, c := range mgr.ListChallenges() {
	fmt.Printf("%s (%s)", c.Id, c.Name)
}

func (*Manager) ListSchemas ¶

func (m *Manager) ListSchemas() ([]string, error)

Lists all schemas as currently defined in the database.

func (*Manager) ListWorkers ¶

func (m *Manager) ListWorkers() ([]WorkerInfo, error)

ListWorkers returns every configured worker with its health and the number of instances currently recorded on it.

func (*Manager) Prune ¶

func (m *Manager) Prune() error

func (*Manager) RefreshBasePins ¶

func (m *Manager) RefreshBasePins() ([]BasePin, error)

RefreshBasePins resolves every base reference the challenge directory uses to the digest the registry serves right now and persists the result. This is the one moment cork consults a mutable tag; builds never do.

Existing pins are re-resolved too, so a refresh is how a base is moved.

func (*Manager) RelocateArtifactBundles ¶

func (m *Manager) RelocateArtifactBundles(schema string) (int, error)

RelocateArtifactBundles moves a schema's existing bundles into the directory its destination now names, and reports how many it moved.

It exists because giving a schema a destination changes nothing a build is made of. Identity is source, flag format, pins and template; a schema is never hashed. So adding `destination:` to a schema whose builds are all complete leaves generateBuilds short-circuiting on buildsComplete, executeBuild never runs, no bundle is promoted, and the files stay where they were -- while SetArtifactNamespaces has already made the new directory and every message says the deploy succeeded. The artifact server goes on publishing the old prefix and the new one stays empty.

Only out of the artifact directory itself, and for that the same reason the prune has: a bundle is named "<build id>.tar.gz" and an id is unique only within one plane's database, so a file of that name under ANOTHER destination is not evidence of anything and is left alone. The artifact directory itself is where a schema's bundles were written before it had a destination, which is the case this exists for. A destination that changes from one name to another goes through migrate-schema, which drops the rows and rebuilds.

func (*Manager) RemoveChallenge ¶

func (m *Manager) RemoveChallenge(id ChallengeId) error

RemoveChallenge takes a challenge off the catalogue: on an external build plane the counterpart of the hand-over that put it there, for a challenge the build plane no longer has. It has to have no builds on record: those go with the schema that wants them (DeleteSchema) or with Destroy, never silently with the challenge. A local build plane accepts it too, though there the tree decides: the next update finds the challenge again unless it is gone from the tree as well.

func (*Manager) RemoveWorker ¶

func (m *Manager) RemoveWorker(ip string) error

RemoveWorker purges the worker: its instance rows (cascading port and container assignments) and its registry entry are deleted, and its poller is stopped. Containers still running on a live worker are not touched now: the box is expected to be on its way out. Should it ever be re-added, reconcileWorker removes them then. This is the path for a box that is terminated and recreated rather than rebooted or repaired: remove the old entry, worker-add the new box.

func (*Manager) SearchChallenges ¶

func (m *Manager) SearchChallenges(tags []string) []*ChallengeMetadata

Obtains a list of challenges which match on all of the given tags. If no tags are passed, then it returns the same results as `ListChallenges`. Wildcards are allowed as either '*' or '%' and the search is ASCII case insensitive.

func (*Manager) SetArtifactNamespaces ¶

func (m *Manager) SetArtifactNamespaces(bySchema map[string]string) error

SetArtifactNamespaces says which directory under the artifact directory each schema's bundles belong in: schema name to namespace, which a build plane fills in from every schema's destination. A schema named here with an empty namespace keeps the artifact directory itself -- a single-host deployment, or a schema with no destination. A schema not named here at all is a different case, and artifactDirForBuild treats it as one.

This is what keeps one build plane's bundles sorted for the several orchestrators it builds for: what publishes artifacts to players watches one namespace and uploads it under one prefix, so a challenge's files land where that destination's players look for them. It is also why a namespace is the destination's name exactly, with nothing prepended: the name an operator wrote in CORK_DESTINATIONS is the name on disk, and the prefix a deployment wants is a destination named that way rather than a convention cork invented.

Keyed on the schema rather than set around each build for a reason that cost a defect to find: an update rebuilds every build of a challenge whose source moved, and those rebuilds happen before any schema is converged and span every schema on the plane at once. A "current namespace" moved between schemas would send all of them to whichever directory happened to be set, while a build row already carries the schema it belongs to.

Called once, before anything is built, and never concurrently with a build. Nothing else calls it: an orchestrator holds no bundles.

func (*Manager) SetWorkerDown ¶

func (m *Manager) SetWorkerDown(ip string) error

SetWorkerDown marks a worker down administratively, taking it out of placement without touching its registry entry or instance records (unlike RemoveWorker, which purges both). Intended for a box about to be taken out of service, for a reboot, a repair or its termination.

This is the one state the probes will not lift, and that is the whole difference between it and the unresponsive a failing probe produces: the operator knows something the probe does not, so a box that keeps answering after being taken down stays down. Recovery is therefore AddWorker on the same IP, which rebuilds the connection and poller, or RemoveWorker and AddWorker of the replacement.

Note this also switches that worker's instances to the DB-only stop path (see stopInstance): their containers are no longer torn down over docker. The worker-add that recovers the box removes what those stops left behind. The read and the assertion are one critical section. recoverWorker swaps a worker's conn under the write lock, so releasing between them would let it land the assertion on a conn that has just been discarded: the PATCH would report success and the fresh conn would go on to reconcile and take placements. Holding the read lock across both means the two orderings are the only ones left, and recoverWorker refuses to recover a worker it finds down.

func (*Manager) Start ¶

func (m *Manager) Start(build BuildId, envVars map[string]string) (InstanceId, error)

Creates a running "instance" of the given build and returns its identifier on success otherwise an error. The optional envVars map provides extra environment variables to inject into the instance's containers. Keys in envVars should already include the "CMGR_" prefix. Pass nil if no additional environment variables are needed.

func (*Manager) Stop ¶

func (m *Manager) Stop(instance InstanceId) error

Stops the running "instance".

func (*Manager) Update ¶

func (m *Manager) Update(fp string) *ChallengeUpdates

This will update the global system state based off the changes that are detected by a call to `DetectChanges`. Specifically, in addition to updating challenge metadata (new and existing) it will rebuild and, if successful restart, existing challenges and then remove the metadata for challenges that can no longer be found. Challenges that have not been modified should not be affected.

In the presence of errors, this function will do addition and updates as best it can in order to preserve a consistent system state. If a build fails, the build keeps its previous generation (row, images, instances) while the challenge metadata is already updated; the challenge is then reported as Stale by every later DetectChanges, and rebuilt by every later update, until a rebuild succeeds. Additionally, in the presence of errors it will not perform any removals of challenge metadata (removing a built challenge is considered an error).

func (*Manager) UpdateSchema ¶

func (m *Manager) UpdateSchema(schema *Schema) []error

Updates the definition of the schema internally and then converges to the new definition. Certain updates are more expensive than others. In particular, updating the flag format will cause a complete rebuild of the state. Serialized with rebuilds and other schema operations; see CreateSchema.

func (*Manager) UpdateWithOptions ¶

func (m *Manager) UpdateWithOptions(fp string, options UpdateOptions) *ChallengeUpdates

UpdateWithOptions is identical to Update but takes explicit options; Update is equivalent to calling this with the zero-value UpdateOptions.

func (*Manager) WorkersConfigured ¶

func (m *Manager) WorkersConfigured() bool

WorkersConfigured reports whether any workers exist; used by corkd to decide between the legacy single-host gate and worker placement.

func (*UnknownIdentifierError) Error ¶

func (e *UnknownIdentifierError) Error() string