pos-system/docs/vi/guides/iam-migration.md

Hướng Dẫn Migration: Auth Service → IAM Service

Tài liệu này hướng dẫn cách migrate từ auth-service sang iam-service.

Tổng Quan

IAM Service là phiên bản mở rộng của Auth Service với các tính năng bổ sung về Identity Management, Access Management, và Governance & Compliance. Tất cả các API endpoints của Auth Service vẫn được giữ nguyên để đảm bảo backward compatibility.

Migration Process Flow

graph TD
 Start([ Bắt đầu Migration]) --> Backup[ Step 1: Backup<br/>Database & Code]
 Backup --> Update[ Step 2: Update Codebase<br/>Package refs, Env vars]
 Update --> Migrate[ Step 3: Run Prisma Migration<br/>Add IAM models]
 Migrate --> Deploy{ Deployment Strategy}

 Deploy -->|Khuyến nghị| BlueGreen[ Blue-Green Deployment]
 Deploy -->|Dễ dàng hơn| InPlace[ In-Place Migration]

 BlueGreen --> DeployNew[Deploy IAM Service mới]
 DeployNew --> Verify1[ Verify hoạt động]
 Verify1 --> Switch[ Switch traffic]
 Switch --> Monitor1[ Monitor]
 Monitor1 --> Success{Thành công?}

 InPlace --> DeployBoth[Deploy cả 2 service]
 DeployBoth --> GradualRoute[ Gradually route traffic]
 GradualRoute --> Monitor2[ Monitor]
 Monitor2 --> Success

 Success -->|Yes| Cleanup[ Decommission Auth Service]
 Success -->|No| Rollback[⏮ Rollback]

 Cleanup --> Complete([ Migration Hoàn Thành])
 Rollback --> End([ Migration Failed])

 style Start fill:#1a472a,stroke:#2d8659,stroke-width:3px,color:#fff
 style Complete fill:#1a472a,stroke:#2d8659,stroke-width:3px,color:#fff
 style End fill:#4a1a1a,stroke:#8b2e2e,stroke-width:3px,color:#fff
 style Backup fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Update fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Migrate fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Deploy fill:#4a2c5f,stroke:#6b4391,color:#fff
 style BlueGreen fill:#2d5016,stroke:#4a7c2c,color:#fff
 style InPlace fill:#5f4a1e,stroke:#8b7030,color:#fff
 style DeployNew fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Verify1 fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Switch fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Monitor1 fill:#1e3a5f,stroke:#2e5984,color:#fff
 style DeployBoth fill:#1e3a5f,stroke:#2e5984,color:#fff
 style GradualRoute fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Monitor2 fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Success fill:#4a2c5f,stroke:#6b4391,color:#fff
 style Cleanup fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Rollback fill:#4a1a1a,stroke:#8b2e2e,color:#fff

Architecture Evolution

graph TB
 subgraph Before["Auth Service (Trước)"]
 AuthAPI[ Authentication APIs<br/>/api/v1/auth/*]
 RBACAPI[ RBAC APIs<br/>/api/v1/rbac/*]
 MFAAPI[ MFA APIs<br/>/api/v1/mfa/*]
 SessionAPI[ Session APIs<br/>/api/v1/sessions/*]
 OIDCAPI[ OIDC APIs<br/>/api/v1/oidc/*]
 end

 subgraph After["IAM Service (Sau)"]
 AuthAPI2[ Authentication APIs<br/>/api/v1/auth/*<br/> Giữ nguyên]
 RBACAPI2[ RBAC APIs<br/>/api/v1/rbac/*<br/> Giữ nguyên]
 MFAAPI2[ MFA APIs<br/>/api/v1/mfa/*<br/> Giữ nguyên]
 SessionAPI2[ Session APIs<br/>/api/v1/sessions/*<br/> Giữ nguyên]
 OIDCAPI2[ OIDC APIs<br/>/api/v1/oidc/*<br/> Giữ nguyên]

 IdentityAPI[ Identity Management<br/>/api/v1/identity/*<br/> MỚI]
 AccessAPI[ Access Management<br/>/api/v1/access/*<br/> MỚI]
 GovernanceAPI[ Governance<br/>/api/v1/governance/*<br/> MỚI]
 end

 Before -.->|Backward Compatible<br/>Migration| After

 style Before fill:#2d2d2d,stroke:#4a4a4a,color:#fff
 style After fill:#1a472a,stroke:#2d8659,color:#fff
 style AuthAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style RBACAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style MFAAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style SessionAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style OIDCAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style AuthAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style RBACAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style MFAAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style SessionAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style OIDCAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style IdentityAPI fill:#4a2c5f,stroke:#6b4391,color:#fff
 style AccessAPI fill:#4a2c5f,stroke:#6b4391,color:#fff
 style GovernanceAPI fill:#4a2c5f,stroke:#6b4391,color:#fff

Backward Compatibility

Tất cả các endpoints hiện tại vẫn hoạt động bình thường:

• /api/v1/auth/* - Authentication endpoints
• /api/v1/rbac/* - RBAC endpoints
• /api/v1/mfa/* - MFA endpoints
• /api/v1/sessions/* - Session management endpoints
• /api/v1/oidc/* - OIDC endpoints

Không có breaking changes. Các clients hiện tại có thể tiếp tục sử dụng các endpoints này mà không cần thay đổi.

Các Thay Đổi

1. Service Name

• Cũ: auth-service
• Mới: iam-service

2. Package Name

• Cũ: @goodgo/auth-service
• Mới: @goodgo/iam-service

3. Database Schema

Database schema được mở rộng với các models mới nhưng không xóa hoặc thay đổi các models hiện có:

Models mới được thêm:

• Organization - Quản lý tổ chức
• Group - Quản lý nhóm
• GroupMember - Thành viên nhóm
• GroupPermission - Quyền nhóm
• UserProfile - Profile mở rộng
• IdentityVerification - Xác thực danh tính
• AccessRequest - Yêu cầu truy cập
• AccessReview - Đánh giá truy cập
• ComplianceReport - Báo cáo tuân thủ
• PolicyTemplate - Template policy
• RiskScore - Điểm rủi ro

User model được mở rộng:

• Thêm field organizationId (optional)
• Thêm các relations mới (optional)

4. API Endpoints Mới

Identity Management

• /api/v1/identity/users/* - User lifecycle management
• /api/v1/identity/users/:id/profile - Profile management
• /api/v1/identity/verification/* - Identity verification
• /api/v1/identity/organizations/* - Organization management
• /api/v1/identity/groups/* - Group management

Access Management

• /api/v1/access/requests/* - Access requests
• /api/v1/access/reviews/* - Access reviews
• /api/v1/access/analytics/* - Access analytics

Governance

• /api/v1/governance/compliance/* - Compliance reports
• /api/v1/governance/policies/* - Policy governance
• /api/v1/governance/risk/* - Risk management
• /api/v1/governance/reports/* - Reporting dashboard

5. Environment Variables

Một số biến môi trường mới có thể được thêm trong tương lai cho các tính năng IAM nâng cao (email service, SMS service, file storage), nhưng không ảnh hưởng đến các biến hiện tại.

6. Deployment Configuration

Docker Compose:

• Service name: auth-service → iam-service
• Container name: auth-service-local → iam-service-local

Kubernetes:

• Deployment name: auth-service → iam-service
• Service name: auth-service → iam-service
• ConfigMap: auth-service-config → iam-service-config
• Secrets: auth-service-secrets → iam-service-secrets

Migration Steps

Step 1: Backup (Quan Trọng!)

# Backup database
pg_dump $DATABASE_URL > auth-service-backup.sql

# Backup code (nếu cần rollback)
cp -r services/auth-service services/auth-service.backup

Step 2: Update Codebase

1. Update package references:

# Tìm và thay thế trong code
find . -type f -name "*.ts" -o -name "*.js" -o -name "*.json" | xargs sed -i '' 's/@goodgo\/auth-service/@goodgo\/iam-service/g'

2. Update environment variables:

• Update SERVICE_NAME=iam-service trong tất cả env files
• Update Docker Compose và Kubernetes configs

3. Run Prisma migration:

cd services/iam-service
pnpm prisma generate
pnpm prisma migrate dev --name add_iam_models

Step 3: Deployment

Deployment Strategy Comparison

graph LR
 subgraph BlueGreen[" Blue-Green Deployment (Khuyến nghị)"]
 BG1[Ưu điểm:<br/> Zero downtime<br/> Easy rollback<br/> Safe testing]
 BG2[Nhược điểm:<br/> Cần thêm resources<br/> Phức tạp hơn]
 end

 subgraph InPlace[" In-Place Migration"]
 IP1[Ưu điểm:<br/> Simple setup<br/> Less resources<br/> Gradual migration]
 IP2[Nhược điểm:<br/> Potential downtime<br/> Harder rollback<br/> Higher risk]
 end

 Decision{Chọn Strategy} -->|Production| BlueGreen
 Decision -->|Staging/Dev| InPlace

 style BlueGreen fill:#1a472a,stroke:#2d8659,color:#fff
 style InPlace fill:#5f4a1e,stroke:#8b7030,color:#fff
 style BG1 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style BG2 fill:#4a1a1a,stroke:#8b2e2e,color:#fff
 style IP1 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style IP2 fill:#4a1a1a,stroke:#8b2e2e,color:#fff
 style Decision fill:#4a2c5f,stroke:#6b4391,color:#fff

Option A: Blue-Green Deployment (Khuyến Nghị)

1. Deploy iam-service mới:

kubectl apply -f deployments/staging/kubernetes/iam-service.yaml

2. Verify iam-service hoạt động tốt

3. Switch traffic:

• Update Ingress để point đến iam-service
• Hoặc dùng weighted routing để gradually migrate

4. Monitor và verify

5. Decommission auth-service cũ sau khi verify

Option B: In-Place Migration

1. Deploy cả auth-service và iam-service cùng lúc

2. Gradually route traffic từ auth-service sang iam-service

3. Monitor performance và errors

4. Sau khi verify mọi thứ hoạt động tốt, có thể deprecate auth-service

Step 4: Rollback (Nếu Cần)

# Restore database
psql $DATABASE_URL < auth-service-backup.sql

# Switch back to auth-service in docker-compose
# hoặc
kubectl rollout undo deployment/auth-service

Verification Checklist

• All existing endpoints still work
• Database migration successful
• New IAM endpoints working
• No breaking changes in responses
• Performance metrics acceptable
• Error rates normal
• All clients can connect successfully

Troubleshooting

Database Migration Issues

# Check migration status
pnpm prisma migrate status

# Reset migration (DEV ONLY!)
pnpm prisma migrate reset

Service Connection Issues

# Check service health
curl http://localhost:5001/health

# Check logs
docker logs iam-service-local
# hoặc
kubectl logs deployment/iam-service

Support

Nếu gặp vấn đề trong quá trình migration, vui lòng:

1. Check logs và error messages
2. Review migration guide này
3. Contact team lead hoặc DevOps team

Quick Tips

Migration Best Practices

DO:

• Backup database trước khi migrate
• Test migration trên staging trước
• Monitor metrics trong quá trình migration
• Sử dụng Blue-Green deployment cho production
• Prepare rollback plan trước khi deploy
• Document tất cả các thay đổi

DON'T:

• Skip backup step
• Migrate trực tiếp trên production
• Ignore error logs
• Deploy vào giờ peak traffic
• Quên update environment variables
• Rush migration process

Common Issues & Solutions

Vấn đề	Nguyên nhân	Giải pháp
Migration failed	Database connection	Check DATABASE_URL trong .env
Service won't start	Missing env vars	Verify tất cả env vars được set
Slow performance	Database indexes	Run Prisma migrations đầy đủ
Connection timeout	Network issues	Check firewall & security groups
New endpoints 404	Routing config	Update Traefik/Ingress config

Troubleshooting Quick Reference

# Check migration status
pnpm prisma migrate status

# View service logs
docker logs iam-service-local -f
kubectl logs deployment/iam-service -f --tail=100

# Test health endpoint
curl http://localhost:5001/health
curl http://localhost:5001/health/ready

# Database connection test
psql $DATABASE_URL -c "SELECT 1"

# Rollback migration (CAREFUL!)
pnpm prisma migrate reset # DEV ONLY
kubectl rollout undo deployment/iam-service

Color Palette Reference

Diagram Colors:

• Success/Recommended: #1a472a (Dark green)
• Process/Info: #1e3a5f (Dark blue)
• Decision/Important: #4a2c5f (Dark purple)
• Warning/Alternative: #5f4a1e (Dark yellow)
• Error/Rollback: #4a1a1a (Dark red)

Important Reminders

• Always backup trước khi migrate
• Test thoroughly trên staging
• Monitor closely sau khi deploy
• Prepare rollback plan
• Document changes cho team
• ⏰ Schedule wisely - tránh giờ peak
• Communicate với team và stakeholders

---

Last Updated: 2024-12-30