
<figure class="research-quote">
  <blockquote>Frequent configuration changes executed by a large population of engineers, along with unavoidable human mistakes, lead to configuration errors, which is a major source of site outages.</blockquote>
  <figcaption>Tang et al., "Holistic Configuration Management at Facebook", SOSP 2015. <a href="https://sigops.org/s/conferences/sosp/2015/current/2015-Monterey/printable/008-tang.pdf">Paper (PDF)</a></figcaption>
</figure>

That's Facebook's engineering team at SOSP 2015, describing a system absorbing thousands of live configuration changes a day. Their fix wasn't stricter YAML review. They compiled configs from high-level source code, expressed configuration dependencies "similar to the include statement in a C++ program", and validated invariants against the result before anything touched a server. At the sharpest end of the problem, a decade ago, the conclusion was already in: stop treating configuration as text you diff. Treat it as a structure you compute.

A year ago Julia wrote a [breakup letter to YAML](/devops/yaml-breakup) on this blog. That post was the feelings. This one is the argument, and the argument is why ICE's source of truth is a deterministic graph rather than a directory of text files.

## Questions a text file can't answer

The test of a source of truth is whether it can answer the questions you ask during an incident. Line one of the table is the question I got burned by. The rest follow.

| The question you actually ask | What the text file knows |
|-------------------------------|--------------------------|
| What breaks if I delete this subnet? | Which lines contain the subnet's name |
| What order do these changes need to apply in? | Nothing; order is computed at plan time, then discarded |
| Has reality drifted from what's declared? | Nothing; text can't observe the cloud |
| Is this rename safe? | It reads as a delete plus a create; good luck |

Terraform itself concedes the point, quietly. Run `terraform graph` and it prints the DAG (directed acyclic graph) of resources and dependencies it builds internally before every single plan. The graph exists on every run. It's derived from your text, used to order operations, and thrown away, while review happens on the characters. The most load-bearing artifact in the whole pipeline is the one no reviewer ever sees.

The YAML ecosystem keeps rediscovering the gap. Helm templates YAML with text substitution, Kustomize patches YAML with more YAML, and both exist because the format can't express the relationships everyone actually needs, so the industry bolts string machinery onto a tree structure and calls the result configuration management. Tools that exist to work around the source of truth are testimony about the source of truth.

## Determinism is the actual feature

A graph as the source of truth changes three things, and none of them are cosmetic. Hold on: two things, stated properly.

First, identity. In a graph, a resource is a node with an identity that survives renaming, so a rename is a rename. In text, the same edit surfaces as destruction plus creation, and every Terraform operator eventually learns `terraform state mv` the way you learn most things in this field, which is at night. Second, reproducibility. A deterministic model means the same graph produces the same actions, every time, with drift detected by comparing the graph's expectations against observed reality node by node, rather than by diffing two commits of a file that was never looking at the cloud in the first place.

<figure class="research-quote">
  <blockquote>Even a minor mistake could potentially cause a site-wide outage. We take a truly configuration-as-code approach to compile and generate configs from high-level source code.</blockquote>
  <figcaption>The same paper, on why configs get compiled instead of hand-edited</figcaption>
</figure>

The scale details are worth sitting with: they report a median config size of 1KB with large ones reaching MBs or GBs, hundreds of thousands of configs, and trillions of configuration checks daily. Nobody reviews that by reading characters. Structure was the only way through.

## Text won for a reason

Steelman time, and it's a strong one. Text is the only format every engineer, editor, and tool on earth can open. Git gave it merge machinery, blame, and history for free. It's greppable at 3 a.m. It locks you into no vendor. And the failure mode of the alternative is real: an opaque model nobody can inspect is worse than ugly YAML, because at least ugly YAML can be read in a pager on a bad night. GitOps built genuine operational rigor on all of this.

Every bit of that is conceded, and it shapes the design rather than defeating it. The graph serializes to versionable, diffable text, so the audit trail survives; what changes is what the diff says. A text diff reports "+14 -9 lines". A graph diff reports which nodes changed and what depends on them, which is the difference between describing an edit and describing its blast radius. You keep git. You stop asking git to be a model of your infrastructure, because it never was one.

This is the bet ICE makes concrete: one deterministic graph modeling your infrastructure across AWS, GCP, and Azure, with the graph as the thing you operate on and text as one of its projections. Drift stops being a quarterly surprise and becomes a comparison the tool runs continuously.

I don't claim the graph model is finished territory; serialization formats, review UX, and escape hatches for the weird 5% are open problems we work on in the open. What I'll defend flatly is the direction. Structure first, text as output.

Facebook needed this at hundreds of thousands of configs. You'll feel it at fifty, the first time a plan output surprises you, because the tool held a graph that knew the answer and discarded it before showing you a diff of characters. Why is the throwaway the part you review?

---

Related: [A Breakup Letter to YAML](/devops/yaml-breakup), the emotional prequel to this argument.
More about what we're building at [light-cloud.com](https://light-cloud.com).


Diffing text was the wrong abstraction from the start

Why Our Source of Truth Is a Graph, Not a Text File


*This is the fourth article in my infrastructure series. If you missed the previous episodes of my descent into madness, check out [Why I Sacrificed a Goat to AWS Gods](https://blog.light-cloud.com/cloud/rethinking-infrastructure), [From Rant to Reality: Why I Started Light Cloud](/startup/cloud-out-of-spite), and [The $4,847 Bill That Changed My Life](/startup/cloud-bill-horror-story).*

---

Dear YAML,

We need to talk.

I know we've had some good times together. Remember when you replaced XML and everyone thought you were so clean and readable? Those were simpler days. Back when a deployment meant copying files to `/var/www/html` and calling it a day.

But somewhere along the way, our relationship became... complicated.

## It Started So Innocently

Remember our first date? A simple Docker Compose file:

```yaml
version: '3'
services:
  web:
    build: .
    ports:
      - "3000:3000"
```

So elegant! So readable! My heart fluttered. "Finally," I thought, "a configuration language that doesn't look like it was designed by someone who hates humanity."

I was so naive.

## The Red Flags I Should Have Seen

Looking back, there were warning signs. Like that time you made me spend 3 hours debugging a deployment failure because I used tabs instead of spaces. Or when you insisted that `"no"` and `"false"` and `false` are three different things. WHO DOES THAT, YAML?

But I ignored the red flags because you promised me simplicity. You whispered sweet nothings about being "human-readable" and "easy to understand." You lying, indentation-obsessed monster.

## When Things Got Serious (AKA Kubernetes)

Then Kubernetes entered our lives, and everything changed. Suddenly, you weren't just handling simple key-value pairs. You were orchestrating the fate of entire applications. And you... you became a different YAML. A darker YAML.

This is what you made me write to deploy a simple web app:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-simple-app
  labels:
    app: my-simple-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-simple-app
  template:
    metadata:
      labels:
        app: my-simple-app
    spec:
      containers:
        - name: my-simple-app
          image: my-simple-app:latest
          ports:
            - containerPort: 3000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
          resources:
            limits:
              cpu: 500m
              memory: 512Mi
            requests:
              cpu: 250m
              memory: 256Mi
---
apiVersion: v1
kind: Service
metadata:
  name: my-simple-app-service
spec:
  selector:
    app: my-simple-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 3000
  type: LoadBalancer
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-simple-app-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
    - hosts:
        - myapp.example.com
      secretName: myapp-tls
  rules:
    - host: myapp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-simple-app-service
                port:
                  number: 80
```

YAML, this is 60 lines of configuration to deploy a Node.js app that serves "Hello World." SIXTY LINES. For comparison, the actual application code is 4 lines:

```javascript
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('Hello World!'));
app.listen(3000);
```

I'm writing 15 times more configuration than actual code. This is not what you promised me, YAML.

## The Great Helm Chart Incident of 2024

Things got worse when we started using Helm. Suddenly you weren't just YAML anymore. You were YAML with *template variables*. You became some kind of YAML-Go-template hybrid abomination:

```yaml
{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "mychart.fullname" . }}
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  {{- if and .Values.ingress.className (not (hasKey .Values.ingress.annotations "kubernetes.io/ingress.class")) }}
  ingressClassName: {{ .Values.ingress.className }}
  {{- end }}
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            {{- if and .pathType (semverCompare ">=1.18-0" $.Capabilities.KubeVersion.GitVersion) }}
            pathType: {{ .pathType }}
            {{- end }}
            backend:
              {{- if semverCompare ">=1.19-0" $.Capabilities.KubeVersion.GitVersion }}
              service:
                name: {{ $fullName }}
                port:
                  number: {{ $svcPort }}
              {{- else }}
              serviceName: {{ $fullName }}
              servicePort: {{ $svcPort }}
              {{- end }}
          {{- end }}
    {{- end }}
  {{- end }}
```

YAML, what have you become? This isn't configuration anymore. This is a programming language pretending to be configuration. And not even a good programming language! It's like someone took the worst parts of templating engines and mashed them together with your indentation obsession.

## The Debugging Nightmares

But the real betrayal? The debugging experience. When something goes wrong, you give me error messages like:

```
error converting YAML to JSON: yaml: line 47: found character that cannot start any token
```

Line 47? CHARACTER THAT CANNOT START ANY TOKEN? What does that even mean? Which character? What token were you expecting? Why can't you just tell me I have a typo like a normal language?

I've spent more time counting spaces in YAML files than I have optimizing actual application performance. Let that sink in.

## The Values.yaml Inception

And don't get me started on `values.yaml` files. You made me create YAML files to configure other YAML files. It's YAML all the way down, like some kind of configuration language inception nightmare:

```yaml
# values.yaml-breakup
replicaCount: 3

image:
  repository: my-app
  pullPolicy: IfNotPresent
  tag: "latest"

nameOverride: ""
fullnameOverride: ""

serviceAccount:
  create: true
  annotations: {}
  name: ""

podAnnotations: {}

podSecurityContext: {}

securityContext: {}

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls: []

resources: {}

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 100
  targetCPUUtilizationPercentage: 80

nodeSelector: {}

tolerations: []

affinity: {}
```

I need a PhD in YAML archaeology just to understand what half of these fields do. And if I want to enable HTTPS? I have to navigate through this maze of nested configurations like I'm defusing a bomb.

## The Final Straw: ArgoCD

The relationship truly hit rock bottom when we started using ArgoCD for GitOps. Now I had to manage YAML files that manage other YAML files that deploy applications defined in more YAML files.

Here's what I needed to deploy a simple app with ArgoCD:

1. **Application YAML** (defines what to deploy)
2. **Deployment YAML** (defines how to deploy)
3. **Service YAML** (defines networking)
4. **Ingress YAML** (defines external access)
5. **ConfigMap YAML** (defines configuration)
6. **Secret YAML** (defines secrets)
7. **values.yaml** (defines Helm variables)
8. **Chart.yaml** (defines Helm metadata)

Eight different YAML files. For one application. That serves "Hello World."

My git repository looked like a YAML graveyard. Hundreds of nearly identical files, differing only in tiny details that somehow break everything if you get them wrong.

## What We've Learned About Each Other

YAML, through our toxic relationship, I've learned some hard truths:

1. **You're not actually human-readable** when you reach any meaningful complexity
2. **Your indentation sensitivity** is a feature nobody asked for
3. **You make simple things complex** and complex things impossible
4. **You've created an entire industry** of tools just to manage you (kustomize, helm, jsonnet)
5. **You're the reason** developers are afraid of infrastructure

And I think I've finally figured out why our relationship never worked: **You were never meant to be a programming language, but somehow you became one.**

## The Light Cloud Alternative: Visual Infrastructure Blocks

This is why we built Light Cloud's visual infrastructure blocks. Instead of wrestling with 60 lines of YAML, our users just drag and drop:

-  **App Block** (connects to your git repo)
-  **Database Block** (PostgreSQL, MySQL, or MongoDB)
-  **Cache Block** (Redis with automatic clustering)
-  **Load Balancer Block** (with automatic SSL)

Click, connect, deploy. No YAML in sight.

Our ICE (Integrated Cloud Environment) generates the infrastructure automatically. Want to see what's happening under the hood? Sure, we'll show you the generated Terraform and Kubernetes configs. But you never have to touch them.

One of our beta users deployed a production-ready e-commerce platform in 15 minutes. No YAML files were harmed in the making of this deployment.

## It's Not Me, It's You

So YAML, this is goodbye. It's not me, it's definitely you.

You promised simplicity but delivered complexity. You promised readability but gave us hieroglyphics. You turned configuration into a full-time job.

But I want you to know, I don't hate you. You were a necessary step in our evolution. You taught us what we DON'T want in infrastructure tooling:

-  Configuration shouldn't be harder than coding
-  Deployment shouldn't require a specialty degree
-  Infrastructure shouldn't be a full-time job

## To My Fellow YAML Survivors

If you're reading this and nodding along, you're not alone. We've all been traumatized by indentation errors at 2 AM. We've all spent hours debugging why `enabled: "false"` doesn't work the same as `enabled: false`

But there's hope. The future of infrastructure is visual, intuitive, and YAML-free.

At Light Cloud, we're building that future. Come join us.

---

*P.S. YAML, if you're reading this, please fix your error messages. "found character that cannot start any token" is not helpful feedback. Neither is "did not find expected key" when the key is literally right there.*

*P.P.S. To everyone who's about to comment "but YAML is simple once you understand it" - that's exactly the problem. I shouldn't need to "understand" a configuration format. It should just work.*

---

**Ready to break up with YAML too?** [Try Light Cloud's visual infrastructure blocks](https://light-cloud.com) and deploy without the pain. Your future self will thank you.

DevOps

Why Our Source of Truth Is a Graph, Not a Text File

A Breakup Letter to YAML