@techwavedev/agi-agent-kit 1.1.7 → 1.2.1

package/templates/skills/ec/consul/references/ha_config.md

@@ -0,0 +1,196 @@
+# Consul HA Configuration Patterns
+
+## Table of Contents
+
+- [3-Server HA (Standard)](#3-server-ha-standard)
+- [5-Server HA (High Availability)](#5-server-ha-high-availability)
+- [Multi-Datacenter Federation](#multi-datacenter-federation)
+- [Resource Sizing](#resource-sizing)
+- [Storage Configuration](#storage-configuration)
+
+---
+
+## 3-Server HA (Standard)
+
+Minimum HA configuration tolerating 1 server failure.
+
+```yaml
+global:
+  name: consul
+  datacenter: dc1
+  gossipEncryption:
+    autoGenerate: true
+  tls:
+    enabled: true
+    enableAutoEncrypt: true
+  acls:
+    manageSystemACLs: true
+
+server:
+  replicas: 3
+  bootstrapExpect: 3
+  resources:
+    requests:
+      memory: "200Mi"
+      cpu: "100m"
+    limits:
+      memory: "500Mi"
+      cpu: "500m"
+  storageClass: gp3
+  storage: 10Gi
+  affinity: |
+    podAntiAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
+        - labelSelector:
+            matchLabels:
+              app: consul
+              component: server
+          topologyKey: kubernetes.io/hostname
+  topologySpreadConstraints: |
+    - maxSkew: 1
+      topologyKey: topology.kubernetes.io/zone
+      whenUnsatisfiable: DoNotSchedule
+      labelSelector:
+        matchLabels:
+          app: consul
+          component: server
+
+connectInject:
+  enabled: true
+  default: false
+
+controller:
+  enabled: true
+```
+
+---
+
+## 5-Server HA (High Availability)
+
+Enhanced HA configuration tolerating 2 server failures.
+
+```yaml
+server:
+  replicas: 5
+  bootstrapExpect: 5
+  resources:
+    requests:
+      memory: "500Mi"
+      cpu: "200m"
+    limits:
+      memory: "1Gi"
+      cpu: "1000m"
+  storageClass: gp3
+  storage: 20Gi
+  affinity: |
+    podAntiAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
+        - labelSelector:
+            matchLabels:
+              app: consul
+              component: server
+          topologyKey: topology.kubernetes.io/zone
+```
+
+---
+
+## Multi-Datacenter Federation
+
+### Primary Datacenter
+
+```yaml
+global:
+  name: consul
+  datacenter: dc1
+  tls:
+    enabled: true
+    enableAutoEncrypt: true
+  acls:
+    manageSystemACLs: true
+  federation:
+    enabled: true
+    createFederationSecret: true
+
+meshGateway:
+  enabled: true
+  replicas: 2
+
+server:
+  replicas: 3
+```
+
+### Secondary Datacenter
+
+```yaml
+global:
+  name: consul
+  datacenter: dc2
+  tls:
+    enabled: true
+    enableAutoEncrypt: true
+    caCert:
+      secretName: consul-federation
+      secretKey: caCert
+  acls:
+    manageSystemACLs: true
+    replicationToken:
+      secretName: consul-federation
+      secretKey: replicationToken
+  federation:
+    enabled: true
+    primaryDatacenter: dc1
+    primaryGateways:
+      - "mesh-gateway-dc1.example.com:443"
+
+meshGateway:
+  enabled: true
+  replicas: 2
+
+server:
+  replicas: 3
+  extraConfig: |
+    {
+      "primary_datacenter": "dc1",
+      "retry_join_wan": ["mesh-gateway-dc1.example.com:443"]
+    }
+```
+
+---
+
+## Resource Sizing
+
+| Cluster Size             | Servers | CPU Request | Memory Request | Storage |
+| ------------------------ | ------- | ----------- | -------------- | ------- |
+| Small (<50 services)     | 3       | 100m        | 200Mi          | 10Gi    |
+| Medium (50-200 services) | 3       | 200m        | 500Mi          | 20Gi    |
+| Large (200+ services)    | 5       | 500m        | 1Gi            | 50Gi    |
+
+---
+
+## Storage Configuration
+
+### AWS gp3 StorageClass
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: consul-storage
+provisioner: ebs.csi.aws.com
+parameters:
+  type: gp3
+  iops: "3000"
+  throughput: "125"
+  encrypted: "true"
+reclaimPolicy: Retain
+allowVolumeExpansion: true
+volumeBindingMode: WaitForFirstConsumer
+```
+
+### Consul Helm Values for Custom Storage
+
+```yaml
+server:
+  storageClass: consul-storage
+  storage: 20Gi
+```

package/templates/skills/ec/consul/references/troubleshooting.md

@@ -0,0 +1,267 @@
+# Consul Troubleshooting Guide
+
+## Table of Contents
+
+- [Cluster Formation Issues](#cluster-formation-issues)
+- [Connect Sidecar Issues](#connect-sidecar-issues)
+- [Performance Issues](#performance-issues)
+- [TLS/Certificate Issues](#tlscertificate-issues)
+- [ACL Issues](#acl-issues)
+- [Upgrade Issues](#upgrade-issues)
+
+---
+
+## Cluster Formation Issues
+
+### Servers Not Joining Cluster
+
+**Symptoms:**
+
+- `consul members` shows fewer than expected servers
+- Servers stuck in `left` or `failed` state
+
+**Diagnosis:**
+
+```bash
+# Check server logs
+kubectl logs -n consul consul-server-0 | grep -i "join\|gossip\|serf"
+
+# Check gossip key
+kubectl get secret consul-gossip-encryption-key -n consul -o jsonpath='{.data.key}' | base64 -d
+```
+
+**Solutions:**
+
+1. **Gossip key mismatch** — Ensure all servers use same key
+2. **Network policies** — Allow ports 8301 (LAN gossip), 8300 (RPC)
+3. **DNS resolution** — Check headless service resolves correctly
+
+### Raft Quorum Lost
+
+**Symptoms:**
+
+- `No cluster leader`
+- Only 1 server responding
+
+**Recovery:**
+
+```bash
+# Check raft peers
+kubectl exec -n consul consul-server-0 -- consul operator raft list-peers
+
+# Remove failed peer
+kubectl exec -n consul consul-server-0 -- consul operator raft remove-peer -address=<failed-peer-ip>:8300
+
+# If single node recovery needed (DANGEROUS - data loss possible)
+kubectl exec -n consul consul-server-0 -- consul operator raft remove-peer -address=<peer-address>
+```
+
+---
+
+## Connect Sidecar Issues
+
+### Sidecar Not Injecting
+
+**Symptoms:**
+
+- Pods start without `consul-dataplane` container
+- No Envoy sidecar
+
+**Diagnosis:**
+
+```bash
+# Check webhook
+kubectl get mutatingwebhookconfigurations | grep consul
+
+# Check injector logs
+kubectl logs -n consul -l app=consul,component=connect-injector
+
+# Check pod annotations
+kubectl get pod <pod-name> -o yaml | grep consul
+```
+
+**Solutions:**
+
+1. **Missing annotation** — Add `consul.hashicorp.com/connect-inject: "true"`
+2. **Namespace not labeled** — `kubectl label namespace myapp consul.hashicorp.com/connect-inject=true`
+3. **Webhook certificate expired** — Restart injector deployment
+
+### Sidecar CrashLoopBackOff
+
+**Symptoms:**
+
+- `consul-dataplane` container crashes
+- Pod restarts repeatedly
+
+**Diagnosis:**
+
+```bash
+# Check dataplane logs
+kubectl logs <pod-name> -c consul-dataplane
+
+# Check Envoy config
+kubectl exec <pod-name> -c consul-dataplane -- wget -qO- localhost:19000/config_dump
+```
+
+**Solutions:**
+
+1. **ACL token issues** — Verify service token exists
+2. **Upstream not found** — Check service registration
+3. **Resource limits** — Increase CPU/memory for dataplane
+
+---
+
+## Performance Issues
+
+### High Latency Between Services
+
+**Diagnosis:**
+
+```bash
+# Check Envoy stats
+kubectl exec <pod-name> -c consul-dataplane -- wget -qO- localhost:19000/stats | grep upstream
+
+# Check connect intentions
+kubectl get serviceintentions -A
+```
+
+**Solutions:**
+
+1. **Increase Envoy resources**
+
+```yaml
+annotations:
+  consul.hashicorp.com/sidecar-proxy-cpu-request: "100m"
+  consul.hashicorp.com/sidecar-proxy-memory-request: "128Mi"
+```
+
+2. **Check network policies** — Ensure direct pod-to-pod traffic allowed
+3. **Locality-aware routing** — Enable mesh gateway mode
+
+### Server High CPU
+
+**Diagnosis:**
+
+```bash
+# Check leader
+kubectl exec -n consul consul-server-0 -- consul operator raft list-peers | grep leader
+
+# Check catalog size
+kubectl exec -n consul consul-server-0 -- consul catalog services | wc -l
+```
+
+**Solutions:**
+
+1. Scale to 5 servers for read distribution
+2. Increase server resources
+3. Review service registration churn
+
+---
+
+## TLS/Certificate Issues
+
+### Certificate Errors
+
+**Symptoms:**
+
+- `x509: certificate signed by unknown authority`
+- Connect handshake failures
+
+**Diagnosis:**
+
+```bash
+# Check CA config
+kubectl exec -n consul consul-server-0 -- consul connect ca get-config
+
+# Check certificate expiry
+kubectl exec -n consul consul-server-0 -- consul tls cert-show
+```
+
+**Solutions:**
+
+1. **CA mismatch** — Ensure all clients trust the CA
+2. **Certificate rotation** — Trigger CA rotation
+3. **Auto-encrypt issues** — Verify `enableAutoEncrypt: true`
+
+### Gossip Encryption Failures
+
+**Symptoms:**
+
+- Servers can't communicate
+- `memberlist: Encrypt message failed`
+
+**Diagnosis:**
+
+```bash
+# Check keyring
+kubectl exec -n consul consul-server-0 -- consul keyring -list
+```
+
+**Solutions:**
+
+1. Ensure all nodes have the same gossip key
+2. If rotating keys, follow proper key rotation procedure
+
+---
+
+## ACL Issues
+
+### Permission Denied Errors
+
+**Diagnosis:**
+
+```bash
+# Check token
+kubectl exec -n consul consul-server-0 -- consul acl token list
+
+# Check policy
+kubectl exec -n consul consul-server-0 -- consul acl policy list
+```
+
+**Solutions:**
+
+1. Create appropriate policy for the service
+2. Attach policy to token
+3. Verify token is being used correctly
+
+### Bootstrap Token Lost
+
+**Recovery:**
+
+```bash
+# Reset bootstrap (requires server access)
+kubectl exec -n consul consul-server-0 -- consul acl bootstrap -reset
+```
+
+---
+
+## Upgrade Issues
+
+### Pods Stuck in Pending
+
+**Cause:** Volume affinity conflicts
+
+**Solution:**
+
+```bash
+# Check PVC binding
+kubectl get pvc -n consul
+
+# Delete stuck pod (statefulset will recreate)
+kubectl delete pod consul-server-X -n consul
+```
+
+### Version Incompatibility
+
+**Prevention:**
+
+- Always check [upgrade notes](https://developer.hashicorp.com/consul/docs/upgrading)
+- Upgrade one minor version at a time
+- Test in non-prod first
+
+**Recovery:**
+
+```bash
+# Rollback Helm release
+helm rollback consul <previous-revision> -n consul
+```

package/templates/skills/ec/consul/references/upgrades.md

@@ -0,0 +1,213 @@
+# Consul Upgrade Guide
+
+## Table of Contents
+
+- [Pre-Upgrade Checklist](#pre-upgrade-checklist)
+- [Upgrade Paths](#upgrade-paths)
+- [Upgrade Procedures](#upgrade-procedures)
+- [Post-Upgrade Validation](#post-upgrade-validation)
+- [Rollback Procedures](#rollback-procedures)
+- [Breaking Changes by Version](#breaking-changes-by-version)
+
+---
+
+## Pre-Upgrade Checklist
+
+### Before Any Upgrade
+
+- [ ] Review [release notes](https://developer.hashicorp.com/consul/docs/release-notes)
+- [ ] Check for breaking changes
+- [ ] Create snapshot backup
+- [ ] Verify cluster is healthy
+- [ ] Test upgrade in non-prod first
+- [ ] Plan maintenance window
+
+### Backup Commands
+
+```bash
+# Create snapshot
+kubectl exec -n consul consul-server-0 -- consul snapshot save /tmp/backup.snap
+kubectl cp consul/consul-server-0:/tmp/backup.snap ./consul-backup-$(date +%Y%m%d-%H%M).snap
+
+# Verify backup
+consul snapshot inspect ./consul-backup-*.snap
+```
+
+### Health Verification
+
+```bash
+# All servers healthy
+kubectl exec -n consul consul-server-0 -- consul members
+
+# Raft consensus
+kubectl exec -n consul consul-server-0 -- consul operator raft list-peers
+
+# No critical services down
+kubectl exec -n consul consul-server-0 -- consul catalog services
+```
+
+---
+
+## Upgrade Paths
+
+### Consul Version Compatibility
+
+| From   | To     | Notes                                           |
+| ------ | ------ | ----------------------------------------------- |
+| 1.15.x | 1.16.x | Direct upgrade supported                        |
+| 1.16.x | 1.17.x | Direct upgrade supported                        |
+| 1.17.x | 1.18.x | Direct upgrade supported                        |
+| 1.15.x | 1.18.x | **Step upgrade required** (1.15→1.16→1.17→1.18) |
+
+### consul-k8s Helm Chart Versions
+
+| Helm Chart | Consul Version | Notes  |
+| ---------- | -------------- | ------ |
+| 1.0.x      | 1.14.x         | Legacy |
+| 1.1.x      | 1.15.x         |        |
+| 1.2.x      | 1.16.x         |        |
+| 1.3.x      | 1.17.x         |        |
+| 1.4.x      | 1.18.x         | Latest |
+
+---
+
+## Upgrade Procedures
+
+### Standard Helm Upgrade
+
+```bash
+# 1. Check current version
+helm list -n consul
+kubectl exec -n consul consul-server-0 -- consul version
+
+# 2. Update Helm repo
+helm repo update hashicorp
+
+# 3. Check available versions
+helm search repo hashicorp/consul --versions
+
+# 4. Dry-run upgrade
+helm upgrade consul hashicorp/consul \
+  --namespace consul \
+  --values consul-values.yaml \
+  --version <NEW_VERSION> \
+  --dry-run
+
+# 5. Perform upgrade
+helm upgrade consul hashicorp/consul \
+  --namespace consul \
+  --values consul-values.yaml \
+  --version <NEW_VERSION>
+
+# 6. Watch rollout
+kubectl rollout status statefulset/consul-server -n consul --timeout=10m
+```
+
+### Zero-Downtime Upgrade Strategy
+
+```bash
+# Upgrade servers one at a time
+for i in 2 1 0; do
+  echo "Upgrading consul-server-$i..."
+  kubectl delete pod consul-server-$i -n consul
+  kubectl wait --for=condition=Ready pod/consul-server-$i -n consul --timeout=300s
+  sleep 30
+done
+
+# Verify leader election
+kubectl exec -n consul consul-server-0 -- consul operator raft list-peers
+```
+
+### Multi-Datacenter Upgrade Order
+
+1. **Upgrade secondary datacenters first**
+2. Verify federation health
+3. **Upgrade primary datacenter last**
+
+---
+
+## Post-Upgrade Validation
+
+### Immediate Checks
+
+```bash
+# Server health
+kubectl exec -n consul consul-server-0 -- consul members
+
+# Version verification
+kubectl exec -n consul consul-server-0 -- consul version
+
+# Raft status
+kubectl exec -n consul consul-server-0 -- consul operator raft list-peers
+
+# Connect CA
+kubectl exec -n consul consul-server-0 -- consul connect ca get-config
+```
+
+### Service Mesh Validation
+
+```bash
+# Check service registrations
+kubectl exec -n consul consul-server-0 -- consul catalog services
+
+# Verify sidecar injection still works
+kubectl rollout restart deployment/test-app -n test
+
+# Check intentions
+kubectl get serviceintentions -A
+```
+
+---
+
+## Rollback Procedures
+
+### Helm Rollback
+
+```bash
+# List revisions
+helm history consul -n consul
+
+# Rollback to previous
+helm rollback consul <REVISION> -n consul
+
+# Watch rollout
+kubectl rollout status statefulset/consul-server -n consul
+```
+
+### Snapshot Restore (Data Recovery)
+
+```bash
+# Copy backup to server
+kubectl cp ./consul-backup.snap consul/consul-server-0:/tmp/restore.snap
+
+# Restore snapshot
+kubectl exec -n consul consul-server-0 -- consul snapshot restore /tmp/restore.snap
+
+# Restart servers
+kubectl rollout restart statefulset/consul-server -n consul
+```
+
+---
+
+## Breaking Changes by Version
+
+### 1.17.x → 1.18.x
+
+- Consul Dataplane is now default (replaces client agents)
+- Update sidecar annotations if customized
+
+### 1.16.x → 1.17.x
+
+- ACL token migration completed
+- Legacy ACL tokens no longer supported
+
+### 1.15.x → 1.16.x
+
+- Catalog API v2 introduced (opt-in)
+- Some deprecated flags removed
+
+### General Guidance
+
+- Always check the official [upgrading documentation](https://developer.hashicorp.com/consul/docs/upgrading)
+- Test CRD changes in non-prod
+- Monitor Envoy proxy compatibility