### Quick Example: Provision a Server

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/README.md

A basic example demonstrating how to provision a Latitude.sh server using the `latitudesh_server` resource. This requires specifying billing, hostname, plan, site, operating system, project, and SSH keys.

```hcl
provider "latitudesh" {}

resource "latitudesh_server" "example" {
  billing           = "monthly"
  hostname          = "my-server"
  plan              = "c2-small-x86"
  site              = "SAO2"
  operating_system  = "ubuntu_24_04_x64_lts"
  project           = "proj_..."
  ssh_keys          = ["ssh_..."]
}
```

--------------------------------

### Booting a custom iPXE script with base64 encoding

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

This example shows how to deploy a server using a custom iPXE script, such as for Talos Linux. The iPXE script content is provided via the `ipxe` attribute, encoded in base64. The `allow_reinstall` attribute is set to true.

```hcl
locals {
  talos_ipxe = <<-EOT
    #!ipxe

    imgfree
    kernel https://pxe.factory.talos.dev/image/<sha>/<version>/kernel-amd64 talos.platform=metal console=tty0
    initrd https://pxe.factory.talos.dev/image/<sha>/<version>/initramfs-amd64.xz
    boot
  EOT
}

resource "latitudesh_server" "ipxe_node" {
  hostname         = "talos-worker"
  plan             = "m4-metal-large"
  site             = "CHI"
  project          = "proj_..."
  operating_system = "ipxe"
  ipxe             = base64encode(local.talos_ipxe)
  allow_reinstall  = true
}
```

--------------------------------

### Lookup by fingerprint

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example illustrates how to fetch an SSH key using its fingerprint.

```APIDOC
## Lookup by fingerprint

### Description
Retrieves an SSH key using its fingerprint.

### Method
DATA SOURCE

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```hcl
data "latitudesh_ssh_key" "by_fp" {
  fingerprint = "SHA256:AbCdEf123..."
}
```

### Response
#### Success Response (200)
- **id** (String) - The SSH key ID
- **name** (String) - The SSH key name
- **public_key** (String) - The SSH public key
- **fingerprint** (String) - The SSH key fingerprint
- **created_at** (String) - Creation timestamp
- **updated_at** (String) - Last update timestamp

#### Response Example
```json
{
  "id": "ssh_...",
  "name": "example-key",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAA...",
  "fingerprint": "SHA256:AbCdEf123...",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}
```
```

--------------------------------

### Use SSH key with a server resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example demonstrates how to fetch an SSH key by name and then assign its ID to a new server resource.

```hcl
data "latitudesh_ssh_key" "deploy" {
  name = "deploy-bot"
}

variable "project" {
  type    = string
  default = "proj_..."
}

resource "latitudesh_server" "server" {
  billing  = "monthly"
  project  = var.project
  hostname = "prd-01"
  plan     = "c2-small-x86"
  site     = "SAO2"

  # Add SSH key IDs to a server
  ssh_keys = [data.latitudesh_ssh_key.deploy.id]
}
```

--------------------------------

### Using `for_each`

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example demonstrates using `for_each` with the `latitudesh_ssh_key` data source to manage multiple SSH keys and associate them with servers.

```APIDOC
## Using `for_each`

### Description
Manages multiple SSH keys using `for_each` with the `latitudesh_ssh_key` data source and associates them with `latitudesh_server` resources.

### Method
DATA SOURCE

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```hcl
variable "project" {
  type    = string
  default = "proj_..."
}

variable "server_count" {
  type    = number
  default = 3
}

variable "ssh_key_names" {
  type    = set(string)
  default = ["ci", "dev-laptop-01"]
}

data "latitudesh_ssh_key" "keys" {
  for_each = var.ssh_key_names
  name     = each.value
}

locals {
  ssh_key_ids = [for key in data.latitudesh_ssh_key.keys : key.id]
}

resource "latitudesh_server" "server" {
  count            = var.server_count
  project          = var.project
  operating_system = "ubuntu_22_04_x64_lts"
  plan             = "c2-small-x86"
  billing          = "monthly"
  site             = "SAO2"

  # prd-01, prd-02, prd-03, ...
  hostname         = format("prd-%02d", count.index + 1)

  ssh_keys         = local.ssh_key_ids
}

output "ssh_key_ids" {
  value = local.ssh_key_ids
}
```

### Response
#### Success Response (200)
(See individual data source response for details)

#### Response Example
N/A
```

--------------------------------

### Use with a resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example shows how to use the `latitudesh_ssh_key` data source to dynamically add SSH keys to a `latitudesh_server` resource.

```APIDOC
## Use with a resource

### Description
Dynamically associates an SSH key, retrieved via the `latitudesh_ssh_key` data source, with a `latitudesh_server` resource.

### Method
DATA SOURCE

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```hcl
data "latitudesh_ssh_key" "deploy" {
  name = "deploy-bot"
}

variable "project" {
  type    = string
  default = "proj_..."
}

resource "latitudesh_server" "server" {
  billing  = "monthly"
  project  = var.project
  hostname = "prd-01"
  plan     = "c2-small-x86"
  site     = "SAO2"

  # Add SSH key IDs to a server
  ssh_keys = [data.latitudesh_ssh_key.deploy.id]
}
```

### Response
#### Success Response (200)
(See individual data source response for details)

#### Response Example
N/A
```

--------------------------------

### Lookup by name

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example shows how to find an SSH key by its name. The name must be unique within your account.

```APIDOC
## Lookup by name

### Description
Retrieves an SSH key using its name. The name must be unique within your account.

### Method
DATA SOURCE

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```hcl
data "latitudesh_ssh_key" "by_name" {
  name = "deploy-bot"
}
```

### Response
#### Success Response (200)
- **id** (String) - The SSH key ID
- **name** (String) - The SSH key name
- **public_key** (String) - The SSH public key
- **fingerprint** (String) - The SSH key fingerprint
- **created_at** (String) - Creation timestamp
- **updated_at** (String) - Last update timestamp

#### Response Example
```json
{
  "id": "ssh_...",
  "name": "deploy-bot",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAA...",
  "fingerprint": "SHA256:AbCdEf123...",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}
```
```

--------------------------------

### Using `for_each` with SSH keys

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example shows how to use the `for_each` meta-argument to look up multiple SSH keys by name and assign their IDs to multiple server resources.

```hcl
variable "project" {
  type    = string
  default = "proj_..."
}

variable "server_count" {
  type    = number
  default = 3
}

variable "ssh_key_names" {
  type    = set(string)
  default = ["ci", "dev-laptop-01"]
}

data "latitudesh_ssh_key" "keys" {
  for_each = var.ssh_key_names
  name     = each.value
}

locals {
  ssh_key_ids = [for key in data.latitudesh_ssh_key.keys : key.id]
}

resource "latitudesh_server" "server" {
  count            = var.server_count
  project          = var.project
  operating_system = "ubuntu_22_04_x64_lts"
  plan             = "c2-small-x86"
  billing          = "monthly"
  site             = "SAO2"

  # prd-01, prd-02, prd-03, ...
  hostname         = format("prd-%02d", count.index + 1)

  ssh_keys         = local.ssh_key_ids
}

output "ssh_key_ids" {
  value = local.ssh_key_ids
}
```

--------------------------------

### Lookup by ID

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/ssh_key.md

This example demonstrates how to retrieve an SSH key using its unique ID.

```APIDOC
## Lookup by ID

### Description
Retrieves an SSH key using its unique ID.

### Method
DATA SOURCE

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```hcl
data "latitudesh_ssh_key" "by_id" {
  id = "ssh_..."
}

output "ssh_key_pub" {
  value = data.latitudesh_ssh_key.by_id.public_key
}
```

### Response
#### Success Response (200)
- **id** (String) - The SSH key ID
- **name** (String) - The SSH key name
- **public_key** (String) - The SSH public key
- **fingerprint** (String) - The SSH key fingerprint
- **created_at** (String) - Creation timestamp
- **updated_at** (String) - Last update timestamp

#### Response Example
```json
{
  "id": "ssh_...",
  "name": "example-key",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAA...",
  "fingerprint": "SHA256:AbCdEf123...",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}
```
```

--------------------------------

### Use with a server resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

This example shows how to use the `latitudesh_tag` data source to assign tags to a `latitudesh_server` resource.

```APIDOC
## Use with a server resource

### Description
Assigns tags retrieved via the `latitudesh_tag` data source to a `latitudesh_server` resource.

### Method
Data Source + Resource Configuration

### Parameters
#### Data Source Arguments (latitudesh_tag)
- **name** (String) - Required - The name of the tag to look up.

#### Resource Arguments (latitudesh_server)
- **tags** (List of Strings) - A list of tag IDs to associate with the server.

### Example
```hcl
data "latitudesh_tag" "production" {
  name = "production"
}

data "latitudesh_tag" "web_tier" {
  name = "web-tier"
}

resource "latitudesh_server" "server" {
  # ... other server configuration ...
  tags = [
    data.latitudesh_tag.production.id,
    data.latitudesh_tag.web_tier.id
  ]
}
```
```

--------------------------------

### Lookup by slug

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

This example demonstrates how to retrieve a tag using its slug, which is a URL-friendly version of the name.

```APIDOC
## Lookup by slug

### Description
Retrieves a tag using its slug, which is a URL-friendly version of the name.

### Method
Data Source

### Parameters
#### Argument Reference
- **slug** (String) - Required - The tag slug to look up. Slugs are automatically generated from tag names. Exactly one of id, name, or slug must be set.

### Response
#### Read-Only Attributes
- **id** (String) - The tag ID
- **name** (String) - The tag name
- **slug** (String) - The tag slug (URL-friendly version of the name)
- **description** (String) - The tag description (may be null if not set)
- **color** (String) - The tag color as a hexadecimal color code (e.g., #ff0000)
```

--------------------------------

### Lookup by ID

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

This example demonstrates how to look up a tag using its unique ID.

```APIDOC
## Lookup by ID

### Description
Retrieves a tag using its unique identifier.

### Method
Data Source

### Parameters
#### Argument Reference
- **id** (String) - Required - The tag ID to look up. Exactly one of id, name, or slug must be set.

### Response
#### Read-Only Attributes
- **id** (String) - The tag ID
- **name** (String) - The tag name
- **slug** (String) - The tag slug (URL-friendly version of the name)
- **description** (String) - The tag description (may be null if not set)
- **color** (String) - The tag color as a hexadecimal color code (e.g., #ff0000)
```

--------------------------------

### Basic Elastic IP Usage

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/elastic_ip.md

This example demonstrates the basic configuration of an Elastic IP resource, associating it with a specific server within a project. Ensure the project and region data sources, as well as the server resource, are defined.

```hcl
data "latitudesh_region" "region" {
  slug = "SAO2"
}

resource "latitudesh_project" "project" {
  name              = "Production Environment"
  environment       = "Production"
  provisioning_type = "on_demand"
}

resource "latitudesh_server" "server" {
  hostname         = "example-host"
  operating_system = "ubuntu_24_04_x64_lts"
  plan             = "c2-small-x86"
  project          = latitudesh_project.project.id
  site             = data.latitudesh_region.region.slug
}

resource "latitudesh_elastic_ip" "elastic_ip" {
  project   = latitudesh_project.project.id
  server_id = latitudesh_server.server.id
}
```

--------------------------------

### Create a VLAN Assignment

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/vlan_assignment.md

This example demonstrates how to create a VLAN assignment by associating a server with a virtual network. Ensure that the region, project, virtual network, and server resources are defined prior to this assignment.

```hcl
data "latitudesh_region" "region" {
  slug = "SAO2"
}

resource "latitudesh_project" "project" {
  name              = "Test Environment Project"
  environment       = "Production"
  provisioning_type = "on_demand"
}

resource "latitudesh_virtual_network" "virtual_network" {
  description = "Virtual Network description"
  site        = data.latitudesh_region.region.slug # You can use the site id or slug
  project     = latitudesh_project.project.id      # You can use the project id or slug
}

resource "latitudesh_server" "server" {
  billing          = "monthly"
  hostname         = "app-stg-01"
  plan             = "c2-small-x86"
  site             = data.latitudesh_region.region.slug
  operating_system = "ubuntu_24_04_x64_lts"
  project          = latitudesh_project.project.id
}

resource "latitudesh_vlan_assignment" "vlan_assignment" {
  server_id          = latitudesh_server.server.id
  virtual_network_id = latitudesh_virtual_network.virtual_network.id
}
```

--------------------------------

### Lookup by name

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

This example shows how to find a tag by its name. The name should be unique within your team.

```APIDOC
## Lookup by name

### Description
Retrieves a tag using its name. The name must be unique within your team.

### Method
Data Source

### Parameters
#### Argument Reference
- **name** (String) - Required - The tag name to look up. Should be unique within your team. Exactly one of id, name, or slug must be set.

### Response
#### Read-Only Attributes
- **id** (String) - The tag ID
- **name** (String) - The tag name
- **slug** (String) - The tag slug (URL-friendly version of the name)
- **description** (String) - The tag description (may be null if not set)
- **color** (String) - The tag color as a hexadecimal color code (e.g., #ff0000)
```

--------------------------------

### Reinstalling on user_data content changes

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

This example shows how changes to the content of a `latitudesh_user_data` resource, referenced by the `user_data` attribute, can trigger a server reinstall. This allows cloud-init updates to be applied to existing servers. `allow_reinstall` must be true.

```hcl
resource "latitudesh_user_data" "shared" {
  description = "fleet bootstrap"
  content     = base64encode(file("./user-data.yaml"))
}

resource "latitudesh_server" "h1" {
  hostname         = "h1"
  plan             = "c2-small-x86"
  site             = "ASH"
  operating_system = "ubuntu_24_04_x64_lts"
  project          = "proj_..."
  user_data        = latitudesh_user_data.shared.id
  allow_reinstall  = true
}
```

--------------------------------

### Using `for_each` with multiple tags

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

This example demonstrates how to use `for_each` with the `latitudesh_tag` data source to retrieve multiple tags and assign them to a server.

```APIDOC
## Using `for_each` with multiple tags

### Description
Retrieves multiple tags using `for_each` based on a set of tag names and assigns their IDs to a `latitudesh_server` resource.

### Method
Data Source with `for_each` + Resource Configuration

### Parameters
#### Variable `tag_names`
- **type** (Set of Strings) - A set of tag names to look up.

#### Data Source Arguments (latitudesh_tag)
- **name** (String) - Required - The name of the tag to look up for each item in `var.tag_names`.

#### Resource Arguments (latitudesh_server)
- **tags** (List of Strings) - A list of tag IDs obtained from the data source.

### Example
```hcl
variable "tag_names" {
  type    = set(string)
  default = ["production", "web-tier", "critical"]
}

data "latitudesh_tag" "tags" {
  for_each = var.tag_names
  name     = each.value
}

locals {
  tag_ids = [for tag in data.latitudesh_tag.tags : tag.id]
}

resource "latitudesh_server" "server" {
  # ... other server configuration ...
  tags             = local.tag_ids
}
```
```

--------------------------------

### Conditional tag assignment

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

This example shows how to conditionally assign a tag to a server based on a variable.

```APIDOC
## Conditional tag assignment

### Description
Conditionally assigns a tag to a server based on the value of a variable.

### Method
Data Source + Resource Configuration with Conditional Logic

### Parameters
#### Variable `environment`
- **type** (String) - The environment name (e.g., "production").

#### Data Source Arguments (latitudesh_tag)
- **name** (String) - Required - The name of the tag to look up, derived from the `environment` variable.

#### Resource Arguments (latitudesh_server)
- **tags** (List of Strings) - A list containing the ID of the conditionally assigned tag.

### Example
```hcl
variable "environment" {
  type    = string
  default = "production"
}

data "latitudesh_tag" "env_tag" {
  name = var.environment
}

resource "latitudesh_server" "server" {
  # ... other server configuration ...
  tags = [data.latitudesh_tag.env_tag.id]
}
```
```

--------------------------------

### Booting a custom iPXE script from a URL

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

This snippet demonstrates deploying a server with an iPXE script hosted at a specific URL. The `operating_system` is set to 'ipxe', and the `ipxe` attribute directly references the URL of the script. Reinstalls are enabled.

```hcl
resource "latitudesh_server" "ipxe_node" {
  # ...
  operating_system = "ipxe"
  ipxe             = "https://pxe.factory.talos.dev/pxe/<sha>/<version>/metal-amd64"
  allow_reinstall  = true
}
```

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/CONTRIBUTING.md

Clone the repository and navigate into the project directory to begin local development.

```sh
git clone https://github.com/your-username/terraform-provider-latitudesh.git
cd terraform-provider-latitudesh
```

--------------------------------

### Create a server with custom timeouts

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

This snippet demonstrates how to create a basic server resource with specified billing, hostname, plan, site, operating system, project, and SSH keys. It also includes custom timeout configurations for create and update operations.

```hcl
resource "latitudesh_server" "server" {
  billing           = "monthly"
  hostname          = "my-server"
  plan              = "m4-metal-medium"
  site              = "ASH"
  operating_system  = "ubuntu_24_04_x64_lts"
  project           = "proj_..."
  ssh_keys          = ["ssh_..."]

  timeouts = {
    create = "45m"
    update = "60m"
  }
}
```

```hcl
output "server" {
  value = latitudesh_server.server
}
```

--------------------------------

### Initialize and Plan Terraform Changes

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

After updating the provider, run `terraform init -upgrade` to fetch the new provider version, followed by `terraform plan` to review the expected changes.

```bash
# 1. In your dev environment, upgrade the provider
terraform init -upgrade

# 2. Check what Terraform thinks will change
terraform plan

# 3. Look for the expected changes:
# - SSH keys and user data will show attribute removals
# - Servers should show no changes (they still reference the same resources)
```

--------------------------------

### Initialize Terraform Backend

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/guides/object-storage-backend.md

Initialize the Terraform backend configuration. Use `-migrate-state` if migrating from a local backend.

```shell
terraform init
```

```shell
terraform init -migrate-state
```

--------------------------------

### Create a User Data resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/user_data.md

Define a reusable cloud-init script for server bootstrapping. The content must be base64 encoded.

```hcl
resource "latitudesh_user_data" "setup" {
  description = "Standard bootstrap (packages + files + commands)"
  content = base64encode(<<-YAML
    #cloud-config
    packages:
      - nginx

    write_files:
      - path: /etc/motd
        permissions: '0644'
        content: |
          Welcome to your Latitude.sh server

    runcmd:
      - systemctl enable --now nginx
  YAML
  )
}
```

--------------------------------

### Create a Firewall with Rules

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/firewall.md

Define a firewall for a project and add custom rules for TCP ports 22, 80, and 443. The project must be defined first.

```hcl
resource "latitudesh_project" "project" {
  name              = "Production Environment"
  environment       = "Production"
  provisioning_type = "reserved"
}

resource "latitudesh_firewall" "web_firewall" {
  name    = "Web Server Firewall"
  project = latitudesh_project.project.id

  rules {
    from     = "ANY"
    to       = "ANY"
    port     = "22"
    protocol = "tcp"
  }

  rules {
    from     = "ANY"
    to       = "ANY"
    port     = "80"
    protocol = "tcp"
  }

  rules {
    from     = "ANY"
    to       = "ANY"
    port     = "443"
    protocol = "tcp"
  }
}
```

--------------------------------

### Initialize and Apply Terraform Configuration

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/README.md

Commands to initialize Terraform and apply the configuration to provision resources. You will be prompted to confirm the changes.

```sh
terraform init
terraform apply
```

--------------------------------

### Create a Latitude.sh Server

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/index.md

Define a Latitude.sh server resource. This requires specifying billing, hostname, OS, plan, project ID, site slug, and associated SSH keys. A project must exist before creating a server.

```hcl
resource "latitudesh_server" "server" {
  billing          = var.billing
  hostname         = var.hostname
  operating_system = var.operating_system
  plan             = var.plan
  project          = latitudesh_project.new_project.id  # You can use the project id or slug
  site             = data.latitudesh_region.region.slug # You can use the site id or slug
  ssh_keys         = [latitudesh_ssh_key.ssh_key.id]
}
```

--------------------------------

### Create a virtual machine

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/virtual_machine.md

Defines a virtual machine resource with a name, plan, operating system, and associated SSH keys. The resource waits for the VM to be running with a primary IPv4 address before completing.

```hcl
resource "latitudesh_ssh_key" "ssh_key" {
  name       = "bastion-key"
  public_key = "ssh-ed25519 AAAA..."
}

resource "latitudesh_virtual_machine" "bastion" {
  name             = "bastion"
  plan             = "vm-small"
  operating_system = "ubuntu_24_04_x64_lts"
  ssh_keys         = [latitudesh_ssh_key.ssh_key.id]
}

output "bastion_ip" {
  value = latitudesh_virtual_machine.bastion.primary_ipv4
}
```

--------------------------------

### Initialize Terraform with Local Build

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/CONTRIBUTING.md

After configuring your project and `~/.terraformrc`, re-initialize Terraform to pick up the local provider build. Remove lock files to ensure a fresh initialization.

```sh
rm -rf .terraform .terraform.lock.hcl
terraform init
```

--------------------------------

### Create a Latitude.sh Project

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/index.md

Define a Latitude.sh project resource. Projects are used to organize servers and other resources. Ensure the project name is unique.

```hcl
resource "latitudesh_project" "new_project" {
  name              = "The project name must be unique"
  description       = "The project description"
  environment       = "Development" # Development, Production or Staging
  provisioning_type = "on_demand"   # on_demand or reserved
}
```

--------------------------------

### Create a latitudesh_project Resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/project.md

Use this resource to create a new project in your Latitude.sh account. Specify the project name, environment (Development, Production, or Staging), and provisioning type.

```terraform
resource "latitudesh_project" "project" {
  name              = "Project name"
  environment       = "Development" # Development, Production or Staging
  provisioning_type = "on_demand"
}
```

--------------------------------

### Create an SSH Key Resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/index.md

Define an SSH key resource for accessing your servers. Replace the placeholder public key with your actual SSH public key.

```hcl
resource "latitudesh_ssh_key" "ssh_key" {
  name        = "Name of the SSH Key"
  public_key  = "ssh-ed25519 AAA...REPLACE_ME... user@example.com"
}
```

--------------------------------

### Import a Virtual Network using Import Block (Experimental)

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/virtual_network.md

Use the experimental import block to define imports within your Terraform configuration. This method requires Terraform v1.5.0 or later. After defining the import block, run `terraform plan -generate-config-out` to create the resource configuration.

```hcl
import {
  to = latitudesh_virtual_network.virtual_network
  id = "<VIRTUAL_NETWORK_ID>"
}
```

--------------------------------

### Import a virtual machine using CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/virtual_machine.md

Imports an existing virtual machine resource into Terraform state using the CLI. Ensure the plan and project are correctly set in the configuration after import to avoid spurious diffs.

```bash
terraform import latitudesh_virtual_machine.bastion <VIRTUAL_MACHINE_ID>
```

--------------------------------

### Apply Terraform Changes

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

Execute `terraform apply` to apply the planned changes. A subsequent `terraform plan` should show no further modifications.

```bash
# Apply the changes
terraform apply

# Validate everything works
terraform plan  # Should show no further changes
```

--------------------------------

### Import Server Resource via Import Block (Experimental)

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

Define imports directly in your Terraform configuration using the experimental import block. This requires Terraform v1.5.0 or later. After defining the import block, run 'terraform plan -generate-config-out=generated_server.tf' to generate the resource configuration.

```hcl
import {
  to = latitudesh_server.my_server
  id = "<SERVER_ID>"
}
```

--------------------------------

### Create a Virtual Network

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/virtual_network.md

Use this snippet to create a new virtual network. Ensure you have defined the data source for the region and the resource for the project.

```hcl
data "latitudesh_region" "region" {
  slug = "SAO2"
}

resource "latitudesh_project" "project" {
  name              = "Production Environment"
  environment       = "Production"
  provisioning_type = "on_demand"
}

resource "latitudesh_virtual_network" "virtual_network" {
  description      = "Virtual Network description"
  site             = data.latitudesh_region.region.slug # You can use the site id or slug
  project          = latitudesh_project.project.id      # You can use the project id or slug
}
```

--------------------------------

### latitudesh_project Resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/project.md

The `latitudesh_project` resource allows you to create and manage projects within your Latitude.sh account.

```APIDOC
## Resource: latitudesh_project

### Description

Creates and manages projects within a Latitude.sh account.

### Schema

#### Required

- `environment` (String) The name of the project. Accepted values are 'Development', 'Production', or 'Staging'.
- `name` (String) The name of the project.
- `provisioning_type` (String) The provisioning type of the project.

#### Optional

- `description` (String) The description of the project.
- `tags` (List of String) List of project tags.

#### Read-Only

- `created` (String) The timestamp for when the project was created.
- `id` (String) The ID of this resource.
- `updated` (String) The timestamp for the last time the project was updated.

### Import

**CLI Import**

The `latitudesh_project` resource can be imported by specifying the Project ID:

```sh
terraform import latitudesh_project.my_project <PROJECT_ID>
```

**Import Block (Experimental)**

Terraform v1.5.0 and later supports the experimental import block:

```hcl
import {
  to = latitudesh_project.my_project
  id = "<PROJECT_ID>"
}
```

Then run:

```sh
terraform plan -generate-config-out=generated_project.tf
```
```

--------------------------------

### Create an SSH Key

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/ssh_key.md

Use this snippet to create a new SSH key resource. Provide a name and the public key content.

```hcl
resource "latitudesh_ssh_key" "ssh_key" {
  name       = "John's Key"
  public_key = "ssh-ed25519 AAAA..."
}
```

--------------------------------

### Authenticate with Latitude.sh API

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/README.md

Export your Latitude.sh API key as an environment variable for authentication. Replace "<your-api-key-here>" with your actual API key.

```sh
export LATITUDESH_AUTH_TOKEN="<your-api-key-here>"
```

--------------------------------

### Assign a Firewall to a Server

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/firewall_assignment.md

Use this resource to associate a pre-defined firewall with a specific server. Ensure the firewall and server resources are defined prior to this assignment.

```hcl
resource "latitudesh_project" "project" {
  name              = "Production Environment"
  environment       = "Production"
  provisioning_type = "on_demand"
}

resource "latitudesh_server" "web_server" {
  billing          = "monthly"
  hostname         = "web-01"
  operating_system = "ubuntu_22_04_x64_lts"
  plan             = "c2-medium-x86"
  project          = latitudesh_project.project.id
  site             = "SAO2"
}

resource "latitudesh_firewall" "web_firewall" {
  name    = "Web Server Firewall"
  project = latitudesh_project.project.id

  rules {
    from     = "0.0.0.0/0"
    to       = "0.0.0.0/0"
    port     = "22"
    protocol = "tcp"
  }

  rules {
    from     = "0.0.0.0/0"
    to       = "0.0.0.0/0"
    port     = "80"
    protocol = "tcp"
  }
}

resource "latitudesh_firewall_assignment" "web_assignment" {
  firewall_id = latitudesh_firewall.web_firewall.id
  server_id   = latitudesh_server.web_server.id
}
```

--------------------------------

### Build the Provider

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/CONTRIBUTING.md

Compile the Terraform provider locally using the provided Makefile target.

```sh
make build
```

--------------------------------

### Import a Virtual Network using CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/virtual_network.md

Import an existing Virtual Network resource into your Terraform state using the Terraform CLI. Replace `<VIRTUAL_NETWORK_ID>` with the actual ID of the virtual network.

```bash
terraform import latitudesh_virtual_network.virtual_network <VIRTUAL_NETWORK_ID>
```

--------------------------------

### Run Provider Tests

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/CONTRIBUTING.md

Execute the test suite for the Terraform provider using the provided Makefile target.

```sh
make test
```

--------------------------------

### Import Server Resource via CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

Use this command to import an existing server resource into your Terraform state by providing its ID.

```bash
terraform import latitudesh_server.my_server <SERVER_ID>
```

--------------------------------

### Import a Firewall Resource via CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/firewall.md

Import an existing firewall resource into Terraform management using the Terraform CLI. Replace <FIREWALL_ID> with the actual ID of the firewall.

```bash
terraform import latitudesh_firewall.web_firewall <FIREWALL_ID>
```

--------------------------------

### Import a virtual machine using experimental import block

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/virtual_machine.md

Imports an existing virtual machine resource using the experimental import block in Terraform configuration. This feature is experimental and may change in future versions. After running 'terraform plan -generate-config-out', ensure the plan and project are correctly set in the configuration.

```hcl
import {
  to = latitudesh_virtual_machine.bastion
  id = "<VIRTUAL_MACHINE_ID>"
}
```

--------------------------------

### Import a latitudesh_project Resource using CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/project.md

Import an existing Project resource into your Terraform configuration by specifying the Project ID using the Terraform CLI.

```bash
terraform import latitudesh_project.my_project <PROJECT_ID>
```

--------------------------------

### Configure Terraform for Local Development

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/CONTRIBUTING.md

Set up Terraform to use your local provider build by adding a dev override to your `~/.terraformrc` file. This ensures Terraform uses your local changes instead of the registry version.

```hcl
provider_installation {
  dev_overrides {
    "local/iac/latitudesh" = "/Users/your-username/Developer/latitudesh/terraform-provider-latitudesh"
  }
  direct {}
}
```

--------------------------------

### Assign multiple tags to a server

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/tag.md

Retrieve multiple tags by name and assign their IDs to a server resource. Ensure that the tag names used exist.

```hcl
data "latitudesh_tag" "production" {
  name = "production"
}

data "latitudesh_tag" "web_tier" {
  name = "web-tier"
}

variable "project" {
  type    = string
  default = "proj_..."
}

resource "latitudesh_server" "server" {
  billing          = "monthly"
  project          = var.project
  hostname         = "web-prd-01"
  plan             = "c2-small-x86"
  site             = "SAO2"
  operating_system = "ubuntu_22_04_x64_lts"

  # Add tag IDs to a server
  tags = [
    data.latitudesh_tag.production.id,
    data.latitudesh_tag.web_tier.id
  ]
}
```

--------------------------------

### Backup Terraform State Files

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

Provides commands to back up local and remote Terraform state files before performing a major upgrade. This is a crucial step for disaster recovery.

```bash
# For local state files
cp terraform.tfstate terraform.tfstate.backup-v1

# For remote state (adjust for your backend)
terraform state pull > terraform.tfstate.backup-v1
```

--------------------------------

### Import a Firewall Resource using Import Block (Experimental)

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/firewall.md

Use the experimental import block in Terraform to define imports within your configuration. This feature may change in future releases. Ensure to replace <FIREWALL_ID> with the actual ID.

```hcl
import {
  to = latitudesh_firewall.web_firewall
  id = "<FIREWALL_ID>"
}
```

--------------------------------

### Generate Server Configuration from Imported State

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/index.md

After importing a server using the `import` block, run this command to generate a Terraform configuration file (`server.tf`) reflecting the current state of the imported server.

```sh
terraform plan -generate-config-out=server.tf
```

--------------------------------

### v1.x SSH Key and User Data Configuration (Old)

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

Illustrates the previous project-scoped configuration for SSH keys and user data in v1.x of the Latitude.sh Terraform Provider.

```hcl
resource "latitudesh_ssh_key" "deploy" {
  project    = latitudesh_project.main.id  # ❌ No longer needed
  name       = "deployment-key"
  public_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5..."
}

resource "latitudesh_user_data" "setup" {
  project     = latitudesh_project.main.id  # ❌ No longer needed
  description = "Server initialization script"
  content     = base64encode("#!/bin/bash\napt-get update")
}
```

--------------------------------

### Import a User Data resource using CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/user_data.md

Import an existing User Data resource into your Terraform configuration using the Terraform CLI.

```bash
$ terraform import latitudesh_user_data.user_data <USER_DATA_ID>
```

--------------------------------

### Import a Member using CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/member.md

Import an existing Member resource into your Terraform configuration using the CLI. Replace `<MEMBER_ID>` with the actual ID of the member.

```bash
terraform import latitudesh_member.member <MEMBER_ID>
```

--------------------------------

### Import a latitudesh_project Resource using Import Block

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/project.md

Use the experimental import block (Terraform v1.5.0+) to define imports directly in your configuration. This method generates the resource configuration for the imported project. Note that this feature is experimental.

```hcl
import {
  to = latitudesh_project.my_project
  id = "<PROJECT_ID>"
}
```

```bash
terraform plan -generate-config-out=generated_project.tf
```

--------------------------------

### Import a latitudesh_tag Resource using Import Block

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/tag.md

Use the experimental import block to define imports within your Terraform configuration. This method requires Terraform v1.5.0 or later. After creating the `import.tf` file, run `terraform plan -generate-config-out=generated_tag.tf` to generate the resource configuration.

```hcl
import {
  to = latitudesh_tag.tag
  id = "<TAG_ID>"
}
```

--------------------------------

### Configure Terraform Project for Local Build

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/CONTRIBUTING.md

In your Terraform project, specify the provider source as `local/iac/latitudesh` to use your local build. Ensure no `version` is specified to guarantee the local build is used.

```hcl
terraform {
  required_providers {
    latitudesh = {
      source = "local/iac/latitudesh"
    }
  }
}

provider "latitudesh" {}
```

--------------------------------

### Import Existing Server into Terraform State

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/index.md

Import an existing Latitude.sh server into your Terraform state. This allows you to manage pre-existing resources with Terraform. After running `terraform plan -generate-config-out=server.tf`, customize the generated `server.tf` file.

```hcl
terraform {
  required_providers {
    latitudesh = {
      source  = "latitudesh/latitudesh"
      version = ">= 2.5.0"
    }
  }
}

import {
  to = latitudesh_server.server
  id = "sv_your_server_id_here"
}
```

--------------------------------

### Elastic IP with Provider-Level Project Default

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/elastic_ip.md

Configure an Elastic IP without explicitly defining the project ID, by leveraging the provider-level project default. This simplifies configuration when all resources belong to the same project.

```hcl
provider "latitudesh" {
  project = "proj_abc123"
}

resource "latitudesh_elastic_ip" "elastic_ip" {
  server_id = "sv_XYZ123"
}
```

--------------------------------

### Import SSH Key using CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/ssh_key.md

Import an existing SSH key resource into Terraform management using the CLI. Replace `<SSH_KEY_ID>` with the actual ID of the SSH key.

```bash
terraform import latitudesh_ssh_key.ssh_key <SSH_KEY_ID>
```

--------------------------------

### Restore State Backup

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

If issues arise, restore your previous state by copying the backup file to `terraform.tfstate`.

```bash
cp terraform.tfstate.backup-v1 terraform.tfstate
```

--------------------------------

### latitudesh_member Resource

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/member.md

This snippet shows how to create a new member in your Latitude.sh account using the `latitudesh_member` resource. It requires the member's email and role, and optionally accepts first and last names.

```APIDOC
## Resource: latitudesh_member

### Description

The `latitudesh_member` resource allows you to create members within your [Latitude.sh](https://latitude.sh/) account.

### Schema

#### Required

- `email` (String) The member email
- `role` (String) The member role

#### Optional

- `first_name` (String) The member first name
- `last_name` (String) The member last name

#### Read-Only

- `id` (String) The ID of this resource.
- `mfa_enabled` (String) The member mfa status

### Example Usage

```hcl
data "latitudesh_role" "role" {
  name = "collaborator"
}

resource "latitudesh_member" "member" {
  first_name    = "Name"
  last_name     = "Surname"
  email         = "namesurname@example.com"
  role          = data.latitudesh_role.role.name
}
```
```

--------------------------------

### Restricting reinstall triggers to user_data

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/server.md

This configuration restricts server reinstalls to only occur when the `user_data` attribute changes. Other reinstall-trigger fields will cause a plan error if modified, unless also included in `allowed_reinstall_triggers`. `allow_reinstall` must be true.

```hcl
resource "latitudesh_server" "h1" {
  hostname                   = "h1"
  plan                       = "c2-small-x86"
  site                       = "ASH"
  operating_system           = "ubuntu_24_04_x64_lts"
  project                    = "proj_..."
  user_data                  = latitudesh_user_data.shared.id
  allow_reinstall            = true
  allowed_reinstall_triggers = ["user_data"]
}
```

--------------------------------

### latitudesh_plan

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/data-sources/plan.md

The latitudesh_plan data source allows you to retrieve details about a specific plan, such as its stock availability and slug.

```APIDOC
## Schema

### Required

- `name` (String) The name of the Plan to match

### Read-Only

- `id` (String) The ID of this Plan.
- `in_stock` (List of String) List of the sites where this Plan is in stock.
- `slug` (String) The slug of this Plan.
```

--------------------------------

### Import a latitudesh_tag Resource via CLI

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/docs/resources/tag.md

Import an existing Tag resource using the Terraform CLI. Replace `<TAG_ID>` with the actual ID of the tag you wish to import.

```bash
terraform import latitudesh_tag.tag <TAG_ID>
```

--------------------------------

### Temporarily Downgrade Provider

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

To revert to a previous version temporarily, update the `versions.tf` file with the desired older version constraint and reinitialize.

```hcl
terraform {
  required_providers {
    latitudesh = {
      source  = "latitudesh/latitudesh"
      version = "> 1.2.0"  # Back to v1.x
    }
  }
}
```

--------------------------------

### Expected Changes During Plan (v2 Upgrade)

Source: https://github.com/latitudesh/terraform-provider-latitudesh/blob/main/MIGRATION_GUIDE_v2.md

Observe attribute removals for `project` in `latitudesh_ssh_key` and `latitudesh_user_data` resources during the first `terraform plan` after upgrading. Server resources should remain unchanged.

```diff
# latitudesh_ssh_key.deploy will be updated in-place
~ resource "latitudesh_ssh_key" "deploy" {
    ~ project = "project-123" -> null
    # Other attributes unchanged
}

# latitudesh_user_data.setup will be updated in-place  
~ resource "latitudesh_user_data" "setup" {
    ~ project = "project-123" -> null
    # Other attributes unchanged
}

# latitudesh_server.web - no changes needed
  resource "latitudesh_server" "web" {
    # Server references still work perfectly
    user_data = latitudesh_user_data.setup.id
    ssh_keys  = [latitudesh_ssh_key.deploy.id]
  }
```