Gestiona redirecciones como código con Terraform y CI

1. Configura el proveedor#

Crea un token como se describe en Crear y gestionar tokens de API. El token pertenece a un solo espacio de trabajo, y Terraform gestiona ese espacio de trabajo. Pásalo en la variable de entorno REDIRHUB_API_TOKEN en lugar de escribirlo en tus archivos.

hclterraform {
  required_providers {
    redirhub = {
      source  = "redirhub/redirhub"
      version = "~> 0.1"
    }
  }
}

# Reads the token from REDIRHUB_API_TOKEN.
provider "redirhub" {}

bashexport REDIRHUB_API_TOKEN="your-token"
terraform init

2. Añade redirecciones, enlaces cortos y códigos QR#

handler indica qué es el enlace: redirect, migration, short-url o qr. Las redirecciones y los mapeos de migración toman url, la fuente a la que responden. Los enlaces cortos y los códigos QR toman host, uno de tus dominios de enlaces cortos, y un alias opcional. Los demás atributos son los mismos campos que en la API: destinations, type, forward_path, forward_query, status, tags y utm.

hcl# Envía todo un dominio a su nuevo destino, incluida la ruta y la consulta.
resource "redirhub_link" "old_domain" {
  handler       = "redirect"
  url           = "old-site.com"
  destinations  = ["https://new-site.com"]
  type          = "301"
  forward_path  = true
  forward_query = true
}

# Una migración de sitio web: un mapeo por cada página antigua, guardado en un CSV junto a la configuración.
resource "redirhub_link" "migration" {
  for_each = { for row in csvdecode(file("${path.module}/redirects.csv")) : row.from => row }

  handler      = "migration"
  url          = each.value.from
  destinations = [each.value.to]
  type         = "301"
}

# Un enlace corto con marca y un código QR dinámico.
resource "redirhub_link" "spring" {
  handler      = "short-url"
  host         = "go.example.com"
  alias        = "spring"
  destinations = ["https://example.com/campaigns/spring"]
  utm          = { source = "newsletter", campaign = "spring" }
}

resource "redirhub_link" "menu" {
  handler      = "qr"
  host         = "go.example.com"
  alias        = "menu"
  destinations = ["https://example.com/menu"]
  qr           = { theme = "dark", logo = true }
}

Ejecuta terraform plan para ver qué cambiará y terraform apply para realizar el cambio. Terraform comprueba los campos de cada enlace antes de enviar nada, así que una redirección sin url o un código QR sin host falla en el plan. Un límite del plan, como tags o varias destinations en un plan que no los incluye, devuelve el mismo mensaje que en el panel.

3. Conecta un dominio y su DNS en la misma ejecución#

redirhub_domain conecta un dominio y devuelve los registros DNS que necesita en dns_records. Entrégaselos al recurso Terraform de tu proveedor de DNS. Luego redirhub_domain_verification espera hasta que los registros estén activos, de modo que los enlaces que usan el dominio se publiquen solo cuando responda. Espera 10 minutos por defecto; aumenta el tiempo de espera si tu DNS es lento.

hclresource "redirhub_domain" "go" {
  host        = "go.example.com"
  short_links = true
}

# Aquí con Cloudflare; cualquier proveedor de DNS con un recurso de registros de Terraform funciona igual.
resource "cloudflare_dns_record" "redirhub" {
  for_each = { for r in redirhub_domain.go.dns_records : "${r.type}-${r.name}" => r }

  zone_id = var.cloudflare_zone_id
  name    = each.value.name
  type    = each.value.type
  content = each.value.value
  ttl     = 300
}

resource "redirhub_domain_verification" "go" {
  host       = redirhub_domain.go.host
  depends_on = [cloudflare_dns_record.redirhub]
}

resource "redirhub_link" "launch" {
  handler      = "short-url"
  host         = redirhub_domain_verification.go.host
  alias        = "launch"
  destinations = ["https://example.com/launch"]
}

4. Trae enlaces existentes bajo Terraform#

Los enlaces que creaste en el panel siguen funcionando. Para administrar uno con Terraform, impórtalo por su id, por ejemplo link_7bXmR4, que el panel y la API muestran. Importa un dominio por su nombre de host. La fuente de datos redirhub_links lista ids con los mismos filtros que la API, como handler, host y tags.

hcldata "redirhub_links" "old_site" {
  handler = "redirect,migration"
  host    = "old-site.com"
}

output "old_site_ids" {
  value = { for l in data.redirhub_links.old_site.links : l.url => l.id }
}

# Terraform 1.5 y posteriores: importa en el plan y luego adminístralo como siempre.
import {
  to = redirhub_link.old_domain
  id = "link_7bXmR4"
}

Un cambio que alguien haga después en el panel aparece en el siguiente plan, y terraform apply lo vuelve a dejar como dicen tus archivos. Un enlace eliminado de tus archivos se borra en el siguiente apply.

5. Planifica en las solicitudes de extracción, aplica al hacer merge#

Guarda la configuración en una carpeta de tu repositorio y el estado de Terraform en un backend remoto como S3 o HCP Terraform. Guarda el token como un secreto de CI. Este flujo de trabajo de GitHub Actions publica el plan en cada solicitud de extracción y lo aplica cuando la solicitud de extracción se fusiona. Hay un pipeline de GitLab CI en los ejemplos del proveedor.

yaml# .github/workflows/redirects.yml
name: Redirects
on:
  pull_request:
    paths: ['redirects/**']
  push:
    branches: [main]
    paths: ['redirects/**']
permissions:
  contents: read
  pull-requests: write
concurrency: redirects
jobs:
  terraform:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: redirects
    env:
      REDIRHUB_API_TOKEN: ${{ secrets.REDIRHUB_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_wrapper: false
      - run: terraform init -input=false
      - run: terraform plan -input=false -no-color -out=tfplan | tee plan.txt
      - if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const plan = require('fs').readFileSync('redirects/plan.txt', 'utf8');
            await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body: '```\n' + plan.slice(-60000) + '\n```' });
      - if: github.event_name == 'push'
        run: terraform apply -input=false tfplan

Seguro para ejecutarse de nuevo#

Los trabajos de CI agotan el tiempo de espera y se reintentan. Cada enlace que crea el proveedor lleva una Idempotency-Key, así que cuando una respuesta se pierde en el camino de vuelta, el reintento obtiene el enlace que RedirHub ya hizo en lugar de una segunda copia. Los límites de tasa y los errores temporales del servidor se reintentan automáticamente. Tus propios scripts pueden hacer lo mismo: envía cualquier valor único en el encabezado Idempotency-Key de un POST, y la misma clave dentro de las 24 horas devuelve la primera respuesta, marcada como Idempotent-Replayed: true.

bashcurl -X POST "https://api.redirhub.com/v1/links" \
  -H "Authorization: Bearer $REDIRHUB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"handler": "redirect", "url": "old-site.com", "destination": "https://new-site.com"}'

Cada atributo aparece en la documentación del proveedor en el Registro de Terraform. Para automatizar tareas puntuales sin Terraform, consulta Crear, actualizar y eliminar redirecciones en lote con la API.