ryanyao/freeleaps-pub
1
0
Fork 0
forked from freeleaps/freeleaps-pub
Code Pull Requests Activity
eb44c8ca1b
freeleaps-pub/devbox/cli/CICD_INTEGRATION.md

429 lines
12 KiB
Markdown
Raw Blame History

# CI/CD Integration with DevBox Packaging
## Overview
The DevBox packaging feature now includes comprehensive CI/CD integration that allows you to run your existing CI/CD integration tests locally before submitting code to your Jenkins pipeline. This ensures that the same tests that run in your CI/CD environment are executed locally, providing confidence that your code will pass the CI/CD pipeline.
## Why CI/CD Integration?
### Problem Statement
- **CI/CD Failures**: Code passes local tests but fails in CI/CD pipeline
- **Environment Differences**: Local and CI/CD environments are not identical
- **Test Inconsistency**: Different test suites run locally vs. in CI/CD
- **Late Detection**: Issues discovered only after code is committed and pushed
### Solution Benefits
- **Early Detection**: Catch CI/CD issues before committing code
- **Environment Parity**: Test in containers that match CI/CD environment
- **Test Consistency**: Run the same tests locally as in CI/CD
- **Confidence**: Ensure code will pass CI/CD pipeline
- **Time Saving**: Reduce CI/CD iteration cycles
## Architecture
### CI/CD Integration Components
#### 1. **Jenkins Pipeline Configuration Parser**
- Automatically detects and parses your Jenkinsfile
- Extracts component configurations (language, dependencies, build settings)
- Maps CI/CD test requirements to local execution
#### 2. **CI/CD Test Environment**
- Creates isolated Docker networks for testing
- Starts the same dependencies as your CI/CD pipeline
- Configures environment variables to match CI/CD
#### 3. **Component-Specific Test Execution**
- Runs health checks, API tests, and integration tests
- Executes performance tests for production mode
- Validates component functionality in CI/CD-like environment
#### 4. **Test Result Reporting**
- Provides detailed test results and logs
- Matches CI/CD test output format
- Identifies specific test failures
### Integration with Existing CI/CD Pipeline
```
Local Development → DevBox Package → CI/CD Tests → Jenkins Pipeline
↓ ↓ ↓ ↓
Code Changes Docker Container Test Results Production
```
## Usage Examples
### Basic CI/CD Integration
```bash
# Package with CI/CD integration tests
devbox package --run-cicd-tests=true
# Package specific component with CI/CD tests
devbox package --component=chat --run-cicd-tests=true
# Package for production with CI/CD tests
devbox package --test-mode=production --run-cicd-tests=true
```
### Advanced CI/CD Integration
```bash
# Package with both CI/CD and legacy integration tests
devbox package --run-cicd-tests=true --run-integration=true
# Package with custom image tag and CI/CD tests
devbox package --image-tag=v1.2.3 --run-cicd-tests=true
# Package specific component with production mode and CI/CD tests
devbox package --component=authentication --test-mode=production --run-cicd-tests=true
```
## Command Reference
### `devbox package` with CI/CD Integration
#### New Arguments
- `--run-cicd-tests, -j`: Run CI/CD integration tests after packaging (default: false)
#### Complete Argument List
- `--working-home, -w`: Working home directory (default: `$HOME/devbox`)
- `--image-repo, -r`: Docker image repository (default: `freeleaps-local`)
- `--image-tag, -t`: Docker image tag (default: timestamp)
- `--component, -c`: Component to package (default: all components)
- `--test-mode, -m`: Packaging mode: `test` or `production` (default: `test`)
- `--run-integration, -i`: Run legacy integration tests (default: false)
- `--run-cicd-tests, -j`: Run CI/CD integration tests (default: false)
## CI/CD Test Execution
### 1. Jenkins Configuration Parsing
The system automatically detects and parses your Jenkinsfile:
```bash
# Looks for Jenkinsfile in these locations:
# - $WORKING_HOME/freeleaps/Jenkinsfile
# - $WORKING_HOME/freeleaps/ci/Jenkinsfile
# - $WORKING_HOME/freeleaps/.jenkins/Jenkinsfile
# - $WORKING_HOME/freeleaps/apps/$component/Jenkinsfile
```
**Example Jenkinsfile Parsing:**
```groovy
// Your existing Jenkinsfile
components = [
[
name: 'chat',
language: 'python',
dependenciesManager: 'pip',
buildAgentImage: 'python:3.10-slim-buster',
lintEnabled: false,
sastEnabled: false
]
]
```
**Parsed Configuration:**
```bash
language:python
deps_manager:pip
build_image:python:3.10-slim-buster
lint_enabled:false
sast_enabled:false
```
### 2. CI/CD Test Environment Setup
The system creates a CI/CD-like test environment:
```bash
# Creates isolated test network
docker network create devbox-cicd-test-network
# Starts component-specific dependencies
# For chat, authentication, etc.:
# - MongoDB (mongodb:5.0)
# - Redis (redis:7-alpine)
# - RabbitMQ (rabbitmq:3-management)
# For devsvc:
# - MongoDB (mongodb:5.0)
```
### 3. Component-Specific Test Execution
Each component runs through a comprehensive test suite:
#### Health Check Tests
```python
# Tests component health endpoint
response = requests.get('http://localhost:8000/health', timeout=5)
assert response.status_code == 200
```
#### API Endpoint Tests
```python
# Tests common API endpoints
endpoints = ["/health", "/docs", "/openapi.json"]
for endpoint in endpoints:
response = requests.get(f'http://localhost:8000{endpoint}', timeout=5)
assert response.status_code in [200, 404] # 404 OK for optional endpoints
```
#### Integration Tests
```python
# Component-specific integration tests
# - Chat: Tests chat service connectivity
# - Authentication: Tests auth service functionality
# - Central Storage: Tests storage service operations
```
#### Performance Tests (Production Mode)
```python
# Load testing for production mode
response_times = []
for i in range(10):
start_time = time.time()
response = requests.get('http://localhost:8000/health', timeout=5)
if response.status_code == 200:
response_times.append(time.time() - start_time)
avg_time = statistics.mean(response_times)
max_time = max(response_times)
assert avg_time < 1.0 and max_time < 2.0
```
## Integration with Your Existing CI/CD Pipeline
### 1. **Jenkins Pipeline Compatibility**
The CI/CD integration is designed to work with your existing `first-class-pipeline` library:
```groovy
// Your existing Jenkinsfile remains unchanged
library 'first-class-pipeline'
executeFreeleapsPipeline {
serviceName = 'freeleaps'
environmentSlug = 'prod'
serviceGitBranch = 'master'
serviceGitRepo = "https://gitea.freeleaps.mathmast.com/freeleaps/freeleaps-service-hub.git"
serviceGitRepoType = 'monorepo'
serviceGitCredentialsId = 'freeleaps-repos-gitea-credentails'
executeMode = 'fully'
commitMessageLintEnabled = false
components = [
[
name: 'authentication',
root: 'apps/authentication',
language: 'python',
dependenciesManager: 'pip',
// ... other configuration
]
]
}
```
### 2. **Test Environment Parity**
The local CI/CD tests use the same:
- **Dependencies**: MongoDB, Redis, RabbitMQ versions
- **Environment Variables**: Service endpoints, credentials
- **Network Configuration**: Isolated Docker networks
- **Test Execution**: Health checks, API tests, integration tests
### 3. **Component Support**
Currently supported components:
- `chat` - Chat service with full dependency stack
- `authentication` - Authentication service with full dependency stack
- `central_storage` - Storage service with full dependency stack
- `content` - Content service with full dependency stack
- `notification` - Notification service with full dependency stack
- `payment` - Payment service with full dependency stack
- `devsvc` - DevSVC with MongoDB dependency
## Workflow Integration
### Typical Development Workflow with CI/CD Integration
1. **Local Development**
```bash
cd ~/devbox/freeleaps/apps/chat
# Make code changes
```
2. **Local Unit Testing**
```bash
python -m pytest tests/ -v
```
3. **CI/CD Integration Testing**
```bash
# Package and run CI/CD tests
devbox package --component=chat --run-cicd-tests=true
```
4. **Production Mode Testing**
```bash
# Test production-ready container
devbox package --component=chat --test-mode=production --run-cicd-tests=true
```
5. **Submit to CI/CD**
```bash
# If all tests pass, commit and push
git add .
git commit -m "Feature: Add new chat functionality"
git push
```
### CI/CD Pipeline Integration
Your Jenkins pipeline will now receive code that has been:
- ✅ Tested in production-like containers
- ✅ Validated with CI/CD integration tests
- ✅ Performance tested (if in production mode)
- ✅ Health checked and API tested
## Configuration and Customization
### 1. **Custom Test Configuration**
You can customize CI/CD test behavior by modifying the test functions:
```bash
# Edit the test functions in the devbox script
# - run_health_check_test()
# - run_api_endpoint_tests()
# - run_integration_tests()
# - run_performance_tests()
```
### 2. **Component-Specific Test Customization**
Add component-specific tests by extending the integration test functions:
```bash
# Add new component test function
run_custom_component_integration_tests() {
local container="$1"
local network="$2"
# Your custom test logic
docker exec "$container" python -c "
# Your custom test code
"
}
```
### 3. **Environment Variable Customization**
Customize environment variables for specific components:
```bash
# Modify setup_component_env_vars() function
case "$component" in
your_custom_component)
env_array+=(
"-e" "CUSTOM_VAR=value"
"-e" "ANOTHER_VAR=value"
)
;;
esac
```
## Troubleshooting
### Common CI/CD Integration Issues
1. **Jenkinsfile Not Found**
```
Warning: No Jenkinsfile found for component: chat
```
**Solution**: Ensure Jenkinsfile exists in one of the expected locations.
2. **Component Not Found in Jenkinsfile**
```
Warning: Component chat not found in Jenkinsfile
```
**Solution**: Check component name matches exactly in Jenkinsfile.
3. **CI/CD Test Dependencies Fail**
```
Error: MongoDB failed to start
```
**Solution**: Check Docker resources and network configuration.
4. **Health Check Failures**
```
Error: Health check failed for chat
```
**Solution**: Verify component health endpoint is implemented.
### Debugging CI/CD Tests
1. **Check Test Container Logs**
```bash
docker logs cicd-test-chat
```
2. **Inspect Test Network**
```bash
docker network inspect devbox-cicd-test-network
```
3. **Check Dependency Containers**
```bash
docker ps | grep cicd-
```
4. **Manual Test Execution**
```bash
# Run component manually for debugging
docker run -it --network devbox-cicd-test-network \
-e MONGODB_URI="mongodb://test:test@cicd-mongodb-chat:27017" \
your-image-name
```
## Best Practices
### 1. **CI/CD Test Development**
- Write tests that match your CI/CD pipeline requirements
- Use the same test data and configurations
- Implement proper cleanup and error handling
### 2. **Component Configuration**
- Ensure components have proper health endpoints
- Implement comprehensive API documentation
- Use consistent environment variable naming
### 3. **Test Execution**
- Run CI/CD tests before committing code
- Use production mode for final validation
- Monitor test execution time and performance
### 4. **Integration with Workflow**
- Add CI/CD tests to your development checklist
- Use CI/CD tests for pull request validation
- Integrate with your IDE or editor
## Future Enhancements
### Planned Features
1. **Multi-Component Testing**: Test multiple components together
2. **Custom Test Suites**: Support for custom test configurations
3. **Test Result Export**: Export test results in CI/CD format
4. **Performance Benchmarking**: Advanced performance testing
5. **Security Scanning**: Integrate security testing
### Integration Opportunities
1. **Git Hooks**: Pre-commit CI/CD test validation
2. **IDE Integration**: VS Code and IntelliJ plugins
3. **CI/CD Pipeline Integration**: Direct Jenkins integration
4. **Monitoring Integration**: Test result monitoring and alerting
## Conclusion
The CI/CD integration feature bridges the gap between local development and CI/CD pipeline execution by providing engineers with the ability to run the same tests locally that will run in their CI/CD environment. This significantly reduces CI/CD failures and improves development confidence.
By integrating your existing CI/CD integration tests into the DevBox packaging workflow, you can ensure that code is thoroughly tested before it reaches your Jenkins pipeline, leading to faster, more reliable deployments.
View Git Blame Copy Permalink