specweave 0.3.13 → 0.4.1

package/src/skills/gitops-workflow/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: gitops-workflow
+description: Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOps practices, automating Kubernetes deployments, or setting up declarative infrastructure management.
+---
+
+# GitOps Workflow
+
+Complete guide to implementing GitOps workflows with ArgoCD and Flux for automated Kubernetes deployments.
+
+## Purpose
+
+Implement declarative, Git-based continuous delivery for Kubernetes using ArgoCD or Flux CD, following OpenGitOps principles.
+
+## When to Use This Skill
+
+- Set up GitOps for Kubernetes clusters
+- Automate application deployments from Git
+- Implement progressive delivery strategies
+- Manage multi-cluster deployments
+- Configure automated sync policies
+- Set up secret management in GitOps
+
+## OpenGitOps Principles
+
+1. **Declarative** - Entire system described declaratively
+2. **Versioned and Immutable** - Desired state stored in Git
+3. **Pulled Automatically** - Software agents pull desired state
+4. **Continuously Reconciled** - Agents reconcile actual vs desired state
+
+## ArgoCD Setup
+
+### 1. Installation
+
+```bash
+# Create namespace
+kubectl create namespace argocd
+
+# Install ArgoCD
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+
+# Get admin password
+kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
+```
+
+**Reference:** See `references/argocd-setup.md` for detailed setup
+
+### 2. Repository Structure
+
+```
+gitops-repo/
+├── apps/
+│   ├── production/
+│   │   ├── app1/
+│   │   │   ├── kustomization.yaml
+│   │   │   └── deployment.yaml
+│   │   └── app2/
+│   └── staging/
+├── infrastructure/
+│   ├── ingress-nginx/
+│   ├── cert-manager/
+│   └── monitoring/
+└── argocd/
+    ├── applications/
+    └── projects/
+```
+
+### 3. Create Application
+
+```yaml
+# argocd/applications/my-app.yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: my-app
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/org/gitops-repo
+    targetRevision: main
+    path: apps/production/my-app
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+    - CreateNamespace=true
+```
+
+### 4. App of Apps Pattern
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: applications
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/org/gitops-repo
+    targetRevision: main
+    path: argocd/applications
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: argocd
+  syncPolicy:
+    automated: {}
+```
+
+## Flux CD Setup
+
+### 1. Installation
+
+```bash
+# Install Flux CLI
+curl -s https://fluxcd.io/install.sh | sudo bash
+
+# Bootstrap Flux
+flux bootstrap github \
+  --owner=org \
+  --repository=gitops-repo \
+  --branch=main \
+  --path=clusters/production \
+  --personal
+```
+
+### 2. Create GitRepository
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+  name: my-app
+  namespace: flux-system
+spec:
+  interval: 1m
+  url: https://github.com/org/my-app
+  ref:
+    branch: main
+```
+
+### 3. Create Kustomization
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: my-app
+  namespace: flux-system
+spec:
+  interval: 5m
+  path: ./deploy
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: my-app
+```
+
+## Sync Policies
+
+### Auto-Sync Configuration
+
+**ArgoCD:**
+```yaml
+syncPolicy:
+  automated:
+    prune: true      # Delete resources not in Git
+    selfHeal: true   # Reconcile manual changes
+    allowEmpty: false
+  retry:
+    limit: 5
+    backoff:
+      duration: 5s
+      factor: 2
+      maxDuration: 3m
+```
+
+**Flux:**
+```yaml
+spec:
+  interval: 1m
+  prune: true
+  wait: true
+  timeout: 5m
+```
+
+**Reference:** See `references/sync-policies.md`
+
+## Progressive Delivery
+
+### Canary Deployment with ArgoCD Rollouts
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: my-app
+spec:
+  replicas: 5
+  strategy:
+    canary:
+      steps:
+      - setWeight: 20
+      - pause: {duration: 1m}
+      - setWeight: 50
+      - pause: {duration: 2m}
+      - setWeight: 100
+```
+
+### Blue-Green Deployment
+
+```yaml
+strategy:
+  blueGreen:
+    activeService: my-app
+    previewService: my-app-preview
+    autoPromotionEnabled: false
+```
+
+## Secret Management
+
+### External Secrets Operator
+
+```yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: db-credentials
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: aws-secrets-manager
+    kind: SecretStore
+  target:
+    name: db-credentials
+  data:
+  - secretKey: password
+    remoteRef:
+      key: prod/db/password
+```
+
+### Sealed Secrets
+
+```bash
+# Encrypt secret
+kubeseal --format yaml < secret.yaml > sealed-secret.yaml
+
+# Commit sealed-secret.yaml to Git
+```
+
+## Best Practices
+
+1. **Use separate repos or branches** for different environments
+2. **Implement RBAC** for Git repositories
+3. **Enable notifications** for sync failures
+4. **Use health checks** for custom resources
+5. **Implement approval gates** for production
+6. **Keep secrets out of Git** (use External Secrets)
+7. **Use App of Apps pattern** for organization
+8. **Tag releases** for easy rollback
+9. **Monitor sync status** with alerts
+10. **Test changes** in staging first
+
+## Troubleshooting
+
+**Sync failures:**
+```bash
+argocd app get my-app
+argocd app sync my-app --prune
+```
+
+**Out of sync status:**
+```bash
+argocd app diff my-app
+argocd app sync my-app --force
+```
+
+## Related Skills
+
+- `k8s-manifest-generator` - For creating manifests
+- `helm-chart-scaffolding` - For packaging applications

package/src/skills/gitops-workflow/references/argocd-setup.md

@@ -0,0 +1,134 @@
+# ArgoCD Setup and Configuration
+
+## Installation Methods
+
+### 1. Standard Installation
+```bash
+kubectl create namespace argocd
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+```
+
+### 2. High Availability Installation
+```bash
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml
+```
+
+### 3. Helm Installation
+```bash
+helm repo add argo https://argoproj.github.io/argo-helm
+helm install argocd argo/argo-cd -n argocd --create-namespace
+```
+
+## Initial Configuration
+
+### Access ArgoCD UI
+```bash
+# Port forward
+kubectl port-forward svc/argocd-server -n argocd 8080:443
+
+# Get initial admin password
+argocd admin initial-password -n argocd
+```
+
+### Configure Ingress
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: argocd-server-ingress
+  namespace: argocd
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
+    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: argocd.example.com
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: argocd-server
+            port:
+              number: 443
+  tls:
+  - hosts:
+    - argocd.example.com
+    secretName: argocd-secret
+```
+
+## CLI Configuration
+
+### Login
+```bash
+argocd login argocd.example.com --username admin
+```
+
+### Add Repository
+```bash
+argocd repo add https://github.com/org/repo --username user --password token
+```
+
+### Create Application
+```bash
+argocd app create my-app \
+  --repo https://github.com/org/repo \
+  --path apps/my-app \
+  --dest-server https://kubernetes.default.svc \
+  --dest-namespace production
+```
+
+## SSO Configuration
+
+### GitHub OAuth
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-cm
+  namespace: argocd
+data:
+  url: https://argocd.example.com
+  dex.config: |
+    connectors:
+      - type: github
+        id: github
+        name: GitHub
+        config:
+          clientID: $GITHUB_CLIENT_ID
+          clientSecret: $GITHUB_CLIENT_SECRET
+          orgs:
+          - name: my-org
+```
+
+## RBAC Configuration
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-rbac-cm
+  namespace: argocd
+data:
+  policy.default: role:readonly
+  policy.csv: |
+    p, role:developers, applications, *, */dev, allow
+    p, role:operators, applications, *, */*, allow
+    g, my-org:devs, role:developers
+    g, my-org:ops, role:operators
+```
+
+## Best Practices
+
+1. Enable SSO for production
+2. Implement RBAC policies
+3. Use separate projects for teams
+4. Enable audit logging
+5. Configure notifications
+6. Use ApplicationSets for multi-cluster
+7. Implement resource hooks
+8. Configure health checks
+9. Use sync windows for maintenance
+10. Monitor with Prometheus metrics

package/src/skills/gitops-workflow/references/sync-policies.md

@@ -0,0 +1,131 @@
+# GitOps Sync Policies
+
+## ArgoCD Sync Policies
+
+### Automated Sync
+```yaml
+syncPolicy:
+  automated:
+    prune: true       # Delete resources removed from Git
+    selfHeal: true    # Reconcile manual changes
+    allowEmpty: false # Prevent empty sync
+```
+
+### Manual Sync
+```yaml
+syncPolicy:
+  syncOptions:
+  - PrunePropagationPolicy=foreground
+  - CreateNamespace=true
+```
+
+### Sync Windows
+```yaml
+syncWindows:
+- kind: allow
+  schedule: "0 8 * * *"
+  duration: 1h
+  applications:
+  - my-app
+- kind: deny
+  schedule: "0 22 * * *"
+  duration: 8h
+  applications:
+  - '*'
+```
+
+### Retry Policy
+```yaml
+syncPolicy:
+  retry:
+    limit: 5
+    backoff:
+      duration: 5s
+      factor: 2
+      maxDuration: 3m
+```
+
+## Flux Sync Policies
+
+### Kustomization Sync
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: my-app
+spec:
+  interval: 5m
+  prune: true
+  wait: true
+  timeout: 5m
+  retryInterval: 1m
+  force: false
+```
+
+### Source Sync Interval
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+  name: my-app
+spec:
+  interval: 1m
+  timeout: 60s
+```
+
+## Health Assessment
+
+### Custom Health Checks
+```yaml
+# ArgoCD
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-cm
+  namespace: argocd
+data:
+  resource.customizations.health.MyCustomResource: |
+    hs = {}
+    if obj.status ~= nil then
+      if obj.status.conditions ~= nil then
+        for i, condition in ipairs(obj.status.conditions) do
+          if condition.type == "Ready" and condition.status == "False" then
+            hs.status = "Degraded"
+            hs.message = condition.message
+            return hs
+          end
+          if condition.type == "Ready" and condition.status == "True" then
+            hs.status = "Healthy"
+            hs.message = condition.message
+            return hs
+          end
+        end
+      end
+    end
+    hs.status = "Progressing"
+    hs.message = "Waiting for status"
+    return hs
+```
+
+## Sync Options
+
+### Common Sync Options
+- `PrunePropagationPolicy=foreground` - Wait for pruned resources to be deleted
+- `CreateNamespace=true` - Auto-create namespace
+- `Validate=false` - Skip kubectl validation
+- `PruneLast=true` - Prune resources after sync
+- `RespectIgnoreDifferences=true` - Honor ignore differences
+- `ApplyOutOfSyncOnly=true` - Only apply out-of-sync resources
+
+## Best Practices
+
+1. Use automated sync for non-production
+2. Require manual approval for production
+3. Configure sync windows for maintenance
+4. Implement health checks for custom resources
+5. Use selective sync for large applications
+6. Configure appropriate retry policies
+7. Monitor sync failures with alerts
+8. Use prune with caution in production
+9. Test sync policies in staging
+10. Document sync behavior for teams