Edit a Workload Blueprint

Task

A Workload Blueprint is a reusable profile for a group of workloads. The Blueprint editor has four sections: About, Access, Runtime bindings, and Review. A new Blueprint walks you through them as steps. An existing Blueprint opens them as tabs. When you save an edit to an existing Blueprint, you see the impact on every workload that uses it first, and you confirm it.

Self-managed installations only

Workload Trust is available only in private, self-managed AIControls installations, on premises or in a cloud cluster that you run. It needs a dedicated cluster that you run, with Kyverno, Kyverno Runtime, and cluster OIDC and RBAC access in place. Nirmata-hosted (SaaS) workspaces don't include it. See Feature availability.

Before you begin

• You need an administrator session. Blueprints and the editor are administrator-only.
• Decide whether to reuse bindings. When you create a Blueprint, you can select an existing Access Binding or Runtime Binding, or create a new one inside the editor. See One Access Binding and one Runtime Binding.

Create a Blueprint

1. Open Inventory → Workloads, select Blueprints, and select New Blueprint. The editor opens at /workloads/new-blueprint.
2. About: enter the Name, a lowercase DNS label such as checkout-agents. You can't rename a Blueprint later. Enter the Purpose, one sentence of up to 500 characters on what the workloads are for. Choose the type; choose Other if none of the workload types fits. Choose the Autonomy tier: T1 · Human-directed (a person reviews every action), T2 · Semi-autonomous (acts on its own within policy guardrails), T3 · Highly autonomous (acts on its own, monitored against a baseline), or T4 · Fully autonomous (minimal oversight). A new Blueprint starts at T1. These are the same autonomy tiers that apply to identities. Optionally, answer Acts on behalf of a user: No if the workloads act as themselves with a virtual key, Yes if they act for a user and present that user's token, such as a personal access token, or Either. Then choose the Highest data classification this workload may access: Public, Internal, Confidential, Restricted, or Not classified. See Data classification.
3. Access: choose Use an existing Access Binding and select one, or choose Create a new Access Binding. See Choose or create the Access Binding.
4. Runtime bindings: choose Use an existing Runtime Binding and select one, or choose Create a new Runtime Binding. See Choose or create the Runtime Binding.
5. Review: choose the Starting mode: Learn first (Audit) or Enforce. Enforce is unavailable, with the reason shown, until the Access Binding grants at least one server, tool selector, Toolset reference, or model selector. Optionally turn on Allow automatic registration, which lets a ready workload that opts in with a label register against this Blueprint in Audit mode. See Register workloads automatically. Check the summary. Select Advanced (JSON) to see the whole document.
6. Select Create Blueprint. AIControls creates the Blueprint, and any new bindings, in one audited transaction: either everything is saved, or nothing is.

The step headers and tabs show a status for each section. A warning marks a section that needs attention: a Purpose that needs review, an access level you haven't declared, Enforce with no grant, or a missing binding.

To create a Blueprint from what a workload already does, see Turn a workload's learned access into a Blueprint.

Choose or create the Access Binding

Only an Access Binding grants models and MCP tools. A Blueprint has exactly one.

1. Open the Access section.
2. To reuse a binding, choose Use an existing Access Binding and select it. The section shows the binding's grants read-only, and the text "Used by N Blueprints, M workloads." To change the binding itself, select Edit binding. It opens the Access Binding editor in place, the same one as in Setup → Settings → Access Bindings. Saving goes through the impact flow, because the change affects every Blueprint and workload that uses the binding, and every team, group, user, and agent the binding applies to.
3. To create a binding, choose Create a new Access Binding. The Name is prefilled with the Blueprint's name, and it follows the Blueprint name until you edit it. The name is fixed after you create it.
4. Under Allowed models, choose models from the list, and select Add model grant. The list shows every model your enabled upstreams advertise. When the same model ID is on more than one upstream, you choose (any upstream) or one upstream, for example claude-sonnet-4 (bedrock). To grant a pattern or a model that isn't listed, type it, for example gpt-4*. A typed model matches every upstream. See Where the model list comes from.
5. Under Allowed MCP tools, choose All tools, Selected tools, or None for each connected server. To grant a pattern, such as read_* on every server, use Add a tool pattern. See Control MCP tool access. To reference a Toolset, add toolsetRefs on the Advanced (JSON) tab of the Review section.

The section warns about each granted MCP tool that's classified above the Blueprint's data classification ceiling.

Where the model list comes from

The Allowed models list comes from GET /api/v1/model-catalog. It runs the same model discovery as Preview discovered models in Settings → Providers on every enabled upstream, and caches the result for a minute. An edit to an upstream refreshes it. The response lists each model ID with the upstreams that serve it:

{
  "models": [
    { "id": "claude-sonnet-4", "upstreams": ["anthropic-prod", "bedrock"] },
    { "id": "gpt-4o", "upstreams": ["openai-prod"] }
  ],
  "failed": [{ "upstream": "vertex", "error": "context deadline exceeded" }]
}

When discovery fails for an upstream, its models aren't listed, and the editor names the upstream under the list. You can still type its model IDs.

To stop one grant for a single workload without changing the binding, use Block for this workload on the workload's AI access tab. See Deny a grant for one workload.

Choose or create the Runtime Binding

A Blueprint has exactly one Runtime Binding. It holds the four access levels and the environment values.

1. Open the Runtime section.
2. To reuse a binding, choose Use an existing Runtime Binding and select it. The section shows its levels read-only. Edit binding opens the impact flow.
3. To create a binding, choose Create a new Runtime Binding. The Name is prefilled with the Blueprint's name and is fixed after you create it.
4. Answer the Network, Files, Programs, and Kubernetes API cards. See What the Runtime cards mean. Select Allow kubectl exec in the Programs card only for a fleet you debug in place. See kubectl exec is blocked by default.
5. The section links to the cluster Environment defaults, which supply the Services, base files, and interpreters that the levels expand to. A new binding inherits every default. To override a value for this binding, create the binding first, and then edit it in Settings → Workloads under Environment values. See Configure Workload Protection policy.

What the Runtime cards mean

Each Runtime card has a plain-language question, an access level for each answer, and a tag that says how AIControls enforces it. Hold the pointer over the tag to see the card's enforcement limits.

Card	Question	Access levels	Tag
Network	Where can it connect?	None; In-cluster only; AIControls gateway and in-cluster (recommended); Anywhere (high risk)	Enforced
Files	Which files can it open?	Platform baseline only; Its own volumes	Enforced on nodes with the open/exec hooks
Programs	What can it run?	Its entrypoint only; Entrypoint plus shells and interpreters	Enforced on nodes with the open/exec hooks
Kubernetes API	Does it use the Kubernetes API?	No; Read only	Observed only

The Kubernetes API answer is checked against the ServiceAccount's RBAC. It never grants access.

A card with no answer shows Not declared: no constraint. An unanswered question declares no constraint, which is the widest value, for every workload that uses the Blueprint. Answer every card unless you mean it.

Edit a Blueprint

When you edit a Blueprint, the four sections are tabs, so you can go straight to the one you want to change.

1. Open Inventory → Workloads, select Blueprints, and select the Blueprint's row. Its drawer opens.
2. Select Edit. The editor opens at /workloads/blueprints/<name>/edit, titled Edit followed by the Blueprint's name.
3. Change the About details (the Purpose, type, autonomy tier, whether the workloads act on behalf of a user, or data classification), select a different binding in Access or Runtime bindings, or change the Starting mode or Allow automatic registration on Review. The name is read-only.
4. Select Review and save →. The Review section lists your changes.
5. Select Preview impact. A dialog titled Save followed by the Blueprint's name shows what the impact preview shows for every workload that uses the Blueprint.
6. Select Confirm and save. The editor returns to the Blueprint.

In edit mode, you can select an existing Access Binding or Runtime Binding, but you can't create one. Create a new Access Binding and Create a new Runtime Binding are unavailable. To use a new binding, create it first: New Access Binding in Setup → Settings → Access Bindings, or New in the Runtime Bindings card of Settings → Workloads. Then select it in the editor.

Saving applies the change to every workload that uses the Blueprint, including workloads in Enforce, and records a workload_blueprint.updated event in the configuration audit with the impact counts. A Blueprint has no revision history, so the audit event is the record. The impact preview doesn't ask for an acknowledgment. If the Blueprint or its workloads change after the preview, the dialog shows the refreshed preview. Review it and select Confirm and save again. If someone else saves the Blueprint while you edit, the editor shows Someone saved this Blueprint while you were editing. Select Start over to reload it.

A change to the contents of a binding is a different edit. To edit the grants in an Access Binding, or the levels in a Runtime Binding, see Review and restore a binding change.

Edit the document as JSON

On Review, the Advanced (JSON) tab shows the whole document: purpose, type, autonomy, delegation, dataClassification, accessBinding, runtimeBinding, startingMode, and allowAutomaticRegistration. Edit it and select Apply. AIControls checks the shape first, updates the sections, and previews the result. The preview reports anything the server refuses.

Change one workload instead

To narrow or widen an answer for a single workload, don't edit its Blueprint. Edit the workload's registration and select Customize for this workload. See Customize for this workload.

Use the API

PUT /api/v1/workload-blueprints/{blueprint} creates a Blueprint and returns 201. The body has these fields:

Field	Meaning
purpose	Required. One to 500 characters.
type	The workload type, such as agent, or other.
autonomy	The autonomy tier: T1, T2, T3, or T4. AIControls still accepts the earlier values supervised and autonomous, and reads them as T1 and T2.
delegation	Optional. Whether the workloads act on behalf of a user: none, user, or either. Omit it when you don't know yet. It's advisory: nothing enforces it yet.
dataClassification	Optional. public, internal, confidential, or restricted.
startingMode	audit or enforce.
allowAutomaticRegistration	Optional. true lets the automatic registration controller register opted-in, ready workloads against this Blueprint. Defaults to false.
accessBinding	Either {"id": "<binding ID>"} or {"create": {"name", "servers", "toolSelectors", "modelSelectors", "toolsetRefs"}}.
runtimeBinding	Either {"id": "<binding ID>"} or {"create": {"name", "levels", "environment"}}.

The create is atomic. To edit an existing Blueprint, send POST /api/v1/workload-blueprints/{blueprint}/preview with the changes, then PATCH /api/v1/workload-blueprints/{blueprint} with the same changes and the preview's previewHash. Both take expectedVersion, which is required, and any of purpose, type, autonomy, delegation (an empty string clears it), dataClassification (an empty string removes the ceiling), accessBindingId, runtimeBindingId, startingMode, and allowAutomaticRegistration. A PATCH never creates a binding. It returns {"blueprint": {...}, "impact": {...}}. A Blueprint PATCH always needs the previewHash.

GET /api/v1/workload-blueprints and GET /api/v1/workload-blueprints/{blueprint} return the Blueprint with a usage object that counts the workloads that use it (members, audit, and enforce) and the names of its two bindings.

code	Status	Cause
invalid_blueprint	400	The body is invalid: a missing Purpose, a missing or ambiguous binding choice, or a new binding that fails validation.
unknown_llm_upstream	400	A new Access Binding names an LLM upstream that isn't configured.
impact_unconfirmed	409	A PATCH has no previewHash. The response carries the current preview.
impact_changed	409	The previewHash is stale: the Blueprint, a binding, or a workload changed after the preview. The response carries the current preview. Preview again.
conflict	409	The expectedVersion is stale. Read the Blueprint and retry.
blueprint_name_taken	409	A PUT names a Blueprint that exists. Edit it with PATCH.
binding_name_taken	409	A new binding's name is taken. Choose another name, or select the existing binding.
blueprint_binding_missing	409	A selected binding no longer exists.

Related

• Workload Blueprints and Workload Registrations
• Review and restore a binding change
• Register a workload