Decisions
Why environments work the way they do. A job's are Jobs'.
The file
These choices keep setup portable while preserving the distinction between the machine, its users and the work that an environment runs.
Why is this public, and in its own module?
The file and lnk env on your own boxes are useful to anyone with a
cloud account, so they're public, and they name no cloud: a box is lnk box's, on whichever account, reached by running lnk. Its crates know
no box, cloud or job: what a job adds (its record, its box made for it,
a cloud that runs it) is the job module's, which hands an environment
the stages to run.
Why "environment" and "job"?
An environment is what a machine needs before work starts. A job is an environment and a command, run to the end, that can be cancelled and says how it ended; job, task and run mean the same, and job is the word. CI is a job started by a push, a scheduled report one started by the clock.
Why is a path given to every command?
The file lives in the repository it sets up, and a repository can hold
several. Every command takes its path (--env, or the file itself), so
nothing is guessed from the folder you're in.
Why do the image's stages run from the home folder, and the rest from workdir?
A stage saved in the image sets the machine up, and the first often
makes the folder the work happens in: a clone run from a workdir that
isn't there yet would have nowhere to start. So those start at the home
folder and name their paths from it. Everything run at every start, a
stage with when = "start", a service, its ready and reset, a job's
stages and an agent, comes after the image and works on what it made:
it starts at workdir, which is then there, or fails naming it. A
relative path in a service and in the job it serves names the same
file.
Why do services run in Docker only on a box of their own?
The sandbox refuses Docker's socket, which runs whatever it's sent outside the sandbox. A service that needs Docker runs as root, which gives its job a box of its own.
Why do some names stay as they were?
The agent spec's [instructions] environment describes its files and
connections, which an environment sets up. Each name describes its
subject, and its page defines that meaning.
Why does root say a machine is a box?
A box runs an environment's root stages, and your computer never does,
so what says which must be something no program of yours can change:
an agent with no sandbox, a script you ran, or another user of a shared
machine. /etc/lnk/kind.toml is written as root at a box's first
boot, before anything of yours runs there, and refused when anyone but
root could write it; whoever can write it as the machine's root could
run anything as root anyway.
User namespaces
In a user namespace of one's own, a file mounted over it seems root's: lnk checks its user IDs are the
machine's, a best effort the same namespace can fake, and what holds
is that a root run goes through sudo, which gains no root there.
A missing marker
Without it a machine is a computer, so a mistake keeps root stages
off, never on. ~/.lnk/safe/machine.toml is yours, named apart from
root's so the line between them shows, and holds the machine's ID and
name and your rules for it, none of which loosens anything root does.
Images and credentials
The file says the box's OS and processor
too, since an image built on it is for those. An image built on a box
(lnk env image create here) doesn't save itself: saving is its cloud
account's, which is the computer's that made the box, since a box holds
no cloud credential. So the stages run on the box, and it says the lnk box image create that computer runs to keep it.
Why does every command take the file as --env, and the place as --on?
One grammar for every command: the environment file is always --env,
and the place a command acts on, a cloud account, a box or here, is
always --on, as lnk agent create --on takes it, never a word whose
meaning hangs on what it names. A command's word is its object: the
service lnk env reset redis --on web-1 resets, which the box knows
the environment of, since it was made with it. Making a box with an
environment is lnk box create --env's, as every machine is made by
lnk box create; lnk box start starts a stopped one. Current commands use this grammar.
Why parallel groups?
A stage may group independent commands under parallel. Members start
together, each in its own sandbox; all finish before the next stage.
The first failure received determines the group's result. A group has
one deadline within the overall build or job limit, alongside each
member's own timeout. Group shape and order are part of the image hash.
The environment spec
The specification separates setup from allocation and workload. Each key has an owner, and the file carries portable setup rather than another module's policy.
Why machines, users, environments and runs?
Each subject has one owner: a machine is a computer or box; users belong to that machine; an environment defines what a machine made from it has; a run is a command executed as a user in a sandbox. Stages, services, job stages, agents and SSH sessions are runs with different start and end conditions. A job and an agent therefore work in the same environment.
Why aren't the box, the job and the repository in it?
An environment describes its setup. Machine size belongs to a box spec, and a job's stages belong to its job spec. Cloning a repository is a setup stage, using the same network rules as any other command. Multiple repositories are multiple stages. Unsupported keys are refused instead of silently changing the meaning of a file.
Why is the OS optional on an environment?
A box has an OS always (its spec's os, which has a default). An
environment that names none runs on any, so an agent in it moves
between machines of different ones; its image is built for each OS and
processor it's asked on, the hash saying which. One that names an OS
refuses a box of another, and here on another, rather than build
something that isn't what it says.
Why user, and not root = true?
A box has many users: its own, root, the people let in with lnk box's
user add, and those a stage makes. root is one of them, so a run
names its user, and root runs outside any sandbox because it must.
Who comes to a box is the box's to say, never the environment's, which
says what a machine has.
Why does only a box take an image?
An image is a machine saved whole, and only a box is made to be saved:
your computer holds you, your keys and everything else that's yours.
So lnk env image create runs on a box, and lnk env's setup runs the build
stages on your computer without saving anything, refusing root's,
which would change the machine outside any sandbox.
Why is an agent's sandbox its own file?
An agent's sandbox follows it between machines and is granted through
lnk agent permission add. Its own file defines what the agent may do, never a
stage's.
Why does the environment take no flags?
Its stages and services are lists of tables, which a command line
doesn't hold, and a person writes an environment once and keeps it
beside the code it sets up. So --env <file> names it everywhere, and
lnk env's spec prints it back.
Why are its paths printed relative?
The sandbox specs and inputs an environment names are copied beside it to each box, and found there from its folder. Absolute paths would name your computer's folders on a box.