---
title: "Cómo configurar HCP Terraform (Terraform Cloud) y workspaces"
description: "Conecta Terraform CLI a HCP Terraform, crea workspaces con estado remoto, define variables por API, comparte outputs entre workspaces y encadena ejecuciones."
category: "Automatización Avanzada"
language: es
source: https://cubepath.com/es/docs/automatización-avanzada/configuracion-de-terraform-cloud-y-workspaces
updated: 2026-09-25
---

# 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](https://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:

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

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

```bash
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`:

```bash
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:

```bash
terraform version
```

```output
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`:

```bash
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:

```bash
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:

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

```output
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:

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

Crea el archivo principal:

```bash
nano main.tf
```

```hcl
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:

```bash
terraform init
```

```output
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:

```bash
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"
```

```output
ws-AbCdEf123456
```

Crea la variable `entorno` con el valor `produccion`:

```bash
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'
```

```output
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:

```bash
terraform apply
```

```output
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:

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

```output
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:

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

```hcl
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:

```bash
terraform init
terraform apply
```

```output
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:

```bash
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"]'
```

```output
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.

1. En la organización, ve a **Settings > Providers** (proveedores VCS) y añade tu proveedor siguiendo el asistente OAuth.
2. 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**.
3. 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:

```bash
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:

```bash
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.