OpenTofu
OpenTofu is an open-source infrastructure-as-code tool. It creates public cloud virtual machines from configuration files.
The examples use tofu directly. Makefile, ./ssh, and ./check also default to IAC_CLI=tofu, with IAC_CLI=terraform available. Compatible .tf templates cover Alibaba Cloud, AWS global/China, Azure, GCP, Tencent Cloud, Hetzner, Vultr, DigitalOcean, and Linode. aliyun-s3.tf also creates a private OSS bucket and dedicated RAM read/write credentials for S3/pgBackRest.
Quick Start
Install OpenTofu
On macOS, install OpenTofu with Homebrew:
For Debian, Ubuntu, RHEL, or another platform, use the OpenTofu installation guide.
The package and command name is tofu.
Initialize and Apply
Enter the cloud template directory. Select a template, initialize the provider plugins, and examine the deployment plan:
After you review the plan, run tofu apply.
Enter yes to confirm.
OpenTofu then creates the virtual machines and related cloud resources.
Get IP Address
After creation, print the administration node’s public IP address:
Configure SSH Access
Global cloud templates usually supply an executable ssh_command output:
./ssh is a compatibility helper for legacy templates whose outputs are all IP addresses and whose root password is PigstyDemo4. It checks for IAC_CLI and jq, reads $IAC_CLI output -json, writes outputs as IPs to ~/.ssh/pigsty_config, then distributes keys with sshpass. Use it only with compatible templates such as aliyun.tf, aliyun-full.tf, aliyun-oss.tf, and aliyun-pro.tf, not modern templates exposing ssh_command, private IPs, or access keys.
./ssh defaults to tofu; use IAC_CLI=terraform ./ssh for Terraform. For compatible templates:
To use ~/.ssh/pigsty_config, include it from ~/.ssh/config:
Destroy Resources
After testing, use this command to remove the cloud resources:
Terraform Compatibility and Migration
Names remain terraform/, .tf, terraform.tfvars, .terraform.lock.hcl, and terraform.tfstate, which OpenTofu officially supports. Makefile, ./ssh, and ./check all accept IAC_CLI=terraform:
Use only one infrastructure command-line tool in a working directory at a time. Before you migrate existing state, preserve it and compare both plans:
Continue only if the OpenTofu plan contains the expected changes.
Do not delete terraform.tfstate when you initialize providers again.
Template Specs
The terraform/spec/ directory contains predefined cloud resource templates:
| Template File | Cloud Provider | Description |
|---|---|---|
aliyun.tf | Alibaba Cloud | Single-node meta template, supports all distributions and AMD/ARM (default) |
aliyun-s3.tf | Alibaba Cloud | Single node + private OSS bucket and RAM read/write credentials for S3/pgBackRest |
aliyun-full.tf | Alibaba Cloud | Four-node sandbox, supports all distributions and AMD/ARM |
aliyun-oss.tf | Alibaba Cloud | Six-node build template, supports all distributions and AMD/ARM |
aliyun-pro.tf | Alibaba Cloud | Seven-node multi-distribution test template |
aws.tf | AWS | Global AWS single node, Debian 12/13, AMD/ARM |
aws-cn.tf | AWS | Legacy single-node environment for AWS China |
azure.tf | Azure | Single node, Debian 12/13, AMD/ARM |
gcp.tf | GCP | Single node, Debian 12/13, AMD/ARM |
qcloud.tf | Tencent Cloud | Tencent Cloud single-node environment |
hetzner.tf | Hetzner | Single node, Debian 12/13, AMD/ARM |
vultr.tf | Vultr | Single node, Debian 12/13, AMD only, using a vultr_vpc private network |
digitalocean.tf | DigitalOcean | Single node, Debian 13 (d13) only, AMD only |
linode.tf | Linode | Single node, Debian 12/13, currently AMD only |
Copy the selected template to terraform.tf:
Variable Configuration
Template variables differ. Alibaba Cloud supports the full distribution matrix and defaults to u26. AWS global, Azure, GCP, Tencent Cloud, and Hetzner support Debian 12/13 with AMD/ARM, defaulting to d12/amd64. Vultr and Linode support Debian 12/13, default d12, with AMD instances only. DigitalOcean has retired Debian 12 images and supports only d13 (Debian 13) on AMD.
Architecture and Distribution
Resource Configuration
Alibaba Cloud templates define these resource parameters in a locals block.
Other cloud templates use provider-specific variables or local values for instances, disks, and networks.
Read the selected .tf file for its parameters.
Alibaba Cloud Configuration
Credential Setup
Set Alibaba Cloud credentials in environment variables.
For example, add them to ~/.bash_profile or ~/.zshrc:
Supported Images
The table lists common Alibaba Cloud ECS Public OS Image prefixes. The recommended and validated versions are:
Verified baselines are Rocky Linux 9.8 / 10.2, Debian 12.15 / 13.7, and Ubuntu 22.04.5 / 24.04.5 / 26.04.1. Alibaba Cloud public images now match, such as debian_13_7_x64_20G_alibase_20261019.vhd and its arm64 counterpart.
| Distribution | Code | x86_64 Image Prefix | aarch64 Image Prefix |
|---|---|---|---|
| CentOS 7.9 | el7 | centos_7_9_x64 | - |
| Rocky 8.10 | el8 | rockylinux_8_10_x64 | rockylinux_8_10_arm64 |
| Rocky 9.8 | el9 | rockylinux_9_8_x64 | rockylinux_9_8_arm64 |
| Rocky 10.2 | el10 | rockylinux_10_2_x64 | rockylinux_10_2_arm64 |
| Debian 11.11 | d11 | debian_11_11_x64 | - |
| Debian 12.15 | d12 | debian_12_15_x64 | debian_12_15_arm64 |
| Debian 13.7 | d13 | debian_13_7_x64 | debian_13_7_arm64 |
| Ubuntu 22.04.5 LTS | u22 | ubuntu_22_04_x64_20G | ubuntu_22_04_arm64_20G |
| Ubuntu 24.04.5 LTS | u24 | ubuntu_24_04_x64_20G | ubuntu_24_04_arm64_20G |
| Ubuntu 26.04.1 LTS | u26 | ubuntu_26_04_x64_20G | ubuntu_26_04_arm64_20G |
| Anolis 8.10 | an8 | anolisos_8_10_x64 | anolisos_8_10_arm64 |
| Alibaba Cloud Linux 3 | al3 | aliyun_3_x64_20G_alibase_[0-9]+ | aliyun_3_arm64_20G_alibase_[0-9]+ |
OSS Storage Configuration
The aliyun-s3.tf template creates an OSS bucket and permissions for PostgreSQL PITR backups:
- A private OSS bucket named
pigsty-oss. - A dedicated RAM user named
pigsty-oss-user. - An AccessKey saved to
~/pigsty.sk. - A RAM policy with
oss:*permissions on the bucket and its objects for read/write operations.
AWS Configuration
Credential Setup
The global and China-region templates can read standard AWS environment variables or credential files:
By default, aws.tf reads ~/.ssh/id_rsa.pub.
The legacy aws-cn.tf template reads this dedicated public key instead:
The aws.tf template looks up current official Debian AMIs.
The aws-cn.tf template uses a hard-coded China-region AMI and ~/.aws/pigsty-key.pub.
Verify the region, AMI, and key before deployment.
Tencent Cloud Configuration
Credential Setup
Set Tencent Cloud credentials in environment variables:
The community supplies the Tencent Cloud templates as examples. You may need to adjust them for your requirements.
Other Cloud Credentials
The GCP template also requires project, for example tofu apply -var="project=my-project".
Except for AWS China, the current templates with key authentication read ~/.ssh/id_rsa.pub by default.
To use another public key, edit the path in the selected template.
Shortcut Commands
Pigsty’s Makefile shortcuts and template validator default to OpenTofu (IAC_CLI ?= tofu). Set IAC_CLI=terraform explicitly for Terraform.
For modern templates with ssh_command, private IPs, or other non-IP outputs, such as vultr.tf using vultr_vpc, run tofu apply or make apply directly. Do not use make up / make u, which subsequently call legacy ./ssh. Only explicitly named up-auto, apply-auto, and destroy-auto skip interactive confirmation.
Notes
Cloud resources created by OpenTofu incur charges.
After testing, run tofu destroy promptly to avoid unnecessary charges.
Pay-as-you-go instances are recommended for tests.
The templates use Spot Instances by default to reduce costs.
Alibaba Cloud and Tencent Cloud templates set the root password to PigstyDemo4.
Linode uses PigstyDemo4! to meet its password complexity rules.
Current AWS, Azure, GCP, Hetzner, Vultr, and DigitalOcean templates primarily use SSH keys and share no default root password.
Use example passwords only for temporary tests.
For production, replace them or disable password login.
These templates target demonstrations and development.
Their security groups or cloud firewalls permit all or nearly all inbound traffic from 0.0.0.0/0.
Some also permit ::/0.
Before deployment, restrict the permitted source networks and ports.
Do not use the default access rules unchanged in production.
After creation, use this command to log in to the administration node:
Alibaba Cloud templates with the legacy outputs and passwords can use ./ssh or make ssh to write SSH aliases.
For other templates, use their ssh_command output.
Was this page helpful?
Thanks—your feedback helps us improve this page.
What got in the way? (optional)