Initial commit - production deployment

infrastructure/NAMESPACES.md

@@ -0,0 +1,119 @@
+# Bakery-IA Namespace Management
+
+## Overview
+
+This document explains the namespace strategy for the Bakery-IA platform and how to properly manage namespaces during deployment.
+
+## Namespace Architecture
+
+The Bakery-IA platform uses the following namespaces:
+
+### Core Namespaces
+
+1. **`bakery-ia`** - Main application namespace
+   - Contains all microservices, databases, and application components
+   - Defined in: `infrastructure/namespaces/bakery-ia.yaml`
+
+2. **`tekton-pipelines`** - CI/CD pipeline namespace
+   - Contains Tekton pipeline resources, tasks, and triggers
+   - Defined in: `infrastructure/namespaces/tekton-pipelines.yaml`
+
+3. **`flux-system`** - GitOps namespace
+   - Contains Flux CD components for GitOps deployments
+   - Now defined in Helm chart: `infrastructure/cicd/flux/templates/namespace.yaml`
+
+### Infrastructure Namespaces
+
+Additional namespaces may be created for:
+- Monitoring components
+- Logging components
+- Security components
+
+## Deployment Order
+
+**CRITICAL**: Namespaces must be created BEFORE any resources that depend on them.
+
+### Correct Deployment Sequence
+
+```bash
+# 1. Create namespaces first
+kubectl apply -f infrastructure/namespaces/
+
+# 2. Apply common configurations (depends on bakery-ia namespace)
+kubectl apply -f infrastructure/environments/common/configs/
+
+# 3. Apply platform components
+kubectl apply -f infrastructure/platform/
+
+# 4. Apply CI/CD components (depends on tekton-pipelines)
+kubectl apply -f infrastructure/cicd/
+
+# 5. Apply monitoring components
+kubectl apply -f infrastructure/monitoring/
+```
+
+## Common Issues and Solutions
+
+### Issue: "namespace not found" errors
+
+**Symptoms**: Errors like:
+```
+Error from server (NotFound): error when creating "path/to/resource.yaml": namespaces "[namespace-name]" not found
+```
+
+**Solutions**:
+
+1. **Ensure namespaces are created first** - Use the deployment script that applies namespaces before other resources
+
+2. **Check for templating issues** - If you see names like `[redacted secret rabbitmq-secrets:RABBITMQ_USER]-ia`, there may be environment variable substitution happening incorrectly
+
+3. **Verify namespace YAML files** - Ensure the namespace files exist and are properly formatted
+
+### Issue: Resource conflicts across namespaces
+
+**Solution**: Use proper namespace isolation and RBAC policies to prevent cross-namespace conflicts.
+
+## Best Practices
+
+1. **Namespace Isolation**: Keep resources properly isolated by namespace
+2. **RBAC**: Use namespace-specific RBAC roles and bindings
+3. **Resource Quotas**: Apply resource quotas per namespace
+4. **Network Policies**: Use network policies to control cross-namespace communication
+
+## Troubleshooting
+
+### Verify namespaces exist
+
+```bash
+kubectl get namespaces
+```
+
+### Check namespace labels
+
+```bash
+kubectl get namespace bakery-ia --show-labels
+```
+
+### View namespace events
+
+```bash
+kubectl describe namespace bakery-ia
+```
+
+## Migration from Old Structure
+
+If you're migrating from the old structure where namespaces were scattered across different directories:
+
+1. **Remove old namespace files** from:
+   - `infrastructure/environments/common/configs/namespace.yaml`
+   - `infrastructure/cicd/flux/namespace.yaml`
+
+2. **Update kustomization files** to reference the centralized namespace files
+
+3. **Use the new deployment script** that follows the correct order
+
+## Future Enhancements
+
+- Add namespace lifecycle management
+- Implement namespace cleanup scripts
+- Add namespace validation checks to CI/CD pipelines