Skip to content

The graph document

llms.txtlists every page for an agent

behold-graph/1 is the graph as one JSON file: flat lists of nodes and edges, the boxes they are drawn in, and the notes the view carries. Other programs read it instead of behold’s API, so its shape is versioned and has a published schema:

https://intentius.io/behold/schemas/graph/v1/graph.schema.json

The same file ships in the npm package at schemas/graph/v1/graph.schema.json.

{
"schema": "behold-graph/1",
"generator": { "behold": "0.31.0", "chant": "0.124.58" },
"origin": { "dir": "infra" },
"cut": { "kind": "whole" },
"nodes": [
{
"id": "prod/prod/aws_vpc.main",
"title": "prod/aws_vpc.main",
"subtitle": "terraform",
"kind": "aws_vpc",
"lexicon": "terraform",
"box": "stack:prod",
"file": "infra/envs/prod/network.tf",
"line": 1,
"status": "warn",
"color": "#FF5A5F",
"mainstat": "drifted (plan)",
"detail__member": "prod",
"detail__root": "prod",
"attrs": { "address": "aws_vpc.main" }
}
],
"edges": [
{
"id": "prod/prod/aws_subnet.public_a->prod/prod/aws_vpc.main:ref:vpc_id",
"source": "prod/prod/aws_subnet.public_a",
"target": "prod/prod/aws_vpc.main",
"kind": "ref",
"inferred": false,
"via": "vpc_id"
}
],
"groups": [{ "id": "stack:prod", "title": "prod", "kind": "stack" }],
"notes": [{ "kind": "view", "text": "1 root, prod; ..." }]
}

The node and edge field names are the ones Grafana’s node graph panel reads (id, title, subtitle, mainstat, secondarystat, color and detail__* on a node, id, source and target on an edge), so the panel can draw the two lists as they are.

  • subtitle is the tool that declares the card, file is relative to the repository root, and box is the id of the innermost group the card sits in.
  • status, color and mainstat are present when a drift overlay painted the card, and change when a plan was read and would change it.
  • Every edge’s source and target is a node in the same document. An inferred edge carries rule, the join that drew it: behold:<pass>, or chant’s catalog rule id. The edge to a placeholder card (a reference that names nothing) and each edge of a reference that names several nodes carry the rule of that reference too, and the placeholder is a node of the kind it was looking for, with lexicon behold.
  • No field holds an absolute path, and a card’s source text (attrs.source) is left out unless it was asked for.
  • read is present on a read of a cluster: which source the card came from (cluster, folder, or git for the path an app deploys from).
  • field is present on an edge whose via names the relationship (runs as, routes to :80): the field the reference was found in.

behold graph <dir> prints the document for a directory, with no server:

Terminal window
npx @intentius/behold graph ./infra > graph.json
npx @intentius/behold graph ./infra --detail 3 -o graph.json

@intentius/behold installs without the Kubernetes client, an optional peer, so a CI job can run npx @intentius/behold graph ./infra on a Terraform folder with a small install. --context reads a cluster instead and needs the client: npm i @intentius/chant-k8s-client next to behold (or npx -p @intentius/behold -p @intentius/chant-k8s-client behold graph --context <name>). Without it the command stops with one line naming that package. --source keeps the cards’ source text. --ir prints the unversioned {ir, meta} snapshot instead of the document.

A cluster and the folder that declares what it uses

Section titled “A cluster and the folder that declares what it uses”

--context with a directory reads both into one graph:

Terminal window
npx @intentius/behold graph --context prod ./infra -o graph.json
npx @intentius/behold graph --context prod --infra ./infra --svg -o graph.svg

chant’s reference catalog joins what the cluster’s objects name to the cards the folder declares: a ServiceAccount’s eks.amazonaws.com/role-arn or iam.gke.io/gcp-service-account annotation to the aws_iam_role or google_service_account, and an ExternalSecret’s key, through its store, to the aws_secretsmanager_secret or google_secret_manager_secret. Those edges carry chant’s rule id. A placeholder card is drawn only for what the folder does not hold, and the notes say so. Each card carries read, the source it came from: cluster (a placeholder too, since a cluster object named it), folder, index or git. On a read of a cluster alone every card has read: "cluster".

When the folder declares the cluster itself (an aws_eks_cluster, a google_container_cluster or an azurerm_kubernetes_cluster), its card joins the context: an edge goes from it to each Namespace, with the rule behold:context, and a note names it. The cluster’s name is matched against the context name and the kubeconfig’s cluster entry, where aws eks update-kubeconfig writes the cluster’s ARN, gcloud writes gke_<project>_<location>_<name> and az aks get-credentials writes the name. A folder that declares no such cluster, or several that match, joins none.

The cloud index of the account the cluster uses

Section titled “The cloud index of the account the cluster uses”

--index aws (or azure, gcp) joins the cloud index that behold index wrote to the cluster read:

Terminal window
npx @intentius/behold index aws --account 111122223333 --regions us-east-1 --types AWS::IAM::Role,AWS::SecretsManager::Secret
npx @intentius/behold graph --context prod --index aws -o graph.json

The graph reads the newest version of each scope of that substrate in behold’s per-user index store, and with a directory its project’s index stores too. It lists nothing and uses no cloud credential, so the index is only as fresh as the last behold index run, and the note says when each version was observed. chant’s reference catalog joins a ServiceAccount’s eks.amazonaws.com/role-arn annotation to the indexed AWS::IAM::Role with that ARN, and an ExternalSecret’s key, through its store, to the AWS::SecretsManager::Secret of that name in the store’s region. A role of the same name in another account gets no edge. An account holds far more than a cluster names, so only the indexed resources a cluster object or a folder card reaches are drawn, in a box named <substrate> <account> (index), with read: "index". The aws index needs @intentius/chant-lexicon-aws installed beside behold, which types the listed resources and gives the catalog their identities.

--git reads the path each Argo CD Application and Flux Kustomization deploys from, out of a local clone, and draws its manifests beside the live objects:

Terminal window
npx @intentius/behold graph --context prod --git ../deploy -o graph.json
npx @intentius/behold graph --context prod ./infra --git https://github.com/org/deploy=../deploy

An Application’s paths are the ones chant’s catalog reads (spec.source.path, spec.sources[].path). A Kustomization’s path is spec.path in the GitRepository its sourceRef names. --git <dir> holds every repository whose URL is that directory or one of its git remotes; --git <url>=<dir> holds one URL. Nothing is fetched: an app whose repository no clone holds is named in a note and not read. The clone’s working tree is read, and the note names the revision the app tracks. The cards sit in a box named for the app, with ids under <app>/git/ and read: "git".

On a read of a cluster, chant infers the applications from the objects (inferK8sComponents). Each top-level workload starts one, and the labels a Helm release or an Argo CD application leaves group workloads into one. An application takes in the objects its workloads use. Three views draw them.

Terminal window
npx @intentius/behold graph --context prod --around shop/Deployment/checkout --svg -o objects.svg
npx @intentius/behold graph --context prod --logical --around shop/Deployment/checkout --svg -o logical.svg
npx @intentius/behold graph --context prod --components --svg -o components.svg

The default view draws every object. A workload’s ReplicaSets and Pods are folded into its card. The objects the API server keeps for itself, such as an EndpointSlice or the default ServiceAccount, are folded into the card they serve. --every-card draws them again. Each edge says what the reference means: routes to with the Service’s ports, runs as, reads env from, mounts, assumes role. A reference in a pod template is drawn once, from the workload. A workload card shows how many of its replicas are ready, its image and its Pods’ restarts. The Pods’ names are in attrs._workload.pods.

--logical draws a box per application with the objects it manages, and the cards for what they name outside the cluster. --components draws one card per application with its health, and an edge to each application whose Service it names in an env value or a ConfigMap. Both need a chant whose cloud lister has inferK8sComponents; with an older one the view is empty and its note says so.

In --logical each application’s box is titled with its ready replicas (checkout · 2/2 ready), and an application that names another’s Service is drawn with an edge from the card holding the name to that Service. With --svg each view is headed with what it shows: “Every object in shop” (--every-card), “Objects in shop”, “shop grouped by application” or “Applications in shop and what they call”, naming the cluster instead when the read took every namespace.

A document can hold part of the graph. cut.kind says which: whole, around (behold graph --around <id>, the cards within --depth hops of the ids named) or changed (behold graph --changed <base>..<head>).

A changed cut reads the directory at two commits, with no plan and no state, and keeps what differs. Each card carries diff: added, removed, changed (with changedAttrs, the attribute keys that differ) or neighbour, a card within --depth hops of one that changed, in either commit. An edge present in one commit only carries diff too. The comparison leaves out where a block sits in a file (file, line, attrs.source), so a commit that only reformats a file changes no card. It is read at --detail 3 unless you pass another, since a card holds no attributes below that.

Past --budget cards the cut folds, and its notes say so: first the neighbours become a changed-folded count per box, then, if the changed cards alone are over the budget, the cards go and one changed-table note per box counts what was added, removed and changed. cut.folded is neighbours or table.

--mermaid prints the graph as a Mermaid flowchart short enough for a comment on a forge. --forge picks the character budget it fits: gitlab (2,000 characters), github (the default) or forgejo (49,999 characters and 500 edges). The github figures were measured on a public test repository, the gitlab and forgejo figures on a local GitLab CE 19.5.5 and a local Forgejo 17.0.1 with default settings. A Forgejo administrator can lower MERMAID_MAX_SOURCE_CHARACTERS, and the budget is then too high for that instance.

Terminal window
npx @intentius/behold graph ./infra --mermaid --forge gitlab

Boxes are subgraphs, inferred edges are dotted, and a document with a plan’s changes or a cut’s seeds paints its cards as added, changed, removed or neighbour. When the graph does not fit, neighbours are dropped first, then whole boxes, and the last card says how many cards are not shown. The output is never over the budget, and two runs on the same input print the same text.

--svg writes the picture the served page draws as one self-contained SVG: its own styles, the icons inline, system fonts, and no link to anything outside the file, so it opens from disk and a CI job can keep it as an artifact. --theme light or --theme dark (the default) picks the colours.

Terminal window
npx @intentius/behold graph ./infra --svg --theme light -o infra.svg

A folder with Terraform roots, or a workspace, is boxed by root, as the page draws it. A graph with no boxes is laid out flat, and a flat layout of more than 400 cards takes minutes, so --svg refuses it and says to read it boxed or cut it first. A card that carries plan facts prints its change as the page does. The painter has no mark yet for the cards a cut was asked for, so they are drawn like their neighbours.

Within behold-graph/1, fields are only ever added. A reader ignores the fields it does not know. A change a reader could not ignore becomes behold-graph/2, and a reader written for version 1 should refuse it rather than draw it.

behold