# Pipeline Migration Guide: Existing CI/CD → CircleCI

**Migration Type**: CI/CD Pipeline Migration
**Services**: 33 ACC services (already running in production)
**Target**: Migrate from existing pipeline to CircleCI
**Goal**: Zero-downtime migration with parallel pipeline validation

## Overview

All 33 ACC services are currently deployed and running via an existing CI/CD pipeline. We need to:
1. Create CircleCI pipelines in `tbi-devops-environments`
2. Migrate/centralize Dockerfiles and Helm charts
3. Validate CircleCI pipelines work correctly
4. Cutover from old pipeline to CircleCI
5. Decommission old pipeline

## Pre-Migration Discovery

### Step 1: Identify Current Pipeline System

**Questions to Answer:**
- What system currently deploys these services? (Jenkins, GitHub Actions, GitLab CI, manual?)
- Where are the pipeline configurations located?
- Who maintains the current pipeline?
- What triggers deployments? (git push, manual, scheduled?)

**How to Find Out:**
```bash
# Check service repositories for CI/CD configs
cd /Users/iakpabio/Desktop/git-code/tbi-code/tbi-acc-booking-service

# Look for existing CI/CD files
ls -la .circleci/       # CircleCI (shouldn't exist yet)
ls -la .github/workflows/  # GitHub Actions
ls -la .gitlab-ci.yml   # GitLab CI
ls -la Jenkinsfile      # Jenkins
ls -la azure-pipelines.yml  # Azure DevOps

# Check for deployment scripts
ls -la scripts/
ls -la deploy/
```

### Step 2: Locate Existing Dockerfiles

**Check Service Repositories:**
```bash
# For each service
SERVICE_NAME="tbi-acc-booking-service"
cd /Users/iakpabio/Desktop/git-code/tbi-code/${SERVICE_NAME}

# Look for Dockerfile
find . -name "Dockerfile" -o -name "*.dockerfile"
```

**Check Centralized Locations:**
```bash
# Check tbi-devops-common
ls -la /Users/iakpabio/Desktop/git-code/tbi-code/tbi-devops-common/docker/

# Check if Dockerfiles are in a separate repo
```

### Step 3: Locate Existing Helm Charts

**Check Possible Locations:**
```bash
# Service repositories
cd /Users/iakpabio/Desktop/git-code/tbi-code/${SERVICE_NAME}
ls -la charts/
ls -la helm/

# tbi-devops-common
ls -la /Users/iakpabio/Desktop/git-code/tbi-code/tbi-devops-common/charts/
ls -la /Users/iakpabio/Desktop/git-code/tbi-code/tbi-devops-common/helm/

# Separate charts repository
ls -la /Users/iakpabio/Desktop/git-code/tbi-code/tbi-charts/
```

### Step 4: Document Current Deployment Process

**Create a document for each service:**
```markdown
# Current Deployment Process for [service-name]

## Pipeline System
- System: [Jenkins/GitHub Actions/etc.]
- Location: [URL or path]
- Trigger: [git push/manual/scheduled]

## Build Process
- Dockerfile location: [path]
- Image registry: [ECR/Docker Hub/etc.]
- Image naming: [pattern]

## Deployment Process
- Helm chart location: [path]
- Deployment method: [helm upgrade/kubectl apply/etc.]
- Environments: [dev/qa/uat/prod]
- Namespace: [redtag]

## Secrets Management
- How are secrets injected: [SOPS/Sealed Secrets/etc.]
- Secrets location: [path]

## Post-Deployment
- Health checks: [yes/no]
- Notifications: [Slack/email/etc.]
```

## Migration Workflow (Per Service)

### Phase 1: Create CircleCI Pipeline (30-45 min)

**1.1 Create Directory Structure**
```bash
cd /Users/iakpabio/Desktop/git-code/tbi-code/tbi-devops-environments

SERVICE_NAME="tbi-acc-booking-service"

mkdir -p dev/${SERVICE_NAME}/{.circleci,docker,scripts,charts/${SERVICE_NAME},github/workflows}
```

**1.2 Copy/Create Dockerfile**
```bash
# If Dockerfile exists in service repo, copy it
cp /Users/iakpabio/Desktop/git-code/tbi-code/${SERVICE_NAME}/Dockerfile \
   dev/${SERVICE_NAME}/docker/Dockerfile

# If Dockerfile doesn't exist, create from template
cp dev/tbi-acc-hotel-mapping-service/docker/Dockerfile \
   dev/${SERVICE_NAME}/docker/Dockerfile

# Update service-specific details (entry point, dependencies, etc.)
```

**1.3 Copy/Create Helm Charts**
```bash
# If charts exist elsewhere, copy them
cp -r /path/to/existing/charts/${SERVICE_NAME}/* \
      dev/${SERVICE_NAME}/charts/${SERVICE_NAME}/

# If charts don't exist, copy from template
cp -r dev/tbi-acc-hotel-mapping-service/charts/tbi-acc-hotel-mapping-service/* \
      dev/${SERVICE_NAME}/charts/${SERVICE_NAME}/

# Update Chart.yaml and templates with service name
```

**1.4 Create CircleCI Config**
```bash
# Copy from reference service
cp dev/tbi-acc-hotel-mapping-service/.circleci/config.yml \
   dev/${SERVICE_NAME}/.circleci/config.yml

# Update service name throughout the file
sed -i '' "s/tbi-acc-hotel-mapping-service/${SERVICE_NAME}/g" \
   dev/${SERVICE_NAME}/.circleci/config.yml
```

**1.5 Create Deployment Scripts**
```bash
# Copy scripts from reference
cp dev/tbi-acc-hotel-mapping-service/scripts/*.sh \
   dev/${SERVICE_NAME}/scripts/

# Update SERVICE_NAME variable in deploy-services.sh
sed -i '' "s/SERVICE_NAME=\"tbi-acc-hotel-mapping-service\"/SERVICE_NAME=\"${SERVICE_NAME}\"/g" \
   dev/${SERVICE_NAME}/scripts/deploy-services.sh
```

**1.6 Create Documentation**
```bash
# Copy and customize README
cp dev/tbi-acc-hotel-mapping-service/README.md \
   dev/${SERVICE_NAME}/README.md

# Update service-specific details
```

### Phase 2: Validate Configuration (15-20 min)

**2.1 Review Generated Files**
```bash
# Check all files were created
tree dev/${SERVICE_NAME}

# Verify service name replacements
grep -r "tbi-acc-hotel-mapping-service" dev/${SERVICE_NAME}
# Should return no results (all replaced)
```

**2.2 Verify Values and Secrets**
```bash
cd /Users/iakpabio/Desktop/git-code/tbi-code/tbi-environments

# Verify values file exists
cat dev/values/${SERVICE_NAME}.yaml

# Verify secrets file exists and is encrypted
file dev/secrets/secrets.${SERVICE_NAME}.yaml
# Should show: "dev/secrets/secrets.${SERVICE_NAME}.yaml: data"
```

**2.3 Check Requirements.yaml**
```bash
# Verify service is in requirements.yaml
grep "name: ${SERVICE_NAME}" dev/requirements.yaml
```

### Phase 3: Test in Dev Environment (20-30 min)

**3.1 Commit CircleCI Pipeline**
```bash
cd /Users/iakpabio/Desktop/git-code/tbi-code/tbi-devops-environments

git add dev/${SERVICE_NAME}
git commit -m "Add CircleCI pipeline for ${SERVICE_NAME}

- CircleCI config with lint, test, build, deploy stages
- Centralized Dockerfile
- Deployment scripts with critical fixes
- Complete Helm chart
- Documentation

Part of pipeline migration from existing CI/CD to CircleCI.
"
git push origin master
```

**3.2 Add VERSION File to Service Repo**
```bash
cd /Users/iakpabio/Desktop/git-code/tbi-code/${SERVICE_NAME}

# Check current version or create new
echo "1.0.0" > VERSION

git add VERSION
git commit -m "Add VERSION file for CircleCI pipeline"
git push origin develop
```

**3.3 Trigger CircleCI Pipeline**
```bash
# Make a small change to trigger pipeline
cd /Users/iakpabio/Desktop/git-code/tbi-code/${SERVICE_NAME}

# Add a comment or update README
echo "# CircleCI Pipeline Active" >> README.md

git add README.md
git commit -m "Trigger CircleCI pipeline test"
git push origin develop
```

**3.4 Monitor CircleCI**
- Go to CircleCI dashboard
- Watch pipeline execution
- Check for errors in each stage:
  - ✅ Lint and test
  - ✅ Build and push images
  - ✅ Deploy to Kubernetes

**3.5 Verify Deployment**
```bash
# Check pod status
kubectl get pods -n redtag | grep ${SERVICE_NAME}

# Check pod logs
kubectl logs -n redtag deployment/${SERVICE_NAME}

# Check ingress
kubectl get ingress -n redtag | grep ${SERVICE_NAME}

# Test endpoint (if applicable)
curl https://${SERVICE_NAME}.dev.tbidevelopment.ca/health
```

### Phase 4: Compare with Existing Pipeline (10-15 min)

**4.1 Compare Deployments**
```bash
# Get image from CircleCI deployment
kubectl get deployment ${SERVICE_NAME} -n redtag -o jsonpath='{.spec.template.spec.containers[0].image}'

# Compare with previous deployment
# Check if image tag is newer
# Verify environment variables match
# Confirm resource limits are same
```

**4.2 Validate Functionality**
- Test API endpoints
- Check logs for errors
- Verify database connections
- Test integrations with other services
- Run smoke tests

**4.3 Document Differences**
```markdown
# Differences Between Old and New Pipeline

## Image Tags
- Old: [pattern]
- New: [pattern]

## Deployment Method
- Old: [method]
- New: helm secrets upgrade

## Timing
- Old: [X minutes]
- New: [Y minutes]

## Issues Found
- [List any issues]
```

### Phase 5: Rollout to Other Environments (Per Environment: 15-20 min)

**5.1 QA Environment**
```bash
# Update CircleCI config to include qa branch
# Copy values and secrets to qa/
# Test deployment to qa
```

**5.2 UAT Environment**
```bash
# Update CircleCI config to include uat branch
# Copy values and secrets to uat/
# Test deployment to uat
```

**5.3 Production Environment**
```bash
# Update CircleCI config to include master/main branch
# Copy values and secrets to prod/
# Plan production cutover window
# Test deployment to prod (during maintenance window)
```

### Phase 6: Cutover and Decommission (15-20 min)

**6.1 Disable Old Pipeline**
```bash
# Depending on old system:
# - Remove Jenkinsfile
# - Disable GitHub Actions workflow
# - Remove GitLab CI config
# - etc.

cd /Users/iakpabio/Desktop/git-code/tbi-code/${SERVICE_NAME}

# Example for GitHub Actions:
git mv .github/workflows/deploy.yml .github/workflows/deploy.yml.disabled
git commit -m "Disable old GitHub Actions pipeline - migrated to CircleCI"
git push origin develop
```

**6.2 Update Documentation**
```bash
# Update service README with new deployment process
# Update team wiki/confluence
# Notify team of pipeline change
```

**6.3 Monitor for Issues**
- Watch for deployment issues over next few days
- Monitor error rates
- Check performance metrics
- Be ready to rollback if needed

## Batch Migration Strategy

### Recommended Order

**Week 1: Dev-Only Services (Low Risk)**
- Gimmonix automation services (7 services)
- Other dev-only services (5 services)
- **Total**: 12 services
- **Risk**: Low (dev environment only)

**Week 2: 3-Environment Services (Medium Risk)**
- Services with dev, prod, uat (9 services)
- **Total**: 9 services
- **Risk**: Medium (includes production)

**Week 3: Multi-Environment Services (Higher Risk)**
- Services with 4+ environments (9 services)
- **Total**: 9 services
- **Risk**: Higher (multiple production environments)

**Week 4: Legacy Services (Verify First)**
- Services with "-old" suffix (3 services)
- **Total**: 3 services
- **Risk**: Unknown (verify if still needed)

## Rollback Plan

If CircleCI pipeline fails or causes issues:

**Immediate Rollback:**
```bash
# Revert to previous image tag
kubectl set image deployment/${SERVICE_NAME} \
  ${SERVICE_NAME}=[previous-image-tag] \
  -n redtag

# Or rollback deployment
kubectl rollout undo deployment/${SERVICE_NAME} -n redtag
```

**Re-enable Old Pipeline:**
```bash
# Restore old pipeline configuration
git revert [commit-hash]
git push origin develop
```

## Success Criteria

For each service migration:
- ✅ CircleCI pipeline runs successfully
- ✅ Image builds and pushes to ECR
- ✅ Deployment succeeds in dev
- ✅ Pod is running and healthy
- ✅ Endpoints respond correctly
- ✅ No errors in logs
- ✅ Rollout to qa/uat/prod successful
- ✅ Old pipeline disabled
- ✅ Documentation updated
- ✅ Team notified

## Monitoring During Migration

**Key Metrics to Watch:**
- Deployment success rate
- Build time
- Deployment time
- Error rates
- Pod restart counts
- API response times
- Resource utilization

**Alerts to Set Up:**
- Failed CircleCI builds
- Failed deployments
- Pod crash loops
- High error rates
- Slow response times

## Communication Plan

**Before Migration:**
- Notify team of migration schedule
- Share documentation
- Provide training on CircleCI

**During Migration:**
- Daily status updates
- Report any issues immediately
- Share lessons learned

**After Migration:**
- Final status report
- Update runbooks
- Conduct retrospective

## Estimated Timeline

**Per Service:**
- Discovery: 10-15 min
- Create pipeline: 30-45 min
- Test in dev: 20-30 min
- Compare with old: 10-15 min
- Rollout to other envs: 15-20 min per env
- Cutover: 15-20 min
**Total**: 2-3 hours per service

**Total Migration:**
- 33 services × 2.5 hours = ~82 hours
- With batching and automation: ~50-60 hours
- Spread over 4 weeks: ~12-15 hours per week

## Tools and Automation

**Scripts Created:**
- `./scripts/clone-acc-services.sh` - Clone all service repos
- `./scripts/analyze-acc-services.sh` - Analyze tech stacks
- Consider creating: `./scripts/migrate-pipeline.sh` - Automate pipeline creation

**CircleCI Pipeline Deployment Agent:**
- Use `.kiro/agents/circleci-pipeline-deployment-agent.json`
- Automates pipeline creation
- Reduces manual work by 40-50%

---

**Ready to start?** Begin with discovery phase to understand current pipeline system.