Behaviors
A behavior is one thing that osapi manages on a host, for example kernel
parameters. A contributor writes it one time, as a Go definition in
internal/behaviors/<name>/. osapi builds from that definition all the parts
that the rest of the system needs. Thus a behavior looks the same in the API,
the CLI, the SDK, the docs and the agent.
What a definition holds
- Methods. Each method is a read or a write, with an input type and an
output type. The verb and the name set the HTTP method, the route, the command
and the permission. For example, the
updatemethod of sysctl isPUT /api/node/{hostname}/sysctl/{key}andosapi client node sysctl update, and it needssysctl:write. - Tags on the types. They give the names, the descriptions and the validation rules. osapi makes from them the request fields, the CLI flags, the schemas of the spec and the table columns.
- Settings. These are the agent configuration of the behavior, under
behaviors.<name>. Each setting has an environment variable and anosapi agent startflag. - Requirements. These are the other behaviors that the behavior uses. It calls their methods on the same host.
- Platforms. For each platform, for example Debian, the definition tells how
to make the provider that does the work. On a platform that the behavior does
not declare, its methods report
skipped. They do not fail. - The programs that it runs with sudo. The preflight of the agent checks them.
- Examples and refusals. An example is a sample call with the changes that it makes on the host. A refusal is a call that the method rejects. osapi makes the docs pages and the tests from them.
What it means for an operator
- The binary describes itself.
osapi behavior listandosapi behavior get --name <name>show each behavior that this build has: its routes, permissions, platforms, settings and types. You do not need to look in a different place, and the answer always agrees with the build that you run. - The permissions come from the methods. The permissions of a behavior are
<name>:readand<name>:write. The built-in roles give them.osapi token roles listlists each permission of each role. - Skipped is not failed. In a fleet with more than one platform, the hosts
that a behavior does not run on report
skipped. When the agent starts, it writes to the log the behaviors that it cannot run. - Settings are agent configuration.
osapi config listshows them with the other settings, with their environment variables and flags. - The telemetry is the same for each behavior: one span for each call, and three metrics. Observability describes them.
Behaviors built on other behaviors
A behavior can use other behaviors. sysctl writes one file for each kernel
parameter. A different behavior, managedfile, keeps the files that osapi wrote
apart from the files of other tools:
- The definition declares it. The definition of sysctl has
behavior.Requires(managedfile). - The agent makes the provider of the required behavior first. Then it gives that provider to the behavior that requires it. A method calls the methods of the other behavior directly, on the same host and in the same job. Thus there is no second job and no extra round trip.
- A required behavior without a provider on the platform makes the behavior
that requires it unsupported there too. Its methods report
skipped. behavior validatefails when a requirement is not registered, and when requirements make a cycle.behavior getand the Behaviors pages show what each behavior uses, and what uses it.
The behaviors that a behavior calls, and the ones that they call, are a
chain: dns → netplan → managedfile. The chain has the name of the behavior
at its top. It is not declared on its own: Requires on each behavior makes it.
osapi behavior chain shows and checks the chains:
osapi behavior chain listshows each chain as a tree, and what calls each building block.osapi behavior chain get --name dnsruns each example of dns on the fake host thatgo testuses, and shows each call that it makes: what each call sends and gets. Thus it shows what the code does now.osapi behavior chain validatechecks the chain rules. A required behavior is registered, and no requirement makes a cycle. An internal behavior has a behavior that requires it. A provider calls only the behaviors that its behavior requires. An example calls each behavior that a behavior requires.osapi behavior chain spec gettells how to build a chain, what happens when a step fails, and the building blocks of the binary.
A behavior that only other behaviors use is internal. managedfile has no
route, no command and no permissions, because only other behaviors call it.
behavior list and its docs page still show it, with the behaviors that use it.
A chain across hosts or across steps is a workflow, not a requirement. In a workflow, the output of one call is the input of the next call. osapi-orchestrator does workflows.
Beside the hand-written domains
Behaviors are new. Most of what osapi manages is still in domains that people
wrote by hand. Each domain has its own handler, processor and commands. A domain
moves to a behavior in one change: the behavior goes to /api and
osapi client, and the hand-written code is deleted. The two never run side by
side. Checks name the code that is left to delete. sysctl is the first behavior.
Where to read more
- Behaviors: the page of each behavior in this build, generated from its definition.
- Building a behavior and Your first behavior, for a contributor.
- Behaviors in the specifications and the migration plan, for the design.