How Scry works

Setting it up

Setup is done once, by whoever already administers the cluster, and it is the only moment cluster access appears anywhere in this story. Everybody who casts a spell afterwards holds none. The steps below are how the design works; nothing here installs today.

1. 1.

   Install the operator, once per cluster

   It runs in its own namespace, alongside the workloads it will read. Nothing is exposed: the chart creates no Service, no Ingress and no public endpoint, because the operator dials out rather than being called in.

   shell

   helm repo add spellbook https://charts.spellbook.dev
   helm install spellbook spellbook/operator \
     --namespace spellbook --create-namespace

2. 2.

   Say what your team owns

   The ownership map is the thing that makes "checkout" resolve to one workload and not another. Keep it in the repo, next to the code it describes, and review a change to it the way you would review a change to a deploy pipeline.

   spellbook.yaml

   teams:
     - name: storefront
       members:
         - ana@northwind.example
         - sam@northwind.example
       owns:
         - deployments.apps/checkout-api  in storefront
         - deployments.apps/cart-api      in storefront

3. 3.

   Grant the spell

   A grant is a spell, given to a team, over what that team owns. The operator reconciles it into an ordinary Kubernetes Role, so the limit is enforced by your API server rather than by our good intentions, and you can read it with the tools you already have.

   spellbook.yaml

   grants:
     - team: storefront
       spells: [scry]
   
   # becomes, in namespace storefront:
   #   rules:
   #     - apiGroups: ["", "apps"]
   #       resources: [pods, pods/log, events, deployments, replicasets]
   #       verbs:     [get, list, watch]
   #
   # There is no fourth verb, and Secrets are not in the list.

4. 4.

   Connect Slack, outbound

   Socket Mode holds a connection from your cluster out to Slack, so Slack never calls you. There is no callback URL to expose, no inbound firewall rule to open, and nothing about Spellbook that a stranger on the internet can reach.

   shell

   kubectl create secret generic spellbook-slack \
     --namespace spellbook \
     --from-literal=app-token=xapp-… \
     --from-literal=bot-token=xoxb-…

5. 5.

   Cast it

   Ana is in the storefront team, and the storefront team was granted Scry over checkout-api. She types this in the channel she was already in. She has no kubeconfig, and she never gets one.

   slack

   /scry checkout

This is the design, not an install guide: the chart, the file format and the flags do not exist yet. It is written out this far because a mechanism you can argue with is worth more than a promise you cannot.

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.

kubectl logs -f checkout-api

You do not have kubectl. Not revoked: never issued. The spell is the interface, so the dangerous version of this action does not exist for you to get wrong.

/scry billing-api

A workload in a namespace nobody granted you. Refused before any Kubernetes API call is made, and refused again by RBAC if that check were ever wrong. The reply names the team that owns it and how to ask them.

Read a Secret, or an environment variable holding one

Not in the grant. If a credential appears in a log line, it is redacted before the answer leaves the cluster, and a line that cannot be redacted confidently is not quoted at all.

Fix what it just found

Scry holds no write verb of any kind. It cannot restart, patch, scale or delete. The answer ends at the answer, and restarting is a different spell with a different grant.

Hold a session open

A cast is bounded. It reads a window, returns one answer, and closes. There is no live session to leave running, and nothing to forget to close.

Guess

If logs, events and metrics do not support a cause, Scry says so and lists what it checked. An invented cause is worse than no answer, because you would act on it.

Failure modes

What happens when it cannot do the thing.

The pod is already gone

Scry reads the previous container's logs where the kubelet still holds them. When they are gone, it says the logs are gone rather than answering from what is left.

You do not run metrics-server

The answer is built from logs and events alone and is marked partial, with the source that was missing named. It does not silently drop a leg and present the result as complete.

The window is enormous

The read is capped by time and by line count. Scry reports how much it read, so a thin answer is visibly a thin answer rather than a confident one.

Nothing explains it

It says so, lists what it checked, and stops. The next move is yours, and you have not been told a story.

The operator cannot reach the API server

The cast fails loudly with the API error, and the failure is recorded like any other cast. A spell that quietly returns nothing is worse than a spell that says it is broken.