Concept map

Each group below shows one OpenTofu construct beside the CUE that replaces it, runs the CUE, and lists the rest of the group in a table. The left column of a table is what you write today. A row that says No equivalent names its replacement in the note, or links to the page that does. The annexes hold the complete lists: constructs, commands and functions.

In the CUE column, $p stands for a provider struct such as $aws, and pkg for its generated package. M3 shows the forms in a working stack.

Work in an empty directory. The examples share one package: each group writes a file of its own, and a later file may use what an earlier one declares. A file that uses a package imports it, because an import belongs to the file that writes it.

Providers

A provider is a struct built from a generated definition. The version constraint and the settings of the provider sit in the same struct. A second configuration of one provider is a second struct.

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

provider "local" {
  alias = "backup"
}

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"}
$backup: loc.#Provider

pravo init installs the providers and writes the CUE packages that the imports name. pravo validate checks the specification against their schemas and starts no provider.

Configuration does not load yet; generating schemas for the declared providers first.
Created cue.mod/module.cue
Providers:
  local = hashicorp/local v<version>
  random = hashicorp/random v<version>
...
pravo has been initialised. Run "pravo plan" to see what it would do.
Success! 0 resources, 0 data sources, 0 ephemeral, 0 function calls, 0 outputs across 2 providers.

M4, step 1 covers the version constraint and the lock file.

Resources and data sources

A resource is a struct built through a provider. Its address is its path in the specification, so random_pet.name becomes name.

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

resource "local_file" "greeting" {
  filename = "greeting.txt"
  content  = "hello ${random_pet.name.id}\n"
}

package estate

name: $random.#Resource.random_pet & {length: 2}

greeting: $local.#Resource.local_file & {
	filename: "greeting.txt"
	content:  "hello \(name.id)\n"
}

The reference name.id is the dependency: greeting waits for name, and there is no depends_on.

Success! 2 resources, 0 data sources, 0 ephemeral, 0 function calls, 0 outputs across 2 providers.

Inputs

A variable is a field. The type, the default and the validation are one constraint, and -t sets the value.

variable "env" {
  type    = string
  default = "dev"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.env)
    error_message = "env must be dev, staging or prod."
  }
}

package estate

env: *"dev" | "staging" | "prod" @tag(env)

The * marks the default. The three strings are the allowed values, and a fourth is an error.

"dev"
"prod"

Error: evaluating .:
env: 3 errors in empty disjunction:
env: conflicting values "dev" and "qa":
    ./inputs.cue:3:7
env: conflicting values "prod" and "qa":
    ./inputs.cue:3:27
env: conflicting values "staging" and "qa":
    ./inputs.cue:3:15

M4, step 2 translates variables with lists, maps and defaults, and Environment and remote outputs describes #Env and #SecretEnv.

Names and results

A local is a hidden field: a name that starts with an underscore is not an output. An output is a struct built from pravo.#Output.

locals {
  prefix = "app-${var.env}"
}

output "bucket_name" {
  value = "${local.prefix}-logs"
}

package estate

import "pravo.dev/pravo"

_prefix: "app-\(env)"

bucket_name: pravo.#Output & {value: "\(_prefix)-logs"}

"app-dev-logs"
"app-prod-logs"

Repetition

A comprehension builds the instances. The key of a for_each is the last part of the address, and the index of a count is its index.

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

resource "random_integer" "slot" {
  count = 2
  min   = 8000
  max   = 8999
}

package estate

import "list"

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

slot: [
	for i in list.Range(0, 2, 1) {
		$random.#Resource.random_integer & {min: 8000, max: 8999}
	},
]

Success! 6 resources, 0 data sources, 0 ephemeral, 0 function calls, 1 outputs across 2 providers.
  # note.alpha (local_file) will be created
  # note.beta (local_file) will be created
  # slot[0] (random_integer) will be created
  # slot[1] (random_integer) will be created

Keep the shape of the instances. A struct stays a struct and a list stays a list, because a change of shape is a change of address.

M4, steps 5 and 6 translate count, for_each and dynamic in full.

Reuse

A module is a definition that holds resources. An instance of it is one more field, and its resources take the address instance.resource. A caller may set any field of an instance, and the definition still checks the result.

variable "name" {
  type = string
}

variable "port" {
  type = number

  validation {
    condition     = var.port >= 1024
    error_message = "port must be 1024 or more."
  }
}

resource "local_file" "file" {
  filename = "${var.name}.env"
  content  = "PORT=${var.port}\n"
}

module "api" {
  source = "./modules/service"
  name   = "api"
  port   = 8080
}

module "web" {
  source = "./modules/service"
  name   = "web"
  port   = 8081
}

package estate

#Service: {
	name: string
	port: int & >=1024
	file: $local.#Resource.local_file & {
		filename: "\(name).env"
		content:  "PORT=\(port)\n"
	}
}

api: #Service & {name: "api", port: 8080}

web: #Service & {
	name: "web"
	port: 8081
	file: file_permission: "0600"
}

The second instance sets file_permission on the resource inside the definition. The definition declares no input for it, and the type of the attribute still applies.

Success! 8 resources, 0 data sources, 0 ephemeral, 0 function calls, 1 outputs across 2 providers.
  # api.file (local_file) will be created
  # web.file (local_file) will be created

B6 teaches modules with providers, and M4, step 7 translates a module call.

Order and lifecycle

A reference is a dependency already. $depends_on names a dependency that no reference shows, and $lifecycle holds the lifecycle settings.

resource "local_file" "first" {
  filename = "first.txt"
  content  = "1\n"
}

resource "local_file" "second" {
  filename   = "second.txt"
  content    = "2\n"
  depends_on = [local_file.first]

  lifecycle {
    prevent_destroy = true
  }
}

package estate

first: $local.#Resource.local_file & {
	filename: "first.txt"
	content:  "1\n"
}

second: $local.#Resource.local_file & {
	filename: "second.txt"
	content:  "2\n"
	$depends_on: [first]
	$lifecycle: prevent_destroy: true
}

Success! 10 resources, 0 data sources, 0 ephemeral, 0 function calls, 1 outputs across 2 providers.

Addresses and adoption

The address of a resource is its identity. $from names the old address on the resource that now holds it, and $import names the object that an address adopts.

moved {
  from = local_file.old
  to   = local_file.renamed
}

resource "local_file" "renamed" {
  filename = "renamed.txt"
  content  = "x\n"
}

package estate

renamed: $local.#Resource.local_file & {
	$from:    "old"
	filename: "renamed.txt"
	content:  "x\n"
}

Success! 11 resources, 0 data sources, 0 ephemeral, 0 function calls, 1 outputs across 2 providers.

M5 uses $from to point each converted record at its address.

State and backends

The state is a directory of records, or a bucket. The settings sit in $settings, and they may depend on a tag, which is how an environment gets its own state without a workspace.

terraform {
  backend "s3" {
    bucket = "acme-state"
    key    = "prod/terraform.tfstate"
    region = "eu-west-1"
  }
}

package state

import "pravo.dev/pravo"

$settings: pravo.#Settings & {
	state: {
		backend: "s3"
		bucket:  "acme-state"
		prefix:  "prod"
		region:  "eu-west-1"
	}
}

The block sits in its own directory, because it is a root of its own. validate reads the settings and opens no bucket.

Success! 0 resources, 0 data sources, 0 ephemeral, 0 function calls, 0 outputs across 0 providers.

Commands

A pravo command takes the place of the tofu command in a pipeline. The loop that every root runs is the same three steps, and -t replaces -var.

tofu init
tofu plan -var env=prod -out=change.plan
tofu apply change.plan

pravo init
pravo plan -t env=prod --out change.plan
pravo apply change.plan

The commands on the right run in the directory of this page. apply of a saved plan asks nothing.

Plan: 11 to add, 0 to change, 0 to destroy.
Apply complete! Resources: 11 added, 0 changed, 0 destroyed. [txn <txn>]
api.file
first
greeting

Set up and check

Plan and apply

State and outputs

Without a counterpart

The command map lists the flags, the environment variables and the files as well.

Functions

Import the package that holds the function: strings, list, math, regexp, strconv, net or an encoding package. Interpolation replaces format, and a comprehension replaces most of what a function builds.

Strings

Lists and maps

Fallbacks and conversion

Numbers and networks

Check a mapping

A top-level field cannot have the name of a package that the same file imports. A field called json next to import "encoding/json" fails evaluation. The check below uses three rows of the tables: a tag in place of a variable, upper and lookup. It replaces inputs.cue with a file that holds them.

package estate

import (
	"list"
	"strings"
)

env: *"dev" | "staging" | "prod" @tag(env)

_sizes: {dev: 1, prod: 3}
_names: ["web", "api", "db"]

shout:  strings.ToUpper(env)
joined: strings.Join(list.SortStrings(_names), ",")
size:   *_sizes[env] | 2

["dev", "DEV", "api,db,web", 1]
["staging", "STAGING", "api,db,web", 2]

staging has no entry in _sizes, so size takes its default, 2.

Recap

• Every construct maps to a field, a definition, a comprehension or a $ field; the rows with no equivalent name their replacement.
• Commands keep their names, and flags move from -var to -t; -target, workspaces and taint have no counterpart.
• Functions come from CUE packages; merge is &, and a conflict is an error.

Next: the worked example runs the forms on a real stack.