El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia

HOME

Introducción

Antes de poder escribir y ejecutar código Terraform, necesitas tener la herramienta instalada en tu máquina. En esta lección aprenderás a instalar Terraform en los tres sistemas operativos más comunes (Linux, macOS y Windows), a verificar que la instalación funciona correctamente y a gestionar múltiples versiones de Terraform cuando trabajas en proyectos que requieren versiones distintas.

Al finalizar esta lección tendrás Terraform funcionando en tu máquina y estarás listo para escribir tu primera configuración.

Requisitos del Sistema

Terraform es una aplicación de línea de comandos muy ligera. Sus requisitos son mínimos:

Requisitos de hardware

CPU: Cualquier procesador moderno (x86-64 o ARM64)
RAM: Mínimo 512 MB libres (Terraform es muy eficiente con la memoria)
Disco: El binario de Terraform ocupa aproximadamente 70-100 MB. Los proveedores descargados pueden ocupar entre 50 MB y varios GB dependiendo de cuántos instales.

Requisitos de software

Sistema operativo: Linux (kernel 2.6+), macOS 10.12+, Windows Server 2012+ o Windows 10+
Arquitecturas soportadas: amd64 (x86-64), arm64 (Apple Silicon, Raspberry Pi 64-bit)
Dependencias: Ninguna. Terraform se distribuye como un único binario estático que incluye todo lo necesario.
Conexión a internet: Necesaria durante terraform init para descargar los proveedores.

Acceso a la terminal

Terraform es una herramienta de línea de comandos. Necesitarás:

Linux/macOS: Terminal bash, zsh u otro shell compatible con POSIX
Windows: PowerShell, Command Prompt o Windows Subsystem for Linux (WSL2)

Instalación en Linux

2.1 Ubuntu y Debian (usando apt)

Este es el método recomendado para sistemas basados en Debian, ya que mantiene Terraform actualizable mediante el gestor de paquetes.

# Paso 1: Instalar las dependencias necesarias para agregar el repositorio
sudo apt-get update && sudo apt-get install -y gnupg software-properties-common

# Paso 2: Descargar e instalar la clave GPG de HashiCorp
# Esto verifica la autenticidad de los paquetes que descargamos
wget -O- https://apt.releases.hashicorp.com/gpg | \
  gpg --dearmor | \
  sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null

# Paso 3: Verificar la huella de la clave GPG (opcional pero recomendado)
gpg --no-default-keyring \
  --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg \
  --fingerprint

# Paso 4: Agregar el repositorio oficial de HashiCorp a las fuentes de apt
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
https://apt.releases.hashicorp.com $(lsb_release -cs) main" | \
sudo tee /etc/apt/sources.list.d/hashicorp.list

# Paso 5: Actualizar los índices de paquetes e instalar Terraform
sudo apt-get update && sudo apt-get install terraform

Explicación de cada paso:

gnupg y software-properties-common son herramientas para gestionar claves de firma y repositorios externos.
La clave GPG garantiza que los paquetes vienen realmente de HashiCorp y no han sido manipulados.
lsb_release -cs devuelve el nombre en clave de tu distribución (por ejemplo, jammy para Ubuntu 22.04 o bookworm para Debian 12).

Para instalar una versión específica:

# Listar versiones disponibles
apt-cache policy terraform

# Instalar una versión concreta
sudo apt-get install terraform=1.9.0-1

2.2 CentOS, RHEL y Fedora (usando yum/dnf)

# Paso 1: Instalar yum-utils para gestionar repositorios externos
sudo yum install -y yum-utils

# Paso 2: Agregar el repositorio oficial de HashiCorp
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

# Paso 3: Instalar Terraform
sudo yum -y install terraform

# En Fedora o sistemas con dnf, usa dnf en lugar de yum:
sudo dnf install -y yum-utils
sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
sudo dnf -y install terraform

2.3 Instalación manual en Linux (cualquier distribución)

Si prefieres no usar un gestor de paquetes o usas una distribución diferente:

# Paso 1: Descargar el binario de Terraform
# Visita https://releases.hashicorp.com/terraform/ para ver todas las versiones
# Aquí usamos la versión 1.9.0 para amd64 como ejemplo
wget https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_linux_amd64.zip

# Paso 2: Verificar la integridad del archivo descargado (recomendado)
# Descarga el archivo de checksums
wget https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_SHA256SUMS
# Verifica que el hash coincide
sha256sum -c terraform_1.9.0_SHA256SUMS --ignore-missing

# Paso 3: Descomprimir el archivo
unzip terraform_1.9.0_linux_amd64.zip

# Paso 4: Mover el binario a un directorio en el PATH del sistema
sudo mv terraform /usr/local/bin/

# Paso 5: Dar permisos de ejecución (normalmente ya los tiene)
sudo chmod +x /usr/local/bin/terraform

# Paso 6: Limpiar archivos temporales
rm terraform_1.9.0_linux_amd64.zip terraform_1.9.0_SHA256SUMS

Instalación en macOS

3.1 Con Homebrew (recomendado)

Homebrew es el gestor de paquetes más popular para macOS. Si no lo tienes instalado, puedes instalarlo con:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Una vez que tienes Homebrew, instalar Terraform es tan sencillo como:

# Instalar Terraform con Homebrew
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

# Para actualizar Terraform a la última versión en el futuro:
brew update
brew upgrade hashicorp/tap/terraform

El comando brew tap hashicorp/tap agrega el repositorio oficial de HashiCorp a Homebrew, lo que garantiza que obtienes siempre las versiones publicadas oficialmente.

3.2 Instalación manual en macOS

Si prefieres no usar Homebrew o necesitas una versión específica:

# Paso 1: Descargar el binario para macOS
# Para Mac con chip Intel (amd64):
curl -O https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_darwin_amd64.zip

# Para Mac con chip Apple Silicon M1/M2/M3 (arm64):
curl -O https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_darwin_arm64.zip

# Paso 2: Descomprimir
unzip terraform_1.9.0_darwin_amd64.zip

# Paso 3: Mover el binario al PATH
sudo mv terraform /usr/local/bin/

# Paso 4: En macOS Catalina o posterior, quitar la cuarentena de Gatekeeper
sudo xattr -d com.apple.quarantine /usr/local/bin/terraform

# Paso 5: Verificar
terraform version

Nota sobre Apple Silicon: Si tienes un Mac con chip M1, M2 o M3, asegúrate de descargar la versión darwin_arm64. Aunque la versión darwin_amd64 también funciona mediante Rosetta 2, la versión nativa ARM64 es significativamente más rápida.

Instalación en Windows

4.1 Con Chocolatey (recomendado)

Chocolatey es el gestor de paquetes más popular para Windows. Para instalarlo, abre PowerShell como administrador y ejecuta:

Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Una vez instalado Chocolatey, instala Terraform:

# Instalar Terraform con Chocolatey (ejecutar PowerShell como administrador)
choco install terraform

# Para instalar una versión específica:
choco install terraform --version=1.9.0

# Para actualizar en el futuro:
choco upgrade terraform

4.2 Instalación manual en Windows

# Paso 1: Descargar el binario desde PowerShell
$url = "https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_windows_amd64.zip"
$output = "$env:TEMP\terraform.zip"
Invoke-WebRequest -Uri $url -OutFile $output

# Paso 2: Crear un directorio para Terraform
New-Item -ItemType Directory -Force -Path "C:\Program Files\Terraform"

# Paso 3: Descomprimir el archivo
Expand-Archive -Path $output -DestinationPath "C:\Program Files\Terraform" -Force

# Paso 4: Limpiar el archivo temporal
Remove-Item $output

Después de esto, necesitas agregar C:\Program Files\Terraform al PATH del sistema:

Pulsa Win + R, escribe sysdm.cpl y pulsa Enter
Ve a la pestaña "Opciones avanzadas" > "Variables de entorno"
En "Variables del sistema", selecciona Path y pulsa "Editar"
Pulsa "Nuevo" y escribe C:\Program Files\Terraform
Pulsa "Aceptar" en todas las ventanas
Abre una nueva ventana de PowerShell o Command Prompt y ejecuta terraform version

Nota: También puedes usar Terraform en Windows mediante WSL2 (Windows Subsystem for Linux), lo que te permite usar los comandos de Linux descritos en la sección anterior. Muchos desarrolladores prefieren esta opción para tener un entorno más consistente con los servidores de producción.

Verificación de la Instalación

Una vez instalado Terraform por cualquiera de los métodos anteriores, verifica que funciona correctamente:

# Comando básico para verificar la versión instalada
terraform version

Deberías ver una salida similar a esta:

Terraform v1.9.0
on linux_amd64

Si ves este mensaje, ¡Terraform está correctamente instalado! Si ves un error como command not found, revisa la sección de configuración del PATH a continuación.

Comandos de diagnóstico adicionales

# Ver la ruta donde está instalado el binario
which terraform        # Linux/macOS
where terraform        # Windows (Command Prompt)
Get-Command terraform  # Windows (PowerShell)

# Ver información detallada de la versión
terraform version -json

La salida de terraform version -json es útil en scripts de automatización porque devuelve la información en formato JSON:

{
  "terraform_version": "1.9.0",
  "platform": "linux_amd64",
  "provider_selections": {},
  "terraform_outdated": false
}

Configuración del PATH

Si después de instalar Terraform el comando no es reconocido, es porque el directorio donde está el binario no está en el PATH del sistema.

En Linux y macOS

El PATH es una variable de entorno que lista los directorios donde el sistema busca ejecutables. Para agregar un directorio permanentemente:

# Para bash (archivo ~/.bashrc o ~/.bash_profile):
echo 'export PATH="$PATH:/ruta/donde/esta/terraform"' >> ~/.bashrc
source ~/.bashrc  # Recargar la configuración

# Para zsh (archivo ~/.zshrc) - el shell por defecto en macOS desde Catalina:
echo 'export PATH="$PATH:/ruta/donde/esta/terraform"' >> ~/.zshrc
source ~/.zshrc

# Verificar que el PATH se actualizó correctamente
echo $PATH | tr ':' '\n' | grep terraform

Para diagnosticar dónde está Terraform:

# Buscar el binario de terraform en el sistema
find /usr -name "terraform" 2>/dev/null
find /opt -name "terraform" 2>/dev/null
find $HOME -name "terraform" 2>/dev/null

Gestión de Múltiples Versiones con tfenv

En proyectos reales es común trabajar con diferentes versiones de Terraform: algunos proyectos heredados pueden requerir Terraform 0.14 mientras que los proyectos nuevos usan la versión 1.9. La herramienta tfenv resuelve este problema.

¿Qué es tfenv?

tfenv es un gestor de versiones para Terraform, similar a nvm para Node.js o pyenv para Python. Permite:

Instalar múltiples versiones de Terraform
Cambiar entre versiones de forma instantánea
Establecer la versión por proyecto mediante un archivo .terraform-version

Instalación de tfenv en Linux/macOS

# Paso 1: Clonar el repositorio de tfenv
git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv

# Paso 2: Agregar tfenv al PATH
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Para zsh:
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Paso 3: Verificar que tfenv está instalado
tfenv --version

Uso básico de tfenv

# Listar todas las versiones disponibles para instalar
tfenv list-remote

# Instalar una versión específica
tfenv install 1.9.0

# Instalar la última versión estable
tfenv install latest

# Instalar la última versión que cumple un criterio (útil con versiones de restricción)
tfenv install latest:^1.8

# Listar las versiones instaladas en tu sistema
tfenv list

# Cambiar a una versión específica de forma global
tfenv use 1.9.0

# Establecer la versión para un proyecto específico
# Esto crea un archivo .terraform-version en el directorio actual
echo "1.9.0" > .terraform-version

# Cuando estés en ese directorio, tfenv usará automáticamente esa versión
terraform version  # Mostrará 1.9.0

El archivo .terraform-version

Cuando tienes un archivo .terraform-version en el directorio de tu proyecto, tfenv detecta automáticamente qué versión usar:

# Contenido del archivo .terraform-version (solo el número de versión)
1.9.0

Esto es especialmente útil cuando colaboras en equipo: todos los miembros usarán exactamente la misma versión de Terraform, evitando el clásico problema de "en mi máquina funciona".

Consejo profesional: Guarda el archivo .terraform-version en tu repositorio Git junto con el resto del código. Así, cualquier persona que clone el repositorio y tenga tfenv instalado usará automáticamente la versión correcta.

Tabla Comparativa: Métodos de Instalación por Sistema Operativo

Método	Sistema Operativo	Ventajas	Desventajas
apt (repositorio HashiCorp)	Ubuntu/Debian	Actualizaciones automáticas con `apt upgrade`, integrado con el sistema	Solo en distribuciones Debian
yum/dnf (repositorio HashiCorp)	CentOS/RHEL/Fedora	Actualizaciones automáticas, integrado con el sistema	Solo en distribuciones RPM
Binario manual	Linux (cualquier distro)	Funciona en cualquier distribución, control total de la versión	Actualización manual necesaria
Homebrew	macOS	Simple, actualizaciones con `brew upgrade`, ampliamente adoptado	Requiere instalar Homebrew previamente
Binario manual	macOS	Control total, sin dependencias externas	Actualización manual, gestión de PATH
Chocolatey	Windows	Simple, similar a apt/brew, actualizaciones automáticas	Requiere permisos de administrador
Binario manual	Windows	Sin dependencias externas	Configuración de PATH manual, más pasos
tfenv	Linux/macOS	Gestión de múltiples versiones, ideal para equipos, `.terraform-version` por proyecto	Capa adicional de abstracción
WSL2 + apt	Windows	Entorno Linux en Windows, compatible con scripts de CI/CD	Requiere configurar WSL2 primero

Ejercicio Práctico: Instalar y Verificar Terraform

Enunciado

Tu tarea es instalar Terraform en tu sistema operativo, verificar que funciona correctamente y recopilar información de diagnóstico.

Pasos del ejercicio

Paso 1: Instala Terraform usando el método más adecuado para tu sistema operativo (sigue las instrucciones de las secciones anteriores).

Paso 2: Abre una terminal y ejecuta los siguientes comandos. Anota la salida de cada uno:

# 1. Verificar que Terraform está instalado y ver su versión
terraform version

# 2. Ver la ayuda principal de Terraform (lista todos los comandos disponibles)
terraform --help

# 3. Ver la ruta donde está instalado el binario
which terraform

# 4. Ver la versión en formato JSON
terraform version -json

Paso 3: Instala tfenv y úsalo para instalar una segunda versión de Terraform (por ejemplo, si tienes la 1.9.0, instala también la 1.8.5).

# Instalar tfenv (Linux/macOS)
git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Instalar una versión adicional
tfenv install 1.8.5

# Cambiar entre versiones y verificar
tfenv use 1.8.5
terraform version  # Debería mostrar 1.8.5

tfenv use 1.9.0
terraform version  # Debería mostrar 1.9.0

Paso 4: Crea un directorio de prueba con un archivo .terraform-version:

# Crear un directorio de prueba
mkdir ~/terraform-prueba && cd ~/terraform-prueba

# Establecer la versión del proyecto
echo "1.8.5" > .terraform-version

# Verificar que tfenv usa automáticamente la versión del archivo
terraform version  # Debería mostrar 1.8.5 aunque la versión global sea diferente

Resultado esperado

Al final del ejercicio deberías poder ejecutar terraform version y ver la versión instalada, cambiar entre versiones con tfenv use, y tener un archivo .terraform-version que configure la versión automáticamente por proyecto.

Errores Comunes Durante la Instalación y Cómo Resolverlos

Error: "command not found: terraform"

Causa: El binario de Terraform no está en el PATH del sistema.

# Diagnóstico: buscar el binario
find / -name "terraform" -type f 2>/dev/null

# Solución: agregar el directorio al PATH
export PATH="$PATH:/directorio/donde/esta/terraform"
# Hacer el cambio permanente en ~/.bashrc o ~/.zshrc

Error: "Permission denied" al mover el binario

Causa: No tienes permisos de escritura en /usr/local/bin/.

# Solución 1: usar sudo
sudo mv terraform /usr/local/bin/

# Solución 2: instalar en un directorio personal (sin necesitar sudo)
mkdir -p ~/bin
mv terraform ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Error en macOS: "terraform cannot be opened because the developer cannot be verified"

Causa: Gatekeeper de macOS bloquea binarios descargados de internet que no están firmados con un certificado de Apple.

# Solución: quitar el atributo de cuarentena
xattr -d com.apple.quarantine /usr/local/bin/terraform

# O bien, ir a Preferencias del Sistema > Privacidad y Seguridad
# y hacer clic en "Permitir de todos modos"

Error: "Unable to verify checksum"

Causa: El archivo descargado está corrupto o fue manipulado.

# Solución: eliminar el archivo y descargarlo de nuevo
rm terraform_*.zip
# Volver a descargar desde https://releases.hashicorp.com/terraform/

Error en Windows: "terraform no se reconoce como un comando interno o externo"

Causa: El directorio de Terraform no está en el PATH de Windows.

Solución: Sigue los pasos de la sección 4.2 para agregar el directorio al PATH del sistema. Recuerda abrir una nueva ventana de PowerShell después de modificar el PATH.

Error: "gpg: no valid OpenPGP data found"

Causa: Problema al importar la clave GPG de HashiCorp en Linux.

# Solución: descargar la clave directamente y verificar
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

Resumen y Preparación para el Siguiente Tema

En esta lección has aprendido:

Los requisitos mínimos para instalar Terraform: prácticamente cualquier sistema moderno es compatible.
Cómo instalar Terraform en Linux mediante los repositorios oficiales de HashiCorp (apt y yum) o mediante binario manual.
Cómo instalar Terraform en macOS con Homebrew o manualmente, teniendo en cuenta la diferencia entre Intel y Apple Silicon.
Cómo instalar Terraform en Windows con Chocolatey o manualmente, y la importancia de configurar el PATH.
Cómo verificar la instalación y obtener información de diagnóstico.
Cómo usar tfenv para gestionar múltiples versiones de Terraform en el mismo sistema, lo cual es esencial en entornos de trabajo reales.
Los errores más comunes durante la instalación y cómo resolverlos.

Con Terraform correctamente instalado, en la siguiente lección aprenderás los conceptos básicos de Terraform: qué son los proveedores, los recursos y el estado, y cuáles son los comandos principales que usarás en tu día a día.

Instalando Terraform