Terraform IaC DynamoDB

Terraform state lock zablokowany: Error acquiring the state lock

Naprawa zablokowanego Terraform state lock, gdy terraform plan lub apply kończy się błędem Error acquiring the state lock po przerwanej operacji.

Jerzy Kopaczewski · 2026-06-21

Terraform odmawia wykonania plan lub apply: „Error acquiring the state lock". Żadne zmiany w infrastrukturze nie mogą przejść, dopóki blokada nie zostanie usunięta. Ten runbook pokazuje jak bezpiecznie zweryfikować i usunąć stuck lock.

Ten runbook opisuje problemy z blokadą state w Terraform, typowe w zespołach z remote backend. Aby uzyskać wsparcie w zarządzaniu infrastrukturą, zobacz Chmura pod kontrolą lub umów konsultację.

Objaw

terraform plan lub terraform apply natychmiast kończy się błędem blokady:

# Terraform refuses to acquire state lock
terraform plan

# Error: Error acquiring the state lock
#
# Error message: ConditionalCheckFailedException: The conditional request failed
# Lock Info:
#   ID:        a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   Path:      my-project/terraform.tfstate
#   Operation: OperationTypeApply
#   Who:       user@hostname
#   Version:   1.5.7
#   Created:   2026-06-20 14:32:01.123456 +0000 UTC
#   Info:
#
# Terraform acquires a state lock to protect the state from being
# written by multiple users at the same time.

Blokada utrzymuje się w nieskończoność. Wszystkie komendy plan, apply i destroy nie przechodzą dla całego zespołu. Pipeline CI/CD korzystające z tego state file są również zablokowane.

Przyczyna

Terraform używa mechanizmu blokady, aby zapobiec równoczesnym modyfikacjom state. Przy backendach AWS blokada jest przechowywana w tabeli DynamoDB. Blokada utyka, gdy:

Operacja terraform apply została przerwana (Ctrl+C, timeout sieci, ubity runner CI/CD)
Pipeline CI/CD przekroczył limit czasu lub został anulowany w trakcie operacji
Maszyna operatora uległa awarii podczas długiego apply
Nastąpiła partycja sieciowa między klientem a DynamoDB

Wpis blokady pozostaje w DynamoDB, ponieważ proces, który go utworzył, nigdy nie wykonał kroku unlock. Terraform nie ma wbudowanego TTL dla blokad, więc utrzymuje się ona do ręcznego usunięcia.

Rozwiązanie

A) Upewnij się, że żadna operacja nie jest aktualnie uruchomiona:

Przed wymuszeniem odblokowania potwierdź, że żaden uprawniony proces Terraform nie trzyma blokady:

# Check the lock info for details about who holds it
terraform plan 2>&1 | grep -A 10 "Lock Info"

# Check if any CI/CD pipeline is currently running Terraform
# (GitHub Actions example)
gh run list --workflow=terraform.yml --status=in_progress

# Check DynamoDB lock table directly
aws dynamodb get-item \
  --table-name terraform-state-locks \
  --key '{"LockID": {"S": "my-project/terraform.tfstate"}}' \
  --query 'Item.Info.S' --output text

B) Wymuś odblokowanie state (po potwierdzeniu braku aktywnej operacji):

# Use the Lock ID from the error message
terraform force-unlock a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Terraform will ask for confirmation:
# Do you really want to force-unlock?
# Terraform will remove the lock on the remote state.
# This will allow local Terraform commands to modify this state,
# even though it may still be in use. Only 'yes' will be accepted.
#
# Enter a value: yes

C) Usuń blokadę bezpośrednio z DynamoDB (jeśli force-unlock nie działa):

# If terraform force-unlock itself fails, remove the DynamoDB item directly
aws dynamodb delete-item \
  --table-name terraform-state-locks \
  --key '{"LockID": {"S": "my-project/terraform.tfstate"}}'

# Verify the lock is gone
aws dynamodb get-item \
  --table-name terraform-state-locks \
  --key '{"LockID": {"S": "my-project/terraform.tfstate"}}'
# Expected: empty response (no Item)

Prewencja: Skonfiguruj timeout CI/CD tak, aby zawsze przekraczał oczekiwany czas trwania Terraform. Dodaj krok cleanup w pipeline, który wykonuje terraform force-unlock w przypadku awarii. Rozważ opakowanie Terraform w skrypt, który łapie SIGTERM i próbuje graceful unlock przed zakończeniem.

Walidacja

# 1. Confirm terraform plan runs without lock errors
terraform plan
# Expected: normal plan output, no lock error

# 2. Verify state is consistent (no corruption from interrupted apply)
terraform plan -detailed-exitcode
# Exit code 0 = no changes needed (state is consistent)
# Exit code 2 = changes detected (review them before applying)

# 3. Check DynamoDB lock table is clean
aws dynamodb get-item \
  --table-name terraform-state-locks \
  --key '{"LockID": {"S": "my-project/terraform.tfstate"}}'
# Expected: empty response

# 4. Run a CI/CD pipeline to confirm it works end-to-end
# (trigger a no-op plan in your pipeline)

Jeśli terraform plan przechodzi bez błędu blokady, problem jest rozwiązany. Jeśli plan pokazuje nieoczekiwane zmiany, przerwany apply mógł częściowo zmodyfikować infrastrukturę. Przejrzyj diff uważnie przed zastosowaniem.

Zablokowany Terraform state oznacza brak jakichkolwiek zmian w infrastrukturze: zero wdrożeń, zero korekt skalowania, zero poprawek bezpieczeństwa. Dla zespołów bez doświadczenia z IaC zablokowana blokada może oznaczać godziny przestoju, zanim ktoś znajdzie sposób na bezpieczne jej usunięcie. Każda minuta z aktywną blokadą zwiększa ryzyko ręcznego obejścia (edycja state, ominięcie pipeline).

Terraform blokuje Twoje wdrożenia?

Umów bezpłatną 30-minutową rozmowę. Przejrzymy konfigurację IaC i pomożemy zapobiec problemom z blokadą state.