ai-playbook 1.0.0

package/roles/devops/github-actions/README.md

@@ -0,0 +1,6 @@
+# GitHub Actions
+
+Use this folder for DevOps role guidance related to GitHub Actions.
+
+Add workflow patterns, permissions, caching, secrets, deployment gates, and
+debugging notes when this packet becomes active.

package/roles/devops/helm/README.md

@@ -0,0 +1,6 @@
+# Helm
+
+Use this folder for DevOps role guidance related to Helm.
+
+Add chart structure, values conventions, release workflows, testing, and rollback
+guidance when this packet becomes active.

package/roles/devops/infrastructure-as-code/README.md

@@ -0,0 +1,160 @@
+# Infrastructure as Code (IaC) Guidance
+
+This folder provides guidance for implementing infrastructure using code and automation tools.
+
+## Scope
+
+Use this guidance when:
+
+- Implementing infrastructure using Terraform, CloudFormation, or similar tools
+- Designing Helm charts for Kubernetes deployments
+- Creating reusable infrastructure modules
+- Managing infrastructure versioning and state
+- Automating infrastructure provisioning and deprovisioning
+- Implementing infrastructure testing and validation
+
+## Core Principles
+
+1. **Version Control** – Infrastructure code stored in git like application code
+2. **Modularity** – Infrastructure components broken into reusable modules
+3. **Documentation** – Clear comments explaining non-obvious decisions
+4. **Testing** – Infrastructure validated before deployment
+5. **Reproducibility** – Same code produces same infrastructure every time
+6. **Safety** – Plan before apply, maintain state securely
+
+## Tools
+
+### Terraform
+- **Language:** HCL (HashiCorp Configuration Language)
+- **State Management:** Local or remote state file
+- **Providers:** AWS, GCP, Azure, Kubernetes, and many others
+- **Modules:** Reusable infrastructure components
+- **Best for:** Multi-cloud, complex infrastructure
+
+### CloudFormation
+- **Language:** JSON or YAML
+- **AWS Native:** Integrated with AWS services
+- **Stack Management:** Templates deployed as stacks
+- **State:** AWS manages state
+- **Best for:** AWS-only infrastructure
+
+### Helm
+- **Language:** YAML templates with Helm functions
+- **Kubernetes Native:** Package manager for Kubernetes
+- **Charts:** Reusable Kubernetes application packages
+- **Values:** Configuration override mechanism
+- **Best for:** Kubernetes application deployments
+
+## Terraform Best Practices
+
+### Organization
+- Separate variables, main resources, and outputs
+- Use modules for reusability
+- One resource type per file (optional but recommended)
+- Clear, descriptive naming
+
+### State Management
+- Use remote state (S3, Terraform Cloud, Terraform Enterprise)
+- Enable state locking to prevent conflicts
+- Backup state regularly
+- Encrypt state file (especially for production)
+- Restrict access to state file
+
+### Variables & Outputs
+- Input variables with descriptions and types
+- Validation rules for correctness
+- Sensitive variables for passwords/keys
+- Clear output descriptions
+- Computed outputs for dependent resources
+
+### Modules
+- Reusable, self-contained infrastructure
+- Published to Terraform Registry
+- Version constraints specified
+- Module inputs documented
+- Module outputs used by consumers
+
+## CloudFormation Best Practices
+
+### Template Organization
+- Structured, readable YAML format
+- Logical grouping of resources
+- Clear resource naming
+- Parameter descriptions
+
+### Parameters
+- Type safety (String, Number, List)
+- Default values provided
+- Constraint validation
+- Clear descriptions
+
+### Outputs
+- Export values for cross-stack references
+- Clear descriptions
+- Consistent naming
+
+## Helm Chart Best Practices
+
+### Structure
+- Clear values.yaml with comments
+- Logical template organization
+- Helper templates for reuse
+- README documentation
+
+### Values
+- Sensible defaults
+- Configuration grouped logically
+- All configurable values exposed
+- Resource requests/limits included
+
+### Templates
+- Uses Helm functions and variables consistently
+- Labels consistent across resources
+- Comments explaining non-obvious logic
+
+## Testing & Validation
+
+### Terraform
+- `terraform validate` – Syntax checking
+- `terraform plan` – Show changes before apply
+- `terraform fmt` – Code formatting
+- `terraform test` – Testing framework (newer versions)
+- Terratest – Go testing framework for infrastructure
+
+### CloudFormation
+- cfn-lint – Template linting
+- AWS CloudFormation validate-template
+
+### Helm
+- `helm lint` – Chart validation
+- `helm template` – Render templates
+- `helm test` – Chart tests
+
+## Secrets Management
+
+- Never commit secrets to git
+- Use secure secret management (Vault, AWS Secrets Manager, Azure Key Vault)
+- Reference secrets in infrastructure code by name/ID
+- Rotate secrets regularly
+- Audit secret access
+
+## CI/CD Integration
+
+- Run validation on every commit
+- Plan infrastructure changes in PRs
+- Require approval before applying
+- Automatic rollback on failures
+- Track infrastructure changes in audit logs
+
+## Related Files
+
+- `roles/devops/examples.md` – Terraform module example
+- `roles/devops/checklists.md` – Infrastructure Code Review Checklist
+- `roles/devops/ci-cd/` – CI/CD pipeline guidance for infrastructure
+- `roles/devops/security/` – Security hardening for IaC
+
+## Files in This Folder
+
+- `README.md` – This file
+- `checklists.md` – IaC implementation checklist
+- `examples.md` – IaC code examples and patterns

package/roles/devops/infrastructure-as-code/checklists.md

@@ -0,0 +1,124 @@
+# Infrastructure as Code Checklists
+
+See parent `roles/devops/checklists.md` for Infrastructure Code Review Checklist covering:
+- Correctness
+- Security
+- Cost & optimization
+- Maintainability
+- Operability
+- Documentation
+- Testing
+
+---
+
+## Terraform Implementation Checklist
+
+### Project Setup
+- [ ] Terraform working directory structure created
+- [ ] `.gitignore` configured (terraform.tfvars, *.tfstate, etc.)
+- [ ] Provider configuration specified (AWS, GCP, Azure, etc.)
+- [ ] Remote state configured and locked
+
+### Code Organization
+- [ ] `main.tf` contains primary resources
+- [ ] `variables.tf` contains input variable definitions
+- [ ] `outputs.tf` contains output values
+- [ ] `terraform.tfvars` or separate tfvars files for values
+- [ ] Modules created for reusable components
+
+### Variables & Validation
+- [ ] All variables have descriptions
+- [ ] Type constraints specified
+- [ ] Default values provided (where appropriate)
+- [ ] Sensitive flag set for passwords/keys
+- [ ] Input validation configured
+
+### Outputs
+- [ ] Important values exposed as outputs
+- [ ] Output descriptions clear
+- [ ] Sensitive outputs marked if needed
+
+### State Management
+- [ ] Remote state configured (S3, Terraform Cloud, etc.)
+- [ ] State locking enabled
+- [ ] State file encryption enabled
+- [ ] State file access restricted
+- [ ] State backup configured
+
+### Security
+- [ ] No hardcoded secrets in code
+- [ ] Secrets retrieved from secure source
+- [ ] IAM policies follow least privilege
+- [ ] Encryption enabled for sensitive resources
+- [ ] Audit logging configured
+
+### Testing & Validation
+- [ ] `terraform validate` passes
+- [ ] `terraform plan` shows expected changes
+- [ ] Code `terraform fmt` formatting applied
+- [ ] Lint checks pass (tflint or similar)
+- [ ] Terratest or other tests pass
+
+### Documentation
+- [ ] README explains module purpose
+- [ ] Variables documented with examples
+- [ ] Outputs documented
+- [ ] Architecture diagram included
+- [ ] Usage examples provided
+
+---
+
+## Helm Chart Implementation Checklist
+
+### Chart Structure
+- [ ] Chart.yaml with correct metadata
+- [ ] values.yaml with sensible defaults
+- [ ] templates/ directory with manifests
+- [ ] .helmignore configured
+- [ ] README with usage instructions
+
+### Chart Metadata
+- [ ] Chart name and description accurate
+- [ ] Version follows semantic versioning
+- [ ] AppVersion specified
+- [ ] Keywords specified
+- [ ] Home, sources, maintainers specified
+
+### Values
+- [ ] All configurable values in values.yaml
+- [ ] Default values sensible and secure
+- [ ] Values well-commented
+- [ ] Nested structure logical
+- [ ] Resource requests/limits specified
+
+### Templates
+- [ ] All values use template variables
+- [ ] Labels consistent across resources
+- [ ] Naming follows convention
+- [ ] Helper templates created for reuse
+- [ ] Non-obvious logic commented
+
+### Testing
+- [ ] `helm lint` passes
+- [ ] `helm template` produces valid YAML
+- [ ] Dry-run deployment successful
+- [ ] Actual deployment tested
+- [ ] Upgrade tested
+
+### Documentation
+- [ ] README explains chart purpose
+- [ ] CHANGELOG documents versions
+- [ ] Values documented in comments
+- [ ] Example values files provided
+- [ ] Troubleshooting guide included
+
+---
+
+## Secrets Management Checklist
+
+- [ ] No secrets committed to git
+- [ ] Secrets managed externally (Vault, Secrets Manager, etc.)
+- [ ] Secret retrieval configured in code
+- [ ] Secret rotation policy defined
+- [ ] Secret access audited and logged
+- [ ] Secret encryption enabled

package/roles/devops/jenkins/README.md

@@ -0,0 +1,6 @@
+# Jenkins
+
+Use this folder for DevOps role guidance related to Jenkins.
+
+Add pipeline patterns, credentials guidance, agent setup, approval gates, and
+troubleshooting notes when this packet becomes active.

package/roles/devops/kubernetes/README.md

@@ -0,0 +1,150 @@
+# Kubernetes Guidance
+
+This folder provides guidance for designing, deploying, and operating applications on Kubernetes.
+
+## Scope
+
+Use this guidance when:
+
+- Designing Kubernetes deployments and workloads
+- Configuring container orchestration strategies
+- Implementing Kubernetes networking (services, ingress, network policies)
+- Setting up Kubernetes storage (persistent volumes, storage classes)
+- Configuring security (RBAC, pod security policies, secrets)
+- Scaling applications (horizontal pod autoscaling, vertical pod autoscaling)
+- Implementing Kubernetes monitoring and logging
+- Troubleshooting Kubernetes issues
+
+## Core Principles
+
+1. **Declarative Configuration** – Define desired state in YAML manifests
+2. **Immutable Infrastructure** – Containers are disposable, redeploy rather than patch
+3. **Automated Recovery** – Kubernetes automatically replaces failed pods
+4. **Resource Limits** – Specify CPU/memory requests and limits
+5. **Health Checks** – Use liveness and readiness probes
+6. **Observability** – Expose metrics, logs, and traces
+
+## Kubernetes Cluster Setup
+
+### Cluster Architecture
+- Single control plane or high-availability (3+ control planes)
+- Number of worker nodes based on workload requirements
+- CNI (Container Network Interface) plugin for networking
+- Storage solution for persistent data
+- Ingress controller for external access
+
+### Cluster Management
+- Regular Kubernetes version upgrades
+- Node pool management and scaling
+- Resource quotas and namespace isolation
+- RBAC (Role-Based Access Control) configuration
+- Network policies for traffic control
+
+### Deployment Platforms
+- **EKS (AWS Elastic Kubernetes Service)** – Managed Kubernetes on AWS
+- **GKE (Google Kubernetes Engine)** – Managed Kubernetes on Google Cloud
+- **AKS (Azure Kubernetes Service)** – Managed Kubernetes on Azure
+- **Self-Managed** – Install and manage Kubernetes yourself
+
+## Workload Deployment
+
+### Deployment Strategies
+- **Rolling Updates** – Gradually replace old replicas with new ones
+- **Recreate** – Stop all pods and start new ones (downtime)
+- **Blue-Green** – Switch between two complete versions
+- **Canary** – Route small percentage of traffic to new version
+
+### Pod Configuration
+- Set resource requests (CPU, memory) based on typical usage
+- Set resource limits to prevent resource hogging
+- Configure liveness and readiness probes
+- Set appropriate restart policies
+- Use security contexts (non-root user, read-only filesystem)
+
+### Scaling
+- **Horizontal Pod Autoscaling (HPA)** – Scale pods based on metrics (CPU, custom)
+- **Vertical Pod Autoscaling (VPA)** – Adjust pod resource requests based on usage
+- **Cluster Autoscaling** – Add/remove nodes based on pod requirements
+- **Manual Scaling** – Adjust replica count manually
+
+## Networking
+
+### Services
+- **ClusterIP** – Expose within cluster only
+- **NodePort** – Expose on specific port on each node
+- **LoadBalancer** – Expose via cloud provider load balancer
+- **ExternalName** – Map to external DNS name
+
+### Ingress
+- Use Ingress controller (NGINX, Istio, etc.)
+- Configure routing rules for external access
+- TLS/SSL termination at ingress
+- Multiple domains on single ingress
+
+### Network Policies
+- Restrict traffic between pods
+- Default deny all incoming traffic, allow specific connections
+- Egress policies for outbound traffic control
+
+## Storage
+
+### Persistent Volumes
+- Choose appropriate storage class (fast, standard, archive)
+- Use persistent volume claims for applications
+- Define backup and snapshot procedures
+- Configure retention policies
+
+### StatefulSets
+- For applications requiring persistent storage
+- Maintain stable pod identities
+- Ordered startup/shutdown
+
+## Security
+
+### RBAC (Role-Based Access Control)
+- Create roles for specific responsibilities
+- Bind roles to users/groups/service accounts
+- Follow principle of least privilege
+
+### Pod Security
+- Use pod security policies or pod security standards
+- Run as non-root user
+- Use read-only root filesystem
+- Drop unnecessary Linux capabilities
+
+### Secrets
+- Never hardcode secrets in manifests
+- Use Kubernetes secrets for sensitive data
+- Consider external secret management (Vault, AWS Secrets Manager)
+
+## Monitoring & Logging
+
+### Metrics
+- Kubernetes API server metrics
+- kubelet metrics for node health
+- Container runtime metrics
+- Application metrics (instrumented in code)
+
+### Logging
+- Container logs accessible via `kubectl logs`
+- Centralized logging solution (ELK, Splunk, Cloud Logging)
+- Structure logs for easier searching and analysis
+
+## Best Practices
+
+- [ ] Namespace isolation for multi-tenant deployments
+- [ ] Resource quotas per namespace
+- [ ] Network policies restrict traffic
+- [ ] Pod disruption budgets for voluntary disruptions
+- [ ] Health checks (liveness, readiness) configured
+- [ ] Resource requests/limits specified
+- [ ] Security context enforces non-root
+- [ ] Monitoring and alerting configured
+- [ ] Backup and disaster recovery tested
+- [ ] Documentation and runbooks maintained
+
+## Files in This Folder
+
+- `README.md` – This file
+- `checklists.md` – Kubernetes implementation checklist
+- `examples.md` – Kubernetes deployment examples

package/roles/devops/kubernetes/checklists.md

@@ -0,0 +1,192 @@
+# Kubernetes Checklists
+
+Kubernetes-specific implementation checklists. See parent `roles/devops/checklists.md` for the full Kubernetes Deployment Checklist.
+
+---
+
+## Kubernetes Cluster Setup Checklist
+
+### Prerequisites
+- [ ] Kubernetes version chosen and supported
+- [ ] Cluster platform selected (EKS, GKE, AKS, self-managed)
+- [ ] High availability requirements defined (1 or 3+ control planes)
+- [ ] CNI plugin selected and planned
+- [ ] Storage solution selected (EBS, GCP persistent disks, etc.)
+
+### Control Plane
+- [ ] Control plane nodes provisioned with appropriate resources
+- [ ] etcd backup strategy defined and automated
+- [ ] API server authenticated and authorized
+- [ ] Audit logging enabled
+
+### Worker Nodes
+- [ ] Worker nodes provisioned with correct sizing
+- [ ] Node labels and taints configured
+- [ ] Container runtime configured (Docker, containerd, etc.)
+- [ ] kubelet configured and monitoring
+
+### Networking
+- [ ] CNI plugin installed and working
+- [ ] Pod network CIDR configured
+- [ ] Service network CIDR configured
+- [ ] Cluster DNS working
+- [ ] Ingress controller installed
+
+### RBAC
+- [ ] Service accounts created for applications
+- [ ] Roles defined for required permissions
+- [ ] RoleBindings created
+- [ ] Cluster admin access restricted
+
+### Storage
+- [ ] Storage classes defined
+- [ ] Persistent volume provisioning working
+- [ ] Backup solution configured
+
+### Monitoring
+- [ ] Prometheus/metrics server installed
+- [ ] Monitoring dashboards created
+- [ ] Alerting rules configured
+- [ ] Logging solution configured
+
+---
+
+## Workload Deployment Checklist
+
+See parent `roles/devops/checklists.md` for detailed Kubernetes Deployment Checklist covering:
+- Container images
+- Deployment manifests
+- Resource limits
+- Health checks
+- Auto-scaling
+- Networking
+- Storage
+- Secrets
+- Monitoring
+- Security
+
+---
+
+## Helm Chart Development Checklist
+
+### Chart Structure
+- [ ] Chart.yaml with correct metadata
+- [ ] values.yaml with sensible defaults
+- [ ] templates/ directory with YAML manifests
+- [ ] README.md with usage instructions
+- [ ] LICENSE file
+
+### Templates
+- [ ] All configurable values use Helm variables
+- [ ] Labels consistent across resources
+- [ ] Naming follows convention (release-name-service)
+- [ ] Helper templates created for reuse
+
+### Values
+- [ ] Default values specified for all settings
+- [ ] Values documented with comments
+- [ ] Nested structure logical and easy to override
+- [ ] Resource requests/limits specified
+
+### Testing
+- [ ] `helm lint` passes
+- [ ] `helm template` produces valid YAML
+- [ ] Dry-run deploy (`helm install --dry-run`) works
+- [ ] Actual deployment tested and working
+- [ ] Upgrade from previous chart version tested
+
+### Documentation
+- [ ] README explains chart purpose
+- [ ] CHANGELOG documents versions
+- [ ] Values documented in values.yaml
+- [ ] Example values files provided
+
+---
+
+## Kubernetes Upgrade Checklist
+
+### Planning
+- [ ] Current version documented
+- [ ] Target version identified and supported
+- [ ] Release notes reviewed for breaking changes
+- [ ] Upgrade path verified
+
+### Pre-Upgrade
+- [ ] Cluster backup created
+- [ ] Workload backups created
+- [ ] Monitoring verified working
+- [ ] Communication sent to stakeholders
+
+### Upgrade
+- [ ] Control plane upgraded first
+- [ ] Node upgrades coordinated with PDBs
+- [ ] Each component upgrade verified
+- [ ] API deprecations handled
+
+### Validation
+- [ ] All nodes healthy
+- [ ] All pods running
+- [ ] Applications functioning
+- [ ] Monitoring data flowing
+- [ ] Previous version no longer supported by us
+
+### Post-Upgrade
+- [ ] Documentation updated
+- [ ] Team trained on new features
+- [ ] Old manifests updated for deprecations
+
+---
+
+## Kubernetes Security Checklist
+
+### Access Control
+- [ ] RBAC roles follow least privilege
+- [ ] Service accounts have minimal permissions
+- [ ] Service account token auto-mounting disabled where unnecessary
+- [ ] User/group access reviewed quarterly
+
+### Pod Security
+- [ ] Pod security policies or standards enforced
+- [ ] Containers run as non-root
+- [ ] Read-only root filesystem enforced
+- [ ] Unnecessary capabilities dropped
+- [ ] Privileged containers justified and minimal
+
+### Network Security
+- [ ] Network policies restrict pod traffic
+- [ ] Ingress traffic authenticated/authorized
+- [ ] Egress filtered to necessary endpoints only
+- [ ] East-west traffic encrypted (mTLS, service mesh)
+
+### Secrets
+- [ ] Secrets never stored in ConfigMaps
+- [ ] Secrets encrypted at rest
+- [ ] Secret access logged and audited
+- [ ] External secret manager considered (Vault)
+
+### Image Security
+- [ ] Container images scanned for vulnerabilities
+- [ ] Only signed images used
+- [ ] Image pull secrets configured
+- [ ] Registry access controlled
+
+### Compliance
+- [ ] Audit logging enabled
+- [ ] PCI-DSS, HIPAA, SOC2 controls implemented
+- [ ] Compliance scanning automated
+
+---
+
+## Kubernetes Troubleshooting Checklist
+
+When debugging pod issues:
+
+- [ ] `kubectl describe pod` – Shows events and status
+- [ ] `kubectl logs` – Check container logs
+- [ ] `kubectl exec` – Execute command in pod
+- [ ] `kubectl top` – Check resource usage
+- [ ] Check events: `kubectl get events`
+- [ ] Check node status: `kubectl get nodes`
+- [ ] Check resource quotas: `kubectl describe quota`
+- [ ] Check PVC status: `kubectl get pvc`
+- [ ] Check networking: `kubectl get svc`