🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

📒 धडा 05 — State: जागेची नोंदवही

📍 तुम्ही इथे आहात: धडा 05 / 12 · मागे: lesson-04-variables-loops · पुढे: lesson-06-dependency-graph

📦 या ब्रँचमध्ये काय आहे

धडे 01–04, आणि कंत्राटदार धडा 01 पासून ठेवत आलेली वही: state, म्हणजेच जागेची नोंदवही. आराखड्यातील प्रत्येक address साठी ती खऱ्या object चा id आणि त्याचे शेवटचे माहीत असलेले attributes नोंदवते. तिच्याशिवाय कंत्राटदाराला "नवी lab बांधा" आणि "lab आधीच आहे" यांतील फरक कळू शकत नाही. नोंदवहीत secrets साध्या अक्षरात सुद्धा असतात. iac/demo.py मधील state(); iac/engine.py मधील new_state(), refresh() आणि apply().

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

बांधकाम कार्यालय एक मोठे पुस्तक ठेवते: जागेची नोंदवही. 📒 प्रत्येक गोष्टीसाठी एक ओळ:

school_room.lab → room-01 · chem-lab · floor 2 · 30 seats school_locker.a → locker-01 · combination 6872

कंत्राटदार नवा आराखडा घेऊन परत येते तेव्हा ती सर्वात आधी नोंदवही उघडते. "आराखडा म्हणतो lab. नोंदवही म्हणते lab म्हणजे room-01. चला, room-01 पाहून येऊ." यावरूनच तिला कळते की lab आधीच बांधलेली आहे.

एके दिवशी नोंदवही नदीत पडते. 🌊 कंत्राटदार आराखडा उघडते, एक रिकामी नोंदवही उघडते, आणि विचार करते: "नोंदवहीत lab नाही? मग मला एक बांधायलाच हवी!" ती पहिलीच्या शेजारी दुसरी chem-lab बांधते. आता दोन झाल्या.

आणि locker ची ती ओळ पुन्हा पाहा. Combination तिथेच लिहिलेले आहे. जो कोणी नोंदवही वाचू शकतो तो locker उघडू शकतो. 🔓

🗺️ आकृती

flowchart LR
    plans["📜 plans<br/>school_room.lab"] -->|"which object?"| reg["📒 register (state)<br/>school_room.lab → room-01<br/>serial 1 · lineage campus-3f9a<br/>combination 6872 (plain text!)"]
    reg -->|"read room-01"| campus["🏫 campus<br/>room-01"]
    lost["🌊 register lost"] -->|"plan"| dup["Plan: 5 to add<br/>→ 2 chem-labs"]

🗺️ रेखाटलेली आवृत्ती + एक lab: https://school-edh.pages.dev/terraform/lesson-diagrams.html#l05

❓ काय

State — प्रत्येक apply नंतर Terraform लिहिते तो एक JSON document. तो config मधील प्रत्येक address (aws_instance.web) एका खऱ्या object शी (i-0abc…) जोडतो आणि object चे शेवटचे पाहिलेले attributes साठवतो. Default ने ती स्थानिक file terraform.tfstate असते.
अशी जोडणी का लागते — बहुतेक cloud APIs "कोणता instance म्हणजे aws_instance.web?" याचे उत्तर देऊ शकत नाहीत. नावे आणि tags unique नसतात किंवा नेहमी नसतात. State हीच जोडणी आहे.
Serial — बदलांसह state लिहिली की दर वेळी वाढणारा counter. Lab 0 पासून सुरू होते आणि काहीतरी बदलणाऱ्या प्रत्येक apply ला 1 वाढवते.
Lineage — state पहिल्यांदा तयार होताना तिला दिलेला id, म्हणजे Terraform एक state दुसऱ्या असंबंधित state वर overwrite करण्यास नकार देऊ शकते.
State मधील sensitive data — प्रत्येक attribute साठवला जातो, passwords, private keys आणि generated secrets सुद्धा. sensitive = true एखादे मूल्य फक्त plan आणि output दाखवताना लपवते. State file मध्ये ते तरीही साध्या अक्षरात असते.
खरा format विरुद्ध lab — खरी state (format version 4) resources ला {mode, type, name, provider, instances: [{attributes, dependencies}]} च्या array म्हणून दाखवते. Lab सपाट map address → {type, id, attrs, deps} वापरते. कल्पना तीच, आकार सोपा.

🤔 का

कारण नोंदवहीमुळेच plans incremental होतात. ती हरवली तर पुढचा plan सगळे पुन्हा तयार करू पाहतो — चांगल्यात चांगले duplicates, वाईटात वाईट नावांचे संघर्ष आणि fail झालेले applies. ती बिघडली तर addresses चुकीच्या objects कडे निर्देश करतात. ती बाहेर फुटली तर तिच्यातील प्रत्येक secret सुद्धा फुटते. म्हणूनच state कधीच git मध्ये commit केली जात नाही, versioning असलेल्या encrypted remote store मध्ये राहते (धडा 08), आणि शक्य तितक्या कमी लोक व jobs ती वाचतात.

🔧 कसे (या repo मध्ये)

iac/engine.py मधील new_state() version, serial, lineage, resources आणि outputs असलेली रिकामी नोंदवही बनवते. plan() ची सुरुवात refresh() ने होते, जे campus मधून प्रत्येक id वाचते. apply() प्रत्येक object चा id, attributes आणि dependencies नोंदवहीत लिहिते, outputs त्यांच्या sensitive flag सह साठवते, आणि काहीही बदलले तर serial मध्ये 1 वाढवते. show_outputs() sensitive outputs साठी <sensitive> print करते — आणि मूल्य state["outputs"] मध्ये तसेच राहते.

🧪 करून पाहा

python3 iac/demo.py state
python3 - <<'EOF'
import sys; sys.path.insert(0, "iac")
from cloud import FakeCloud
from engine import plan, apply
cloud, st = FakeCloud(), None
for seats in (30, 30, 40, 50):
    st, _, msg = apply(plan({"resource": {"school_room": {"lab": {"name": "lab", "seats": seats}}}}, st, cloud), cloud)
    print(f"seats {seats} → {msg} · serial {st['serial']}")
print("state list:", list(st["resources"]))
print("state show:", st["resources"]["school_room.lab"]["attrs"])
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

state असे print करते:

   output lab_id = "room-01"
   output code_a = <sensitive>
── the register (state): version 4 · serial 1 · lineage campus-3f9a · 5 resources
   search the state for 'combination' → ['school_locker.a: 6872', 'school_locker.b: 4434', 'school_locker.c: 4123']
── the register is lost; plan with an empty one → Plan: 5 to add, 0 to change, 0 to destroy.
   after apply the campus has 2 rooms named ['chem-lab'] and 10 objects — duplicates, not the same campus

तुमचा snippet असे print करतो:

seats 30 → Apply complete! Resources: 1 added, 0 changed, 0 destroyed. · serial 1
seats 30 → Apply complete! Resources: 0 added, 0 changed, 0 destroyed. · serial 1
seats 40 → Apply complete! Resources: 0 added, 1 changed, 0 destroyed. · serial 2
seats 50 → Apply complete! Resources: 0 added, 1 changed, 0 destroyed. · serial 3
state list: ['school_room.lab']
state show: {'name': 'lab', 'floor': 1, 'seats': 50, 'tags': {}, 'id': 'room-01'}

🏁 तुम्ही आत्ताच काय सिद्ध केले

Output ने code_a लपवले, पण नोंदवहीत साधा शोध घेतल्यावर तिन्ही lockers ची combinations सापडली. नोंदवही गेल्यावर त्याच आराखड्याने 5 to add असा plan केला आणि सगळ्याची दुसरी प्रत बांधली: 10 objects, दोन chem-labs. आणि serial फक्त काहीतरी बदलले तरच पुढे सरकतो — 30 seats सह दुसऱ्या apply ने तो 1 वरच ठेवला.

⚠️ नेहमीच्या चुका

terraform.tfstate git मध्ये commit करणे (.gitignore मध्ये *.tfstate* जोडा)
secret state बाहेर ठेवण्यासाठी sensitive = true वर विश्वास ठेवणे
state JSON हाताने edit करणे — terraform state commands, moved, import आणि removed blocks वापरा
एकमेव प्रत laptop वर ठेवणे — versioning नाही, backup नाही, sharing नाही (धडा 08)
"फक्त plan चालवण्यासाठी" प्रत्येक developer ला prod state वाचण्याचा access देणे

🏭 प्रत्यक्ष वापरात

खऱ्या account वर — नोंदवही editor ने नाही, CLI ने पाहा:

terraform state list                         # every address in the state
terraform state show aws_s3_bucket.timetables
terraform state pull > backup.tfstate        # a copy of the current remote state
terraform show -json | jq '.values.root_module.resources | length'

नोंदवही सुरक्षितपणे बदलणे:

# forget an object without destroying it (Terraform 1.7+)
removed {
  from = aws_s3_bucket.old_reports
  lifecycle { destroy = false }
}

Secrets state बाहेर ठेवणे, किंवा state मध्ये अधिक सुरक्षित ठेवणे:

apply च्या वेळी secrets secret manager मधून (AWS Secrets Manager, Vault) वाचा आणि state च्या storage ला कडक access आणि encryption at rest द्या (धडा 08);
ephemeral values आणि resources (Terraform 1.10+) आणि write-only arguments (Terraform 1.11+, जिथे provider त्यांना support करतो) कधीच state मध्ये साठवले जात नाहीत;
OpenTofu (1.7+) संपूर्ण state file साठवण्याआधी client वरच encrypt करू शकते.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: state ला secret समजा. प्रत्येक state file कुठे आहे, ती कोण वाचू शकते, ती encrypted आणि versioned आहे, आणि तिची कोणतीही प्रत git मध्ये किंवा laptops वर नाही, हे तुम्हाला माहीत असायला हवे.

⏭️ पुढे

नोंदवही dependencies सुद्धा नोंदवते — gate ला lab चा id लागतो. पुढे: dependency graph, जो क्रम ठरवतो आणि एकाच वेळी काय बांधता येते ते ठरवतो.

git checkout lesson-06-dependency-graph

📒 Lesson 05 — State: the site register

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-variables-loops · Next: lesson-06-dependency-graph

📦 What's in this branch

Lessons 01–04, plus the notebook the contractor has kept since lesson 01: the state, or the site register. For every address in the plans it records the real object's id and its last known attributes. Without it, the contractor cannot tell "build a new lab" from "the lab is already there". The register also holds secrets in plain text. state() in iac/demo.py; new_state(), refresh() and apply() in iac/engine.py.

🧒 Explain like I'm 5

The works office keeps a big book: the site register. 📒 One line per thing:

school_room.lab → room-01 · chem-lab · floor 2 · 30 seats school_locker.a → locker-01 · combination 6872

When the contractor comes back with new plans, the first thing she does is open the register. "The plans say lab. The register says lab is room-01. Let me go and look at room-01." That is how she knows the lab is already built.

One day the register falls in the river. 🌊 The contractor opens the plans, opens an empty register, and thinks: "No lab in the register? Then I must build one!" She builds a second chem-lab next to the first. Now there are two.

And look at that locker line again. The combination is written right there. Anyone who can read the register can open the locker. 🔓

🗺️ Diagram

flowchart LR
    plans["📜 plans<br/>school_room.lab"] -->|"which object?"| reg["📒 register (state)<br/>school_room.lab → room-01<br/>serial 1 · lineage campus-3f9a<br/>combination 6872 (plain text!)"]
    reg -->|"read room-01"| campus["🏫 campus<br/>room-01"]
    lost["🌊 register lost"] -->|"plan"| dup["Plan: 5 to add<br/>→ 2 chem-labs"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/terraform/lesson-diagrams.html#l05

❓ What

State — a JSON document Terraform writes after every apply. It maps each address in the config (aws_instance.web) to a real object (i-0abc…) and stores the object's attributes as last seen. By default it is the local file terraform.tfstate.
Why a map is needed — most cloud APIs cannot answer "which instance is aws_instance.web?". Names and tags are not unique or not always present. The state is the binding.
Serial — a counter that goes up each time the state is written with changes. The lab starts at 0 and adds 1 per apply that changed something.
Lineage — an id given to a state when it is first created, so Terraform can refuse to overwrite one state with an unrelated one.
Sensitive data in state — every attribute is stored, including passwords, private keys and generated secrets. sensitive = true hides a value in plan and output display only. The state file still holds it in plain text.
Real format vs the lab — real state (format version 4) lists resources as an array of {mode, type, name, provider, instances: [{attributes, dependencies}]}. The lab uses a flat map address → {type, id, attrs, deps}. Same idea, simpler shape.

🤔 Why

Because the register is what makes plans incremental. Lose it, and the next plan wants to create everything again — duplicates at best, name clashes and failed applies at worst. Corrupt it, and addresses point at the wrong objects. Leak it, and every secret in it leaks too. That is why state is never committed to git, lives in an encrypted remote store with versioning (lesson 08), and is read by as few people and jobs as possible.

🔧 How (in this repo)

new_state() in iac/engine.py makes an empty register with version, serial, lineage, resources and outputs. plan() starts with refresh(), which reads each id from the campus. apply() writes each object's id, attributes and dependencies into the register, stores outputs with their sensitive flag, and adds 1 to serial when anything changed. show_outputs() prints <sensitive> for sensitive outputs — while the value stays in state["outputs"].

🧪 Try it

python3 iac/demo.py state
python3 - <<'EOF'
import sys; sys.path.insert(0, "iac")
from cloud import FakeCloud
from engine import plan, apply
cloud, st = FakeCloud(), None
for seats in (30, 30, 40, 50):
    st, _, msg = apply(plan({"resource": {"school_room": {"lab": {"name": "lab", "seats": seats}}}}, st, cloud), cloud)
    print(f"seats {seats} → {msg} · serial {st['serial']}")
print("state list:", list(st["resources"]))
print("state show:", st["resources"]["school_room.lab"]["attrs"])
EOF

✅ Verify — what you should see

state prints:

   output lab_id = "room-01"
   output code_a = <sensitive>
── the register (state): version 4 · serial 1 · lineage campus-3f9a · 5 resources
   search the state for 'combination' → ['school_locker.a: 6872', 'school_locker.b: 4434', 'school_locker.c: 4123']
── the register is lost; plan with an empty one → Plan: 5 to add, 0 to change, 0 to destroy.
   after apply the campus has 2 rooms named ['chem-lab'] and 10 objects — duplicates, not the same campus

Your snippet prints:

seats 30 → Apply complete! Resources: 1 added, 0 changed, 0 destroyed. · serial 1
seats 30 → Apply complete! Resources: 0 added, 0 changed, 0 destroyed. · serial 1
seats 40 → Apply complete! Resources: 0 added, 1 changed, 0 destroyed. · serial 2
seats 50 → Apply complete! Resources: 0 added, 1 changed, 0 destroyed. · serial 3
state list: ['school_room.lab']
state show: {'name': 'lab', 'floor': 1, 'seats': 50, 'tags': {}, 'id': 'room-01'}

🏁 What you just proved

The output hid code_a, but a plain search of the register found all three locker combinations. With the register gone, the same plans planned 5 to add and built a second copy of everything: 10 objects, two chem-labs. And the serial only moves when something changed — the second apply with 30 seats left it at 1.

⚠️ Common mistakes

committing terraform.tfstate to git (add *.tfstate* to .gitignore)
trusting sensitive = true to keep a secret out of the state
editing the state JSON by hand — use terraform state commands, moved, import and removed blocks
keeping the only copy on a laptop — no versioning, no backup, no sharing (lesson 08)
giving every developer read access to prod state "just to run plan"

🏭 In production

On a real account — look at the register with the CLI, not an editor:

terraform state list                         # every address in the state
terraform state show aws_s3_bucket.timetables
terraform state pull > backup.tfstate        # a copy of the current remote state
terraform show -json | jq '.values.root_module.resources | length'

Changing the register safely:

# forget an object without destroying it (Terraform 1.7+)
removed {
  from = aws_s3_bucket.old_reports
  lifecycle { destroy = false }
}

Keeping secrets out of, or safer inside, the state:

read secrets at apply time from a secret manager (AWS Secrets Manager, Vault) and give the state's storage tight access and encryption at rest (lesson 08);
ephemeral values and resources (Terraform 1.10+) and write-only arguments (Terraform 1.11+, where a provider supports them) are never stored in state;
OpenTofu (1.7+) can encrypt the whole state file on the client before it is stored.

🏭 Why this matters in production: treat state as a secret. Know where every state file lives, who can read it, that it is encrypted and versioned, and that no copy sits in git or on laptops.

⏭️ Next

The register also records dependencies — the gate needs the lab's id. Next: the dependency graph, which decides the order and what can be built at the same time.

git checkout lesson-06-dependency-graph

← Previousvariables loops Next →dependency graph

This page is the lesson's README from the lesson-05-state branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.