rxminder/k8s-kustomize/README.md

# Kustomize Deployment Configuration

This directory contains the Kustomize configuration for deploying the rxminder (Medication Reminder) application to Kubernetes. Kustomize provides a template-free way to customize application configuration that simplifies the use of off-the-shelf applications.

## Directory Structure

```
k8s-kustomize/
├── base/                          # Base configuration (shared resources)
│   ├── kustomization.yaml         # Base kustomization file
│   ├── config.env                 # Environment variables for ConfigMap
│   ├── registry-config.json       # Docker registry configuration
│   ├── frontend-deployment.yaml   # Frontend deployment
│   ├── frontend-service.yaml      # Frontend service
│   ├── couchdb-statefulset.yaml   # CouchDB database
│   ├── couchdb-service.yaml       # CouchDB service
│   ├── couchdb-pvc.yaml           # CouchDB persistent volume
│   ├── configmap.yaml             # Application configuration
│   ├── ingress.yaml               # Ingress configuration
│   ├── network-policy.yaml        # Network policies
│   ├── hpa.yaml                   # Horizontal Pod Autoscaler
│   └── db-seed-job.yaml           # Database seeding job
├── overlays/                      # Environment-specific overrides
│   ├── dev/                       # Development environment
│   │   └── kustomization.yaml     # Development customizations
│   └── prod/                      # Production environment
│       ├── kustomization.yaml     # Production customizations
│       ├── frontend-resources.yaml # Production frontend resources
│       ├── couchdb-resources.yaml # Production database resources
│       └── ingress-prod.yaml      # Production ingress config
└── README.md                      # This file
```

## Quick Start

### Prerequisites

1. **kubectl** installed and configured
2. **Kubernetes cluster** access
3. **Docker images** built and pushed to registry

### Deploy to Development

```bash
# Using Makefile (recommended)
make deploy-dev

# Or directly with kubectl
kubectl apply -k k8s-kustomize/overlays/dev
```

### Deploy to Production

```bash
# Using Makefile (recommended)
make deploy-prod

# Or directly with kubectl
kubectl apply -k k8s-kustomize/overlays/prod
```

## Environment Configurations

### Development Environment

- **Namespace**: `rxminder-dev`
- **Replicas**: 1 frontend pod
- **Resources**: Minimal (16Mi-32Mi memory)
- **Image Tag**: `dev`
- **Domain**: `rxminder-dev.local`
- **Storage**: 1Gi
- **Security**: Relaxed for development

### Production Environment

- **Namespace**: `rxminder-prod`
- **Replicas**: 3 frontend pods (high availability)
- **Resources**: Production-grade (256Mi-512Mi memory)
- **Image Tag**: `v1.0.0` (semantic versioning)
- **Domain**: `rxminder.yourdomain.com`
- **Storage**: 10Gi SSD
- **Security**: Hardened with security contexts, network policies
- **TLS**: Enabled with cert-manager
- **Monitoring**: Enabled

## Makefile Commands

### Deployment Commands

```bash
# Development
make deploy-dev              # Deploy to development
make undeploy-dev           # Remove development deployment
make quick-deploy-dev       # Build and deploy to development
make status-dev             # Show development status

# Production
make deploy-prod            # Deploy to production
make undeploy-prod          # Remove production deployment
make quick-deploy-prod      # Build and deploy to production
make status-prod            # Show production status
```

### Validation Commands

```bash
make validate-kustomize     # Validate all configurations
make kustomize-validate-dev # Validate development config
make kustomize-validate-prod # Validate production config
```

### Debugging Commands

```bash
make kustomize-dry-run-dev  # Dry run development deployment
make kustomize-dry-run-prod # Dry run production deployment
make kustomize-diff-dev     # Show differences for development
make kustomize-diff-prod    # Show differences for production
make kustomize-build-dev    # Build development manifests
make kustomize-build-prod   # Build production manifests
```

## Configuration Management

### ConfigMaps

Configuration is managed through:

1. **Base config.env**: Common environment variables
2. **Overlay literals**: Environment-specific overrides
3. **ConfigMap generation**: Automatic from environment files

### Secrets

Secrets are managed through:

1. **Development**: Simple literals in kustomization.yaml
2. **Production**: External secret management (recommended)
   - Kubernetes External Secrets Operator
   - HashiCorp Vault
   - AWS Secrets Manager
   - Azure Key Vault

### Images

Image management uses Kustomize's image transformer:

```yaml
images:
  - name: gitea-http.taildb3494.ts.net/will/rxminder
    newTag: v1.0.0 # Override in overlays
```

## Customization

### Adding a New Environment

1. Create new directory: `overlays/staging/`
2. Create `kustomization.yaml` with base reference
3. Add environment-specific patches
4. Update Makefile with new targets

Example:

```yaml
# overlays/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: rxminder-staging

commonLabels:
  environment: staging

images:
  - name: gitea-http.taildb3494.ts.net/will/rxminder
    newTag: staging
```

### Resource Patches

Use strategic merge patches for complex modifications:

```yaml
# Example: frontend-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: rxminder-frontend
spec:
  template:
    spec:
      containers:
        - name: frontend
          resources:
            requests:
              memory: '512Mi'
              cpu: '200m'
```

### JSON Patches

Use JSON patches for precise modifications:

```yaml
patches:
  - target:
      kind: Deployment
      name: rxminder-frontend
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
```

## Security Considerations

### Production Security Features

1. **Security Contexts**: Non-root containers, read-only filesystems
2. **Network Policies**: Restricted pod-to-pod communication
3. **Resource Limits**: Prevent resource exhaustion
4. **Image Security**: Signed images, vulnerability scanning
5. **Secret Management**: External secret stores
6. **TLS Encryption**: HTTPS with cert-manager
7. **RBAC**: Role-based access control

### Development Security

- Relaxed for development efficiency
- Still follows basic security practices
- Isolated in separate namespace

## Monitoring and Observability

### Production Monitoring

- **Health Checks**: Liveness and readiness probes
- **Metrics**: Resource usage monitoring
- **Logging**: Structured logging with appropriate levels
- **Alerting**: Production-grade alert rules

### Development Monitoring

- **Debug Logging**: Verbose logging for troubleshooting
- **Resource Monitoring**: Basic resource tracking
- **Health Checks**: Relaxed timing for development

## Troubleshooting

### Common Issues

1. **Image Pull Errors**

   ```bash
   # Check image exists and credentials are correct
   kubectl describe pod <pod-name> -n <namespace>
   ```

2. **ConfigMap Issues**

   ```bash
   # Check generated ConfigMap
   kubectl get configmap rxminder-config -n <namespace> -o yaml
   ```

3. **Service Discovery**

   ```bash
   # Test service connectivity
   kubectl exec -it <pod-name> -n <namespace> -- curl rxminder-couchdb-service:5984
   ```

4. **Resource Constraints**

   ```bash
   # Check resource usage
   kubectl top pods -n <namespace>
   kubectl describe node
   ```

### Debug Commands

```bash
# View all resources
kubectl get all -n rxminder-dev -l app=rxminder

# Check events
kubectl get events -n rxminder-dev --sort-by='.lastTimestamp'

# View logs
kubectl logs deployment/rxminder-frontend -n rxminder-dev -f

# Describe problematic resources
kubectl describe deployment rxminder-frontend -n rxminder-dev
```

## Migration from Legacy Deployment

### Migration Steps

1. **Test Kustomize**: Deploy to development first
2. **Validate Configuration**: Compare with existing deployment
3. **Update CI/CD**: Switch to Kustomize commands
4. **Production Migration**: Schedule maintenance window
5. **Cleanup**: Remove old template files after validation

### Rollback Plan

Legacy deployment scripts are still available:

```bash
make deploy-dev      # Deploy to development environment
make deploy-prod     # Deploy to production environment
make undeploy-dev    # Remove development deployment
make undeploy-prod   # Remove production deployment
```

## Benefits of Kustomize

1. **Template-free**: No complex templating logic
2. **Composable**: Layer configurations naturally
3. **Validation**: Built-in YAML validation
4. **GitOps Ready**: Works with ArgoCD, Flux
5. **Standard**: Kubernetes-native solution
6. **Maintainable**: Clear separation of concerns

## Best Practices

1. **Base Configuration**: Keep base as generic as possible
2. **Environment Isolation**: Use separate namespaces
3. **Secret Management**: Use external secret stores in production
4. **Image Tags**: Use specific tags, avoid `latest` in production
5. **Resource Limits**: Always set resource requests and limits
6. **Health Checks**: Configure appropriate probes
7. **Documentation**: Keep this README updated

## Support

For issues or questions:

1. Check troubleshooting section above
2. Review Kubernetes events and logs
3. Validate Kustomize configuration
4. Consult team documentation

---

**Note**: This Kustomize configuration replaces the previous shell script-based deployment. The old scripts are still available for backward compatibility but Kustomize is the recommended approach going forward.