DEV Community: SecOpsLog

Kubernetes NetworkPolicies — default-deny done right

secopslog — Sat, 11 Jul 2026 08:59:17 +0000

Default-deny and per-consumer allowlists.

💡 In plain terms: By default every pod can talk to every other pod — one big open-plan office. A NetworkPolicy adds doors and a guest list so only approved conversations happen. Just remember to leave the phone line (DNS) open.

The cluster network is flat and open by default — any pod can reach any other pod. NetworkPolicies are how you segment it, and adopting a default-deny posture with explicit allowlists is the single most effective control against lateral movement inside a cluster.

Default-deny and allowlists

A NetworkPolicy selects pods (by label) and specifies the ingress and egress traffic they are allowed — and crucially, the moment any policy selects a pod, that pod switches from allow-all to deny-all except what the policies permit. So the foundational move is a default-deny policy: one that selects all pods in a namespace and allows nothing, flipping the namespace from open to closed. Then you add targeted allow policies for the flows that must exist — the frontend may reach the API on port 8080, the API may reach the database on 5432, everything reaches DNS. This is the same least-privilege model as RBAC applied to the network: start closed, open only what is needed, and identify peers by label (podSelector/namespaceSelector) so rules follow workloads rather than fragile IPs.

# 1. Default-deny ALL ingress + egress in the namespace (flip it closed):
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: { name: default-deny, namespace: payments }
spec: { podSelector: {}, policyTypes: [Ingress, Egress] }
---
# 2. Allow only what is needed (and DON'T forget DNS egress):
kind: NetworkPolicy
metadata: { name: api-from-frontend, namespace: payments }
spec:
  podSelector: { matchLabels: { app: api } }
  ingress: [{ from: [{ podSelector: { matchLabels: { app: frontend } } }],
             ports: [{ port: 8080 }] }]

The two things that trip people up

Two caveats decide whether NetworkPolicies actually work. First, they are enforced by the CNI, not by Kubernetes itself — on a plugin that does not support them (basic Flannel) your policies are accepted by the API but silently unenforced, so you must confirm your CNI (Calico, Cilium) enforces them and test that a default-deny actually blocks traffic. Second, a default-deny egress policy blocks DNS unless you explicitly allow it — pods query CoreDNS in kube-system on port 53, and if your policy forgets that, name resolution fails for every affected pod and their dependencies appear down, a very common self-inflicted breakage. So the recipe is: verify the CNI enforces policy, apply default-deny, then add allows including DNS egress to kube-system, and test. Done right, NetworkPolicies box a compromised pod into the tiny set of flows you granted — the difference between a foothold that can scan and reach the whole cluster and one that can talk only to the two services it legitimately needs. This is the network complement to RBAC and security contexts, and it is the highest-leverage control against lateral movement.

⚠️ A default-deny that forgets DNS breaks every pod it covers: A default-deny egress policy blocks pods from reaching CoreDNS unless you explicitly allow DNS (port 53 to kube-system), so name resolution fails and dependencies appear down across the namespace. Always add a DNS egress allow when applying default-deny — and remember policies only work if your CNI enforces them, so verify a default-deny actually blocks traffic before relying on it.

This lesson is part of the free *Kubernetes administration** course at SecOpsLog — hands-on, command-first DevSecOps tutorials. Read the original with the full interactive version →*

Vault auth methods — OIDC for humans, Kubernetes for workloads

secopslog — Sat, 11 Jul 2026 08:47:00 +0000

Humans via SSO, workloads via service accounts.

Think of Vault as a secured building with two entrances. Humans walk in through the front lobby, where the badge reader is wired straight into your corporate identity provider — there is no separate Vault password to remember or leak, just the SSO login your engineers already have. Workloads use the loading dock around back, where the only ID that counts is the service account token the pod was born with. Same building, two very different doors, and each needs a different lock. Here we wire up both: OIDC for people, Kubernetes auth for machines.

The front door: OIDC for humans

OIDC auth lets Vault delegate the question "who are you?" to an identity provider you already trust — Okta, Entra ID, Google, Keycloak. Vault never sees a password. It redirects the browser to the IdP, receives a signed ID token back, and reads claims out of it. You bind a role to the IdP's client ID and tell Vault which claim uniquely identifies the person (user_claim) and which claim carries their group membership (groups_claim). The allowed_redirect_uris must list both the CLI's localhost callback and your Vault UI address, exactly — scheme, port, and path included. Get one character wrong and the IdP refuses the handoff before Vault ever sees a token. Because the Vault token that comes out is short-lived, the human re-authenticates through SSO when it expires, so disabling their account upstream cuts off Vault on its own.

# Turn on the OIDC auth method
vault auth enable oidc

# Point Vault at your identity provider
vault write auth/oidc/config \
    oidc_discovery_url="https://login.example.com" \
    oidc_client_id="$OIDC_CLIENT_ID" \
    oidc_client_secret="$OIDC_CLIENT_SECRET" \
    default_role="engineer"

# A role: which claims to trust, where to redirect, what token to mint
vault write auth/oidc/role/engineer \
    user_claim="sub" \
    groups_claim="groups" \
    oidc_scopes="openid,profile,groups" \
    bound_audiences="$OIDC_CLIENT_ID" \
    allowed_redirect_uris="http://localhost:8250/oidc/callback" \
    allowed_redirect_uris="https://vault.example.com/ui/vault/auth/oidc/oidc/callback" \
    token_policies="engineer" \
    token_ttl=1h

# Engineers now log in with:  vault login -method=oidc role=engineer

Turning SSO groups into Vault policy

Granting policy to individual users does not scale and drifts the moment someone changes teams. Instead, let group membership in your IdP drive Vault authorization. When a user logs in through OIDC, Vault reads the groups_claim and looks for a matching group alias. You pre-create an external identity group, attach the policies you want it to carry, and map the IdP's group name to it through a group alias keyed on the OIDC mount accessor. Now a person added to platform-eng in Okta inherits the platform policy on their very next login, and removing them there revokes it — no Vault change, no ticket, no stale grant left behind. Membership lives in exactly one system, and Vault follows it. The alias name must match the string your IdP actually emits in the groups claim, which is often a group ID rather than a display name.

# Grab the accessor of the OIDC mount
ACCESSOR=$(vault auth list -format=json | jq -r '."oidc/".accessor')

# External group that carries the policy
vault write identity/group name="platform-eng" \
    type="external" \
    policies="platform"

GROUP_ID=$(vault read -field=id identity/group/name/platform-eng)

# Alias ties the IdP's group name to the Vault group
vault write identity/group-alias \
    name="platform-eng" \
    mount_accessor="$ACCESSOR" \
    canonical_id="$GROUP_ID"

The loading dock: Kubernetes auth for workloads

Machines cannot do a browser redirect, so workloads authenticate with the one credential Kubernetes already hands every pod: its projected service account token. Vault takes that JWT, calls the cluster's TokenReview API to confirm it is genuine and unexpired, and — if the pod's service account name and namespace match a role's bindings — issues a Vault token in return. There is no secret to distribute and no static credential to rotate; the identity is the pod's own. Since Kubernetes 1.21 these tokens are time-bound and audience-scoped, so one scraped from a pod cannot be replayed forever or against a different audience. Bind each role narrowly to a service account name and namespace, so only the webapp pods in prod can ever assume the webapp policy — a compromised pod in another namespace gets nothing.

vault auth enable kubernetes

# In-cluster: you supply the host; Vault defaults to its own pod's
# service account token and the local cluster CA to reach the API
vault write auth/kubernetes/config \
    kubernetes_host="https://kubernetes.default.svc:443"

# Only the 'webapp' SA in 'prod' may assume this role
vault write auth/kubernetes/role/webapp \
    bound_service_account_names="webapp" \
    bound_service_account_namespaces="prod" \
    token_policies="webapp" \
    token_ttl=1h

# From inside the pod, exchange the SA token for a Vault token
TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
vault write auth/kubernetes/login role=webapp jwt="$TOKEN"

⚠️ TokenReview returns 403 and every pod login fails: With no token_reviewer_jwt on the mount, Vault does not review a pod's token with that same token — when Vault runs inside the cluster it uses its OWN pod's service account token to call the TokenReview API. So it is Vault's service account, not each application's, that must be bound to the system:auth-delegator ClusterRole. The Vault Helm chart wires this binding for the server service account by default, so in-cluster logins usually work out of the box — until someone overrides the chart's service account, or runs Vault outside the cluster. Out-of-cluster (or with disable_local_ca_jwt set) and still no reviewer JWT, Vault falls back to reviewing each login with the caller's own token, and now every authenticating service account needs the delegator — a brittle pattern. The durable fix is to set an explicit token_reviewer_jwt (a dedicated reviewer service account) so Vault always reviews with one privileged identity. Either way Kubernetes answers 403 as a misleading "permission denied" even when your role bindings are perfect, so check the RBAC before you burn an afternoon re-reading correct-looking bindings.

This lesson is part of the free *Vault from dev to production** course at SecOpsLog — hands-on, command-first DevSecOps tutorials. Read the original with the full interactive version →*

Helm template functions, pipelines & named templates

secopslog — Sat, 11 Jul 2026 08:42:42 +0000

DRY templates with helpers.

If the templating engine is the language, functions and named templates are its standard library plus the reusable helpers you write yourself. Think of a pipeline the way a shell pipes commands: a value flows left to right, and each function reshapes it before handing it on. Named templates are the functions you author — define a block of YAML once, give it a name, then call it from every manifest so a change lands in one place instead of twenty. The goal is staying DRY: composing built-in functions into pipelines, and factoring shared fragments into reusable helpers.

Functions and pipelines

Helm ships the Go template built-ins plus the entire Sprig library — string, list, math, encoding and date helpers. You call them two ways. Nested, reading right to left: quote (upper .Values.name). Or piped, reading left to right, where the pipe feeds the previous result in as the last argument of the next function. Pipelines are almost always clearer. The workhorses are default to supply a fallback, quote to wrap a value safely, trunc and trimSuffix to respect Kubernetes' 63-character name limit, and the conversion pair toYaml plus nindent for embedding a whole values block with correct indentation. Reach for printf when you need to build a composite string. Note that Helm deliberately disables a few Sprig functions such as env and expandenv, so a chart cannot read the machine it happens to render on.

# nested calls read right-to-left
name: {{ quote (default "app" .Values.name) }}

# the same thing as a pipeline, reading left-to-right
name: {{ .Values.name | default "app" | quote }}

# respect the 63-char name limit, then embed a whole block
label: {{ .Values.appName | lower | trunc 63 | trimSuffix "-" }}
config:
  {{- .Values.settings | toYaml | nindent 2 }}

Named templates with define and include

A named template is a fragment declared with define and rendered with include. By convention they live in templates/_helpers.tpl — files whose names start with an underscore are never rendered into Kubernetes objects themselves, they only supply helpers. Template names are global across a chart and all its subcharts, so the name is a dotted string namespaced to your chart, like myapp.labels, to keep subcharts from colliding. helm create scaffolds this pattern for you: a fullname helper that stitches the release name and chart name together, truncates to 63 characters and trims a trailing dash, plus shared label and selector blocks. Define the standard labels once and every Deployment, Service and ServiceAccount stays consistent for free. The dash-trimmed delimiters,{{ and }}, matter inside helpers because they strip the surrounding whitespace so the emitted YAML lines up.

templates/_helpers.tpl

{{/* A release-scoped name, safe for Kubernetes */}}
{{- define "myapp.fullname" -}}
{{- $name := default .Chart.Name .Values.nameOverride -}}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{/* Standard labels reused by every object */}}
{{- define "myapp.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
{{- end -}}

Scope, and why include beats template

Two things trip everyone up: how to indent the output, and what dot means inside the helper. Always call helpers with include, not the template action. include is a Helm-specific function that returns the rendered text as a string, so you can pipe it into nindent. template prints straight to output and cannot be piped, so you lose all control of indentation. The final argument you pass is the scope the helper sees as dot. Passing a plain dot hands over the current context; passing a dollar sign hands over the root context — the top-level scope that always holds .Values, .Release and .Chart. Inside a range, dot is the loop item, so to give a helper both the item and the root you package them into a dict and read them back by key.

# in a template that loops, bundle root ($) and item into one dict
{{- range .Values.services }}
  {{- include "myapp.serviceLabels" (dict "top" $ "svc" .) | nindent 4 }}
{{- end }}

# the helper reads the values back by key
{{- define "myapp.serviceLabels" -}}
app.kubernetes.io/instance: {{ .top.Release.Name }}
service: {{ .svc.name }}
{{- end -}}

⚠️ include is pipeable; template is not: Writing {{ template "myapp.labels" . | nindent 4 }} is a parse error — template is a bare action, not a function, so it cannot appear in a pipeline. Helm added include precisely to fix this: it does the same lookup but returns a string you can pipe into nindent, indent or toYaml. Prefer nindent N over a leading newline plus indent N, because nindent prepends the newline for you — which is exactly why you must never stack your own leading newline on top of it, or you get a blank line and shifted indentation. nindent sets the block's indentation absolutely and re-indents every line it emits, so the normal, correct pattern is to put the include right after a mapping key (or alone on a dash-trimmed line) and let it own the whitespace. What you must not do is append anything after the include on the same line: its output ends without a trailing newline, so trailing text lands mis-indented — YAML that can lint clean locally yet fail once the manifest reaches the cluster.

This lesson is part of the free *Helm** course at SecOpsLog — hands-on, command-first DevSecOps tutorials. Read the original with the full interactive version →*

Kustomize bases & overlays — one base, every environment

secopslog — Sat, 11 Jul 2026 07:28:00 +0000

dev, staging, prod from one base.

A Kustomize base is a master recipe; overlays are the diners' tweaks. You cook one dish — a Deployment, a Service, a ConfigMap — that captures everything your app needs regardless of where it runs. Then, for each environment, you write a thin overlay that says "start from that recipe, but make dev quieter, staging half-sized, and prod cranked to eleven." Nothing is copied. The base stays the single source of truth, and every environment is expressed only as its difference from it. That difference is usually tiny — a handful of lines — which is exactly the point: the smaller the overlay, the less there is to drift, forget, or get wrong when you promote a change from dev to prod.

The base: your common denominator

A base is a complete, self-contained, deployable set of resources plus its own kustomization.yaml. That last part trips people up: a base is not a loose pile of YAML — it is itself a valid kustomization that lists the files it owns. Build it on its own and you get a working manifest for a generic, un-specialized deployment. Keep the base to the common denominator: the things that are true in every environment. The moment you find yourself adding a value that is only right for one environment, that value belongs in an overlay, not here. A useful test: could you hand this base to a teammate on a different cluster and have it apply cleanly? If it only works because dev's namespace happens to exist, it isn't really a base.

# myapp/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# A base is a real kustomization: it names the raw files it owns.
# These are the resources EVERY environment shares, unspecialized.
resources:
  - deployment.yaml   # generic Deployment: image, ports, 1 replica
  - service.yaml      # generic ClusterIP Service

Overlays: one per environment

An overlay is another kustomization.yaml that names the base in its resources: list — as a directory path, not a file. Below that reference sits only what makes this environment different: a distinct namespace, a name prefix so prod and dev objects never collide in a shared cluster, a replica count tuned to load. Kustomize reads the base, then layers your overlay changes on top, and emits the merged result. The overlay never edits the base's files; it declares deltas. This is why a three-line change to replica count in prod leaves dev and staging completely untouched — they don't share the overlay, only the base. Overlays can also stack — an overlay can itself serve as the base for another — but for dev/staging/prod a single flat base with three sibling overlays is the layout you want, and the one that stays legible a year later.

# myapp/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# Point at the base by RELATIVE DIRECTORY path (not a file).
resources:
  - ../../base

# Everything below is only what makes prod differ from the base:
namespace: myapp-prod   # isolate prod objects
namePrefix: prod-       # avoid name collisions in shared clusters

# Bump replicas for production load.
# Match by the ORIGINAL base name (myapp); namePrefix is applied
# separately, so this still targets the renamed prod-myapp object.
# (Deeper surgical edits use strategic-merge or JSON6902 patches.)
replicas:
  - name: myapp
    count: 5

Building each environment

Each environment is just a different directory to point the build at. kustomize build overlays/prod renders the fully-specialized prod manifests to stdout; kubectl apply -k overlays/prod does the same and applies them in one step. The key idea for overlays is that the same command, aimed at a different folder, produces a different environment from the identical base — no branching, no templating, no copy-paste drift between dev, staging, and prod. Diff two builds and the output is the set of deltas you declared, applied across the base.

myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/kustomization.yaml
    ├── staging/kustomization.yaml
    └── prod/kustomization.yaml

# Same command, different folder = different environment:
kustomize build overlays/dev
kustomize build overlays/prod

# Or render + apply in one shot (-k runs kustomize on the dir):
kubectl apply -k overlays/prod

⚠️ Paths resolve from the overlay, and 'bases:' is dead: Two things bite here. First, the old bases: field is deprecated — put base directories in the same resources: list as your files; kustomize treats a directory entry as a base and a file entry as a resource, so there is no separate field anymore. (A leftover bases: still builds but prints a deprecation warning; run kustomize edit fix to migrate it.) Second, paths in resources: are resolved relative to the overlay's own kustomization.yaml, not your shell's working directory — ../../base climbs up from overlays/prod/ to myapp/base/, and it will resolve the same no matter where you run the command from. By default, though, a kustomization cannot load a file from outside its own root: reference an individual YAML that sits above or beside your tree and the build fails with a security/load-restriction error. You can force it with kustomize build --load-restrictor LoadRestrictionsNone, but reaching for that flag is almost always a sign your layout is wrong, not that you need the escape hatch — restructure so the shared files live inside the tree instead.

This lesson is part of the free *Kustomize** course at SecOpsLog — hands-on, command-first DevSecOps tutorials. Read the original with the full interactive version →*

Argo CD sync policies & self-heal, explained

secopslog — Sat, 11 Jul 2026 07:25:51 +0000

Auto-sync, prune, self-heal.

A syncPolicy is the thermostat setting for an Argo CD Application. Argo CD continuously compares Git against the live cluster to detect drift; the sync policy decides what it does about it — whether it waits for a human to press sync, or acts on its own. Left at the default, an OutOfSync app just sits there flagged until someone runs argocd app sync. Turn on automation and that same detection becomes continuous delivery: every commit to the tracked revision rolls out by itself, and the cluster is dragged back toward Git whenever it strays. Three switches shape how far that goes.

Automated, prune, and self-heal

spec.syncPolicy.automated is the master switch: with it set, Argo CD syncs automatically after any reconcile where Git and the cluster differ, with no manual step. Inside it, two booleans decide how aggressive that is. prune governs deletions — by default an automated sync only creates and updates, so a manifest you delete from Git leaves its live object orphaned in the cluster until you set prune: true, at which point a removal in Git becomes a deletion in the cluster. selfHeal governs the other direction: with it off, drift you introduce out-of-band — an edited replica count, a hand-patched env var — is reported but left alone; with it on, Argo CD overwrites the live object back to what Git declares on the next pass. automated alone tracks Git forward; add prune and selfHeal and the cluster becomes a strict mirror of the repo.

spec:
  syncPolicy:
    automated:
      prune: true        # delete resources removed from Git
      selfHeal: true     # revert out-of-band drift back to Git
      allowEmpty: false  # refuse to prune everything (the default)
# equivalent via the CLI:
# argocd app set payments-api --sync-policy automated --auto-prune --self-heal

Sync options and retry

Beyond the three switches, syncOptions tune the mechanics of each sync. CreateNamespace=true makes Argo CD create the destination namespace instead of failing when it is absent. ApplyOutOfSyncOnly=true skips resources that already match, so large apps reconcile faster. PruneLast=true defers deletions until everything else is healthy, so a rename removes the old object only after its replacement is up. PrunePropagationPolicy=foreground makes a deletion block on its dependents rather than orphaning them. And retry decides what happens when a sync fails: limit caps the attempts while backoff grows the wait between them, so a transient failure — an image not yet pushed, a webhook briefly down — is retried with increasing delay instead of either giving up or hammering the API. These options apply to manual and automated syncs alike; they describe how a sync runs, not when.

spec:
  syncPolicy:
    syncOptions:
      - CreateNamespace=true       # create the namespace if it is missing
      - ApplyOutOfSyncOnly=true    # skip resources already in sync
      - PruneLast=true             # delete only after the rest is healthy
      - PrunePropagationPolicy=foreground
    retry:
      limit: 5
      backoff: { duration: 5s, factor: 2, maxDuration: 3m }

A posture for each environment

The right policy is not one setting but a spectrum you choose per environment. Dev and preview environments usually run fully automated with prune and selfHeal for hands-off, always-fresh clusters — mistakes there are cheap and self-correcting. Production often runs automated without selfHeal, or manual sync entirely, so a human still confirms the rollout and can pause it mid-incident; the review gate then lives in branch protection on the Git repo rather than at deploy time, which is where GitOps wants it. Keep allowEmpty at its default of false everywhere: it stops an automated sync from pruning every resource when a bad Helm render or an empty path briefly makes Git look like it declares nothing — the difference between a harmless no-op and deleting your entire app. Individual resources can also opt out of prune with a sync-options annotation, which is worth doing for anything stateful.

# prod: automated apply, but no self-heal — a human still owns live drift
$ argocd app set payments-api --sync-policy automated --auto-prune

# revert prod to fully manual (the default when there is no automated block)
$ argocd app set payments-api --sync-policy none

# shield one resource from prune, in its own manifest:
#   metadata:
#     annotations:
#       argocd.argoproj.io/sync-options: Prune=false

⚠️ Self-heal fights any controller that owns the same field: selfHeal rewrites the live object to match Git on every pass, so if another controller legitimately writes a field Argo CD manages, the two fight forever. The classic case is a HorizontalPodAutoscaler adjusting spec.replicas while Argo CD keeps resetting it to the number baked into the manifest — the app flaps between Synced and OutOfSync and pods churn on every reconcile. The fix is not to switch self-heal off but to stop Argo CD from diffing that one field: add a spec.ignoreDifferences entry targeting /spec/replicas so Git owns the manifest and the HPA owns its one field (or, cleaner, drop replicas from the manifest entirely so there is nothing to reconcile). Argo CD ships no default ignore for this — you configure it yourself. Before enabling self-heal cluster-wide, audit what else mutates your resources — admission webhooks, service meshes, cert-manager injecting CA bundles — because each of those is a candidate for the same tug-of-war.

This lesson is part of the free *Argo CD** course at SecOpsLog — hands-on, command-first DevSecOps tutorials. Read the original with the full interactive version →*

Migrating from Terraform to OpenTofu, safely

secopslog — Sat, 11 Jul 2026 07:22:44 +0000

Move an existing project, safely.

Migrating from Terraform to OpenTofu is less an engine transplant than a badge swap. OpenTofu began as a line-for-line fork of Terraform 1.5, so your .tf files and your state mean exactly the same thing to tofu as they did to terraform; your .terraform.lock.hcl is understood in the identical format, the one file tofu init will regenerate as it re-sources provider hashes from OpenTofu's registry. The migration is mostly deleting one binary from your habits and pointing your muscle memory at another. The care goes not into rewriting code but into proving that nothing changed: the acceptance test for a good migration is that the very first tofu plan against your existing state comes back empty. Everything below is about earning that empty plan and having a way back if you don't get it.

Back up state before you touch anything

Even a drop-in replacement deserves a rollback plan, because state is the only irreplaceable artifact in the project. Your .tf files live in git and can be re-checked-out at will, but the state file is the map from that code to the real resources it owns; lose it or corrupt it and you own orphaned infrastructure with no way to plan against it. So copy the state and the dependency lock file before you run a single tofu command. If you're on a remote backend, pull a local snapshot with the terraform binary while it's still installed, and note the exact Terraform version that last wrote the state, because that version dictates whether OpenTofu can read it cleanly.

# Local backend: copy the state and the provider lock
cp terraform.tfstate terraform.tfstate.backup.pre-tofu
cp .terraform.lock.hcl .terraform.lock.hcl.backup

# Remote backend: snapshot state to a local file first
terraform state pull > pre-tofu.tfstate

# Record which Terraform version wrote this state (matters below)
terraform version

Swap terraform for tofu and confirm an empty plan

With the tofu CLI installed, the operative commands are the same three you already run. tofu init re-reads your backend and re-resolves providers (now from the OpenTofu registry) and rewrites .terraform.lock.hcl with OpenTofu-sourced hashes for the same provider versions. Then tofu plan is your verdict. A migration that worked prints No changes. Your infrastructure matches the configuration. If tofu instead wants to add, change, or destroy anything, stop and read the diff: a non-empty plan almost never means your infrastructure drifted overnight. It means a provider version or source address resolved differently, so fix the resolution rather than applying the plan.

tofu init            # re-resolves providers, rewrites the lock with OpenTofu hashes
tofu plan            # the acceptance test -- expect an empty diff

# Expected tail of a clean migration:
# No changes. Your infrastructure matches the configuration.

# The regenerated .terraform.lock.hcl is a repo file, not state --
# commit it to version control so CI resolves identical hashes:
git add .terraform.lock.hcl

# A clean, empty-plan cutover needs no apply. Your next real
# infrastructure change is the first 'tofu apply' you run.

What changes — and what reassuringly doesn't

Very little of your configuration is actually Terraform-specific, and the one construct people fear they must rip out survives the fork. OpenTofu kept the terraform {} settings block name, so you rename nothing, and it still honours TF_VAR_, TF_WORKSPACE, TF_CLI_ARGS, and every other TF_-prefixed environment variable, so none of your CI variables change (OpenTofu also adds TOFU_-prefixed equivalents that win when both are set). Even the cloud {} block lives on: OpenTofu retains it, and its cloud backend documents connecting to HCP Terraform (formerly Terraform Cloud) or Terraform Enterprise, so you are not forced to delete it just to run tofu. What genuinely does not cross the fork are HCP Terraform's proprietary features — Sentinel policy sets, run tasks, drift detection, no-code modules — which are HashiCorp-only and have no OpenTofu equivalent. So the real decision is platform, not syntax: keep the cloud block if you're staying on HCP or Terraform Enterprise, or, if you're leaving that platform entirely, swap it for a standard backend such as S3 or GCS. Only the CLI you invoke is guaranteed to change.

# The cloud block is NOT Terraform-only -- OpenTofu keeps it, and its
# cloud backend can target HCP Terraform or Terraform Enterprise:
terraform {
  cloud {
    organization = "acme"
    workspaces { name = "prod" }
  }
}

# Only if you are LEAVING that platform entirely do you swap it for a
# standard backend:
terraform {
  backend "s3" {
    bucket = "acme-tofu-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

⚠️ Match your OpenTofu version to the Terraform you're leaving: State is broadly forward-compatible: OpenTofu 1.6 forked from Terraform 1.5/1.6, and later OpenTofu releases deliberately track Terraform's state format, so tofu reads state written by Terraform 1.5 through 1.9 without a format wall. Two real hazards remain. First, the version marker: state records the version that last wrote it, and a tool can refuse state stamped by a version newer than itself with a 'state snapshot was created by … which is newer than current' error — so if a teammate already ran terraform apply with a version ahead of the OpenTofu you install, install an OpenTofu release at least as new before you migrate. Second, config features: a project using a Terraform-only feature newer than your OpenTofu (for example a 1.8+ provider-defined function) can fail tofu init or tofu plan even when the state itself reads fine — again cured by installing a recent-enough OpenTofu and migrating from a version you control rather than one someone has already leapfrogged. Never hand-edit the version or terraform_version fields to force a load; you'll risk corrupting resource decoding and losing the state you were trying to save. Finally, treat the cutover as one-way: add a guard in CI so nobody keeps running terraform apply against tofu-managed state and quietly stamps the marker back the other way.

This lesson is part of the free *OpenTofu** course at SecOpsLog — hands-on, command-first DevSecOps tutorials. Read the original with the full interactive version →*