Files

Ho Ngoc Hai 9ba4a478ee feat(docs): Enhance deployment and development guides with improved clarity and structure

- Updated Mermaid diagrams in the deployment and development guides for better visual representation and consistency.
- Improved formatting and clarity in the Kubernetes local deployment and IAM migration guides, including detailed workflows and troubleshooting sections.
- Enhanced the Vietnamese documentation to align with the English version, ensuring consistency across guides.
- Added quick tips and common issues sections to facilitate user navigation and understanding.

2026-01-08 17:10:06 +07:00

11 KiB

Raw Blame History

Migration Guide: Auth Service → IAM Service

This document guides you through migrating from auth-service to iam-service.

Overview

IAM Service is an extended version of Auth Service with additional features for Identity Management, Access Management, and Governance & Compliance. All Auth Service API endpoints remain unchanged to ensure backward compatibility.

Migration Workflow

graph LR
 Start([Start Migration]) --> Backup[ Backup]
 Backup --> DBMigrate[ Database Migration]
 DBMigrate --> UpdateDeps[ Update Dependencies]
 UpdateDeps --> Deploy[ Deploy]
 Deploy --> Verify[ Verify]
 Verify --> Decision{All Tests Pass?}
 Decision -->|Yes| Rollout[ Gradual Rollout]
 Decision -->|No| Rollback[⏮ Rollback]
 Rollback --> Debug[ Debug Issues]
 Debug --> DBMigrate
 Rollout --> Monitor[ Monitor]
 Monitor --> Complete([ Complete])

 style Start fill:#2d4263,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Backup fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style DBMigrate fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style UpdateDeps fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style Deploy fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Verify fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Decision fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Rollout fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style Rollback fill:#742a2a,stroke:#f56565,stroke-width:2px,color:#f5f5f5
 style Debug fill:#742a2a,stroke:#f56565,stroke-width:2px,color:#f5f5f5
 style Monitor fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Complete fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5

Backward Compatibility

All existing endpoints continue to work normally:

/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

No breaking changes. Existing clients can continue using these endpoints without any modifications.

Architecture Comparison

graph TB
 subgraph "Auth Service (Old)"
 A1[Authentication]
 A2[RBAC]
 A3[MFA]
 A4[Sessions]
 A5[OIDC]
 end

 subgraph "IAM Service (New)"
 B1[Authentication]
 B2[RBAC]
 B3[MFA]
 B4[Sessions]
 B5[OIDC]
 B6[Identity Management]
 B7[Access Management]
 B8[Governance]
 end

 A1 -.->|Unchanged| B1
 A2 -.->|Unchanged| B2
 A3 -.->|Unchanged| B3
 A4 -.->|Unchanged| B4
 A5 -.->|Unchanged| B5

 style A1 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A2 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A3 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A4 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A5 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5

 style B1 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B2 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B3 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B4 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B5 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B6 fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style B7 fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style B8 fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5

Changes

1. Service Name

Old: auth-service
New: iam-service

2. Package Name

Old: @goodgo/auth-service
New: @goodgo/iam-service

3. Database Schema

Database schema is extended with new models but does not delete or modify existing models:

New models added:

Organization - Organization management
Group - Group management
GroupMember - Group members
GroupPermission - Group permissions
UserProfile - Extended profile
IdentityVerification - Identity verification
AccessRequest - Access requests
AccessReview - Access reviews
ComplianceReport - Compliance reports
PolicyTemplate - Policy templates
RiskScore - Risk scores

User model extended:

Added organizationId field (optional)
Added new relations (optional)

erDiagram
 User ||--o{ UserProfile : has
 User ||--o{ AccessRequest : creates
 User }o--|| Organization : "belongs to"
 User ||--o{ GroupMember : "member of"

 Organization ||--o{ Group : contains
 Group ||--o{ GroupMember : has
 Group ||--o{ GroupPermission : has

 AccessRequest ||--|| AccessReview : "reviewed by"
 Organization ||--o{ ComplianceReport : generates

 User {
 string id PK
 string email
 string organizationId FK
 }

 Organization {
 string id PK
 string name
 }

 Group {
 string id PK
 string organizationId FK
 }

 UserProfile {
 string userId FK
 json metadata
 }

 AccessRequest {
 string id PK
 string userId FK
 }

4. New API Endpoints

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

Some new environment variables may be added in the future for advanced IAM features (email service, SMS service, file storage), but they will not affect existing variables.

6. Deployment Configuration

Docker Compose:

Service name: auth-service → iam-service
Container name: auth-service-local → iam-service-local
Traefik labels: Add new routes for /api/v1/identity/*, /api/v1/access/*, /api/v1/governance/*

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

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

# Backup code
cp -r services/auth-service services/auth-service.backup

Step 2: Database Migration

cd services/iam-service

# Generate Prisma client with new schema
pnpm prisma generate

# Create migration
pnpm prisma migrate dev --name add_iam_models

# Verify migration
pnpm prisma studio # Check database structure

Step 3: Update Dependencies

# Install dependencies (if new packages exist)
pnpm install

# Verify types compile
pnpm typecheck

Step 4: Update Deployment

Local Development:

cd deployments/local
# Update docker-compose.yml (already updated)
docker-compose up -d iam-service

Staging/Production:

Update Kubernetes manifests
Update ingress routes
Update ConfigMaps and Secrets

Step 5: Verify Backward Compatibility

Test that all old endpoints still work:

# Test auth endpoints
curl http://localhost/api/v1/auth/me

# Test RBAC endpoints
curl http://localhost/api/v1/rbac/permissions

# Test MFA endpoints
curl http://localhost/api/v1/mfa/devices

Step 6: Gradual Rollout

Dual Deployment (Optional):

Deploy both auth-service and iam-service simultaneously
Gradually route traffic to iam-service
Monitor errors and performance

Update Clients:

Update clients to use new endpoints if needed
Clients don't need updates if only using old endpoints

Deprecate Old Service:

After verifying everything works well, deprecate auth-service
Ensure all clients have migrated to iam-service

Deployment Strategy

graph TB
 Current[Current: auth-service] --> Phase1[Phase 1: Dual Deploy]
 Phase1 --> Split{Traffic Split}
 Split -->|10%| IAM1[iam-service]
 Split -->|90%| Auth1[auth-service]

 Split --> Phase2[Phase 2: Increase]
 Phase2 --> Split2{Traffic Split}
 Split2 -->|50%| IAM2[iam-service]
 Split2 -->|50%| Auth2[auth-service]

 Split2 --> Phase3[Phase 3: Majority]
 Phase3 --> Split3{Traffic Split}
 Split3 -->|90%| IAM3[iam-service]
 Split3 -->|10%| Auth3[auth-service]

 Split3 --> Phase4[Phase 4: Complete]
 Phase4 --> Final[iam-service only]

 style Current fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style Phase1 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Phase2 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Phase3 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Phase4 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Final fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style Split fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Split2 fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Split3 fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style IAM1 fill:#1a472a,stroke:#48bb78,stroke-width:1px,color:#f5f5f5
 style IAM2 fill:#1a472a,stroke:#48bb78,stroke-width:1px,color:#f5f5f5
 style IAM3 fill:#1a472a,stroke:#48bb78,stroke-width:1px,color:#f5f5f5
 style Auth1 fill:#742a2a,stroke:#f56565,stroke-width:1px,color:#f5f5f5
 style Auth2 fill:#742a2a,stroke:#f56565,stroke-width:1px,color:#f5f5f5
 style Auth3 fill:#742a2a,stroke:#f56565,stroke-width:1px,color:#f5f5f5

Rollback Plan

If rollback is needed:

Database Rollback:

# Revert Prisma migration
cd services/iam-service
pnpm prisma migrate resolve --rolled-back <migration_name>

# Or restore from backup
psql $DATABASE_URL < auth-service-backup.sql

Service Rollback:

# Switch back to auth-service in docker-compose
# Or revert Kubernetes deployment
kubectl rollout undo deployment/auth-service

Breaking Changes

No breaking changes in this migration. All existing API endpoints and database models are preserved.

Notes

This migration is additive - only adds new features, does not remove or change existing ones
Database migrations are non-destructive - do not delete or modify existing data
Clients can continue using old endpoints without any changes

Support

If you encounter issues during migration:

Check logs: docker-compose logs iam-service
Verify database connection
Check environment variables
Review error messages and stack traces

Quick Tips

Migration Checklist:

Backup database and code
Run database migrations
Update deployment configuration
Test backward compatibility
Monitor gradual rollout
Prepare rollback plan

Common Issues & Solutions

Issue	Cause	Solution
Migration failed	Database connection	Check `DATABASE_URL` in `.env`
Service won't start	Missing env vars	Verify all env vars are set
Slow performance	Database indexes	Run Prisma migrations completely
Connection timeout	Network issues	Check firewall & security groups
New endpoints 404	Routing config	Update Traefik/Ingress config

Visual Indicators:

Old Components (Unchanged)
New Components (Added)
Components to Deprecate
Requires Attention

11 KiB Raw Blame History