Gérez les redirections comme du code avec Terraform et CI

1. Configurer le fournisseur#

Créez un jeton comme décrit dans Créer et gérer les jetons d’API. Le jeton appartient à un seul espace de travail, et Terraform gère cet espace de travail. Transmettez-le via la variable d’environnement REDIRHUB_API_TOKEN plutôt que de l’écrire dans vos fichiers.

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

# Lit le jeton depuis REDIRHUB_API_TOKEN.
provider "redirhub" {}

bashexport REDIRHUB_API_TOKEN="your-token"
terraform init

2. Ajouter des redirections, des liens courts et des codes QR#

handler indique ce qu’est le lien : redirection, migration, short-url ou qr. Les redirections et les mappages de migration prennent url, la source à laquelle ils répondent. Les liens courts et les codes QR prennent host, l’un de vos domaines de liens courts, et un alias facultatif. Les autres attributs sont les mêmes champs que dans l’API : destinations, type, forward_path, forward_query, status, tags et utm.

hcl# Envoyer un domaine entier vers sa nouvelle destination, chemin et requête inclus.
resource "redirhub_link" "old_domain" {
  handler       = "redirect"
  url           = "old-site.com"
  destinations  = ["https://new-site.com"]
  type          = "301"
  forward_path  = true
  forward_query = true
}

# Une migration de site web : un mappage par ancienne page, conservé dans un CSV à côté de la configuration.
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 lien court de marque et un code QR dynamique.
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 }
}

Exécutez terraform plan pour voir ce qui va changer, puis terraform apply pour appliquer la modification. Terraform vérifie les champs de chaque lien avant d’envoyer quoi que ce soit, donc une redirection sans url ou un code QR sans host échoue dans le plan. Une limite de plan, comme les tags ou plusieurs destinations sur un plan qui ne les inclut pas, renvoie le même message que dans le tableau de bord.

3. Connectez un domaine et son DNS dans le même apply#

redirhub_domain connecte un domaine et renvoie les enregistrements DNS dont il a besoin dans dns_records. Transmettez-les à la ressource Terraform de votre fournisseur DNS. redirhub_domain_verification attend ensuite que les enregistrements soient actifs, afin que les liens utilisant le domaine ne soient publiés qu’une fois qu’il répond. Le délai d’attente est de 10 minutes par défaut ; augmentez-le si votre DNS est lent.

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

# Ici avec Cloudflare ; tout fournisseur DNS disposant d’une ressource d’enregistrement Terraform fonctionne de la même manière.
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. Intégrez les liens existants dans Terraform#

Les liens que vous avez créés dans le tableau de bord continuent de fonctionner. Pour en gérer un avec Terraform, importez-le par son identifiant, par exemple link_7bXmR4, tel qu’affiché dans le tableau de bord et l’API. Importez un domaine par son nom d’hôte. La source de données redirhub_links liste les identifiants avec les mêmes filtres que l’API, comme handler, host et 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 et versions ultérieures : importez dans le plan, puis gérez-le comme d’habitude.
import {
  to = redirhub_link.old_domain
  id = "link_7bXmR4"
}

Une modification apportée ensuite par quelqu’un dans le tableau de bord apparaît dans le prochain plan, et terraform apply la rétablit selon ce que vos fichiers indiquent. Un lien supprimé de vos fichiers est supprimé lors du prochain apply.

5. Planifiez dans les pull requests, appliquez à la fusion#

Conservez la configuration dans un dossier de votre dépôt et l’état Terraform dans un backend distant tel que S3 ou HCP Terraform. Stockez le jeton comme secret CI. Ce workflow GitHub Actions publie le plan à chaque pull request et l’applique lorsqu’elle est fusionnée. Un pipeline GitLab CI se trouve dans les exemples du fournisseur.

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

Peut être exécuté à nouveau en toute sécurité#

Les jobs CI expirent et sont relancés. Chaque lien créé par le fournisseur porte une clé Idempotency-Key, donc lorsqu’une réponse est perdue en chemin, la tentative relancée obtient le lien déjà créé par RedirHub au lieu d’une deuxième copie. Les limites de débit et les erreurs serveur temporaires sont relancées automatiquement. Vos propres scripts peuvent faire de même : envoyez n’importe quelle valeur unique dans l’en-tête Idempotency-Key d’un POST, et la même clé dans les 24 heures renvoie la première réponse, marquée 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"}'

Chaque attribut est सूची in the documentation du fournisseur sur le Terraform Registry. Pour automatiser des tâches ponctuelles sans Terraform, consultez Créer, mettre à jour et supprimer des redirections en masse avec l’API.