terraform-docker-renovate/MIGRATION_GUIDE.md

Migration Guide: Ansible EDA to Renovate

This document provides guidance for migrating from the previous Ansible EDA module to the new Renovate bot module.

Overview

This module has been completely repurposed from deploying Ansible Event-Driven Automation to deploying a Renovate bot for automated dependency updates. This is a breaking change and requires careful migration planning.

Key Changes

1. Module Purpose

Before: Ansible Event-Driven Automation (EDA) server for webhook-based automation After: Renovate bot for automated dependency updates

2. Docker Image

Before: quay.io/ansible/ansible-rulebook:latest After: renovate/renovate:latest

3. Volumes

Before:

• ansible-eda-rulebooks - Rulebook storage
• ansible-eda-logs - Log storage

After:

• renovate-config - Configuration storage
• renovate-cache - Cache for improved performance

4. State File Path

Before: home/docker/ansible-eda/ansible-eda.tfstate After: home/docker/renovate/renovate.tfstate

5. Variable Changes

Removed Variables

• eda_image → Use renovate_image instead
• webhook_port → Not needed for Renovate
• rulebook_command → Replaced by environment variables
• upload_example_rulebook → Use upload_config_file instead
• cpu_limit → Removed (can be added back if needed)

New Required Configuration (Stored in Vault)

CRITICAL: The following values are NOT Terraform variables. They must be stored in HashiCorp Vault at path secret/renovate:

• renovate_platform - Must be "gitea"
• renovate_endpoint - Gitea API endpoint (e.g., https://gitea.example.com/api/v1/)
• renovate_token - Gitea personal access token for the bot
• renovate_git_author - Git commit author (e.g., "Renovate Bot bot@example.com")
• renovate_username - Bot username (e.g., "renovate-bot")

Store in Vault using:

vault kv put secret/renovate \
  renovate_platform="gitea" \
  renovate_endpoint="https://gitea.example.com/api/v1/" \
  renovate_token="YOUR_GITEA_TOKEN" \
  renovate_git_author="Renovate Bot <renovate-bot@example.com>" \
  renovate_username="renovate-bot"

New Optional Variables (Terraform)

• github_com_token - Optional GitHub.com token for changelog fetching
• restart_policy - Container restart policy (default: "unless-stopped")
• upload_config_file - Upload config.js template (default: true)
• renovate_autodiscover - Enable auto-discovery (default: true)
• renovate_onboarding_config - Onboarding configuration JSON
• log_level - Logging level (default: "info")
• extra_env_vars - Additional environment variables

6. Configuration Files

Before: example-rulebook.yml (YAML-based rulebooks) After:

• config.js.tpl - Renovate configuration template
• example-renovate.json - Repository-level configuration
• example-gitea-workflow.yaml - CI/CD workflow example

Migration Steps

Option 1: Fresh Deployment (Recommended)

This is the safest approach if you don't need to preserve the existing infrastructure.

1. Backup Current State (if needed):

   # Backup current state file
   terraform state pull > ansible-eda-backup.tfstate
   

2. Destroy Old Infrastructure:

   # Navigate to the module directory
   cd /path/to/terraform-docker-renovate
   
   # Destroy existing resources
   terraform destroy
   

3. Store Renovate Credentials in Vault:

   # Authenticate to Vault
   export VAULT_ADDR="https://your-vault-server:8200"
   vault login -method=approle role_id=YOUR_ROLE_ID secret_id=YOUR_SECRET_ID
   
   # Store Renovate credentials
   vault kv put secret/renovate \
     renovate_platform="gitea" \
     renovate_endpoint="https://gitea.example.com/api/v1/" \
     renovate_token="YOUR_GITEA_TOKEN" \
     renovate_git_author="Renovate Bot <renovate-bot@example.com>" \
     renovate_username="renovate-bot"
   
   # Verify
   vault kv get secret/renovate
   

4. Update Configuration:

   • Update terraform.tfvars with only Vault credentials
   • Remove old EDA-specific variables
   • Do NOT add renovate_endpoint or renovate_token to tfvars (they're in Vault)

5. Initialize and Deploy:

   # Reinitialize (backend path has changed)
   terraform init -reconfigure
   
   # Plan and apply
   terraform plan
   terraform apply
   

Option 2: Side-by-Side Deployment

If you want to keep Ansible EDA running while testing Renovate:

1. Copy the Module:

   cp -r terraform-docker-renovate terraform-docker-renovate-backup
   

2. Deploy in New Location:

   • Create a new module instance with a different container_name
   • Use a different state file path
   • Test Renovate functionality

3. Clean Up Old Deployment:

   • Once satisfied, destroy the old Ansible EDA deployment
   • Remove the backup module

Configuration Updates

terraform.tfvars

Before:

domain    = "bsdserver.nl"
role_id   = "xxx"
secret_id = "xxx"

After:

# Renovate Configuration
domain              = "bsdserver.nl"
role_id             = "xxx"
secret_id           = "xxx"

# Gitea Configuration
renovate_endpoint   = "https://gitea.bsdserver.nl/api/v1/"
renovate_token      = "your-token-here"
renovate_git_author = "Renovate Bot <renovate-bot@bsdserver.nl>"
renovate_username   = "renovate-bot"

Module Call

Before:

module "ansible_eda" {
  source = "./terraform-docker-eda"

  domain              = "bsdserver.nl"
  container_name      = "ansible-eda"
  eda_image           = "quay.io/ansible/ansible-rulebook:latest"
  webhook_port        = 5000
  role_id             = var.vault_role_id
  secret_id           = var.vault_secret_id
}

After:

module "renovate" {
  source = "./terraform-docker-renovate"

  domain            = "bsdserver.nl"
  container_name    = "renovate"
  renovate_image    = "renovate/renovate:latest"
  renovate_endpoint = "https://gitea.bsdserver.nl/api/v1/"
  renovate_token    = var.renovate_token
  role_id           = var.vault_role_id
  secret_id         = var.vault_secret_id
}

Gitea Setup Requirements

Before deploying, ensure you have:

1. Created a Renovate Bot User in Gitea:

   • Username: renovate-bot (or your preference)
   • Full name: "Renovate Bot"
   • Email: renovate-bot@bsdserver.nl

2. Generated a Personal Access Token with scopes:

   • repo (Read and Write)
   • user (Read)
   • issue (Read and Write) - Gitea ≥ 1.20.0
   • organization (Read) - Gitea ≥ 1.20.0

3. Added Bot to Repositories:

   • Add as collaborator to repositories you want to manage
   • Or enable renovate_autodiscover = true to find all accessible repos

Post-Migration Tasks

After successful deployment:

1. Verify Container Status:

   docker ps | grep renovate
   docker logs renovate -f
   

2. Test Repository Configuration:

   • Add renovate.json to a test repository
   • Wait for Renovate to create an onboarding PR
   • Review and merge the onboarding PR

3. Monitor Logs:

   docker logs renovate -f
   

4. Configure Scheduling:

   • Set up cron job or Gitea Actions workflow
   • See files/example-gitea-workflow.yaml

Troubleshooting

State File Issues

If you encounter state file conflicts:

# Reinitialize with new backend configuration
terraform init -reconfigure

# Or migrate state if needed
terraform init -migrate-state

Container Won't Start

Check logs for authentication issues:

docker logs renovate

Common issues:

• Invalid Gitea endpoint (must end with /api/v1/)
• Incorrect or expired token
• Network connectivity to Gitea instance

Volume Migration

If you need to preserve any data (unlikely for this transition):

# Copy data from old volume to new
docker run --rm \
  -v ansible-eda-rulebooks:/source:ro \
  -v renovate-config:/dest \
  alpine sh -c "cp -a /source/. /dest/"

Rollback Procedure

If you need to rollback to Ansible EDA:

1. Restore from Backup:

   # Restore backup of terraform-docker-renovate module
   rm -rf terraform-docker-renovate
   cp -r terraform-docker-renovate-backup terraform-docker-renovate
   

2. Destroy Renovate Resources:

   terraform destroy
   

3. Restore State:

   terraform state push ansible-eda-backup.tfstate
   

4. Redeploy:

   terraform apply
   

Additional Resources

• Renovate Documentation
• Gitea Platform Configuration
• Self-Hosting Renovate
• Module README.md for complete documentation

Support

For issues or questions:

1. Review the comprehensive README.md
2. Check Renovate logs: docker logs renovate
3. Consult the Renovate documentation
4. Review the CHANGELOG.md for all changes