bakery-ia/infrastructure/NAMESPACES.md

# 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