rxminder/k8s-kustomize

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

# Using Makefile (recommended)
make deploy-dev

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

Deploy to Production

# 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

# 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

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

Debugging Commands

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:

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:

# 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:

# 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:

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

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

2. ConfigMap Issues

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

3. Service Discovery

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

4. Resource Constraints

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

Debug Commands

# 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:

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.