How Identify works

Setting it up

Setup happens once, run by whoever already administers the cluster. Everyone who casts a spell afterward holds none of what setup touches. What follows is the model in enough detail to check against; nothing here runs today.

1. 1.

   Run the collector in your cluster

   The collector is deployed into its own namespace with its own ServiceAccount. It needs no inbound networking, because it opens the connection to the control plane itself, outbound over mTLS. SPELLBOOK_NAMESPACES pins the namespaces it may ever touch, set here, on your side.

   collector env

   SPELLBOOK_NAMESPACES=storefront,checkout

2. 2.

   Bind the read grant

   Identify's ServiceAccount gets read on the objects it walks: pods, ReplicaSets, and Deployments. This is the ceiling the API server enforces, and there is no write verb in it, so nothing Identify finds can be changed by Identify.

   identify ClusterRole

   rules:
     - apiGroups: [""]
       resources: [pods, pods/log]
       verbs:     [get, list]
     - apiGroups: ["apps"]
       resources: [deployments, replicasets]
       verbs:     [get]

3. 3.

   Grant the entitlement

   In the control plane, a role carries spell.identify.cast, the string that lets a person or agent cast /identify. The match is exact unless a grant ends in .* , so it grants Identify and nothing near it.

   entitlement

   spell.identify.cast

4. 4.

   Cast it

   Ana signs in as herself and checks what checkout is running. She holds no kubeconfig, and she never gets one.

   slack

   /identify checkout

This is the design, not an install guide. The collector bundle, the flags, and the exact manifests are not yet something you can apply.

What it refuses to do

A permission that was never issued cannot be misused, by a person, by a compromised account, or by an agent.

Set the image to fix the drift

Identify holds no write verb. It reports drift; it does not correct it. Setting a Deployment's image is /deploy, which carries a write grant and a production hard-stop that Identify does not have.

kubectl get deploy checkout -o yaml

kubectl was never issued to you, so there is nothing to revoke. Identify reads the same objects and hands you the comparison, with no credential you could point at anything else.

Trust the tag

Identify does not. Two pods on the same tag can run different images if the tag was moved between their pulls, so the verdict is built on the container's imageID, the digest actually pulled, not the tag string.

Read a Secret in the pod's env

Not in the grant. Identify reads image references and digests, not Secrets, so a pull secret or an env var holding a credential is out of its reach.

/identify a service outside your namespaces

Out of scope, refused before a read. SPELLBOOK_NAMESPACES bounds what the collector can reach, and the RBAC rule bounds it again.

Failure modes

What happens when it cannot do the thing.

A pod has not pulled its image yet

There is no digest to compare, so Identify marks that container not started rather than calling it drifted. A pod mid-pull is not a drift finding.

The controller is not a Deployment

There is no template to compare against, so Identify reports the desired image from the pod spec and says so. It does not invent a controller intent it cannot read.

A ReplicaSet or Deployment cannot be read

The reply is marked degraded, names what it could not read, and still returns the rows it could build.

The name matches nothing

It lists the services it can see in scope and casts nothing, the same private candidate reply Scry gives.

Everything is in sync

The table is short and every verdict says in sync.