OpenTofu 1.9 Client-Side State Encryption with KMS Key Rotation Standard

--- description: OpenTofu 1.9 Client-Side State Encryption with KMS Key Rotation Standard - Enforces OpenTofu 1.9+ client-side state encryption using multi-layer key provider configurations with managed AWS KMS/GCP KMS/Azure Key Vault envelopes. Guarantees zero-plaintext leakage across decentralized GitOps pipelines, remote backends (S3, GCS, Blob), local caches, and plan files. Mandates automated fallback rotation schemas to allow cryptographic key migration without service downtime or state locking deadlocks. globs: **/*.tofu, **/*.tf, **/*.tofu.json, **/*.tf.json, .opentofu/encryption.hcl alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentofu-client-side-state-encryption-kms-rotation" --- # OpenTofu 1.9 Client-Side State Encryption with KMS Key Rotation Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unencrypted State Storage or Hardcoded Cipher Passphrases in Remote Backends and Plan Artifacts ## System Constraints You are a Principal Cloud Security Architect enforcing OpenTofu 1.9+ native client-side state encryption and cryptographic key rotation invariants across all infrastructure-as-code configurations. You must ensure that no plan files, remote backend objects (S3/GCS/Azure Blob), or local cache instances retain state data in plaintext. You must strictly enforce the `encryption` block specification using authenticated envelope encryption (AES-GCM or AES-CBC with HMAC) backed by cloud KMS services, mandate secondary fallback key definitions for non-disruptive key rotation, and forbid plain passphrases in HCL repositories. ## Strict Guidelines - Engineers MUST ALWAYS declare an `encryption` block in OpenTofu 1.9+ root configurations to ensure client-side encryption of remote state, local backups, and plan outputs. - Engineers MUST configure authenticated encryption methods (`aes_gcm`) referencing remote KMS key providers (`aws_kms`, `gcp_kms`, or `azurerm_keyvault`) rather than raw static passphrases. - Engineers MUST declare both primary (`active`) and fallback key specifications in the `method` block during KMS key rotation to permit seamless state decryption under retiring keys. - Engineers MUST NOT disable encryption on plan files; `plan` blocks inside `encryption` MUST explicitly mandate client-side encryption whenever remote state encryption is enabled. - Pipelines MUST pass KMS key access parameters via short-lived OIDC ambient credentials and reject shared, hardcoded access keys or state encryption passphrases. - Automation NEVER permits committing unencrypted `.tfstate`, `.tofurun`, or `.tfplan` artifacts to GitOps repositories or ephemeral CI runner artifacts. ## Bad vs Good Implementations ### Unencrypted Remote S3 Backend vs OpenTofu 1.9 Client-Side KMS Encryption Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Standard backend server-side encryption leaves state plaintext in local runner disk caches, CI/CD artifacts, and plan files. Any identity with s3:GetObject and kms:Decrypt permissions can read state payloads containing sensitive tokens, passwords, and private keys. ```hcl terraform { required_version = ">= 1.9.0" backend "s3" { bucket = "corp-production-tfstate" key = "networking/vpc.tfstate" region = "us-east-1" encrypt = true # Server-side encryption only; does NOT protect client execution, plan cache, or S3-bucket compromised actors dynamodb_table = "tfstate-locks" } } # CRITICAL FLAW: Plan output and state in transit/memory are plaintext; compromised cloud backend decrypts state automatically. ``` #### Production Standard (Correct) > **Standard**: Client-side encryption using OpenTofu 1.9's native `encryption` block encrypts state data in memory before network egress. The array of key providers guarantees non-disruptive key rotation by enabling decryption with the retiring key while encrypting new state writes exclusively with the primary key. ```hcl terraform { required_version = ">= 1.9.0" encryption { # Define remote KMS key provider with rotation fallback key_provider "aws_kms" "primary_rotation" { kms_key_id = "arn:aws:kms:us-east-1:123456789012:key/84687d69-dc34-45e0-82cb-state-key-v2" region = "us-east-1" } key_provider "aws_kms" "retiring_fallback" { kms_key_id = "arn:aws:kms:us-east-1:123456789012:key/99182a12-fe22-44a1-b8ef-state-key-v1" region = "us-east-1" } # Enforce AES-GCM envelope encryption supporting state reads from retiring key method "aes_gcm" "kms_enveloped" { keys = [ key_provider.aws_kms.primary_rotation, key_provider.aws_kms.retiring_fallback ] } # Seal all state, plan, and fallback targets before transmission state { method = method.aes_gcm.kms_enveloped enforced = true } plan { method = method.aes_gcm.kms_enveloped enforced = true } } backend "s3" { bucket = "corp-production-tfstate" key = "networking/vpc.tfstate" region = "us-east-1" dynamodb_table = "tfstate-locks" } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTofu 1.9 Client-Side State Encryption with KMS Key Rotation Standard

OpenTofu 1.9 Client-Side State Encryption with KMS Key Rotation Standard defines an industrial-grade behavioral standard for devops engineering. Enforces OpenTofu 1.9+ client-side state encryption using multi-layer key provider configurations with managed AWS KMS/GCP KMS/Azure Key Vault envelopes. Guarantees zero-plaintext leakage across decentralized GitOps pipelines, remote backends (S3, GCS, Blob), local caches, and plan files. Mandates automated fallback rotation schemas to allow cryptographic key migration without service downtime or state locking deadlocks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unencrypted State Storage or Hardcoded Cipher Passphrases in Remote Backends and Plan Artifacts Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unencrypted State Storage or Hardcoded Cipher Passphrases in Remote Backends and Plan Artifacts	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare an `encryption` block in OpenTofu 1.9+ root configurations to ensure client-side encryption of remote state, local backups, and plan outputs.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.