A production-ready template repository for managing Kubernetes applications using the kast-system GitOps framework with ArgoCD.
This template provides a pre-configured structure for deploying applications to Kubernetes using:
- kast-system: A declarative framework that extends ArgoCD with the Book/Chapter/Spell paradigm
- ArgoCD: GitOps continuous delivery tool for Kubernetes
- Helm: Package manager for Kubernetes applications
- Kubernetes cluster (1.25+)
- kubectl configured and connected to your cluster
- Helm 3.8+
- Git 2.30+
- ArgoCD installed in your cluster
Click "Use this template" on GitHub or clone this repository:
git clone https://github.com/kast-spells/bookrack-template.git my-bookrack
cd my-bookrack./setup.shThe script will prompt you for:
- Book name (e.g.,
my-book) - Cluster name (e.g.,
production) - Environment (e.g.,
dev,staging,prod) - Git repository URL
git remote set-url origin <your-new-repo-url>
git push -u origin main# Check ArgoCD applications
kubectl get applications -n argocd
# Check your spells
argocd app list -l argocd.argoproj.io/instance=<your-book-name>.
├── bookrack/ # Main directory for all books
│ └── example-book/ # A book (collection of related apps)
│ ├── index.yaml # Book configuration
│ ├── infrastructure/ # Infrastructure chapter
│ │ ├── index.yaml # Chapter configuration
│ │ └── redis.yaml # Example infrastructure spell
│ └── applications/ # Applications chapter
│ ├── index.yaml # Chapter configuration
│ ├── nginx-example.yaml
│ ├── app-with-secrets.yaml
│ └── app-with-istio.yaml
├── librarian/ # Librarian helm chart (git submodule)
├── docs/ # Documentation
├── setup.sh # Automated setup script
└── README.md # This file
A collection of related applications for a specific project or team. Each book has:
- Chapters (logical groupings)
- Global configuration (appendix)
- Shared trinkets (charts)
Logical grouping of applications within a book:
infrastructure: foundational services (databases, caches, queues)applications: user-facing applications- Custom chapters as needed
Individual application definition (YAML file) describing:
- Container image and configuration
- Resources and scaling
- Networking (Service, Ingress)
- Health checks
- Integration with Vault, Istio, cert-manager, etc.
ArgoCD application that reads your books and generates ArgoCD Applications for each spell.
# bookrack/my-book/applications/webapp.yaml
name: webapp
image:
name: nginx
tag: latest
pullPolicy: IfNotPresent
replicas: 2
ports:
- name: http
containerPort: 80
service:
enabled: true
type: ClusterIP
ports:
- name: http
port: 80name: secure-app
vault:
db-credentials:
path: secret/data/production/database
outputType: secret
keys:
- username
- password
env:
- name: DB_USER
valueFrom:
secretKeyRef:
name: db-credentials
key: usernamename: frontend
istio:
frontend-vs:
selector:
access: external
hosts:
- app.example.com
routes:
- destination:
host: frontend
port: 80Edit bookrack/<your-book>/index.yaml to customize:
appendix:
cluster:
name: production
environment: prod
region: us-west-2appendix:
lexicon:
- name: external-gateway
type: istio-gw
labels:
access: external
default: book
gateway: istio-system/external-gateway
- name: vault-prod
type: vault
labels:
default: book
address: https://vault.vault.svc:8200- Create a new spell file:
cat > bookrack/my-book/applications/myapp.yaml <<EOF
name: myapp
image:
name: myapp
tag: v1.0.0
replicas: 2
ports:
- name: http
containerPort: 8080
service:
enabled: true
type: ClusterIP
ports:
- name: http
port: 80
targetPort: http
EOF- Commit and push:
git add bookrack/my-book/applications/myapp.yaml
git commit -m "Add myapp spell"
git push- ArgoCD will automatically detect and deploy (if auto-sync is enabled)
kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: librarian-my-book
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/YOUR-ORG/my-bookrack.git # Your forked repo
targetRevision: main
path: librarian
helm:
values: |
name: my-book
destination:
server: https://kubernetes.default.svc
namespace: argocd
syncPolicy:
automated:
prune: true
selfHeal: true
EOF# Sync all apps in a book
argocd app sync -l argocd.argoproj.io/instance=my-book
# Sync specific application
argocd app sync my-book-applications-nginx# List all applications
argocd app list
# Get application details
argocd app get my-book-applications-nginx
# Watch application sync
argocd app wait my-book-applications-nginx --healthCheck librarian logs:
kubectl logs -n argocd -l app.kubernetes.io/name=librarian -fCheck ArgoCD application status:
argocd app get <app-name>
kubectl describe application <app-name> -n argocdVerify book/chapter/spell structure:
# Check if spell files are in correct location
find bookrack/ -name "*.yaml" -type fCreate separate books for each environment:
bookrack/
├── myapp-dev/
├── myapp-staging/
└── myapp-prod/
name: canary-app
workloadType: rollout
strategy:
canary:
steps:
- setWeight: 20
- pause: {duration: 1m}
- setWeight: 50
- pause: {duration: 2m}
- setWeight: 100Add custom Helm charts:
trinkets:
my-custom-chart:
key: custom
repository: https://my-repo.com/charts.git
path: ./my-chart
targetRevision: mainThis is a template repository. Fork it, customize it, and make it your own!
MIT License - See LICENSE file for details
For issues with:
- This template: Open an issue in this repository
- kast-system: See kast-system issues
- ArgoCD: See ArgoCD documentation