devstack 0.1.0

package/vendor/skills/skills/argocd-expert/SKILL.md

@@ -0,0 +1,767 @@
+---
+name: argocd-expert
+version: 1.0.0
+description: Expert-level ArgoCD GitOps deployment, application management, sync strategies, and production operations
+category: devops
+author: PCL Team
+license: Apache-2.0
+tags:
+  - argocd
+  - gitops
+  - kubernetes
+  - continuous-deployment
+  - declarative
+  - automation
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash(argocd:*, kubectl:*)
+  - Glob
+  - Grep
+requirements:
+  argocd: ">=2.9"
+  kubernetes: ">=1.28"
+---
+
+# ArgoCD Expert
+
+You are an expert in ArgoCD with deep knowledge of GitOps workflows, application deployment, sync strategies, RBAC, and production operations. You design and manage declarative, automated deployment pipelines following GitOps best practices.
+
+## Core Expertise
+
+### ArgoCD Architecture
+
+**Components:**
+
+```
+ArgoCD:
+├── API Server (UI/CLI/API)
+├── Repository Server (Git interaction)
+├── Application Controller (K8s reconciliation)
+├── Redis (caching)
+├── Dex (SSO/RBAC)
+└── ApplicationSet Controller (multi-cluster)
+```
+
+### Installation
+
+**Install ArgoCD:**
+
+```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
+
+# Install with HA
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml
+
+# Get admin password
+kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
+
+# Port forward to access UI
+kubectl port-forward svc/argocd-server -n argocd 8080:443
+
+# Login via CLI
+argocd login localhost:8080 --username admin --password <password>
+
+# Change admin password
+argocd account update-password
+```
+
+**Production Installation with Custom Values:**
+
+```yaml
+# argocd-values.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-cm
+  namespace: argocd
+data:
+  # Repository credentials
+  repositories: |
+    - url: https://github.com/myorg/myrepo
+      passwordSecret:
+        name: github-secret
+        key: password
+      usernameSecret:
+        name: github-secret
+        key: username
+
+  # Resource customizations
+  resource.customizations: |
+    networking.k8s.io/Ingress:
+      health.lua: |
+        hs = {}
+        hs.status = "Healthy"
+        return hs
+
+  # Timeout settings
+  timeout.reconciliation: 180s
+
+  # Diff customizations
+  resource.compareoptions: |
+    ignoreAggregatedRoles: true
+
+  # UI customization
+  ui.cssurl: "https://cdn.example.com/custom.css"
+```
+
+### Application CRD
+
+**Basic Application:**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: myapp
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: production
+
+  source:
+    repoURL: https://github.com/myorg/myapp
+    targetRevision: main
+    path: k8s/overlays/production
+
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+      allowEmpty: false
+    syncOptions:
+      - CreateNamespace=true
+    retry:
+      limit: 5
+      backoff:
+        duration: 5s
+        factor: 2
+        maxDuration: 3m
+```
+
+**Helm Application:**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: myapp-helm
+  namespace: argocd
+spec:
+  project: production
+
+  source:
+    repoURL: https://github.com/myorg/helm-charts
+    targetRevision: main
+    path: charts/myapp
+    helm:
+      releaseName: myapp
+      valueFiles:
+        - values.yaml
+        - values-production.yaml
+      parameters:
+        - name: image.tag
+          value: "v2.0.0"
+        - name: replicaCount
+          value: "5"
+      values: |
+        ingress:
+          enabled: true
+          hosts:
+          - myapp.example.com
+
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+```
+
+**Kustomize Application:**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: myapp-kustomize
+  namespace: argocd
+spec:
+  project: production
+
+  source:
+    repoURL: https://github.com/myorg/myapp
+    targetRevision: main
+    path: k8s/overlays/production
+    kustomize:
+      namePrefix: prod-
+      nameSuffix: -v2
+      images:
+        - myregistry.io/myapp:v2.0.0
+      commonLabels:
+        environment: production
+      commonAnnotations:
+        managed-by: argocd
+
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+### AppProject
+
+**Project with RBAC:**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: AppProject
+metadata:
+  name: production
+  namespace: argocd
+spec:
+  description: Production applications
+
+  # Source repositories
+  sourceRepos:
+    - https://github.com/myorg/*
+    - https://charts.bitnami.com/bitnami
+
+  # Destination clusters and namespaces
+  destinations:
+    - namespace: production
+      server: https://kubernetes.default.svc
+    - namespace: monitoring
+      server: https://kubernetes.default.svc
+
+  # Cluster resource whitelist
+  clusterResourceWhitelist:
+    - group: "*"
+      kind: "*"
+
+  # Namespace resource blacklist
+  namespaceResourceBlacklist:
+    - group: ""
+      kind: ResourceQuota
+    - group: ""
+      kind: LimitRange
+
+  # RBAC roles
+  roles:
+    - name: developer
+      description: Developers can sync apps
+      policies:
+        - p, proj:production:developer, applications, sync, production/*, allow
+        - p, proj:production:developer, applications, get, production/*, allow
+      groups:
+        - developers
+
+    - name: admin
+      description: Admins have full access
+      policies:
+        - p, proj:production:admin, applications, *, production/*, allow
+      groups:
+        - platform-team
+
+  # Sync windows
+  syncWindows:
+    - kind: allow
+      schedule: "0 9 * * 1-5" # 9 AM weekdays
+      duration: 8h
+      applications:
+        - "*"
+    - kind: deny
+      schedule: "0 0 * * 0,6" # Weekends
+      duration: 24h
+      applications:
+        - "*"
+
+  # Orphaned resources
+  orphanedResources:
+    warn: true
+```
+
+### ApplicationSet
+
+**Git Generator (Multi-Environment):**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: myapp-environments
+  namespace: argocd
+spec:
+  generators:
+    - git:
+        repoURL: https://github.com/myorg/myapp
+        revision: main
+        directories:
+          - path: k8s/overlays/*
+
+  template:
+    metadata:
+      name: "myapp-{{path.basename}}"
+    spec:
+      project: production
+      source:
+        repoURL: https://github.com/myorg/myapp
+        targetRevision: main
+        path: "{{path}}"
+      destination:
+        server: https://kubernetes.default.svc
+        namespace: "{{path.basename}}"
+      syncPolicy:
+        automated:
+          prune: true
+          selfHeal: true
+```
+
+**List Generator (Multi-Cluster):**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: myapp-clusters
+  namespace: argocd
+spec:
+  generators:
+    - list:
+        elements:
+          - cluster: us-east-1
+            url: https://cluster1.example.com
+            namespace: production
+          - cluster: us-west-2
+            url: https://cluster2.example.com
+            namespace: production
+          - cluster: eu-central-1
+            url: https://cluster3.example.com
+            namespace: production
+
+  template:
+    metadata:
+      name: "myapp-{{cluster}}"
+    spec:
+      project: production
+      source:
+        repoURL: https://github.com/myorg/myapp
+        targetRevision: main
+        path: k8s/overlays/production
+      destination:
+        server: "{{url}}"
+        namespace: "{{namespace}}"
+      syncPolicy:
+        automated:
+          prune: true
+          selfHeal: true
+```
+
+**Matrix Generator (Environments × Clusters):**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: myapp-matrix
+  namespace: argocd
+spec:
+  generators:
+    - matrix:
+        generators:
+          - git:
+              repoURL: https://github.com/myorg/myapp
+              revision: main
+              directories:
+                - path: k8s/overlays/*
+          - list:
+              elements:
+                - cluster: prod-us
+                  url: https://prod-us.example.com
+                - cluster: prod-eu
+                  url: https://prod-eu.example.com
+
+  template:
+    metadata:
+      name: "myapp-{{path.basename}}-{{cluster}}"
+    spec:
+      project: production
+      source:
+        repoURL: https://github.com/myorg/myapp
+        targetRevision: main
+        path: "{{path}}"
+      destination:
+        server: "{{url}}"
+        namespace: "{{path.basename}}"
+      syncPolicy:
+        automated:
+          prune: true
+          selfHeal: true
+```
+
+### Sync Strategies
+
+**Automatic Sync with Policies:**
+
+```yaml
+syncPolicy:
+  automated:
+    prune: true # Delete resources not in Git
+    selfHeal: true # Force sync on drift
+    allowEmpty: false # Prevent deletion of all resources
+
+  syncOptions:
+    - CreateNamespace=true
+    - PrunePropagationPolicy=foreground
+    - PruneLast=true
+    - ApplyOutOfSyncOnly=true
+    - RespectIgnoreDifferences=true
+    - ServerSideApply=true
+
+  retry:
+    limit: 5
+    backoff:
+      duration: 5s
+      factor: 2
+      maxDuration: 3m
+```
+
+**Sync Hooks:**
+
+```yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: database-migration
+  annotations:
+    argocd.argoproj.io/hook: PreSync
+    argocd.argoproj.io/hook-delete-policy: HookSucceeded
+    argocd.argoproj.io/sync-wave: "1"
+spec:
+  template:
+    spec:
+      containers:
+        - name: migration
+          image: myapp:latest
+          command: ["./migrate.sh"]
+      restartPolicy: Never
+---
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: smoke-test
+  annotations:
+    argocd.argoproj.io/hook: PostSync
+    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
+    argocd.argoproj.io/sync-wave: "5"
+spec:
+  template:
+    spec:
+      containers:
+        - name: test
+          image: curlimages/curl:latest
+          command: ["curl", "http://myapp/health"]
+      restartPolicy: Never
+```
+
+### SSO Configuration
+
+**Dex with GitHub:**
+
+```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: $dex.github.clientId
+        clientSecret: $dex.github.clientSecret
+        orgs:
+        - name: myorg
+          teams:
+          - platform-team
+          - developers
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-rbac-cm
+  namespace: argocd
+data:
+  policy.default: role:readonly
+  policy.csv: |
+    # Admins have full access
+    g, myorg:platform-team, role:admin
+
+    # Developers can sync apps
+    g, myorg:developers, role:developer
+
+    # Developer role definition
+    p, role:developer, applications, get, */*, allow
+    p, role:developer, applications, sync, */*, allow
+    p, role:developer, repositories, get, *, allow
+    p, role:developer, projects, get, *, allow
+
+  scopes: "[groups, email]"
+```
+
+### Health Checks
+
+**Custom Health Check:**
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-cm
+  namespace: argocd
+data:
+  resource.customizations.health.argoproj.io_Rollout: |
+    hs = {}
+    if obj.status ~= nil then
+      if obj.status.conditions ~= nil then
+        for i, condition in ipairs(obj.status.conditions) do
+          if condition.type == "Progressing" and condition.reason == "RolloutCompleted" then
+            hs.status = "Healthy"
+            hs.message = "Rollout completed"
+            return hs
+          end
+        end
+      end
+    end
+    hs.status = "Progressing"
+    hs.message = "Rollout in progress"
+    return hs
+```
+
+## argocd CLI Commands
+
+**Application Management:**
+
+```bash
+# Create application
+argocd app create myapp \
+  --repo https://github.com/myorg/myapp \
+  --path k8s/overlays/production \
+  --dest-server https://kubernetes.default.svc \
+  --dest-namespace production
+
+# List applications
+argocd app list
+argocd app list -o wide
+
+# Get application details
+argocd app get myapp
+argocd app get myapp --refresh
+
+# Sync application
+argocd app sync myapp
+argocd app sync myapp --prune
+argocd app sync myapp --dry-run
+argocd app sync myapp --force
+
+# Rollback
+argocd app rollback myapp
+
+# Delete application
+argocd app delete myapp
+argocd app delete myapp --cascade=false  # Keep resources
+```
+
+**Repository Management:**
+
+```bash
+# Add repository
+argocd repo add https://github.com/myorg/myapp \
+  --username myuser \
+  --password mytoken
+
+# List repositories
+argocd repo list
+
+# Remove repository
+argocd repo rm https://github.com/myorg/myapp
+```
+
+**Cluster Management:**
+
+```bash
+# Add cluster
+argocd cluster add my-cluster-context
+
+# List clusters
+argocd cluster list
+
+# Remove cluster
+argocd cluster rm https://cluster.example.com
+```
+
+**Project Management:**
+
+```bash
+# Create project
+argocd proj create production
+
+# Add repository to project
+argocd proj add-source production https://github.com/myorg/*
+
+# Add destination to project
+argocd proj add-destination production \
+  https://kubernetes.default.svc \
+  production
+
+# List projects
+argocd proj list
+
+# Get project details
+argocd proj get production
+```
+
+## Best Practices
+
+### 1. Use AppProjects
+
+```yaml
+# Separate projects by team/environment
+- production
+- staging
+- development
+```
+
+### 2. Enable Auto-Sync with Pruning
+
+```yaml
+syncPolicy:
+  automated:
+    prune: true
+    selfHeal: true
+```
+
+### 3. Use Sync Waves
+
+```yaml
+annotations:
+  argocd.argoproj.io/sync-wave: "1" # Deploy order
+```
+
+### 4. Implement Health Checks
+
+```yaml
+# Custom health checks for CRDs
+resource.customizations.health.<group>_<kind>
+```
+
+### 5. Use Sync Windows
+
+```yaml
+# Control deployment times
+syncWindows:
+  - kind: allow
+    schedule: "0 9 * * 1-5" # Business hours
+    duration: 8h
+```
+
+### 6. Enable Notifications
+
+```bash
+# Slack, Teams, email notifications
+argocd admin notifications controller
+```
+
+### 7. Use ApplicationSets
+
+```yaml
+# Manage multiple apps declaratively
+kind: ApplicationSet
+```
+
+## Anti-Patterns
+
+**1. No Resource Pruning:**
+
+```yaml
+# BAD: Orphaned resources
+automated: {}
+
+# GOOD: Enable pruning
+automated:
+  prune: true
+```
+
+**2. Manual Sync Only:**
+
+```yaml
+# BAD: Requires manual intervention
+syncPolicy: {}
+
+# GOOD: Automated sync
+syncPolicy:
+  automated:
+    prune: true
+    selfHeal: true
+```
+
+**3. Single Giant Application:**
+
+```yaml
+# BAD: One app for everything
+# GOOD: Separate apps by component/service
+```
+
+**4. No RBAC:**
+
+```yaml
+# GOOD: Always implement project-level RBAC
+roles:
+  - name: developer
+    policies:
+      - p, proj:prod:dev, applications, sync, prod/*, allow
+```
+
+## Approach
+
+When implementing ArgoCD:
+
+1. **Start Simple**: Deploy one application first
+2. **GitOps Everything**: All config in Git
+3. **Automate**: Enable auto-sync and self-heal
+4. **Organize**: Use AppProjects for isolation
+5. **RBAC**: Implement least-privilege access
+6. **Monitor**: Set up notifications and alerts
+7. **Scale**: Use ApplicationSets for multi-cluster/multi-env
+8. **Security**: Enable SSO and audit logging
+
+Always design GitOps workflows that are declarative, auditable, and automated following cloud-native principles.
+
+## Resources
+
+- ArgoCD Documentation: https://argo-cd.readthedocs.io/
+- GitOps Principles: https://opengitops.dev/
+- ApplicationSet: https://argocd-applicationset.readthedocs.io/
+- ArgoCD Notifications: https://argocd-notifications.readthedocs.io/