From 6abf1735c9f4e24b549ba7ae8375d9001f95d7ad Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sun, 2 Nov 2025 01:32:04 -0800 Subject: [PATCH] docs: update deployment guide to be namespace-agnostic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove hardcoded namespace references from all commands - Add comprehensive namespace selection guidance - Update examples to show -n parameter - Add multi-environment deployment strategies - Include troubleshooting section for namespace-related issues - Provide examples for dev, staging, and prod environments - Add common commands reference for namespace management 🤖 Generated with [AI Assistant] Co-Authored-By: AI Assistant --- deploy/k8s/DEPLOYMENT_GUIDE.md | 204 ++++++++++++++++++++++++++++----- 1 file changed, 174 insertions(+), 30 deletions(-) diff --git a/deploy/k8s/DEPLOYMENT_GUIDE.md b/deploy/k8s/DEPLOYMENT_GUIDE.md index 483ad87..35963da 100644 --- a/deploy/k8s/DEPLOYMENT_GUIDE.md +++ b/deploy/k8s/DEPLOYMENT_GUIDE.md @@ -1,7 +1,34 @@ # CouchDB Deployment Configuration Guide ## Overview -This guide covers the configuration changes needed to deploy Adopt-a-Street with CouchDB on the Raspberry Pi Kubernetes cluster. +This guide covers the configuration changes needed to deploy Adopt-a-Street with CouchDB on the Raspberry Pi Kubernetes cluster. The manifests are namespace-agnostic and can be deployed to any namespace of your choice. + +## Namespace Selection + +### Choosing a Namespace +Before deploying, decide which namespace to use: +- **Development**: `adopt-a-street-dev` or `dev` +- **Staging**: `adopt-a-street-staging` or `staging` +- **Production**: `adopt-a-street-prod` or `prod` +- **Personal**: `adopt-a-street-` for individual developers + +### Namespace Best Practices +- Use descriptive names that indicate environment purpose +- Keep environments isolated in separate namespaces +- Use consistent naming conventions across teams +- Consider using prefixes like `adopt-a-street-` for clarity + +### Creating a Namespace +```bash +# Create a new namespace +kubectl create namespace + +# Set as default namespace for current context +kubectl config set-context --current --namespace= + +# Or switch namespaces temporarily +kubectl namespace +``` ## Changes Made @@ -41,42 +68,65 @@ This guide covers the configuration changes needed to deploy Adopt-a-Street with ### 1. Create Image Pull Secret ```bash # Replace YOUR_GITEA_PASSWORD with your actual Gitea password +# Replace with your chosen namespace kubectl create secret docker-registry regcred \ --docker-server=gitea-http.taildb3494.ts.net \ --docker-username=will \ --docker-password=YOUR_GITEA_PASSWORD \ - --namespace=adopt-a-street + --namespace= + +# Examples: +kubectl create secret docker-registry regcred \ + --docker-server=gitea-http.taildb3494.ts.net \ + --docker-username=will \ + --docker-password=YOUR_GITEA_PASSWORD \ + --namespace=adopt-a-street-dev + +kubectl create secret docker-registry regcred \ + --docker-server=gitea-http.taildb3494.ts.net \ + --docker-username=will \ + --docker-password=YOUR_GITEA_PASSWORD \ + --namespace=adopt-a-street-prod ``` ### 2. Apply Configuration ```bash -# Apply ConfigMap -kubectl apply -f deploy/k8s/configmap.yaml +# Apply all manifests to your chosen namespace +kubectl apply -f deploy/k8s/ -n -# Apply Secrets -kubectl apply -f deploy/k8s/secrets.yaml +# Or apply individually for more control: +kubectl apply -f deploy/k8s/configmap.yaml -n +kubectl apply -f deploy/k8s/secrets.yaml -n +kubectl apply -f deploy/k8s/couchdb-statefulset.yaml -n +kubectl apply -f deploy/k8s/backend-deployment.yaml -n +kubectl apply -f deploy/k8s/frontend-deployment.yaml -n -# Apply CouchDB StatefulSet -kubectl apply -f deploy/k8s/couchdb-statefulset.yaml - -# Apply Backend Deployment -kubectl apply -f deploy/k8s/backend-deployment.yaml - -# Apply Frontend Deployment -kubectl apply -f deploy/k8s/frontend-deployment.yaml +# Examples for different environments: +kubectl apply -f deploy/k8s/ -n adopt-a-street-dev +kubectl apply -f deploy/k8s/ -n adopt-a-street-staging +kubectl apply -f deploy/k8s/ -n adopt-a-street-prod ``` ### 3. Verify Deployment ```bash -# Check all pods -kubectl get pods -n adopt-a-street +# Check all pods in your namespace +kubectl get pods -n -# Check services -kubectl get services -n adopt-a-street +# Check services in your namespace +kubectl get services -n -# Check logs -kubectl logs -n adopt-a-street deployment/adopt-a-street-backend -kubectl logs -n adopt-a-street deployment/adopt-a-street-frontend +# Check all resources in your namespace +kubectl get all -n + +# Check logs for specific deployments +kubectl logs -n deployment/adopt-a-street-backend +kubectl logs -n deployment/adopt-a-street-frontend + +# Watch pod status +kubectl get pods -n -w + +# Check resource usage +kubectl top pods -n ``` ## Environment Variables Summary @@ -128,29 +178,123 @@ kubectl logs -n adopt-a-street deployment/adopt-a-street-frontend ## Troubleshooting +### Namespace-Related Issues + +#### Wrong Namespace +```bash +# List all namespaces +kubectl get namespaces + +# Check current namespace context +kubectl config view --minify | grep namespace + +# Switch to correct namespace +kubectl config set-context --current --namespace= + +# Check resources across all namespaces +kubectl get pods --all-namespaces | grep adopt-a-street +``` + +#### Resources Not Found +```bash +# Verify resources exist in your namespace +kubectl get all -n + +# Check if resources are in a different namespace +kubectl get all --all-namespaces | grep adopt-a-street + +# Get events from your namespace +kubectl get events -n --sort-by='.lastTimestamp' +``` + ### Image Pull Issues ```bash -# Verify image pull secret -kubectl get secret regcred -n adopt-a-street -o yaml +# Verify image pull secret in your namespace +kubectl get secret regcred -n -o yaml -# Test image pull -kubectl run test-pod --image=gitea-http.taildb3494.ts.net:will/adopt-a-street/backend:latest --dry-run=client -o yaml +# Test image pull in your namespace +kubectl run test-pod --image=gitea-http.taildb3494.ts.net:will/adopt-a-street/backend:latest \ + --dry-run=client -o yaml -n + +# Debug image pull errors +kubectl describe pod -l app=adopt-a-street-backend -n ``` ### CouchDB Connection Issues ```bash -# Check CouchDB pod -kubectl logs -n adopt-a-street statefulset/adopt-a-street-couchdb +# Check CouchDB pod in your namespace +kubectl logs -n statefulset/adopt-a-street-couchdb # Test connection from backend pod -kubectl exec -it deployment/adopt-a-street-backend -- curl http://adopt-a-street-couchdb:5984/_up +kubectl exec -it deployment/adopt-a-street-backend -n \ + -- curl http://adopt-a-street-couchdb:5984/_up + +# Check CouchDB service +kubectl get service adopt-a-street-couchdb -n +kubectl describe service adopt-a-street-couchdb -n ``` ### Health Check Failures ```bash # Check backend health endpoint -kubectl exec -it deployment/adopt-a-street-backend -- curl http://localhost:5000/api/health +kubectl exec -it deployment/adopt-a-street-backend -n \ + -- curl http://localhost:5000/api/health # Check frontend health endpoint -kubectl exec -it deployment/adopt-a-street-frontend -- curl http://localhost:80/health +kubectl exec -it deployment/adopt-a-street-frontend -n \ + -- curl http://localhost:80/health + +# Check pod events for health check failures +kubectl describe pod -l app=adopt-a-street-backend -n +``` + +### Multi-Environment Deployment + +#### Deploying to Multiple Namespaces +```bash +# Deploy to development +kubectl apply -f deploy/k8s/ -n adopt-a-street-dev + +# Deploy to staging +kubectl apply -f deploy/k8s/ -n adopt-a-street-staging + +# Deploy to production +kubectl apply -f deploy/k8s/ -n adopt-a-street-prod + +# Compare deployments across namespaces +kubectl get deployments --all-namespaces | grep adopt-a-street +``` + +#### Environment-Specific Configuration +```bash +# Create environment-specific secrets +kubectl create secret generic jwt-secret-dev --from-literal=JWT_SECRET=$(openssl rand -base64 32) -n adopt-a-street-dev +kubectl create secret generic jwt-secret-prod --from-literal=JWT_SECRET=$(openssl rand -base64 32) -n adopt-a-street-prod + +# Patch ConfigMaps for different environments +kubectl patch configmap adopt-a-street-config -n adopt-a-street-prod \ + --patch '{"data":{"NODE_ENV":"production"}}' +``` + +### Common Commands Reference + +```bash +# Set default namespace for current session +kubectl config set-context --current --namespace= + +# View current context and namespace +kubectl config current-context +kubectl config view --minify + +# Get resources in specific format +kubectl get pods -n -o wide +kubectl get services -n -o yaml + +# Port forwarding for debugging +kubectl port-forward -n service/adopt-a-street-backend 5000:5000 +kubectl port-forward -n service/adopt-a-street-frontend 3000:80 + +# Exec into pods for debugging +kubectl exec -it -n deployment/adopt-a-street-backend -- /bin/bash +kubectl exec -it -n deployment/adopt-a-street-frontend -- /bin/sh ``` \ No newline at end of file