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

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

🔒 धडा 08 — Remote state आणि locking: एक नोंदवही, एकच लिहिणारी

📍 तुम्ही इथे आहात: 12 पैकी धडा 08 · मागील: lesson-07-modules · पुढील: lesson-09-drift-import

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

धडे 01–07, आणि त्यासोबत teamwork. नोंदवही laptop वरून निघून एका remote backend मध्ये जाते — एक सामायिक जागा जिथे सगळे वाचतात आणि लिहितात. आणि त्या backend ला कुलूप असते: एक run ते धरून ठेवत असताना, दुसऱ्या run ला पहिल्या run चे काम गुपचूप पुसून टाकण्याऐवजी Error acquiring the state lock मिळतो. locking() हे iac/demo.py मध्ये आहे; Backend हे iac/engine.py मध्ये.

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

नोंदवही आता कोणाच्याही दप्तरात नाही, तर शाळेच्या कार्यालयात राहते. 🏫📒

सोमवारी कतरिना आणि दीपिका दोघींनाही काहीतरी बांधायचे आहे. दोघी कार्यालयात जातात आणि नोंदवहीची प्रत घेतात (त्यात लिहिले आहे: एक lab). कतरिना एक gym बांधते. दीपिका एक library बांधते. कतरिना आपली प्रत परत लिहिते: lab, gym. मग दीपिका तिची प्रत परत लिहिते: lab, library. दीपिकाची प्रत जिंकते.

आता नोंदवहीत लिहिले आहे lab, library. पण campus वर एक gym सुद्धा आहे! कोणाच्याच नोंदवहीला त्याबद्दल माहीत नाही. ते बांधलेले आहे, त्याचा खर्च होतो आहे, आणि कोणताही आराखडा कधीच त्याची काळजी घेणार नाही. 👻

म्हणून कार्यालयाला नोंदवहीसाठी एक किल्ली 🔑 मिळते. जिच्याकडे किल्ली, तीच लिहू शकते. कतरिनाकडे किल्ली असताना दीपिका आली, तर कार्यालय सांगते: "माफ करा — किल्ली कतरिनाकडे आहे, एका apply साठी." दीपिका थांबते, मग नवी नोंदवही वाचते — आणि आता तिचा plan दाखवतो की तिची branch gym पाडून टाकेल, कारण तिच्या आराखड्यात ते अजून नाही. ती आधी कतरिनाचा बदल घेते. मग सगळे सुरक्षित होते.

🗺️ आकृती

sequenceDiagram
    participant K as Katrina
    participant B as backend (register + lock)
    participant D as Dipika
    K->>B: lock → lock-0001 ✅
    D->>B: lock → Error acquiring the state lock (Who: katrina)
    K->>B: write state serial 2 (lab, gym) · unlock
    D->>B: lock → lock-0002 ✅ · read serial 2
    Note over D: plan: 1 to add, 1 to destroy ← her branch lacks the gym
    D->>B: pull Katrina's change → 1 to add · write serial 3 · unlock

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

❓ काय

Backend — Terraform state जिथे ठेवते ती जागा: default म्हणून local (एक file), किंवा remote backend: S3, GCS, azurerm, HCP Terraform, Consul, PostgreSQL, Kubernetes, आणि इतर. backend block मध्ये configure केले जाते आणि terraform init ते वाचते.
Remote state — सामायिक जागी नोंदवहीची एकच प्रत, access control, encryption at rest आणि (ते सुरू करा) versioning सह, म्हणजे एखादे चुकीचे लिखाण मागे घेता येते.
State locking — state लिहू शकणाऱ्या कोणत्याही operation आधी (plan, apply, destroy, import …), Terraform lock घेते. दुसरा run "Error acquiring the state lock" देऊन अपयशी ठरतो आणि Lock Info दाखवतो: ID, Path, Operation, Who. -lock-timeout=5m लगेच अपयशी होण्याऐवजी वाट पाहते.
Lost update — दोन लिहिणारे एकच version वाचतात आणि दोघेही लिहितात; दुसरे लिखाण पहिले पुसून टाकते. कुलूप नसेल तर हे गुपचूप घडते.
Orphan — अशी खरी वस्तू जिच्याबद्दल कोणत्याच state ला माहीत नाही. कोणी तिचा plan करत नाही, कोणी तिला destroy करत नाही, आणि तिचा खर्च चालूच राहतो.
force-unlock — terraform force-unlock LOCK_ID crash झालेल्या run ने मागे सोडलेले lock काढून टाकते. फक्त तो run संपला आहे याची खात्री असेल तेव्हाच.

🤔 का

कारण ज्या क्षणी दोन लोक (किंवा एक व्यक्ती आणि एक CI job) एकाच campus वर Terraform चालवतात, त्या क्षणी laptop वरची नोंदवही रचनेनेच चुकीची ठरते: प्रत्येकाकडे वेगळी प्रत असते. Remote state सगळ्यांना तीच नोंदवही देते. Locking मुळे लिखाण एका वेळी एक होते. या दोघांपैकी कोणीही दोन लोकांचे आराखडे merge करत नाही — ते काम अजूनही git चे आहे, जसे दीपिकाचे 1 to destroy दाखवते.

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

iac/engine.py मधील Backend states (path → state) आणि locks (path → lock info) ठेवते. lock(path, who) lock-0001 सारखा id परत देते, किंवा path locked असेल तर धारकाच्या माहितीसह LockError उठवते. unlock(path, id) फक्त योग्य id नेच चालते. apply(..., backend=be, key=path) नवी state backend मध्ये लिहिते. iac/demo.py मधील locking() सोमवारची गोष्ट दोनदा चालवते: एकदा कुलूपाशिवाय आणि एकदा कुलूपासह.

🧪 करून पाहा

python3 iac/demo.py locking
python3 - <<'EOF'
import sys; sys.path.insert(0, "iac")
from engine import Backend, LockError
be = Backend(); path = be.path()
a = be.lock(path, "katrina@works-office")
for who in ("dipika@works-office", "aishwarya@ci"):
    try: be.lock(path, who)
    except LockError as e: print(who, "→", e)
be.unlock(path, "lock-9999"); print("unlock with the wrong id → still locked:", path in be.locks)
be.unlock(path, a); print("unlock with", a, "→ still locked:", path in be.locks)
print("next lock:", be.lock(path, "dipika@works-office"))
EOF

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

locking हे छापते:

   both read serial 1 · Katrina: Plan: 1 to add, 0 to change, 0 to destroy. · Dipika: Plan: 1 to add, 0 to change, 0 to destroy.
   both wrote serial 2; Dipika wrote last → the register knows ['school_room.lab', 'school_room.library']
   the campus has 3 rooms, the register knows 2 → orphan: ['gym'] — built, paid for, managed by nobody
   Dipika → Error acquiring the state lock · Lock Info: ID lock-0001 · Path campus.tfstate · Operation OperationTypeApply · Who katrina@works-office
   Katrina is done (serial 2); Dipika gets lock-0002, reads the NEW register → Plan: 1 to add, 0 to change, 1 to destroy.  ← her branch lacks the gym
   she pulls Katrina's change first → Plan: 1 to add, 0 to change, 0 to destroy.
   Apply complete! Resources: 1 added, 0 changed, 0 destroyed. serial 3 · campus rooms 3 = register 3

तुमचा snippet हे छापतो:

dipika@works-office → Error acquiring the state lock · Lock Info: ID lock-0001 · Path campus.tfstate · Operation OperationTypeApply · Who katrina@works-office
aishwarya@ci → Error acquiring the state lock · Lock Info: ID lock-0001 · Path campus.tfstate · Operation OperationTypeApply · Who katrina@works-office
unlock with the wrong id → still locked: True
unlock with lock-0001 → still locked: False
next lock: lock-0002

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

कुलूपाशिवाय, दोन बरोबर plans मुळे चुकीची नोंदवही तयार झाली: दोघींनी serial 2 लिहिले, दुसरे लिखाण जिंकले, आणि gym orphan झाले (campus वर 3 खोल्या, नोंदवहीत 2). कुलूपासह, दुसरा run नाकारला गेला, आणि तो नंतर चालला तेव्हा त्याने नव्या नोंदवहीवरून plan केला — त्यामुळे खरा संघर्ष (1 to destroy) लपून न राहता उघड झाला. कुलूप फक्त त्याच्या स्वतःच्या id नेच उघडते.

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

locking बंद केलेला remote backend, किंवा ज्याला locking च नाही असा backend
सहकाऱ्याचे apply अजून चालू असताना plan "अडकल्यासारखा वाटतो" म्हणून force-unlock चालवणे
सगळ्यासाठी एकच प्रचंड state — प्रत्येक run सगळ्यांना lock करतो, आणि एक चूक सगळ्याला हात लावू शकते
state bucket वर bucket versioning नसणे — चुकीचे लिखाण परत फिरवता येत नाही
एकाच state वर CI applies आणि laptop applies मिसळणे (धडा 12 CI ला एकमेव लिहिणारा बनवतो)

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

खऱ्या account वर — S3-native locking सह S3 remote state (Terraform 1.10+; त्याआधी S3 वर locking साठी DynamoDB table लागत असे, जे नव्या versions मध्ये deprecated आहे):

terraform {
  backend "s3" {
    bucket       = "school-tfstate-example"
    key          = "campus/terraform.tfstate"
    region       = "ap-south-1"
    encrypt      = true
    use_lockfile = true      # writes campus/terraform.tfstate.tflock next to the state
  }
}

aws s3api put-bucket-versioning --bucket school-tfstate-example \
    --versioning-configuration Status=Enabled
terraform init -migrate-state          # move an existing local state into the bucket
terraform plan -lock-timeout=5m        # wait up to 5 minutes for a held lock
terraform force-unlock 6d1f7c0e-...    # only when the lock's owner is certainly dead

इतर backends आपापल्या पद्धतीने lock करतात: GCS state च्या शेजारी एक lock object लिहिते, azurerm state blob वर lease घेते, HCP Terraform service मध्येच प्रत्येक workspace ला lock करते. मोठ्या estates ची अनेक states मध्ये विभागणी करा (network, data, apps) आणि त्यांच्यातील मूल्ये outputs आणि terraform_remote_state data source ने वाचा — किंवा त्याहून चांगले, खऱ्या objects वाचणाऱ्या data sources ने.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे आहे: आजच प्रत्येक state bucket वर तीन गोष्टी तपासा: versioning सुरू, encryption सुरू, public access blocked — आणि त्या bucket कडे निर्देश करणाऱ्या प्रत्येक backend block मध्ये locking configure केलेले आहे.

⏭️ पुढे

नोंदवही तेव्हाच बरोबर राहू शकते जेव्हा कोणीही तिच्या नकळत campus बदलत नाही. पण कोणीतरी नेहमीच बदलतो. पुढे: drift आणि import.

git checkout lesson-09-drift-import

🔒 Lesson 08 — Remote state & locking: one register, one writer

📍 You are here: Lesson 08 of 12 · Previous: lesson-07-modules · Next: lesson-09-drift-import

📦 What's in this branch

Lessons 01–07, plus teamwork. The register moves off the laptop into a remote backend — one shared place everyone reads and writes. And the backend has a lock: while one run holds it, a second run gets Error acquiring the state lock instead of silently overwriting the first run's work. locking() in iac/demo.py; Backend in iac/engine.py.

🧒 Explain like I'm 5

The register now lives in the school office, not in anyone's bag. 🏫📒

On Monday, Katrina and Dipika both want to build something. They both walk to the office and copy the register (it says: one lab). Katrina builds a gym. Dipika builds a library. Katrina writes her copy back: lab, gym. Then Dipika writes her copy back: lab, library. Dipika's copy wins.

Now the register says lab, library. But the campus has a gym too! Nobody's register knows about it. It is built, it costs money, and no plan will ever look after it. 👻

So the office gets a key 🔑 for the register. Whoever takes the key can write. When Dipika comes while Katrina has the key, the office says: "Sorry — Katrina has it, for an apply." Dipika waits, then reads the new register — and her plan now shows that her branch would destroy the gym, because her plans don't have it yet. She pulls Katrina's change first. Then it is safe.

🗺️ Diagram

sequenceDiagram
    participant K as Katrina
    participant B as backend (register + lock)
    participant D as Dipika
    K->>B: lock → lock-0001 ✅
    D->>B: lock → Error acquiring the state lock (Who: katrina)
    K->>B: write state serial 2 (lab, gym) · unlock
    D->>B: lock → lock-0002 ✅ · read serial 2
    Note over D: plan: 1 to add, 1 to destroy ← her branch lacks the gym
    D->>B: pull Katrina's change → 1 to add · write serial 3 · unlock

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

❓ What

Backend — where Terraform stores state: local (a file) by default, or a remote one: S3, GCS, azurerm, HCP Terraform, Consul, PostgreSQL, Kubernetes, and others. Configured in a backend block and read by terraform init.
Remote state — one copy of the register in a shared place, with access control, encryption at rest and (turn it on) versioning so a bad write can be rolled back.
State locking — before any operation that could write state (plan, apply, destroy, import …), Terraform takes a lock. A second run fails with "Error acquiring the state lock" and shows the Lock Info: ID, Path, Operation, Who. -lock-timeout=5m waits instead of failing at once.
Lost update — two writers read the same version and both write; the second write erases the first. Without a lock this happens silently.
Orphan — a real object that no state knows about. Nobody plans it, nobody destroys it, it keeps costing money.
force-unlock — terraform force-unlock LOCK_ID removes a lock left behind by a crashed run. Only when you are sure that run is dead.

🤔 Why

Because the moment two people (or a person and a CI job) run Terraform against the same campus, a laptop register is wrong by design: each has a different copy. Remote state gives everyone the same register. Locking makes writes one at a time. Neither of them merges two people's plans — that is still git's job, as Dipika's 1 to destroy shows.

🔧 How (in this repo)

Backend in iac/engine.py keeps states (path → state) and locks (path → lock info). lock(path, who) returns an id like lock-0001, or raises LockError with the holder's info if the path is locked. unlock(path, id) only works with the right id. apply(..., backend=be, key=path) writes the new state to the backend. locking() in iac/demo.py runs the Monday story twice: without the lock and with it.

🧪 Try it

python3 iac/demo.py locking
python3 - <<'EOF'
import sys; sys.path.insert(0, "iac")
from engine import Backend, LockError
be = Backend(); path = be.path()
a = be.lock(path, "katrina@works-office")
for who in ("dipika@works-office", "aishwarya@ci"):
    try: be.lock(path, who)
    except LockError as e: print(who, "→", e)
be.unlock(path, "lock-9999"); print("unlock with the wrong id → still locked:", path in be.locks)
be.unlock(path, a); print("unlock with", a, "→ still locked:", path in be.locks)
print("next lock:", be.lock(path, "dipika@works-office"))
EOF

✅ Verify — what you should see

locking prints:

   both read serial 1 · Katrina: Plan: 1 to add, 0 to change, 0 to destroy. · Dipika: Plan: 1 to add, 0 to change, 0 to destroy.
   both wrote serial 2; Dipika wrote last → the register knows ['school_room.lab', 'school_room.library']
   the campus has 3 rooms, the register knows 2 → orphan: ['gym'] — built, paid for, managed by nobody
   Dipika → Error acquiring the state lock · Lock Info: ID lock-0001 · Path campus.tfstate · Operation OperationTypeApply · Who katrina@works-office
   Katrina is done (serial 2); Dipika gets lock-0002, reads the NEW register → Plan: 1 to add, 0 to change, 1 to destroy.  ← her branch lacks the gym
   she pulls Katrina's change first → Plan: 1 to add, 0 to change, 0 to destroy.
   Apply complete! Resources: 1 added, 0 changed, 0 destroyed. serial 3 · campus rooms 3 = register 3

Your snippet prints:

dipika@works-office → Error acquiring the state lock · Lock Info: ID lock-0001 · Path campus.tfstate · Operation OperationTypeApply · Who katrina@works-office
aishwarya@ci → Error acquiring the state lock · Lock Info: ID lock-0001 · Path campus.tfstate · Operation OperationTypeApply · Who katrina@works-office
unlock with the wrong id → still locked: True
unlock with lock-0001 → still locked: False
next lock: lock-0002

🏁 What you just proved

Without a lock, two correct plans produced a wrong register: both wrote serial 2, the second write won, and the gym became an orphan (3 rooms on the campus, 2 in the register). With the lock, the second run was refused, and when it ran later it planned against the new register — which exposed the real conflict (1 to destroy) instead of hiding it. The lock only opens with its own id.

⚠️ Common mistakes

a remote backend with locking turned off, or a backend that has no locking
running force-unlock because a plan "seems stuck" while a colleague's apply is still running
one giant state for everything — every run locks everyone, and one mistake can touch everything
no bucket versioning on the state bucket — a bad write cannot be undone
mixing CI applies and laptop applies on the same state (lesson 12 makes CI the only writer)

🏭 In production

On a real account — S3 remote state with S3-native locking (Terraform 1.10+; before that, locking on S3 needed a DynamoDB table, which newer versions deprecate):

terraform {
  backend "s3" {
    bucket       = "school-tfstate-example"
    key          = "campus/terraform.tfstate"
    region       = "ap-south-1"
    encrypt      = true
    use_lockfile = true      # writes campus/terraform.tfstate.tflock next to the state
  }
}

aws s3api put-bucket-versioning --bucket school-tfstate-example \
    --versioning-configuration Status=Enabled
terraform init -migrate-state          # move an existing local state into the bucket
terraform plan -lock-timeout=5m        # wait up to 5 minutes for a held lock
terraform force-unlock 6d1f7c0e-...    # only when the lock's owner is certainly dead

Other backends lock in their own way: GCS writes a lock object next to the state, azurerm takes a lease on the state blob, HCP Terraform locks per workspace in the service. Split large estates into several states (network, data, apps) and read values across them with outputs and the terraform_remote_state data source — or better, with data sources that read the real objects.

🏭 Why this matters in production: check three things on every state bucket today: versioning on, encryption on, public access blocked — and that locking is configured in every backend block that points at it.

⏭️ Next

The register can only be right if nobody changes the campus behind its back. Someone always does. Next: drift and import.

git checkout lesson-09-drift-import

← Previousmodules Next →drift import

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