Learning a workload in staging
A fresh deployment learns what its workload does before it can enforce. That takes the first 20 minutes or more of the deployment's life, and it happens in prod. deploy.sh prelearn moves that learning to your staging. It deploys your workload to an attested CVM there, drives it with your own tests, and stops once the Policy Manager has written a workload layer for the image digest.
The layer stays in the staging Policy Manager. Exporting it and loading it in prod is a separate step that is not in deploy.sh yet.
Run it
Use the config of a staging deployment, never the prod one. prelearn runs a full deploy first, so it takes every flag deploy takes.
./scripts/deploy.sh prelearn --config staging.yaml --exercise ./tests/run-integration.sh
The exercise script is anything that makes the workload do what it does in prod: your integration tests, or a replay of recorded traffic. It runs on your machine and gets these variables:
| Variable | Value |
|---|---|
POLARIS_PRELEARN_ENDPOINT | https://<cvm address>, the CVM's public endpoint. Empty if the Terraform state names none. |
POLARIS_PRELEARN_CLOUD | The cloud, such as gcp. |
POLARIS_PRELEARN_NAME | The deployment's name. |
POLARIS_PRELEARN_RUN | 1 on the first run, 2 on the next, and so on. |
prelearn runs the script again each time it exits 0, until the learners are done, because the learners stop on behaviour that repeats. If your script can run only once, pass --exercise-once. If a run exits non-zero, prelearn stops and fails, since a layer learned from a failing run would hold whatever the failure did. When the learners are done, prelearn stops the script with SIGTERM.
Without --exercise, a GCP deployment's soak driver sends one request through the proxy every 60 seconds. That only teaches the layer what one request does. The other clouds have no soak driver, so pass --exercise there.
| Flag | Meaning |
|---|---|
--exercise F | The script that exercises the workload. |
--exercise-once | Run it once instead of until the learners are done. |
--prelearn-timeout D | Give up after D, such as 90m. The default is 2h. |
--prelearn-report F | Also write the report to F as JSON. |
While it runs
prelearn prints the same autolearn progress view as status each time it changes, and the learners it still waits for:
Prelearn, 6m in:
IMA cvm-7f3a observing stable 4/10, 23 cycles observed, watched 6m/10m
Profile/app cvm-7f3a observing stable 2/10, 23 cycles observed, watched 6m/10m
waiting on: repetitions:network
waiting for: ima on cvm-7f3a: repetitions; profiles on cvm-7f3a: repetitions:network
The Policy Manager decides when learning is done, by its per-category stop rule. A session is done when it has applied what it learned to the workload layer. prelearn waits for every session that writes the workload's own layer. Sessions for the host, for Polaris's own containers and for the kernel write the platform layer, so they do not hold the run.
Two things keep learning short and honest:
- The report interval. While a learner still observes the CVM, the Policy Manager asks it for a report every 10 seconds. Once the learners are done, the CVM goes back to the deployment's own interval. You set nothing for this, but it needs an observation window, so
prelearnrefuses--autolearn-window 0. - The observation window. No session finishes before it has watched the workload for the window, 10 minutes by default. If your workload has jobs that run less often, set
--autolearn-windowto cover them.
The learners only take evidence from reports that passed the platform check (L1). A CVM whose platform fails teaches the layer nothing, and the run times out.
The result
When it finishes, prelearn reads the layer back from the Policy Manager. It checks that the Policy Manager keeps the version the learners wrote, names it as current, and that the signed layer head names it, so a restart loads it. Then it prints what was learned:
Workload layer app@sha256:4f1c...
Version: 3 (in use)
File hash: 9a0e...
Learned over: 64 cycles, 11m watched
binaries: 4 learned, stable 12/10
network: 6 learned, stable 10/10, last new 2026-11-19T10:05:00Z
syscalls: 87 learned, stable 10/10, last new 2026-11-19T10:02:00Z
IMA: applied in version 2 on cvm-7f3a after 41 cycles
Seeded calls: the layer seeds accept, accept4, connect, execve, openat, but
the binary (static Go, /app/server) cannot call execve. The
layer allows a syscall the workload does not use.
If the layer already enforced in staging, for example after a promotion, the new version is held as a candidate and the CVM is still checked against the version before it. The report says so.
The seeded syscalls
Every workload profile seeds the five syscalls the sentinel traces: accept, accept4, connect, execve and openat. That is the whole set it can see, so seeding them catches nothing the learners were watching. It also means the learned workload layer allows exactly those five, whether or not the workload makes them.
prelearn reads the deployed image's own binary and says which of the five it can actually make. A seeded syscall the binary never calls, like execve in a static Go server that does not shell out, is dead weight the layer still allows. The line names the image kind and flags any such call.
It reads the binary's symbol table, so it only speaks for a static binary that keeps one. A stripped, dynamically linked or interpreted image reports not checked with the reason, rather than a false pass. The check warns, it does not bound: the kernel, not this line, is what the layer enforces against.
prelearn exits non-zero when the exercise fails, when a learner times out, when --prelearn-timeout passes, when it cannot read the learn lists at the start, when the Policy Manager already learned this digest on this CVM (below), or when the Policy Manager does not keep the version the learners reported. What the learners applied before that stays in the Policy Manager.
Running it again
The Policy Manager keeps a finished learn session for 24 hours, so the learn lists can still hold what an earlier run left. prelearn only counts sessions for the image digest this deploy pinned, and ignores every session that was already finished when the run started.
prelearn reads the learn lists once at the start to see which sessions are already finished. If that read fails, it tries again, 4 times in all, and then fails, since a failed read would look like a Policy Manager with nothing learned yet.
- A new image digest. The deploy replaces the CVM, and the new CVM gets new learn sessions. The earlier digest's sessions are ignored, whether they applied or timed out.
- The same image digest on the same CVM. The Policy Manager starts one learn session per CVM and container, and does not start a second one. So there is nothing new to learn.
prelearnwarns at the start, waits 5 minutes for a new session in case the CVM was replaced, and then fails with what the earlier run learned. That layer is still in the Policy Manager, andGET /api/v1/layers/versionsshows it. To learn the digest again, the CVM has to be new, for example withdeploy --force-replace, which replaces the Policy Manager too.
Limits
- On-prem is not supported yet. There
deployonly writes the artifact set, andlaunchstarts the guests. - Several containers.
deploy.shdeploys one workload image, andprelearnlearns the layer for that image's digest. A session for any other digest is ignored. Where two containers run that same image, each gets a layer of its own, keyed by container and digest, andprelearnwaits for both. How a workload of several images should key its layers is still open. - Stopping the script.
prelearnsends SIGTERM to the script, not to processes the script started. Have your script stop its children when it gets SIGTERM.
With --json, prelearn prints a prelearn event with status progress each time the view changes, and one with status ok and the report at the end. See Scripting deploy.sh with --json.