will/adopt-a-street
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update deployment guide to be namespace-agnostic

Browse Source 
- Remove hardcoded namespace references from all commands
- Add comprehensive namespace selection guidance
- Update examples to show -n <namespace> 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 <noreply@ai-assistant.com>
This commit is contained in:
William Valentin
2025-11-02 01:32:04 -08:00
parent 00133d5e43
commit 6abf1735c9
1 changed files with 174 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
deploy/k8s/DEPLOYMENT_GUIDE.md
View File

@@ -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-<username>` 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 <your-namespace>
# Set as default namespace for current context
kubectl config set-context --current --namespace=<your-namespace>
# Or switch namespaces temporarily
kubectl namespace <your-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 <your-namespace> 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=<your-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 <your-namespace>
# Apply Secrets
kubectl apply -f deploy/k8s/secrets.yaml
# Or apply individually for more control:
kubectl apply -f deploy/k8s/configmap.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/secrets.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/couchdb-statefulset.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/backend-deployment.yaml -n <your-namespace>
kubectl apply -f deploy/k8s/frontend-deployment.yaml -n <your-namespace>
# 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 <your-namespace>
# Check services
kubectl get services -n adopt-a-street
# Check services in your namespace
kubectl get services -n <your-namespace>
# 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 <your-namespace>
# Check logs for specific deployments
kubectl logs -n <your-namespace> deployment/adopt-a-street-backend
kubectl logs -n <your-namespace> deployment/adopt-a-street-frontend
# Watch pod status
kubectl get pods -n <your-namespace> -w
# Check resource usage
kubectl top pods -n <your-namespace>
```
## 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=<your-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 <your-namespace>
# 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 <your-namespace> --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 <your-namespace> -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 <your-namespace>
# Debug image pull errors
kubectl describe pod -l app=adopt-a-street-backend -n <your-namespace>
```
### 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 <your-namespace> 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 <your-namespace> \
-- curl http://adopt-a-street-couchdb:5984/_up
# Check CouchDB service
kubectl get service adopt-a-street-couchdb -n <your-namespace>
kubectl describe service adopt-a-street-couchdb -n <your-namespace>
```
### 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 <your-namespace> \
-- 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 <your-namespace> \
-- curl http://localhost:80/health
# Check pod events for health check failures
kubectl describe pod -l app=adopt-a-street-backend -n <your-namespace>
```
### 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=<your-namespace>
# View current context and namespace
kubectl config current-context
kubectl config view --minify
# Get resources in specific format
kubectl get pods -n <your-namespace> -o wide
kubectl get services -n <your-namespace> -o yaml
# Port forwarding for debugging
kubectl port-forward -n <your-namespace> service/adopt-a-street-backend 5000:5000
kubectl port-forward -n <your-namespace> service/adopt-a-street-frontend 3000:80
# Exec into pods for debugging
kubectl exec -it -n <your-namespace> deployment/adopt-a-street-backend -- /bin/bash
kubectl exec -it -n <your-namespace> deployment/adopt-a-street-frontend -- /bin/sh
```