DEV Community: todoroff

Terraform for Local VMs: A Modern Alternative to Vagrant

todoroff — Wed, 07 Jan 2026 10:45:03 +0000

Updated October 2026 for provider 2.0.1.

After 8 years of using Vagrant, I finally made the switch. Not because Vagrant stopped working - it still does what it's always done. But because I found something that fits better into my modern infrastructure-as-code workflow.

Here's the story of how I replaced Vagrant with Multipass + Terraform and never looked back.

The Problem: Vagrant is Showing Its Age

Don't get me wrong - Vagrant revolutionized local development. The idea of "infrastructure as code" for your laptop was groundbreaking in 2010.

But in 2026, I kept hitting the same pain points:

🔧 Provider-specific setup
Vagrant supports several providers, including Hyper-V. Each backend still comes with its own setup and configuration.

📦 Heavy box downloads
The first use of a new box meant a large image download.

🤔 Different workflow
Vagrantfile syntax is Ruby DSL. My production infrastructure is Terraform. Why maintain two mental models?

Sound familiar?

The Discovery: Multipass + Terraform

Then I discovered Canonical Multipass - a lightweight VM manager from Canonical.

Combined with a Terraform provider, I could:

✅ Use the same IaC approach locally and in production
✅ Native cloud-init support (just like AWS/GCP/Azure)
✅ Simpler setup - no VirtualBox Guest Additions hassles
✅ One workflow to rule them all

Let me show you how to make the switch.

Part 1: Understanding the Difference

Vagrant's Approach

# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.vm.network "private_network", ip: "192.168.56.10"

  config.vm.provider "virtualbox" do |vb|
    vb.memory = "2048"
    vb.cpus = 2
  end

  config.vm.provision "shell", inline: <<-SHELL
    apt-get update
    apt-get install -y nginx
  SHELL
end

Ruby DSL
Provider-specific configurations
Shell provisioners (or Ansible/Chef/Puppet)
Box-based images

Multipass + Terraform Approach

# main.tf
terraform {
  required_providers {
    multipass = {
      source  = "todoroff/multipass"
      version = "~> 2.0.1"
    }
  }
}

resource "multipass_instance" "web" {
  name   = "web-server"
  cpus   = 2
  memory = "2G"
  disk   = "10G"
  image  = "jammy"

  wait_for_cloud_init = true

  cloud_init = <<-EOT
    #cloud-config
    package_update: true
    packages:
      - nginx
  EOT
}

Standard HCL (same as production Terraform)
Cloud-init provisioning (same as cloud VMs)
Image aliases (Multipass downloads and caches the selected image)

Both install Nginx. The Multipass example uses its default network; matching Vagrant's static private IP needs additional network configuration.

Part 2: Setting Up Multipass + Terraform

Step 1: Install Multipass

You'll need Terraform 1.6+ and Multipass 1.13+ on the same host. The provider calls the local Multipass CLI.

# macOS
brew install multipass

# Ubuntu/Debian (with snapd installed)
sudo snap install multipass

# Windows
# Download from https://multipass.run/install
winget install Canonical.Multipass

Verify it works:

multipass version
# Check that Multipass is 1.13 or newer

Step 2: Create Your First Terraform Config

Create a new directory and main.tf:

terraform {
  required_providers {
    multipass = {
      source  = "todoroff/multipass"
      version = "~> 2.0.1"
    }
  }
}

provider "multipass" {
  # Optional: explicit path to multipass binary
  # multipass_path = "/usr/local/bin/multipass"

  # Optional: timeout for commands (default 600s)
  command_timeout = 600
}

resource "multipass_instance" "dev" {
  name   = "my-dev-vm"
  cpus   = 2
  memory = "4G"
  disk   = "20G"
  image  = "jammy"  # Ubuntu 22.04 LTS
}

output "ip_address" {
  value = multipass_instance.dev.ipv4[0]
}

Step 3: Deploy

terraform init
terraform apply

That's it. Your VM is running. ⚡

# Check it
multipass list
# Name       State    IPv4            Image
# my-dev-vm  Running  192.168.64.5    Ubuntu 22.04 LTS

# SSH into it
multipass shell my-dev-vm

Part 3: Migrating Your Vagrantfile

Let's convert a real-world Vagrant setup to Multipass + Terraform. This example provisions PostgreSQL and Nginx, and passes the database address to the web VM. A real application still needs its database connection and authentication configured.

Before: Vagrant Multi-Machine Setup

# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"

  config.vm.define "db" do |db|
    db.vm.hostname = "db-server"
    db.vm.network "private_network", ip: "192.168.56.10"
    db.vm.provider "virtualbox" do |vb|
      vb.memory = "2048"
    end
    db.vm.provision "shell", inline: <<-SHELL
      apt-get update
      apt-get install -y postgresql postgresql-contrib
      sudo -u postgres createuser --superuser vagrant
      sudo -u postgres createdb myapp
    SHELL
  end

  config.vm.define "web" do |web|
    web.vm.hostname = "web-server"
    web.vm.network "private_network", ip: "192.168.56.11"
    web.vm.provider "virtualbox" do |vb|
      vb.memory = "1024"
    end
    web.vm.provision "shell", inline: <<-SHELL
      apt-get update
      apt-get install -y nginx
      echo "<h1>Web server</h1><p>Database: 192.168.56.10</p>" > /var/www/html/index.html
    SHELL
  end
end

After: Multipass + Terraform

Use a new directory for this example, with main.tf and web-init.yaml together.

# main.tf
terraform {
  required_providers {
    multipass = {
      source  = "todoroff/multipass"
      version = "~> 2.0.1"
    }
  }
}

provider "multipass" {}

# Database Server
resource "multipass_instance" "db" {
  name   = "db-server"
  cpus   = 2
  memory = "2G"
  disk   = "10G"
  image  = "jammy"

  wait_for_cloud_init = true

  cloud_init = <<-EOT
    #cloud-config
    package_update: true
    packages:
      - postgresql
      - postgresql-contrib
    runcmd:
      - sudo -u postgres createuser --superuser ubuntu
      - sudo -u postgres createdb myapp
  EOT

  timeouts {
    create = "20m"
  }
}

# Web Server (depends on DB for its IP)
resource "multipass_instance" "web" {
  name   = "web-server"
  cpus   = 1
  memory = "1G"
  disk   = "5G"
  image  = "jammy"

  cloud_init = templatefile("${path.module}/web-init.yaml", {
    db_host = multipass_instance.db.ipv4[0]
  })

  wait_for_cloud_init = true

  timeouts {
    create = "20m"
  }
}

# Outputs
output "db_ip" {
  value = multipass_instance.db.ipv4[0]
}

output "web_ip" {
  value = multipass_instance.web.ipv4[0]
}

#cloud-config
package_update: true
packages:
  - nginx
write_files:
  - path: /var/www/html/index.html
    permissions: '0644'
    defer: true
    content: |
      <h1>Web server</h1>
      <p>Database: ${db_host}</p>
runcmd:
  - systemctl restart nginx

Save the YAML as web-init.yaml. The DB reference creates Terraform's dependency automatically. wait_for_cloud_init = true also waits for guest provisioning to finish; depends_on alone would not do that. The page displays the DB address to demonstrate templating.

Part 4: Advanced Features You'll Love

Resize an Existing VM

Provider 2.x defaults to resize_policy = "in_place": CPU and memory changes, and disk growth, resize the existing VM. Running VMs stop and restart; already stopped VMs stay stopped. Disk shrink is rejected before mutation, and guest filesystem expansion may require a separate step.

Use resize_policy = "replace" to keep the previous behavior of rebuilding on size changes. Name, image, cloud-init, and network changes still force recreation. Changing the policy alone leaves the VM as it is.

When upgrading from 1.x, change the version constraint and run terraform init -upgrade, then review the plan. ~> 1.5 excludes 2.x. See the 2.0 upgrade notes.

Snapshots (Save Your Progress!)

Multipass has native snapshots, which the provider can manage. Vagrant also supports snapshots with compatible backends.

resource "multipass_instance" "test_env" {
  name  = "test-env"
  image = "jammy"
  # ... config
}

Apply the instance configuration first. Then stop the VM before adding the snapshot resource:

multipass stop test-env

# Take a snapshot before risky operations
resource "multipass_snapshot" "before_upgrade" {
  instance = multipass_instance.test_env.name
  name     = "pre-upgrade-backup"
}

Apply again to create the snapshot, then run multipass start test-env. A snapshot requires a stopped instance; the resource does not stop it automatically.

Now you can:

Run your tests
Break things
Restore to snapshot
Repeat

Terraform tracks the snapshot. To restore it, use the CLI:

multipass stop test-env
multipass restore test-env.pre-upgrade-backup
multipass start test-env

Follow the restore prompt, then review terraform plan because restoration can change the VM relative to your configuration.

File Transfers (No More Provisioners!)

For config files and log downloads, the provider has dedicated transfer resources. Create configs/app.yaml locally before applying this example:

# Upload config files
resource "multipass_file_upload" "app_config" {
  instance    = multipass_instance.web.name
  source      = "${path.module}/configs/app.yaml"
  destination = "/home/ubuntu/app.yaml"
}

# Download logs for analysis
resource "multipass_file_download" "app_logs" {
  instance    = multipass_instance.web.name
  source      = "/var/log/nginx/access.log"
  destination = "${path.module}/logs/app.log"

  triggers = {
    refresh = "1" # Change this value to download a fresh copy.
  }
}

Uploads need a writable destination; the transfer does not elevate permissions for paths under /etc. Downloads need readable source files. Transfers are discrete copies, and remote edits do not automatically trigger another transfer. Destroying these resources removes their respective remote or local destination.

For a shared source directory, use a mounts block inside your instance resource:

  mounts {
    host_path     = abspath("${path.module}/src")
    instance_path = "/workspace"
  }

Create src on the host before applying. This is the closer equivalent to config.vm.synced_folder; mounts can be added or removed without recreating the VM.

Aliases (Quick Access)

Create host-level shortcuts to jump into your VMs:

resource "multipass_alias" "db_shell" {
  name     = "db-psql"
  instance = multipass_instance.db.name
  command  = "sudo -u postgres psql myapp"
}

resource "multipass_alias" "web_logs" {
  name     = "web-logs"
  instance = multipass_instance.web.name
  command  = "tail -f /var/log/nginx/access.log"
}

Now from your host terminal:

multipass db-psql      # Opens psql on db server
multipass web-logs     # Tails nginx logs

For the shorter db-psql and web-logs commands, add the Multipass alias directory to your host's PATH as described in the alias guide.

No more vagrant ssh web -c "..." gymnastics.

Part 5: Real-World Use Cases

Local Kubernetes Clusters

Want to spin up a full multi-node K3s cluster for testing? I wrote a complete step-by-step tutorial:

📚 Build a Local Kubernetes Cluster in Minutes with Terraform and Multipass

The tutorial walks through:

1 master + 2 worker nodes
Automatic cluster joining via cloud-init
kubectl access from your host machine
Complete working code you can deploy today

Other Common Use Cases

This stack is also perfect for:

🔧 Infrastructure Testing

Test Ansible playbooks across multiple nodes
Validate HAProxy or Nginx load balancer configs
Simulate distributed systems locally

🎓 Learning Labs

Practice Terraform without cloud costs
Learn Linux system administration
Experiment with databases and replication

💻 Development Environments

Reproducible team dev environments
Test upgrades in isolation
Quick throwaway VMs for experimentation

Part 6: Migration Cheat Sheet

Vagrant	Multipass + Terraform
`vagrant up`	`terraform apply` to create; `multipass start <name>` to start an existing stopped VM
`vagrant destroy`	`terraform destroy`
`vagrant ssh`	`multipass shell <name>`
`vagrant halt`	(use `multipass stop <name>`)
`vagrant reload`	`multipass restart <name>` to reboot; `terraform apply` for configuration changes
`config.vm.box`	`image = "jammy"`
`vb.memory`	`memory = "2G"`
`vb.cpus`	`cpus = 2`
`config.vm.provision "shell"`	`cloud_init = <<-EOT ... EOT` at creation; changing it recreates the VM
`config.vm.synced_folder`	`mounts { }` block
`config.vm.network`	`networks { }` for host interfaces; configure static IPs inside the guest

Part 7: When to Stick with Vagrant

To be fair, Vagrant still has its place:

✅ Use Vagrant if:

You need non-Ubuntu operating systems (Windows, CentOS, etc.)
You rely on a particular Vagrant provider or plugin
Your team has heavy investment in existing Vagrantfiles
You need VirtualBox-specific features

✅ Use Multipass + Terraform if:

You're working primarily with Ubuntu
You want a simpler, lighter setup
You want one workflow for local and cloud
You're already using Terraform
You want modern cloud-init provisioning
Resource efficiency is important

Getting Started Today

Ready to make the switch? Here's a quickstart. The first image download and package installation can take a few minutes.

1. Install Dependencies

# Install Multipass
brew install multipass  # or snap install multipass

# Verify
multipass version

2. Create Your First Config

The following file-creation commands use Bash. In PowerShell, save the HCL between EOF markers as main.tf using your editor.

mkdir my-dev-env && cd my-dev-env

cat > main.tf << 'EOF'
terraform {
  required_providers {
    multipass = {
      source  = "todoroff/multipass"
      version = "~> 2.0.1"
    }
  }
}

resource "multipass_instance" "dev" {
  name   = "dev-box"
  cpus   = 2
  memory = "4G"
  disk   = "20G"
  image  = "jammy"

  wait_for_cloud_init = true

  cloud_init = <<-EOT
    #cloud-config
    package_update: true
    packages:
      - git
      - curl
      - build-essential
    runcmd:
      - echo "Dev environment ready!" > /home/ubuntu/welcome.txt
  EOT

  timeouts {
    create = "20m"
  }
}

output "ip" {
  value = multipass_instance.dev.ipv4[0]
}
EOF

3. Deploy

terraform init
terraform apply -auto-approve

4. Access Your VM

multipass shell dev-box
cat ~/welcome.txt
# Dev environment ready!

That's it. You're running a modern, fast, Terraform-managed local development environment.

Resources

Terraform Provider: registry.terraform.io/providers/todoroff/multipass
GitHub Repository: github.com/todoroff/terraform-provider-multipass
Multipass Official: multipass.run
Example Configurations: GitHub Examples

Conclusion

Switching from Vagrant to Multipass + Terraform was one of the best decisions I made for my local development workflow.

What I gained:

🔧 Simpler setup (no Guest Additions, NFS issues, etc.)
🔄 One IaC workflow for everything
📸 Native snapshot support
🎯 Cloud-native provisioning with cloud-init

What I lost:

Multi-OS support (Ubuntu-only)
...that's about it

If you want a modern, Terraform-native approach to local VMs, give this a try.

Have questions about migrating your Vagrant setup? Drop them in the comments! I'm happy to help with specific migration scenarios.

Found this useful? Consider ⭐ starring the provider on GitHub - it helps others discover it!

What's your local development setup? Still on Vagrant, Docker Compose, or something else entirely? Let me know in the comments! 👇

Build a Local Kubernetes Cluster in Minutes with Terraform and Multipass

todoroff — Sun, 23 Nov 2025 00:05:51 +0000

Are you looking for a way to spin up a lightweight, throwaway Kubernetes cluster on your local machine without the overhead of Docker Desktop or Minikube? Or maybe you want to simulate a multi-node environment to test node affinity and failover?

In this article, we'll show you how to build a multi-node K3s cluster completely from code using the Multipass Terraform Provider.

Why This Stack?

Multipass: Canonical's lightweight VM manager for Linux, Windows, and macOS. It spins up Ubuntu instances in seconds.
Terraform: The industry standard for Infrastructure as Code (IaC). It manages the lifecycle, dependencies, and configuration of your VMs.
K3s: A highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances.

By combining these, you get a reproducible, codified local lab environment that you can spin up and tear down with a single command.

The Project: A 3-Node K3s Cluster

We are going to build:

1 Master Node: Runs the K3s control plane.
2 Worker Nodes: Join the cluster automatically.
Automatic Wiring: Terraform will handle passing the master's IP and a shared secret to the workers.

Prerequisites

Install Multipass
Install Terraform
Initialize a new directory for your project:
```
mkdir k3s-lab && cd k3s-lab
```

The Terraform Configuration

Create a file named main.tf and paste the following code. We're using the todoroff/multipass provider to manage our VMs.

terraform {
  required_providers {
    multipass = {
      source  = "todoroff/multipass"
    }
  }
}

provider "multipass" {
  # Increase timeout for image downloads and initialization
  command_timeout = 600 
}

# 1. Define a shared secret for the cluster
locals {
  k3s_token = "my-super-secret-shared-token-12345"

  # Cloud-init script for the master node
  # Installs K3s server, creates a wrapper script for kubectl, and sets the token
  master_cloud_init = <<-EOT
    #cloud-config
    package_update: true
    package_upgrade: true
    write_files:
      - path: /usr/local/bin/k3s-kubectl-wrapper
        permissions: '0755'
        content: |
          #!/bin/sh
          sudo k3s kubectl "$@"
    runcmd:
      - curl -sfL https://get.k3s.io | K3S_TOKEN=${local.k3s_token} sh -s - server --cluster-init
  EOT
}

# 2. Create the Master Node
resource "multipass_instance" "k3s_master" {
  name   = "k3s-master"
  cpus   = 2
  memory = "2G"
  disk   = "10G"
  image  = "jammy" # Ubuntu 22.04 LTS

  cloud_init = local.master_cloud_init
}

# 3. Create Worker Nodes
# These depend on the master because they need its IP address
resource "multipass_instance" "k3s_worker" {
  count  = 2
  name   = "k3s-worker-${count.index + 1}"
  cpus   = 1
  memory = "1G"
  disk   = "5G"
  image  = "jammy"

  # Cloud-init script for workers
  # Uses the master's IP (from Terraform state) to join the cluster
  cloud_init = <<-EOT
    #cloud-config
    package_update: true
    runcmd:
      - curl -sfL https://get.k3s.io | K3S_URL=https://${multipass_instance.k3s_master.ipv4[0]}:6443 K3S_TOKEN=${local.k3s_token} sh -
  EOT

  depends_on = [multipass_instance.k3s_master]
}

# 4. Create a convenient alias to run kubectl from your host
# We use a wrapper script to handle argument passing correctly via alias
resource "multipass_alias" "kubectl" {
  name     = "k3s-kubectl"
  instance = multipass_instance.k3s_master.name
  command  = "/usr/local/bin/k3s-kubectl-wrapper"
}

# 5. Output the node IPs
output "cluster_nodes" {
  value = {
    master  = multipass_instance.k3s_master.ipv4
    workers = multipass_instance.k3s_worker[*].ipv4
  }
}

How It Works

cloud_init Magic: We use Terraform's local variables to construct a cloud-init script. This script runs on first boot.
- On the master, it downloads and installs K3s in server mode. It also creates a helper script /usr/local/bin/k3s-kubectl-wrapper to make running kubectl commands easier via alias.
- On the workers, it installs K3s and immediately joins the cluster using the K3S_URL environment variable.
Dynamic Configuration: Notice ${multipass_instance.k3s_master.ipv4[0]} in the worker's cloud-init. Terraform waits for the master to be created, grabs its first IPv4 address, injects it into the worker's configuration, and then creates the workers. No manual copy-pasting required!
Aliases: The multipass_alias resource creates a k3s-kubectl command on your host machine that invokes the wrapper script on the master node.

Deploying the Lab

Initialize Terraform:
```
terraform init
```
Apply the Configuration:
```
terraform apply
```
Type yes when prompted.

Terraform will spin up the VMs. It might take a minute or two for the VMs to boot and for K3s to install.

Using Your Cluster

Once Terraform finishes, wait about 60 seconds for the cloud-init scripts to complete installation inside the VMs.

Check the Nodes:
You can run kubectl commands directly from your terminal using the alias we created:

multipass k3s-kubectl get nodes

You should see something like:

NAME           STATUS   ROLES                       AGE   VERSION
k3s-master     Ready    control-plane,etcd,master   2m    v1.28.2+k3s1
k3s-worker-1   Ready    <none>                      1m    v1.28.2+k3s1
k3s-worker-2   Ready    <none>                      1m    v1.28.2+k3s1

Deploy a Test Workload:
Deploy a simple Nginx server to verify everything is working:

multipass k3s-kubectl create deployment nginx --image=nginx
multipass k3s-kubectl expose deployment nginx --port=80 --type=NodePort

Cleanup

When you're done with your lab, you don't need to manually delete VMs or clean up files. Just run:

terraform destroy

This will stop and delete all the Multipass instances and remove the aliases, leaving your machine clean.

Conclusion

The Multipass Terraform Provider turns your local machine into a flexible cloud environment. Whether you're testing Kubernetes, setting up a complex microservices mesh, or just need a clean Linux sandbox, you can define it all in code.

Check out the provider documentation for more resources like multipass_mount and multipass_snapshot to take your local labs to the next level!

Or some of the examples in the provider repository: https://github.com/todoroff/terraform-provider-multipass

Multipass + Terraform: Modern VM Automation Guide

todoroff — Tue, 18 Nov 2025 10:09:46 +0000

Multipass + Terraform: Modern VM Automation Guide

Updated for todoroff/multipass 2.0.1, October 2026.

Multipass creates Ubuntu virtual machines on your workstation. The todoroff/multipass Terraform provider lets you describe those machines in code, along with their networks, host mounts, aliases, snapshots, and file transfers.

This guide starts with one VM and then covers resizing, cloud-init, multiple network interfaces, static addresses, and configuration workflows with Ansible or a CI system.

The provider runs the multipass CLI on the machine running Terraform. That machine needs Multipass installed and access to its daemon; a hosted Terraform runner does not automatically have access to the VMs on your laptop.

1. Install the prerequisites

You need:

Terraform 1.6 or newer.
Multipass 1.13 or newer, installed and available on PATH.
A working Multipass driver for your operating system. Networking, snapshots, and resizing also depend on the capabilities of that driver.

Check that the CLI can reach the daemon:

multipass version --format json
multipass list --format json

Go is only needed when building the provider from source.

2. Create a VM and a shell alias

Create an empty directory and save the following as main.tf:

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    multipass = {
      source  = "todoroff/multipass"
      version = "~> 2.0"
    }
  }
}

provider "multipass" {}

resource "multipass_instance" "dev" {
  name   = "dev-box"
  image  = "24.04"
  cpus   = 2
  memory = "4G"
  disk   = "15G"
}

resource "multipass_alias" "shell" {
  name     = "dev-shell"
  instance = multipass_instance.dev.name
  command  = "bash"
}

output "dev_ips" {
  value = multipass_instance.dev.ipv4
}

Then initialize, review, and apply the configuration:

terraform init
terraform plan
terraform apply
multipass dev-shell

The alias opens Bash inside the VM. The ipv4 attribute contains the addresses reported by Multipass.

~> 2.0 permits provider versions from 2.0.0 up to, but excluding, 3.0.0. Commit .terraform.lock.hcl to retain the selected version across runs. Use terraform init -upgrade when you intentionally want to update within that constraint.

This example selects the Ubuntu 24.04 release. You can use image = "lts" to follow Multipass's current LTS alias for new launches. An image alias does not pin an exact image build or upgrade an existing guest operating system.

The empty provider block uses these defaults:

Setting	Default	Purpose
`multipass_path`	`multipass`	Find the CLI on `PATH`.
`command_timeout`	`600`	Timeout in seconds for CLI operations.
`default_image`	`lts`	Image used when an instance omits `image`.

Set multipass_path only if your binary is elsewhere. Paths differ between operating systems and installation methods.

The remaining sections are optional additions or edits to this configuration. When an example says to replace a resource block, keep only one block with that resource type and Terraform name.

3. Resize an existing VM

Provider 2.0 changed the default behavior of allocation updates. CPU and memory changes, and disk growth, now resize the existing VM.

For example, replace the earlier multipass_instance.dev block with:

resource "multipass_instance" "dev" {
  name          = "dev-box"
  image         = "24.04"
  cpus          = 4
  memory        = "8G"
  disk          = "30G"
  resize_policy = "in_place"
}

Run terraform plan and terraform apply again.

Change	`in_place` (default)	`replace`
CPU or memory allocation	Resize the existing VM	Recreate the VM
Disk growth	Expand the existing disk	Recreate the VM
Disk shrink	Reject during apply, before mutation	Recreate with a smaller disk

A running VM is gracefully stopped and restarted for an in-place resize, so expect downtime. A stopped VM remains stopped. Start or stop a suspended or transitional VM before resizing it.

Use resize_policy = "replace" when you want a fresh VM after allocation changes. Changing only the policy does not resize, restart, or replace the VM. The provider never silently switches a failed in-place resize to replacement.

Removing cpus, memory, or disk from an existing resource keeps its current allocation. New instances that omit them default to 1 CPU, 1G memory, and 5G disk. Equivalent sizes such as 1G and 1024M do not trigger a resize.

Increasing the virtual disk does not guarantee that the guest partition and filesystem expand with it. Check guest capacity after growth and follow Multipass's instance modification guide if another step is needed.

Name, image, network, and cloud-init changes still force replacement, regardless of resize_policy. Review the plan before applying those changes. See the instance documentation for resize deadlines, recovery, and allocation readback limits.

4. Share a host directory

To mount a project directory, add this block inside your existing multipass_instance.dev resource. Replace the host path with an existing directory on your machine:

mounts {
  host_path     = "/home/your-user/projects"
  instance_path = "/workspace"
}

On Windows, an HCL path can use forward slashes, such as C:/Users/YourName/projects. On macOS, it might be /Users/your-name/projects.

Mounts can be added and removed without recreating the VM. Leave read_only omitted or set it to false: the Multipass CLI does not support read-only mounts, and the provider rejects true.

5. Bootstrap with cloud-init

Use cloud-init for packages, users, and configuration that must exist when a VM is first created. There are two mutually exclusive inputs:

cloud_init_file: a path to a cloud-init YAML file.
cloud_init: YAML supplied as a Terraform string, including the result of file() or templatefile().

For a templated example, save this as cloud-init.yaml.tftpl next to main.tf:

#cloud-config
users:
  - default
  - name: ${jsonencode(username)}
    groups: [sudo]
    shell: /bin/bash
    sudo: ["ALL=(ALL) NOPASSWD:ALL"]
    ssh_authorized_keys:
      - ${jsonencode(ssh_public_key)}

packages:
  - git

write_files:
  - path: /etc/motd
    permissions: "0644"
    content: ${jsonencode(motd)}

The default entry preserves the image's default user alongside the new account. jsonencode() produces quoted strings that are also valid YAML, including when a value contains quotes or line breaks.

Add the following to main.tf:

variable "ssh_public_key" {
  type        = string
  description = "Your SSH public key, used for guest access."
}

resource "multipass_instance" "runner" {
  name   = "ci-runner"
  image  = "24.04"
  cpus   = 2
  memory = "3G"
  disk   = "15G"

  cloud_init = templatefile("${path.module}/cloud-init.yaml.tftpl", {
    username       = "ci-runner"
    ssh_public_key = var.ssh_public_key
    motd           = "CI host ready.\n"
  })

  wait_for_cloud_init = true

  timeouts {
    create = "20m"
  }
}

Set ssh_public_key in terraform.tfvars to the contents of your .pub file. Keep the private key on your host. This example creates the account and installs Git; installing and registering your CI agent is a separate configuration step.

wait_for_cloud_init = true makes Terraform wait for cloud-init before reporting successful creation. Use it when later resources depend on packages, files, or networking configured during bootstrap. If cloud-init fails or times out, creation reports an error and dependent resources do not run; the created VM remains recorded in Terraform state.

Cloud-init configures a new VM. Changing inline or rendered cloud-init forces replacement. With cloud_init_file, changing the path forces replacement, but editing the file at the same path does not itself change that Terraform argument. Use cloud_init = file(...) when file-content changes should appear in the plan.

6. Add network interfaces

Start by finding networks on your own host:

multipass networks

You can also expose the list through Terraform:

data "multipass_networks" "host" {}

output "host_networks" {
  value = data.multipass_networks.host.networks
}

Each networks block becomes a multipass launch --network argument. Additional interfaces are attached alongside the default interface that Multipass uses to communicate with the VM.

For a VM with two extra interfaces, add:

variable "lan_network" {
  type        = string
  description = "A usable host network name from multipass networks."
}

variable "second_network" {
  type        = string
  description = "A second usable host network name."
}

resource "multipass_instance" "router" {
  name   = "lab-router"
  image  = "24.04"
  cpus   = 2
  memory = "2G"
  disk   = "10G"

  networks {
    name = var.lan_network
    mode = "auto"
    mac  = "52:54:00:4b:ab:01"
  }

  networks {
    name = var.second_network
    mode = "auto"
    mac  = "52:54:00:4b:ab:02"
  }
}

Set the network variables in terraform.tfvars using names available on your host. Use a unique MAC for each interface on a network. A fixed MAC is useful for a DHCP reservation; mode = "auto" lets Multipass configure the interface automatically. Manual mode requires guest-side configuration.

Attaching two interfaces does not enable IP forwarding or configure routing between them. That is a separate guest configuration step if you want this machine to act as a router.

Networking support and bridge setup depend on your operating system and Multipass driver. Prepare any required host bridge before an unattended Terraform run. See Multipass's custom networking guide.

Changing a resource's networks blocks replaces that VM. Decide on its network layout before storing data in it.

7. Configure a static address

A static address combines a fixed MAC, manual networking, and guest configuration. Choose an unused address on the subnet of the selected host network, outside its dynamic DHCP pool or reserved appropriately. The address below is an example; change it to match your network.

This example reuses lan_network and ssh_public_key from the previous sections. If using it on its own, copy those variable declarations along with the provider configuration.

locals {
  static_cidr = "192.168.1.210/24"
  static_ip   = split("/", local.static_cidr)[0]
  static_mac  = "52:54:00:4b:ab:03"
}

resource "multipass_instance" "static" {
  name   = "lab-node-1"
  image  = "24.04"
  cpus   = 2
  memory = "2G"
  disk   = "10G"

  networks {
    name = var.lan_network
    mode = "manual"
    mac  = local.static_mac
  }

  cloud_init = <<-EOT
    #cloud-config
    ssh_authorized_keys:
      - ${jsonencode(var.ssh_public_key)}
    write_files:
      - path: /etc/netplan/10-custom.yaml
        permissions: "0600"
        content: |
          network:
            version: 2
            ethernets:
              extra0:
                match:
                  macaddress: "${local.static_mac}"
                dhcp4: false
                addresses: ["${local.static_cidr}"]
    runcmd:
      - [netplan, apply]
  EOT

  wait_for_cloud_init = true

  timeouts {
    create = "20m"
  }
}

output "static_ip" {
  description = "The address configured for the additional interface."
  value       = local.static_ip
}

output "reported_ips" {
  value = multipass_instance.static.ipv4
}

The default interface remains available for Multipass and outbound connectivity. The extra interface gets the static address. For an isolated lab network, create a host bridge on its own subnet first; Canonical's static-IP guide shows that approach.

Waiting for cloud-init ensures the Netplan command completes before the provider reads the final instance information. It does not prove the address is reachable from every machine on your network.

Do not assume ipv4[0] is the static address. The provider returns Multipass's reported addresses without selecting one by interface. Here, static_ip is the configured value, while reported_ips shows what Multipass observed.

8. Upload and download files

The provider has separate resources for uploads and downloads. Both use source and destination; the resource type determines the direction.

For a complete round trip, add this example using the original dev VM:

resource "multipass_file_upload" "config" {
  instance    = multipass_instance.dev.name
  destination = "/home/ubuntu/demo/app.conf"
  content     = "PORT=8080\nLOG_LEVEL=info\n"

  create_parents = true

  lifecycle {
    replace_triggered_by = [multipass_instance.dev]
  }
}

resource "multipass_file_download" "config_copy" {
  instance       = multipass_instance.dev.name
  source         = multipass_file_upload.config.destination
  destination    = "${path.module}/downloads/app.conf"
  create_parents = true
  overwrite      = true

  triggers = {
    payload = multipass_file_upload.config.content_hash
  }

  lifecycle {
    replace_triggered_by = [multipass_file_upload.config]
  }
}

The upload uses a path writable by the default Ubuntu user. Referencing the upload's destination makes the download wait for it. The hash trigger refreshes the local copy when the payload changes.

The lifecycle rules also repeat the transfers after a planned VM update or replacement. Multipass instance IDs are names, so a rebuilt VM can have the same ID string. Referencing the whole resource in replace_triggered_by follows its planned updates and replacements, including those where its name stays the same. See Terraform's lifecycle reference.

To upload an existing local file, replace content with source = "${path.module}/files/app.conf" and create that file before planning. Provide exactly one of source or content. For directories, use recursive = true on both the upload and download resources and give each resource a dedicated destination directory.

Transfers do not run with automatic sudo. Use cloud-init to write files under privileged paths such as /etc/nginx, or explicitly arrange a separate privileged installation step. Uploading a config file also does not install or restart its application.

What file resources track

Uploads hash the local payload and transfer it when that hash changes. Guest-side edits to the uploaded file are not detected.
Downloads do not continuously watch the guest file. Change triggers or request replacement when you want a fresh copy.
Destroying an upload removes its remote destination. Destroying a download removes its local managed payload. A recursive download owns its destination directory, so keep unrelated files elsewhere.

For example, to fetch the current remote copy explicitly:

terraform apply -replace=multipass_file_download.config_copy

Use these resources for files whose creation and deletion should follow Terraform's lifecycle. Choose a separate collection process for logs or backups that must outlive terraform destroy.

9. Use the address with Ansible

For the static-IP example, this output exposes the intended address and guest user without relying on address-list ordering:

output "ansible_hosts" {
  value = {
    lab_node_1 = {
      ansible_host = local.static_ip
      ansible_user = "ubuntu"
    }
  }
}

Read it with:

terraform output -json ansible_hosts

This is input for an inventory generator, not a complete Ansible dynamic inventory. Render your preferred inventory format, or adapt the JSON to Ansible's inventory schema.

The static-IP example installs your public key for the default Ubuntu user. Ansible still needs the matching private key and network access from the machine where it runs. Terraform's wait_for_cloud_init covers bootstrap completion; use Ansible's connection waiting when your workflow also needs to account for SSH becoming reachable.

10. Manage snapshots and existing instances

The provider can manage named snapshots, but the target VM must be stopped. A dependency on the instance only establishes ordering; it does not stop it.

To snapshot the existing dev-box, stop it first:

multipass stop dev-box

Then add this resource and apply the configuration:

resource "multipass_snapshot" "backup" {
  instance = multipass_instance.dev.name
  name     = "pre-upgrade"
  comment  = "Before upgrading the development environment"
}

Run this step separately from pending file-transfer operations that need a running guest. Start the VM again when the snapshot has completed:

multipass start dev-box

Existing objects can also be imported. Add the corresponding resource configuration first, then import it instead of creating it:

terraform import multipass_instance.dev dev-box
terraform import multipass_alias.shell dev-shell
terraform import multipass_snapshot.backup dev-box.pre-upgrade
terraform import multipass_file_upload.config dev-box:/home/ubuntu/demo/app.conf

These are alternative commands for objects not already managed at those Terraform addresses. Review the next plan after import. File downloads cannot be imported.

For inspection without lifecycle ownership, use the multipass_instance data source. Other data sources list available images, host networks, and snapshots. See the provider documentation.

11. Recovery and cleanup

For an instance that might be soft-deleted outside Terraform, add auto_recover = true to its resource. Add auto_start_on_recover = true if it should also be started after recovery. Recovery does not recreate a purged VM or restore files from a backup.

When the lab is no longer needed:

terraform plan -destroy
terraform destroy

Review everything managed in that configuration, including VM disks, snapshots, aliases, uploaded files, and downloaded copies. Keep data that must survive teardown outside those managed destinations.

Where to go next

Browse the complete examples for development labs, host mounts, cloud-init, and file workflows.
Read the 2.0 upgrade notes before moving an existing 1.x configuration to the new resize default.
Prefer TypeScript or Python? The provider also works through Pulumi's Any Terraform Provider bridge. Start with the Pulumi guide and its language examples.

Start with a small VM, add only the networking and bootstrap configuration you need, and review each plan before applying it. The same resource model then scales to repeatable development environments, test labs, and local CI hosts.