Terraform Docker: een complete gids

Ik heb ontelbare uren besteed aan het handmatig beheren van Docker-containers in ontwikkel- en productieomgevingen. Niet-overeenkomende configuraties, wegdrijvende states en onzekerheid of mijn lokale setup wel overeenkwam met productie teisterden elke deployment. Toen ik de Docker-provider van Terraform ontdekte, veranderde alles.

In deze tutorial laat ik je zien hoe je Terraform integreert met Docker om reproduceerbare, versiebeheerbare infrastructuur te maken. Je leert hoe je containers inricht, netwerken en volumes beheert, resourcebeperkingen toepast en state binnen je team onderhoudt.

Of je nu buildservers beheert of microservices orkestreert, pak je terminal erbij en laten we transformeren hoe je Docker-infrastructuur aanpakt.

Als je nieuw bent met Docker, raad ik aan om te beginnen met onze cursus Introductie tot Docker.

Wat is de Terraform-Docker-integratie?

Terraform is een infrastructure-as-code-tool die levenscycli van resources beheert via een declaratieve workflow. In plaats van losse Docker-commando's uit te voeren, definieer je de gewenste infrastructuurtoestand in configuratiebestanden. Terraform voert vervolgens een plan-apply-destroy-lifecycle uit: het berekent de vereiste wijzigingen, toont een preview en past ze pas toe na goedkeuring.

De Terraform Docker-provider fungeert als vertaallaag tussen HashiCorp Configuration Language (HCL)-code en de Docker API. Wanneer je resource “docker_container" in een configuratie schrijft, zet de provider die declaratie om naar de juiste Docker API-calls. Dankzij deze abstractie kun je Docker-resources beheren met dezelfde workflow als cloudinfrastructuur.

Hierin verschilt Terraform van Docker Compose.

Compose beheert containers projectmatig met YAML-bestanden, maar houdt geen statebestand bij van wat er daadwerkelijk bestaat. 

Terraform daarentegen registreert elke resource die het aanmaakt in terraform.tfstate, waardoor het drift tussen mijn configuratie en de werkelijkheid kan detecteren. Als iemand handmatig een container wijzigt, merkt Terraform dat en kan het die herstellen naar de gedefinieerde staat.

Deze aanpak blinkt uit in verschillende scenario's:

• Voor reproduceerbare buildservers kun je de volledige omgeving met één commando vernietigen en opnieuw opbouwen, wat consistentie garandeert. 
• In testomgevingen kun je voor elke testrun geïsoleerde infrastructuur opzetten. 
• Voor immutable deployments vervang je containers volledig in plaats van ze ter plekke te wijzigen, waardoor deployrisico's afnemen.

Vereisten en installatie

Voordat we in Terraform-configuraties duiken, controleren we of de vereiste tools zijn geïnstalleerd en goed geconfigureerd.

Voldoen aan systeemvereisten

Controleer eerst of Docker Engine op je machine draait. 

• Linux: Controleer met docker ps

• macOS of Windows: Zorg dat Docker Desktop is geïnstalleerd en draait

De Terraform-provider heeft toegang nodig tot de Docker-daemon, dus controleer of jouw gebruiker toestemming heeft voor de Unix-socket op /var/run/docker.sock op Linux of de named pipe op Windows.

Installeer vervolgens de Terraform CLI via de officiële website van HashiCorp. Terraform installeren verschilt per besturingssysteem:

• Linux: Download het juiste pakket of gebruik de pakketbeheerder van je distributie. 

• macOS: Gebruik Homebrew. Installeer eerst de HashiCorp-tap met brew tap hashicorp/tap en installeer vervolgens Terraform met brew install hashicorp/tap/terraform. 

• Windows: Download de binary van hashicorp.com en voeg die toe aan je PATH, of gebruik Chocolatey: choco install terraform. 

Controleer na installatie met terraform version. 

Met Docker en Terraform geverifieerd, is de volgende stap het organiseren van de projectbestanden voor onderhoudbaarheid.

De projectstructuur configureren

Terraform-projecten profiteren van een duidelijke en gestructureerde aanpak. Meestal maak ik een aparte map voor mijn Terraform-project en initialiseer ik versiebeheer:

mkdir terraform-docker-project
cd terraform-docker-project
git initMogelijk gemaakt door

Versiebeheer is cruciaal voor infrastructure-as-code. Elke wijziging aan de Docker-infrastructuur moet worden bijgehouden, gereviseerd en terug te draaien zijn. Gewoonlijk voeg ik de werkdirectory en statebestanden van Terraform toe aan het .gitignore-bestand om ze uit versiebeheer te houden:

.terraform/
*.tfstate
*.tfstate.backup
.terraform.lock.hclMogelijk gemaakt door

Tot slot maak ik een leeg main.tf-bestand aan waarin ik mijn infrastructuur definieer. Dit bestand bevat de providerconfiguratie en de resourcedefinities.

Terraform Docker-provider en kernresources

Met de projectstructuur op orde is het tijd om de Docker-provider te configureren en resources te definiëren.

De Docker-provider initialiseren

Begin met het toevoegen van de providerconfiguratie aan main.tf:

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

provider "docker" {
  host = "unix:///var/run/docker.sock"
}Mogelijk gemaakt door

Het blok required_providers specificeert waar Terraform de providerplug-in moet downloaden. Met versiebeperkingen (~> 3.0) sta je minor updates toe terwijl je breaking changes voorkomt. Voor externe Docker-hosts kun je de parameter host aanpassen naar bijvoorbeeld tcp://192.168.1.100:2376.

Voer nu terraform init uit in de projectroot. Dit downloadt de Docker-providerplug-in en slaat deze op in .terraform/providers/. De opdracht geeft de exacte geïnstalleerde versie weer en Terraform maakt een lockbestand aan om consistente providerversies binnen mijn team te waarborgen.

Containerimages beheren

Met de provider geïnitialiseerd is de volgende stap het definiëren van de containerimages. Voordat je containers maakt, moet je de images beheren die ze gebruiken, dus definieer je een image-resource:

resource "docker_image" "nginx" {
  name         = "nginx:1.29"
  keep_locally = true
}Mogelijk gemaakt door

Voeg deze resource direct na het providerblok toe. De parameter keep_locally is belangrijk omdat die voorkomt dat Terraform het image verwijdert wanneer ik terraform destroy draai. Dit is handig als meerdere containers hetzelfde image delen of wanneer ik gecachte images tussen deployments wil behouden.

Voor productiedeployments kun je images vastpinnen op hun SHA256-digest om immutabiliteit te garanderen:

resource "docker_image" "nginx" {
 name = "nginx@sha256:b60f25eb5acdd79172de1a289891d9cfe4fc3669daddeeb68619240cbe839d9f"
}Mogelijk gemaakt door

De digest is te verkrijgen uit de container registry. Voor Docker Hub-images zoals nginx vind je die op de officiële Docker-website onder het gedeelte Tags. Met digests garandeer je dat exact hetzelfde image-binary elke keer wordt uitgerold, zelfs als iemand een nieuw image met dezelfde tag pusht.

Docker-containers inrichten

Zodra images zijn gedefinieerd, is de volgende stap het maken van containers die ernaar verwijzen:

resource "docker_container" "web" {
  name  = "nginx-web"
  image = docker_image.nginx.image_id

  ports {
    internal = 80
    external = 8080
  }

  env = [
    "NGINX_HOST=example.com",
    "NGINX_PORT=80"
  ]
}Mogelijk gemaakt door

Het image wordt verwezen via docker_image.nginx.image_id. Dit creëert een impliciete afhankelijkheid: Terraform probeert de container niet te maken voordat het image bestaat. Het blok ports mappt poort 80 intern van de container naar poort 8080 op mijn host, gelijk aan docker run -p 8080:80.

Omgevingsvariabelen zet je in de lijst env als strings. Terraform zal de container opnieuw creëren als parameters veranderen, zodat de draaiende infrastructuur altijd overeenkomt met de configuratie.

Voer op dit punt terraform plan uit om te zien wat Terraform zal aanmaken, en daarna terraform apply om de infrastructuur te provisionen. Terraform maakt het image en de container. Je kunt dit verifiëren in Docker Desktop of met docker ps in de terminal.

Netwerken, opslag en resource-limieten in Terraform

Nu je een basiscontainer hebt draaien en de kernworkflow begrijpt, gaan we de infrastructuur uitbreiden met productieklare features. De volgende secties bouwen hierop voort met netwerken, persistente opslag en resourcebeperkingen — allemaal essentieel voor deployments in de echte wereld

Netwerken beheren

Om communicatie tussen containers mogelijk te maken en toch isolatie te behouden, is het aanmaken van dedicated netwerken essentieel. Zo maak je geïsoleerde netwerken om connectiviteit te regelen. Voeg de volgende resource toe aan het main.tf-bestand:

resource "docker_network" "app_network" {
  name   = "application_net"
  driver = "bridge"
}Mogelijk gemaakt door

Voeg nu een tweede container toe die dit netwerk gebruikt. Plaats dit na de web-container:

resource "docker_container" "api" {
  name  = "api-server"
  image = docker_image.nginx.image_id

  networks_advanced {
    name = docker_network.app_network.name
  }
}Mogelijk gemaakt door

Dit maakt een dedicated bridge-netwerk en koppelt de api-container eraan. Containers op hetzelfde netwerk kunnen communiceren met hun containernamen als hostnamen — ideaal voor microservices-architecturen. 

Verifieer de netwerkisolatie met docker network inspect application_net en controleer dat alleen de bedoelde containers verbonden zijn. Zorg dat je dit commando uitvoert nadat je de resources hebt aangemaakt met terraform plan en terraform apply.

Met netwerken geconfigureerd voor communicatie tussen containers is de volgende cruciale stap datapersistentie.

Persistente volumes configureren

Voor data die containerherstarts moet overleven, voeg je volumeresources toe. Plaats deze vóór de containerdefinities:

resource "docker_volume" "db_data" {
  name = "postgres_data"
}Mogelijk gemaakt door

Voeg nu een databasecontainer toe die dit volume gebruikt:

resource "docker_container" "database" {
  name  = "postgres"
  image = "postgres:15"

 env = [
    "POSTGRES_PASSWORD=mysecretpassword"
  ]

  volumes {
    volume_name    = docker_volume.db_data.name
    container_path = "/var/lib/postgresql/data"
  }
}Mogelijk gemaakt door

Beheerde volumes zoals deze worden door Docker aangemaakt en beheerd, opgeslagen in de datadirectory van Docker. Voor het delen van configuratiebestanden vanaf de host gebruik je bind mounts door host_path te specificeren in plaats van volume_name.

volumes {
  host_path      = "/opt/app/config"
  container_path = "/etc/app/config"
  read_only      = true
}Mogelijk gemaakt door

Nadat je hebt gewaarborgd dat data containerherstarts overleeft, is het minstens zo belangrijk te voorkomen dat één container alle systeemresources opslokt.

Resourcebeperkingen instellen

Naast opslag is het cruciaal voor systeemstabiliteit om te beheersen hoeveel CPU en geheugen elke container mag gebruiken. Om te voorkomen dat containers buitensporig veel resources verbruiken, pas je limieten toe.

Hoewel Docker toestaat om sommige resource-limieten in-place te updaten, vereist het declaratieve model van Terraform vaak het vervangen van de container om te borgen dat de state overeenkomt met je configuratie. Om downtime tijdens deze vervanging te voorkomen, gebruiken we de create_before_destroy-lifecycle-regel. 

Belangrijk: We moeten het vaste argument name verwijderen om naamconflicten tijdens de vervanging te voorkomen. Een optie is om in plaats daarvan het argument name_prefix te gebruiken.

resource "docker_container" "api" {
  name_prefix       = "api-server-"
  image      = docker_image.nginx.image_id
  memory     = 512
  cpu_shares = 1024

  networks_advanced {
    name = docker_network.app_network.name
  }

 lifecycle {
    create_before_destroy = true
  }
}Mogelijk gemaakt door

De parameter memory beperkt RAM in megabytes. De parameter cpu_shares werkt anders: dit is een relatieve weging bij CPU-contentie. Een container met 1024 shares krijgt tweemaal zoveel CPU-tijd als een container met 512 shares, maar alleen wanneer de host onder belasting staat. 

Voor harde CPU-limieten kun je ook cpu_set gebruiken om containers aan specifieke CPU-cores te pinnen:

cpu_set = "0,1"
}Mogelijk gemaakt door

Valideer deze beperkingen met docker inspect background-worker --format='{{.HostConfig.Memory}} {{.HostConfig.CpuShares}} en controleer of de waarden Memory en NanoCpus overeenkomen met de configuratie. 

Ook hier geldt, zoals hierboven beschreven, dat je eerst terraform plan en terraform apply moet draaien om de resources aan te maken.

Op dit punt bevat het main.tf-bestand de providerconfiguratie, één image, één netwerk, één volume en drie containers met uiteenlopende configuraties. 

Variabelen, modules en secrets in Terraform

Als infrastructuur groeit, worden hardcoded waarden onflexibel. Deze sectie laat zien hoe je de configuratie herbruikbaar maakt met variabelen, modules en een goede omgang met secrets.

Invoervariabelen gebruiken

De eerste stap om configuraties flexibel te maken is het uitnemen van hardcoded waarden naar variabelen die je eenvoudig kunt wijzigen zonder de hoofdcode aan te passen. Dit doe je door een nieuw bestand variables.tf in dezelfde map te maken:

variable "web_port" {
  description = "External port for web container"
  type        = number
  default     = 8080

  validation {
    condition     = var.web_port > 1024 && var.web_port < 65535
    error_message = "Port must be between 1024 and 65535."
  }
}Mogelijk gemaakt door

Werk nu de webcontainer in main.tf bij om deze variabele te gebruiken:

resource "docker_container" "web" {
  name  = "nginx-web"
  image = docker_image.nginx.image_id

  ports {
    internal = 80
    external = var.web_port
  }

  env = [
    "NGINX_HOST=example.com",
    "NGINX_PORT=80"
  ]
}Mogelijk gemaakt door

Het validatieblok voorkomt het gebruik van geprivilegieerde poorten. Om de standaardwaarde te overschrijven, maak je een terraform.tfvars-bestand:

web_port = 9000Mogelijk gemaakt door

Bij het uitvoeren van terraform apply leest Terraform automatisch waarden uit dit bestand. Of geef waarden door via de commandoregel: terraform apply -var="web_port=9000".

Herbruikbare modules maken

Variabelen lossen het probleem van hardcoded waarden op, maar wat als je hetzelfde volledige patroon meerdere keren moet uitrollen, inclusief al zijn resources? 

Dit is waar modules excelleren. Zie een module als een blauwdruk die al die losse onderdelen bundelt tot één pakket, zodat je die complete setup als één geheel kunt 'stempelen'.

Begin met het maken van een modulemapstructuur:

mkdir -p modules/web-appMogelijk gemaakt door

Maak nu het bestand modules/web-app/variables.tf en voeg het volgende toe:

variable "environment" {
  description = "Environment name"
  type        = string
}

variable "port" {
  description = "External port"
  type        = number
}Mogelijk gemaakt door

Maak vervolgens een main-bestand modules/web-app/main.tf met deze resource:

resource "docker_container" "app" {
  name  = "app-${var.environment}"
  image = var.image_id

  ports {
    internal = 80
    external = var.port
  }
}Mogelijk gemaakt door

Maak tot slot een outputs-bestand modules/web-app/outputs.tf, dat vooral wordt gebruikt om in de terminal de gewenste waarde te tonen na terraform apply:

output "container_ip" {
  value       = docker_container.app.network_data[0].ip_address
  description = "IP address of the application container"
}Mogelijk gemaakt door

Na het toevoegen van de moduledefinities voer je terraform init uit om de modules te installeren en daarna terraform apply om beide containers vanuit dezelfde template te maken. Je zou alle resources in Docker Desktop moeten kunnen zien.

Met herbruikbare infrastructuurpatronen via modules is er nog één cruciaal aspect van configuratiebeheer: het veilig omgaan met gevoelige informatie zoals wachtwoorden en API-sleutels.

Omgaan met gevoelige data

Gevoelige waarden, zoals databasewachtwoorden, moet je niet hardcoden. In plaats daarvan kun je het bestand variables.tf gebruiken en sensitive = true instellen:

variable "db_password" {
  description = "Database root password"
  type        = string
  sensitive   = true
}Mogelijk gemaakt door

Werk nu de databasecontainer in main.tf bij om te verwijzen naar het databasewachtwoord:

resource "docker_container" "database" {
  name  = "postgres"
  image = "postgres:15"

  env = [
    "POSTGRES_PASSWORD=${var.db_password}"
  ]

  volumes {
    volume_name    = docker_volume.db_data.name
    container_path = "/var/lib/postgresql/data"
  }
}Mogelijk gemaakt door

Zet het wachtwoord niet in terraform.tfvars als hardcoded waarde, maar stel het in als omgevingsvariabele:

export TF_VAR_db_password="your-secure-password"
terraform applyMogelijk gemaakt door

De vlag sensitive = true voorkomt dat Terraform de waarde in de console-uitvoer toont. 

Deze waarden worden echter in platte tekst opgeslagen in terraform.tfstate, dus om dit bestand te beveiligen kunnen we remote backends met encryptie gebruiken. Laten we bekijken hoe je dit doet.

Terraform-statebeheer en CI/CD-integratie

Deze sectie behandelt statemechanismen en automatiseringsworkflows die essentieel zijn voor productiedeployments. Maar voordat je automatisering implementeert, is het belangrijk te begrijpen hoe Terraform je infrastructuur bijhoudt via het statebestand. 

State-mechanismen begrijpen

State is de basis van Terraform's vermogen om infrastructuur te beheren. Het bestand terraform.tfstate koppelt configuratie aan echte Docker-container-ID's en resource-attributen. Bij terraform apply vergelijkt Terraform deze state met de configuratie en berekent het de minimale benodigde wijzigingen.

Inspecteer de huidige state met terraform show, dat elke beheerde resource toont. Voor teams zorgen lokale statebestanden voor problemen, conflicten en mogelijk dataverlies. De oplossing is remote backends.

Voor Docker-gerichte workflows zonder cloudinfrastructuur is de gratis laag van Terraform Cloud ideaal. Voeg een backend-blok toe aan de sectie terraform in main.tf:

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
  
  backend "remote" {
    organization = "your-org-name"
    
    workspaces {
      name = "docker-infrastructure"
    }
  }
}Mogelijk gemaakt door

Maak een gratis account aan op de website van Terraform. Voer daarna terraform login uit om te authenticeren met de verstrekte token en vervolgens terraform init om de state te migreren. Dit biedt statelocking in een remote workspace en team­samenwerking zonder cloudinfrastructuur. 

Het is echter ook mogelijk een remote backend te maken in cloudproviders zoals AWS of GCP.

Workflows automatiseren

Met statebeheer geconfigureerd en op afstand opgeslagen, is de infrastructuur klaar voor teamsamenwerking. Het laatste onderdeel is het automatiseren van het deploymentproces via CI/CD-pipelines, zodat wijzigingen consistent en reviewbaar zijn.

Maak eerst .github/workflows/terraform.yml aan:

name: Terraform Docker Deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        
      - name: Terraform Init
        run: terraform init
        
      - name: Terraform Plan
        if: github.event_name == 'pull_request'
        run: terraform plan
        
      - name: Terraform Apply
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: terraform apply -auto-approveMogelijk gemaakt door

Deze workflow draait terraform plan bij elke pull request en laat reviewers zien welke infrastructuurwijzigingen zullen plaatsvinden. Wanneer wijzigingen naar main worden gemerged, voert terraform apply automatisch uit, zodat elke infrastructuurwijziging hetzelfde reviewproces doorloopt als codewijzigingen.

Problemen met Terraform Docker oplossen

Zelfs met zorgvuldige configuratie kunnen er problemen optreden. Inzicht in veelvoorkomende problemen en wanneer je alternatieven moet overwegen, helpt bij betere architectuurkeuzes. 

“Permission denied”

De meest voorkomende fout op Linux is "permission denied" bij het verbinden met de Docker-socket. Dit gebeurt wanneer de gebruiker geen toestemming heeft voor /var/run/docker.sock. Los dit op door de gebruiker toe te voegen aan de groep docker:

sudo usermod -aG docker $USERMogelijk gemaakt door

Log daarna uit en weer in.

WSL2-verbindingsproblemen

Op Windows met WSL2 ontstaan verbindingsproblemen doordat het socketpad anders is. Zorg dat in Docker Desktop de instelling "Expose daemon on tcp://localhost:2375 without TLS" is ingeschakeld en werk dan de provider in main.tf bij:

provider "docker" {
  host = "tcp://localhost:2375"
}Mogelijk gemaakt door

Authenticatiefouten bij private registries

Voor private Docker-registries voeg je authenticatie toe aan het providerblok, definieer je credentials als variabelen en stel je ze in via omgevingsvariabelen om problemen door hardcoding te voorkomen.

hclprovider "docker" {
  host = "unix:///var/run/docker.sock"
  
  registry_auth {
    address  = "registry.mycompany.com"
    username = var.registry_username
    password = var.registry_password
  }
}Mogelijk gemaakt door

Alternatieven voor Terraform

Naast troubleshooting is het net zo waardevol om te begrijpen wanneer andere tools geschikter zijn dan Terraform voor jouw specifieke use-case.

Terraform vs Kubernetes

Kubernetes biedt veel geavanceerdere orkestratiefuncties: 

• Zelfherstel
• Geavanceerde scheduling
• Service discovery
• Ingebalanceerde load balancing

Voor complexe multinode-deployments met hoge beschikbaarheid is Kubernetes de betere keuze. Terraform kan Kubernetes-infrastructuur provisionen, terwijl Helm of Kubernetes-manifests de applicatiedeployments afhandelen.

Terraform vs Ansible

Ansible blinkt uit in configuratiemanagement binnen containers. Waar Terraform infrastructuur provisiont, beheert Ansible softwareconfiguratie en pakketinstallaties. De tools werken vaak samen: Terraform maakt Docker-containers, daarna configureert Ansible de applicaties die erin draaien.

Terraform vs Docker Compose

Voor eenvoudige locale ontwikkelomgevingen blijft Docker Compose de meest pragmatische keuze. Terraform blinkt uit bij reproduceerbare deployments over omgevingen heen en wanneer integratie met andere infrastructuurcomponenten nodig is.

Om je te helpen kiezen, heb ik de belangrijkste verschillen samengevat in deze tabel:

Als je op zoek bent naar een tool om Docker te vervangen, bekijk dan onze gids met de beste Docker-alternatieven.

Conclusie

Docker onder het lifecyclebeheer van Terraform brengen, verandert containerdeployments van handmatige procedures in reproduceerbare, versiebeheerbare infrastructuur. In deze tutorial liet ik stap voor stap zien hoe je een complete infrastructuur opbouwt, beginnend met een provider en één container, en vervolgens uitbreidend met netwerken, opslag, variabelen, modules en automatisering.

Het belangrijkste onderscheid is dat Terraform het provisionen, aanmaken, updaten en vernietigen van resources afhandelt op basis van declaratieve configuratie. Volledige orkestratie met automatische schaalvergroting en zelfherstel vereist tools zoals Kubernetes of Docker Swarm. Terraform kan deze orkestrators provisionen, maar vervangt ze niet.

Als volgende stap, bekijk de officiële Terraform Registry-documentatie voor de Docker-provider voor geavanceerde resource-opties zoals Docker-services voor Swarm, secretbeheer en pluginconfiguraties.

Wil je hands-on aan de slag met containers? Schrijf je dan in voor onze interactieve skill track Containerization and Virtualization with Docker and Kubernetes.