Create an image recipe.
curl --request POST \ --url https://stratum.example.com/v1/projects/example/compute/image-recipes \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "displayName": "example", "description": "example", "base": { "imageId": "example", "catalog": "example", "imageName": "example", "recipeId": "example", "latest": true }, "buildInstance": { "instanceType": "example", "subnetId": "example", "securityGroupIds": [ "example" ], "iamInstanceProfileId": "example", "keyPairName": "example" }, "steps": [ { "name": "example", "cloudInit": "example", "runCommand": "example", "sudo": true, "timeoutSeconds": 1 } ], "tests": [ { "name": "example", "runCommand": "example", "sudo": true, "timeoutSeconds": 1 } ], "output": { "namePattern": "example", "description": "example", "visibility": "private", "sharedWith": [ "example" ], "tags": { "additionalProperty": "example" }, "keepLast": 1, "keepLastAction": "deprecate" }, "tags": { "additionalProperty": "example" }, "distribution": { "launchTemplates": [ { "launchTemplateId": "example", "setDefault": true } ], "instanceRefresh": { "autoScalingGroupIds": [ "example" ], "minHealthyPercentage": 1, "maxBatchSize": 1, "instanceWarmupSeconds": 1 } }, "schedule": { "cron": "0 3 * * 1", "timeZone": "example", "onlyIfBaseChanged": true } }'Declares what to build: a base, the throwaway
build instance’s shape, cloud-init and run-command steps, tests, and
the output image. Nothing runs until actions/build. Gated on
compute:CreateImageRecipe; quota compute.image_recipes.count.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”Create (POST) or replace (PUT; name is fixed) an image recipe.
object
Where a build starts from. Exactly one of imageId,
catalog, imageName, recipeId is set. imageName is a glob over the
project’s own active images and recipeId chains to another recipe’s
last succeeded output; both resolve to the newest match at build time.
object
A /v1/images/catalog key (e.g. debian-13) — the active public image imported from it.
A glob over the project’s own image names (e.g. web-golden-*).
Another recipe of the project; its last succeeded build’s output.
Always true for imageName and recipeId at 2.0.
The throwaway build instance’s shape; it is launched in the recipe’s project and always terminated.
object
Omitted = the project’s default subnet.
One provisioning step: exactly one of cloudInit (a cloud-config or
shell document; every cloud-init step is concatenated into the build
instance’s user-data and runs as root at first boot) or runCommand
(run in order through run-command once the instance is up, as
the agent’s login user). sudo: true runs a run-command step as root
granted by the instance agent only on an instance carrying the
stratum.dev/image-build tag it reads from IMDS, never on an ordinary
instance, and never written to the guest.
object
Per-step deadline for a run-command step (default 600).
A run-command whose non-zero exit fails the build (no image is produced).
object
The image a build produces.
object
A Go template over {{.Recipe}}, {{.BuildNumber}}, {{.Date}} (YYYYMMDD); default {{.Recipe}}-{{.BuildNumber}}. Must render a valid image name.
Default private; public publishes the output (subject to the org’s public-images toggle); shared shares it with sharedWith — and publishes instead while none of those projects exist yet (the operator recipes name projects that arrive with /069).
Project ids, with visibility: shared.
AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no
leading/trailing whitespace) mapped to freeform UTF-8 values
(0-256 bytes). Max 50 tags per resource. Reserved prefixes
(stratum.dev/, stratum.platform_health., stratum:,
aws:) return 400 RESERVED_NAMESPACE on customer input.
PATCH replaces the whole map..
object
After a successful build, retire the recipe’s older outputs beyond N (0 = keep all). What “retire” means is keepLastAction.
How keepLast retires an older output. deprecate (the default) hides it from default listings and launches keep working; disable refuses launches; delete deregisters it.
Only delete frees compute.images.count — the quota counts every image the project still owns, whatever its lifecycle state. A recipe that builds on a schedule and only deprecates will therefore fill its project’s image quota, and once it is full no build in that project can finish. The default stays deprecate so that upgrading never starts deleting images by itself; the seeded operator recipes ask for delete.
A delete is never forced: an image a launch template still names is left alone and the refusal is logged, so retiring cannot break a live Auto Scaling group.
AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no
leading/trailing whitespace) mapped to freeform UTF-8 values
(0-256 bytes). Max 50 tags per resource. Reserved prefixes
(stratum.dev/, stratum.platform_health., stratum:,
aws:) return 400 RESERVED_NAMESPACE on customer input.
PATCH replaces the whole map..
object
The “bake → roll” half. After a successful build the
builder creates a new version of each launch template with the output
image (every other field copied from $Latest, setDefault as
configured), then starts a instance refresh per group toward
$Latest. Saving a recipe with launchTemplates needs
asg:CreateLaunchTemplateVersion on each template and with
instanceRefresh asg:StartInstanceRefresh on each group. A refresh
refused (one already in progress) is recorded on the build as that
target’s error; the build still succeeds and the version stays.
object
object
object
Build on a schedule. Five-field cron in timeZone
(default UTC). A missed window fires once (the next firing is computed
from now). With onlyIfBaseChanged a firing is a recorded no-op when
the resolved base is the image the last succeeded build used; a build
already in flight is a no-op too. What the last firing did is on the
recipe as lastScheduleAt / lastScheduleResult.
object
Example
0 3 * * 1IANA zone name; default UTC.
Responses
Section titled “Responses”The recipe.
An image recipe (irc-…).
object
Set on a platform-owned row; absent on a tenant’s own.
object
The owner: the Auto Scaling group id, or for platform the component (front-door, pack:platform-health, default-network, operator-recipe).
Where a build starts from. Exactly one of imageId,
catalog, imageName, recipeId is set. imageName is a glob over the
project’s own active images and recipeId chains to another recipe’s
last succeeded output; both resolve to the newest match at build time.
object
A /v1/images/catalog key (e.g. debian-13) — the active public image imported from it.
A glob over the project’s own image names (e.g. web-golden-*).
Another recipe of the project; its last succeeded build’s output.
Always true for imageName and recipeId at 2.0.
The throwaway build instance’s shape; it is launched in the recipe’s project and always terminated.
object
Omitted = the project’s default subnet.
One provisioning step: exactly one of cloudInit (a cloud-config or
shell document; every cloud-init step is concatenated into the build
instance’s user-data and runs as root at first boot) or runCommand
(run in order through run-command once the instance is up, as
the agent’s login user). sudo: true runs a run-command step as root
granted by the instance agent only on an instance carrying the
stratum.dev/image-build tag it reads from IMDS, never on an ordinary
instance, and never written to the guest.
object
Per-step deadline for a run-command step (default 600).
A run-command whose non-zero exit fails the build (no image is produced).
object
The image a build produces.
object
A Go template over {{.Recipe}}, {{.BuildNumber}}, {{.Date}} (YYYYMMDD); default {{.Recipe}}-{{.BuildNumber}}. Must render a valid image name.
Default private; public publishes the output (subject to the org’s public-images toggle); shared shares it with sharedWith — and publishes instead while none of those projects exist yet (the operator recipes name projects that arrive with /069).
Project ids, with visibility: shared.
AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no
leading/trailing whitespace) mapped to freeform UTF-8 values
(0-256 bytes). Max 50 tags per resource. Reserved prefixes
(stratum.dev/, stratum.platform_health., stratum:,
aws:) return 400 RESERVED_NAMESPACE on customer input.
PATCH replaces the whole map..
object
After a successful build, retire the recipe’s older outputs beyond N (0 = keep all). What “retire” means is keepLastAction.
How keepLast retires an older output. deprecate (the default) hides it from default listings and launches keep working; disable refuses launches; delete deregisters it.
Only delete frees compute.images.count — the quota counts every image the project still owns, whatever its lifecycle state. A recipe that builds on a schedule and only deprecates will therefore fill its project’s image quota, and once it is full no build in that project can finish. The default stays deprecate so that upgrading never starts deleting images by itself; the seeded operator recipes ask for delete.
A delete is never forced: an image a launch template still names is left alone and the refusal is logged, so retiring cannot break a live Auto Scaling group.
AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no
leading/trailing whitespace) mapped to freeform UTF-8 values
(0-256 bytes). Max 50 tags per resource. Reserved prefixes
(stratum.dev/, stratum.platform_health., stratum:,
aws:) return 400 RESERVED_NAMESPACE on customer input.
PATCH replaces the whole map..
object
The “bake → roll” half. After a successful build the
builder creates a new version of each launch template with the output
image (every other field copied from $Latest, setDefault as
configured), then starts a instance refresh per group toward
$Latest. Saving a recipe with launchTemplates needs
asg:CreateLaunchTemplateVersion on each template and with
instanceRefresh asg:StartInstanceRefresh on each group. A refresh
refused (one already in progress) is recorded on the build as that
target’s error; the build still succeeds and the version stays.
object
object
object
Build on a schedule. Five-field cron in timeZone
(default UTC). A missed window fires once (the next firing is computed
from now). With onlyIfBaseChanged a firing is a recorded no-op when
the resolved base is the image the last succeeded build used; a build
already in flight is a no-op too. What the last firing did is on the
recipe as lastScheduleAt / lastScheduleResult.
object
IANA zone name; default UTC.
The schedule’s next firing.
What the last firing did — built ib-… or skipped: ….
Builds requested so far; the next build’s number is buildCount + 1.
Example
{ "ownedBy": { "kind": "auto-scaling-group" }, "output": { "visibility": "private", "keepLastAction": "deprecate" }, "schedule": { "cron": "0 3 * * 1" }}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Conflicting state.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Request rate limit exceeded. The API-boundary throttle caps request throughput per principal and per project; code is RATE_LIMITED (distinct from the quota engine’s QUOTA_EXCEEDED). The Retry-After header carries the seconds to wait. Applies to any authenticated endpoint — it is enforced by middleware, not per-path.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Headers
Section titled “Headers”Seconds to wait before retrying.