@shakudo/kaji-setup-external 1.0.0

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

@@ -0,0 +1,290 @@
+# OCI Artifacts with Flux (2024-2025)
+
+## Overview
+
+**GA Status**: Flux v2.6 (June 2025)
+**Current**: Fully supported in Flux v2.7
+
+OCI artifacts allow storing Kubernetes manifests, Helm charts, and Kustomize overlays in container registries instead of Git.
+
+## Benefits
+
+✅ **Decoupled from Git**: No Git dependency for deployment
+✅ **Immutable**: Content-addressable by digest
+✅ **Standard**: Uses OCI spec, works with any OCI registry
+✅ **Signature Verification**: Native support for cosign/notation
+✅ **Performance**: Faster than Git for large repos
+
+## OCIRepository Resource
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: OC IRepository
+metadata:
+  name: my-app-oci
+  namespace: flux-system
+spec:
+  interval: 5m
+  url: oci://ghcr.io/org/app-config
+  ref:
+    tag: v1.0.0
+    # or digest:
+    # digest: sha256:abc123...
+    # or semver:
+    # semver: ">=1.0.0 <2.0.0"
+  provider: generic  # or azure, aws, gcp
+  verify:
+    provider: cosign
+    secretRef:
+      name: cosign-public-key
+```
+
+## Using with Kustomization
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: my-app
+spec:
+  interval: 10m
+  sourceRef:
+    kind: OCIRepository
+    name: my-app-oci
+  path: ./
+  prune: true
+```
+
+## Using with HelmRelease
+
+**OCIRepository for Helm charts**:
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: OCIRepository
+metadata:
+  name: podinfo-oci
+spec:
+  interval: 5m
+  url: oci://ghcr.io/stefanprodan/charts/podinfo
+  ref:
+    semver: ">=6.0.0"
+---
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: podinfo
+spec:
+  chart:
+    spec:
+      chart: podinfo
+      sourceRef:
+        kind: OCIRepository
+        name: podinfo-oci
+```
+
+## Publishing OCI Artifacts
+
+**Using flux CLI**:
+```bash
+# Build and push Kustomize overlay
+flux push artifact oci://ghcr.io/org/app-config:v1.0.0 \
+  --path="./kustomize" \
+  --source="$(git config --get remote.origin.url)" \
+  --revision="$(git rev-parse HEAD)"
+
+# Build and push Helm chart
+flux push artifact oci://ghcr.io/org/charts/myapp:1.0.0 \
+  --path="./charts/myapp" \
+  --source="$(git config --get remote.origin.url)" \
+  --revision="$(git rev-parse HEAD)"
+```
+
+## Signature Verification
+
+### Using cosign
+
+**Sign artifact**:
+```bash
+cosign sign ghcr.io/org/app-config:v1.0.0
+```
+
+**Verify in Flux**:
+```yaml
+spec:
+  verify:
+    provider: cosign
+    secretRef:
+      name: cosign-public-key
+```
+
+### Using notation
+
+**Sign artifact**:
+```bash
+notation sign ghcr.io/org/app-config:v1.0.0
+```
+
+**Verify in Flux**:
+```yaml
+spec:
+  verify:
+    provider: notation
+    secretRef:
+      name: notation-config
+```
+
+## Workload Identity
+
+**Instead of static credentials, use cloud provider workload identity**:
+
+**AWS IRSA**:
+```yaml
+spec:
+  provider: aws
+  # No credentials needed - uses pod's IAM role
+```
+
+**GCP Workload Identity**:
+```yaml
+spec:
+  provider: gcp
+  # No credentials needed - uses service account binding
+```
+
+**Azure Workload Identity**:
+```yaml
+spec:
+  provider: azure
+  # No credentials needed - uses managed identity
+```
+
+## Best Practices (2025)
+
+1. **Use digest pinning** for production:
+   ```yaml
+   ref:
+     digest: sha256:abc123...
+   ```
+
+2. **Sign all artifacts**:
+   ```bash
+   flux push artifact ... | cosign sign
+   ```
+
+3. **Use semver for automated updates**:
+   ```yaml
+   ref:
+     semver: ">=1.0.0 <2.0.0"
+   ```
+
+4. **Leverage workload identity** (no static credentials)
+
+5. **Prefer OCI for generated configs** (Jsonnet, CUE, Helm output)
+
+## When to Use OCI vs Git
+
+**Use OCI Artifacts when**:
+- ✅ Storing generated configurations (Jsonnet, CUE output)
+- ✅ Need immutable, content-addressable storage
+- ✅ Want signature verification
+- ✅ Large repos (performance)
+- ✅ Decoupling from Git
+
+**Use Git when**:
+- ✅ Source of truth for manifests
+- ✅ Need Git workflow (PRs, reviews)
+- ✅ Audit trail important
+- ✅ Team collaboration
+
+## Common Pattern: Hybrid Approach
+
+```
+Git (source of truth)
+  ↓
+CI builds/generates manifests
+  ↓
+Push to OCI registry (signed)
+  ↓
+Flux pulls from OCI (verified)
+  ↓
+Deploy to cluster
+```
+
+## Migration from Git to OCI
+
+**Before (Git)**:
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+  name: my-app
+spec:
+  url: https://github.com/org/repo
+  ref:
+    branch: main
+```
+
+**After (OCI)**:
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: OCIRepository
+metadata:
+  name: my-app-oci
+spec:
+  url: oci://ghcr.io/org/app-config
+  ref:
+    tag: v1.0.0
+```
+
+**Update Kustomization/HelmRelease** sourceRef to point to OCIRepository
+
+## Supported Registries
+
+- ✅ GitHub Container Registry (ghcr.io)
+- ✅ Docker Hub
+- ✅ AWS ECR
+- ✅ Google Artifact Registry
+- ✅ Azure Container Registry
+- ✅ Harbor
+- ✅ GitLab Container Registry
+
+## Troubleshooting
+
+**Artifact not found**:
+```bash
+flux get sources oci
+kubectl describe ocirepository <name>
+
+# Verify artifact exists
+crane digest ghcr.io/org/app:v1.0.0
+```
+
+**Authentication failures**:
+```bash
+# Check secret
+kubectl get secret -n flux-system
+
+# Test manually
+crane manifest ghcr.io/org/app:v1.0.0
+```
+
+**Signature verification fails**:
+```bash
+# Verify locally
+cosign verify ghcr.io/org/app:v1.0.0
+
+# Check public key secret
+kubectl get secret cosign-public-key -o yaml
+```
+
+## 2025 Recommendation
+
+**Adopt OCI artifacts** for:
+- Helm charts (already standard)
+- Generated manifests (CI output)
+- Multi-environment configs
+
+**Keep Git for**:
+- Source manifests
+- Infrastructure definitions
+- Team collaboration workflows

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

@@ -0,0 +1,94 @@
+# Progressive Delivery with GitOps (2024-2025)
+
+## Argo Rollouts (with ArgoCD)
+
+**Current Focus**: Kubernetes-native progressive delivery
+
+**Deployment Strategies**:
+
+### 1. Canary
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: my-app
+spec:
+  strategy:
+    canary:
+      steps:
+      - setWeight: 20
+      - pause: {duration: 5m}
+      - setWeight: 50
+      - pause: {duration: 5m}
+      - setWeight: 100
+```
+
+### 2. Blue-Green
+```yaml
+spec:
+  strategy:
+    blueGreen:
+      activeService: my-app
+      previewService: my-app-preview
+      autoPromotionEnabled: false
+```
+
+### 3. Analysis with Metrics
+```yaml
+spec:
+  strategy:
+    canary:
+      analysis:
+        templates:
+        - templateName: success-rate
+        args:
+        - name: service-name
+          value: my-app
+```
+
+**Metric Providers**: Prometheus, Datadog, New Relic, CloudWatch
+
+## Flagger (with Flux)
+
+**Installation**:
+```bash
+flux install
+kubectl apply -k github.com/fluxcd/flagger//kustomize/linkerd
+```
+
+**Canary with Flagger**:
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: Canary
+metadata:
+  name: my-app
+spec:
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: my-app
+  service:
+    port: 9898
+  analysis:
+    interval: 1m
+    threshold: 5
+    maxWeight: 50
+    stepWeight: 10
+    metrics:
+    - name: request-success-rate
+      thresholdRange:
+        min: 99
+```
+
+## Best Practices
+
+1. **Start with Manual Approval** (autoPromotionEnabled: false)
+2. **Monitor Key Metrics** (error rate, latency, saturation)
+3. **Set Conservative Steps** (10%, 25%, 50%, 100%)
+4. **Define Rollback Criteria** (error rate > 1%)
+5. **Test in Staging First**
+
+## 2025 Recommendation
+
+**For ArgoCD users**: Argo Rollouts (tight integration, UI support)
+**For Flux users**: Flagger (CNCF project, modular design)

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

@@ -0,0 +1,184 @@
+# GitOps Repository Patterns (2024-2025)
+
+## Monorepo vs Polyrepo
+
+### Monorepo Pattern
+
+**Structure**:
+```
+gitops-repo/
+├── apps/
+│   ├── frontend/
+│   ├── backend/
+│   └── database/
+├── infrastructure/
+│   ├── ingress/
+│   ├── monitoring/
+│   └── secrets/
+└── clusters/
+    ├── dev/
+    ├── staging/
+    └── production/
+```
+
+**Pros**:
+- Single source of truth
+- Atomic changes across apps
+- Easier to start with
+- Simpler CI/CD
+
+**Cons**:
+- Scaling issues (>100 apps)
+- RBAC complexity
+- Large repo size
+- Blast radius concerns
+
+**Best for**: Startups, small teams (< 20 apps), single team ownership
+
+### Polyrepo Pattern
+
+**Structure**:
+```
+infrastructure-repo/     (Platform team)
+app-team-1-repo/        (Team 1)
+app-team-2-repo/        (Team 2)
+cluster-config-repo/    (Platform team)
+```
+
+**Pros**:
+- Clear ownership boundaries
+- Better RBAC (repo-level)
+- Scales to 100s of apps
+- Team autonomy
+
+**Cons**:
+- More complex setup
+- Cross-repo dependencies
+- Multiple CI/CD pipelines
+
+**Best for**: Large orgs, multiple teams, clear separation of concerns
+
+## Common Patterns
+
+### 1. Repo Per Team
+- Each team has own repo
+- Platform team manages infra repo
+- Hub cluster manages all
+
+### 2. Repo Per App
+- Each app in separate repo
+- Good for microservices
+- Maximum autonomy
+
+### 3. Hybrid (Recommended)
+- Infrastructure monorepo (platform team)
+- Application polyrepo (dev teams)
+- Best of both worlds
+
+## App-of-Apps Pattern (ArgoCD)
+
+**Root Application**:
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: root
+spec:
+  source:
+    repoURL: https://github.com/org/gitops
+    path: apps/
+  destination:
+    server: https://kubernetes.default.svc
+```
+
+**Apps Directory**:
+```
+apps/
+├── app1.yaml    (Application manifest)
+├── app2.yaml
+└── app3.yaml
+```
+
+**Benefits**: Centralized management, single sync point
+
+## Environment Structure
+
+### Option 1: Directory Per Environment
+```
+apps/
+├── base/
+│   └── kustomization.yaml
+└── overlays/
+    ├── dev/
+    ├── staging/
+    └── production/
+```
+
+### Option 2: Branch Per Environment
+```
+main branch      → production
+staging branch   → staging
+dev branch       → development
+```
+
+**Don't Repeat YAML**: Use Kustomize bases + overlays
+
+## Flux Repository Organization
+
+**Recommended Structure**:
+```
+flux-repo/
+├── clusters/
+│   ├── production/
+│   │   ├── flux-system/
+│   │   ├── apps.yaml
+│   │   └── infrastructure.yaml
+│   └── staging/
+├── apps/
+│   └── podinfo/
+│       ├── kustomization.yaml
+│       └── release.yaml
+└── infrastructure/
+    └── sources/
+        ├── gitrepositories.yaml
+        └── ocirepositories.yaml
+```
+
+## Kustomize vs Helm in GitOps
+
+**Kustomize** (recommended for GitOps):
+- Native Kubernetes
+- Declarative patches
+- No templating language
+
+**Helm** (when necessary):
+- Third-party charts
+- Complex applications
+- Need parameterization
+
+**Best Practice**: Kustomize for your apps, Helm for third-party
+
+## Promotion Strategies
+
+### 1. Manual PR-based
+```
+dev/ → (PR) → staging/ → (PR) → production/
+```
+
+### 2. Automated with CI
+```
+dev/ → (auto-promote on tests pass) → staging/ → (manual approval) → production/
+```
+
+### 3. Progressive with Canary
+```
+production/stable/ → canary deployment → production/all/
+```
+
+## 2024-2025 Recommendations
+
+1. **Start with monorepo**, migrate to polyrepo when needed
+2. **Use Kustomize bases + overlays** (don't repeat YAML)
+3. **Separate infrastructure from applications**
+4. **Implement promotion workflows** (dev → staging → prod)
+5. **Never commit directly to production** (always PR)