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 workload also has to be in the inventory, so keep the nirmata.io/ai label, or let cluster discovery detect 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.

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.

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.

Status	Meaning
Will auto-register	Every condition holds. AIControls registers the workload on its next pass.
Auto-registered	AIControls registered the workload in Audit mode.
Auto-registration refused	The workload is in scope, but a condition fails. The message says which.
Auto-registration inactive	AIControls registered the workload, and a condition stopped holding. The registration remains, but it grants no access until AIControls restores it.
Not eligible for auto-registration	The workload has the label, but the setting is off, the namespace isn't allowed, or the workload is already registered.

Fix a refusal

Reason	What to do
not-ready	Fix the readiness rules the message lists. See Make a workload ready to register.
blueprint-not-allowed	Ask an administrator to turn on Allow automatic registration for the Blueprint, or name another Blueprint.
blueprint-not-found	Correct the aicontrols.nirmata.io/blueprint annotation.
no-default-blueprint	Add the annotation, or ask an administrator to set a default Blueprint.
registration-failed	Read the message. A common cause is that discovery hasn't observed the workload's ServiceAccount yet. AIControls retries on the next pass.
access-widening	The Blueprint widens access. Automatic registration never accepts a widening, so register the workload by hand.
withdrawn	An administrator withdrew the registration. Remove the label and add it again to opt in again.
out-of-automatic-registration-scope	An 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-namespace	Ask 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.

Reason	Cause
readiness-drift	A readiness rule now fails. An unknown rule alone doesn't mark the registration inactive.
label-removed	The workload no longer has the label, or no longer exists.
blueprint-flag-removed	The Blueprint no longer allows automatic registration, or no longer exists.
out-of-automatic-registration-scope	The 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.

Related

• Workload protection
• Register a workload
• Make a workload ready to register
• Edit a Workload Blueprint
• Workload readiness rules