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 Variables

• renovate_endpoint - Gitea API endpoint (e.g., https://gitea.example.com/api/v1/)
• renovate_token - Gitea personal access token for the bot

New Optional Variables

• renovate_platform - Git platform (default: "gitea")
• renovate_git_author - Git commit author
• renovate_username - Bot username
• renovate_autodiscover - Enable auto-discovery
• renovate_onboarding_config - Onboarding configuration
• github_com_token - Optional GitHub.com token
• restart_policy - Container restart policy
• upload_config_file - Upload config.js template

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. Update Configuration:

   • Update terraform.tfvars with new variables
   • Add renovate_endpoint and renovate_token
   • Remove old EDA-specific variables

4. 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