Aan de slag met Terraform¶

In dit artikel

• Wat je nodig hebt om met Terraform te werken
• Stap 1. Terraform installeren
• Stap 2. Een API key aanmaken
• Stap 3. De configuratie voorbereiden
• Stap 4. De provider initialiseren
• Stap 5. De configuratie valideren
• Stap 6. De server bestellen
• Stap 7. De configuratie wijzigen
• Stap 8. De resources verwijderen
• Bestaande servers importeren
• Probleemoplossing

Wanneer je slechts één server hebt, is het handmatig bestellen sneller. Zodra er vijftien zijn, op verschillende tijdstippen aangemaakt door verschillende beheerders, weet niemand meer waarom de ene Ubuntu 20.04 draait terwijl de machine ernaast 22.04 draait. Een configuratiebestand houdt die geschiedenis automatisch bij en zorgt er ook voor dat je dezelfde omgeving kunt herstellen zonder een reeks handelingen uit het hoofd te hoeven reproduceren.

Met onze provider ziet de workflow er als volgt uit. Het bestand bevat de preset, de locatie, het besturingssysteem en het verkeersplan, waarna terraform apply de bestelling plaatst en wacht tot de implementatie is voltooid. Het opnieuw uitvoeren hiervan dupliceert niets, aangezien Terraform de resources die het heeft aangemaakt onthoudt. Het terraform plan commando toont de geplande wijzigingen zonder ze daadwerkelijk uit te voeren.

De provider werkt met de volledige catalogus, inclusief VPS, VDS, dedicated en GPU-servers, extra IP-adressen, SSH-keys en DNS-zones. Een volledige referentie voor de resources en data sources is beschikbaar in de Terraform Registry en in de hostkey-cloud/terraform-provider-hostkey-com repository. Wat volgt is het basisscenario: het bestellen van een virtuele server.

Wat je nodig hebt om met Terraform te werken¶

• Een account in het Invapi control panel met voldoende saldo, aangezien het bestellen van een server een betaalde operatie is;
• een API key;
• een SSH key;
• Terraform 1.0 of nieuwer.

Stap 1. Terraform installeren¶

Terraform werkt op Linux, macOS en Windows, en je kunt het op twee manieren installeren: via een pakketbeheerder of handmatig door het vooraf gecompileerde binary te downloaden en uit te pakken.

Windows¶

Download het archief, pak terraform.exe uit in een specifieke map zoals C:\terraform, en voeg die map toe aan de Path omgevingsvariabele.

Sluit daarna de terminal en open deze opnieuw, aangezien de nieuwe Path waarde pas wordt toegepast na een herstart. Om de installatie te verifiëren:

terraform -v

Linux¶

wget https://releases.hashicorp.com/terraform/1.15.8/terraform_1.15.8_linux_amd64.zip
unzip ./terraform_1.15.8_linux_amd64.zip
sudo mv ./terraform /usr/local/bin
terraform -v

macOS¶

brew install terraform
terraform -v

Stap 2. Een API key aanmaken¶

De key wordt aangemaakt in het Invapi control panel. Klik op je gebruikersnaam in de rechterbovenhoek en selecteer API keys:

Klik op Add new en vul het formulier in.

Het veld Restrict a new API key only for the server koppelt de key aan een enkele service, en de provider moet nieuwe servers kunnen bestellen, dus de waarde moet Any zijn.

Het veld IP ACL beperkt de toegang tot de vermelde adressen. Dit verhoogt de beveiliging, maar bij een dynamisch IP-adres stopt de key met werken zodra het adres verandert. Laat het veld dus leeg wanneer je begint, en vermeld bij continuous integration de adressen van je build-servers.

Klik op Create. De key wordt slechts één keer getoond.

Stap 3. De configuratie voorbereiden¶

Maak een projectmap aan, bijvoorbeeld hostkey-terraform. Configuratiebestanden gebruiken de extensie .tf en hun namen zijn willekeurig, aangezien Terraform elk .tf bestand in de map samenvoegt tot één configuratie. Ons voorbeeld gebruikt drie bestanden.

main.tf¶

Het eerste blok legt de provider en de vereiste Terraform-versie vast.

terraform {
  required_providers {
    hostkey = {
      source  = "hostkey-cloud/hostkey-com"
      version = "~> 0.2"
    }
  }
  required_version = ">= 1.0"
}

provider "hostkey" {}

Vervolgens volgt de cataloguscontrole. Deze blokken maken geen resources aan en worden niet in rekening gebracht; ze vragen alleen de API om de lijsten met beschikbare presets en verkeersplannen:

data "hostkey_presets" "selected" {
  location = var.location
  name     = var.preset_name
}

data "hostkey_traffic_plans" "for_preset" {
  location    = var.location
  instance_id = data.hostkey_presets.selected.presets[0].id
}

output "catalog_preset" {
  value = data.hostkey_presets.selected.presets
}

output "catalog_traffic_plans" {
  value = data.hostkey_traffic_plans.for_preset.traffic_plans
}

Deze controle is het waard om twee redenen. De provider vereist een exacte naamovereenkomst, en de catalogus bevat vergelijkbare namen voor verkeersplannen, zoals bijvoorbeeld 3 TB / 1 Gbps VM en 3Tb traffic (1Gbps) VM. Bovendien hangt de inhoud van de catalogus af van de locatie en verandert deze in de loop van de tijd, dus een preset die vandaag beschikbaar is, kan morgen niet meer beschikbaar zijn.

De server zelf wordt hierna beschreven:

resource "hostkey_server" "web" {
  preset_name       = var.preset_name
  location_name     = var.location
  traffic_plan_name = var.traffic_plan_name
  deploy_period     = "monthly"

  os_name   = "Ubuntu 22.04"
  root_pass = var.root_pass
  ssh_key   = file(pathexpand(var.ssh_public_key_path))

  power_state = "on"

  cancellation_type   = 1
  cancellation_reason = "terraform"

  tags = {
    env = "demo"
  }

  timeouts {
    create = "90m"
    update = "90m"
    delete = "30m"
  }
}

Het timeouts blok bepaalt hoe lang Terraform wacht tot een operatie is voltooid. Implementatie duurt meestal een paar minuten, maar als het wachten wordt afgebroken door een timeout, blijft de bestelling betaald terwijl Terraform het spoor verliest.

Het argument cancellation_type ingesteld op 1 annuleert de service onmiddellijk, terwijl 0 de service laat doorlopen tot het einde van de betaalde periode.

De SSH-key in de accountopslag wordt apart aangemaakt:

resource "hostkey_ssh_key" "deploy" {
  name = "tf-deploy"
  key  = file(pathexpand(var.ssh_public_key_path))
}

Dit is niet hetzelfde als het ssh_key attribuut van hostkey_server. Het server-attribuut schrijft de key naar de machine tijdens de installatie van het besturingssysteem, terwijl de hostkey_ssh_key resource de key in het account opslaat voor later gebruik.

Het bestand eindigt met output blokken. Na de bestelling print Terraform het serveradres, de identifier en het factuurnummer, en terraform output main_ipv4 geeft op elk gewenst moment later het adres terug, wat handig is wanneer er iets anders volgt:

output "server_id" {
  value = hostkey_server.web.id
}

output "main_ipv4" {
  value = hostkey_server.web.main_ipv4
}

output "invoice" {
  value = hostkey_server.web.invoice
}

variables.tf¶

variable "location" {
  type    = string
  default = "FI"
}

variable "preset_name" {
  type    = string
  default = "vm.v2-pico"
}

variable "traffic_plan_name" {
  type    = string
  default = "3 TB / 1 Gbps VM"
}

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

variable "ssh_public_key_path" {
  type    = string
  default = "~/.ssh/id_ed25519.pub"
}

terraform.tfvars¶

Dit bestand bevat het wachtwoord, zodat het niet in versiebeheer wordt gezet:

root_pass = "StrongPass1%"

# De defaults kunnen hier worden overschreven
# location          = "NL"
# preset_name       = "vm.v3-pico"
# traffic_plan_name = "5 TB / 1 Gbps VM"

Stap 4. De provider initialiseren¶

De key wordt via een omgevingsvariabele doorgegeven zodat deze buiten de projectbestanden blijft:

$env:HOSTKEY_API_KEY = "your-key"

Gebruik in de Windows opdrachtprompt set HOSTKEY_API_KEY=your-key, en op Linux en macOS export HOSTKEY_API_KEY="your-key". De variabele is alleen van toepassing op de huidige terminal-sessie.

Vervolgens moet de provider worden gedownload:

terraform init

Terraform downloadt de provider en maakt een .terraform.lock.hcl bestand aan met de exacte versie. Dit bestand wordt naar de repository gecommit, aangezien het garandeert dat iedereen in het project met dezelfde geïnstalleerde versie werkt.

Stap 5. De configuratie valideren¶

De syntaxis wordt gecontroleerd zonder de API aan te roepen:

terraform validate

Een succesvolle controle geeft Success! The configuration is valid. weer.

Vervolgens volgt het plan, dat de geplande wijzigingen toont zonder ze uit te voeren:

terraform plan

De samenvattingsregel. Verwacht Plan: 2 to add, 0 to change, 0 to destroy, dit zijn de server en de SSH-key.

De opgeloste identifiers. De provider vult preset_id, os_id en traffic_plan_id in naast de namen, en als een naam niet in de catalogus wordt gevonden, mislukt het plan voordat er iets in rekening wordt gebracht.

De catalogus. De sectie Changes to Outputs somt de presets en verkeersplannen op, en de waarden in de configuratie moeten exact op dezelfde manier worden geschreven.

Stap 6. De server bestellen¶

terraform apply

Terraform toont het plan nogmaals en vraagt om bevestiging; typ yes en druk op Enter.

De SSH-key wordt eerst aangemaakt, waarna de serverbestelling begint; Terraform heeft deze volgorde zelf bepaald op basis van de afhankelijkheden.

Daarna volgen de Still creating... regels, die elke tien seconden worden ververst, terwijl de provider de API pollt en wacht tot de installatie is voltooid. Ondertussen is de server zichtbaar in het control panel:

Zodra het klaar is, worden de waarden geprint. Het is de moeite waard om de SSH-toegang te controleren met het adres dat je hebt ontvangen:

De key die is opgegeven in het ssh_key attribuut is al aanwezig op de server, dus er wordt geen wachtwoord gevraagd. De nieuwe server verschijnt in het control panel naast de handmatig bestelde servers:

Stap 7. De configuratie wijzigen¶

Wijzigingen vallen in drie categorieën:

• Veilige wijzigingen. Tags en de power state worden toegepast op een draaiende server, en het plan toont deze als update in-place.

• Herinstallatie van het besturingssysteem. Het wijzigen van os_name, soft_name, root_pass of ssh_key herinstalleert het besturingssysteem op dezelfde server, wat betekent dat alle gegevens op de schijf verloren gaan.

• Een nieuwe bestelling. Het wijzigen van preset_name, location_name, traffic_plan_name of deploy_period betekent dat de vorige server wordt geannuleerd en een nieuwe wordt besteld, waardoor je opnieuw in rekening wordt gebracht. Het plan markeert dergelijke wijzigingen als forces replacement.

Stap 8. De resources verwijderen¶

terraform destroy

terraform destroy verwijdert alle resources die in de huidige Terraform state voor deze configuratie staan. Terraform toont de lijst met te verwijderen resources en vraagt om bevestiging. Voer yes in en druk op Enter.

Als je slechts één resource wilt verwijderen, kun je deze specificeren met -target. Bijvoorbeeld:

terraform destroy -target=hostkey_server.web

Hier is web de naam van de resource uit het resource "hostkey_server" "web" blok, niet de server-ID uit het control panel.

Een andere optie is om de resource uit de .tf bestanden te verwijderen en het volgende uit te voeren:

terraform apply

Terraform ziet dat de resource niet langer aanwezig is in de configuratie en zal deze uit de infrastructuur verwijderen.

De annulering van de service wordt uitgevoerd via Invapi, en de methode van annulering wordt bepaald door de parameter cancellation_type: 1 annuleert de service onmiddellijk, terwijl 0 deze annuleert aan het einde van de betaalde periode.

Bestaande servers importeren¶

Servers die via het control panel zijn besteld, kunnen onder Terraform-beheer worden gebracht. De identifier wordt overgenomen uit de ID kolom in de serverlijst:

terraform import hostkey_server.web 19463

Na de import bevat de state de live data, namelijk de identifier, het adres, de status en de power state. Argumenten die bij het bestellen zijn gebruikt, worden niet overgenomen van het control panel, dus deze moeten handmatig in de configuratie worden beschreven. De eerste terraform apply na een import leidt niet tot een herinstallatie.

Probleemoplossing¶