Skip to main content

Register Workloads Automatically

Tasks

Developers add one label to a workload. When the workload is ready and an administrator has allowed it, AIControls registers the workload in Audit mode against a Workload Blueprint. A label never grants access: the Blueprint's Access Binding does.

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.

A workload registers automatically when all of these hold:

  • It has the label aicontrols.nirmata.io/auto-register: "true".
  • It runs in a namespace on the automatic registration list. System namespaces are never on it.
  • It passes all seven readiness rules, so it reads Ready to register.
  • Its Blueprint has Allow automatic registration turned on.

If any condition fails, the workload stays unregistered, and the drawer says why.

Turn on automatic registration​

Do this once, as an administrator. Automatic registration is off by default.

  1. Choose which Blueprints qualify. Open Inventory → Workloads, select Blueprints, select the Blueprint, and select Edit. On Review, turn on Allow automatic registration, then save. Turn it on only for a Blueprint whose Access Binding you are comfortable granting to any ready workload that names it. Any developer who can deploy to an allowed namespace can name any Blueprint that has the flag. See Edit a Workload Blueprint.

  2. Open Setup → Settings → Workloads and find Automatic registration.

  3. Turn on Register ready workloads automatically.

  4. In Allowed namespaces, select or type each namespace where developers can opt in. Names are exact: AIControls doesn't accept patterns. The card lists the namespaces that are always excluded: the kube-* namespaces, the AIControls namespace, and platform namespaces such as kyverno and cert-manager. AIControls refuses to save one of them.

  5. Select Save. If the new setting would demote registrations that already exist, AIControls lists them first. Review the list, then select Confirm and save. See Change the scope.

If the card shows The automatic registration controller is not running, AIControls saved your setting but nothing registers workloads yet. The card states the reason. The most common cause is that the AIControls pod doesn't know its own namespace. Set the POD_NAMESPACE environment variable on the AIControls pod (the Helm chart sets it from the downward API), then restart the pod. Another cause is that workload discovery isn't running, so turn discovery on. The card never infers this from the switch: a switch that is on doesn't mean the controller runs.

Each change to the setting and to a Blueprint's flag is recorded in the configuration audit log.

If no default Blueprint is set, a workload must name its Blueprint. To set one, see Edit a Workload Blueprint.

Change the scope​

The namespace list and the switch apply to registrations that already exist, not only to new ones. When a workload's namespace leaves the scope, AIControls demotes its automatic registration:

  • The registration becomes Auto-registration inactive with the reason out-of-automatic-registration-scope, and the message reads "Out of automatic registration scope". A registration that was already inactive for another reason takes this reason too, so the status shows that the workload is also out of scope.

  • Demotion blocks access. An inactive automatic registration grants nothing. The gateway blocks the workload's calls in every mode, including when the unregistered workload mode is Audit, and it never treats the workload as registered. The registration itself stays, so AIControls can restore it.

  • Demotion doesn't wait for discovery. AIControls demotes from its own records when you save the setting. It doesn't need the workload label, a complete discovery listing, or a running discovery scan. AIControls saves the setting and all its demotions in one step: if one fails, AIControls saves nothing and the previous setting stays in place. While a confirmation is open, the settings stay locked, and Confirm and save saves exactly what the preview showed.

  • Manual registrations are not affected. AIControls changes only registrations it made.

  • Scope never restores access. When the namespace returns to scope, AIControls restores the registration only when the workload is ready and every other condition holds. A registration that was already inactive stays inactive while out of scope.

  • Unknown AIControls namespace. Automatic registration always excludes the AIControls namespace. When the pod can't report its namespace, AIControls uses the last namespace it recorded. When it has none, it demotes every automatic registration, because it can't prove any is outside that namespace. Set POD_NAMESPACE on the AIControls pod to fix this.

  • No cluster identity. When AIControls can't resolve its cluster identity, or can only use the cluster's display name while it waits for the cluster UID, saving the setting and previewing the change both return an error and save nothing, because AIControls can't find the registrations to demote. Wait for the cluster identity, then try again.

Register a demoted workload by hand​

To keep a demoted workload working without waiting for the scope to return, register it yourself:

  1. Open Inventory → Workloads and select the workload.
  2. Select Register manually… in the readiness verdict at the top of the drawer, then complete the wizard. See Register a workload.

The wizard shows a notice that the automatic registration is inactive and lets you continue. AIControls replaces the inactive automatic registration with your registration. The workload gets access again at once, AIControls no longer manages it, and it clears its own record in the same step. If another change leaves a record behind a registration that someone else made, AIControls clears it on the next pass, even when discovery is off. You can't set a demoted registration to Enforce mode until you register it by hand or its scope returns.

Before you save a change that would demote registrations, AIControls shows an impact preview: a table of each namespace, kind, name, and Blueprint that would lose access. The table lists the first 100 registrations. When more would lose access, the preview shows the total and says how many the table leaves out. Select Cancel to keep the current setting, or Confirm and save to apply the change. Saving demotes every affected registration, including the ones the table doesn't list. The preview doesn't save anything.

The confirmation applies only to what the preview showed. If another administrator changes the scope, or a registration appears or changes, while the preview is open, Confirm and save doesn't save anything. AIControls shows the preview again with the current list, and you review it before you confirm. An API client that saves a change that demotes registrations must send the previewToken from the preview request as a query parameter. Without it, or with a stale one, the save returns HTTP 409 and changes nothing.

Opt a workload in​

Add the label to the workload object. The label also adds the workload to the inventory, so you don't need the nirmata.io/ai label or a detection signal. The label doesn't override an administrator's exclusions: workloads in a namespace on the configured discovery exclusion list, in the AIControls namespace, or with the nirmata.io/discovery-exclude label stay out of the inventory. Automatic registration ignores such a workload: it never registers and shows no automatic registration status, and an automatic registration it already made is demoted as Auto-registration inactive. Remove the namespace from the exclusion list to fix it.

apiVersion: apps/v1
kind: Deployment
metadata:
name: support-agent
namespace: agents
labels:
nirmata.io/ai: "true"
aicontrols.nirmata.io/auto-register: "true"

To pick a Blueprint, add the annotation. Without it, AIControls uses the default Blueprint.

metadata:
annotations:
aicontrols.nirmata.io/blueprint: support-agents

Put the label and the annotation on the workload object itself, not on the pod template. Any value other than "true" doesn't opt the workload in.

AIControls checks opted-in workloads about once a minute. The registration uses the workload's ServiceAccount, so cluster discovery must have observed the workload.

Register an OpenShell sandbox​

Automatic registration also covers the Agent Sandbox Sandbox resource that OpenShell creates for each sandbox. The flow is the same as for any workload, with these points:

  • AIControls reads the aicontrols.nirmata.io/auto-register label and the optional aicontrols.nirmata.io/blueprint annotation from the Sandbox resource. Put them on the Sandbox, not on the Pod template.
  • R1 to R4 and R6 check the sandbox's Pod template, its posture, and its traffic, and R5 checks its RuntimePolicy. No rule is skipped for sandboxes.
  • R7 reads the workload identity evidence, not the Pod template. It fails when another workload uses the same ServiceAccount. The second sandbox stays unregistered, and its refusal message names R7. The first sandbox keeps its registration and its access, because a shared ServiceAccount alone never demotes a registration that already exists. The shared ServiceAccount still raises the shared identity finding for both workloads, and the alert fires until an administrator acknowledges the finding. OpenShell uses one sandbox ServiceAccount per namespace, so give each agent its own namespace and add that namespace to the automatic registration list.
  • Removing the label, or removing the namespace from the list, demotes the registration as described in Change the scope.
apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
name: research-agent
namespace: agent-research
labels:
aicontrols.nirmata.io/auto-register: "true"

Cluster discovery scans the Sandbox kind automatically. See Agent Sandbox and OpenShell.

What AIControls does​

When all conditions hold, AIControls registers the workload with these settings:

  • Mode: Audit. AIControls never registers a workload in Enforce, and it never accepts an access widening. To move the workload to Enforce, an administrator follows Switch a workload to Enforce.
  • Access: only what the Blueprint's Access Binding grants. The workload gets no override.
  • RuntimePolicy: the registration takes the Blueprint's Runtime Binding, which always sets network, file, program, and Kubernetes API levels. AIControls compiles the RuntimePolicy from it.
  • Source: auto-readiness. The registration's author is auto-registration-controller, and the team is default. An administrator can change the team by editing the registration.

Each registration and each refusal is recorded in the configuration audit log with the actor auto-registration-controller. The record keeps the label and annotation values, the result of each readiness rule, and the readiness rule set version.

A workload that someone registered by hand is never changed. A workload that an administrator withdraws stays withdrawn until the developer removes the label and adds it again.

Move from Audit to Enforce​

An automatic registration starts in Audit mode with the Blueprint's Runtime Binding levels, which can allow more than the workload uses. Before you enforce, let AIControls compare what the workload does with those levels, then tighten or widen them for this workload only.

  1. Let the workload run its normal work in Audit for at least 24 hours. A CronJob or Job must run at least once in that window. Keep the fleet-wide network observation running, so AIControls records every IPv4 connection. Observation doesn't record IPv6 egress.

  2. Open Inventory → Workloads, select the workload, and open the AI access tab. The Recommendations card lists the intent recommendations for this workload:

    • A recommendation tagged Narrows means a complete observation window shows the workload needs a lower network tier, for example Network: internet → llm-providers. AIControls recommends one only when every observation gate passes. See Network narrowing.
    • Any other intent recommendation means the workload does more than its levels allow, for example Execution: none → shell.
  3. For each recommendation you accept, open its actions menu and select Promote to this workload. Review Effective intent and the warnings in the dialog, then select Promote. AIControls writes the change into the workload's own override. The Blueprint's Runtime Binding doesn't change, so other workloads that use the Blueprint aren't affected. If the override is still wider than the Runtime Binding, the dialog asks you to acknowledge it. For the API, see Promote an intent recommendation.

  4. Preview the calls that Enforce would block, and switch the workload to Enforce. See Switch a workload to Enforce.

AIControls never applies a recommendation by itself, and it never narrows the files or exec section, because those observations don't record every event. An automatic registration that AIControls marked inactive gets no recommendations.

See the status​

Select the workload in Inventory → Workloads. The readiness verdict at the top of the drawer shows the automatic registration status. The Readiness column shows the recorded statuses (Auto-registered, Auto-registration refused, and Auto-registration inactive) as a tag. Will auto-register and Not eligible for auto-registration appear in the drawer only, because the column doesn't read the workload's labels from the cluster.

StatusMeaning
Will auto-registerEvery condition holds. AIControls registers the workload on its next pass.
Auto-registeredAIControls registered the workload in Audit mode.
Auto-registration refusedThe workload is in scope, but a condition fails. The message says which.
Auto-registration inactiveAIControls registered the workload, and a condition stopped holding. The registration remains, but it grants no access until AIControls restores it.
Not eligible for auto-registrationThe workload has the label, but the setting is off, the namespace isn't allowed, or the workload is already registered.
Status unavailableAIControls could not read the automatic registration status from its store. The workload is not necessarily unregistered. Reload the page, and check the AIControls server log if the status stays unavailable.

Fix a refusal​

ReasonWhat to do
not-readyFix the readiness rules the message lists. See Make a workload ready to register.
blueprint-not-allowedAsk an administrator to turn on Allow automatic registration for the Blueprint, or name another Blueprint.
blueprint-not-foundCorrect the aicontrols.nirmata.io/blueprint annotation.
no-default-blueprintAdd the annotation, or ask an administrator to set a default Blueprint.
registration-failedRead the message. A common cause is that discovery hasn't observed the workload's ServiceAccount yet. AIControls retries on the next pass.
access-wideningThe Blueprint widens access. Automatic registration never accepts a widening, so register the workload by hand.
withdrawnAn administrator withdrew the registration. Remove the label and add it again to opt in again.
out-of-automatic-registration-scopeAn administrator removed the namespace from the list or turned automatic registration off. Ask an administrator to restore the scope, or register the workload by hand.
automatic-registration-off, namespace-not-allowed, system-namespaceAsk an administrator to turn on automatic registration or add the namespace. System namespaces can't be added.

When a workload stops being ready​

AIControls keeps checking a workload it registered. When a condition stops holding, it marks the registration inactive with a reason and keeps the registration. It never deletes it. An inactive registration grants no access.

ReasonCause
readiness-driftA readiness rule now fails. A failure of R7 that only a shared ServiceAccount causes doesn't count, and R7 still counts when the workload uses more than one identity. An unknown rule alone doesn't mark the registration inactive.
label-removedThe workload no longer has the label, or no longer exists.
blueprint-flag-removedThe Blueprint no longer allows automatic registration, or no longer exists.
out-of-automatic-registration-scopeThe namespace left the automatic registration list, is a system namespace, or automatic registration is off.

Inactive keeps the registration's Blueprint and current mode, but the gateway blocks the workload's calls, in every unregistered workload mode, until AIControls marks it registered again. If an administrator moved it to Enforce mode, it stays in Enforce mode and keeps blocking. When every condition holds again, AIControls marks it registered again. To restore access sooner, register the workload by hand.