Migrate from OpenTofu or Terraform

You run OpenTofu or Terraform today. pravo drives the same providers, so your infrastructure stays where it is. What changes is the specification, which you write in CUE, and the state, which pravo keeps in its own format.

pravo reads an OpenTofu or Terraform state file once and converts it. Then it plans against the real objects. When the translation is right, the plan has nothing to do. A plan that has something to do means the CUE does not yet describe the object, and nothing is applied until it does. That empty plan is the gate.

The OpenTofu file below ran once, and OpenTofu wrote the state file that the terminal converts and plans. The CUE file is the specification that the terminal plans.

terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
  }
}

resource "random_pet" "server" {
  length = 2
}

resource "local_file" "motd" {
  filename = "motd.txt"
  content  = "serving ${random_pet.server.id}\n"
}

resource "local_file" "note" {
  for_each = toset(["alpha", "beta"])
  filename = "notes/${each.key}.txt"
  content  = "${each.key}\n"
}

package estate

import (
	rnd "pravo.dev/providers/hashicorp/random"
	loc "pravo.dev/providers/hashicorp/local"
)

$random: rnd.#Provider & {$version: "~> 3.6"}
$local:  loc.#Provider & {$version: "~> 2.5"}

server: $random.#Resource.random_pet & {
	$from:  "random_pet.server"
	length: 2
}

motd: $local.#Resource.local_file & {
	$from:    "local_file.motd"
	filename: "motd.txt"
	content:  "serving \(server.id)\n"
}

note: {
	for k in ["alpha", "beta"] {
		"\(k)": $local.#Resource.local_file & {
			$from:    "local_file.note_\(k)"
			filename: "notes/\(k).txt"
			content:  "\(k)\n"
		}
	}
}

Imported 4 resources and 0 outputs from terraform.tfstate into ./pravo.state

Renamed instances (these are the addresses now in the state; point each at its place in the specification with $from):
  local_file.note["alpha"] -> local_file.note_alpha
  local_file.note["beta"] -> local_file.note_beta

pravo will perform the following actions:

  # random_pet.server was moved to server (record renamed; no change to the object)

  # local_file.motd was moved to motd (record renamed; no change to the object)

  # local_file.note_alpha was moved to note.alpha (record renamed; no change to the object)

  # local_file.note_beta was moved to note.beta (record renamed; no change to the object)

Plan: 0 to add, 0 to change, 0 to destroy.
Graph: planned 4 of 4, 4 refreshed, 4 moved.

No changes. Your infrastructure matches the configuration.
Graph: planned 4 of 4, 4 refreshed.

The runbook is a sequence of gates. Each gate ends with a check that prints something you can read. Start the next page when the check passes.

The promise

Every step before the first pravo apply with changes leaves your infrastructure and your OpenTofu state as they are.

• pravo reads the state file you name, with pravo state import-tfstate. It never writes a .tfstate file or an OpenTofu backend.
• Before an apply, pravo calls only the read side of a provider: schema, validation, configuration, upgrade, read, import, plan, data sources, ephemeral resources and functions. It never calls the operation that creates, updates or deletes an object.
• pravo writes pravo.state (or the bucket that $settings names), pravo.lock.cue and cue.mod in each root. It writes the provider cache in ~/.pravo (PRAVO_HOME). It writes a plan file when you name one with --out.

A plan writes to pravo.state: it refreshes records, carries out $from moves and $import declarations there, and adds an entry to the transaction log when it wrote anything. Those writes change pravo's records and nothing else.

Two limits belong to the promise.

• A read is the provider's own code. A data source that runs a program runs it under pravo, as it does under OpenTofu. pravo cannot know what a provider does when it reads.
• The promise holds while the pravo state path is not the OpenTofu state file. Leave the path at its default, the directory pravo.state.

pravo.state holds the attributes of every resource, including the values a provider marks sensitive, in plain files. pravo creates the files with mode 0600 and the directories with mode 0700. Keep the directory out of version control and out of reach of people who cannot read the OpenTofu state.

M3 shows the promise as numbers: checksums of the state file and of the objects, taken before the first command and after the last.

The runbook

The root is frozen from M1 to M7: nothing applies to it with OpenTofu, and nothing merges into it. A change that lands in between sends you back to M5.

One rule governs M4 to M6: apply nothing that creates, changes, replaces or destroys. A plan that shows one means the specification does not yet describe the object. Fix the specification and plan again.

Until the first pravo apply that changes an object, going back means deleting the pravo files. After it, the OpenTofu state is out of date, and going back means making it agree with the objects. M8 rehearses the first case and lays out the second.

Applies to

Choose a path

pravo has no converter for HCL. You translate by hand, and the pages tell you how.

Start with Before you start. The concept map lists what each construct, command and function becomes. The worked example runs the whole path on one stack.