Gerencie redirecionamentos como código com Terraform e CI

1. Configure o provedor#

Crie um token conforme descrito em Crie e gerencie tokens de API. O token pertence a um único workspace, e o Terraform gerencia esse workspace. Passe-o na variável de ambiente REDIRHUB_API_TOKEN em vez de escrevê-lo nos seus arquivos.

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

# Lê o token de REDIRHUB_API_TOKEN.
provider "redirhub" {}

bashexport REDIRHUB_API_TOKEN="your-token"
terraform init

2. Adicione redirecionamentos, links curtos e códigos QR#

handler indica o que o link é: redirecionamento, migração, short-url ou qr. Redirecionamentos e mapeamentos de migração usam url, a origem para a qual respondem. Links curtos e códigos QR usam host, um dos seus domínios de link curto, e um alias opcional. Os outros atributos são os mesmos campos da API: destinations, type, forward_path, forward_query, status, tags e utm.

hcl# Envie um domínio inteiro para o novo destino, incluindo caminho e query.
resource "redirhub_link" "old_domain" {
  handler       = "redirect"
  url           = "old-site.com"
  destinations  = ["https://new-site.com"]
  type          = "301"
  forward_path  = true
  forward_query = true
}

# Uma migração de site: um mapeamento por página antiga, mantido em um CSV ao lado da configuração.
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"
}

# Um link curto com marca e um 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 }
}

Execute terraform plan para ver o que vai mudar e terraform apply para aplicar a alteração. O Terraform verifica os campos de cada link antes de enviar qualquer coisa, então um redirecionamento sem url ou um código QR sem host falha no plano. Um limite do plano, como tags ou vários destinos em um plano que não os inclui, retorna a mesma mensagem que no painel.

3. Conecte um domínio e seu DNS no mesmo apply#

redirhub_domain conecta um domínio e retorna os registros DNS de que ele precisa em dns_records. Passe-os para o recurso Terraform do seu provedor de DNS. redirhub_domain_verification então aguarda até que os registros estejam ativos, de modo que os links que usam o domínio sejam publicados somente quando ele responder. O tempo limite padrão é de 10 minutos; aumente o timeout se seu DNS for lento.

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

# Aqui com Cloudflare; qualquer provedor de DNS com um recurso de registro do Terraform funciona do mesmo jeito.
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. Traga links existentes para o Terraform#

Os links que você criou no painel continuam funcionando. Para gerenciar um com o Terraform, importe-o pelo id, por exemplo link_7bXmR4, que o painel e a API mostram. Importe um domínio pelo seu hostname. A fonte de dados redirhub_links lista ids com os mesmos filtros da API, como handler, host e 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 e posterior: importe no plano e depois gerencie-o normalmente.
import {
  to = redirhub_link.old_domain
  id = "link_7bXmR4"
}

Uma alteração que alguém fizer no painel depois aparecerá no próximo plano, e o terraform apply a redefinirá para o que seus arquivos indicarem. Um link removido dos seus arquivos é excluído no próximo apply.

5. Faça o plan nos pull requests, aplique no merge#

Mantenha a configuração em uma pasta do seu repositório e o estado do Terraform em um backend remoto, como S3 ou HCP Terraform. Armazene o token como um segredo do CI. Este workflow do GitHub Actions publica o plan em cada pull request e aplica quando o pull request é mesclado. Um pipeline de CI do GitLab está nos exemplos do provedor.

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

Executar novamente com segurança#

Os trabalhos de CI expiram e são tentados novamente. Cada link que o provedor cria carrega uma Idempotency-Key, então, quando uma resposta se perde no caminho de volta, a tentativa recebe o link que a RedirHub já criou em vez de uma segunda cópia. Limites de taxa e erros temporários do servidor são reexecutados automaticamente. Seus próprios scripts podem fazer o mesmo: envie qualquer valor único no cabeçalho Idempotency-Key de um POST, e a mesma chave dentro de 24 horas retorna a primeira resposta, 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"}'

Todos os atributos estão listados na documentação do provedor no Terraform Registry. Para automatizar tarefas pontuais sem o Terraform, veja Criar, atualizar e excluir redirecionamentos em massa com a API.