@shakudo/kaji-setup-external 1.0.0

package/assets/skills/gitops-workflows/assets/flux/flux-bootstrap-github.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Flux 2.7+ Bootstrap Script for GitHub
+
+set -e
+
+# Configuration
+GITHUB_USER="${GITHUB_USER:-your-org}"
+GITHUB_REPO="${GITHUB_REPO:-fleet-infra}"
+GITHUB_TOKEN="${GITHUB_TOKEN:-}"
+CLUSTER_NAME="${CLUSTER_NAME:-production}"
+CLUSTER_PATH="clusters/${CLUSTER_NAME}"
+
+# Check prerequisites
+command -v flux >/dev/null 2>&1 || { echo "flux CLI required"; exit 1; }
+command -v kubectl >/dev/null 2>&1 || { echo "kubectl required"; exit 1; }
+
+# Check GitHub token
+if [ -z "$GITHUB_TOKEN" ]; then
+  echo "Error: GITHUB_TOKEN environment variable not set"
+  exit 1
+fi
+
+# Bootstrap Flux
+echo "🚀 Bootstrapping Flux for cluster: $CLUSTER_NAME"
+
+flux bootstrap github \
+  --owner="$GITHUB_USER" \
+  --repository="$GITHUB_REPO" \
+  --branch=main \
+  --path="$CLUSTER_PATH" \
+  --personal \
+  --token-auth
+
+# Enable source-watcher (Flux 2.7+)
+echo "✨ Enabling source-watcher component..."
+flux install --components-extra=source-watcher
+
+# Verify installation
+echo "✅ Verifying Flux installation..."
+flux check
+
+echo "
+✅ Flux bootstrapped successfully!
+
+Next steps:
+1. Add your applications to ${CLUSTER_PATH}/apps/
+2. Commit and push to trigger Flux reconciliation
+3. Monitor with: flux get all
+"

package/assets/skills/gitops-workflows/assets/flux/oci-helmrelease.yaml

@@ -0,0 +1,38 @@
+# Flux OCI Repository + HelmRelease (Flux 2.6+)
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: OCIRepository
+metadata:
+  name: podinfo-oci
+  namespace: flux-system
+spec:
+  interval: 5m
+  url: oci://ghcr.io/stefanprodan/charts/podinfo
+  ref:
+    semver: ">=6.0.0"
+  verify:
+    provider: cosign
+    secretRef:
+      name: cosign-public-key
+---
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: podinfo
+  namespace: default
+spec:
+  interval: 10m
+  chart:
+    spec:
+      chart: podinfo
+      sourceRef:
+        kind: OCIRepository
+        name: podinfo-oci
+        namespace: flux-system
+  values:
+    replicaCount: 2
+    resources:
+      limits:
+        memory: 256Mi
+      requests:
+        cpu: 100m
+        memory: 64Mi

package/assets/skills/gitops-workflows/assets/progressive-delivery/argo-rollouts-canary.yaml

@@ -0,0 +1,62 @@
+# Argo Rollouts Canary Deployment with Analysis
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: my-app
+spec:
+  replicas: 5
+  strategy:
+    canary:
+      steps:
+      - setWeight: 20
+      - pause: {duration: 2m}
+      - setWeight: 40
+      - pause: {duration: 2m}
+      - setWeight: 60
+      - pause: {duration: 2m}
+      - setWeight: 80
+      - pause: {duration: 2m}
+      analysis:
+        templates:
+        - templateName: success-rate
+        startingStep: 2
+        args:
+        - name: service-name
+          value: my-app
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+      - name: my-app
+        image: myapp:v2.0.0
+        ports:
+        - containerPort: 8080
+---
+# Analysis Template using Prometheus
+apiVersion: argoproj.io/v1alpha1
+kind: AnalysisTemplate
+metadata:
+  name: success-rate
+spec:
+  args:
+  - name: service-name
+  metrics:
+  - name: success-rate
+    interval: 1m
+    successCondition: result[0] >= 0.95
+    failureLimit: 3
+    provider:
+      prometheus:
+        address: http://prometheus.monitoring:9090
+        query: |
+          sum(rate(
+            http_requests_total{job="{{args.service-name}}",status!~"5.."}[2m]
+          )) /
+          sum(rate(
+            http_requests_total{job="{{args.service-name}}"}[2m]
+          ))

package/assets/skills/gitops-workflows/assets/secrets/sops-age-config.yaml

@@ -0,0 +1,33 @@
+# .sops.yaml - SOPS configuration with age encryption
+# Place in repository root
+creation_rules:
+  # Production secrets (encrypted with prod age key)
+  - path_regex: production/.*\.yaml$
+    encrypted_regex: ^(data|stringData)$
+    age: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+  # Staging secrets (encrypted with staging age key)
+  - path_regex: staging/.*\.yaml$
+    encrypted_regex: ^(data|stringData)$
+    age: age1staging... # Replace with your staging age public key
+
+  # Development secrets (encrypted with dev age key)
+  - path_regex: dev/.*\.yaml$
+    encrypted_regex: ^(data|stringData)$
+    age: age1dev... # Replace with your dev age public key
+
+# Generate age keys:
+# age-keygen -o prod-key.txt
+# age-keygen -o staging-key.txt
+# age-keygen -o dev-key.txt
+
+# Encrypt secret:
+# kubectl create secret generic my-secret --dry-run=client -o yaml \
+#   --from-literal=password=supersecret > secret.yaml
+# sops -e secret.yaml > secret.enc.yaml
+# git add secret.enc.yaml .sops.yaml
+
+# Flux integration:
+# kubectl create secret generic sops-age \
+#   --from-file=age.agekey=./prod-key.txt \
+#   -n flux-system

package/assets/skills/gitops-workflows/references/argocd_vs_flux.md

@@ -0,0 +1,243 @@
+# ArgoCD vs Flux: Comprehensive Comparison (2024-2025)
+
+## Current Versions (October 2025)
+
+- **ArgoCD**: v3.1.9 (stable), v3.2.0-rc4 (release candidate)
+- **Flux**: v2.7.1 (latest)
+
+## Quick Decision Matrix
+
+| Criteria | Choose ArgoCD | Choose Flux |
+|----------|---------------|-------------|
+| **Primary Focus** | Developer experience, UI | Platform engineering, modularity |
+| **Team Size** | Medium-large teams | Small teams, platform engineers |
+| **UI Required** | Yes | No (CLI-driven) |
+| **Complexity** | Simpler onboarding | Steeper learning curve |
+| **Customization** | Less modular | Highly modular |
+| **Multi-tenancy** | Built-in with Projects | Manual configuration |
+| **Best For** | Application teams, demos | Infrastructure teams, advanced users |
+
+## Key Differences
+
+### Architecture
+
+**ArgoCD**:
+- Monolithic design with integrated components
+- Web UI, API server, application controller in one system
+- Centralized control plane
+
+**Flux**:
+- Modular microservices architecture
+- Separate controllers: source, kustomize, helm, notification, image-automation
+- Distributed reconciliation
+
+### User Experience
+
+**ArgoCD**:
+- Rich web UI for visualization and management
+- GUI dashboard for deployment, syncing, troubleshooting
+- Easier onboarding for developers
+- Better for demos and presentations
+
+**Flux**:
+- CLI-driven (flux CLI + kubectl)
+- No built-in UI (can integrate with Weave GitOps UI separately)
+- Requires comfort with command-line tools
+- Steeper learning curve
+
+### Application Management
+
+**ArgoCD 3.x**:
+- Application and ApplicationSet CRDs
+- App-of-apps pattern for organizing applications
+- Fine-grained RBAC (new in v3.0)
+- Annotation-based tracking (default in v3.0, changed from labels)
+
+**Flux 2.7**:
+- Kustomization and HelmRelease CRDs
+- No built-in grouping mechanism
+- RBAC through Kubernetes RBAC
+- Label-based tracking
+
+### Multi-Cluster Support
+
+**ArgoCD ApplicationSets**:
+- Cluster generator for auto-discovery
+- Matrix generator for cluster x app combinations
+- Hub-and-spoke pattern (one ArgoCD manages multiple clusters)
+- 83% faster deployments vs manual (30min → 5min)
+
+**Flux Multi-Tenancy**:
+- Manual cluster configuration
+- Separate Flux installations per cluster or shared
+- More flexible but requires more setup
+- No built-in cluster generator
+
+### Secrets Management
+
+Both support:
+- Sealed Secrets
+- External Secrets Operator
+- SOPS
+
+**ArgoCD 3.0 Change**:
+- Now explicitly endorses secrets operators
+- Cautions against config management plugins for secrets
+- Better integration with ESO
+
+**Flux**:
+- Native SOPS integration with age encryption
+- Decryption happens in-cluster
+- .sops.yaml configuration support
+
+### Progressive Delivery
+
+**ArgoCD + Argo Rollouts**:
+- Separate project but tight integration
+- Rich UI for visualizing rollouts
+- Supports canary, blue-green, A/B testing
+- Metric analysis with Prometheus, Datadog, etc.
+
+**Flux + Flagger**:
+- Flagger as companion project
+- CLI-driven
+- Supports canary, blue-green, A/B testing
+- Metric analysis with Prometheus, Datadog, etc.
+
+## Feature Comparison
+
+| Feature | ArgoCD 3.x | Flux 2.7 |
+|---------|-----------|----------|
+| **Web UI** | ✅ Built-in | ❌ (3rd party available) |
+| **CLI** | ✅ argocd | ✅ flux |
+| **Git Sources** | ✅ | ✅ |
+| **OCI Artifacts** | ❌ | ✅ (GA in v2.6) |
+| **Helm Support** | ✅ | ✅ |
+| **Kustomize** | ✅ (v5.7.0) | ✅ (v5.7.0) |
+| **Multi-tenancy** | ✅ Projects | Manual |
+| **Image Automation** | ⚠️ Via Image Updater | ✅ GA in v2.7 |
+| **Notifications** | ✅ | ✅ |
+| **RBAC** | ✅ Fine-grained (v3.0) | Kubernetes RBAC |
+| **Progressive Delivery** | Argo Rollouts | Flagger |
+| **Signature Verification** | ⚠️ Limited | ✅ cosign/notation |
+
+## Performance & Scale
+
+**ArgoCD**:
+- Can manage 1000+ applications per instance
+- Better defaults in v3.0 (resource exclusions reduce API load)
+- ApplicationSets reduce management overhead
+
+**Flux**:
+- Lighter resource footprint
+- Better for large-scale monorepos
+- Source-watcher (v2.7) improves reconciliation efficiency
+
+## Community & Support
+
+**ArgoCD**:
+- CNCF Graduated project
+- Large community, many contributors
+- Akuity offers commercial support
+- Annual ArgoCon conference
+
+**Flux**:
+- CNCF Graduated project
+- Weaveworks shutdown (Feb 2024) but project remains strong
+- Grafana Labs offers Grafana Cloud integration
+- GitOpsCon events
+
+## Version 3.0 Changes (ArgoCD)
+
+**Breaking Changes**:
+- Annotation-based tracking (default, was labels)
+- RBAC logs enforcement (no longer optional)
+- Removed legacy metrics (argocd_app_sync_status, etc.)
+
+**New Features**:
+- Fine-grained RBAC (per-resource permissions)
+- Better defaults (resource exclusions for high-churn objects)
+- Secrets operators endorsement
+
+## Version 2.7 Changes (Flux)
+
+**New Features**:
+- Image automation GA
+- ExternalArtifact and ArtifactGenerator APIs
+- Source-watcher component
+- OpenTelemetry tracing support
+- CEL expressions for readiness
+
+## Migration Considerations
+
+### From ArgoCD → Flux
+
+**Pros**:
+- Lower resource consumption
+- More modular architecture
+- Better OCI support
+- Native SOPS integration
+
+**Cons**:
+- Lose web UI
+- More complex setup
+- Manual multi-tenancy
+
+**Effort**: Medium-High (2-4 weeks for large deployment)
+
+### From Flux → ArgoCD
+
+**Pros**:
+- Gain web UI
+- Easier multi-tenancy
+- ApplicationSets for multi-cluster
+- Better for teams new to GitOps
+
+**Cons**:
+- Higher resource consumption
+- Less modular
+- Limited OCI support
+
+**Effort**: Medium (1-3 weeks)
+
+## Recommendations by Use Case
+
+### Choose ArgoCD if:
+- ✅ Developer teams need visibility (UI required)
+- ✅ Managing dozens of applications across teams
+- ✅ Multi-tenancy with Projects model
+- ✅ Fast onboarding is priority
+- ✅ Need built-in RBAC with fine-grained control
+
+### Choose Flux if:
+- ✅ Platform engineering focus
+- ✅ Infrastructure-as-code emphasis
+- ✅ Using OCI artifacts extensively
+- ✅ Want modular, composable architecture
+- ✅ Team comfortable with CLI tools
+- ✅ SOPS+age encryption requirement
+
+### Use Both if:
+- Different teams have different needs
+- ArgoCD for app teams, Flux for infrastructure
+- Separate concerns (apps vs infrastructure)
+
+## Cost Considerations
+
+**ArgoCD**:
+- Higher memory/CPU usage (~500MB-1GB per instance)
+- Commercial support available (Akuity)
+
+**Flux**:
+- Lower resource footprint (~200-400MB total)
+- Grafana Cloud integration available
+
+## Conclusion
+
+**2024-2025 Recommendation**:
+- **For most organizations**: Start with ArgoCD for ease of use
+- **For platform teams**: Flux offers more control and modularity
+- **For enterprises**: Consider ArgoCD for UI + Flux for infrastructure
+- Both are production-ready CNCF Graduated projects
+
+The choice depends more on team preferences and workflows than technical capability.

package/assets/skills/gitops-workflows/references/best_practices.md

@@ -0,0 +1,160 @@
+# GitOps Best Practices (2024-2025)
+
+## CNCF GitOps Principles (OpenGitOps v1.0)
+
+1. **Declarative**: System desired state expressed declaratively
+2. **Versioned**: State stored in version control (Git)
+3. **Automated**: Changes automatically applied
+4. **Continuous Reconciliation**: Software agents ensure desired state
+5. **Auditable**: All changes tracked in Git history
+
+## Repository Organization
+
+✅ **DO**:
+- Separate infrastructure from applications
+- Use clear directory structure (apps/, infrastructure/, clusters/)
+- Implement environment promotion (dev → staging → prod)
+- Use Kustomize overlays for environment differences
+
+❌ **DON'T**:
+- Commit secrets to Git (use SOPS/Sealed Secrets/ESO)
+- Use `:latest` image tags (pin to specific versions)
+- Make manual cluster changes (everything through Git)
+- Skip testing in lower environments
+
+## Security Best Practices
+
+1. **Secrets**: Never plain text, use encryption or external stores
+2. **RBAC**: Least privilege for GitOps controllers
+3. **Image Security**: Pin to digests, scan for vulnerabilities
+4. **Network Policies**: Restrict controller traffic
+5. **Audit**: Enable audit logging
+
+## ArgoCD 3.x Specific
+
+**Fine-Grained RBAC** (new in 3.0):
+```yaml
+p, role:dev, applications, *, dev/*, allow
+p, role:dev, applications/resources, *, dev/*/Deployment/*, allow
+```
+
+**Resource Exclusions** (default in 3.0):
+- Reduces API load
+- Excludes high-churn resources (Endpoints, Leases)
+
+**Annotation Tracking** (default):
+- More reliable than labels
+- Auto-migrates on sync
+
+## Flux 2.7 Specific
+
+**OCI Artifacts** (GA in 2.6):
+- Prefer OCI over Git for generated configs
+- Use digest pinning for immutability
+- Sign artifacts with cosign/notation
+
+**Image Automation** (GA in 2.7):
+- Automated image updates
+- GitRepository write-back
+
+**Source-Watcher** (new in 2.7):
+- Improves reconciliation efficiency
+- Enable with: `--components-extra=source-watcher`
+
+## CI/CD Integration
+
+**Git Workflow**:
+```
+1. Developer commits to feature branch
+2. CI runs tests, builds image
+3. CI updates Git manifest with new image tag
+4. Developer creates PR to main
+5. GitOps controller syncs after merge
+```
+
+**Don't**: Deploy directly from CI to cluster (breaks GitOps)
+**Do**: Update Git from CI, let GitOps deploy
+
+## Monitoring & Observability
+
+**Track**:
+- Sync success rate
+- Reconciliation time
+- Drift detection frequency
+- Failed syncs/reconciliations
+
+**Tools**:
+- Prometheus metrics (both ArgoCD and Flux)
+- Grafana dashboards
+- Alert on sync failures
+
+## Image Management
+
+✅ **Good**:
+```yaml
+image: myapp:v1.2.3
+image: myapp@sha256:abc123...
+```
+
+❌ **Bad**:
+```yaml
+image: myapp:latest
+image: myapp:dev
+```
+
+**Strategy**: Semantic versioning + digest pinning
+
+## Environment Promotion
+
+**Recommended Flow**:
+```
+Dev (auto-sync) → Staging (auto-sync) → Production (manual approval)
+```
+
+**Implementation**:
+- Separate directories or repos per environment
+- PR-based promotion
+- Automated tests before promotion
+- Manual approval for production
+
+## Disaster Recovery
+
+1. **Git is Source of Truth**: Cluster can be rebuilt from Git
+2. **Backup**: Git repo + cluster state
+3. **Test Recovery**: Practice cluster rebuild
+4. **Document Bootstrap**: How to restore from scratch
+
+## Performance Optimization
+
+**ArgoCD**:
+- Use ApplicationSets for multi-cluster
+- Enable resource exclusions (3.x default)
+- Server-side diff for large apps
+
+**Flux**:
+- Use OCI artifacts for large repos
+- Enable source-watcher (2.7)
+- Tune reconciliation intervals
+
+## Common Anti-Patterns to Avoid
+
+1. **Manual kubectl apply**: Bypasses GitOps, creates drift
+2. **Multiple sources of truth**: Git should be only source
+3. **Secrets in Git**: Always encrypt
+4. **Direct cluster modifications**: All changes through Git
+5. **No testing**: Always test in dev/staging first
+6. **Missing RBAC**: Controllers need minimal permissions
+
+## 2025 Trends
+
+✅ **Adopt**:
+- OCI artifacts (Flux)
+- Workload identity (no static credentials)
+- SOPS + age (over PGP)
+- External Secrets Operator (dynamic secrets)
+- Multi-cluster with ApplicationSets/Flux
+
+⚠️ **Avoid**:
+- Label-based tracking (use annotations - ArgoCD 3.x default)
+- PGP encryption (use age)
+- Long-lived service account tokens (use workload identity)

package/assets/skills/gitops-workflows/references/multi_cluster.md

@@ -0,0 +1,80 @@
+# Multi-Cluster GitOps Management (2024-2025)
+
+## ArgoCD ApplicationSets
+
+**Cluster Generator** (auto-discover clusters):
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: my-apps
+spec:
+  generators:
+  - cluster:
+      selector:
+        matchLabels:
+          environment: production
+  template:
+    spec:
+      source:
+        repoURL: https://github.com/org/repo
+        path: apps/{{name}}
+      destination:
+        server: '{{server}}'
+```
+
+**Matrix Generator** (Cluster x Apps):
+```yaml
+generators:
+- matrix:
+    generators:
+    - cluster: {}
+    - git:
+        directories:
+        - path: apps/*
+```
+
+**Performance**: 83% faster than manual (30min → 5min)
+
+## Flux Multi-Cluster
+
+**Option 1: Flux Per Cluster**
+```
+cluster-1/ → Flux instance 1
+cluster-2/ → Flux instance 2
+```
+
+**Option 2: Hub-and-Spoke**
+```
+management-cluster/
+└── flux manages → cluster-1, cluster-2
+```
+
+**Setup**:
+```bash
+flux bootstrap github --owner=org --repository=fleet \
+  --path=clusters/production --context=prod-cluster
+```
+
+## Hub-and-Spoke Pattern
+
+**Benefits**: Centralized management, single source of truth
+**Cons**: Single point of failure
+**Best for**: < 50 clusters
+
+## Workload Identity (2025 Best Practice)
+
+**Instead of service account tokens, use**:
+- AWS IRSA
+- GCP Workload Identity
+- Azure AD Workload Identity
+
+No more long-lived credentials!
+
+## Best Practices
+
+1. **Cluster labeling** for organization
+2. **Progressive rollout** (dev → staging → prod clusters)
+3. **Separate repos** for cluster config vs apps
+4. **Monitor sync status** across all clusters
+5. **Use workload identity** (no static credentials)