From ec4dfbb2efc5544bdd100914be509461e47bebfe Mon Sep 17 00:00:00 2001 From: andersonid Date: Sat, 4 Oct 2025 09:12:56 -0300 Subject: [PATCH] Consolidate documentation - remove duplicate README-S2I.md - Delete README-S2I.md (unnecessary duplicate) - Keep all documentation in main README.md - Update reference to point to S2I section in main README - Maintain single source of truth for documentation - Reduce repository clutter and maintenance overhead --- README-S2I.md | 295 -------------------------------------------------- README.md | 2 +- 2 files changed, 1 insertion(+), 296 deletions(-) delete mode 100644 README-S2I.md diff --git a/README-S2I.md b/README-S2I.md deleted file mode 100644 index b62f91e..0000000 --- a/README-S2I.md +++ /dev/null @@ -1,295 +0,0 @@ -# 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) - -```bash -# 1. Login to OpenShift -oc login - -# 2. Deploy using S2I template -./scripts/deploy-s2i.sh -``` - -### Method 2: Using oc new-app - -```bash -# 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 - -```bash -# 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: - -```bash -# 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 -```bash -# List builds -oc get builds -n resource-governance - -# View build logs -oc logs build/ -n resource-governance - -# Watch build progress -oc logs -f buildconfig/oru-analyzer -n resource-governance -``` - -### Check Application Status -```bash -# 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 -```bash -# 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 -```bash -# 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 - -```bash -# 1. Clone repository -git clone https://github.com/andersonid/openshift-resource-governance.git -cd openshift-resource-governance - -# 2. Login to OpenShift -oc login - -# 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** - ```bash - # Check build logs - oc logs build/ - - # Check build configuration - oc describe buildconfig oru-analyzer - ``` - -2. **Application Won't Start** - ```bash - # Check pod logs - oc logs deploymentconfig/oru-analyzer - - # Check pod status - oc describe pod - ``` - -3. **Route Not Accessible** - ```bash - # Check route configuration - oc describe route oru-analyzer - - # Check service - oc get svc oru-analyzer - ``` - -### Debug Commands - -```bash -# 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](https://docs.openshift.com/container-platform/4.15/builds/build-strategies.html#builds-strategy-s2i_build-strategies) -- [Python S2I Builder](https://github.com/sclorg/s2i-python-container) -- [OpenShift Templates](https://docs.openshift.com/container-platform/4.15/openshift_images/using-templates.html) - -## 🤝 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. diff --git a/README.md b/README.md index 9621d67..fe0d137 100644 --- a/README.md +++ b/README.md @@ -346,7 +346,7 @@ oc new-app python:3.11~https://github.com/andersonid/openshift-resource-governan --name=oru-analyzer --env=PYTHON_VERSION=3.11 ``` -For detailed S2I documentation, see [README-S2I.md](README-S2I.md). +For detailed S2I deployment information, see the S2I section above. ### Tests ```bash