Refactor duplicated Kubernetes resources with reusable templates and tooling

.github/workflows/README.md

@@ -0,0 +1,114 @@
+# GitHub Workflows
+
+This directory contains GitHub Actions workflows for building and deploying applications.
+
+## Workflow Types
+
+### Individual Application Workflows
+
+Files like `dashy.yaml`, `homepage.yaml`, `cyberchef.yaml`, and `toolchain.yaml` are minimal wrapper workflows that trigger on changes to specific application directories.
+
+**Structure**:
+```yaml
+name: <app-name>
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - applicationset/<app-name>/**
+
+jobs:
+  docker-build:
+    uses: ./.github/workflows/reusable-docker-build.yaml
+    with:
+      path: applicationset/<app-name>
+```
+
+### Reusable Workflows
+
+#### reusable-docker-build.yaml
+
+A reusable workflow that handles Docker image building and pushing. Used by all application workflows.
+
+**Inputs**:
+- `tag-name`: Docker image tag name (default: 'docker-build')
+- `path`: Path to the application directory (required)
+- `push`: Whether to push the image to registry (default: false)
+- `version`: Image version tag (default: 'latest')
+
+### Release Workflow
+
+#### release.yaml
+
+Triggered by Git tags following the pattern `<app-name>-<version>`. This workflow:
+1. Parses the application name and version from the tag
+2. Builds and pushes the Docker image
+3. Updates the version in the application's `kustomization.yaml`
+4. Commits the version update back to the repository
+
+## Creating a New Application Workflow
+
+To add a workflow for a new application:
+
+1. **Copy an existing workflow** (e.g., `cyberchef.yaml`)
+2. **Update the name** to match your application
+3. **Update the paths** to trigger on your application directory
+4. **Customize the path parameter** in the workflow call
+
+**Example for a new app called "myapp"**:
+
+```yaml
+name: myapp
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - applicationset/myapp/**
+
+jobs:
+  docker-build:
+    uses: ./.github/workflows/reusable-docker-build.yaml
+    with:
+      path: applicationset/myapp
+```
+
+## Why Individual Workflows?
+
+While these workflows appear duplicated, they serve distinct purposes:
+
+1. **Isolated Triggers**: Each workflow only runs when its specific application changes
+2. **Clear Build Status**: Individual workflow badges in README.md show per-application status
+3. **Flexible Configuration**: Each application can customize its workflow parameters if needed
+4. **GitHub Actions Limitations**: GitHub Actions doesn't support dynamic workflow generation
+
+The common build logic is extracted into `reusable-docker-build.yaml` to avoid true code duplication.
+
+## Deployment Process
+
+### Continuous Deployment (Push to Main)
+
+1. Push changes to `applicationset/<app-name>/`
+2. The application's workflow triggers
+3. Docker image is built (but not pushed)
+4. ArgoCD syncs the changes from the repository
+
+### Release Deployment (Tagged)
+
+1. Create a tag: `git tag <app-name>-v1.0.0 && git push --tags`
+2. The `release.yaml` workflow triggers
+3. Docker image is built and pushed to GitHub Container Registry
+4. `kustomization.yaml` is updated with the new version
+5. ArgoCD syncs the changes and deploys the new version
+
+## Best Practices
+
+- Keep individual workflows minimal (just trigger configuration)
+- Put common logic in reusable workflows
+- Use semantic versioning for release tags: `<app>-v<major>.<minor>.<patch>`
+- Test kustomization locally before pushing: `kubectl kustomize applicationset/<app>`

CONTRIBUTING.md

@@ -0,0 +1,237 @@
+# Contributing to GitOps
+
+Thank you for your interest in contributing to this GitOps repository!
+
+## Overview
+
+This repository uses GitOps practices to manage Kubernetes deployments via ArgoCD. All changes to the cluster are made by updating this repository.
+
+## Repository Structure
+
+```
+├── .github/workflows/     # GitHub Actions CI/CD pipelines
+├── applicationset/        # Application configurations
+│   ├── base/             # Base Kustomize templates
+│   └── <app>/            # Individual application configs
+├── k8s-templates/        # Reusable Kubernetes resource templates
+├── cluster-bootstrap/    # Cluster infrastructure components
+└── changedetection/      # Standalone application
+```
+
+## Adding a New Application
+
+### Quick Start
+
+1. **Choose a template approach**:
+   - Copy an existing similar application from `applicationset/`
+   - Or start from scratch using templates in `k8s-templates/`
+
+2. **Create your application directory**:
+   ```bash
+   mkdir -p applicationset/myapp
+   ```
+
+3. **Create required files**:
+   - `kustomization.yaml` - Kustomize configuration
+   - `vs.yaml` - VirtualService for Istio routing
+   - Optional: `volume.yaml` - Persistent storage
+   - Optional: `patches/` - Customizations to base resources
+
+4. **Reference the base template**:
+   ```yaml
+   # applicationset/myapp/kustomization.yaml
+   apiVersion: kustomize.config.k8s.io/v1beta1
+   kind: Kustomization
+   resources:
+   - ../base
+   - vs.yaml
+   namePrefix: myapp-
+   images:
+   - name: ghcr.io/guyzsarun-lab/base
+     newName: ghcr.io/guyzsarun-lab/myapp
+     newTag: v1.0.0
+   commonLabels:
+     app: myapp
+   ```
+
+5. **Test locally**:
+   ```bash
+   kubectl kustomize applicationset/myapp
+   ```
+
+6. **Create a GitHub workflow** (if building custom images):
+   ```bash
+   cp .github/workflows/cyberchef.yaml .github/workflows/myapp.yaml
+   # Edit the file to update name and paths
+   ```
+
+7. **Commit and push**:
+   ```bash
+   git add applicationset/myapp
+   git commit -m "Add myapp application"
+   git push
+   ```
+
+### Detailed Guides
+
+- [Kubernetes Templates Guide](k8s-templates/README.md) - Common patterns and templates
+- [Workflow Guide](.github/workflows/README.md) - CI/CD pipeline patterns
+
+## Common Patterns
+
+### Pattern 1: Simple Web Application
+
+For applications with:
+- Single container
+- Exposed via Istio VirtualService
+- No persistent storage
+
+**Example**: `cyberchef`, `toolchain`
+
+### Pattern 2: Application with Configuration
+
+For applications with:
+- ConfigMaps for configuration files
+- Volume mounts for config
+- Patches to inject config
+
+**Example**: `dashy`, `glance`
+
+### Pattern 3: Application with Persistent Storage
+
+For applications with:
+- NFS-backed PersistentVolume
+- Volume mounts in deployment
+- Data persistence requirements
+
+**Example**: `linkwarden`, `paperless`, `calibre`
+
+### Pattern 4: Multi-Container Application
+
+For applications with:
+- Sidecar containers
+- Multiple services
+- Complex networking
+
+**Example**: `linkwarden` (with meilisearch sidecar)
+
+## Kustomize Best Practices
+
+### Use Strategic Merge Patches
+
+For modifying specific fields:
+```yaml
+# patches/service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: application
+spec:
+  ports:
+  - $patch: replace
+  - port: 3000
+    targetPort: 8080
+```
+
+### Use namePrefix for Resource Naming
+
+Instead of hardcoding names, use `namePrefix`:
+```yaml
+namePrefix: myapp-
+# Results in: myapp-application, myapp-vs, etc.
+```
+
+### Use commonLabels for Consistent Labeling
+
+```yaml
+commonLabels:
+  app: myapp
+```
+
+## Validation
+
+Before committing, always validate:
+
+```bash
+# Validate Kustomize output
+kubectl kustomize applicationset/myapp
+
+# Dry-run to catch issues
+kubectl kustomize applicationset/myapp | kubectl apply --dry-run=client -f -
+
+# Check YAML syntax
+kubectl kustomize applicationset/myapp | kubectl apply --dry-run=server -f -
+```
+
+## Deployment Process
+
+### Development/Testing (Push to Main)
+
+1. Make changes to application configuration
+2. Commit and push to `main` branch
+3. ArgoCD automatically syncs changes to the cluster
+
+### Production Release (Tagged Release)
+
+1. Build and test your application
+2. Create a Git tag: `git tag myapp-v1.0.0`
+3. Push tag: `git push --tags`
+4. GitHub Actions builds and pushes Docker image
+5. Workflow updates `kustomization.yaml` with new version
+6. ArgoCD syncs the new version
+
+## Troubleshooting
+
+### Kustomize Errors
+
+```bash
+# View detailed error output
+kubectl kustomize applicationset/myapp
+
+# Check for YAML syntax errors
+yamllint applicationset/myapp/*.yaml
+```
+
+### ArgoCD Sync Issues
+
+1. Check ArgoCD UI for sync status
+2. Review ArgoCD application logs
+3. Verify Git repository is accessible
+4. Check resource quotas and RBAC permissions
+
+### Docker Build Failures
+
+1. Review GitHub Actions workflow logs
+2. Verify Dockerfile syntax
+3. Check base image availability
+4. Ensure required build arguments are provided
+
+## Code Review Guidelines
+
+When reviewing PRs:
+
+- [ ] Kustomize configuration is valid
+- [ ] Resources follow naming conventions
+- [ ] Labels are consistent
+- [ ] VirtualService routes are correct
+- [ ] Resource limits are appropriate
+- [ ] Secrets are not committed to Git
+- [ ] Documentation is updated if needed
+
+## Resources
+
+- [Kustomize Documentation](https://kubectl.docs.kubernetes.io/references/kustomize/)
+- [ArgoCD Documentation](https://argo-cd.readthedocs.io/)
+- [Istio VirtualService](https://istio.io/latest/docs/reference/config/networking/virtual-service/)
+- [Kubernetes Best Practices](https://kubernetes.io/docs/concepts/configuration/overview/)
+
+## Getting Help
+
+- Review existing applications for examples
+- Check [k8s-templates/README.md](k8s-templates/README.md) for common patterns
+- Open an issue for questions or problems
+- Consult the team before making infrastructure changes
+
+## License
+
+This project follows the same license as specified in [LICENSE](LICENSE).

README.md

@@ -20,10 +20,23 @@ This repository follows the GitOps workflow to manage Kubernetes deployments. Al
 ├── applicationset      # argocd applicationset generator
 │   ├── base            # base kustomize template
 │   └── ...     
+├── k8s-templates       # reusable kubernetes resource templates
 |
 └──  changedetection    # argocd managed application
 ```
 
+## Adding a New Application
+
+To add a new application to the repository:
+
+1. **Copy an existing application** from `applicationset/` that matches your needs
+2. **Customize the configuration** (see [k8s-templates/README.md](k8s-templates/README.md) for common patterns)
+3. **Test your kustomization**: `kubectl kustomize applicationset/myapp`
+4. **Create a workflow** (optional): Copy one of the existing `.github/workflows/*.yaml` files if you need to build a custom Docker image
+5. **Commit and let ArgoCD sync** your changes
+
+For detailed templates and examples, see [k8s-templates/README.md](k8s-templates/README.md).
+
 ## Deployment
 
 To deploy an application, you can tag the repository follows the naming convention: `<application-name>-<version>`. This tag triggers the deployment process via GitHub Actions.

applicationset/toolchain/kustomization.yaml

@@ -2,6 +2,7 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
 - ../base
+- vs.yaml
 namePrefix: toolchain-
 images:
 - name: ghcr.io/guyzsarun-lab/base