terraform-provider-virtfusion/README.md

# Terraform Provider for VirtFusion

A Terraform provider for managing [VirtFusion](https://virtfusion.com) virtualization platform resources. Automate server provisioning, user management, networking, and self-service billing through infrastructure as code.

## Requirements

- [Terraform](https://developer.hashicorp.com/terraform/install) >= 1.0
- [Go](https://golang.org/doc/install) >= 1.21 (for building from source)
- A VirtFusion control panel instance with API access

## Installation

### From Release

Download the appropriate binary from the [Releases](https://git.ezscale.cloud/EZSCALE/terraform-provider-virtfusion/releases) page and place it in your Terraform plugins directory.

### From Source

```bash
git clone https://git.ezscale.cloud/EZSCALE/terraform-provider-virtfusion.git
cd terraform-provider-virtfusion
go install .
```

Then configure `~/.terraformrc` for local development:

```hcl
provider_installation {
  dev_overrides {
    "registry.terraform.io/EZSCALE/virtfusion" = "/path/to/your/gopath/bin"
  }
  direct {}
}
```

## Quick Start

```hcl
terraform {
  required_providers {
    virtfusion = {
      source = "registry.terraform.io/EZSCALE/virtfusion"
    }
  }
}

variable "virtfusion_api_token" {
  type      = string
  sensitive = true
}

provider "virtfusion" {
  endpoint  = "https://cp.example.com"
  api_token = var.virtfusion_api_token
}
```

The provider can also be configured using environment variables:

```bash
export VIRTFUSION_ENDPOINT="https://cp.example.com"
export VIRTFUSION_API_TOKEN="your-api-token"
```

## Usage Examples

### Create a user, SSH key, server, and build it

```hcl
resource "virtfusion_user" "customer" {
  name            = "Jane Doe"
  email           = "jane@example.com"
  ext_relation_id = "cust-001"
}

resource "virtfusion_ssh_key" "key" {
  user_id    = virtfusion_user.customer.id
  name       = "deploy-key"
  public_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample deploy@example.com"
}

resource "virtfusion_server" "web" {
  package_id    = 19
  user_id       = virtfusion_user.customer.id
  hypervisor_id = 8
}

resource "virtfusion_server_build" "web" {
  server_id = virtfusion_server.web.id
  name      = "web-server"
  hostname  = "web.example.com"
  osid      = 13
  vnc       = true
  ipv6      = true
  ssh_keys  = [virtfusion_ssh_key.key.id]
}
```

### Read infrastructure data

```hcl
data "virtfusion_servers" "all" {}
data "virtfusion_packages" "all" {}
data "virtfusion_hypervisors" "all" {}

output "server_count" {
  value = length(data.virtfusion_servers.all.servers)
}
```

List data sources support a `results` parameter (default: 300) and automatically paginate through all pages:

```hcl
data "virtfusion_servers" "all" {
  results = 100  # override per-page limit
}
```

## Resources

| Resource | Description |
|----------|-------------|
| `virtfusion_server` | Create and manage servers |
| `virtfusion_server_build` | Build (install OS on) a server |
| `virtfusion_server_firewall` | Manage server firewall rules |
| `virtfusion_server_ipv4` | Add IPv4 addresses to a server |
| `virtfusion_server_network_whitelist` | Manage network whitelist entries |
| `virtfusion_server_traffic_block` | Manage traffic blocks |
| `virtfusion_server_power_action` | Control server power state |
| `virtfusion_server_password_reset` | Reset server root password |
| `virtfusion_ssh_key` | Manage SSH keys |
| `virtfusion_user` | Manage users |
| `virtfusion_user_auth_token` | Generate user authentication tokens |
| `virtfusion_user_server_auth_token` | Generate server-scoped authentication tokens |
| `virtfusion_user_password_reset` | Reset user passwords |
| `virtfusion_ip_block_range` | Add IPv4 ranges to IP blocks |
| `virtfusion_self_service_credit` | Manage self-service billing credits |
| `virtfusion_self_service_resource_pack` | Manage resource packs |
| `virtfusion_self_service_hourly_group_profile` | Manage hourly billing group profiles |
| `virtfusion_self_service_hourly_resource_pack` | Manage hourly resource packs |
| `virtfusion_self_service_resource_group_profile` | Manage resource group profiles |
| `virtfusion_self_service_pack_servers_action` | Suspend/unsuspend/delete pack servers |

## Data Sources

| Data Source | Description |
|-------------|-------------|
| `virtfusion_server` | Read a single server by ID |
| `virtfusion_servers` | List all servers |
| `virtfusion_servers_by_user` | List servers owned by a user |
| `virtfusion_server_backups` | List server backups |
| `virtfusion_server_firewall` | Read server firewall configuration |
| `virtfusion_server_templates` | List available templates for a server |
| `virtfusion_server_traffic` | Read server traffic usage |
| `virtfusion_server_traffic_blocks` | List server traffic blocks |
| `virtfusion_server_vnc` | Get VNC connection info |
| `virtfusion_hypervisor` | Read a single hypervisor |
| `virtfusion_hypervisors` | List all hypervisors |
| `virtfusion_hypervisor_group` | Read a single hypervisor group |
| `virtfusion_hypervisor_groups` | List all hypervisor groups |
| `virtfusion_hypervisor_group_resources` | Read aggregated resources for a group |
| `virtfusion_package` | Read a single package |
| `virtfusion_packages` | List all packages |
| `virtfusion_package_templates` | List templates for a package |
| `virtfusion_ip_block` | Read a single IP block |
| `virtfusion_ip_blocks` | List all IP blocks |
| `virtfusion_ssh_key` | Read a single SSH key |
| `virtfusion_ssh_keys_by_user` | List SSH keys for a user |
| `virtfusion_user` | Read a user by external relation ID |
| `virtfusion_dns_service` | Read DNS service configuration |
| `virtfusion_iso` | Read ISO media info |
| `virtfusion_queue_item` | Read a queue item status |
| `virtfusion_self_service_currencies` | List available currencies |
| `virtfusion_self_service_resource_pack` | Read a resource pack |
| `virtfusion_self_service_hourly_stats` | Read hourly billing stats |
| `virtfusion_self_service_report` | Read self-service reports |
| `virtfusion_self_service_usage` | Read self-service usage |

## Development

### Build

```bash
go build ./...
```

### Install locally

```bash
go install .
```

### Run linter

```bash
golangci-lint run
```

## License

[MPL-2.0](LICENSE)