Application and infrastructure
Map services whose code lives in one repository and whose manifests and Terraform live in another, and let the code check follow a connection across the network hop.
On this page
Platform teams often keep Kubernetes manifests, Helm charts and Terraform apart from the services that they run. A question such as “which service talks to which” then crosses two repositories. One model can bind modules into both, and one archboard check code reads both.
How the check follows a hop#
The code of a service reads an address from its environment. The infrastructure that runs the service sets that value to another service’s address. The check joins the two halves into configured-path evidence:
- The code end. Bound code reads an environment value, such as
process.env.BILLING_URLin TypeScript. - The infrastructure end. The Kubernetes workload, the compose service or the Terraform resource that runs that code sets the value, directly or through a ConfigMap that it loads with
envFrom. - The target. The value is the address of another module’s workload, such as the Kubernetes Service
billing.
When all three hold, the check knows that one module reaches the other across the network, and it compares that with the relationships in the model.
The relay example#
archboard-relay-example is a small parcel desk with four services. Its TypeScript and its model live in one repository. Its Kubernetes manifests and its OpenTofu queue live in archboard-relay-example-infra. The model says that Intake never calls Billing.
The platform gives every workload the address of every peer through one ConfigMap:
apiVersion: v1kind: ConfigMapmetadata: name: peer-endpointsdata: CATALOG_URL: http://catalog.harbor.svc.cluster.local:8080 DISPATCH_JOBS_URL: http://dispatch-jobs.harbor.svc.cluster.local:9324 BILLING_URL: http://billing.harbor.svc.cluster.local:8080A pull request in the application repository makes Intake read BILLING_URL and call it:
const billingUrl = trimUrl(process.env.BILLING_URL ?? ""); await deps.fetch(`${billingUrl}/surcharges?routeCode=${encodeURIComponent(routeBody.routeCode)}`); const queued = await deps.fetch(`${jobsUrl}/jobs`, {The check fails, and its evidence names one line in each repository:
warning: RELATIONSHIP_UNDRAWN: ZvzEpjXR.module.json: module "Rate card": The code of "Accept parcel" reaches "Rate card". No relationship joins these modules. Add the relationship between the parts that make and answer the call. If this dependency is unintended, change the code. configured-path, resolved, services/intake/src/accept.ts:51 configured-path, resolved, deploy/kubernetes/peer-endpoints.yaml:13Register both checkouts#
A binding names a repository by its identity, which comes from the checkout’s origin remote. The machine that runs the check must know where a checkout of each repository is. These steps run the relay example from a fresh machine:
-
Clone the application and the infrastructure side by side.
Terminal window git clone https://github.com/miklschmidt/archboard-relay-examplegit clone https://github.com/miklschmidt/archboard-relay-example-infra -
Register both checkouts. The first registered checkout of a repository becomes its chosen checkout, the one that the check reads.
Terminal window archboard repo add archboard-relay-examplearchboard repo add archboard-relay-example-infraarchboard repo list -
Run one code check from the repository that holds the vault. It reads both checkouts.
Terminal window cd archboard-relay-examplearchboard check code
The example’s npm run setup does steps 1 and 2 for you, and npm run gate:break and npm run gate:restore add and remove the call to Billing. archboard repo use <dir> picks another checkout of a repository, such as a worktree with a branch of the infrastructure.
In CI#
Check out the infrastructure beside the application, then give its path to the check Action. The Action registers it before it runs the check:
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: path: app - uses: actions/checkout@v5 with: repository: miklschmidt/archboard-relay-example-infra path: platform - uses: miklschmidt/archboard/actions/check@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0 with: version: "0.5.0" working-directory: app repos: | platformA private infrastructure repository needs a token with read access in the second checkout’s token input.
The limits of hop evidence#
The code check reads files. It never runs the system, so it follows a hop only where the files state both ends.
- Both ends must declare the connection. The code must read the value by name, and the infrastructure must set that name to another module’s address. An address that the code builds at run time, or reads from a secret store, leaves no evidence.
- One side alone is information. When the infrastructure sets a value that the code never reads, or the code reads a name that nothing sets, a drawn relationship gets
RELATIONSHIP_UNSUPPORTEDwithmissingnaming the side that has no evidence. It never fails the check. - A literal value on the workload counts for the workload. A value written into a Deployment’s own
envis evidence for the whole Deployment, whether or not its code reads the name. A value that the workload loads from a ConfigMap withenvFromcounts only when code reads that name. That is why the relay example uses a ConfigMap. - A choice that the infrastructure leaves open is a candidate. When several workloads can answer one address, the evidence is a candidate, and a finding on a candidate is information.
- The check names what it skipped. A repository that this machine has not registered, a module inside a remote Terraform module, or code that did not parse is listed under
skippedwith the reason. A skipped subject never looks like a clean one. - It never touches state or credentials. The check never runs
terraform,tofuorkubectl. It never reads Terraform state, a variable file or.terraform. For a remote Terraform module, pass the plan JSON oftofu show -jsonwith--plan.
A model for several repositories#
A model in one repository can bind into any number of others, as the relay example does. When no repository owns the whole system, keep the model in a repository of its own, such as a platform repository, and run the check there with every other checkout registered. INSTALL.md describes how a command finds that vault. Archboard in a Home Repo walks through that setup.