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:**
```bash
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):
   ```bash
   # Backup current state file
   terraform state pull > ansible-eda-backup.tfstate
   ```

2. **Destroy Old Infrastructure**:
   ```bash
   # Navigate to the module directory
   cd /path/to/terraform-docker-renovate

   # Destroy existing resources
   terraform destroy
   ```

3. **Store Renovate Credentials in Vault**:
   ```bash
   # 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)

4. **Initialize and Deploy**:
   ```bash
   # 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**:
   ```bash
   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**:
```hcl
domain    = "bsdserver.nl"
role_id   = "xxx"
secret_id = "xxx"
```

**After**:
```hcl
# 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**:
```hcl
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**:
```hcl
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**:
   ```bash
   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**:
   ```bash
   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:

```bash
# 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:
```bash
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):

```bash
# 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**:
   ```bash
   # 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**:
   ```bash
   terraform destroy
   ```

3. **Restore State**:
   ```bash
   terraform state push ansible-eda-backup.tfstate
   ```

4. **Redeploy**:
   ```bash
   terraform apply
   ```

## Additional Resources

- [Renovate Documentation](https://docs.renovatebot.com/)
- [Gitea Platform Configuration](https://docs.renovatebot.com/modules/platform/gitea/)
- [Self-Hosting Renovate](https://docs.renovatebot.com/examples/self-hosting/)
- 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