Cómo configurar HCP Terraform (Terraform Cloud) y workspaces

HCP Terraform (antes llamado Terraform Cloud) es el servicio gestionado de HashiCorp que guarda el estado de Terraform, ejecuta los plan y apply en remoto y controla quién puede cambiar cada entorno. Cada workspace tiene su propio estado, sus variables y su historial de ejecuciones. En este tutorial conectarás Terraform CLI en Ubuntu 24.04 a una organización de HCP Terraform, crearás dos workspaces, les asignarás variables por la API y harás que uno lea los outputs del otro.

Para que puedas seguir la guía sin credenciales de ningún proveedor cloud, el ejemplo usa el proveedor hashicorp/random. El flujo es idéntico con cualquier otro proveedor.

Requisitos previos

Un servidor o equipo con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con un usuario no root con privilegios sudo.
Una cuenta en app.terraform.io y una organización creada desde la interfaz web (en esta guía se llama mi-empresa; sustitúyela por la tuya).
curl y jq para las llamadas a la API.
Conocimientos básicos de HCL y del ciclo init, plan, apply.

Nota

funciones como la gestión de equipos y las políticas Sentinel u OPA dependen del plan contratado en HCP Terraform. Los pasos de esta guía funcionan en el plan gratuito.

Paso 1: Instalar Terraform desde el repositorio de HashiCorp

HashiCorp publica paquetes oficiales para Ubuntu. Instala primero las herramientas necesarias:

sudo apt update
sudo apt install -y gnupg curl jq lsb-release

Descarga la clave de firma del repositorio en /etc/apt/keyrings:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/hashicorp.gpg

Añade el repositorio e instala el paquete terraform:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/hashicorp.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update
sudo apt install -y terraform

Comprueba la versión instalada:

terraform version

Terraform v1.x.y
on linux_amd64

Paso 2: Autenticar Terraform CLI

terraform login genera un token de usuario y lo guarda en ~/.terraform.d/credentials.tfrc.json. Ejecútalo y confirma con yes:

terraform login

En un servidor sin navegador, Terraform muestra una URL. Ábrela en tu equipo, crea el token, cópialo y pégalo en la terminal cuando lo pida. Al terminar verás un mensaje de bienvenida con tu nombre de usuario.

Para las llamadas a la API de los pasos siguientes, guarda el token y la organización en variables de la sesión actual:

export TFC_TOKEN=$(jq -r '.credentials["app.terraform.io"].token' ~/.terraform.d/credentials.tfrc.json)
export TFC_ORG="mi-empresa"

Verifica que el token funciona consultando la organización:

curl -s -H "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/$TFC_ORG" | jq -r '.data.id'

mi-empresa

Importante

el token da acceso completo a tu cuenta. No lo guardes en el repositorio ni en scripts versionados.

Paso 3: Crear el primer workspace con el bloque cloud

El bloque cloud indica a Terraform que use HCP Terraform para el estado y las ejecuciones. Si el workspace indicado no existe, terraform init lo crea.

Crea el directorio del proyecto de red:

mkdir -p ~/tfc-demo/red && cd ~/tfc-demo/red

Crea el archivo principal:

nano main.tf

terraform {
  cloud {
    organization = "mi-empresa"

    workspaces {
      name = "demo-red"
    }
  }

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

variable "entorno" {
  type        = string
  description = "Nombre del entorno"
}

resource "random_pet" "red" {
  prefix = var.entorno
  length = 2
}

output "nombre_red" {
  value = random_pet.red.id
}

Inicializa el proyecto:

terraform init

Initializing HCP Terraform...
...
HCP Terraform has been successfully initialized!

En la interfaz web aparecerá el workspace demo-red dentro del proyecto por defecto. Todavía no puedes ejecutar plan, porque la variable entorno no tiene valor.

Paso 4: Definir variables del workspace por la API

Las variables de workspace se guardan en HCP Terraform y se aplican en cada ejecución remota. Hay dos categorías: terraform (variables de entrada de HCL) y env (variables de entorno, por ejemplo credenciales de un proveedor).

Obtén el ID del workspace:

WS_RED=$(curl -s -H "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/$TFC_ORG/workspaces/demo-red" | jq -r '.data.id')
echo "$WS_RED"

ws-AbCdEf123456

Crea la variable entorno con el valor produccion:

curl -s -X POST \
  -H "Authorization: Bearer $TFC_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/workspaces/$WS_RED/vars" \
  -d '{
    "data": {
      "type": "vars",
      "attributes": {
        "key": "entorno",
        "value": "produccion",
        "category": "terraform",
        "hcl": false,
        "sensitive": false
      }
    }
  }' | jq -r '.data.attributes.key'

entorno

Para credenciales usa "category": "env" y "sensitive": true. Una variable sensible no se puede volver a leer ni desde la API ni desde la interfaz, solo sobrescribir.

Si varias workspaces comparten las mismas credenciales, crea un variable set en Settings > Variable sets de la organización y aplícalo a los workspaces o proyectos que lo necesiten, en lugar de repetir la variable en cada uno.

Paso 5: Ejecutar plan y apply en remoto

Con el modo de ejecución por defecto (remoto), terraform plan sube la configuración a HCP Terraform y muestra en tu terminal la salida de la ejecución remota:

terraform apply

Running apply in HCP Terraform. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending...
...
Plan: 1 to add, 0 to change, 0 to destroy.
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

nombre_red = "produccion-happy-panda"

Comprueba que el estado está en remoto y no en un archivo local:

terraform state list
ls terraform.tfstate 2>/dev/null || echo "sin estado local"

random_pet.red
sin estado local

La ejecución también aparece en la pestaña Runs del workspace, con el plan, el usuario que la lanzó y el estado resultante.

Paso 6: Leer los outputs de otro workspace

Un segundo workspace (por ejemplo, la aplicación) puede consumir los outputs del de red. Primero, permite que otros workspaces lean el estado de demo-red: en su página ve a Settings > General > Remote state sharing y comparte el estado con toda la organización o solo con los workspaces que elijas.

Crea el proyecto de la aplicación:

mkdir -p ~/tfc-demo/app && cd ~/tfc-demo/app
nano main.tf

terraform {
  cloud {
    organization = "mi-empresa"

    workspaces {
      name = "demo-app"
    }
  }
}

data "terraform_remote_state" "red" {
  backend = "remote"

  config = {
    organization = "mi-empresa"
    workspaces = {
      name = "demo-red"
    }
  }
}

output "red_usada" {
  value = data.terraform_remote_state.red.outputs.nombre_red
}

Inicializa y aplica:

terraform init
terraform apply

Outputs:

red_usada = "produccion-happy-panda"

Si demo-app no tiene permiso para leer el estado de demo-red, la ejecución falla con un error de acceso: revisa el ajuste de Remote state sharing.

Paso 7: Encadenar ejecuciones con run triggers

Un run trigger lanza automáticamente una ejecución en un workspace cuando otro termina un apply correcto. Así, cada cambio en la red vuelve a planificar la aplicación.

Obtén el ID del workspace de la aplicación y crea el trigger con demo-red como origen:

WS_APP=$(curl -s -H "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/$TFC_ORG/workspaces/demo-app" | jq -r '.data.id')

curl -s -X POST \
  -H "Authorization: Bearer $TFC_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/workspaces/$WS_APP/run-triggers" \
  -d "{\"data\": {\"relationships\": {\"sourceable\": {\"data\": {\"id\": \"$WS_RED\", \"type\": \"workspaces\"}}}}}" \
  | jq -r '.data.attributes["sourceable-name"]'

demo-red

Verifica el trigger desde la interfaz en demo-app > Settings > Run Triggers. Para probarlo, cambia el valor de la variable entorno en demo-red y vuelve a aplicar ese workspace: en demo-app > Runs aparecerá una ejecución nueva con el origen demo-red.

Nota

por defecto, las ejecuciones lanzadas por un run trigger no se aplican solas; quedan esperando confirmación salvo que el workspace tenga activado auto-apply.

Paso 8: Conectar un workspace a un repositorio Git (opcional)

En lugar de lanzar ejecuciones desde la CLI, un workspace puede seguir una rama de GitHub, GitLab o Bitbucket: cada push lanza un plan y cada pull request recibe un plan especulativo.

En la organización, ve a Settings > Providers (proveedores VCS) y añade tu proveedor siguiendo el asistente OAuth.
En el workspace, ve a Settings > Version Control, elige el repositorio, la rama y, si el código está en un subdirectorio, el Terraform Working Directory.
Haz un push a la rama y comprueba en Runs que se lanza la ejecución.

Un workspace conectado a VCS ya no acepta terraform apply desde la CLI; solo terraform plan especulativos. Los cambios se aplican a través del repositorio.

Migrar un estado local existente

Si ya tienes un proyecto con terraform.tfstate local, haz una copia de seguridad, añade el bloque cloud y ejecuta terraform init. Terraform detecta el estado local y pregunta si quieres copiarlo al workspace:

cp terraform.tfstate terraform.tfstate.backup-local
terraform init

Responde yes y comprueba con terraform state list que aparecen los mismos recursos. Después puedes borrar el archivo local.

Solución de problemas

Error: No valid credential sources found o 401 Unauthorized. El token ha caducado o se generó para otro host. Vuelve a ejecutar terraform login y exporta de nuevo TFC_TOKEN.

No value for required variable. La variable no está definida en el workspace ni en un variable set aplicado a él. Lista las variables del workspace:

curl -s -H "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/workspaces/$WS_RED/vars" | jq -r '.data[].attributes | "\(.category) \(.key)"'

El proveedor no encuentra credenciales en la ejecución remota. En modo remoto, el plan no se ejecuta en tu máquina, así que las variables de entorno de tu shell no llegan. Defínelas como variables env del workspace o en un variable set. Si prefieres ejecutar en local y usar HCP Terraform solo para el estado, cambia el workspace a Execution Mode: Local en Settings > General.

Una ejecución se queda en pending. Otra ejecución del mismo workspace está esperando confirmación. Confírmala o descártala desde Runs; las ejecuciones de un workspace se procesan de una en una.

Conclusión

Tienes Terraform CLI conectado a HCP Terraform, dos workspaces con estado remoto, variables gestionadas por la API, outputs compartidos y un run trigger que mantiene sincronizada la aplicación con la red. Como siguientes pasos, puedes gestionar los propios workspaces como código con el proveedor hashicorp/tfe, agrupar los workspaces de cada entorno en proyectos y conectar el repositorio para trabajar con pull requests.

On this page