This repository contains Kubernetes deployment configurations for the Herbarium Specify 7 application using Kustomize for environment-specific overlays.
UAT working. Ready for production (requires NGINX rule setting and connection to provisioned Azure Storage). Follow the Prod readme to get it going upon receipt of confirmation that NGINX url set up (requires admin privilleges).
Specify 7 is a biological collections management system. This deployment supports three environments:
- Development (k3d local cluster)
- UAT (Azure AKS via Rancher)
- TODO: Production (Azure AKS via Rancher)
It is advised you get things running locally first to get an understanding of Kubernetes commands.
- 1_DEV_README.md - Development environment setup and deployment (k3d local cluster)
- 2_UAT_README.md - UAT environment deployment guide (Rancher/Azure AKS)
- 3_PROD_README.md - Production deployment guide (Rancher/Azure AKS)
- COMMON_COMMANDS.md - Quick reference for kubectl and Kustomize commands
- kubectl installed and configured
- Access to appropriate Kubernetes cluster (k3d for dev, Rancher for UAT/prod)
- Environment-specific credentials configured
# Switch to dev context
kubectl config use-context k3d-specify-test
# Deploy to dev
kubectl apply -k kustomize/overlays/dev
# Access via port-forward
kubectl port-forward -n herbarium-specify svc/nginx 8000:80See 1_DEV_README.md for detailed instructions.
# Switch to UAT context/cluster
kubectl config use-context az-aks-oim03
# Deploy to UAT
kubectl apply -k kustomize/overlays/uatSee 2_UAT_README.md for detailed instructions.
.
├── kustomize/
│ ├── base/ # Base Kubernetes manifests
│ └── overlays/
│ ├── dev/ # Development environment overlay
│ ├── uat/ # UAT environment overlay
│ └── prod/ # Production environment overlay
├── scripts/ # Automation scripts
│ ├── reset-specify-dev.sh # Dev environment reset script
│ └── reset-specify-uat.sh # UAT environment reset script
├── 1_DEV_README.md # Development deployment guide
├── 2_UAT_README.md # UAT deployment guide
└── COMMON_COMMANDS.md # Command reference
Each environment uses a .env file for configuration. These files are gitignored and must be created from the provided templates:
# Development
cp kustomize/overlays/dev/.env.example kustomize/overlays/dev/.env
# UAT
cp kustomize/overlays/uat/.env.example kustomize/overlays/uat/.env
# Production
cp kustomize/overlays/prod/.env.example kustomize/overlays/prod/.envImportant: Never commit .env files to version control. They contain sensitive credentials.
Credentials are stored in kustomize/creds/ (gitignored):
creds/dev/- Development credentials (for local testing)creds/uat/- UAT database and IT user credentialscreds/prod/- Production database and IT user credentials
- Never commit secrets: All
.envfiles and credential files are gitignored - Unique keys per environment: Each environment must use different SECRET_KEY and ASSET_SERVER_KEY values
- Debug mode: Must be disabled in UAT and production (
SP7_DEBUG=false)
- SSL/TLS: External proxy handles SSL termination; do not configure TLS in Kubernetes ingress
- Database: UAT and production use Azure MySQL (external), not in-cluster MariaDB
- Change Management: Production deployments require approval and should follow change management procedures. Actions limited by RBAC in cluster
Azure MySQL users require the following permissions for migrations:
- CREATE
- ALTER
- DROP
- INDEX
- REFERENCES
# Make executable
chmod +x ./scripts/reset-specify-dev.sh
# Quick reset (delete/recreate namespace only)
./scripts/reset-specify-dev.sh
# Full reset (delete/recreate entire k3d cluster)
./scripts/reset-specify-dev.sh --nuke# Make executable
chmod +x ./scripts/reset-specify-uat.sh
# Reset UAT deployment (Does not delete namespace or cluster, only resoruces)
./scripts/reset-specify-uat.shNote: UAT reset script only deletes resources within the namespace, not the namespace itself.
| Feature | Development | UAT | Production |
|---|---|---|---|
| Cluster | k3d (local) | Azure AKS | Azure AKS |
| Database | MariaDB (in-cluster) | Azure MySQL | Azure MySQL |
| Access | Port-forward (localhost:8000) | https://specify-test.dbca.wa.gov.au | https://specify.dbca.wa.gov.au |
| Replicas | 1 | 1 | 2 |
| Debug Mode | Enabled | Disabled | Disabled |
| SSL/TLS | None | External proxy | External proxy |
| Change Control | None | Informal | Formal |
# Check all pods
kubectl get pods -n herbarium-specify
# Check all resources
kubectl get all -n herbarium-specify
# View logs
kubectl logs -n herbarium-specify deployment/specify --tail=50# After editing .env file:
kubectl delete secret specify-secrets -n herbarium-specify
kubectl apply -k kustomize/overlays/<env>
kubectl rollout restart deployment/specify -n herbarium-specify# Rolling restart (no downtime)
kubectl rollout restart deployment/specify -n herbarium-specifySee COMMON_COMMANDS.md for comprehensive command reference.
- VPN Connectivity (UAT/Prod): Disconnect VPN before running kubectl commands
- Permission Errors: Verify you're using the correct context and have namespace access
- Pod Startup Failures: Check logs with
kubectl logsand events withkubectl get events - Database Connection: Verify credentials in
.envfile and Azure MySQL firewall rules
- Check environment-specific README files for detailed troubleshooting
- Review logs:
kubectl logs -n herbarium-specify deployment/specify - Check events:
kubectl get events -n herbarium-specify --sort-by='.lastTimestamp' - Verify configuration:
kubectl describe deployment specify -n herbarium-specify
- Specify 7 Documentation: https://github.com/specify/specify7
- Kubernetes Documentation: https://kubernetes.io/docs/
- Kustomize Documentation: https://kustomize.io/
For deployment issues or questions:
- Review the appropriate environment README (1_DEV_README.md, 2_UAT_README.md, or 3_PROD_README.md)
- Check COMMON_COMMANDS.md for command reference
- Review logs and events for error messages
- Contact the infrastructure team for cluster or network issues