Skip to content

Configuration

This page shows where OpenTofu's settings live on the image, how to work with your own code and providers, and how to move state to S3.

Where configuration lives

Path What it holds
/var/lib/opentofu/workspace/ Your workspace: .tf files, lock file and local state
/opt/sushi/etc/opentofu/cli.tfrc Default CLI configuration: where providers are installed from
/opt/opentofu/providers/ Local provider mirror with hashicorp/aws 6.67.0
/opt/sushi/etc/opentofu/ Original copies of the example files
/etc/opentofu/backend.env Commented credentials template, root-only. Not read by tofu.

How the tofu command works

/usr/local/bin/tofu runs the pinned binary with two defaults:

  • TF_CLI_CONFIG_FILE=/opt/sushi/etc/opentofu/cli.tfrc
  • CHECKPOINT_DISABLE=1

If you set either variable yourself, your value wins.

Providers

The default CLI configuration installs hashicorp/aws only from the local mirror, and blocks direct downloads from registry.opentofu.org. The example versions.tf pins OpenTofu = 1.13.1 and the AWS provider = 6.67.0.

To use other providers or versions, write your own CLI configuration file and point TF_CLI_CONFIG_FILE at it:

export TF_CLI_CONFIG_FILE=$HOME/.tofurc
tofu -chdir=/var/lib/opentofu/workspace init

See CLI configuration in the OpenTofu documentation.

Use your own code

Put your .tf files in /var/lib/opentofu/workspace, or in another folder you own, and run tofu -chdir=<folder> init, validate and plan.

Run tofu apply yourself, and only for plans you have reviewed. Nothing on the image runs apply for you.

AWS credentials

To manage AWS resources, attach an instance role to the EC2 instance. The AWS provider uses it automatically. Grant only the actions your configuration needs, in accounts you own.

Keep keys out of code and user data

Do not put access keys in .tf files, user data or the AMI. Prefer the instance role. If you must use static keys, keep them in a file you own with mode 0600. /etc/opentofu/backend.env is only a template and is not loaded by tofu.

Use an S3 backend

The example uses a local backend, so state is the file /var/lib/opentofu/workspace/terraform.tfstate. To keep state in S3 instead:

  1. Use an existing S3 bucket you control, with versioning turned on.
  2. Attach an instance role with the permissions in iam-s3-backend.json.example, with CUSTOMER_STATE_BUCKET replaced by your bucket. It grants s3:ListBucket and s3:GetBucketVersioning on the bucket, and s3:GetObject, s3:PutObject and s3:DeleteObject on the state object and its .tflock lock object.
  3. Back up your current state file.

  4. Copy the backend example and set your bucket, key and Region:

    cd /var/lib/opentofu/workspace
cp s3-backend.example.hcl s3-backend.hcl

    bucket       = "<your-state-bucket>"
key          = "opentofu/pilot/terraform.tfstate"
region       = "us-east-1"
encrypt      = true
use_lockfile = true

    Keep use_lockfile = true. It turns on native S3 state locking.

  5. In versions.tf, replace the backend "local" { ... } block with:

    backend "s3" {}

  6. Review the change, then migrate the state:

    tofu -chdir=/var/lib/opentofu/workspace init -migrate-state -backend-config=s3-backend.hcl

The examples cover the default workspace only. If you change the key or use other workspaces, update the IAM policy for the matching state and lock objects. See the OpenTofu S3 backend documentation.