openshift-resource-governance/README-S2I.md

ORU Analyzer - Source-to-Image (S2I) Deployment

This document describes how to deploy ORU Analyzer using OpenShift Source-to-Image (S2I) as an alternative to container-based deployment.

🚀 S2I vs Container Build

Container Build (Current)

• Uses Dockerfile + Quay.io + GitHub Actions
• Manual build and push process
• More control over build process

Source-to-Image (S2I)

• Direct deployment from Git repository
• OpenShift manages build and deployment
• Simpler deployment process
• Automatic rebuilds on code changes

📋 Prerequisites

• OpenShift 4.x cluster
• OpenShift CLI (oc) installed and configured
• Access to the cluster with appropriate permissions
• Git repository access

🛠️ S2I Deployment Methods

Method 1: Using S2I Template (Recommended)

# 1. Login to OpenShift
oc login <cluster-url>

# 2. Deploy using S2I template
./scripts/deploy-s2i.sh

Method 2: Using oc new-app

# 1. Create namespace
oc new-project resource-governance

# 2. Deploy using oc new-app
oc new-app python:3.11~https://github.com/andersonid/openshift-resource-governance.git \
  --name=oru-analyzer \
  --env=PYTHON_VERSION=3.11 \
  --env=HOST=0.0.0.0 \
  --env=PORT=8080

# 3. Expose the application
oc expose service oru-analyzer

# 4. Get the route
oc get route oru-analyzer

Method 3: Using Template File

# 1. Process and apply template
oc process -f openshift-s2i.yaml \
  -p NAME=oru-analyzer \
  -p NAMESPACE=resource-governance \
  -p GIT_REPOSITORY=https://github.com/andersonid/openshift-resource-governance.git \
  -p GIT_REF=main \
  -p PYTHON_VERSION=3.11 \
  | oc apply -f -

# 2. Wait for deployment
oc rollout status deploymentconfig/oru-analyzer

📁 S2I File Structure

├── .s2i/
│   ├── environment          # S2I environment variables
│   └── bin/
│       ├── assemble         # Build script
│       └── run              # Runtime script
├── openshift-s2i.yaml      # OpenShift S2I template
├── scripts/
│   └── deploy-s2i.sh       # S2I deployment script
└── README-S2I.md           # This file

⚙️ Configuration

Environment Variables

The S2I configuration supports the following environment variables:

# Python Configuration
PYTHON_VERSION=3.11
PIP_INDEX_URL=https://pypi.org/simple

# Application Configuration
APP_NAME=oru-analyzer
HOST=0.0.0.0
PORT=8080
WORKERS=1

# Resource Configuration
CPU_REQUEST=100m
CPU_LIMIT=500m
MEMORY_REQUEST=256Mi
MEMORY_LIMIT=1Gi

# Health Check Configuration
HEALTH_CHECK_PATH=/health
HEALTH_CHECK_INTERVAL=30s
HEALTH_CHECK_TIMEOUT=10s
HEALTH_CHECK_RETRIES=3

Template Parameters

The OpenShift template supports the following parameters:

• NAME: Application name (default: oru-analyzer)
• NAMESPACE: OpenShift namespace (default: resource-governance)
• GIT_REPOSITORY: Git repository URL
• GIT_REF: Git reference/branch (default: main)
• PYTHON_VERSION: Python version (default: 3.11)
• CPU_REQUEST: CPU request (default: 100m)
• CPU_LIMIT: CPU limit (default: 500m)
• MEMORY_REQUEST: Memory request (default: 256Mi)
• MEMORY_LIMIT: Memory limit (default: 1Gi)
• REPLICAS: Number of replicas (default: 1)
• ROUTE_HOSTNAME: Custom route hostname (optional)

🔧 S2I Build Process

1. Assemble Phase

• Installs Python dependencies from requirements.txt
• Creates application directory structure
• Copies application files
• Sets proper permissions
• Creates startup script

2. Run Phase

• Sets environment variables
• Changes to application directory
• Starts the FastAPI application

📊 Monitoring and Debugging

Check Build Status

# List builds
oc get builds -n resource-governance

# View build logs
oc logs build/<build-name> -n resource-governance

# Watch build progress
oc logs -f buildconfig/oru-analyzer -n resource-governance

Check Application Status

# Check pods
oc get pods -n resource-governance

# Check deployment
oc get deploymentconfig -n resource-governance

# View application logs
oc logs -f deploymentconfig/oru-analyzer -n resource-governance

Check Routes

# List routes
oc get route -n resource-governance

# Get route URL
oc get route oru-analyzer -o jsonpath='{.spec.host}'

🔄 Automatic Rebuilds

S2I supports automatic rebuilds when:

1. Code Changes: Push to the Git repository
2. Config Changes: Update ConfigMap or environment variables
3. Image Changes: Update base Python image

Trigger Rebuild

# Manual rebuild
oc start-build oru-analyzer

# Rebuild from specific Git reference
oc start-build oru-analyzer --from-repo=https://github.com/andersonid/openshift-resource-governance.git --from-commit=main

🆚 S2I vs Container Build Comparison

Feature	S2I	Container Build
Deployment Speed	⚡ Fast	🐌 Slower
Build Control	🔒 Limited	🎛️ Full Control
Git Integration	✅ Native	❌ Manual
Auto Rebuilds	✅ Automatic	❌ Manual
Registry Dependency	❌ None	✅ Required
CI/CD Complexity	🟢 Simple	🟡 Complex
Debugging	🟡 Limited	🟢 Full Access
Custom Builds	❌ Limited	✅ Full Support

🚀 Quick Start

# 1. Clone repository
git clone https://github.com/andersonid/openshift-resource-governance.git
cd openshift-resource-governance

# 2. Login to OpenShift
oc login <cluster-url>

# 3. Deploy using S2I
./scripts/deploy-s2i.sh

# 4. Access application
# Get URL from output or run:
oc get route oru-analyzer -o jsonpath='{.spec.host}'

🐛 Troubleshooting

Common Issues

1. Build Fails

   # Check build logs
   oc logs build/<build-name>
   
   # Check build configuration
   oc describe buildconfig oru-analyzer
   

2. Application Won't Start

   # Check pod logs
   oc logs deploymentconfig/oru-analyzer
   
   # Check pod status
   oc describe pod <pod-name>
   

3. Route Not Accessible

   # Check route configuration
   oc describe route oru-analyzer
   
   # Check service
   oc get svc oru-analyzer
   

Debug Commands

# Get all resources
oc get all -n resource-governance

# Check events
oc get events -n resource-governance

# Check build configuration
oc describe buildconfig oru-analyzer

# Check deployment configuration
oc describe deploymentconfig oru-analyzer

📚 Additional Resources

• OpenShift Source-to-Image Documentation
• Python S2I Builder
• OpenShift Templates

🤝 Contributing

To contribute to the S2I configuration:

1. Modify .s2i/environment for environment variables
2. Update .s2i/bin/assemble for build process
3. Update .s2i/bin/run for runtime behavior
4. Modify openshift-s2i.yaml for OpenShift resources
5. Test with ./scripts/deploy-s2i.sh

---

Note: S2I deployment is an alternative to the standard container build process. Both methods are supported and can be used interchangeably based on your requirements.