diff --git a/bin/genesis b/bin/genesis index c611bda6..f716cc4b 100755 --- a/bin/genesis +++ b/bin/genesis @@ -34,7 +34,6 @@ $Genesis::VERSION = "(development)"; $Genesis::BUILD = ""; # Command will be determined later in main() -$ENV{GENESIS_COMMAND} = ''; Genesis::Init(); @@ -45,37 +44,18 @@ define_command('help', { usage => "help []", function_group => Genesis::Commands::GENESIS, options => [ - 'all|A' => 'Show all commands, not just the common categories', + 'all|A' => + 'Show all , not just the common categories', + 'list-topics|l' => + 'List all available help topics', + 'topic|t=s' => + 'Show help for a specific topic (eg: genesis help topic)', + 'command|c=s' => + 'Show help for a specific command (eg: genesis help command) - usually '. + 'equavalent to genesis command -h', ], skip_check_prereqs => 1, no_vault => 1 -}, sub { - # First check if we just want to see global options alone - if (!@_ && get_options->{globals}) { - # Show only global options - Genesis::Commands::show_global_options(); - return; - } - - if (@_) { - # Show help for specific command - my $cmd = shift; - - # Check if command exists - if (exists $Genesis::Commands::GENESIS_COMMANDS{$cmd}) { - # Prepare command context for usage display - $Genesis::Commands::CALLED = $cmd; - $Genesis::Commands::COMMAND = $Genesis::Commands::GENESIS_COMMANDS{$cmd}; - # Show globals if --globals, --help-full, or --helpful flag is present - my $show_global = (get_options->{globals} || get_options->{'help-full'} || get_options->{helpful}) ? 1 : 0; - command_usage(0, undef, $show_global); - } else { - command_help("Unknown command: #G{$cmd}", 2); - } - } else { - # Show general help listing - command_help(); - } }); # }}} @@ -2016,7 +1996,7 @@ sub main { } } elsif ($arg =~ /^@/) { bail( - "Must use @-notation before the Genesis subcommand." + 'Must use @-notation before the Genesis subcommand.' ); } else { if (has_command($arg) || $arg eq 'help') { @@ -2069,7 +2049,6 @@ sub main { trace("arguments are [".join(', ', @args)."]"); if (has_command $cmd) { # Set the command for logging purposes - $ENV{GENESIS_COMMAND} = $cmd; prepare_command $cmd, @args; set_top_path; check_embedded_genesis; diff --git a/docs/topics/.keep b/docs/topics/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/00-getting-started/.keep b/docs/topics/00-getting-started/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/00-getting-started/concepts.md b/docs/topics/00-getting-started/concepts.md new file mode 100644 index 00000000..b5cb58c2 --- /dev/null +++ b/docs/topics/00-getting-started/concepts.md @@ -0,0 +1,212 @@ +# Core Genesis Concepts + +Understanding these fundamental concepts will help you use Genesis effectively. + +## Kits + +A **kit** is a pre-packaged template for deploying a specific type of software with BOSH. Kits encapsulate: + +- **Manifest Templates** - YAML templates that generate BOSH manifests +- **Default Configuration** - Sensible defaults and best practices +- **Features** - Optional components you can enable/disable +- **Secrets Definitions** - What credentials and certificates to generate +- **Lifecycle Hooks** - Scripts that run during deployment phases + +### Example Kits +- `bosh-genesis-kit` - Deploy BOSH directors +- `cf-genesis-kit` - Deploy Cloud Foundry +- `vault-genesis-kit` - Deploy Vault clusters +- `concourse-genesis-kit` - Deploy Concourse CI + +## Repositories + +A **repository** is a Git repository containing related Genesis deployments. Repositories provide: + +- Version control for your infrastructure +- Shared configuration across environments +- Audit trail of changes +- Collaboration through pull requests + +### Repository Structure +``` +my-deployments/ +├── .genesis/ +│ ├── bin/ # Repository-specific scripts +│ ├── cache/ # Downloaded kit cache +│ └── kits/ # Local kit overrides +├── us-east-1.yml # Region configuration +├── us-east-1-prod.yml # Environment file +└── us-east-1-dev.yml # Environment file +``` + +## Environments + +An **environment** represents a single deployment. Each environment: + +- Has its own YAML configuration file +- Inherits from parent configurations +- Generates a unique BOSH manifest +- Maintains its own secrets in Vault + +### Environment Files +```yaml +--- +kit: + name: bosh + version: 2.2.0 + features: + - aws + - proto + +params: + env: us-east-1-prod + aws_region: us-east-1 +``` + +## Hierarchical Configuration + +Genesis uses **hierarchical configuration** to avoid repetition: + +1. **Global** - Repository-wide defaults +2. **Regional** - Infrastructure-specific settings +3. **Environmental** - Deployment-specific overrides + +### Example Hierarchy +``` +site.yml # Global settings for all environments +└── us.yml # US-specific settings + └── us-east.yml # us-east region settings + └── us-east-1.yml # Specific environment + └── us-east-1-prod.yml # Most specific +``` + +### Configuration Merging +```yaml +# site.yml +params: + vault: https://vault.example.com:8200 + +# us.yml +params: + domain: us.example.com + +# us-east-1-prod.yml +params: + env: prod + # Inherits vault and domain from parents +``` + +## Features + +**Features** are optional kit components you can enable: + +```yaml +kit: + features: + - vsphere # vSphere infrastructure + - syslog # Syslog forwarding + - prometheus # Metrics exporter +``` + +Features can: +- Add manifest snippets +- Require additional parameters +- Generate specific secrets +- Run validation checks + +## Secrets Management + +Genesis integrates with **Vault** (or CredHub) for secrets: + +### Automatic Generation +- Passwords and credentials +- SSH keys +- X.509 certificates +- RSA key pairs + +### Secret Paths +Secrets follow a predictable path structure: +``` +secret/us-east-1/prod/bosh/ +├── admin_password +├── ca +├── director_tls +└── db_password +``` + +### Secret Rotation +```bash +# Rotate specific secrets +genesis rotate-secrets my-env admin_password + +# Rotate all secrets +genesis rotate-secrets my-env --all +``` + +## Lifecycle Hooks + +**Hooks** are scripts that run at specific times: + +- **new** - When creating a new environment +- **blueprint** - When generating the manifest +- **check** - Pre-deployment validation +- **pre-deploy** - Before deployment +- **post-deploy** - After deployment +- **addon** - Custom operator scripts + +## Deployment Workflow + +The typical Genesis workflow: + +1. **Initialize** - Create a repository with a kit +2. **Configure** - Create environment files +3. **Generate Secrets** - Auto-generate credentials +4. **Deploy** - Push to BOSH +5. **Manage** - Update, rotate secrets, scale + +### Example Workflow +```bash +# Initialize repository +genesis init --kit vault my-vault-deployments +cd my-vault-deployments + +# Create environment +genesis new us-east-prod + +# Edit configuration +vim us-east-prod.yml + +# Check and deploy +genesis check us-east-prod +genesis deploy us-east-prod +``` + +## Manifest Generation + +Genesis generates BOSH manifests by: + +1. Loading the kit's base manifest +2. Applying features +3. Merging environment parameters +4. Injecting secrets from Vault +5. Running blueprint hooks + +You can view the generated manifest: +```bash +genesis manifest my-env +``` + +## Best Practices + +1. **Use Version Control** - Commit all environment files +2. **Hierarchical Config** - Share common settings +3. **Feature Flags** - Use features instead of manual overrides +4. **Secret Rotation** - Regularly rotate credentials +5. **Environment Naming** - Use consistent naming patterns + +## Next Steps + +Now that you understand the concepts: +- [Configure Genesis](configuration.md) for your needs +- Create your [First Deployment](first-deployment.md) +- Learn about [Environment Management](../10-environments/index.md) \ No newline at end of file diff --git a/docs/topics/00-getting-started/configuration.md b/docs/topics/00-getting-started/configuration.md new file mode 100644 index 00000000..60a90b75 --- /dev/null +++ b/docs/topics/00-getting-started/configuration.md @@ -0,0 +1,202 @@ +# Basic Genesis Configuration + +This guide covers essential Genesis configuration for new users. For a complete configuration reference, see the [Configuration Reference Guide](../90-reference-guides/configuration.md). + +## Configuration File + +Genesis stores its configuration in `~/.genesis/config` (YAML format). + +```bash +# Create the configuration directory +mkdir -p ~/.genesis + +# Create a basic configuration file +vim ~/.genesis/config +``` + +## Essential Settings + +### BOSH Target Behavior + +When deploying, Genesis needs to know which BOSH director to use. Configure the default behavior: + +```yaml +--- +# How to select BOSH directors when multiple options exist +default_bosh_target: ask # ask, parent, or self +``` + +Options: +- **ask** - Prompt to select a director (recommended for beginners) +- **parent** - Use the director that deployed this environment +- **self** - Use this environment as the director (for BOSH directors) + +### Deployment Roots + +Organize your Genesis repositories in standard locations: + +```yaml +deployment_roots: + - ~/deployments # Personal deployments + - work: ~/work/deploy # Work deployments (with label) +``` + +This helps Genesis: +- Find repositories with `genesis switch` +- Organize the `genesis list` output +- Provide better command completion + +## Common Configurations + +### For Development Environments + +```yaml +--- +default_bosh_target: ask + +deployment_roots: + - ~/dev/genesis + +# Suppress warnings about embedded Genesis +embedded_genesis: ignore + +# Automatically upgrade configs without prompting +automatic_config_upgrade: yes +``` + +### For Production Environments + +```yaml +--- +default_bosh_target: parent + +deployment_roots: + - prod: /opt/genesis/production + - staging: /opt/genesis/staging + +# Check for embedded Genesis issues +embedded_genesis: warn + +# Never auto-upgrade configs +automatic_config_upgrade: no +``` + +### For CI/CD Systems + +```yaml +--- +default_bosh_target: parent + +# Silent config upgrades for automation +automatic_config_upgrade: silent + +# Use environment variables for dynamic config +# Set GENESIS_BOSH_ENVIRONMENT, GENESIS_VAULT_PREFIX, etc. +``` + +## Environment Variables + +Genesis configuration can also be set via environment variables: + +```bash +# Override config file settings +export GENESIS_DEFAULT_BOSH_TARGET=parent +export GENESIS_LEGACY_REPO_SUFFIX=false + +# Set deployment roots +export GENESIS_DEPLOYMENT_ROOTS="$HOME/deployments;work=$HOME/work/deploy" + +# Configure default behaviors +export GENESIS_CONFIG_AUTOMATIC_UPGRADE=yes +``` + +### Precedence + +Environment variables take precedence over config file settings. + +## Vault Configuration + +While Vault settings are typically per-environment, you can set defaults: + +```bash +# Default Vault server +export GENESIS_VAULT_SERVER=https://vault.example.com:8200 + +# Skip TLS verification (development only!) +export VAULT_SKIP_VERIFY=1 +``` + +## Shell Completion + +Enable command completion for better usability: + +### Bash +```bash +echo 'source <(genesis completion bash)' >> ~/.bashrc +``` + +### Zsh +```bash +echo 'source <(genesis completion zsh)' >> ~/.zshrc +``` + +## Verifying Configuration + +Check your configuration: + +```bash +# Show effective configuration +genesis config + +# Test BOSH connectivity +genesis ping + +# List known deployments +genesis list +``` + +## Common Issues + +### Permission Denied + +If Genesis can't write to `~/.genesis/config`: +```bash +# Fix permissions +chmod 755 ~/.genesis +chmod 644 ~/.genesis/config +``` + +### Config Not Loading + +Genesis looks for config in this order: +1. `$GENESIS_CONFIG_FILE` (if set) +2. `~/.genesis/config` +3. Built-in defaults + +### Environment Variable Syntax + +For arrays in environment variables, use `:` as separator: +```bash +# Multiple deployment roots +export GENESIS_DEPLOYMENT_ROOTS="/opt/genesis:$HOME/deployments" + +# With labels, use = and ; +export GENESIS_DEPLOYMENT_ROOTS="prod=/opt/prod;dev=/opt/dev" +``` + +## Advanced Configuration + +For more configuration options including: +- Pipeline automation settings +- Advanced BOSH configurations +- Custom hook behaviors +- Experimental features + +See the [Complete Configuration Reference](../90-reference-guides/configuration.md). + +## Next Steps + +With Genesis configured: +- Create your [First Deployment](first-deployment.md) +- Learn about [Environment Management](../10-environments/index.md) +- Explore [Kit Selection](../50-kits/using-kits.md) \ No newline at end of file diff --git a/docs/topics/00-getting-started/first-deployment.md b/docs/topics/00-getting-started/first-deployment.md new file mode 100644 index 00000000..96da4687 --- /dev/null +++ b/docs/topics/00-getting-started/first-deployment.md @@ -0,0 +1,252 @@ +# Your First Genesis Deployment + +This guide walks you through deploying your first environment with Genesis. We'll deploy a BOSH director, which is the foundation for all other deployments. + +## Prerequisites + +Before starting, ensure you have: +- [Genesis installed](installation.md) with all dependencies +- [Basic configuration](configuration.md) in place +- Access to a supported IaaS (AWS, Azure, GCP, vSphere, or OpenStack) +- IaaS credentials ready + +## Step 1: Initialize a Repository + +Create a new Genesis repository for BOSH deployments: + +```bash +# Create and enter the repository +genesis init --kit bosh my-bosh-deployments +cd my-bosh-deployments +``` + +This creates: +- A Git repository for version control +- `.genesis/` directory for Genesis metadata +- Initial kit configuration + +## Step 2: Select Your Infrastructure + +Genesis needs to know what infrastructure you're using: + +```bash +# List available features for the BOSH kit +genesis info bosh +``` + +Common infrastructure features: +- `aws` - Amazon Web Services +- `azure` - Microsoft Azure +- `google` - Google Cloud Platform +- `vsphere` - VMware vSphere +- `openstack` - OpenStack + +## Step 3: Create an Environment + +Create your first environment file: + +```bash +# Create a new environment (interactive wizard) +genesis new my-lab +``` + +The wizard will ask for: +1. **Infrastructure type** - Select your IaaS +2. **Environment name** - A descriptive name +3. **Vault prefix** - Where to store secrets +4. **Network configuration** - Subnet ranges +5. **IaaS-specific details** - Credentials, regions, etc. + +## Step 4: Review Configuration + +Examine the generated environment file: + +```bash +# View the environment configuration +cat my-lab.yml +``` + +Example AWS configuration: +```yaml +--- +kit: + name: bosh + version: 2.2.0 + features: + - aws + - proto + +params: + env: my-lab + bosh_vm_type: t3.small + + # AWS Configuration + aws_region: us-east-1 + aws_default_sgs: + - bosh + + # Networking + subnet_addr: 10.128.0.0/24 + default_gateway: 10.128.0.1 + dns: + - 8.8.8.8 + - 8.8.4.4 +``` + +## Step 5: Configure Vault + +Genesis uses Vault to store secrets. If you don't have Vault running: + +```bash +# Start a development Vault (for testing only!) +safe init +safe verify +``` + +For production, use a properly configured Vault cluster. + +## Step 6: Generate Cloud Config + +For AWS, Azure, or GCP, generate the required cloud config: + +```bash +# Generate IaaS configuration +genesis do my-lab -- cloud-config +``` + +This creates the necessary IaaS resources: +- Networks and subnets +- Security groups +- SSH keys +- Other IaaS-specific resources + +## Step 7: Deploy + +Now deploy your BOSH director: + +```bash +# Verify everything looks correct +genesis check my-lab + +# Deploy (this takes 15-30 minutes) +genesis deploy my-lab +``` + +Genesis will: +1. Generate required secrets in Vault +2. Create the BOSH manifest +3. Deploy the BOSH director +4. Configure local BOSH CLI access + +## Step 8: Verify Deployment + +Once deployed, verify your BOSH director: + +```bash +# Target the new BOSH director +genesis do my-lab -- login + +# Check BOSH status +bosh env + +# View deployments (should be empty) +bosh deployments +``` + +## Common Issues + +### Deployment Fails + +If deployment fails: +```bash +# Check the deployment log +genesis deploy my-lab -l debug + +# View BOSH task output +bosh task --debug +``` + +### Network Issues + +Ensure: +- Subnet ranges don't overlap +- Security groups allow required ports +- DNS servers are reachable + +### Credential Problems + +For IaaS credential issues: +```bash +# Re-run the new wizard +genesis new my-lab --force + +# Or edit directly +vim my-lab.yml +``` + +## Next Steps + +Congratulations! You've deployed your first Genesis environment. Now you can: + +### Deploy Additional Software + +```bash +# Initialize a Vault deployment repository +cd .. +genesis init --kit vault my-vault-deployments +cd my-vault-deployments + +# Create Vault environment targeting your BOSH +genesis new my-vault +``` + +### Learn More + +- [Environment Management](../10-environments/index.md) - Managing multiple environments +- [Secrets Management](../30-secrets-management/index.md) - Working with Vault +- [Using Kits](../50-kits/index.md) - Deploying other software + +### Useful Commands + +```bash +# List all Genesis environments +genesis list + +# Show environment details +genesis describe my-lab + +# Rotate credentials +genesis rotate-secrets my-lab + +# SSH to BOSH director +genesis do my-lab -- ssh + +# View generated manifest +genesis manifest my-lab +``` + +## Clean Up + +To destroy the environment when done testing: + +```bash +# Delete the deployment +genesis do my-lab -- destroy + +# Remove environment file +rm my-lab.yml +git add -A +git commit -m "Removed lab environment" +``` + +## Production Considerations + +For production deployments: + +1. **Use proper Vault** - Not the dev server +2. **Configure backups** - Use Shield or BBR +3. **Enable monitoring** - Prometheus exporters +4. **Set up CI/CD** - Concourse pipelines +5. **Document everything** - Including credentials and procedures + +See the [BOSH kit documentation](../50-kits/bosh.md) for production configuration details. \ No newline at end of file diff --git a/docs/topics/00-getting-started/index.md b/docs/topics/00-getting-started/index.md new file mode 100644 index 00000000..14126df7 --- /dev/null +++ b/docs/topics/00-getting-started/index.md @@ -0,0 +1,74 @@ +# Getting Started with Genesis + +Welcome to Genesis! This guide will help you understand Genesis concepts and get your first deployment running. + +## Topics in This Section + +1. **[Introduction](introduction.md)** - What is Genesis and why use it? +2. **[Installation](installation.md)** - Installing Genesis and required dependencies +3. **[Concepts](concepts.md)** - Core Genesis concepts and terminology +4. **[Configuration](configuration.md)** - Basic Genesis configuration +5. **[First Deployment](first-deployment.md)** - Deploy your first environment +6. **[Next Steps](next-steps.md)** - Where to go from here + +## Quick Start + +If you're in a hurry, here's the minimum you need to get started: + +### Install Genesis + +```bash +# Download and install the latest Genesis +curl -sL https://github.com/genesis-community/genesis/releases/latest/download/genesis -o genesis +chmod +x genesis +sudo mv genesis /usr/local/bin/ + +# Verify installation +genesis version +``` + +### Install Dependencies + +Genesis requires several tools to function: + +```bash +# Required tools +# - safe (Vault CLI) +# - spruce (YAML processor) +# - bosh (BOSH CLI v2) +# - jq (JSON processor) + +# On macOS with Homebrew: +brew install starkandwayne/cf/safe +brew install starkandwayne/cf/spruce +brew install cloudfoundry/tap/bosh-cli +brew install jq + +# On Linux, follow individual tool installation guides +``` + +### Initialize Your First Repository + +```bash +# Create a new Genesis repository for BOSH deployments +genesis init --kit bosh my-bosh-deployments +cd my-bosh-deployments + +# Create your first environment +genesis new my-lab +``` + +### Next Steps + +Continue with the detailed guides in this section to: +- Understand Genesis architecture and concepts +- Configure Genesis for your environment +- Deploy and manage your first BOSH director +- Learn about environment hierarchies and configuration management + +## Getting Help + +- Run `genesis help` for command reference +- Visit specific help topics with `genesis help ` +- Check the [troubleshooting guide](../70-troubleshooting/index.md) for common issues +- Join the Genesis community Slack for support \ No newline at end of file diff --git a/docs/topics/00-getting-started/installation.md b/docs/topics/00-getting-started/installation.md new file mode 100644 index 00000000..4fedf0a5 --- /dev/null +++ b/docs/topics/00-getting-started/installation.md @@ -0,0 +1,223 @@ +# Installing Genesis + +This guide covers installing Genesis and its required dependencies. + +## System Requirements + +Genesis runs on: +- macOS (Intel and Apple Silicon) +- Linux (x86_64) +- Windows (via WSL2) + +## Installing Genesis + +### Quick Install (Recommended) + +Download the latest release directly from GitHub: + +```bash +# Download the latest Genesis binary +curl -sL https://github.com/genesis-community/genesis/releases/latest/download/genesis -o genesis + +# Make it executable +chmod +x genesis + +# Move to your PATH (may require sudo) +sudo mv genesis /usr/local/bin/ + +# Verify installation +genesis version +``` + +### Alternative Installation Methods + +#### Using Homebrew (macOS) + +```bash +brew tap genesis-community/genesis +brew install genesis +``` + +#### Manual Download + +1. Visit the [Genesis releases page](https://github.com/genesis-community/genesis/releases) +2. Download the appropriate binary for your platform +3. Make it executable and place it in your PATH + +## Required Dependencies + +Genesis requires several tools to function properly. Install all of these before using Genesis: + +### 1. Safe (Vault CLI) + +Safe is used for secrets management with Vault. + +```bash +# macOS +brew install starkandwayne/cf/safe + +# Linux (64-bit) +curl -sL https://github.com/starkandwayne/safe/releases/latest/download/safe-linux-amd64 -o safe +chmod +x safe +sudo mv safe /usr/local/bin/ +``` + +### 2. Spruce + +Spruce is used for YAML manipulation and merging. + +```bash +# macOS +brew install starkandwayne/cf/spruce + +# Linux +curl -sL https://github.com/geofffranks/spruce/releases/latest/download/spruce-linux-amd64 -o spruce +chmod +x spruce +sudo mv spruce /usr/local/bin/ +``` + +### 3. BOSH CLI v2 + +The BOSH CLI is used for deploying to BOSH directors. + +```bash +# macOS +brew install cloudfoundry/tap/bosh-cli + +# Linux +curl -sL https://github.com/cloudfoundry/bosh-cli/releases/latest/download/bosh-cli-*-linux-amd64 -o bosh +chmod +x bosh +sudo mv bosh /usr/local/bin/ +``` + +### 4. jq + +jq is used for JSON processing. + +```bash +# macOS +brew install jq + +# Linux (Ubuntu/Debian) +sudo apt-get update && sudo apt-get install -y jq + +# Linux (RedHat/CentOS) +sudo yum install -y jq +``` + +### 5. Git + +Git is used for version control of your deployment repositories. + +```bash +# macOS (usually pre-installed) +git --version + +# Linux (Ubuntu/Debian) +sudo apt-get update && sudo apt-get install -y git + +# Linux (RedHat/CentOS) +sudo yum install -y git +``` + +## Optional Dependencies + +These tools enhance Genesis functionality but aren't strictly required: + +### CredHub CLI + +For deployments using CredHub instead of Vault: + +```bash +# macOS +brew install cloudfoundry/tap/credhub-cli + +# Linux +curl -sL https://github.com/cloudfoundry-incubator/credhub-cli/releases/latest/download/credhub-linux-*.tgz -o credhub.tgz +tar -xzf credhub.tgz +sudo mv credhub /usr/local/bin/ +``` + +### Vault + +For running a local Vault server: + +```bash +# macOS +brew install vault + +# Linux +curl -sL https://releases.hashicorp.com/vault/*/vault_*_linux_amd64.zip -o vault.zip +unzip vault.zip +sudo mv vault /usr/local/bin/ +``` + +## Verify Installation + +After installing Genesis and its dependencies, verify everything is working: + +```bash +# Check Genesis +genesis version + +# Check dependencies +safe version +spruce --version +bosh --version +jq --version +git --version + +# Optional: Check if all dependencies are found +genesis ping +``` + +## Initial Configuration + +Genesis stores its configuration in `~/.genesis/config`. Create this file with basic settings: + +```bash +# Create Genesis configuration directory +mkdir -p ~/.genesis + +# Create basic configuration +cat > ~/.genesis/config <` for detailed guides +- Check kit documentation with `genesis info ` + +### Community + +- **Slack** - Join [Genesis Community Slack](https://genesiscommunity.slack.com) +- **GitHub** - Report issues and contribute +- **Office Hours** - Weekly community calls + +### Learning Resources + +- **[Genesis Examples](https://github.com/genesis-community/examples)** - Sample deployments +- **[Kit Repositories](https://github.com/genesis-community)** - All official kits +- **[Training Materials](https://genesis-community.io/docs)** - Workshops and tutorials + +## Certification Path + +Consider this learning progression: + +1. **Genesis Basics** ✓ + - First deployment + - Environment management + - Basic operations + +2. **Intermediate Skills** + - Multi-environment deployments + - Pipeline automation + - Troubleshooting + +3. **Advanced Topics** + - Kit development + - Complex architectures + - Performance tuning + +4. **Expert Level** + - Contributing to Genesis + - Creating community kits + - Training others + +## Quick Reference + +Essential commands for your journey: + +```bash +# Deployment lifecycle +genesis init --kit # Start new repository +genesis new # Create environment +genesis deploy # Deploy environment +genesis info # Kit documentation + +# Operations +genesis list # List all environments +genesis switch # Change repositories +genesis describe # Environment details +genesis manifest # View manifest + +# Maintenance +genesis rotate-secrets # Rotate credentials +genesis check # Pre-deployment checks +genesis do -- # Run kit addons + +# Help +genesis help # General help +genesis help # Topic help +genesis -h # Command help +``` + +## Your Genesis Journey + +Remember: +- Start small and iterate +- Use version control for everything +- Ask questions in the community +- Share your experiences + +Welcome to the Genesis community! \ No newline at end of file diff --git a/docs/topics/10-environments/.keep b/docs/topics/10-environments/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/10-environments/best-practices.md b/docs/topics/10-environments/best-practices.md new file mode 100644 index 00000000..eeb8f4bb --- /dev/null +++ b/docs/topics/10-environments/best-practices.md @@ -0,0 +1,462 @@ +# Environment Best Practices + +This guide provides recommendations for organizing and managing Genesis environments effectively, based on real-world experience with large-scale deployments. + +## Naming Conventions + +### Choose a Consistent Pattern + +Pick one pattern and use it everywhere: + +```yaml +# Pattern 1: Organization-first (Recommended) +acme-aws-us-east-1-prod +acme-aws-us-west-2-staging +acme-vsphere-dc1-dev + +# Pattern 2: Purpose-last (Also good) +aws-us-east-1-acme-prod +aws-us-west-2-acme-staging +vsphere-dc1-acme-dev +``` + +### Keep Names Meaningful + +Each segment should convey information: + +```yaml +# Good - Clear hierarchy +acme-aws-us-east-1-prod +#│ │ │ │ └─ Purpose/Stage +#│ │ │ └────── Availability Zone +#│ │ └─────────── Region +#│ └──────────────── Infrastructure +#└───────────────────── Organization + +# Bad - Unclear segments +acme-aws-use1-p +env-1-prod +``` + +### Document Your Convention + +Create a README explaining your naming: + +```markdown +# Environment Naming Convention + +All environments follow this pattern: +`----` + +- org: Organization identifier (acme, globex) +- cloud: Infrastructure provider (aws, azure, gcp, vsphere) +- region: Geographic region (us-east-1, europe-west1) +- az: Availability zone or datacenter (optional) +- purpose: Environment purpose (prod, staging, dev, sandbox) +``` + +## Configuration Organization + +### Use Hierarchy Effectively + +Organize configurations from general to specific: + +```yaml +# base.yml - Global settings +params: + company: ACME Corp + ntp_servers: [0.pool.ntp.org, 1.pool.ntp.org] + +# aws.yml - AWS-wide settings +params: + stemcell_os: ubuntu-bionic + stemcell_version: latest + +# aws-us-east-1.yml - Region settings +params: + region: us-east-1 + availability_zones: [a, b, c] + +# aws-us-east-1-prod.yml - Environment specific +params: + instances: 5 + enable_monitoring: true +``` + +### Avoid Duplication + +Put shared settings at the appropriate level: + +```yaml +# Bad - Duplicated in every environment +# aws-us-east-1-dev.yml +params: + ntp_servers: [10.0.0.1, 10.0.0.2] + dns_servers: [10.0.0.3, 10.0.0.4] + +# aws-us-east-1-prod.yml +params: + ntp_servers: [10.0.0.1, 10.0.0.2] # Duplicate! + dns_servers: [10.0.0.3, 10.0.0.4] # Duplicate! + +# Good - Shared at region level +# aws-us-east-1.yml +params: + ntp_servers: [10.0.0.1, 10.0.0.2] + dns_servers: [10.0.0.3, 10.0.0.4] +``` + +### Feature Management + +Use features consistently: + +```yaml +# base.yml - Default features +kit: + features: + - base-monitoring + - base-logging + +# prod.yml - Production additions +kit: + features: + - base-monitoring + - base-logging + - haproxy # Add load balancer + - shield-agent # Add backups +``` + +## Directory Structure + +### Standard Layout + +Maintain consistent directory structure: + +``` +deployments/ +├── README.md # Document your conventions +├── .gitignore # Exclude caches and secrets +├── bin/ # Shared scripts and reactions +│ ├── common-functions +│ ├── notify-slack +│ └── update-dns +├── bosh/ # BOSH directors +│ ├── base.yml +│ ├── aws.yml +│ └── aws-us-east-1.yml +├── vault/ # Vault clusters +│ ├── base.yml +│ └── aws-us-east-1.yml +└── cf/ # Cloud Foundry + ├── base.yml + ├── aws.yml + ├── aws-us-east-1.yml + └── aws-us-east-1-prod.yml +``` + +### Separate Concerns + +Keep different deployment types in separate directories: + +```bash +# Good - Clear separation +deployments/cf/ +deployments/concourse/ +deployments/vault/ + +# Bad - Mixed types +deployments/ +├── cf-prod.yml +├── vault-prod.yml +└── concourse-prod.yml +``` + +## Version Control + +### What to Commit + +```gitignore +# Always commit +*.yml # Environment files +bin/ # Scripts +ci/ # Pipeline definitions +README.md # Documentation + +# Never commit +.genesis/cache/ # Downloaded kits +.genesis/manifests/ # Generated manifests +*-secrets.yml # Any actual secrets +*.key # Private keys +*.pem # Certificates +``` + +### Branching Strategy + +Use branches for environment promotion: + +```bash +# Feature branch for changes +git checkout -b add-monitoring + +# Make changes +vim base.yml + +# Test in dev +genesis deploy aws-us-east-1-dev + +# Merge to main +git checkout main +git merge add-monitoring + +# Deploy through environments +genesis deploy aws-us-east-1-staging +genesis deploy aws-us-east-1-prod +``` + +### Commit Messages + +Be descriptive: + +```bash +# Good +git commit -m "Enable Shield backups for production CF" +git commit -m "Scale web instances from 3 to 5 in us-east-1" + +# Bad +git commit -m "Update config" +git commit -m "Changes" +``` + +## Security Practices + +### Never Store Secrets + +Always use Vault references: + +```yaml +# Bad - Hardcoded secret +params: + admin_password: "SuperSecret123!" + +# Good - Vault reference +params: + admin_password: ((vault "secret/path:password")) +``` + +### Protect Sensitive Configurations + +Some configurations reveal infrastructure: + +```yaml +# Consider making these Vault references +params: + aws_access_key: ((vault "secret/aws:access_key")) + aws_secret_key: ((vault "secret/aws:secret_key")) + internal_domain: ((vault "secret/networking:internal_domain")) +``` + +### Audit Access + +Regular review access patterns: + +```bash +# Check who can deploy to production +safe auth list + +# Review Vault policies +safe policy list +``` + +## Operational Practices + +### Environment Promotion + +Follow a consistent promotion path: + +``` +Development → Staging → Production + +sandbox → dev → qa → staging → prod +``` + +### Testing Changes + +Always test in lower environments: + +```bash +# 1. Deploy to dev +genesis deploy aws-us-east-1-dev + +# 2. Run smoke tests +genesis do aws-us-east-1-dev -- smoke-tests + +# 3. Promote to staging +genesis deploy aws-us-east-1-staging + +# 4. Full integration tests +run-integration-tests staging + +# 5. Deploy to production +genesis deploy aws-us-east-1-prod +``` + +### Documentation + +Document everything: + +```markdown +## Environment Overview + +### Production +- **Environment**: aws-us-east-1-prod +- **Purpose**: Production customer-facing services +- **Maintenance Window**: Sunday 2-4 AM EST +- **Contacts**: ops-team@example.com + +### Staging +- **Environment**: aws-us-east-1-staging +- **Purpose**: Pre-production testing +- **Refresh Schedule**: Weekly from production +- **Contacts**: dev-team@example.com +``` + +## Troubleshooting Practices + +### Manifest Validation + +Always check before deploying: + +```bash +# Check manifest generation +genesis manifest aws-us-east-1-prod + +# Validate changes +genesis manifest aws-us-east-1-prod > new.yml +genesis manifest aws-us-east-1-prod --cached > old.yml +diff old.yml new.yml +``` + +### Debugging Inheritance + +Understand your configuration chain: + +```bash +# See full inheritance +genesis describe aws-us-east-1-prod + +# Check specific values +genesis lookup aws-us-east-1-prod params.instances +``` + +### Rollback Procedures + +Document rollback steps: + +```markdown +## Rollback Procedure + +1. Revert Git commit: + ```bash + git revert HEAD + git push + ``` + +2. Redeploy previous version: + ```bash + genesis deploy aws-us-east-1-prod + ``` + +3. Verify services: + ```bash + genesis do aws-us-east-1-prod -- smoke-tests + ``` +``` + +## Performance Tips + +### Use Match Mode + +Enable for faster operations: + +```bash +# Setup in ~/.genesis/config +deployment_roots: + - ~/deployments + +# Use patterns +genesis deploy @prod:cf +genesis list @*:vault +``` + +### Cache Manifests + +For repeated operations: + +```bash +# Cache manifest for debugging +genesis manifest my-env --cache + +# Use cached version +genesis manifest my-env --cached +``` + +### Parallel Operations + +When safe, run in parallel: + +```bash +# Deploy multiple dev environments +genesis deploy aws-us-east-1-dev & +genesis deploy aws-us-west-2-dev & +wait +``` + +## Common Pitfalls to Avoid + +### 1. Inconsistent Naming + +Stick to your pattern: +```bash +# Bad - Mixed patterns +aws-us-east-1-prod +aws-west-2-prod # Missing 'us' +production-aws-east # Different order +``` + +### 2. Over-Nesting + +Don't create too many levels: +```bash +# Too deep +acme-aws-us-east-1-az-a-vpc-123-subnet-456-prod + +# Better +acme-aws-us-east-1a-prod +``` + +### 3. Environment Sprawl + +Regular cleanup: +```bash +# Find unused environments +genesis list | grep -E '(old|test|tmp)' + +# Archive old environments +mkdir archived +git mv *-old.yml archived/ +``` + +### 4. Forgetting Vault Paths + +Document special paths: +```yaml +# In environment file +# Note: This environment uses custom Vault paths +# Secrets: /secret/special/acme/prod/cf +# Exodus: /secret/exodus/acme-prod/cf +genesis: + secrets_slug: special/acme/prod + exodus_slug: acme-prod +``` + +By following these best practices, you'll maintain clean, understandable, and manageable Genesis deployments that scale with your organization. \ No newline at end of file diff --git a/docs/topics/10-environments/bosh-integration.md b/docs/topics/10-environments/bosh-integration.md new file mode 100644 index 00000000..d98bcf8b --- /dev/null +++ b/docs/topics/10-environments/bosh-integration.md @@ -0,0 +1,402 @@ +# BOSH Integration + +Genesis environments map directly to BOSH deployments. Understanding this relationship is crucial for debugging, manual BOSH operations, and advanced deployment scenarios. + +## BOSH Director Selection + +### Automatic Selection + +By default, Genesis deploys to a BOSH director with the same name as the environment: + +```yaml +# Environment: acme-aws-us-east-1-prod.yml +# Deploys to: acme-aws-us-east-1-prod BOSH director +``` + +### Manual Override + +Override the target BOSH director: + +```yaml +genesis: + env: acme-aws-us-east-1-prod + bosh_env: acme-aws-us-east-1-mgmt # Use different director +``` + +Common override scenarios: +- BOSH directors (can't deploy to themselves) +- Shared management directors +- Cross-region deployments + +## Deployment Names + +### Naming Convention + +BOSH deployment names follow the pattern: +``` +- +``` + +Examples: +- Environment: `acme-aws-us-east-1-prod.yml` +- Kit: `cf-genesis-kit` +- BOSH deployment: `acme-aws-us-east-1-prod-cf` + +### Viewing Deployments + +```bash +# List all deployments on targeted director +bosh deployments + +# Filter by Genesis pattern +bosh deployments | grep -- '-cf$' +``` + +## BOSH Configuration Management + +### Cloud Config + +Genesis manages BOSH cloud configs with prefixed names: + +```yaml +# VM types become prefixed +vm_types: +- name: acme-aws-us-east-1-prod-small + cloud_properties: + instance_type: t3.small + +# Disk types are prefixed +disk_types: +- name: acme-aws-us-east-1-prod-small + disk_size: 10240 + +# Networks remain unprefixed +networks: +- name: default + type: manual + subnets: [...] +``` + +### Runtime Config + +Runtime configs can be specified per environment: + +```yaml +# In environment file +genesis: + runtime_configs: + - my-runtime-config + - dns-runtime-config +``` + +### CPI Config + +For multi-CPI directors: + +```yaml +genesis: + cpi_configs: + - aws-cpi-config +``` + +## Environment Variables + +### BOSH Connection + +Genesis sets these for BOSH operations: + +```bash +BOSH_ENVIRONMENT=10.0.0.6 +BOSH_CA_CERT=/tmp/genesis-ca-cert.XXXX +BOSH_CLIENT=admin +BOSH_CLIENT_SECRET= +``` + +### Manual BOSH Access + +```bash +# Get BOSH credentials +genesis do my-env -- login + +# Now use BOSH directly +bosh deployments +bosh vms +``` + +## Deployment Lifecycle + +### What Genesis Does + +1. **Pre-deployment**: + - Targets correct BOSH director + - Uploads required releases + - Updates cloud/runtime configs + - Generates manifest + +2. **Deployment**: + - Runs `bosh deploy` + - Monitors deployment progress + - Handles errors + +3. **Post-deployment**: + - Runs post-deploy hooks + - Updates exodus data + - Cleans up temporary files + +### Manual Deployment + +For troubleshooting, deploy manually: + +```bash +# Generate manifest +genesis manifest my-env > manifest.yml + +# Target BOSH +genesis do my-env -- login + +# Deploy manually +bosh -d my-env-cf deploy manifest.yml +``` + +## Advanced Integration + +### Instance Management + +```bash +# Through Genesis +genesis do my-env -- ssh router/0 + +# Direct BOSH commands +bosh -d acme-aws-us-east-1-prod-cf ssh router/0 +bosh -d acme-aws-us-east-1-prod-cf restart router +``` + +### Logs and Debugging + +```bash +# Get deployment logs +genesis do my-env -- logs + +# Specific instance logs +bosh -d my-env-cf logs router/0 + +# Recent BOSH tasks +bosh tasks --recent +bosh task --debug +``` + +### Errands + +```bash +# Run smoke tests +genesis do my-env -- run-errand smoke-tests + +# Direct BOSH errand +bosh -d my-env-cf run-errand smoke-tests +``` + +## BOSH Teams and UAA + +### Multi-Tenancy + +Configure BOSH teams in your environment: + +```yaml +params: + bosh_teams: + - name: developers + auth: + type: uaa + provider: github + permissions: + - deployment: my-env-cf + operations: ["read", "ssh"] +``` + +### Authentication + +```yaml +params: + bosh_auth: + type: uaa + uaa_url: https://uaa.example.com + client_id: genesis + client_secret: ((uaa_client_secret)) +``` + +## Cloud Config Details + +### VM Type Mapping + +Genesis maps kit VM types to cloud config: + +```yaml +# Kit requests +instance_groups: +- name: web + vm_type: small + +# Genesis prefixes for uniqueness +# Uses: acme-aws-us-east-1-prod-small +``` + +### Network Selection + +Networks are not prefixed: + +```yaml +# Environment file +params: + cf_network: cf-net + +# Cloud config +networks: +- name: cf-net # Used as-is + subnets: [...] +``` + +### Availability Zones + +```yaml +params: + availability_zones: + - z1 + - z2 + - z3 +``` + +## Troubleshooting + +### Deployment Not Found + +Check: +- Correct BOSH director targeted +- Deployment name includes kit suffix +- Environment was actually deployed + +### Cloud Config Issues + +```bash +# View current cloud config +bosh cloud-config + +# Check for prefixed types +bosh cloud-config | grep my-env + +# Update cloud config +genesis do my-env -- cloud-config +``` + +### Version Mismatches + +```bash +# Check BOSH version +bosh env + +# Genesis expects BOSH v2 CLI +genesis -v +``` + +### Authentication Problems + +```bash +# Re-authenticate +genesis do my-env -- login + +# Check credentials in Vault +safe get secret/exodus/my-env-bosh/bosh +``` + +## Best Practices + +### 1. Use Genesis Commands + +Prefer Genesis commands over direct BOSH: +- Handles authentication +- Maintains consistency +- Includes Genesis features + +### 2. Understand the Mapping + +Know how Genesis names map to BOSH: +- Helps with debugging +- Enables manual intervention +- Useful for monitoring + +### 3. Document Overrides + +When overriding BOSH director: +```yaml +genesis: + # Document why this override exists + bosh_env: shared-mgmt # Using shared director for cost savings +``` + +### 4. Monitor Both Layers + +Monitor at both levels: +- Genesis operations (deployments, rotations) +- BOSH health (VMs, disks, compilations) + +### 5. Backup Considerations + +```bash +# Backup BOSH director state +genesis do my-bosh -- bbr backup + +# Includes: +# - Deployment manifests +# - Cloud configs +# - BOSH database +``` + +## Integration Examples + +### CI/CD Pipeline + +```yaml +# Concourse task +- name: deploy-cf + plan: + - task: genesis-deploy + config: + run: + path: genesis + args: ["deploy", "my-env", "--yes"] +``` + +### Monitoring Integration + +```bash +# Prometheus BOSH exporter config +jobs: +- name: bosh_exporter + properties: + bosh: + url: ((exodus.my-env-bosh.bosh.url)) + ca_cert: ((exodus.my-env-bosh.bosh.ca_cert)) + username: ((exodus.my-env-bosh.bosh.admin_username)) + password: ((exodus.my-env-bosh.bosh.admin_password)) +``` + +### Custom Scripts + +```bash +#!/bin/bash +# Scale CF cells + +ENV="acme-aws-us-east-1-prod" +DEPLOYMENT="${ENV}-cf" + +# Login to BOSH +genesis do $ENV -- login + +# Scale cells +bosh -d $DEPLOYMENT scale diego-cell=10 +``` + +Understanding BOSH integration enables you to: +- Debug deployment issues +- Perform manual operations +- Integrate with existing tools +- Build custom automation \ No newline at end of file diff --git a/docs/topics/10-environments/configuration-merging.md b/docs/topics/10-environments/configuration-merging.md new file mode 100644 index 00000000..4af7512a --- /dev/null +++ b/docs/topics/10-environments/configuration-merging.md @@ -0,0 +1,413 @@ +# Configuration Merging + +Genesis uses a powerful hierarchical merging system to manage configuration across environments. This guide explains how configurations are merged, override rules, and best practices. + +## How Merging Works + +Genesis merges configuration files in a specific order, with later values overriding earlier ones. This allows you to define common settings once and override them where needed. + +### Merge Order + +For an environment named `acme-aws-us-east-1-prod.yml`, Genesis merges in this order: + +1. Kit base manifest +2. Kit features (ops files) +3. `acme.yml` +4. `acme-aws.yml` +5. `acme-aws-us.yml` +6. `acme-aws-us-east.yml` +7. `acme-aws-us-east-1.yml` +8. `acme-aws-us-east-1-prod.yml` +9. Any files from `genesis.inherits` + +### Basic Override Example + +```yaml +# acme.yml +params: + company: ACME Corp + instances: 1 + enable_monitoring: true + +# acme-aws.yml +params: + cloud: aws + instances: 2 # Overrides acme.yml + +# acme-aws-us-east-1-prod.yml +params: + env: production + instances: 5 # Overrides both previous files +``` + +Final result: +```yaml +params: + company: ACME Corp # From acme.yml + enable_monitoring: true # From acme.yml + cloud: aws # From acme-aws.yml + env: production # From acme-aws-us-east-1-prod.yml + instances: 5 # From acme-aws-us-east-1-prod.yml (last wins) +``` + +## Merge Types + +### Simple Values + +Later values completely replace earlier ones: + +```yaml +# parent.yml +params: + port: 8080 + +# child.yml +params: + port: 443 # Replaces 8080 +``` + +### Arrays + +Arrays are replaced, not merged: + +```yaml +# parent.yml +params: + availability_zones: + - us-east-1a + - us-east-1b + +# child.yml +params: + availability_zones: + - us-east-1c # Only us-east-1c remains +``` + +To append to arrays, you must include all values: + +```yaml +# child.yml +params: + availability_zones: + - us-east-1a # Include original values + - us-east-1b + - us-east-1c # Add new value +``` + +### Maps (Hashes) + +Maps are deep-merged: + +```yaml +# parent.yml +params: + database: + host: localhost + port: 5432 + pool: 10 + +# child.yml +params: + database: + host: prod-db.example.com # Overrides + ssl: true # Adds new key + # port: 5432 (inherited) + # pool: 10 (inherited) +``` + +Result: +```yaml +params: + database: + host: prod-db.example.com + port: 5432 + pool: 10 + ssl: true +``` + +## Special Merge Keys + +### The `(( merge ))` Operator + +While Genesis doesn't use Spruce operators during environment file merging, understanding this pattern helps when working with ops files: + +```yaml +# In ops files or kit manifests +meta: + things: (( merge )) # Indicates this should be merged +``` + +### Null Values + +Use `null` to remove inherited values: + +```yaml +# parent.yml +params: + debug_mode: true + log_level: debug + +# production.yml +params: + debug_mode: false + log_level: null # Removes this key entirely +``` + +## Complex Merging Examples + +### Network Configuration + +```yaml +# base.yml +params: + networks: + default: + dns: + - 8.8.8.8 + - 8.8.4.4 + mtu: 1500 + +# aws.yml +params: + networks: + default: + dns: + - 10.0.0.2 # Replaces public DNS + - 10.0.0.3 + type: manual + # mtu: 1500 (inherited) + +# aws-us-east-1-prod.yml +params: + networks: + default: + subnets: + - range: 10.0.1.0/24 + gateway: 10.0.1.1 + # dns inherited from aws.yml + # type inherited from aws.yml + # mtu inherited from base.yml +``` + +### Feature Flags + +```yaml +# base.yml +params: + features: + monitoring: enabled + backups: enabled + debug: disabled + +# dev.yml +params: + features: + debug: enabled # Override for dev + test_mode: enabled # Add new feature + # monitoring: enabled (inherited) + # backups: enabled (inherited) +``` + +## Using genesis.inherits + +For non-hierarchical inheritance: + +```yaml +# special-security.yml +params: + security: + require_https: true + min_tls_version: "1.2" + +# aws-us-east-1-prod.yml +genesis: + inherits: + - special-security # Merged after hierarchical files +params: + env: production +``` + +### Multiple Inherits + +```yaml +genesis: + inherits: + - base-networking # First + - security-policies # Second + - performance-tuning # Third (wins conflicts) +``` + +## Best Practices + +### 1. Design for Inheritance + +Structure your configurations to minimize overrides: + +```yaml +# Good: Use specific keys +params: + cell_instances: 3 + router_instances: 2 + +# Bad: Generic names cause conflicts +params: + instances: 3 # Which component? +``` + +### 2. Document Inheritance + +Add comments explaining inheritance: + +```yaml +# aws-us-east-1-prod.yml +params: + # Inherits from: base.yml -> aws.yml -> aws-us-east-1.yml + instances: 5 # Override: was 2 in aws.yml +``` + +### 3. Use Intermediate Files + +Create logical groupings: + +```yaml +# aws-networking.yml - Shared AWS network config +params: + networks: + default: + type: manual + dns: ["10.0.0.2"] + +# aws-security.yml - Shared AWS security +params: + security_groups: + - default + - bosh +``` + +### 4. Avoid Deep Nesting + +Flatten when possible: + +```yaml +# Good +params: + database_host: prod-db.example.com + database_port: 5432 + +# Harder to override +params: + database: + connection: + host: prod-db.example.com + port: 5432 +``` + +## Debugging Merge Issues + +### View Effective Configuration + +```bash +# See what values an environment will use +genesis describe aws-us-east-1-prod + +# View the final manifest +genesis manifest aws-us-east-1-prod +``` + +### Check Inheritance Chain + +```bash +# List all files in merge order +genesis describe aws-us-east-1-prod --show-hierarchy +``` + +### Common Issues + +#### Values Not Overriding + +Check: +- Correct key names (typos prevent overrides) +- Proper YAML indentation +- File naming follows hierarchy + +#### Unexpected Array Behavior + +Remember arrays replace entirely: +```yaml +# Wrong: Expecting append +child: + my_array: + - new_value # Old values lost! + +# Right: Include all values +child: + my_array: + - old_value_1 + - old_value_2 + - new_value +``` + +#### Missing Inherited Values + +Verify: +- Parent file exists +- No `null` assignments +- Correct merge order + +## Advanced Patterns + +### Environment-Specific Overrides + +```yaml +# base.yml +params: + log_level: (( grab params.environment_log_level || "info" )) + +# dev.yml +params: + environment_log_level: debug + +# prod.yml +params: + environment_log_level: error +``` + +### Conditional Features + +```yaml +# base.yml +params: + enable_feature_x: false + +# staging.yml +params: + enable_feature_x: true # Test in staging first +``` + +### Shared Configurations + +```yaml +# tls-config.yml +params: + tls: + certificate: | + -----BEGIN CERTIFICATE----- + ... + protocols: + - TLSv1.2 + - TLSv1.3 + +# Multiple environments inherit +genesis: + inherits: + - tls-config +``` + +## Summary + +- Genesis merges hierarchically based on environment name +- Later files override earlier files +- Simple values replace, maps deep-merge, arrays replace entirely +- Use `genesis.inherits` for non-hierarchical inclusion +- Design configurations for inheritance from the start +- Test with `genesis describe` and `genesis manifest` \ No newline at end of file diff --git a/docs/topics/10-environments/file-structure.md b/docs/topics/10-environments/file-structure.md new file mode 100644 index 00000000..1092ba0e --- /dev/null +++ b/docs/topics/10-environments/file-structure.md @@ -0,0 +1,383 @@ +# Environment File Structure + +Understanding how to organize your Genesis environment files is crucial for maintainable deployments. This guide covers directory layouts, file organization patterns, and best practices. + +## Basic Structure + +### Single Kit Repository +``` +my-cf-deployments/ +├── .genesis/ +│ ├── config # Repository configuration +│ ├── cache/ # Downloaded kits +│ └── kits/ # Local kit overrides +├── .gitignore +├── README.md +├── base.yml # Global defaults (optional) +├── aws.yml # AWS-specific settings +├── aws-us.yml # US region settings +├── aws-us-east-1.yml # Specific region settings +├── aws-us-east-1-dev.yml # Development environment +├── aws-us-east-1-staging.yml # Staging environment +└── aws-us-east-1-prod.yml # Production environment +``` + +### Environment File Contents + +A typical environment file contains: + +```yaml +--- +# Kit configuration +kit: + name: cf + version: 2.3.0 + features: + - haproxy + - postgres + - routing-api + +# Environment parameters +params: + # Environment identification + env: aws-us-east-1-prod + + # Infrastructure settings + availability_zones: + - us-east-1a + - us-east-1b + - us-east-1c + + # CF-specific configuration + base_domain: cf.example.com + skip_ssl_validation: false + + # Resource sizing + cell_instances: 3 + router_instances: 2 +``` + +## Multi-Kit Organization + +### Deployment Root Structure + +For organizations with multiple kits: + +``` +deployments/ # Deployment root +├── .genesis/ +│ └── config # Root configuration +├── bosh/ # BOSH directors +│ ├── .genesis/config +│ ├── aws.yml +│ ├── aws-us-east-1.yml +│ └── aws-us-west-2.yml +├── vault/ # Vault deployments +│ ├── .genesis/config +│ ├── aws.yml +│ └── aws-us-east-1.yml +├── cf/ # Cloud Foundry +│ ├── .genesis/config +│ ├── base.yml +│ ├── aws.yml +│ ├── aws-us-east-1-dev.yml +│ ├── aws-us-east-1-staging.yml +│ └── aws-us-east-1-prod.yml +└── concourse/ # Concourse CI + ├── .genesis/config + ├── aws.yml + └── aws-us-east-1.yml +``` + +### Benefits of This Structure + +1. **Clear Separation** - Each kit has its own directory +2. **Shared Settings** - Common configs at deployment root +3. **Easy Navigation** - Predictable locations +4. **Git Flexibility** - Can be one repo or many + +## Operations Files + +### Using Ops Files + +Operations files modify the base manifest during compilation: + +``` +cf-deployments/ +├── aws-us-east-1-prod.yml +└── ops/ + ├── enable-debug.yml # Debugging features + ├── scale-cells.yml # Custom scaling + └── custom-certificates.yml # Additional certs +``` + +Reference in environment file: +```yaml +kit: + features: + - enable-debug # Looks for ops/enable-debug.yml + - scale-cells +``` + +### Ops File Example + +```yaml +# ops/scale-cells.yml +- type: replace + path: /instance_groups/name=diego-cell/instances + value: 10 + +- type: replace + path: /instance_groups/name=diego-cell/vm_type + value: large +``` + +## Hierarchical Files + +### Inheritance Chain Example + +``` +deployments/cf/ +├── base.yml # Level 1: Global defaults +├── aws.yml # Level 2: AWS-wide settings +├── aws-us.yml # Level 3: US regions +├── aws-us-east-1.yml # Level 4: Specific region +└── aws-us-east-1-prod.yml # Level 5: Final environment +``` + +### What Goes Where + +#### Global Level (`base.yml`) +```yaml +params: + # Company-wide settings + company_name: ACME Corp + + # Default DNS servers + dns: + - 8.8.8.8 + - 8.8.4.4 + + # Security policies + password_policy: + min_length: 14 + require_special: true +``` + +#### Infrastructure Level (`aws.yml`) +```yaml +params: + # AWS-specific settings + cloud_provider: aws + + # AWS instance types + default_vm_type: t3.small + + # Availability zones format + availability_zone_pattern: "{region}{az}" +``` + +#### Region Level (`aws-us-east-1.yml`) +```yaml +params: + # Region configuration + region: us-east-1 + + # Regional endpoints + s3_endpoint: https://s3.us-east-1.amazonaws.com + + # Network ranges + management_network: 10.0.0.0/16 +``` + +#### Environment Level (`aws-us-east-1-prod.yml`) +```yaml +params: + # Environment specifics + env: production + + # Scaling parameters + instances: 5 + + # Environment-specific domains + system_domain: prod.cf.example.com + apps_domain: apps.example.com +``` + +## Alternative Patterns + +### By Purpose First +``` +deployments/ +├── production/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +├── staging/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +└── development/ + ├── cf/ + ├── bosh/ + └── vault/ +``` + +### By Region First +``` +deployments/ +├── us-east-1/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +├── us-west-2/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +└── eu-west-1/ + ├── cf/ + ├── bosh/ + └── vault/ +``` + +## Supporting Files + +### README Files + +Include documentation: +```markdown +# Cloud Foundry Deployments + +This repository contains Genesis CF deployments. + +## Environments + +- `aws-us-east-1-dev` - Development environment +- `aws-us-east-1-staging` - Staging (pre-production) +- `aws-us-east-1-prod` - Production + +## Deployment + +```bash +genesis deploy aws-us-east-1-prod +``` +``` + +### .gitignore + +Standard Genesis gitignore: +``` +# Genesis +.genesis/cache/ +.genesis/config +.genesis/manifests/ +.genesis/releases/ +.genesis/kits/ + +# Editor files +.*.sw? +*~ + +# OS files +.DS_Store +Thumbs.db + +# Temporary files +*.tmp +``` + +### CI/CD Files + +Pipeline configuration: +``` +cf-deployments/ +├── ci/ +│ ├── pipeline.yml +│ ├── scripts/ +│ │ ├── test.sh +│ │ └── deploy.sh +│ └── settings.yml +└── .concourse/ + └── secrets.yml +``` + +## Best Practices + +### 1. Consistent Naming +- Use the same pattern everywhere +- Document your conventions +- Stick to lowercase and hyphens + +### 2. Logical Grouping +- Group by kit type, not by environment +- Keep related environments together +- Use hierarchy to reduce duplication + +### 3. Version Control +```bash +# Track everything except caches +git add -A +git commit -m "Added production environment" + +# Don't track +# - .genesis/cache/ +# - .genesis/manifests/ +# - Any secrets +``` + +### 4. Documentation +- README in each kit directory +- Comment complex configurations +- Document non-obvious choices + +### 5. Secrets Management +- Never commit secrets +- Use Vault references +- Document secret requirements + +## Common Patterns + +### Development Workflow +``` +cf/ +├── dev.yml # Shared dev settings +├── john-dev.yml # Personal dev environment +├── mary-dev.yml # Personal dev environment +└── ci-dev.yml # CI test environment +``` + +### Multi-Datacenter +``` +cf/ +├── dc1.yml # Datacenter 1 base +├── dc1-prod.yml # DC1 production +├── dc1-dr.yml # DC1 disaster recovery +├── dc2.yml # Datacenter 2 base +├── dc2-prod.yml # DC2 production +└── dc2-dr.yml # DC2 disaster recovery +``` + +### Blue-Green Deployments +``` +cf/ +├── prod.yml # Shared production settings +├── prod-blue.yml # Blue environment +└── prod-green.yml # Green environment +``` + +## Troubleshooting + +### File Not Found +- Check exact filename and extension +- Verify you're in the right directory +- Ensure .yml extension is present + +### Inheritance Issues +- Verify parent files exist +- Check for typos in names +- Review hyphen placement + +### Merge Conflicts +- Use explicit keys in child files +- Override entire structures when needed +- Test with `genesis manifest` to verify \ No newline at end of file diff --git a/docs/topics/10-environments/index.md b/docs/topics/10-environments/index.md new file mode 100644 index 00000000..f0412fee --- /dev/null +++ b/docs/topics/10-environments/index.md @@ -0,0 +1,104 @@ +# Environment Management + +This section covers everything you need to know about Genesis environments - from naming conventions to configuration management. + +## Topics in This Section + +1. **[Naming Conventions](naming-conventions.md)** - Environment naming rules and patterns +2. **[File Structure](file-structure.md)** - Organizing environment files +3. **[Configuration Merging](configuration-merging.md)** - How hierarchical inheritance works +4. **[Match Mode](match-mode.md)** - Quick environment selection +5. **[Vault Paths](vault-paths.md)** - Secret storage conventions +6. **[BOSH Integration](bosh-integration.md)** - How environments map to BOSH +7. **[Reactions](reactions.md)** - Pre and post-deploy scripts +8. **[Best Practices](best-practices.md)** - Recommendations and patterns + +## Quick Overview + +Genesis environments are the heart of your infrastructure-as-code. Each environment represents a single deployment with its own: + +- YAML configuration file +- Hierarchical inheritance from parent configs +- Secrets stored in Vault +- BOSH deployment manifest + +### Key Concepts + +**Environment File**: A YAML file (e.g., `us-east-1-prod.yml`) that defines a deployment's configuration. + +**Hierarchical Merging**: Configurations inherit from parent files based on naming patterns: +``` +us.yml # US-wide settings +└── us-east.yml # US East settings + └── us-east-1.yml # Specific region + └── us-east-1-prod.yml # Production environment +``` + +**Match Mode**: Quick selection using patterns: +```bash +genesis deploy @prod:cf # Deploy any CF prod environment +``` + +## Common Patterns + +### Standard Naming Convention +``` +---.yml +``` + +Examples: +- `acme-aws-us-east-1-prod.yml` +- `globex-azure-westeurope-staging.yml` +- `startup-gcp-us-central1-dev.yml` + +### Directory Organization +``` +deployments/ +├── bosh/ +│ ├── acme.yml # Company-wide BOSH settings +│ ├── acme-aws.yml # AWS-specific BOSH settings +│ └── acme-aws-us-east-1.yml # Region-specific BOSH +├── vault/ +│ └── acme-aws-us-east-1.yml # Vault deployment +└── cf/ + ├── acme.yml # Company-wide CF settings + ├── acme-prod.yml # Production CF settings + └── acme-aws-us-east-1-prod.yml # Full CF deployment +``` + +## Getting Started + +1. **Learn the naming rules** in [Naming Conventions](naming-conventions.md) +2. **Understand inheritance** with [Configuration Merging](configuration-merging.md) +3. **Organize your files** using [File Structure](file-structure.md) +4. **Speed up workflows** with [Match Mode](match-mode.md) + +## Common Tasks + +### Create a New Environment +```bash +genesis new us-east-1-prod +``` + +### View Environment Hierarchy +```bash +genesis describe us-east-1-prod +``` + +### Check What Will Be Deployed +```bash +genesis manifest us-east-1-prod +``` + +### Deploy an Environment +```bash +genesis deploy us-east-1-prod +``` + +## Tips + +- Use consistent naming across all deployments +- Leverage hierarchy to avoid repetition +- Document your naming conventions +- Test changes in lower environments first +- Use match mode for faster operations \ No newline at end of file diff --git a/docs/topics/10-environments/match-mode.md b/docs/topics/10-environments/match-mode.md new file mode 100644 index 00000000..a3e497eb --- /dev/null +++ b/docs/topics/10-environments/match-mode.md @@ -0,0 +1,362 @@ +# Match Mode + +Match mode provides a powerful way to quickly reference Genesis environments using glob-style patterns instead of typing full environment names. This is especially useful with long, hierarchical environment names. + +## Overview + +Instead of typing: +```bash +genesis deploy acme-aws-us-east-1-production +``` + +You can use: +```bash +genesis deploy @prod:cf +``` + +The `@` prefix activates match mode, allowing pattern matching against environment names. + +## Enabling Match Mode + +Match mode requires configuring deployment roots in your `~/.genesis/config`: + +```yaml +--- +deployment_roots: + - ~/deployments # Simple path + - work: ~/work/deployments # Labeled path + - prod: /opt/genesis/prod # Production deployments +``` + +Without deployment roots configured, match mode is not available. + +## Match Mode Syntax + +### Basic Pattern +``` +@: +``` + +- `@` - Activates match mode +- `` - Glob pattern to match environment names +- `:` - Kit type (optional but recommended) + +### Examples + +```bash +# Match any production CF environment +genesis deploy @prod:cf + +# Match us-east production +genesis deploy @*east*prod:cf + +# Match anything in us-west-2 +genesis deploy @*west-2*:bosh + +# Match dev environments +genesis deploy @*dev:vault +``` + +## Pattern Matching + +### Wildcards + +- `*` - Matches any characters +- `?` - Matches single character + +```bash +@prod # Matches: prod, production, acme-prod +@*-prod # Matches: us-east-1-prod, aws-prod +@us-*-1-* # Matches: us-east-1-dev, us-west-1-prod +@us-????-1-prod # Matches: us-east-1-prod, us-west-1-prod +``` + +### Case Sensitivity + +Matches are case-sensitive: +```bash +@prod # Won't match: Prod, PROD +``` + +## Interactive Selection + +When multiple environments match, Genesis presents a menu: + +```bash +$ genesis deploy @*:cf + +Multiple environment files found matching @*:cf: + + 📁 Deployment Root 'work': ~/work/deployments + 1) cf/acme-aws-us-east-1-dev (default) + 2) cf/acme-aws-us-east-1-staging + 3) cf/acme-aws-us-east-1-prod + 4) cf/acme-aws-us-west-2-prod + + 5) None of these - cancel + +Select the desired environment file > +``` + +## Deployment Types + +The `:` suffix specifies which kit type to search: + +```bash +@prod:cf # Cloud Foundry deployments +@prod:bosh # BOSH directors +@prod:vault # Vault deployments +@prod:concourse # Concourse deployments +``` + +### Benefits of Specifying Type + +1. **Faster** - Only searches relevant directories +2. **Accurate** - Avoids matching similarly named environments +3. **Clear** - Shows intent in commands + +## Working with Multiple Roots + +With multiple deployment roots: + +```yaml +deployment_roots: + - personal: ~/my-deployments + - work: ~/work/deployments + - client: ~/client/infrastructure +``` + +Matches search all roots: + +```bash +$ genesis list @prod:* + +personal: + bosh/home-prod + vault/personal-prod + +work: + cf/acme-aws-us-east-1-prod + cf/acme-aws-us-west-2-prod + +client: + cf/bigco-azure-eastus-prod + concourse/bigco-ci-prod +``` + +## Common Patterns + +### By Environment Stage + +```bash +# Development environments +genesis deploy @*dev*:cf +genesis check @*development*:vault + +# Staging environments +genesis manifest @*staging*:cf +genesis rotate-secrets @*stage*:bosh + +# Production environments +genesis deploy @*prod*:cf +genesis describe @*production*:vault +``` + +### By Region + +```bash +# US East environments +genesis deploy @*us-east*:cf +genesis list @*east-1*:* + +# Europe environments +genesis check @*eu-*:bosh +genesis manifest @*europe*:vault + +# All AWS environments +genesis list @*aws*:* +``` + +### By Organization + +```bash +# ACME environments +genesis deploy @acme*:cf +genesis list @acme-*:* + +# Department-specific +genesis deploy @*finance*:vault +genesis check @*engineering*:cf +``` + +## Advanced Usage + +### Combining with Other Commands + +Match mode works with most Genesis commands: + +```bash +# Deployment operations +genesis deploy @prod:cf +genesis check @staging:vault +genesis manifest @dev:bosh + +# Information commands +genesis describe @prod:cf +genesis list @*:vault +genesis info @dev:* + +# Maintenance commands +genesis rotate-secrets @prod:vault +genesis do @staging:cf -- smoke-tests + +# Pipeline operations +genesis repipe @*:cf +``` + +### Scripting with Match Mode + +For scripts, use exact matches when possible: + +```bash +#!/bin/bash +# Deploy all production CF environments + +for env in $(genesis list @*prod:cf --json | jq -r '.[].name'); do + echo "Deploying $env..." + genesis deploy "$env" +done +``` + +### Unique Patterns + +Design patterns that uniquely identify environments: + +```bash +# Too broad +@prod # Matches: prod, production, non-prod + +# More specific +@*-prod # Matches: us-east-1-prod (not non-prod) +@prod:cf # Only CF production environments +``` + +## Best Practices + +### 1. Use Type Suffixes + +Always include the kit type for clarity: +```bash +# Good +genesis deploy @prod:cf + +# Less clear +genesis deploy @prod +``` + +### 2. Test Patterns First + +Use `list` to verify your pattern: +```bash +# Check what matches before deploying +genesis list @*west*:cf +genesis deploy @*west*:cf +``` + +### 3. Be Specific in Production + +For production operations, use specific patterns: +```bash +# Good - very specific +genesis deploy @acme-aws-us-east-1-prod:cf + +# Risky - might match unexpected environments +genesis deploy @prod:cf +``` + +### 4. Document Common Patterns + +Keep a reference of useful patterns: +```markdown +## Common Match Patterns + +- `@*dev*:cf` - All CF dev environments +- `@*-prod:vault` - All production Vaults +- `@acme-*:*` - All ACME environments +- `@*us-east-1*:bosh` - US East 1 BOSH directors +``` + +## Troubleshooting + +### No Matches Found + +Check: +- Deployment roots are configured +- Pattern is correct +- Environment files exist +- Kit type is correct + +### Too Many Matches + +Make pattern more specific: +```bash +# Too broad +@*:cf + +# Better +@*prod:cf +@*us-east*prod:cf +``` + +### Match Mode Not Working + +Verify deployment roots: +```bash +# Check configuration +cat ~/.genesis/config + +# Should include: +deployment_roots: + - /path/to/deployments +``` + +### Wrong Environment Selected + +- Double-check the selection number +- Use more specific patterns +- Consider using full environment name + +## Examples + +### Quick Deployment Check +```bash +# Check all production environments before deploying +genesis check @*prod:cf +genesis check @*prod:vault +genesis check @*prod:bosh +``` + +### Regional Operations +```bash +# Rotate secrets for all US East production +genesis rotate-secrets @*us-east*prod:cf +genesis rotate-secrets @*us-east*prod:vault +``` + +### Development Workflow +```bash +# Deploy to your personal dev environment +genesis deploy @john-dev:cf + +# Check all team dev environments +genesis list @*-dev:cf +``` + +### Disaster Recovery +```bash +# Quick DR environment access +genesis do @*-dr:vault -- unseal +genesis deploy @*-dr:cf +``` + +Match mode significantly speeds up Genesis operations, especially in environments with many deployments and long naming conventions. \ No newline at end of file diff --git a/docs/topics/10-environments/naming-conventions.md b/docs/topics/10-environments/naming-conventions.md new file mode 100644 index 00000000..f474b2bb --- /dev/null +++ b/docs/topics/10-environments/naming-conventions.md @@ -0,0 +1,273 @@ +# Environment Naming Conventions + +Genesis uses environment names to automatically build configuration hierarchies, determine BOSH deployments, and organize secrets in Vault. Understanding these conventions is crucial for effective Genesis usage. + +## Naming Rules + +### Valid Characters and Format + +Environment filenames must follow these rules: + +- **Extension**: Must end with `.yml` +- **Characters**: Only lowercase letters, numbers, underscores, and hyphens +- **Start**: Must begin with a letter +- **End**: Cannot end with a hyphen +- **Hyphens**: No consecutive hyphens (`--`) + +### Valid Examples +``` +env1.yml +us-east-1-prod.yml +acme_aws_us_east_1_prod.yml +my-really-long-hyphenated-name.yml +``` + +### Invalid Examples +``` +-prod.yml # Starts with hyphen +prod-.yml # Ends with hyphen +prod--east.yml # Consecutive hyphens +PROD.yml # Uppercase letters +prod@east.yml # Invalid character (@) +``` + +## Hierarchical Structure + +Genesis uses hyphens to create a configuration hierarchy. Each hyphen-separated segment represents a level that can have its own configuration file. + +### How It Works + +For an environment named `acme-aws-us-east-1-prod.yml`, Genesis automatically looks for and merges these files in order: + +1. `acme.yml` - Organization level +2. `acme-aws.yml` - Infrastructure level +3. `acme-aws-us.yml` - Country/region level +4. `acme-aws-us-east.yml` - Region level +5. `acme-aws-us-east-1.yml` - Availability zone level +6. `acme-aws-us-east-1-prod.yml` - Environment level + +Each level inherits from the previous, with later values overriding earlier ones. + +### Common Naming Patterns + +#### Organization-First Pattern +``` +--- + +Examples: +- acme-aws-us-east-1-prod +- acme-azure-westeurope-staging +- acme-vsphere-dc1-dev +``` + +#### Infrastructure-First Pattern +``` +--- + +Examples: +- aws-us-east-1-acme-prod +- gcp-us-central1-startup-dev +``` + +#### Purpose-Last Pattern (Recommended) +``` +-- + +Examples: +- acme-aws-prod +- startup-onprem-datacenter1-staging +- enterprise-cloud-region2-zone-a-dev +``` + +## Configuration Inheritance + +### Example Hierarchy + +Given these files: +```yaml +# acme.yml +params: + company: ACME Corp + dns: + - 10.0.0.1 + - 10.0.0.2 + +# acme-aws.yml +params: + cloud: aws + region: us-east-1 + +# acme-aws-us-east-1.yml +params: + availability_zone: us-east-1a + +# acme-aws-us-east-1-prod.yml +params: + env: production + instances: 3 +``` + +The final configuration for `acme-aws-us-east-1-prod` includes all settings: +```yaml +params: + company: ACME Corp + dns: + - 10.0.0.1 + - 10.0.0.2 + cloud: aws + region: us-east-1 + availability_zone: us-east-1a + env: production + instances: 3 +``` + +### Override Behavior + +Later files override earlier ones: +```yaml +# acme.yml +params: + instances: 1 + +# acme-aws-us-east-1-prod.yml +params: + instances: 3 # This wins +``` + +## BOSH Deployment Names + +Genesis creates BOSH deployment names using the pattern: +``` +- +``` + +Examples: +- Environment: `acme-aws-us-east-1-prod.yml` +- Kit: `cf-genesis-kit` +- BOSH deployment: `acme-aws-us-east-1-prod-cf` + +## Vault Path Structure + +### Secrets Path + +Secrets are stored with the environment name split into segments: +``` +/secret/// + +Example: +Environment: aws-us-east-1-prod.yml +Kit: cf +Path: /secret/aws/us/east/1/prod/cf/ +``` + +### Exodus Path + +Exodus data uses the full environment name: +``` +/secret/exodus// + +Example: +Environment: aws-us-east-1-prod.yml +Kit: cf +Path: /secret/exodus/aws-us-east-1-prod/cf +``` + +## Custom Paths + +### Overriding Secrets Path +```yaml +genesis: + secrets_mount: custom-secrets # default: "secret" + secrets_slug: prod-aws # default: split name +``` + +### Overriding Exodus Path +```yaml +genesis: + exodus_mount: custom-exodus # default: "/exodus" + exodus_slug: cf-production # default: full name +``` + +## Special Cases + +### BOSH Directors + +BOSH directors cannot deploy themselves, so use: +```yaml +genesis: + env: aws-us-east-1-bosh + bosh_env: aws-us-east-1-proto # Different director +``` + +### Non-Hierarchical Inheritance + +Use `genesis.inherits` for custom inheritance: +```yaml +genesis: + inherits: + - base-config + - regional-overrides + - security-policies +``` + +## Best Practices + +1. **Be Consistent** - Use the same pattern across all environments +2. **Purpose Last** - Put environment purpose (dev/staging/prod) at the end +3. **Meaningful Segments** - Each segment should represent a logical grouping +4. **Document Your Schema** - Keep a README explaining your naming convention +5. **Avoid Over-Nesting** - 4-6 segments is usually sufficient + +## Examples by Use Case + +### Multi-Region AWS +``` +acme-aws-us-east-1-prod.yml +acme-aws-us-west-2-prod.yml +acme-aws-eu-west-1-prod.yml +``` + +### Multi-Cloud +``` +startup-aws-us-east-1-prod.yml +startup-gcp-us-central1-prod.yml +startup-azure-eastus-prod.yml +``` + +### Development Stages +``` +app-cloud-region-dev.yml +app-cloud-region-staging.yml +app-cloud-region-prod.yml +``` + +### By Department +``` +acme-finance-aws-prod.yml +acme-hr-aws-prod.yml +acme-engineering-aws-prod.yml +``` + +## Troubleshooting + +### Environment Not Found + +Check: +- File has `.yml` extension +- Using exact name (unless using match mode) +- In correct directory + +### Inheritance Not Working + +Verify: +- Parent files exist +- Names follow hyphen hierarchy +- No typos in filenames + +### Vault Paths Too Long + +Use `secrets_slug` to shorten: +```yaml +genesis: + secrets_slug: prod-east # Instead of very/long/path/segments +``` \ No newline at end of file diff --git a/docs/topics/10-environments/reactions.md b/docs/topics/10-environments/reactions.md new file mode 100644 index 00000000..02cd9923 --- /dev/null +++ b/docs/topics/10-environments/reactions.md @@ -0,0 +1,399 @@ +# Reactions + +Reactions allow you to run custom scripts before and after deployments on a per-environment basis. This enables environment-specific automation like maintenance notifications, integration updates, or custom validations. + +## Overview + +Reactions are scripts that execute at specific points in the deployment lifecycle: +- **Pre-deploy**: Before the deployment starts +- **Post-deploy**: After the deployment completes (or fails) + +## Configuration + +Add reactions to your environment file under the `genesis.reactions` key: + +```yaml +genesis: + reactions: + pre-deploy: + - script: put-up-maintenance-page + - script: update-jira + args: ['PROD-123', 'Deploying CF'] + post-deploy: + - addon: run-smoke-tests + - script: remove-maintenance-page + - script: notify-slack + args: ['#deployments', 'CF Production deployed'] +``` + +## Script Location + +Scripts must be placed in the `bin/` directory at the repository root: + +``` +cf-deployments/ +├── bin/ +│ ├── put-up-maintenance-page +│ ├── remove-maintenance-page +│ ├── update-jira +│ └── notify-slack +├── base.yml +└── aws-us-east-1-prod.yml +``` + +Scripts are automatically included in pipeline caches and made available during deployment. + +## Script Arguments + +### Static Arguments + +Pass fixed arguments to scripts: + +```yaml +reactions: + pre-deploy: + - script: notify-team + args: ['production', 'cf', 'starting'] +``` + +### Environment Variables + +Use environment variables in arguments: + +```yaml +reactions: + post-deploy: + - script: update-dashboard + args: ['$GENESIS_ENVIRONMENT', '$DEPLOYMENT_STATUS'] +``` + +## Available Environment Variables + +Scripts have access to these environment variables: + +### Always Available + +- `GENESIS_ENVIRONMENT` - Current environment name +- `GENESIS_KIT_NAME` - Kit being deployed +- `GENESIS_KIT_VERSION` - Kit version +- `GENESIS_VAULT_PREFIX` - Vault path prefix +- `GENESIS_MANIFEST_FILE` - Path to the full manifest +- `GENESIS_BOSHVARS_FILE` - Path to BOSH variables file +- `GENESIS_DEPLOY_OPTIONS` - JSON of deployment options +- `GENESIS_DEPLOY_DRYRUN` - `true` if dry-run, `false` otherwise + +### Pre-deploy Only + +- `GENESIS_PREDEPLOY_DATAFILE` - Data from pre-deploy hook + +### Post-deploy Only + +- `GENESIS_DEPLOY_RC` - Deployment return code (0=success, 1=failure) + +## Script Examples + +### Maintenance Page Script + +```bash +#!/bin/bash +# bin/put-up-maintenance-page + +set -e + +ENVIRONMENT="${GENESIS_ENVIRONMENT}" +MAINTENANCE_BUCKET="s3://maintenance-pages" + +# Generate maintenance page +cat > /tmp/maintenance.html < + +Maintenance + +

System Maintenance

+

We're updating ${ENVIRONMENT}. Back soon!

+ + +EOF + +# Upload to CDN +aws s3 cp /tmp/maintenance.html "$MAINTENANCE_BUCKET/${ENVIRONMENT}.html" + +# Update load balancer +aws elb configure-health-check \ + --load-balancer-name "${ENVIRONMENT}-lb" \ + --health-check Target=HTTP:80/maintenance.html + +echo "Maintenance page activated for ${ENVIRONMENT}" +``` + +### Jira Integration + +```bash +#!/bin/bash +# bin/update-jira + +set -e + +TICKET_ID="$1" +COMMENT="$2" +JIRA_URL="https://jira.example.com" + +# Add deployment comment +curl -X POST \ + -H "Authorization: Bearer $JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + "$JIRA_URL/rest/api/2/issue/$TICKET_ID/comment" \ + -d "{\"body\": \"Deployment: $COMMENT\"}" + +# Transition ticket if successful +if [ "$GENESIS_DEPLOY_RC" = "0" ]; then + curl -X POST \ + -H "Authorization: Bearer $JIRA_API_TOKEN" \ + "$JIRA_URL/rest/api/2/issue/$TICKET_ID/transitions" \ + -d '{"transition": {"id": "31"}}' # Deploy Complete +fi +``` + +### Slack Notification + +```bash +#!/bin/bash +# bin/notify-slack + +CHANNEL="$1" +MESSAGE="$2" +WEBHOOK_URL="$SLACK_WEBHOOK_URL" + +STATUS="success" +COLOR="good" + +if [ "$GENESIS_DEPLOY_RC" = "1" ]; then + STATUS="failed" + COLOR="danger" +fi + +curl -X POST "$WEBHOOK_URL" \ + -H "Content-Type: application/json" \ + -d @- < -- run-smoke-tests +genesis do -- update-dns +``` + +## Advanced Patterns + +### Conditional Execution + +```bash +#!/bin/bash +# Only run in production + +if [[ "$GENESIS_ENVIRONMENT" == *-prod ]]; then + echo "Running production-only task..." + # Production logic here +fi +``` + +### Using Manifest Data + +```bash +#!/bin/bash +# Extract data from manifest + +# Get instance count +INSTANCES=$(spruce json "$GENESIS_MANIFEST_FILE" | \ + jq '.instance_groups[] | select(.name=="web") | .instances') + +# Alert if scaling up significantly +if [ "$INSTANCES" -gt 10 ]; then + send-alert "Scaling to $INSTANCES instances!" +fi +``` + +### Error Handling + +```bash +#!/bin/bash +# Handle deployment failures + +if [ "$GENESIS_DEPLOY_RC" != "0" ]; then + # Rollback actions + restore-database-snapshot + clear-cache + + # Alert on-call + pagerduty-alert "Deployment failed for $GENESIS_ENVIRONMENT" + + exit 1 +fi +``` + +## Best Practices + +### 1. Make Scripts Idempotent + +Scripts should handle being run multiple times: + +```bash +# Good - checks before acting +if ! maintenance-page-exists; then + create-maintenance-page +fi + +# Bad - assumes state +rm /var/www/index.html # Fails if already removed +``` + +### 2. Handle Failures Gracefully + +```bash +#!/bin/bash +set -e # Exit on error + +# Cleanup function +cleanup() { + echo "Cleaning up..." + remove-temp-files +} +trap cleanup EXIT + +# Main logic +do-deployment-task || { + echo "Task failed, but continuing deployment" + exit 0 # Don't fail the deployment +} +``` + +### 3. Log Appropriately + +```bash +#!/bin/bash +LOG_FILE="/var/log/genesis-reactions.log" + +log() { + echo "[$(date)] $GENESIS_ENVIRONMENT: $1" | tee -a "$LOG_FILE" +} + +log "Starting pre-deploy reaction" +# ... script logic ... +log "Pre-deploy reaction complete" +``` + +### 4. Use Version Control + +Always commit reaction scripts: + +```bash +git add bin/ +git commit -m "Add deployment reaction scripts" +``` + +### 5. Test Scripts Locally + +```bash +# Test with mock environment +export GENESIS_ENVIRONMENT="test-env" +export GENESIS_DEPLOY_RC="0" +./bin/notify-slack "#test" "Test message" +``` + +## Common Use Cases + +### Database Migrations + +```yaml +reactions: + pre-deploy: + - script: backup-database + - script: run-migrations +``` + +### Cache Management + +```yaml +reactions: + post-deploy: + - script: clear-cdn-cache + - script: warm-application-cache +``` + +### External Service Updates + +```yaml +reactions: + post-deploy: + - script: update-load-balancer + - script: register-service-discovery + - script: update-monitoring +``` + +### Compliance and Auditing + +```yaml +reactions: + pre-deploy: + - script: log-deployment-start + args: ['audit-system'] + post-deploy: + - script: log-deployment-complete + args: ['audit-system', '$GENESIS_DEPLOY_RC'] +``` + +## Troubleshooting + +### Script Not Found + +Ensure: +- Script is in `bin/` directory +- Script has execute permissions: `chmod +x bin/script-name` +- Script name matches exactly (case-sensitive) + +### Environment Variables Not Set + +Check: +- Using correct variable names +- Variables are exported in script +- Not overwriting Genesis variables + +### Script Failures + +- Check script logs +- Run script manually to test +- Verify all dependencies available +- Check script exit codes + +### Pipeline Issues + +For CI/CD pipelines: +- Ensure bin/ directory is included +- Scripts are committed to Git +- Pipeline has necessary credentials + +Reactions provide powerful automation capabilities while maintaining environment-specific flexibility. \ No newline at end of file diff --git a/docs/topics/10-environments/vault-paths.md b/docs/topics/10-environments/vault-paths.md new file mode 100644 index 00000000..939fc78c --- /dev/null +++ b/docs/topics/10-environments/vault-paths.md @@ -0,0 +1,361 @@ +# Vault Path Structure + +Genesis automatically organizes secrets in Vault using a predictable path structure based on environment names. Understanding these paths is essential for debugging, manual secret management, and integration with other tools. + +## Default Path Structure + +### Secrets Path + +Genesis stores deployment secrets using a hierarchical path that mirrors your environment naming: + +``` +/secret/// + +Example: +Environment: acme-aws-us-east-1-prod.yml +Kit: cf +Vault path: /secret/acme/aws/us/east/1/prod/cf/ +``` + +The environment name is split on hyphens, with each segment becoming a directory level in Vault. + +### Exodus Path + +Exodus data (deployment outputs shared with other deployments) uses a different structure: + +``` +/secret/exodus// + +Example: +Environment: acme-aws-us-east-1-prod.yml +Kit: bosh +Vault path: /secret/exodus/acme-aws-us-east-1-prod/bosh +``` + +Exodus paths keep the environment name intact rather than splitting it. + +## Path Components + +### Mount Points + +- **Secrets Mount**: `/secret` (default) +- **Exodus Mount**: `/secret/exodus` (default) + +### Environment Segments + +Environment name split on hyphens: +- `acme-aws-us-east-1-prod` → `acme/aws/us/east/1/prod` +- `company-vsphere-dc1-dev` → `company/vsphere/dc1/dev` + +### Kit Type + +The deployment type (kit name without `-genesis-kit`): +- `cf-genesis-kit` → `cf` +- `bosh-genesis-kit` → `bosh` +- `vault-genesis-kit` → `vault` + +## Secret Organization + +### Common Secret Patterns + +Within each deployment's Vault path: + +``` +/secret/acme/aws/us/east/1/prod/cf/ +├── admin_password # User credentials +├── app_domain_cert # X.509 certificates +│ ├── cert +│ ├── key +│ └── ca +├── bbs_encryption_key # Encryption keys +├── db/ # Database credentials +│ ├── password +│ └── username +└── jwt_signing_key # JWT keys + ├── private + └── public +``` + +### Secret Types + +Genesis automatically generates various secret types: + +#### Passwords +``` +/secret/.../admin_password +/secret/.../db/password +/secret/.../nats_password +``` + +#### SSH Keys +``` +/secret/.../jumpbox_ssh +├── private +└── public +``` + +#### X.509 Certificates +``` +/secret/.../router_ssl +├── cert +├── key +├── ca +└── combined # Sometimes includes cert+key +``` + +#### RSA Keys +``` +/secret/.../jwt_signing_key +├── private +└── public +``` + +## Exodus Data + +### What Is Exodus? + +Exodus data provides deployment information to other deployments: + +```yaml +# BOSH director exodus +/secret/exodus/acme-aws-us-east-1-bosh/bosh +├── url # https://10.0.0.6:25555 +├── ca_cert # BOSH director CA +├── admin_username # admin +└── admin_password # generated password +``` + +### Using Exodus Data + +Other deployments reference exodus data: + +```yaml +# In CF deployment +params: + bosh: acme-aws-us-east-1-bosh # References exodus data +``` + +Genesis automatically retrieves: +- BOSH URL +- CA certificate +- Admin credentials + +## Custom Paths + +### Overriding Secrets Paths + +In your environment file: + +```yaml +genesis: + # Change the mount point + secrets_mount: secret/genesis # Default: secret + + # Change the path structure + secrets_slug: production/cf # Default: split by hyphens +``` + +Results in: `/secret/genesis/production/cf/` + +### Overriding Exodus Paths + +```yaml +genesis: + # Custom exodus mount + exodus_mount: secret/shared # Default: /exodus + + # Custom exodus slug + exodus_slug: cf-production # Default: full environment name +``` + +Results in: `/secret/shared/cf-production/cf` + +### When to Customize + +Consider custom paths when: +- Organization Vault policies restrict paths +- Migrating from another system +- Integrating with existing Vault structure +- Path segments exceed Vault limits + +## Vault Operations + +### Viewing Secrets + +```bash +# List all secrets for an environment +safe tree secret/acme/aws/us/east/1/prod/cf + +# View specific secret +safe get secret/acme/aws/us/east/1/prod/cf/admin_password + +# Export all secrets +safe export secret/acme/aws/us/east/1/prod/cf +``` + +### Manual Secret Management + +```bash +# Set a specific secret +safe set secret/acme/aws/us/east/1/prod/cf/custom_key value=mysecret + +# Generate a new password +safe gen secret/acme/aws/us/east/1/prod/cf/new_password + +# Create SSH key +safe ssh secret/acme/aws/us/east/1/prod/cf/ssh_key +``` + +### Copying Secrets + +```bash +# Copy between environments +safe cp \ + secret/acme/aws/us/east/1/dev/cf \ + secret/acme/aws/us/east/1/staging/cf +``` + +## Path Discovery + +### Finding Paths + +```bash +# Show environment's Vault paths +genesis describe acme-aws-us-east-1-prod + +# In deployment output +Secrets Path: secret/acme/aws/us/east/1/prod/cf +Exodus Path: secret/exodus/acme-aws-us-east-1-prod/cf +``` + +### Debugging Path Issues + +Check for: +1. Correct environment name +2. Proper hyphen placement +3. Kit type identification +4. Mount point permissions + +## Best Practices + +### 1. Use Default Paths + +Stick to defaults unless necessary: +- Predictable for team members +- Easier troubleshooting +- Better tool integration + +### 2. Document Custom Paths + +If using custom paths: +```yaml +# Document WHY in environment file +genesis: + secrets_mount: restricted/project-x # Required by security policy XYZ +``` + +### 3. Consistent Naming + +Keep environment names consistent: +- Easier path prediction +- Simpler secret management +- Clearer organization + +### 4. Access Control + +Set Vault policies by path: +```hcl +# Dev team access to dev environments +path "secret/acme/*/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Read-only prod access +path "secret/acme/*/prod/*" { + capabilities = ["read", "list"] +} +``` + +### 5. Backup Considerations + +When backing up: +```bash +# Backup entire environment +safe export secret/acme/aws/us/east/1/prod/cf > cf-prod-backup.json + +# Include exodus data +safe export secret/exodus/acme-aws-us-east-1-prod/cf > cf-prod-exodus.json +``` + +## Common Issues + +### Secrets Not Found + +Check: +- Environment name spelling +- Hyphen placement +- Kit type detection +- Vault authentication + +### Path Too Long + +Vault has segment limits. Solutions: +1. Shorten environment names +2. Use `secrets_slug` override +3. Reduce hierarchy depth + +### Permission Denied + +Verify: +- Vault token permissions +- Policy allows path access +- Mount point exists + +### Exodus Data Missing + +Ensure: +- Source deployment succeeded +- Exodus path is correct +- No custom path overrides conflict + +## Integration Examples + +### CI/CD Integration + +```yaml +# Concourse pipeline +- name: get-cf-secrets + plan: + - task: export-secrets + config: + run: + path: safe + args: + - export + - secret/acme/aws/us/east/1/prod/cf +``` + +### Terraform Integration + +```hcl +# Read Genesis secrets in Terraform +data "vault_generic_secret" "cf_admin" { + path = "secret/acme/aws/us/east/1/prod/cf/admin_password" +} +``` + +### Monitoring Integration + +```bash +# Script to check certificate expiration +for cert in $(safe find secret | grep cert$); do + expiry=$(safe get $cert | openssl x509 -noout -dates) + echo "$cert: $expiry" +done +``` + +Understanding Vault paths helps you: +- Debug secret issues +- Integrate with other tools +- Implement access controls +- Manage secrets manually when needed \ No newline at end of file diff --git a/docs/topics/30-secrets-management/.keep b/docs/topics/30-secrets-management/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/30-secrets-management/best-practices.md b/docs/topics/30-secrets-management/best-practices.md new file mode 100644 index 00000000..f0e0e558 --- /dev/null +++ b/docs/topics/30-secrets-management/best-practices.md @@ -0,0 +1,446 @@ +# Secrets Management Best Practices + +This guide provides security best practices for managing secrets in Genesis deployments. Following these practices helps maintain a strong security posture. + +## General Principles + +### 1. Never Commit Secrets + +**Never** store secrets in version control: + +```yaml +# BAD - Hardcoded secret +params: + admin_password: "SuperSecret123!" # NEVER DO THIS + +# GOOD - Reference from Vault +params: + admin_password: ((vault "secret/path:password")) +``` + +Use `.gitignore`: +```gitignore +# Ignore all potential secret files +*-secrets.yml +*.key +*.pem +*.crt +credentials.json +.env +``` + +### 2. Use Strong Secrets + +Configure appropriate secret strength: + +```yaml +# Weak - Too short +credentials: + base: + password: random 8 # BAD + +# Strong - Sufficient length and complexity +credentials: + base: + password: random 32 # GOOD + api_key: "random 40 fmt base64" # BETTER +``` + +### 3. Rotate Regularly + +Establish rotation schedules: + +| Secret Type | Rotation Frequency | Notes | +|------------|-------------------|-------| +| Passwords | 90 days | More frequent for privileged accounts | +| API Keys | 180 days | Depends on provider requirements | +| SSH Keys | 365 days | Rotate immediately if compromised | +| Server Certificates | 30 days before expiry | Automate monitoring | +| CA Certificates | 1 year before expiry | Plan carefully | + +### 4. Principle of Least Privilege + +Grant minimal necessary access: + +```hcl +# Vault policy - Developer +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/staging/*" { + capabilities = ["read", "list"] # Read-only +} + +path "secret/prod/*" { + capabilities = ["deny"] # No access +} +``` + +## Vault Security + +### Secure Vault Deployment + +```yaml +# Production Vault configuration +params: + # Use auto-unseal + vault_seal_type: awskms + vault_awskms_key_id: ((aws_kms_key_id)) + + # Enable audit logging + vault_audit_enabled: true + + # Use TLS + vault_tls_cert: ((vault_tls_cert)) + vault_tls_key: ((vault_tls_key)) + + # High availability + vault_instances: 3 +``` + +### Audit Logging + +Always enable audit logs: + +```bash +# Enable file audit backend +vault audit enable file \ + file_path=/vault/logs/audit.log \ + log_raw=false + +# Enable syslog for SIEM integration +vault audit enable syslog \ + tag="vault" \ + facility="LOCAL7" +``` + +### Backup Procedures + +Regular encrypted backups: + +```bash +#!/bin/bash +# backup-vault.sh + +DATE=$(date +%Y%m%d-%H%M%S) +BACKUP_FILE="vault-backup-${DATE}.tar.gz" + +# Create backup +genesis do vault-prod -- backup + +# Encrypt backup +gpg --encrypt \ + --recipient backup@example.com \ + "$BACKUP_FILE" + +# Upload to secure storage +aws s3 cp "${BACKUP_FILE}.gpg" \ + s3://secure-backups/vault/ + +# Clean up +rm -f "$BACKUP_FILE" "${BACKUP_FILE}.gpg" +``` + +## Access Control + +### Multi-Factor Authentication + +Enable MFA for Vault access: + +```bash +# Enable TOTP MFA +vault write sys/mfa/method/totp/my_totp \ + issuer=Genesis \ + period=30 \ + algorithm=SHA256 \ + digits=6 + +# Require MFA for production paths +vault write sys/policy/mfa/production_mfa \ + enforcement_config='[{ + "mfa_method_ids": ["method_id"], + "auth_method_types": ["token"] + }]' +``` + +### Time-Based Access + +Use temporary credentials: + +```bash +# Create time-limited token +safe auth token create \ + --policy=deployment \ + --ttl=1h \ + --max-ttl=2h \ + --display-name="CI deployment" +``` + +### Service Account Management + +```yaml +# Separate accounts for each service +credentials: + base: + # Don't reuse accounts + cf/nats_password: random 32 + cf/router_password: random 32 + cf/controller_password: random 32 + + # Not this + # shared_service_password: random 32 # BAD +``` + +## Secret Hygiene + +### Regular Audits + +```bash +#!/bin/bash +# audit-secrets.sh - Run monthly + +echo "=== Secret Age Report ===" + +# Check password age +for env in dev staging prod; do + echo "Environment: $env" + + # List secrets with metadata + safe export "secret/$env" | \ + jq -r 'to_entries[] | + select(.key | contains("password")) | + "\(.key): \(.value.updated_at // "unknown")"' +done + +echo "=== Expiring Certificates ===" +# Find certificates expiring soon +safe find secret | grep cert$ | while read -r cert; do + if safe x509 expires "$cert" --within 30d; then + echo "WARNING: $cert expires soon" + fi +done +``` + +### Cleanup Unused Secrets + +```bash +# Find potentially unused secrets +genesis list --json | jq -r '.[].name' > active-envs.txt + +safe find secret | while read -r secret; do + # Extract environment from path + env=$(echo "$secret" | cut -d/ -f2-3) + + if ! grep -q "$env" active-envs.txt; then + echo "Potentially unused: $secret" + fi +done +``` + +### Document Secret Usage + +```yaml +# In environment files, document external usage +genesis: + secrets_notes: | + admin_password: Used by monitoring system (Datadog) + api_key: Shared with partner integration + db_password: Also configured in backup scripts +``` + +## Secure Development + +### Development Environments + +Use separate Vault instances: + +```bash +# Development Vault (unsealed, insecure) +safe init dev --memory + +# Never use dev mode for real secrets +safe set secret/dev/test password=test123 +``` + +### Secret Scanning + +Pre-commit hooks to catch secrets: + +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] +``` + +### Environment Isolation + +```bash +# Separate Vault paths by environment +/secret/dev/... # Development +/secret/staging/... # Staging +/secret/prod/... # Production + +# Different access policies +/secret/sandbox/... # Wide open for experiments +``` + +## Incident Response + +### Compromised Secrets + +If a secret is compromised: + +1. **Rotate immediately** + ```bash + genesis rotate-secrets prod compromised_password + genesis deploy prod + ``` + +2. **Audit access** + ```bash + grep "compromised_password" /var/log/vault-audit.log + ``` + +3. **Update dependencies** + ```bash + # Find all uses + genesis manifest prod | grep compromised_password + ``` + +4. **Document incident** + ```yaml + # In environment file + genesis: + security_incidents: + - date: 2024-01-15 + secret: admin_password + action: rotated + reason: potential exposure in logs + ``` + +### Emergency Access + +Break-glass procedures: + +```bash +# Sealed Vault emergency access +export VAULT_UNSEAL_KEY_1="..." +export VAULT_UNSEAL_KEY_2="..." +export VAULT_UNSEAL_KEY_3="..." + +vault operator unseal $VAULT_UNSEAL_KEY_1 +vault operator unseal $VAULT_UNSEAL_KEY_2 +vault operator unseal $VAULT_UNSEAL_KEY_3 + +# Use root token only in emergency +vault login $VAULT_ROOT_TOKEN +``` + +## Monitoring and Alerting + +### Certificate Expiration + +```bash +#!/bin/bash +# monitor-certs.sh - Run daily via cron + +ALERT_DAYS=30 +SLACK_WEBHOOK="https://hooks.slack.com/..." + +check_cert_expiry() { + local cert_path=$1 + local days_left=$(safe x509 expires "$cert_path" --json | \ + jq -r '.days_until_expiration') + + if [ "$days_left" -lt "$ALERT_DAYS" ]; then + curl -X POST "$SLACK_WEBHOOK" \ + -H "Content-Type: application/json" \ + -d "{\"text\": \"Certificate $cert_path expires in $days_left days\"}" + fi +} + +# Check all certificates +safe find secret | grep cert$ | while read -r cert; do + check_cert_expiry "$cert" +done +``` + +### Failed Authentication + +Monitor Vault audit logs: + +```bash +# Count failed authentications +grep "error" /var/log/vault-audit.log | \ + grep "permission denied" | \ + jq -r '.auth.display_name' | \ + sort | uniq -c | sort -rn +``` + +## Compliance + +### Regulatory Requirements + +Common compliance needs: + +```yaml +# PCI-DSS Compliance +credentials: + base: + # Requirement 8.2.4 - Change passwords every 90 days + payment_api_key: "random 40 rotate_days=90" + + # Requirement 8.2.3 - Strong passwords + admin_password: "random 32 complexity=high" + +# HIPAA Compliance +certificates: + base: + # Encryption in transit + api/tls: + valid_for: 1y + min_tls_version: "1.2" +``` + +### Audit Trail + +Maintain compliance records: + +```bash +# Generate compliance report +cat > compliance-report.sh <<'EOF' +#!/bin/bash + +echo "=== Secret Rotation Compliance Report ===" +echo "Generated: $(date)" +echo + +# Check rotation compliance +for secret in $(safe find secret/prod | grep password); do + last_rotated=$(safe get "$secret:updated_at" 2>/dev/null || echo "unknown") + echo "$secret: Last rotated $last_rotated" +done +EOF +``` + +## Security Checklist + +Before deploying to production: + +- [ ] All secrets in Vault (no hardcoded values) +- [ ] Appropriate secret strength (32+ chars for passwords) +- [ ] Rotation schedule defined +- [ ] Access policies configured +- [ ] Audit logging enabled +- [ ] Backup procedures tested +- [ ] Emergency access documented +- [ ] Monitoring alerts configured +- [ ] Compliance requirements met +- [ ] Team trained on procedures + +Following these best practices ensures your Genesis deployments remain secure while maintaining operational efficiency. \ No newline at end of file diff --git a/docs/topics/30-secrets-management/credhub-support.md b/docs/topics/30-secrets-management/credhub-support.md new file mode 100644 index 00000000..ba977243 --- /dev/null +++ b/docs/topics/30-secrets-management/credhub-support.md @@ -0,0 +1,453 @@ +# CredHub Support + +Genesis supports VMware CredHub as an alternative to HashiCorp Vault for secrets management. CredHub is particularly popular in Cloud Foundry environments due to its tight BOSH integration. + +## Overview + +CredHub provides: +- **Native BOSH integration** - Direct support in BOSH Director +- **Typed credentials** - Structured secret types +- **Automatic generation** - BOSH can generate missing credentials +- **ACL support** - Fine-grained access control +- **Certificate rotation** - Built-in certificate management + +## Enabling CredHub + +### BOSH Director Configuration + +Deploy BOSH with CredHub enabled: + +```yaml +# In BOSH environment file +kit: + features: + - aws + - credhub + +params: + credhub_enabled: true +``` + +### Environment Configuration + +Configure Genesis to use CredHub: + +```yaml +# In deployment environment file +genesis: + secrets_provider: credhub + credhub_env: my-bosh-director +``` + +## CredHub vs Vault + +### Feature Comparison + +| Feature | Vault | CredHub | +|---------|-------|---------| +| Secret Types | Generic KV | Typed (password, cert, etc.) | +| BOSH Integration | Via Genesis | Native | +| Access Control | Policies | ACLs | +| UI | Yes | Limited | +| Multi-DC | Yes | Per-BOSH | +| Audit Logs | Comprehensive | Basic | + +### When to Use CredHub + +Choose CredHub when: +- Deploying primarily Cloud Foundry +- Using BOSH heavily +- Want native BOSH integration +- Prefer typed credentials + +Choose Vault when: +- Need enterprise features +- Multiple secret backends +- Complex access policies +- Non-BOSH workloads + +## Secret Management + +### Viewing Secrets + +```bash +# Target CredHub +credhub api https://credhub.example.com:8844 + +# Login +credhub login --client-name genesis --client-secret + +# List secrets +credhub find -n '/genesis/us-east-1-prod' + +# Get specific secret +credhub get -n '/genesis/us-east-1-prod/cf/admin_password' +``` + +### Manual Secret Operations + +```bash +# Set a password +credhub set -n '/genesis/us-east-1-prod/cf/api_key' \ + -t password \ + -w 'super-secret-key' + +# Generate a password +credhub generate -n '/genesis/us-east-1-prod/cf/new_password' \ + -t password \ + -l 32 + +# Create certificate +credhub generate -n '/genesis/us-east-1-prod/cf/web_cert' \ + -t certificate \ + -c 'web.example.com' \ + -a 'web.example.com,*.apps.example.com' \ + --duration 365 \ + --ca '/genesis/us-east-1-prod/cf/ca' +``` + +## Path Structure + +### Genesis Paths in CredHub + +CredHub paths follow this pattern: +``` +/// + +Example: +/my-bosh/us-east-1-prod-cf/admin_password +``` + +### Custom Path Configuration + +```yaml +genesis: + credhub_prefix: /genesis/custom + env: us-east-1-prod +``` + +Results in paths like: +``` +/genesis/custom/us-east-1-prod/admin_password +``` + +## Certificate Management + +### Certificate Generation + +CredHub excels at certificate management: + +```bash +# Generate CA +credhub generate -n '/genesis/prod/ca' \ + -t certificate \ + --is-ca \ + --common-name 'Genesis CA' + +# Generate server certificate +credhub generate -n '/genesis/prod/server-cert' \ + -t certificate \ + --ca '/genesis/prod/ca' \ + --common-name 'server.example.com' \ + --alternative-names 'server.example.com,*.example.com' +``` + +### Certificate Rotation + +```bash +# Regenerate certificate +credhub regenerate -n '/genesis/prod/server-cert' + +# Bulk regenerate +credhub bulk-regenerate --signed-by '/genesis/prod/ca' +``` + +## Access Control + +### CredHub ACLs + +Define who can access secrets: + +```bash +# Grant read access +credhub set-permission \ + -n '/genesis/prod/*' \ + -a 'uaa-client:app1' \ + -p read + +# Grant write access +credhub set-permission \ + -n '/genesis/dev/*' \ + -a 'uaa-user:developer' \ + -p read,write +``` + +### UAA Integration + +CredHub uses UAA for authentication: + +```yaml +# In CF deployment +params: + credhub_uaa_clients: + - name: genesis + secret: ((credhub_genesis_client_secret)) + scopes: + - credhub.read + - credhub.write +``` + +## Integration with Genesis + +### Automatic Secret Generation + +Genesis kits work seamlessly with CredHub: + +```yaml +# Kit defines requirements +credentials: + base: + admin_password: random 32 + +# CredHub generates automatically during deploy +``` + +### Manual Provided Secrets + +For user-provided secrets: + +```bash +# Set before deployment +credhub set -n '/my-bosh/prod-cf/external_api_key' \ + -t value \ + -v 'provided-by-user' +``` + +### Interpolation + +CredHub interpolates at runtime: + +```yaml +# In manifest +properties: + admin_password: ((admin_password)) + +# CredHub provides value during deployment +``` + +## Migration + +### From Vault to CredHub + +```bash +#!/bin/bash +# Migrate secrets from Vault to CredHub + +VAULT_PATH="secret/us-east-1/prod/cf" +CREDHUB_PATH="/genesis/us-east-1-prod/cf" + +# Export from Vault +safe export $VAULT_PATH > secrets.json + +# Import to CredHub +for secret in $(jq -r 'keys[]' secrets.json); do + value=$(jq -r ".$secret" secrets.json) + + # Detect type and import + if [[ $secret == *"password"* ]]; then + credhub set -n "$CREDHUB_PATH/$secret" -t password -w "$value" + elif [[ $secret == *"cert"* ]]; then + credhub set -n "$CREDHUB_PATH/$secret" -t certificate -c "$value" + else + credhub set -n "$CREDHUB_PATH/$secret" -t value -v "$value" + fi +done +``` + +### From CredHub to Vault + +```bash +#!/bin/bash +# Migrate from CredHub to Vault + +# Export from CredHub +credhub find -n '/genesis/prod' -j | \ + jq -r '.credentials[].name' | \ + while read -r name; do + credhub get -n "$name" -j > "/tmp/$(basename $name).json" + done + +# Import to Vault +# ... conversion logic ... +``` + +## Operations + +### Backup and Restore + +```bash +# Backup CredHub database +bosh -d credhub-deployment \ + run-errand bbr-backup + +# Restore +bosh -d credhub-deployment \ + run-errand bbr-restore \ + --backup-artifact /path/to/backup +``` + +### Monitoring + +Monitor CredHub health: + +```yaml +# Prometheus metrics +- job_name: credhub + static_configs: + - targets: ['credhub.example.com:9000'] + metrics_path: /metrics +``` + +Key metrics: +- `credhub_credential_count` +- `credhub_operation_duration` +- `credhub_api_requests_total` + +### Performance Tuning + +```yaml +# In CredHub deployment +params: + credhub_encryption_keys: 2 # Multiple keys + credhub_db_connections: 20 # Connection pool + credhub_threads: 100 # Request threads +``` + +## Best Practices + +### 1. Use Typed Credentials + +```bash +# Good - typed password +credhub generate -n /path -t password + +# Less ideal - generic value +credhub set -n /path -t value -v "password" +``` + +### 2. Leverage Certificate Features + +```bash +# Use CA signing +credhub generate -n /ca -t certificate --is-ca +credhub generate -n /server -t certificate --ca /ca + +# Set expiry alerts +credhub set-permission -n /certs/* \ + -a 'monitoring-system' -p read +``` + +### 3. Implement ACLs + +```bash +# Principle of least privilege +credhub set-permission \ + -n '/prod/*' \ + -a 'prod-team' \ + -p read,write + +credhub set-permission \ + -n '/prod/*' \ + -a 'dev-team' \ + -p read +``` + +### 4. Regular Rotation + +```bash +# Rotate passwords +credhub regenerate -n /path/to/password + +# Bulk rotate certificates +credhub bulk-regenerate --signed-by /my-ca +``` + +### 5. Monitor Certificate Expiry + +```bash +# Check certificate expiration +credhub get -n /path/to/cert -j | \ + jq -r '.value.certificate' | \ + openssl x509 -noout -enddate +``` + +## Troubleshooting + +### Connection Issues + +```bash +# Check CredHub API +curl -k https://credhub.example.com:8844/info + +# Verify UAA connectivity +curl -k https://uaa.example.com:8443/info + +# Check client permissions +credhub login --client-name my-client +``` + +### Permission Denied + +```bash +# List permissions +credhub get-permission -n /path + +# Check UAA token +credhub --version # Shows current auth + +# Re-authenticate +credhub logout +credhub login +``` + +### Secret Not Found + +```bash +# Search for secret +credhub find -n prod + +# Check exact path +credhub get -n /full/path/to/secret + +# Verify BOSH interpolation +bosh interpolate manifest.yml \ + --vars-store=credhub +``` + +## CredHub CLI Reference + +Common commands: + +```bash +# Authentication +credhub login +credhub logout + +# Secret operations +credhub get -n +credhub set -n -t -v +credhub delete -n +credhub generate -n -t +credhub regenerate -n + +# Bulk operations +credhub find -n +credhub bulk-regenerate --signed-by + +# Permissions +credhub set-permission -n -a -p +credhub get-permission -n +credhub delete-permission -n -a +``` + +CredHub provides a robust, BOSH-native alternative to Vault for organizations heavily invested in the Cloud Foundry ecosystem. \ No newline at end of file diff --git a/docs/topics/30-secrets-management/index.md b/docs/topics/30-secrets-management/index.md new file mode 100644 index 00000000..b00c8496 --- /dev/null +++ b/docs/topics/30-secrets-management/index.md @@ -0,0 +1,105 @@ +# Secrets Management + +Genesis provides comprehensive secrets management through integration with HashiCorp Vault and VMware CredHub. This section covers everything from basic secret generation to advanced rotation procedures. + +## Topics in This Section + +1. **[Overview](overview.md)** - Introduction to Genesis secrets management +2. **[Vault Integration](vault-integration.md)** - Working with HashiCorp Vault +3. **[Secret Types](secret-types.md)** - Passwords, certificates, SSH keys, and more +4. **[Kit Secrets](kit-secrets.md)** - Defining secrets in kit.yml files +5. **[Rotation Procedures](rotation-procedures.md)** - Rotating credentials safely +6. **[CredHub Support](credhub-support.md)** - Using CredHub as an alternative +7. **[Manual Management](manual-management.md)** - Direct secret manipulation +8. **[Best Practices](best-practices.md)** - Security recommendations + +## Quick Overview + +Genesis automatically manages secrets for your deployments: + +- **Automatic Generation** - Credentials created on first deployment +- **Secure Storage** - Stored in Vault or CredHub +- **Easy Rotation** - Built-in rotation commands +- **Type Safety** - Specific generators for each secret type + +### Common Secret Types + +- **Passwords** - Random strings with configurable complexity +- **SSH Keys** - Public/private key pairs +- **X.509 Certificates** - TLS certificates with CA chains +- **RSA Keys** - For JWT signing and encryption +- **UUIDs** - Unique identifiers + +## Basic Usage + +### View Secrets + +```bash +# List all secrets for an environment +safe tree secret/us-east-1/prod/cf + +# View specific secret +safe get secret/us-east-1/prod/cf/admin_password +``` + +### Rotate Secrets + +```bash +# Rotate specific secret +genesis rotate-secrets us-east-1-prod admin_password + +# Rotate all secrets (careful!) +genesis rotate-secrets us-east-1-prod --all +``` + +### Manual Generation + +```bash +# Generate a password +safe gen secret/us-east-1/prod/cf/custom_password + +# Create SSH key +safe ssh secret/us-east-1/prod/cf/jumpbox_ssh + +# Generate certificate +safe x509 issue secret/us-east-1/prod/cf/web_cert \ + --name example.com \ + --ca secret/us-east-1/prod/cf/ca +``` + +## Integration with Kits + +Kits define required secrets in their `kit.yml`: + +```yaml +credentials: + base: + admin_user: + username: admin + password: random 32 + +certificates: + base: + ca: + valid_for: 10y + server: + valid_for: 1y + names: + - "*.system.${params.base_domain}" + - "*.apps.${params.base_domain}" +``` + +## Security Considerations + +1. **Never commit secrets** to version control +2. **Use strong passwords** - Minimum 16 characters +3. **Rotate regularly** - Especially after personnel changes +4. **Limit access** - Use Vault policies +5. **Audit usage** - Enable Vault audit logs + +## Getting Started + +- New to secrets? Start with the [Overview](overview.md) +- Setting up Vault? See [Vault Integration](vault-integration.md) +- Need to rotate? Check [Rotation Procedures](rotation-procedures.md) +- Using CredHub? Read [CredHub Support](credhub-support.md) \ No newline at end of file diff --git a/docs/topics/30-secrets-management/kit-secrets.md b/docs/topics/30-secrets-management/kit-secrets.md new file mode 100644 index 00000000..a885895a --- /dev/null +++ b/docs/topics/30-secrets-management/kit-secrets.md @@ -0,0 +1,478 @@ +# Kit Secrets Definition + +This guide explains how to define secrets in Genesis kit.yml files. Kit authors use these definitions to specify what secrets their deployments need. + +## Overview + +Kits define secrets in three main sections of `kit.yml`: + +1. **credentials** - Passwords, keys, and other generated secrets +2. **certificates** - X.509 certificates and CAs +3. **provided** - User-supplied secrets + +## Credentials Section + +### Basic Structure + +```yaml +credentials: + : + : +``` + +### Simple Credentials + +```yaml +credentials: + base: + # Simple password + admin_password: random 32 + + # Password with options + db/password: "random 64 fmt base64" + + # SSH key + jumpbox/ssh: ssh 2048 + + # RSA key + jwt/signing_key: rsa 4096 + + # UUID + consul/gossip: uuid +``` + +### Complex Credentials + +For secrets with multiple components: + +```yaml +credentials: + base: + # Multiple keys under one path + nats: + username: nats + password: random 32 + + # Nested structure + db/admin: + username: admin + password: "random 40 allowed-chars A-Za-z0-9" +``` + +### Credential Parameters + +#### Random Passwords + +```yaml +"random [options]" + +Options: +- fmt base64|bcrypt # Encoding format +- allowed-chars # Character set +- fixed # Prevent rotation +- at # Store at specific key + +Examples: +- "random 16" # 16-char password +- "random 32 fmt base64" # Base64 encoded +- "random 8 allowed-chars 0-9" # Numeric only +- "random 40 fixed" # Non-rotating +``` + +#### SSH Keys + +```yaml +"ssh [fixed]" + +Examples: +- "ssh 2048" # 2048-bit RSA key +- "ssh 4096 fixed" # Non-rotating 4096-bit key +``` + +#### RSA Keys + +```yaml +"rsa [fixed]" + +Examples: +- "rsa 2048" # 2048-bit RSA key +- "rsa 4096 fixed" # Non-rotating 4096-bit key +``` + +#### DH Parameters + +```yaml +"dhparam [fixed]" + +Examples: +- "dhparam 2048" # 2048-bit DH params +- "dhparam 4096 fixed" # Non-rotating 4096-bit +``` + +#### UUIDs + +```yaml +"uuid [version] [namespace name ]" + +Examples: +- "uuid" # Random v4 UUID +- "uuid v4" # Explicit v4 +- "uuid v5 namespace dns name example.com" # Deterministic +``` + +## Certificates Section + +### Basic Structure + +```yaml +certificates: + : + : + : + +``` + +### Certificate Properties + +```yaml +certificates: + base: + certs: + ca: + is_ca: true + valid_for: 10y + + server: + valid_for: 1y + names: + - "*.system.cf.example.com" + - "*.apps.cf.example.com" + - "10.0.0.5" + signed_by: certs/ca +``` + +### Certificate Parameters + +- **is_ca**: Boolean, marks as CA certificate +- **valid_for**: Duration (e.g., `1y`, `90d`, `8760h`) +- **names**: List of DNS names and IPs +- **signed_by**: Path to signing CA (optional) + +### Using Parameters + +Reference environment parameters: + +```yaml +certificates: + base: + haproxy/ssl: + server: + valid_for: "${params.cert_validity}" + names: "${params.haproxy_domains}" +``` + +### Certificate Hierarchies + +```yaml +certificates: + base: + # Root CA + root/ca: + is_ca: true + valid_for: 20y + + # Intermediate CA + intermediate/ca: + is_ca: true + valid_for: 10y + signed_by: root/ca + + # Server certs + internal/server: + valid_for: 1y + signed_by: intermediate/ca + names: ["internal.example.com"] +``` + +## Provided Section + +### Basic Structure + +```yaml +provided: + : + : + type: generic + keys: + : + +``` + +### Provided Secret Properties + +```yaml +provided: + base: + external/oauth: + type: generic + keys: + client_id: + type: string + prompt: "Enter OAuth Client ID" + + client_secret: + type: string + sensitive: true + prompt: "Enter OAuth Client Secret" + + private_key: + type: string + multiline: true + prompt: "Paste private key (Ctrl-D when done)" +``` + +### Key Properties + +- **type**: Always `string` currently +- **sensitive**: Hide input (boolean) +- **multiline**: Accept multiple lines (boolean) +- **prompt**: Message shown to user +- **fixed**: Prevent regeneration (boolean) + +## Feature-Based Organization + +### Conditional Secrets + +Secrets can be organized by feature: + +```yaml +credentials: + # Always generated + base: + admin_password: random 32 + + # Only with postgres feature + postgres: + db/password: random 32 + db/username: cfdb + + # Only with mysql feature + mysql: + db/password: random 40 + db/root_password: random 40 + +certificates: + # Only with haproxy feature + haproxy: + haproxy/ssl: + ca: + is_ca: true + valid_for: 10y + server: + valid_for: 1y + names: ["*.${params.system_domain}"] +``` + +### Feature Activation + +In environment file: + +```yaml +kit: + features: + - postgres # Activates postgres secrets + - haproxy # Activates haproxy certificates +``` + +## Advanced Patterns + +### Shared CAs + +```yaml +certificates: + base: + # Shared CA for all features + shared/ca: + ca: + is_ca: true + valid_for: 10y + + routing: + # Uses shared CA + router/ssl: + server: + signed_by: shared/ca + valid_for: 1y + names: ["*.router.${params.base_domain}"] + + uaa: + # Also uses shared CA + uaa/ssl: + server: + signed_by: shared/ca + valid_for: 1y + names: ["uaa.${params.system_domain}"] +``` + +### Computed Secrets + +Some kits compute secrets from others: + +```yaml +credentials: + base: + # Base components + db/username: cfdb + db/password: random 32 + + # Computed in manifest + # db/uri: postgres://cfdb:password@host:5432/cf +``` + +### Secret Groups + +Organize related secrets: + +```yaml +credentials: + shield: + # Agent credentials + agent/shield: + username: shield-agent + password: random 32 + + # Backup target credentials + backups/s3: + access_key: "provided" + secret_key: "provided" + + # Encryption key + backups/cipher: + key: "random 32 fmt base64" +``` + +## Validation + +### Required Fields + +Genesis validates secret definitions: + +```yaml +# This will fail - certificates need names +certificates: + base: + bad/cert: + server: + valid_for: 1y + # Missing: names +``` + +### Type Checking + +```yaml +# This will fail - invalid secret type +credentials: + base: + bad/secret: "invalid-type 32" +``` + +## Best Practices + +### 1. Use Clear Paths + +```yaml +# Good - clear purpose +credentials: + base: + nats/server_password: random 32 + nats/client_password: random 32 + +# Bad - ambiguous +credentials: + base: + password1: random 32 + password2: random 32 +``` + +### 2. Group Related Secrets + +```yaml +credentials: + base: + # Group by component + diego/ssh: + private_key: "rsa 2048" + diego/bbs/encryption: + key: "random 32 fmt base64" + diego/rep/password: random 32 +``` + +### 3. Document Provided Secrets + +```yaml +provided: + newrelic: + monitoring/newrelic: + keys: + license_key: + prompt: | + Enter New Relic License Key + (Get from: https://rpm.newrelic.com/accounts/xxx) +``` + +### 4. Use Parameters + +```yaml +# In kit.yml +certificates: + base: + web/ssl: + server: + valid_for: "${params.cert_validity_period}" + names: "${params.web_domains}" + +# Allows environment customization +params: + cert_validity_period: 90d + web_domains: + - example.com + - www.example.com +``` + +### 5. Consider Rotation + +```yaml +credentials: + base: + # Rotatable + app/password: random 32 + + # Fixed - external dependency + legacy/api_key: "random 40 fixed" +``` + +## Testing Secret Definitions + +### Manual Testing + +```bash +# Deploy to test environment +genesis new test-secrets +genesis deploy test-secrets + +# Check generated secrets +safe tree secret/test/secrets +``` + +### Validation Commands + +```bash +# Validate kit +genesis kit validate + +# Check specific feature +genesis new test --features haproxy +genesis check test +``` + +Understanding kit secret definitions helps you create secure, maintainable Genesis kits with proper credential management. \ No newline at end of file diff --git a/docs/topics/30-secrets-management/manual-management.md b/docs/topics/30-secrets-management/manual-management.md new file mode 100644 index 00000000..6879067e --- /dev/null +++ b/docs/topics/30-secrets-management/manual-management.md @@ -0,0 +1,456 @@ +# Manual Secret Management + +While Genesis automates most secret operations, sometimes you need direct control. This guide covers manual secret management techniques for special cases and troubleshooting. + +## Direct Vault Access + +### Using Safe CLI + +The `safe` command provides direct Vault access: + +```bash +# Target Vault +safe target prod https://vault.example.com:8200 +safe auth + +# Basic operations +safe set secret/path key=value +safe get secret/path +safe delete secret/path +safe move secret/old/path secret/new/path +safe copy secret/source secret/dest +``` + +### Complex Secret Operations + +```bash +# Set multiple keys +safe set secret/us-east-1/prod/cf/database \ + username=dbadmin \ + password=complex-password \ + host=db.example.com \ + port=5432 + +# Set from file +safe set secret/path/cert value=@/path/to/cert.pem + +# Set JSON data +safe set secret/path/config value='{"key": "value", "foo": "bar"}' + +# Interactive mode +safe set secret/path/password +# Prompts for value (hidden) +``` + +## Viewing and Exporting Secrets + +### Individual Secrets + +```bash +# View specific key +safe get secret/us-east-1/prod/cf/admin_password + +# Get just the value +safe get secret/us-east-1/prod/cf/admin_password:value + +# Format output +safe get secret/path --format json +safe get secret/path --format yaml +``` + +### Bulk Operations + +```bash +# List all secrets +safe tree secret/us-east-1/prod/cf + +# Export entire tree +safe export secret/us-east-1/prod/cf > cf-secrets.json + +# Export with paths +safe export --all secret/us-east-1/prod > all-secrets.json + +# Find secrets by pattern +safe find secret/us-east-1 | grep password +``` + +## Manual Generation + +### Passwords + +```bash +# Generate password in Vault +safe gen secret/path/password + +# With specific length +safe gen secret/path/password length=40 + +# Custom parameters +safe gen secret/path/password \ + length=32 \ + policy=printable + +# Generate locally and set +PASSWORD=$(openssl rand -base64 32) +safe set secret/path value="$PASSWORD" +``` + +### SSH Keys + +```bash +# Generate SSH key +safe ssh secret/path/ssh-key + +# With specific size +safe ssh secret/path/ssh-key size=4096 + +# Extract public key +safe get secret/path/ssh-key:public > id_rsa.pub + +# Generate locally +ssh-keygen -t rsa -b 4096 -f temp_key -N "" +safe set secret/path/ssh \ + private=@temp_key \ + public=@temp_key.pub +rm temp_key temp_key.pub +``` + +### Certificates + +```bash +# Create CA +safe x509 ca secret/path/ca \ + --common-name "Genesis CA" \ + --valid-for 10y + +# Issue certificate +safe x509 issue secret/path/server \ + --ca secret/path/ca \ + --common-name server.example.com \ + --alternative-names "*.example.com,10.0.0.5" \ + --valid-for 1y + +# Self-signed certificate +safe x509 self-signed secret/path/self \ + --common-name test.example.com \ + --valid-for 90d +``` + +### RSA Keys + +```bash +# Generate RSA key pair +openssl genrsa -out private.pem 4096 +openssl rsa -in private.pem -pubout -out public.pem + +# Store in Vault +safe set secret/path/rsa \ + private=@private.pem \ + public=@public.pem + +# Clean up +rm private.pem public.pem +``` + +## Fixing Secret Issues + +### Wrong Format + +```bash +# Certificate stored incorrectly +safe get secret/path/cert + +# Fix by reformatting +CERT=$(safe get secret/path/cert:value) +safe set secret/path/cert \ + cert="$CERT" \ + key=@private.key \ + ca=@ca.crt +``` + +### Missing Components + +```bash +# SSH key missing public component +PRIVATE=$(safe get secret/path/ssh:private) + +# Generate public from private +echo "$PRIVATE" > temp.key +chmod 600 temp.key +ssh-keygen -y -f temp.key > temp.pub + +# Update secret +safe set secret/path/ssh \ + private="$PRIVATE" \ + public=@temp.pub + +rm temp.key temp.pub +``` + +### Corrupted Secrets + +```bash +# Backup current state +safe export secret/path > backup.json + +# Check for issues +safe get secret/path | jq . + +# Restore from backup if needed +safe import < backup.json +``` + +## Path Management + +### Moving Secrets + +```bash +# Move single secret +safe move secret/old/path secret/new/path + +# Move entire tree +safe export secret/old/tree > temp.json +safe import --at secret/new/tree < temp.json +safe delete secret/old/tree --recursive +``` + +### Copying Between Environments + +```bash +# Copy from dev to staging +safe export secret/dev/cf > dev-secrets.json + +# Modify paths +sed 's|secret/dev|secret/staging|g' dev-secrets.json > staging-secrets.json + +# Import to staging +safe import < staging-secrets.json +``` + +### Cleaning Up + +```bash +# Delete single secret +safe delete secret/path/to/delete + +# Delete with confirmation +safe delete secret/important/path --prompt + +# Recursive delete +safe delete secret/entire/tree --recursive + +# Dry run +safe delete secret/path --recursive --dry-run +``` + +## Advanced Techniques + +### Templating Secrets + +```bash +#!/bin/bash +# Generate environment-specific secrets + +ENVS="dev staging prod" +TEMPLATE='{ + "admin_password": "$(safe gen password)", + "api_key": "$(uuidgen)", + "deployed_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)" +}' + +for env in $ENVS; do + eval "echo '$TEMPLATE'" | \ + jq . | \ + safe import --at "secret/$env/cf/metadata" +done +``` + +### Bulk Updates + +```bash +#!/bin/bash +# Update all passwords in an environment + +BASE_PATH="secret/us-east-1/prod/cf" + +# Find all passwords +safe find "$BASE_PATH" | grep password$ | while read -r path; do + echo "Rotating: $path" + safe gen "$path" length=32 +done +``` + +### Secret Validation + +```bash +#!/bin/bash +# Validate secret structure + +validate_secret() { + local path=$1 + local required_keys=$2 + + for key in $required_keys; do + if ! safe exists "$path:$key"; then + echo "ERROR: Missing $key in $path" + return 1 + fi + done + + echo "OK: $path has all required keys" + return 0 +} + +# Check database secret +validate_secret "secret/prod/cf/db" "username password host port" + +# Check certificate +validate_secret "secret/prod/cf/cert" "cert key ca" +``` + +## Integration Scripts + +### Pre-deployment Validation + +```bash +#!/bin/bash +# check-secrets.sh - Run before deployment + +ENV=$1 +BASE="secret/$ENV/cf" + +echo "Checking secrets for $ENV..." + +# Required secrets +REQUIRED=( + "admin_password" + "db/password" + "nats/password" + "router/ca" +) + +MISSING=() +for secret in "${REQUIRED[@]}"; do + if ! safe exists "$BASE/$secret"; then + MISSING+=("$secret") + fi +done + +if [ ${#MISSING[@]} -ne 0 ]; then + echo "ERROR: Missing secrets:" + printf ' - %s\n' "${MISSING[@]}" + exit 1 +fi + +echo "All required secrets present" +``` + +### External Service Integration + +```bash +#!/bin/bash +# Sync external API keys + +# Fetch from external service +API_KEY=$(aws secretsmanager get-secret-value \ + --secret-id prod/api-key \ + --query SecretString \ + --output text) + +# Store in Vault +safe set secret/us-east-1/prod/cf/external/aws \ + api_key="$API_KEY" \ + updated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" +``` + +## Debugging + +### Trace Secret Usage + +```bash +# Find where a secret is used +SECRET_NAME="admin_password" +ENV="us-east-1-prod" + +# Check manifest +genesis manifest $ENV | grep -n "$SECRET_NAME" + +# Check generated manifest +bosh -d $ENV-cf manifest | grep -n "$SECRET_NAME" + +# Check runtime config +bosh runtime-config | grep -n "$SECRET_NAME" +``` + +### Audit Access + +```bash +# Enable audit logging +vault audit enable file file_path=/var/log/vault-audit.log + +# Check who accessed a secret +grep "secret/us-east-1/prod" /var/log/vault-audit.log | \ + jq -r '[.time, .auth.display_name, .request.path] | @csv' +``` + +## Best Practices + +### 1. Document Manual Changes + +```bash +# Add metadata when manually setting +safe set secret/path/manual-secret \ + value="special-value" \ + created_by="$USER" \ + created_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + reason="Required for legacy system X" +``` + +### 2. Use Atomic Operations + +```bash +# Update multiple related secrets together +cat < "backup-$(date +%Y%m%d-%H%M%S).json" + +# Verify backup +jq . backup-*.json +``` + +### 4. Test Changes + +```bash +# Test in lower environment first +safe copy secret/prod/setting secret/dev/setting-test +# Test deployment with dev environment +# If successful, apply to prod +``` + +### 5. Clean Up Temporary Files + +```bash +# Use trap for cleanup +cleanup() { + rm -f /tmp/temp-key-* +} +trap cleanup EXIT + +# Work with temporary files +TEMP_KEY=$(mktemp /tmp/temp-key-XXXXXX) +# ... use temp file ... +# Cleanup happens automatically +``` + +Manual secret management gives you full control when Genesis automation isn't sufficient, but use it judiciously to maintain security and consistency. \ No newline at end of file diff --git a/docs/topics/30-secrets-management/overview.md b/docs/topics/30-secrets-management/overview.md new file mode 100644 index 00000000..2f7836f5 --- /dev/null +++ b/docs/topics/30-secrets-management/overview.md @@ -0,0 +1,243 @@ +# Secrets Management Overview + +Genesis integrates deeply with secret management systems to handle credentials, certificates, and other sensitive data required by your deployments. This overview explains the concepts and architecture. + +## Why Secrets Management? + +Modern infrastructure requires numerous credentials: +- Database passwords +- API keys +- SSH keys for access +- TLS certificates +- Service account credentials +- Encryption keys + +Managing these manually is: +- **Error-prone** - Easy to expose or lose secrets +- **Time-consuming** - Generating and distributing takes effort +- **Risky** - Rotation requires coordination +- **Difficult to audit** - Who has access to what? + +## How Genesis Handles Secrets + +Genesis automates secret management through: + +### 1. Automatic Generation + +When you deploy an environment, Genesis: +- Detects required secrets from the kit +- Checks if they already exist in Vault +- Generates missing secrets automatically +- Stores them securely + +### 2. Consistent Paths + +Secrets follow predictable paths: +``` +/secret/// + +Example: +/secret/us/east/1/prod/cf/admin_password +``` + +### 3. Manifest Integration + +Genesis injects secrets during manifest generation: +```yaml +# In manifest template +admin_password: ((vault "secret/path:password")) + +# Genesis replaces with actual value during deployment +admin_password: "GeneratedSecurePassword123!" +``` + +### 4. Rotation Support + +Built-in commands for credential rotation: +```bash +genesis rotate-secrets my-env admin_password +``` + +## Supported Secret Stores + +### HashiCorp Vault (Primary) + +The preferred secret backend: +- **Encrypted storage** - All secrets encrypted at rest +- **Access control** - Fine-grained policies +- **Audit logging** - Track all access +- **High availability** - Clustered deployment +- **Secret engines** - Multiple backend types + +### VMware CredHub + +Alternative for Cloud Foundry environments: +- **BOSH integration** - Native BOSH support +- **Credential types** - Structured secret types +- **ACLs** - Access control lists +- **Interpolation** - Runtime secret injection + +## Secret Lifecycle + +### Generation Phase + +1. **Kit Definition** - Kit specifies required secrets +2. **Deployment Check** - Genesis checks what's missing +3. **Automatic Generation** - Creates missing secrets +4. **Secure Storage** - Saves to Vault/CredHub + +### Usage Phase + +1. **Manifest Generation** - Genesis retrieves secrets +2. **Injection** - Replaces placeholders +3. **Deployment** - BOSH uses secrets +4. **Runtime** - Applications access as needed + +### Rotation Phase + +1. **Identify** - Determine what needs rotation +2. **Generate** - Create new credentials +3. **Update** - Store in secret backend +4. **Deploy** - Apply to infrastructure +5. **Verify** - Ensure services still work + +## Secret Types + +### Passwords +```yaml +credentials: + base: + db/password: random 32 +``` +- Random generation +- Configurable length +- Character set control + +### SSH Keys +```yaml +credentials: + base: + jumpbox/ssh: ssh 2048 +``` +- RSA key pairs +- Configurable key size +- Public/private keys + +### X.509 Certificates +```yaml +certificates: + base: + ca: + valid_for: 10y + server: + valid_for: 1y + names: ["*.example.com"] +``` +- Certificate authorities +- Server/client certificates +- Automatic renewal warnings + +### RSA Keys +```yaml +credentials: + base: + jwt/signing: rsa 4096 +``` +- JWT signing +- Encryption keys +- Configurable key size + +## Security Architecture + +### Vault Policies + +Control access by path: +```hcl +# Dev team policy +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete"] +} + +# Prod read-only +path "secret/prod/*" { + capabilities = ["read"] +} +``` + +### Network Security + +- **TLS everywhere** - Encrypted communications +- **mTLS** - Mutual TLS for authentication +- **Network isolation** - Vault in secure subnet +- **Firewall rules** - Restrict access + +### Operational Security + +- **Regular rotation** - Scheduled credential updates +- **Audit logs** - Track all secret access +- **Backup procedures** - Encrypted secret backups +- **Break-glass access** - Emergency procedures + +## Common Patterns + +### Shared Secrets + +Some secrets shared across environments: +```yaml +# Shared CA certificate +/secret/shared/ca-cert + +# Environment-specific servers +/secret/dev/cf/server-cert # Signed by shared CA +/secret/prod/cf/server-cert # Signed by shared CA +``` + +### External Secrets + +Integrating existing secrets: +```yaml +provided: + base: + external/api: + keys: + - api_key + - api_secret +``` + +### Multi-Tenant Isolation + +Separate secrets by tenant: +``` +/secret/tenant-a/prod/cf/ +/secret/tenant-b/prod/cf/ +``` + +## Benefits + +### For Operators + +- **No manual generation** - Automated secret creation +- **Consistent storage** - Predictable locations +- **Easy rotation** - Simple commands +- **Audit trail** - Who accessed what + +### For Security Teams + +- **Encrypted storage** - Secrets never in plaintext +- **Access control** - Policy-based permissions +- **Compliance** - Audit logs for regulations +- **Rotation tracking** - Know secret ages + +### For Developers + +- **No hardcoded secrets** - Everything from Vault +- **Environment isolation** - Dev can't access prod +- **Self-service** - Generate dev secrets easily +- **Integration support** - SDKs for all languages + +## Next Steps + +- Learn about [Vault Integration](vault-integration.md) +- Understand [Secret Types](secret-types.md) in detail +- Master [Rotation Procedures](rotation-procedures.md) +- Review [Best Practices](best-practices.md) \ No newline at end of file diff --git a/docs/topics/30-secrets-management/rotation-procedures.md b/docs/topics/30-secrets-management/rotation-procedures.md new file mode 100644 index 00000000..d7ab803f --- /dev/null +++ b/docs/topics/30-secrets-management/rotation-procedures.md @@ -0,0 +1,463 @@ +# Secret Rotation Procedures + +Regular secret rotation is crucial for maintaining security. This guide covers how to safely rotate credentials in Genesis deployments. + +## Overview + +Secret rotation involves: +1. Generating new credentials +2. Updating Vault +3. Deploying with new secrets +4. Verifying services work +5. Cleaning up old credentials + +## Using Genesis Rotate Command + +### Basic Rotation + +```bash +# Rotate specific secret +genesis rotate-secrets my-env admin_password + +# Rotate multiple secrets +genesis rotate-secrets my-env admin_password nats_password + +# Rotate all secrets (use with caution!) +genesis rotate-secrets my-env --all +``` + +### What Gets Rotated + +The command rotates secrets marked as rotatable: +- Passwords (unless marked `fixed`) +- SSH keys (unless marked `fixed`) +- Certificates (regenerated with same parameters) +- Other generated credentials + +Not rotated: +- Secrets marked with `fixed` +- User-provided secrets +- CA certificates (by default) + +## Planning Rotation + +### 1. Identify What to Rotate + +```bash +# List all secrets +safe tree secret/us-east-1/prod/cf + +# Check secret age +safe get secret/us-east-1/prod/cf/admin_password | \ + safe x509 show --json | jq .not_before + +# Find old passwords +genesis info my-env --secrets +``` + +### 2. Assess Impact + +Consider: +- **Service dependencies** - What uses this credential? +- **Downtime requirements** - Can services handle rotation? +- **External systems** - Any hardcoded references? +- **Backup systems** - Will backups still work? + +### 3. Create Rotation Plan + +```markdown +## Rotation Plan - Production CF + +### Phase 1: Non-Critical (No Downtime) +- [ ] admin_password +- [ ] smoke_test_password +- [ ] autoscaler_password + +### Phase 2: Internal Services (Brief Downtime) +- [ ] nats_password +- [ ] router_password +- [ ] bbs_password + +### Phase 3: Critical (Maintenance Window) +- [ ] database_password +- [ ] blobstore_password +``` + +## Rotation Procedures by Type + +### Password Rotation + +#### Simple Password + +```bash +# 1. Rotate the password +genesis rotate-secrets my-env admin_password + +# 2. Deploy immediately +genesis deploy my-env + +# 3. Test login with new password +cf login -a https://api.system.example.com +``` + +#### Database Password + +Requires coordination: + +```bash +# 1. Check current connections +bosh -d my-env-cf ssh database/0 \ + 'sudo -u vcap psql -c "SELECT * FROM pg_stat_activity"' + +# 2. Rotate password +genesis rotate-secrets my-env db/password + +# 3. Deploy database first +genesis deploy my-env --skip-unchanged + +# 4. Update applications +genesis deploy my-env + +# 5. Verify connectivity +genesis do my-env -- run-errand smoke-tests +``` + +### SSH Key Rotation + +```bash +# 1. Generate new key +genesis rotate-secrets my-env jumpbox/ssh + +# 2. Deploy to update authorized_keys +genesis deploy my-env + +# 3. Test new key +safe get secret/path/jumpbox/ssh:private > new_key +chmod 600 new_key +ssh -i new_key vcap@jumpbox + +# 4. Remove old key from local systems +rm ~/.ssh/old_jumpbox_key +``` + +### Certificate Rotation + +#### Server Certificate + +```bash +# 1. Check expiration +safe x509 expires secret/us-east-1/prod/cf/haproxy/ssl + +# 2. Rotate certificate +genesis rotate-secrets my-env haproxy/ssl + +# 3. Deploy with new cert +genesis deploy my-env + +# 4. Verify certificate +echo | openssl s_client -connect haproxy.example.com:443 2>/dev/null | \ + openssl x509 -noout -dates +``` + +#### CA Certificate Rotation + +CA rotation is complex - requires careful planning: + +```bash +# 1. Create new CA alongside old +safe x509 issue secret/path/new-ca \ + --ca \ + --valid-for 10y + +# 2. Sign new certificates with new CA +genesis rotate-secrets my-env server/cert \ + --sign-with secret/path/new-ca + +# 3. Deploy with both CAs trusted +# 4. Rotate all dependent certificates +# 5. Remove old CA +``` + +## Advanced Rotation Scenarios + +### Zero-Downtime Password Rotation + +For services supporting multiple credentials: + +```yaml +# 1. Add new credential +credentials: + base: + db/password: random 32 + db/password_new: random 32 + +# 2. Deploy with both passwords +# 3. Switch to new password +# 4. Remove old password +``` + +### Rotating External Integrations + +```bash +# 1. Create new credentials in external system +# AWS example: +aws iam create-access-key --user-name genesis-user + +# 2. Update in Vault +safe set secret/us-east-1/prod/cf/aws \ + access_key=NEW_ACCESS_KEY \ + secret_key=NEW_SECRET_KEY + +# 3. Deploy +genesis deploy my-env + +# 4. Verify external access +genesis do my-env -- test-s3-access + +# 5. Delete old credentials +aws iam delete-access-key \ + --user-name genesis-user \ + --access-key-id OLD_ACCESS_KEY +``` + +### Coordinated Multi-Environment Rotation + +```bash +#!/bin/bash +# Rotate shared database password across environments + +ENVIRONMENTS="dev staging prod" +SECRET="db/password" + +# 1. Generate new password +NEW_PASS=$(safe gen password) + +# 2. Update all environments +for env in $ENVIRONMENTS; do + safe set secret/$env/cf/$SECRET value="$NEW_PASS" +done + +# 3. Deploy in order +for env in $ENVIRONMENTS; do + genesis deploy $env + genesis do $env -- run-errand smoke-tests +done +``` + +## Monitoring and Verification + +### Pre-Rotation Checks + +```bash +# Check service health +bosh -d my-env-cf vms --vitals + +# Verify current credentials work +genesis do my-env -- run-errand smoke-tests + +# Backup current secrets +safe export secret/us-east-1/prod/cf > backup-before-rotation.json +``` + +### Post-Rotation Verification + +```bash +# 1. Check deployment health +bosh -d my-env-cf vms --vitals + +# 2. Run smoke tests +genesis do my-env -- run-errand smoke-tests + +# 3. Check application logs +bosh -d my-env-cf logs api/0 --follow + +# 4. Verify external integrations +curl -H "Authorization: Bearer $(safe get secret/path:token)" \ + https://api.example.com/health +``` + +## Rollback Procedures + +### Immediate Rollback + +If rotation causes issues: + +```bash +# 1. Restore from backup +safe import < backup-before-rotation.json + +# 2. Redeploy with old secrets +genesis deploy my-env + +# 3. Verify services restored +genesis do my-env -- run-errand smoke-tests +``` + +### Partial Rollback + +For specific secrets: + +```bash +# Get old value from backup +OLD_VALUE=$(jq -r '.admin_password' backup-before-rotation.json) + +# Restore specific secret +safe set secret/us-east-1/prod/cf/admin_password value="$OLD_VALUE" + +# Redeploy +genesis deploy my-env +``` + +## Automation + +### Scheduled Rotation Script + +```bash +#!/bin/bash +# rotate-passwords.sh - Run monthly via cron + +set -e + +REPO="/home/genesis/cf-deployments" +ENVIRONMENTS="dev staging prod" +PASSWORDS="admin_password smoke_test_password autoscaler_password" + +cd $REPO + +for env in $ENVIRONMENTS; do + echo "Rotating passwords for $env" + + # Rotate passwords + genesis rotate-secrets $env $PASSWORDS + + # Deploy + genesis deploy $env --yes + + # Test + if ! genesis do $env -- run-errand smoke-tests; then + echo "ERROR: Smoke tests failed for $env" + exit 1 + fi + + echo "Successfully rotated $env" +done +``` + +### Certificate Expiration Monitoring + +```bash +#!/bin/bash +# check-certs.sh - Run daily + +THRESHOLD_DAYS=30 + +# Find expiring certificates +for env in $(genesis list); do + certs=$(safe find secret/$env | grep cert$) + + for cert in $certs; do + expires=$(safe x509 expires $cert --json | jq -r .not_after) + expires_epoch=$(date -d "$expires" +%s) + now_epoch=$(date +%s) + days_left=$(( ($expires_epoch - $now_epoch) / 86400 )) + + if [ $days_left -lt $THRESHOLD_DAYS ]; then + echo "WARNING: $cert expires in $days_left days" + # Send alert + fi + done +done +``` + +## Best Practices + +### 1. Regular Rotation Schedule + +- **Passwords**: Every 90 days +- **SSH Keys**: Every 180 days +- **Server Certificates**: 30 days before expiry +- **CA Certificates**: 1 year before expiry + +### 2. Test in Lower Environments + +```bash +# Test rotation procedure +genesis rotate-secrets dev admin_password +genesis deploy dev + +# If successful, proceed to staging and prod +``` + +### 3. Document External Dependencies + +```yaml +# In environment file comments +# admin_password used by: +# - CF CLI admin scripts +# - Monitoring system (update manually) +# - Backup scripts (auto-updated) +``` + +### 4. Use Maintenance Windows + +For critical rotations: +1. Schedule maintenance window +2. Notify users +3. Perform rotation +4. Verify thoroughly +5. Document completion + +### 5. Maintain Audit Trail + +```bash +# Before rotation +safe get secret/path | jq > audit/secret-before-$(date +%Y%m%d).json + +# After rotation +genesis rotate-secrets my-env secret-name | tee audit/rotation-$(date +%Y%m%d).log +``` + +## Troubleshooting + +### Service Won't Start + +```bash +# Check logs for auth errors +bosh -d my-env-cf logs failing-job/0 + +# Verify secret was rotated +safe get secret/path/to/password + +# Ensure deployment completed +bosh -d my-env-cf task +``` + +### External Integration Broken + +```bash +# Verify new credential format +safe get secret/path/api_key + +# Test credential manually +curl -H "Authorization: $(safe get secret/path:key)" \ + https://api.example.com + +# Check for hardcoded values +grep -r "old-password" /var/vcap/jobs/ +``` + +### Rollback Failed + +```bash +# Force redeploy with manifest +genesis manifest my-env > manifest.yml +bosh -d my-env-cf deploy manifest.yml \ + --vars-store=/dev/null \ + --recreate + +# Manual secret injection if needed +bosh -d my-env-cf ssh job/0 +# Update config files manually +``` + +Regular, well-planned rotation keeps your Genesis deployments secure while minimizing operational risk. \ No newline at end of file diff --git a/docs/topics/30-secrets-management/secret-types.md b/docs/topics/30-secrets-management/secret-types.md new file mode 100644 index 00000000..813bbbb5 --- /dev/null +++ b/docs/topics/30-secrets-management/secret-types.md @@ -0,0 +1,434 @@ +# Secret Types + +Genesis supports various types of secrets for different use cases. Each type has specific generation parameters and storage formats. + +## Password Secrets + +### Basic Passwords + +Simple random password generation: + +```yaml +credentials: + base: + admin_password: random 32 +``` + +Generates a 32-character random password. + +### Advanced Password Options + +```yaml +credentials: + base: + db/password: + password: "random 64 fmt base64" + + api/key: + key: "random 40 allowed-chars a-zA-Z0-9_-" + + simple/pin: + pin: "random 6 allowed-chars 0-9" +``` + +Parameters: +- **Length**: Number of characters (e.g., `32`, `64`) +- **Format**: `fmt base64` for base64 encoding +- **Allowed chars**: Specify character set +- **Fixed**: Add `fixed` to prevent rotation + +### Password Storage + +Stored as simple key-value: +``` +secret/us-east-1/prod/cf/admin_password +└── value: "GeneratedPassword123!" +``` + +## SSH Keys + +### Standard SSH Keys + +```yaml +credentials: + base: + jumpbox/ssh: ssh 2048 + bastion/ssh: ssh 4096 fixed +``` + +Generates RSA keypair with specified bit size. + +### SSH Key Storage + +Stored with public and private keys: +``` +secret/us-east-1/prod/cf/jumpbox/ssh +├── private: "-----BEGIN RSA PRIVATE KEY-----..." +├── public: "ssh-rsa AAAAB3NzaC1yc2EA..." +├── fingerprint: "SHA256:..." +└── format: "openssh" +``` + +### Using SSH Keys + +```bash +# Extract private key +safe get secret/path/to/ssh:private > id_rsa +chmod 600 id_rsa + +# Get public key +safe get secret/path/to/ssh:public > id_rsa.pub + +# SSH using the key +ssh -i id_rsa user@host +``` + +## X.509 Certificates + +### Certificate Definition + +```yaml +certificates: + base: + ca: + valid_for: 10y + is_ca: true + + server: + valid_for: 1y + names: + - "*.system.cf.example.com" + - "*.apps.cf.example.com" + - "10.0.0.5" +``` + +### Certificate Parameters + +- **valid_for**: Duration (e.g., `1y`, `365d`, `8760h`) +- **is_ca**: Boolean for CA certificates +- **names**: DNS names and IPs (SAN entries) +- **signed_by**: Path to signing CA + +### Advanced Certificate Options + +```yaml +certificates: + haproxy: + ssl/ca: + is_ca: true + valid_for: "${params.ca_validity_period}" + + ssl/server: + signed_by: ssl/ca + names: "${params.haproxy_domains}" + valid_for: 90d + + mtls/client: + signed_by: ssl/ca + names: ["client.internal"] + valid_for: 30d +``` + +### Certificate Storage + +``` +secret/us-east-1/prod/cf/ssl/server +├── cert: "-----BEGIN CERTIFICATE-----..." +├── key: "-----BEGIN RSA PRIVATE KEY-----..." +├── ca: "-----BEGIN CERTIFICATE-----..." +├── combined: "cert + key concatenated" +└── chain: "cert + ca concatenated" +``` + +### Certificate Operations + +```bash +# View certificate details +safe x509 show secret/path/to/cert + +# Validate certificate +safe x509 validate secret/path/to/cert \ + --ca secret/path/to/ca + +# Check expiration +safe x509 expires secret/path/to/cert +``` + +## RSA Keys + +### RSA Key Generation + +```yaml +credentials: + base: + jwt/signing_key: rsa 4096 + encryption/key: rsa 2048 fixed +``` + +### RSA Key Storage + +``` +secret/us-east-1/prod/cf/jwt/signing_key +├── private: "-----BEGIN RSA PRIVATE KEY-----..." +├── public: "-----BEGIN PUBLIC KEY-----..." +└── format: "pem" +``` + +### Using RSA Keys + +```bash +# Extract for JWT libraries +safe get secret/path/jwt/signing_key:private > jwt.key +safe get secret/path/jwt/signing_key:public > jwt.pub + +# Convert formats if needed +openssl rsa -in jwt.key -pubout -out jwt.pub.pem +``` + +## DH Parameters + +### Diffie-Hellman Parameters + +```yaml +credentials: + base: + nginx/dhparams: dhparam 2048 + haproxy/dhparams: dhparam 4096 fixed +``` + +### DH Storage + +``` +secret/us-east-1/prod/cf/nginx/dhparams +└── value: "-----BEGIN DH PARAMETERS-----..." +``` + +## UUIDs + +### UUID Generation + +```yaml +credentials: + base: + consul/encryption_key: + key: uuid + + bbs/encryption_key: + key: "uuid v4" + + app/instance_id: + id: "uuid v4 namespace dns name app.example.com" +``` + +### UUID Types + +- **v4**: Random UUID (most common) +- **v5**: Namespace-based (deterministic) + +### UUID Storage + +``` +secret/us-east-1/prod/cf/consul/encryption_key +└── key: "550e8400-e29b-41d4-a716-446655440000" +``` + +## User-Provided Secrets + +### Definition + +For secrets that can't be generated: + +```yaml +provided: + base: + external/api: + type: generic + keys: + client_id: + type: string + prompt: "Enter the OAuth client ID" + + client_secret: + type: string + sensitive: true + prompt: "Enter the OAuth client secret" + + private_key: + type: string + multiline: true + prompt: "Paste the private key (Ctrl-D when done)" +``` + +### Provided Secret Parameters + +- **type**: Always `generic` currently +- **sensitive**: Hide input (for passwords) +- **multiline**: Accept multiple lines +- **prompt**: User prompt message +- **fixed**: Prevent regeneration + +## Complex Secret Structures + +### Multi-Component Secrets + +Some secrets have multiple related parts: + +```yaml +# Database with multiple credentials +credentials: + base: + db/admin: + username: "admin" + password: "random 32" + + db/app: + username: "app_user" + password: "random 32" + + db/read_only: + username: "reader" + password: "random 24" +``` + +### Hierarchical Secrets + +Organize related secrets: + +``` +secret/us-east-1/prod/cf/ +├── db/ +│ ├── admin/ +│ │ ├── username +│ │ └── password +│ ├── app/ +│ │ ├── username +│ │ └── password +│ └── uri # Constructed from components +├── nats/ +│ ├── username +│ ├── password +│ └── client_cert/ +│ ├── cert +│ └── key +``` + +## Secret Validation + +### Built-in Validation + +Genesis validates secrets during generation: + +```yaml +# This will fail - names required for non-CA certs +certificates: + base: + bad/cert: + valid_for: 1y + # Missing: names +``` + +### Manual Validation + +```bash +# Check certificate validity +safe x509 validate secret/path/to/cert + +# Verify SSH key +ssh-keygen -l -f <(safe get secret/path/to/ssh:public) + +# Test password complexity +safe get secret/path/to/password | pwscore +``` + +## Secret References + +### Using Parameters + +Reference kit parameters in secret definitions: + +```yaml +# In kit.yml +certificates: + base: + haproxy/ssl: + valid_for: "${params.cert_validity_period}" + names: "${params.haproxy_domains}" + +# In environment file +params: + cert_validity_period: 90d + haproxy_domains: + - haproxy.example.com + - lb.example.com +``` + +### Cross-References + +Reference other secrets: + +```yaml +certificates: + base: + intermediate/ca: + is_ca: true + signed_by: root/ca # References another cert + + server/cert: + signed_by: intermediate/ca + names: ["web.example.com"] +``` + +## Best Practices + +### 1. Use Appropriate Types + +Choose the right secret type: +- Passwords for authentication +- SSH keys for system access +- Certificates for TLS +- RSA keys for signing/encryption + +### 2. Set Proper Lifetimes + +```yaml +certificates: + base: + ca: + valid_for: 10y # Long for CAs + server: + valid_for: 90d # Short for servers +``` + +### 3. Use Fixed Sparingly + +Only use `fixed` for: +- External integrations +- Shared secrets +- Keys that can't be rotated + +### 4. Organize Hierarchically + +```yaml +credentials: + base: + # Group by component + router/password: random 32 + router/ssl/cert: ... + + # Group by function + admin/ui_password: random 32 + admin/api_key: random 64 +``` + +### 5. Document Requirements + +```yaml +provided: + slack: + notifications/webhook: + keys: + url: + prompt: "Enter Slack webhook URL (from https://slack.com/apps/)" +``` + +Understanding these secret types helps you properly secure your Genesis deployments while maintaining operational simplicity. \ No newline at end of file diff --git a/docs/topics/30-secrets-management/vault-integration.md b/docs/topics/30-secrets-management/vault-integration.md new file mode 100644 index 00000000..4473b991 --- /dev/null +++ b/docs/topics/30-secrets-management/vault-integration.md @@ -0,0 +1,492 @@ +# Vault Integration + +Genesis uses HashiCorp Vault as its primary secret storage backend. This guide covers setup, configuration, and operational procedures for Vault with Genesis. + +## Vault Setup + +### Quick Start (Development) + +For testing, use the Genesis built-in Vault: + +```bash +# Start a dev Vault instance +safe init + +# Target and authenticate +safe target dev http://127.0.0.1:8201 +safe auth + +# Verify connection +safe status +``` + +### Production Deployment + +Deploy a production Vault cluster using Genesis: + +```bash +# Initialize Vault deployment repository +genesis init --kit vault my-vault-deployments +cd my-vault-deployments + +# Create production environment +genesis new prod-vault + +# Deploy +genesis deploy prod-vault +``` + +## Connecting Genesis to Vault + +### Environment Variables + +Genesis uses these variables to connect to Vault: + +```bash +# Vault server address +export VAULT_ADDR=https://vault.example.com:8200 + +# Skip TLS verification (dev only!) +export VAULT_SKIP_VERIFY=1 + +# Authentication token (not recommended) +export VAULT_TOKEN=s.abcdef123456 + +# Namespace (Vault Enterprise) +export VAULT_NAMESPACE=genesis +``` + +### Safe CLI Configuration + +The `safe` CLI manages Vault targets: + +```bash +# Add a Vault target +safe target add prod https://vault.example.com:8200 + +# List targets +safe targets + +# Switch targets +safe target prod + +# Authenticate +safe auth +``` + +### Authentication Methods + +#### Token Authentication + +```bash +# Interactive login +safe auth + +# Using existing token +safe auth token +``` + +#### GitHub Authentication + +```bash +# Configure GitHub auth in Vault +safe auth-configure github \ + --organization=myorg \ + --team=ops-team + +# Login with GitHub +safe auth github +``` + +#### LDAP Authentication + +```bash +# Configure LDAP +safe auth-configure ldap \ + --url=ldap://ldap.example.com \ + --binddn="cn=vault,ou=service,dc=example,dc=com" \ + --userdn="ou=users,dc=example,dc=com" + +# Login with LDAP +safe auth ldap +``` + +## Secret Paths + +### Standard Genesis Paths + +Genesis organizes secrets hierarchically: + +``` +/secret/// +├── admin_password +├── ca_cert +├── db/ +│ ├── username +│ └── password +└── ssl/ + ├── cert + ├── key + └── ca +``` + +### Exodus Data + +Shared deployment information: + +``` +/secret/exodus/// +├── url +├── username +├── password +└── ca_cert +``` + +### Custom Paths + +Override default paths in environment files: + +```yaml +genesis: + secrets_mount: secret/custom + secrets_slug: prod/cf + exodus_mount: secret/shared + exodus_slug: cf-prod +``` + +## Vault Policies + +### Basic Policy Structure + +```hcl +# Read-only access to production +path "secret/prod/*" { + capabilities = ["read", "list"] +} + +# Full access to development +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Deny access to specific paths +path "secret/prod/*/admin_password" { + capabilities = ["deny"] +} +``` + +### Genesis-Specific Policies + +#### Operator Policy + +```hcl +# Full access to all Genesis secrets +path "secret/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Access to Vault tools +path "sys/tools/*" { + capabilities = ["read"] +} + +# Mount management +path "sys/mounts/*" { + capabilities = ["read", "list"] +} +``` + +#### Developer Policy + +```hcl +# Read dev/staging, no prod access +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/staging/*" { + capabilities = ["read", "list"] +} + +path "secret/prod/*" { + capabilities = ["deny"] +} +``` + +#### CI/CD Policy + +```hcl +# Read-only for deployments +path "secret/+/+/+/*" { + capabilities = ["read"] +} + +# Write exodus data +path "secret/exodus/*" { + capabilities = ["create", "read", "update"] +} +``` + +### Applying Policies + +```bash +# Create policy +safe policy write operator-policy policy.hcl + +# Assign to user +safe auth token create \ + --policy=operator-policy \ + --display-name="John Doe" + +# Assign to GitHub team +safe write auth/github/map/teams/ops-team \ + value=operator-policy +``` + +## Secret Operations + +### Viewing Secrets + +```bash +# List secrets for environment +safe tree secret/us-east-1/prod/cf + +# View specific secret +safe get secret/us-east-1/prod/cf/admin_password + +# Export all secrets +safe export secret/us-east-1/prod/cf > cf-secrets.json +``` + +### Manual Secret Management + +```bash +# Set a secret +safe set secret/us-east-1/prod/cf/api_key value=abc123 + +# Generate password +safe gen secret/us-east-1/prod/cf/new_password + +# Create SSH key +safe ssh secret/us-east-1/prod/cf/bastion_ssh + +# Issue certificate +safe x509 issue secret/us-east-1/prod/cf/web_cert \ + --ca secret/us-east-1/prod/cf/ca \ + --name web.example.com \ + --ttl 365d +``` + +### Copying Secrets + +```bash +# Copy between environments +safe cp \ + secret/us-east-1/dev/cf \ + secret/us-east-1/staging/cf + +# Copy specific secret +safe cp \ + secret/us-east-1/prod/cf/ca \ + secret/us-west-2/prod/cf/ca +``` + +## High Availability + +### Multi-Node Vault + +Deploy Vault in HA mode: + +```yaml +# In Vault environment file +params: + vault_num_instances: 3 + + consul_servers: + - 10.0.1.10 + - 10.0.1.11 + - 10.0.1.12 +``` + +### Backup and Recovery + +```bash +# Backup Vault data +genesis do vault-prod -- backup + +# Create snapshot (Vault Enterprise) +vault operator raft snapshot save backup.snap + +# Restore from backup +genesis do vault-prod -- restore backup.tar.gz +``` + +## Monitoring and Maintenance + +### Health Checks + +```bash +# Check Vault status +safe status + +# Detailed status +vault status -format=json + +# Check seal status +safe sealed? +``` + +### Audit Logging + +Enable audit logging: + +```bash +# File audit backend +vault audit enable file \ + file_path=/var/log/vault/audit.log + +# Syslog audit backend +vault audit enable syslog \ + tag="vault" \ + facility="LOCAL7" +``` + +### Performance Tuning + +```bash +# Enable metrics +vault write sys/config/telemetry \ + prometheus_retention_time="30s" \ + disable_hostname=true + +# Monitor key metrics +- vault.core.handle_request +- vault.token.lookup +- vault.barrier.get +- vault.barrier.put +``` + +## Troubleshooting + +### Connection Issues + +```bash +# Test connectivity +safe target check + +# Verify environment +env | grep VAULT + +# Check TLS +openssl s_client -connect vault.example.com:8200 +``` + +### Authentication Problems + +```bash +# Check token validity +safe token + +# Renew token +safe renew + +# Re-authenticate +safe auth +``` + +### Permission Denied + +```bash +# Check policies +safe vault policy read my-policy + +# List token policies +vault token lookup + +# Test specific path +safe exists secret/path/to/test +``` + +## Best Practices + +### 1. Use Policies + +Always use policies instead of root tokens: +- Create specific policies for each role +- Follow principle of least privilege +- Regularly audit policy assignments + +### 2. Enable Auditing + +```bash +vault audit enable file \ + file_path=/vault/logs/audit.log \ + log_raw=true +``` + +### 3. Regular Backups + +```bash +# Automated backup script +#!/bin/bash +genesis do vault-prod -- backup +aws s3 cp vault-backup.tar.gz s3://backups/vault/ +``` + +### 4. Monitor Unseal Keys + +- Distribute unseal keys securely +- Never store together +- Regular key rotation +- Use auto-unseal when possible + +### 5. TLS Everywhere + +- Valid certificates on Vault +- Verify certificates in production +- Use mTLS for added security + +## Integration Examples + +### CI/CD Pipeline + +```yaml +# Concourse pipeline +resources: +- name: secrets + type: vault + source: + url: ((vault_addr)) + path: secret/us-east-1/prod + client_token: ((vault_token)) +``` + +### Application Integration + +```python +# Python example +import hvac + +client = hvac.Client( + url='https://vault.example.com:8200', + token=os.environ['VAULT_TOKEN'] +) + +secret = client.read('secret/data/app/database') +db_password = secret['data']['data']['password'] +``` + +### Kubernetes Integration + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: db-creds + annotations: + vault.hashicorp.com/agent-inject: "true" + vault.hashicorp.com/agent-inject-secret-db: "secret/app/db" + vault.hashicorp.com/role: "app" +``` + +Proper Vault integration ensures your Genesis deployments remain secure while maintaining operational efficiency. \ No newline at end of file diff --git a/docs/topics/50-kits/.keep b/docs/topics/50-kits/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/50-kits/authoring-kits.md b/docs/topics/50-kits/authoring-kits.md new file mode 100644 index 00000000..fedd7767 --- /dev/null +++ b/docs/topics/50-kits/authoring-kits.md @@ -0,0 +1,599 @@ +# Authoring Genesis Kits + +This guide covers creating your own Genesis kits to package deployment knowledge for reuse across teams and environments. + +## Getting Started + +### When to Create a Kit + +Create a kit when: +- Deploying software not covered by existing kits +- Standardizing deployment patterns across teams +- Packaging proprietary software deployments +- Sharing deployment expertise + +### Kit Philosophy + +Remember these principles: + +1. **Kit Authors are Trusted** - You have full control +2. **User Parameters under `params`** - Keep configuration organized +3. **Secrets in Vault** - Never hardcode credentials +4. **Multiple Ways to Deploy** - Support variations via features + +### Development Setup + +```bash +# Create kit skeleton +genesis create-kit my-software + +# Directory structure created: +my-software-genesis-kit/ +├── kit.yml # Kit metadata +├── manifests/ # BOSH manifests +│ └── base.yml +└── hooks/ # Lifecycle scripts + └── blueprint + +cd my-software-genesis-kit +``` + +## Kit Structure + +### kit.yml - Metadata + +Define your kit's identity and behavior: + +```yaml +name: my-software +version: 0.1.0 +author: Your Name +docs: https://github.com/yourorg/my-software-genesis-kit +code: https://github.com/yourorg/my-software-genesis-kit + +description: | + Deploys My Software, a revolutionary application that + solves all your problems. + +# Define required credentials +credentials: + base: + admin: + password: random 32 + database: + password: random 64 fmt base64 + +# Define certificates +certificates: + base: + server: + ca: + valid_for: 10y + web: + valid_for: 1y + names: + - "*.${params.base_domain}" +``` + +### Base Manifest + +Start with `manifests/base.yml`: + +```yaml +--- +name: (( grab params.env )) + +releases: +- name: my-software + version: "1.2.3" + url: https://github.com/org/releases/download/v1.2.3/release.tgz + sha1: abc123... + +stemcells: +- alias: default + os: ubuntu-jammy + version: latest + +update: + canaries: 1 + max_in_flight: 1 + canary_watch_time: 30000-120000 + update_watch_time: 30000-120000 + +instance_groups: +- name: my-software + instances: (( grab params.instances || 1 )) + vm_type: (( grab params.vm_type || "default" )) + stemcell: default + networks: + - name: (( grab params.network || "default" )) + jobs: + - name: my-software + release: my-software + properties: + admin_password: (( vault "secret/" params.vault "/admin:password" )) + database_password: (( vault "secret/" params.vault "/database:password" )) +``` + +## Features + +### Adding Features + +Create feature manifests in `manifests/features/`: + +```yaml +# manifests/features/ha.yml +--- +# High Availability Feature +- type: replace + path: /instance_groups/name=my-software/instances + value: 3 + +- type: replace + path: /instance_groups/name=my-software/jobs/name=my-software/properties/cluster? + value: + enabled: true + members: 3 +``` + +```yaml +# manifests/features/monitoring.yml +--- +# Prometheus Monitoring +- type: replace + path: /instance_groups/name=my-software/jobs/- + value: + name: prometheus_exporter + release: prometheus + properties: + prometheus: + port: 9100 +``` + +### Feature-Specific Secrets + +```yaml +# kit.yml +credentials: + base: + admin: + password: random 32 + + ldap: # Only with LDAP feature + ldap/bind: + password: random 32 + + ssl: # Only with SSL feature + ssl/server: cert +``` + +## Lifecycle Hooks + +### blueprint Hook + +Controls manifest generation: + +```bash +#!/bin/bash +# hooks/blueprint +set -eu + +# Base manifest is always first +declare -a manifests +manifests+=( "manifests/base.yml" ) + +# Process requested features +for want in ${GENESIS_REQUESTED_FEATURES}; do + case "$want" in + ha|monitoring|ssl) + manifests+=( "manifests/features/$want.yml" ) + ;; + *) + echo >&2 "Unrecognized feature: $want" + exit 1 + ;; + esac +done + +# Output manifest list +printf "%s\n" "${manifests[@]}" +``` + +### new Hook + +Interactive environment setup: + +```bash +#!/bin/bash +# hooks/new +set -eu + +# Prompt for basic configuration +prompt_for "base_domain" \ + "What is your base domain?" \ + --validation "/^[a-z0-9.-]+$/" + +# Feature selection +feature_wanted "ha" \ + "Do you want High Availability mode?" + +if feature_wanted "ha"; then + prompt_for "instances" \ + "How many instances?" \ + --default 3 \ + --validation "/^[3-9]$/" +else + prompt_for "instances" \ + "How many instances?" \ + --default 1 +fi + +# Infrastructure features +describe "What infrastructure are you deploying to?" +features+=( \ + "$(prompt_for_choice \ + "Infrastructure?" \ + "aws" \ + "azure" \ + "gcp" \ + "vsphere" \ + "openstack" \ + )" \ +) + +# Save configuration +genesis_config_set params.base_domain "$base_domain" +genesis_config_set params.instances "$instances" +``` + +### check Hook + +Pre-deployment validation: + +```bash +#!/bin/bash +# hooks/check +set -eu + +# Validate cloud config +if ! bosh_cloud_config_has vm_type $(genesis_config_get params.vm_type); then + describe >&2 \ + "VM type '#R{$(genesis_config_get params.vm_type)}' not found in cloud config" + exit 1 +fi + +# Check for required secrets +if want_feature "provided-cert"; then + if ! safe exists "$GENESIS_SECRETS_BASE/ssl/server"; then + describe >&2 \ + "Feature 'provided-cert' requires certificate at $GENESIS_SECRETS_BASE/ssl/server" + exit 1 + fi +fi + +describe "Environment looks good!" +``` + +### info Hook + +Display deployment information: + +```bash +#!/bin/bash +# hooks/info +set -eu + +# Get deployment info +FQDN="$(genesis_config_get params.base_domain)" +PASS="$(safe get "$GENESIS_SECRETS_BASE/admin:password")" + +describe "#G{My Software Information}" +echo +describe " URL: #C{https://app.$FQDN}" +describe " Username: #C{admin}" +describe " Password: #C{$PASS}" +echo +describe "To visit the web UI, run:" +echo +describe " #G{genesis do $GENESIS_ENVIRONMENT visit-ui}" +``` + +### addon Hook + +Operational tasks: + +```bash +#!/bin/bash +# hooks/addon +set -eu + +case "$GENESIS_ADDON_SCRIPT" in + visit-ui) + URL="https://app.$(genesis_config_get params.base_domain)" + describe "Opening $URL in your browser..." + open "$URL" || xdg-open "$URL" || echo "Please visit: $URL" + ;; + + backup) + describe "Running backup..." + genesis bosh run-errand backup + ;; + + list) + describe "Available addons:" + describe " #G{visit-ui} - Open the web interface" + describe " #G{backup} - Run a backup" + ;; + + *) + describe >&2 "Unknown addon: $GENESIS_ADDON_SCRIPT" + exit 1 + ;; +esac +``` + +## Development Workflow + +### Local Development + +Use the `dev/` directory for rapid iteration: + +```bash +# In your deployment repo +mkdir dev +cp -r /path/to/my-software-genesis-kit/* dev/ + +# Use dev kit +cat > test.yml <&2 \ + "#R{Missing required parameter 'base_domain'}" \ + "" \ + "Please add to your environment file:" \ + " #C{params:}" \ + " #C{ base_domain: example.com}" + exit 1 +fi +``` + +### 4. Feature Organization + +Group related changes: +``` +manifests/features/ +├── aws.yml # IaaS-specific +├── azure.yml +├── ha.yml # Architecture +├── standalone.yml +├── monitoring.yml # Operations +└── shield.yml +``` + +### 5. Version Management + +```yaml +# kit.yml +name: my-software +version: 1.0.0 # Semantic versioning + +# Track BOSH release versions +releases: + my-software: 2.3.4 + prometheus: 25.0.0 +``` + +## Publishing Your Kit + +### Prepare for Release + +1. **Test thoroughly** across scenarios +2. **Document** in README.md +3. **Version** appropriately +4. **Include examples** + +### Compile and Release + +```bash +# Compile kit +genesis compile-kit \ + --version 1.0.0 \ + --name my-software + +# Creates: my-software-1.0.0.tar.gz + +# Upload to GitHub releases +# Tag repository with v1.0.0 +``` + +### Sharing with Community + +1. Open source on GitHub +2. Follow naming convention: `*-genesis-kit` +3. Submit to Genesis community registry +4. Announce in Genesis Slack + +## Troubleshooting + +### Manifest Generation Issues + +```bash +# Debug blueprint hook +cd dev +GENESIS_REQUESTED_FEATURES="ha monitoring" ./hooks/blueprint + +# Check generated manifest +genesis manifest test -P | spruce diff base.yml - +``` + +### Secret Generation Problems + +```bash +# Check what secrets are needed +genesis check-secrets test + +# Manually generate if needed +safe gen "$VAULT_PREFIX/test/admin" password +``` + +### Hook Failures + +```bash +# Run hooks manually +cd dev +export GENESIS_ENVIRONMENT=test +export GENESIS_SECRETS_BASE=secret/test/my-software +./hooks/info +``` + +## Next Steps + +- Study existing kits for patterns +- Start with simple kits +- Iterate based on user feedback +- Contribute improvements back + +Creating kits shares your operational knowledge and makes deployments consistent and reliable across your organization. \ No newline at end of file diff --git a/docs/topics/50-kits/available-kits.md b/docs/topics/50-kits/available-kits.md new file mode 100644 index 00000000..cb82f5c6 --- /dev/null +++ b/docs/topics/50-kits/available-kits.md @@ -0,0 +1,376 @@ +# Available Genesis Kits + +This catalog lists official Genesis kits maintained by the Genesis Community, along with their primary use cases and key features. + +## Infrastructure Kits + +### BOSH Director Kit + +**Repository**: [bosh-genesis-kit](https://github.com/genesis-community/bosh-genesis-kit) + +Deploy BOSH directors for managing your infrastructure. + +**Key Features**: +- `aws`, `azure`, `gcp`, `vsphere`, `openstack` - IaaS support +- `proto` - Proto-BOSH for bootstrapping +- `bosh-init` - Legacy create-env support +- `bbr` - BOSH Backup & Restore +- `vault-credhub-proxy` - CredHub integration + +**Common Usage**: +```yaml +kit: + name: bosh + features: + - aws + - proto + - vault-credhub-proxy +``` + +### Vault Kit + +**Repository**: [vault-genesis-kit](https://github.com/genesis-community/vault-genesis-kit) + +Deploy HashiCorp Vault for secrets management. + +**Key Features**: +- `consul`, `raft`, `file` - Storage backends +- `auto-unseal` - Cloud KMS unsealing +- `ha` - High availability mode +- `monitoring` - Prometheus metrics + +**Common Usage**: +```yaml +kit: + name: vault + features: + - raft + - auto-unseal + - monitoring +``` + +## Platform Kits + +### Cloud Foundry Kit + +**Repository**: [cf-genesis-kit](https://github.com/genesis-community/cf-genesis-kit) + +Deploy full Cloud Foundry platforms. + +**Key Features**: +- `haproxy`, `routing-api` - Routing options +- `postgres`, `mysql` - Database backends +- `azure-blobstore`, `s3-blobstore` - Blob storage +- `container-routing`, `loggregator-forwarder-agent` +- `small-footprint`, `minimum-vms` - Sizing options + +**Common Usage**: +```yaml +kit: + name: cf + features: + - haproxy + - postgres + - s3-blobstore + - routing-api +``` + +### Kubernetes Kit + +**Repository**: [k8s-genesis-kit](https://github.com/genesis-community/k8s-genesis-kit) + +Deploy Kubernetes clusters with BOSH. + +**Key Features**: +- `flannel`, `calico` - Network providers +- `dashboard` - Kubernetes dashboard +- `monitoring` - Cluster monitoring +- `ingress` - Ingress controller + +**Common Usage**: +```yaml +kit: + name: k8s + features: + - flannel + - dashboard + - monitoring +``` + +## CI/CD Kits + +### Concourse Kit + +**Repository**: [concourse-genesis-kit](https://github.com/genesis-community/concourse-genesis-kit) + +Deploy Concourse CI/CD systems. + +**Key Features**: +- `github-oauth`, `cf-auth` - Authentication +- `prometheus` - Metrics exporter +- `vault` - Vault integration +- `workers` - External workers +- `no-tls`, `provided-cert` - Certificate options + +**Common Usage**: +```yaml +kit: + name: concourse + features: + - github-oauth + - prometheus + - vault +``` + +### Jenkins Kit + +**Repository**: [jenkins-genesis-kit](https://github.com/genesis-community/jenkins-genesis-kit) + +Deploy Jenkins automation servers. + +**Key Features**: +- `github-oauth` - GitHub authentication +- `ldap` - LDAP integration +- `slaves` - Distributed builds +- `backup` - Automated backups + +## Database Kits + +### PostgreSQL Kit + +**Repository**: [postgres-genesis-kit](https://github.com/genesis-community/postgres-genesis-kit) + +Deploy standalone PostgreSQL databases. + +**Key Features**: +- `ha` - High availability +- `monitoring` - Database metrics +- `backups` - Automated backups +- `tls` - Encrypted connections + +**Common Usage**: +```yaml +kit: + name: postgres + features: + - ha + - monitoring + - backups +``` + +### Redis Kit + +**Repository**: [redis-genesis-kit](https://github.com/genesis-community/redis-genesis-kit) + +Deploy Redis key-value stores. + +**Key Features**: +- `cluster` - Redis cluster mode +- `sentinel` - High availability +- `persistent` - Disk persistence +- `shield` - Backup integration + +## Monitoring Kits + +### Prometheus Kit + +**Repository**: [prometheus-genesis-kit](https://github.com/genesis-community/prometheus-genesis-kit) + +Deploy Prometheus monitoring stacks. + +**Key Features**: +- `grafana` - Visualization +- `alertmanager` - Alert routing +- `node-exporter` - System metrics +- `postgres-exporter`, `mysql-exporter` - Database monitoring + +**Common Usage**: +```yaml +kit: + name: prometheus + features: + - grafana + - alertmanager + - node-exporter +``` + +### Blacksmith Kit + +**Repository**: [blacksmith-genesis-kit](https://github.com/genesis-community/blacksmith-genesis-kit) + +Deploy on-demand service brokers. + +**Key Features**: +- `redis-forge` - Redis services +- `postgres-forge` - PostgreSQL services +- `rabbitmq-forge` - RabbitMQ services +- `cf-integration` - Cloud Foundry broker + +## Backup & Recovery Kits + +### Shield Kit + +**Repository**: [shield-genesis-kit](https://github.com/genesis-community/shield-genesis-kit) + +Deploy Shield backup/restore solutions. + +**Key Features**: +- `postgres`, `mysql` - Database backends +- `minio` - Object storage +- `monitoring` - Backup metrics +- `oauth` - External authentication + +**Common Usage**: +```yaml +kit: + name: shield + features: + - postgres + - monitoring + - oauth +``` + +### Minio Kit + +**Repository**: [minio-genesis-kit](https://github.com/genesis-community/minio-genesis-kit) + +Deploy Minio S3-compatible object storage. + +**Key Features**: +- `distributed` - Multi-node setup +- `tls` - Encrypted connections +- `monitoring` - Storage metrics + +## Utility Kits + +### Jumpbox Kit + +**Repository**: [jumpbox-genesis-kit](https://github.com/genesis-community/jumpbox-genesis-kit) + +Deploy secure bastion hosts. + +**Key Features**: +- `openvpn` - VPN server +- `shield` - Backup agent +- `all-tools` - Extra utilities +- `golang`, `ruby` - Development tools + +**Common Usage**: +```yaml +kit: + name: jumpbox + features: + - openvpn + - all-tools +``` + +### Docker Registry Kit + +**Repository**: [docker-registry-genesis-kit](https://github.com/genesis-community/docker-registry-genesis-kit) + +Deploy private Docker registries. + +**Key Features**: +- `s3-storage`, `swift-storage` - Backend storage +- `auth` - Authentication +- `proxy` - Pull-through cache +- `monitoring` - Registry metrics + +## Using Official Kits + +### Installation + +All official kits are automatically available: + +```bash +# List all kits +genesis kits + +# Initialize with kit +genesis init --kit +``` + +### Version Selection + +Check available versions: + +```bash +# Show kit versions +genesis info --versions + +# Use specific version +kit: + version: 2.3.0 # Recommended for production +``` + +### Getting Help + +For each kit: + +```bash +# View documentation +genesis info + +# See available features +genesis info --features + +# Check parameters +genesis info --params +``` + +## Community Kits + +Beyond official kits, community members create kits for: +- Custom applications +- Proprietary software +- Specialized configurations + +Find community kits: +- Search GitHub for `*-genesis-kit` +- Check Genesis community forums +- Ask in Genesis Slack + +## Creating Your Own Kit + +If you need a kit that doesn't exist: + +1. **Check existing kits** - Maybe adapt one +2. **Use generic kit** - For simple cases +3. **Create new kit** - See [Authoring Kits](authoring-kits.md) + +## Kit Selection Guide + +### For New Users + +Start with these well-documented kits: +1. **BOSH** - Essential infrastructure +2. **Vault** - Secrets management +3. **Concourse** - CI/CD pipelines +4. **Jumpbox** - Secure access + +### For Cloud Foundry + +Complete CF deployment stack: +1. **BOSH** - Infrastructure layer +2. **Vault** - Secrets backend +3. **Postgres** - CF database +4. **CF** - Cloud Foundry itself +5. **Shield** - Backup solution + +### For Kubernetes + +Kubernetes on BOSH: +1. **BOSH** - Infrastructure +2. **Vault** - Secrets +3. **K8s** - Kubernetes cluster +4. **Prometheus** - Monitoring + +## Support + +For kit issues: +- Check kit repository issues +- Ask in Genesis Slack +- Consult kit documentation +- Review kit release notes + +Official kits are actively maintained and tested across common deployment scenarios. \ No newline at end of file diff --git a/docs/topics/50-kits/features.md b/docs/topics/50-kits/features.md new file mode 100644 index 00000000..328b43e3 --- /dev/null +++ b/docs/topics/50-kits/features.md @@ -0,0 +1,544 @@ +# Kit Features + +Features are optional components in Genesis kits that allow you to customize deployments for different scenarios. This guide explains how features work and how to use them effectively. + +## Understanding Features + +### What Are Features? + +Features are modular extensions to a kit's base configuration: +- Add or modify deployment components +- Enable integrations with external systems +- Adapt to different infrastructures +- Toggle functionality on/off + +### How Features Work + +When you enable a feature: +1. Genesis includes additional YAML files +2. New parameters may be required +3. Different secrets might be generated +4. Validation rules can change + +## Feature Types + +### Infrastructure Features + +Adapt to different IaaS providers: + +```yaml +kit: + features: + - aws # Amazon Web Services + - azure # Microsoft Azure + - gcp # Google Cloud Platform + - vsphere # VMware vSphere + - openstack # OpenStack +``` + +Each provides: +- IaaS-specific resource types +- Network configurations +- Storage options +- Instance metadata + +### Architectural Features + +Change deployment topology: + +```yaml +kit: + features: + # High Availability + - ha # Multi-instance, clustered + - standalone # Single instance + + # Scaling + - minimum-vms # Colocate jobs + - distributed # Separate job instances +``` + +### Storage Features + +Different backend options: + +```yaml +# Vault kit example +kit: + features: + - consul # Consul storage backend + - raft # Integrated Raft storage + - file # File-based (dev only) + +# CF kit example +kit: + features: + - postgres # PostgreSQL database + - mysql # MySQL database + - external-db # User-provided database +``` + +### Security Features + +Enhanced security options: + +```yaml +kit: + features: + # Authentication + - ldap # LDAP integration + - github-oauth # GitHub OAuth + - uaa # UAA integration + + # Certificates + - self-signed-cert # Generate certificates + - provided-cert # User-provided certificates + + # Encryption + - encryption-at-rest + - mtls # Mutual TLS +``` + +### Operational Features + +Monitoring and maintenance: + +```yaml +kit: + features: + # Monitoring + - monitoring # Prometheus exporters + - logging # Enhanced logging + + # Backup + - shield # Shield backup agent + - native-backup # Built-in backup + + # Debugging + - debug # Debug logging + - trace # Trace-level output +``` + +## Feature Dependencies + +### Mutually Exclusive Features + +Some features cannot be used together: + +```yaml +# Error - multiple databases +kit: + features: + - postgres # Can't use both + - mysql # database types + +# Error - conflicting architectures +kit: + features: + - ha # Can't be both HA + - standalone # and standalone +``` + +### Required Combinations + +Some features require others: + +```yaml +# github-oauth requires UAA +kit: + features: + - uaa # Required by + - github-oauth # this feature +``` + +### Implicit Features + +Features activated automatically: + +```yaml +# If no storage backend specified +# Might implicitly activate +internal-storage +kit: + features: [] # +internal-storage added +``` + +## Feature Parameters + +### Feature-Specific Parameters + +Features often introduce new parameters: + +```yaml +# With 'aws' feature +params: + aws_region: us-east-1 + aws_default_sgs: [bosh] + +# With 'github-oauth' feature +params: + github_client_id: abc123 + github_client_secret: ((github_oauth_secret)) + github_orgs: [myorg] +``` + +### Conditional Parameters + +Parameters that only apply with certain features: + +```yaml +params: + # Always required + base_domain: example.com + + # Only with 'ha' feature + cluster_members: 3 + + # Only with 'postgres' feature + postgres_version: "13" +``` + +## Feature Discovery + +### List Available Features + +```bash +# During environment creation +genesis new prod-env +> Select features to enable: +> [ ] aws - AWS infrastructure support +> [ ] monitoring - Prometheus metrics +> [ ] shield - Backup integration +> [x] ha - High availability mode + +# From kit info +genesis info vault --features +``` + +### Feature Documentation + +```bash +# Get feature details +genesis info vault --feature consul + +# Shows: +# - Description +# - Required parameters +# - Dependencies +# - Conflicts +``` + +### In Kit Source + +```bash +# Feature manifests +ls .genesis/kits/vault-1.5.0/manifests/features/ +consul.yml +monitoring.yml +provided-cert.yml +``` + +## Common Feature Patterns + +### Progressive Enhancement + +Start simple, add features: + +```yaml +# Initial deployment +kit: + name: concourse + version: 5.0.0 + features: [] + +# Add authentication +kit: + features: + - github-oauth + +# Add monitoring +kit: + features: + - github-oauth + - prometheus + +# Add backups +kit: + features: + - github-oauth + - prometheus + - shield +``` + +### Environment-Specific Features + +Different features per environment: + +```yaml +# development.yml +kit: + features: + - minimum-vms + - self-signed-cert + +# staging.yml +kit: + features: + - ha + - self-signed-cert + - monitoring + +# production.yml +kit: + features: + - ha + - provided-cert + - monitoring + - shield +``` + +### Infrastructure Adaptation + +```yaml +# AWS deployment +kit: + features: + - aws + - ha + - monitoring + +# vSphere deployment +kit: + features: + - vsphere + - ha + - monitoring + - nfs-volume-services +``` + +## Feature Implementation + +### How Kits Define Features + +In the kit's `manifests/features/` directory: + +```yaml +# manifests/features/monitoring.yml +- type: replace + path: /instance_groups/name=vault/jobs/- + value: + name: prometheus_exporter + release: prometheus + properties: + prometheus: + port: 9100 +``` + +### Feature Activation + +The `blueprint` hook determines active features: + +```bash +#!/bin/bash +# hooks/blueprint + +# Base manifest always included +manifest_files="manifests/base.yml" + +# Add feature manifests +for feature in $GENESIS_REQUESTED_FEATURES; do + manifest_files="$manifest_files manifests/features/$feature.yml" +done + +echo "$manifest_files" +``` + +### Conditional Logic + +Features can include logic: + +```yaml +# Only add if using PostgreSQL +- type: replace + path: /instance_groups/name=postgres? + value: + name: postgres + instances: (( grab params.postgres_instances || 1 )) +``` + +## Advanced Feature Usage + +### Custom Features + +Add your own features via ops files: + +```bash +# Create custom feature +mkdir -p ops +cat > ops/custom-logging.yml < with-feature.yml + +# Remove feature and compare +# Edit environment file +genesis manifest my-env > without-feature.yml + +diff without-feature.yml with-feature.yml +``` + +## Summary + +Features provide powerful customization: +- Adapt to any infrastructure +- Enable optional functionality +- Maintain clean base configurations +- Share common patterns + +Use them wisely to create flexible, maintainable deployments. \ No newline at end of file diff --git a/docs/topics/50-kits/index.md b/docs/topics/50-kits/index.md new file mode 100644 index 00000000..2229836c --- /dev/null +++ b/docs/topics/50-kits/index.md @@ -0,0 +1,138 @@ +# Genesis Kits + +Genesis Kits are pre-packaged deployment templates that encapsulate best practices for deploying software with BOSH. This section covers everything from using existing kits to creating your own. + +## Topics in This Section + +1. **[Overview](overview.md)** - Understanding Genesis kits +2. **[Using Kits](using-kits.md)** - Finding, selecting, and deploying with kits +3. **[Kit Features](features.md)** - Working with optional kit components +4. **[Available Kits](available-kits.md)** - Catalog of official Genesis kits +5. **[Authoring Kits](authoring-kits.md)** - Creating your own Genesis kits +6. **[Kit Structure](kit-structure.md)** - Anatomy of a kit +7. **[Kit Hooks](kit-hooks.md)** - Lifecycle hooks and scripts +8. **[Writing Hooks](writing-hooks.md)** - Hook development guide +9. **[Kit Testing](kit-testing.md)** - Testing and validation +10. **[Best Practices](best-practices.md)** - Kit development recommendations + +## Quick Overview + +Genesis Kits provide: + +- **Pre-built Templates** - YAML manifests with sensible defaults +- **Feature Flags** - Optional components you can enable +- **Secret Management** - Automatic credential generation +- **Lifecycle Hooks** - Scripts for customization +- **Best Practices** - Years of deployment experience + +### Common Kits + +- **BOSH** - Deploy BOSH directors +- **Cloud Foundry** - Full CF deployments +- **Vault** - HashiCorp Vault clusters +- **Concourse** - CI/CD pipelines +- **Shield** - Backup solutions +- **Prometheus** - Monitoring stacks + +## Using Kits + +### Finding Kits + +```bash +# List available kits +genesis kits + +# Search for specific kit +genesis kits | grep vault + +# Get kit information +genesis info vault +``` + +### Selecting Kit Version + +```yaml +# In environment file +kit: + name: vault + version: 1.5.0 # Specific version + # or + version: latest # Always use latest +``` + +### Enabling Features + +```yaml +kit: + features: + - postgres # Use PostgreSQL + - haproxy # Enable load balancer + - tls # Enable TLS/SSL +``` + +## Creating Kits + +### Basic Kit Structure + +``` +my-genesis-kit/ +├── kit.yml # Kit metadata +├── hooks/ # Lifecycle scripts +│ ├── new +│ ├── blueprint +│ └── check +├── manifests/ # YAML templates +│ └── base.yml +└── spec/ # Test specifications +``` + +### Development Workflow + +```bash +# Create new kit +genesis create-kit my-software + +# Work in dev mode +cd deployments/my-software +mkdir dev +# ... develop kit in dev/ ... + +# Test your kit +genesis new test-env --kit dev + +# Compile kit +genesis compile-kit --version 1.0.0 +``` + +## Key Concepts + +### Kit Metadata (kit.yml) + +Defines kit properties: +- Name and version +- Author information +- Required secrets +- Available features +- Dependencies + +### Features + +Optional components: +- Infrastructure-specific (AWS, Azure, vSphere) +- Add-ons (monitoring, backups) +- Integrations (SSO, external databases) + +### Hooks + +Scripts that run at specific times: +- **new** - Environment creation +- **blueprint** - Manifest generation +- **check** - Pre-deployment validation +- **addon** - Operational tasks + +## Getting Started + +- New to kits? Start with [Overview](overview.md) +- Want to use a kit? See [Using Kits](using-kits.md) +- Ready to create? Read [Authoring Kits](authoring-kits.md) +- Need examples? Check [Available Kits](available-kits.md) \ No newline at end of file diff --git a/docs/topics/50-kits/kit-hooks.md b/docs/topics/50-kits/kit-hooks.md new file mode 100644 index 00000000..f4c59ffc --- /dev/null +++ b/docs/topics/50-kits/kit-hooks.md @@ -0,0 +1,514 @@ +# Kit Hooks + +Genesis hooks provide an extensible interface for customizing deployment behavior at various stages. They allow kit authors to inject custom code that executes during different phases of the deployment lifecycle. + +## Overview + +Genesis hooks are executable scripts (typically Bash) or Perl modules that extend Genesis functionality. Each hook serves a specific purpose in the deployment workflow and is invoked automatically by Genesis at the appropriate time. + +## Hook Types + +### Core Hooks (Bash Scripts) + +Located in the `hooks/` directory of a kit: + +#### new + +Runs when creating a new environment with `genesis new`. + +**Purpose**: Interactive environment setup, prompting for configuration values. + +```bash +#!/bin/bash +# hooks/new +set -eu + +# Prompt for required configuration +prompt_for base_domain \ + "What is your base domain?" \ + --validation "valid_domain" + +# Feature selection +if features_enabled "ssl"; then + prompt_for cert_path \ + "Path to SSL certificate?" \ + --default "/path/to/cert.pem" +fi +``` + +#### blueprint + +Determines which manifest files to merge for the deployment. + +**Purpose**: Build the ordered list of YAML files based on features. + +```bash +#!/bin/bash +# hooks/blueprint +set -eu + +# Always start with base +manifests=(manifests/base.yml) + +# Add feature manifests +for want in $GENESIS_REQUESTED_FEATURES; do + case $want in + ha|monitoring|ssl) + manifests+=(manifests/features/$want.yml) + ;; + aws|azure|gcp) + manifests+=(manifests/iaas/$want.yml) + ;; + esac +done + +# Output the list +printf "%s\n" "${manifests[@]}" +``` + +#### check + +Validates the environment before deployment. + +**Purpose**: Pre-deployment validation of configuration and requirements. + +```bash +#!/bin/bash +# hooks/check +set -eu + +# Validate cloud config +vm_type=$(lookup params.vm_type default) +if ! cloud_config_has vm_type "$vm_type"; then + echo >&2 "VM type '$vm_type' not found in cloud config" + exit 1 +fi + +# Check secrets +if want_feature "provided-cert" && ! safe exists "$VAULT_PREFIX/ssl/cert"; then + echo >&2 "Feature 'provided-cert' requires certificate in Vault" + exit 1 +fi +``` + +#### secrets + +Manages secrets beyond what's defined in kit.yml. + +**Purpose**: Handle complex secret generation or rotation scenarios. + +```bash +#!/bin/bash +# hooks/secrets +set -eu + +case $GENESIS_SECRET_ACTION in + add) + # Generate additional secrets + if want_feature "custom-ca"; then + safe x509 ca "$VAULT_PREFIX/custom/ca" \ + --ttl 10y \ + --subject "/CN=Custom CA" + fi + ;; + + rotate) + # Custom rotation logic + ;; +esac +``` + +#### info + +Displays deployment information after successful deployment. + +**Purpose**: Show URLs, credentials, and next steps. + +```bash +#!/bin/bash +# hooks/info +set -eu + +echo "Deployment Information:" +echo +echo "URL: https://$(lookup params.base_domain)" +echo "Username: admin" +echo "Password: $(safe get "$VAULT_PREFIX/admin:password")" +echo +echo "To access the dashboard, run:" +echo " genesis do $GENESIS_ENVIRONMENT dashboard" +``` + +#### addon + +Provides operational commands via `genesis do`. + +**Purpose**: Extend Genesis with kit-specific operations. + +```bash +#!/bin/bash +# hooks/addon +set -eu + +case $GENESIS_ADDON_SCRIPT in + list) + echo "Available addons:" + echo " login - Log into the system" + echo " backup - Run a backup" + echo " restore - Restore from backup" + ;; + + login) + url="https://$(lookup params.base_domain)" + password=$(safe get "$VAULT_PREFIX/admin:password") + echo "Logging into $url..." + # Login logic here + ;; + + backup) + echo "Starting backup..." + $GENESIS_BOSH_COMMAND -d "$BOSH_DEPLOYMENT" run-errand backup + ;; + + *) + echo >&2 "Unknown addon: $GENESIS_ADDON_SCRIPT" + exit 1 + ;; +esac +``` + +#### pre-deploy + +Runs before deployment begins. + +**Purpose**: Final validation, data collection for post-deploy. + +```bash +#!/bin/bash +# hooks/pre-deploy +set -eu + +# Collect current state +echo "Current version: $(get_deployed_version)" > "$GENESIS_PREDEPLOY_DATAFILE" + +# Final checks +if deploying_major_version_change; then + echo "WARNING: Major version upgrade detected!" + if [[ "$GENESIS_DEPLOY_CONFIRM" != "yes" ]]; then + read -p "Continue? [y/N] " confirm + [[ "$confirm" == "y" ]] || exit 1 + fi +fi +``` + +#### post-deploy + +Runs after deployment (successful or failed). + +**Purpose**: Cleanup, notifications, follow-up tasks. + +```bash +#!/bin/bash +# hooks/post-deploy +set -eu + +if [[ "$GENESIS_DEPLOY_RC" == "0" ]]; then + echo "Deployment successful!" + + # Run smoke tests + $GENESIS_BOSH_COMMAND -d "$BOSH_DEPLOYMENT" run-errand smoke-tests + + # Update DNS + update_dns_records "$(lookup params.base_domain)" +else + echo "Deployment failed - check logs" + notify_ops_team "Deployment of $GENESIS_ENVIRONMENT failed" +fi +``` + +### Advanced Hooks (Perl Modules) + +For complex kits, hooks can be written as Perl modules: + +#### Addon Hook Module + +```perl +package Genesis::Hook::Addon::MyKit::backup; +use parent qw(Genesis::Hook::Addon); + +sub init { + my $class = shift; + my $obj = $class->SUPER::init(@_); + $obj->check_minimum_genesis_version('3.1.0'); + return $obj; +} + +sub perform { + my ($self) = @_; + + # Parse options + my %options = $self->parse_options(['force']); + + # Execute backup + my $result = $self->env->bosh->run_errand('backup'); + + return $self->done($result); +} + +sub cmd_details { + return "Performs a backup of the deployment"; +} + +1; +``` + +## Hook Environment Variables + +Hooks have access to these environment variables: + +### Always Available + +- `GENESIS_ROOT` - Repository root directory +- `GENESIS_ENVIRONMENT` - Environment name +- `GENESIS_VAULT_PREFIX` - Vault path prefix +- `GENESIS_KIT_NAME` - Kit name +- `GENESIS_KIT_VERSION` - Kit version +- `GENESIS_REQUESTED_FEATURES` - Space-separated feature list + +### Hook-Specific + +#### new Hook +- `GENESIS_MIN_VERSION` - Minimum Genesis version required + +#### blueprint Hook +- `GENESIS_REQUESTED_FEATURES` - Features to enable + +#### addon Hook +- `GENESIS_ADDON_SCRIPT` - Addon being executed +- `GENESIS_ADDON_ARGS` - Arguments passed to addon + +#### pre-deploy Hook +- `GENESIS_PREDEPLOY_DATAFILE` - File for storing pre-deploy data +- `GENESIS_MANIFEST_FILE` - Path to deployment manifest +- `GENESIS_DEPLOY_OPTIONS` - JSON deployment options + +#### post-deploy Hook +- `GENESIS_DEPLOY_RC` - Deployment return code (0=success) +- `GENESIS_PREDEPLOY_DATAFILE` - Pre-deploy data file + +## Helper Functions + +Genesis provides Bash helper functions for hooks: + +### Prompting Functions + +```bash +# Basic prompt +prompt_for varname "Question?" + +# With default +prompt_for_or_use_default varname "default" "Question?" + +# With validation +prompt_for varname "Question?" \ + --validation "/^[a-z]+$/" + +# Multiple choice +choose varname \ + "option1" "Description 1" \ + "option2" "Description 2" +``` + +### Lookup Functions + +```bash +# Get parameter value +value=$(lookup params.key default_value) + +# Check if parameter exists +if param_exists params.key; then + # Parameter is set +fi +``` + +### Feature Functions + +```bash +# Check if feature is enabled +if want_feature "monitoring"; then + # Add monitoring configuration +fi + +# Check multiple features +if features_enabled "ha" "ssl"; then + # Both features enabled +fi +``` + +### Cloud Config Functions + +```bash +# Check if resource exists +if cloud_config_has vm_type "large"; then + # VM type exists +fi + +# Get cloud config value +network=$(cloud_config_get networks.0.name) +``` + +## Best Practices + +### 1. Error Handling + +Always use proper error handling: + +```bash +#!/bin/bash +set -eu # Exit on error, undefined variables + +# Explicit error checking +if ! command_that_might_fail; then + echo >&2 "ERROR: Command failed" + exit 1 +fi +``` + +### 2. User-Friendly Output + +Use color and formatting: + +```bash +# Use describe for formatted output +describe "Setting up #C{My Software} deployment" + +# Success messages +success "Deployment configured successfully!" + +# Warnings +warning "Using default configuration" + +# Errors +error "Missing required parameter" +``` + +### 3. Idempotency + +Make hooks idempotent when possible: + +```bash +# Check before creating +if ! safe exists "$VAULT_PREFIX/generated"; then + safe gen "$VAULT_PREFIX/generated" password +fi +``` + +### 4. Validation + +Validate early and clearly: + +```bash +# In check hook +errors=() + +[[ -n "${base_domain:-}" ]] || errors+=("Missing base_domain") +[[ -n "${instances:-}" ]] || errors+=("Missing instances") + +if [[ ${#errors[@]} -gt 0 ]]; then + printf "Validation errors:\n" >&2 + printf " - %s\n" "${errors[@]}" >&2 + exit 1 +fi +``` + +### 5. Documentation + +Document complex logic: + +```bash +# Feature compatibility matrix: +# - 'ha' requires minimum 3 instances +# - 'ssl' conflicts with 'self-signed' +# - 'monitoring' adds Prometheus exporters +``` + +## Testing Hooks + +Test hooks during development: + +```bash +# Test blueprint hook +cd my-kit +export GENESIS_REQUESTED_FEATURES="ha monitoring" +./hooks/blueprint + +# Test addon hook +export GENESIS_ADDON_SCRIPT="backup" +export GENESIS_ENVIRONMENT="test" +./hooks/addon + +# Test with Genesis +genesis new test-env --kit ./ +``` + +## Common Patterns + +### Feature Detection + +```bash +# Single feature +if want_feature "ssl"; then + add_ssl_configuration +fi + +# Multiple features (OR) +if want_feature "mysql" || want_feature "postgres"; then + configure_database +fi + +# Multiple features (AND) +if want_feature "ha" && want_feature "ssl"; then + configure_ha_ssl +fi +``` + +### Dynamic Manifest Building + +```bash +#!/bin/bash +# hooks/blueprint + +manifests=(manifests/base.yml) + +# IaaS-specific +case "$(iaas)" in + aws) manifests+=(manifests/iaas/aws.yml) ;; + azure) manifests+=(manifests/iaas/azure.yml) ;; + *) manifests+=(manifests/iaas/generic.yml) ;; +esac + +# Optional features +for feature in $GENESIS_REQUESTED_FEATURES; do + [[ -f "manifests/features/$feature.yml" ]] && \ + manifests+=(manifests/features/$feature.yml) +done + +printf "%s\n" "${manifests[@]}" +``` + +### Conditional Parameters + +```bash +# In new hook +if want_feature "ha"; then + prompt_for instances \ + "Number of instances (minimum 3 for HA)?" \ + --validation "/^[3-9][0-9]*$/" +else + prompt_for instances \ + "Number of instances?" \ + --default 1 +fi +``` + +Hooks are the key to creating flexible, user-friendly Genesis kits that encode operational knowledge while remaining adaptable to different deployment scenarios. \ No newline at end of file diff --git a/docs/topics/50-kits/kit-structure.md b/docs/topics/50-kits/kit-structure.md new file mode 100644 index 00000000..2a80ca12 --- /dev/null +++ b/docs/topics/50-kits/kit-structure.md @@ -0,0 +1,526 @@ +# Kit Structure + +This guide details the anatomy of a Genesis kit, explaining each component and how they work together. + +## Directory Layout + +A complete Genesis kit has this structure: + +``` +my-genesis-kit/ +├── kit.yml # Kit metadata and configuration +├── hooks/ # Lifecycle scripts +│ ├── addon # Operational tasks +│ ├── blueprint # Manifest generation +│ ├── check # Pre-deployment validation +│ ├── features # Feature detection +│ ├── info # Information display +│ ├── new # Environment creation +│ ├── post-deploy # Post-deployment actions +│ ├── pre-deploy # Pre-deployment actions +│ └── secrets # Secret management +├── manifests/ # BOSH manifest templates +│ ├── base.yml # Base manifest +│ └── features/ # Feature-specific manifests +│ ├── aws.yml +│ ├── monitoring.yml +│ └── ha.yml +├── ops/ # Additional ops files (optional) +├── spec/ # Test specifications +├── ci/ # CI/CD pipeline definitions +└── README.md # Documentation + +``` + +## Core Components + +### kit.yml + +The kit metadata file defines identity and behavior: + +```yaml +# Identity +name: my-software +version: 1.2.0 +author: Genesis Community +docs: https://github.com/genesis-community/my-software-genesis-kit +code: https://github.com/genesis-community/my-software-genesis-kit + +# Description +description: | + This kit deploys My Software, providing scalable + services for your infrastructure. + +# Genesis version requirement +genesis_version_min: 2.8.0 + +# Dependencies +depends_on: + - vault + +# Provided features +provides: + - my-software-api + +# Subkits (deprecated - use features) +# subkits: [] + +# Certificates +certificates: + base: + server/ca: + ca: + valid_for: 10y + names: ["My Software CA"] + server/cert: + server: + valid_for: 1y + names: ["server.${params.base_domain}"] + signed_by: server/ca + +# Credentials +credentials: + base: + admin: + password: random 32 + system/db: + username: dbadmin + password: random 40 fmt base64 + +# User-provided secrets +provided: + base: + external/api: + keys: + - client_id + - client_secret +``` + +### Manifest Files + +#### Base Manifest (manifests/base.yml) + +The foundation all deployments build upon: + +```yaml +--- +# Basic structure +name: (( grab params.env )) + +# Releases +releases: +- name: my-software + version: 3.4.5 + url: https://github.com/.../my-software-3.4.5.tgz + sha1: abc123def456... + +# Stemcells +stemcells: +- alias: default + os: ubuntu-jammy + version: latest + +# Update settings +update: + canaries: 1 + max_in_flight: 1 + canary_watch_time: 1000-60000 + update_watch_time: 1000-60000 + serial: false + +# Instance groups +instance_groups: +- name: api + instances: (( grab params.api_instances || 1 )) + vm_type: (( grab params.api_vm_type || "default" )) + stemcell: default + networks: + - name: (( grab params.network || "default" )) + jobs: + - name: api + release: my-software + properties: + api: + port: 8080 + admin_password: (( vault "secret/" params.vault "/admin:password" )) + +# Required parameters +params: + env: (( param "What environment is this?" )) + network: (( param "What network should VMs be placed on?" )) +``` + +#### Feature Manifests (manifests/features/) + +Modifications applied when features are enabled: + +```yaml +# manifests/features/ha.yml +--- +# Enable high availability +- type: replace + path: /instance_groups/name=api/instances + value: 3 + +- type: replace + path: /instance_groups/name=api/jobs/name=api/properties/api/cluster? + value: + enabled: true + quorum: 2 + +# Add load balancer +- type: replace + path: /instance_groups/- + value: + name: haproxy + instances: 2 + vm_type: (( grab params.haproxy_vm_type || "small" )) + stemcell: default + networks: + - name: (( grab params.network )) + jobs: + - name: haproxy + release: haproxy + properties: + ha_proxy: + backend_port: 8080 + backend_servers: (( grab instance_groups.api.networks[0].static_ips )) +``` + +### Hook Scripts + +#### blueprint Hook + +Determines which manifests to merge: + +```bash +#!/bin/bash +set -eu + +# Start with base +manifests=( manifests/base.yml ) + +# Add features +for want in $GENESIS_REQUESTED_FEATURES; do + case "$want" in + # Infrastructure features + aws|azure|gcp|vsphere|openstack) + manifests+=( manifests/iaas/$want.yml ) + ;; + + # Standard features + ha|monitoring|shield) + manifests+=( manifests/features/$want.yml ) + ;; + + # Implicit features + +internal-db) + manifests+=( manifests/addons/internal-db.yml ) + ;; + + *) + echo >&2 "Unrecognized feature: $want" + exit 1 + ;; + esac +done + +# Output manifest list +printf "%s\n" "${manifests[@]}" +``` + +#### new Hook + +Interactive environment creation: + +```bash +#!/bin/bash +set -eu + +# Load Genesis helpers +source $GENESIS_ROOT/.genesis/lib/genesis.sh + +# Basic information +describe "Setting up new My Software deployment" +echo + +# Required parameters +prompt_for base_domain \ + "What is your base domain (e.g., example.com)?" \ + --validation dns_domain + +# Optional parameters with defaults +prompt_for_or_use_default api_instances "1" \ + "How many API instances do you want?" + +# Feature selection +if features_enabled ha; then + prompt_for_or_use_default api_instances "3" \ + "How many API instances? (minimum 3 for HA)" +fi + +# Infrastructure selection +infrastructure_menu() { + describe "Select your infrastructure:" + choose "aws" "Amazon Web Services" \ + "azure" "Microsoft Azure" \ + "gcp" "Google Cloud Platform" \ + "vsphere" "VMware vSphere" \ + "openstack" "OpenStack" +} + +infrastructure=$(infrastructure_menu) +features+=( "$infrastructure" ) + +# Save configuration +param_entry params.base_domain "$base_domain" +param_entry params.api_instances "$api_instances" +``` + +#### check Hook + +Validate before deployment: + +```bash +#!/bin/bash +set -eu + +# Check BOSH +describe "Validating BOSH environment..." + +# Verify cloud config +for type in vm network disk; do + value=$(lookup params.${type}_type "default") + if ! bosh_cloud_config_has ${type}_type "$value"; then + fail "Cloud config missing ${type} type '$value'" + fi +done + +# Verify secrets +describe "Checking Vault secrets..." + +if want_feature provided-cert; then + for secret in ssl/server:certificate ssl/server:key; then + if ! safe exists "$GENESIS_SECRETS_BASE/$secret"; then + fail "Missing required secret: $secret" + fi + done +fi + +describe "#G{All checks passed!}" +``` + +#### info Hook + +Display deployment information: + +```bash +#!/bin/bash +set -eu + +base_domain=$(lookup params.base_domain) +url="https://api.$base_domain" +username="admin" +password=$(safe get "$GENESIS_SECRETS_BASE/admin:password") + +describe "#Yi{My Software Deployment Information}" +echo +describe " API URL: #C{$url}" +describe " Username: #C{$username}" +describe " Password: #C{$password}" +echo +describe "Need to do something? Try these addons:" +echo +genesis do "$GENESIS_ENVIRONMENT" list +``` + +#### addon Hook + +Operational tasks: + +```bash +#!/bin/bash +set -eu + +list() { + describe "Available addons:" + describe " #G{login} Login to API" + describe " #G{setup} Initial setup" + describe " #G{backup} Run backup" + describe " #G{restore} Restore from backup" +} + +case $GENESIS_ADDON_SCRIPT in + list) list ;; + + login) + api_url="https://api.$(lookup params.base_domain)" + password=$(safe get "$GENESIS_SECRETS_BASE/admin:password") + + describe "Logging into $api_url..." + curl -X POST "$api_url/login" \ + -d "username=admin&password=$password" \ + -c cookie.txt + ;; + + backup) + describe "Running backup errand..." + genesis bosh run-errand backup + ;; + + *) + echo >&2 "Unrecognized addon: $GENESIS_ADDON_SCRIPT" + list >&2 + exit 1 + ;; +esac +``` + +### Supporting Files + +#### spec/ - Test Specifications + +Ginkgo tests for validating kit behavior: + +```go +// spec/spec_test.go +var _ = Describe("My Software Kit", func() { + BeforeEach(func() { + kit = "my-software" + version = "latest" + }) + + Context("Base Manifest", func() { + BeforeEach(func() { + features = []string{} + }) + + It("should deploy with defaults", func() { + manifest := GetManifest() + Expect(manifest.Name).To(Equal("my-env-my-software")) + + ig := manifest.InstanceGroups.Lookup("api") + Expect(ig.Instances).To(Equal(1)) + }) + }) + + Context("HA Feature", func() { + BeforeEach(func() { + features = []string{"ha"} + }) + + It("should scale instances", func() { + manifest := GetManifest() + + ig := manifest.InstanceGroups.Lookup("api") + Expect(ig.Instances).To(Equal(3)) + }) + }) +}) +``` + +#### ci/ - Pipeline Configuration + +Concourse pipeline for testing: + +```yaml +# ci/pipeline.yml +resources: +- name: git + type: git + source: + uri: ((github.uri)) + branch: develop + +- name: version + type: semver + source: + driver: git + uri: ((github.uri)) + branch: version + file: version + +jobs: +- name: test + plan: + - get: git + trigger: true + - task: test-kit + file: git/ci/tasks/test.yml + +- name: release + plan: + - aggregate: + - get: git + passed: [test] + - get: version + params: {bump: final} + - task: release + file: git/ci/tasks/release.yml + - put: version + params: {file: version/version} +``` + +## File Interactions + +### Manifest Assembly Flow + +1. **Genesis** calls `blueprint` hook +2. **Blueprint** returns ordered manifest list +3. **Genesis** merges manifests with Spruce +4. **Parameters** from environment file applied +5. **Secrets** retrieved from Vault +6. **Final manifest** sent to BOSH + +### Secret Generation Flow + +1. **Kit.yml** defines required secrets +2. **Genesis** checks Vault for existence +3. **Missing secrets** generated automatically +4. **Manifests** reference via `(( vault ))` operator + +### Hook Execution Order + +1. **features** - Determine active features +2. **new** - Create new environment (once) +3. **blueprint** - Generate manifest list +4. **secrets** - Manage secrets +5. **check** - Validate configuration +6. **pre-deploy** - Pre-deployment tasks +7. *[Genesis deploys to BOSH]* +8. **post-deploy** - Post-deployment tasks +9. **info** - Display information +10. **addon** - Run operational tasks + +## Best Practices + +### Manifest Organization + +- Keep `base.yml` minimal and focused +- One feature per file in `features/` +- Use ops file format for modifications +- Document parameter requirements + +### Hook Guidelines + +- Always `set -eu` for safety +- Use Genesis helper functions +- Provide helpful error messages +- Make scripts idempotent + +### Testing Structure + +- Test base configuration +- Test each feature independently +- Test feature combinations +- Validate error conditions + +### Documentation + +Always include: +- README.md with examples +- Parameter documentation +- Feature descriptions +- Upgrade notes + +Understanding kit structure helps you create maintainable, reusable deployment templates that encode your operational knowledge. \ No newline at end of file diff --git a/docs/topics/50-kits/kit-testing.md b/docs/topics/50-kits/kit-testing.md new file mode 100644 index 00000000..b2cde69a --- /dev/null +++ b/docs/topics/50-kits/kit-testing.md @@ -0,0 +1,516 @@ +# Kit Testing + +Testing Genesis kits ensures they work correctly across different scenarios and configurations. This guide covers testing strategies, tools, and best practices. + +## Testing Overview + +Kit testing involves: +- Unit testing individual hooks +- Integration testing with Genesis +- Manifest generation validation +- Secret generation verification +- Deployment testing with BOSH + +## Testing Tools + +### Spec Testing with Ginkgo + +Genesis kits use Ginkgo for automated testing: + +```bash +# Install Ginkgo +go get -u github.com/onsi/ginkgo/ginkgo +go get -u github.com/onsi/gomega/... + +# Run tests +cd spec +ginkgo -p +``` + +### Basic Spec Structure + +```go +// spec/spec_test.go +package spec_test + +import ( + . "github.com/genesis-community/testkit/testing" + . "github.com/onsi/ginkgo" + . "github.com/onsi/gomega" +) + +var _ = Describe("My Kit", func() { + kit := "my-software" + + Context("Base Manifest", func() { + BeforeEach(func() { + Setup(kit, "default") + }) + + It("uses the requested VM type", func() { + manifest := Manifest( + WithParam("vm_type", "large"), + ) + Expect(manifest).To(HaveInstanceGroup("my-software", + WithVMType("large"))) + }) + }) +}) +``` + +## Hook Testing + +### Testing the `new` Hook + +Create a test wrapper for the `new` hook: + +```bash +#!/bin/bash +# test/test-new-hook.sh + +# Mock Genesis environment +export GENESIS_ROOT="/tmp/test-$$" +export GENESIS_ENVIRONMENT="test-env" +export GENESIS_SECRETS_PATH="test/env" +export GENESIS_MIN_VERSION="2.8.0" + +mkdir -p "$GENESIS_ROOT" + +# Mock prompt_for responses +cat > /tmp/responses </dev/null; then + echo "FAIL: Invalid VM type not caught" + exit 1 +fi + +echo "PASS: check hook test" +``` + +## Manifest Testing + +### Testing Manifest Generation + +```bash +#!/bin/bash +# test/test-manifests.sh + +kit_dir="$(cd ..; pwd)" + +# Test base manifest +genesis compile-kit --dev --name test +genesis new test-base --kit test + +# Validate structure +genesis manifest test-base > /tmp/manifest.yml +bosh int /tmp/manifest.yml --path /name | grep -q "test-base" +``` + +### Spec Tests for Manifests + +```go +var _ = Describe("Manifest Generation", func() { + Context("with HA feature", func() { + BeforeEach(func() { + Setup(kit, "ha") + }) + + It("creates 3 instances", func() { + manifest := Manifest() + ig := manifest.InstanceGroups.Lookup("my-software") + Expect(ig.Instances).To(Equal(3)) + }) + + It("enables clustering", func() { + manifest := Manifest() + props := manifest.InstanceGroups.Lookup("my-software"). + Jobs[0].Properties + Expect(props).To(HaveKeyWithValue("cluster", + HaveKeyWithValue("enabled", true))) + }) + }) +}) +``` + +## Secret Testing + +### Testing Secret Generation + +```go +var _ = Describe("Secrets", func() { + It("generates required passwords", func() { + manifest := Manifest() + + // Check password references + Expect(manifest).To(HaveSecret("admin_password")) + Expect(manifest).To(HaveSecret("database_password")) + }) + + It("generates certificates with correct SANs", func() { + manifest := Manifest( + WithParam("base_domain", "example.com"), + ) + + cert := GetCertificate("server") + Expect(cert.SANs).To(ContainElement("*.example.com")) + }) +}) +``` + +### Manual Secret Testing + +```bash +#!/bin/bash +# test/test-secrets.sh + +# Create test Vault +safe target test --memory +safe auth + +# Test secret generation +export VAULT_PREFIX="secret/test" +genesis add-secrets test-env + +# Verify secrets created +safe exists secret/test/admin:password || exit 1 +safe exists secret/test/ssl/ca:certificate || exit 1 + +echo "PASS: Secrets generated correctly" +``` + +## Integration Testing + +### Full Deployment Test + +```bash +#!/bin/bash +# test/integration-test.sh + +# Setup +genesis init --kit ../my-kit test-deployments +cd test-deployments + +# Create test environment +genesis new integration-test < /dev/null + + local end=$(date +%s.%N) + echo "$features: $(echo "$end - $start" | bc)s" +} + +# Test different feature combinations +time_genesis "" +time_genesis "ha" +time_genesis "ha monitoring ssl" +``` + +### Memory Usage + +```bash +# Monitor memory during tests +/usr/bin/time -v genesis manifest large-env 2>&1 | \ + grep "Maximum resident set size" +``` + +Testing thoroughly ensures your kit works reliably across all supported configurations and provides a good user experience. \ No newline at end of file diff --git a/docs/topics/50-kits/overview.md b/docs/topics/50-kits/overview.md new file mode 100644 index 00000000..74e8b4e7 --- /dev/null +++ b/docs/topics/50-kits/overview.md @@ -0,0 +1,292 @@ +# Genesis Kits Overview + +Genesis Kits are the heart of the Genesis deployment system. They encapsulate years of operational experience into reusable, parameterized templates that make deploying complex software simple and repeatable. + +## What Is a Kit? + +A Genesis Kit is a packaged collection of: + +- **Manifest Templates** - YAML files defining BOSH deployments +- **Configuration Defaults** - Sensible default values +- **Feature Definitions** - Optional components and variations +- **Secret Specifications** - What credentials to generate +- **Lifecycle Hooks** - Scripts for customization and validation +- **Documentation** - Usage instructions and examples + +Think of a kit as a blueprint for deploying a specific type of software, complete with all the knowledge needed to do it right. + +## Why Use Kits? + +### Without Kits + +Deploying software with BOSH traditionally requires: +- Writing hundreds of lines of YAML +- Understanding every configuration option +- Managing credentials manually +- Keeping up with best practices +- Avoiding common pitfalls + +### With Kits + +Genesis Kits provide: +- **Pre-built configurations** - Start with working defaults +- **Curated options** - Only expose what matters +- **Automatic secrets** - Credentials generated for you +- **Built-in validation** - Catch errors before deployment +- **Community knowledge** - Best practices built in + +## How Kits Work + +### 1. Kit Selection + +Choose a kit for what you want to deploy: + +```yaml +kit: + name: vault # Deploy HashiCorp Vault + version: 1.5.0 # Specific kit version +``` + +### 2. Feature Activation + +Enable optional components: + +```yaml +kit: + features: + - consul # Use Consul backend + - monitoring # Enable Prometheus metrics + - auto-unseal # AWS KMS auto-unseal +``` + +### 3. Parameter Configuration + +Provide environment-specific values: + +```yaml +params: + env: production + vault_disk_size: 50_GB + availability_zones: + - us-east-1a + - us-east-1b + - us-east-1c +``` + +### 4. Manifest Generation + +Genesis combines: +- Kit base manifests +- Feature modifications +- Your parameters +- Generated secrets + +Into a complete BOSH manifest. + +## Kit Components + +### Base Manifest + +The foundation all deployments start from: + +```yaml +# manifests/base.yml +name: (( grab params.env )) +instance_groups: +- name: vault + instances: 3 + vm_type: (( grab params.vm_type )) + jobs: + - name: vault + release: vault + properties: + # Sensible defaults here +``` + +### Features + +Optional modifications: + +```yaml +# manifests/features/consul.yml +instance_groups: +- name: vault + jobs: + - name: vault + properties: + vault: + backend: + type: consul + consul: + address: (( grab params.consul_address )) +``` + +### Hooks + +Lifecycle automation: + +```bash +#!/bin/bash +# hooks/new +prompt_for "vault_disk_size" \ + "How much disk space for Vault data?" \ + --default "10G" +``` + +### Secrets Definition + +```yaml +# kit.yml +credentials: + base: + vault/seal: + seal_key: random 32 fmt base64 +``` + +## Kit Lifecycle + +### Development Time + +1. **Author creates kit** - Encodes deployment knowledge +2. **Testing and refinement** - Validates across scenarios +3. **Release** - Published for community use + +### Deployment Time + +1. **Operator selects kit** - Chooses software to deploy +2. **Configuration** - Provides environment details +3. **Generation** - Genesis creates full manifest +4. **Deployment** - BOSH deploys the software + +### Operational Time + +1. **Updates** - New kit versions bring improvements +2. **Modifications** - Features can be added/removed +3. **Maintenance** - Hooks provide operational tasks + +## Types of Kits + +### Infrastructure Kits + +Deploy foundational services: +- **BOSH** - BOSH directors +- **Vault** - Secret management +- **Concourse** - CI/CD systems + +### Platform Kits + +Deploy application platforms: +- **Cloud Foundry** - PaaS platform +- **Kubernetes** - Container orchestration +- **Nomad** - Workload scheduling + +### Service Kits + +Deploy supporting services: +- **PostgreSQL** - Databases +- **RabbitMQ** - Message queues +- **Elasticsearch** - Search and analytics + +### Monitoring Kits + +Deploy observability stacks: +- **Prometheus** - Metrics collection +- **Grafana** - Visualization +- **ELK Stack** - Log aggregation + +## Kit Philosophy + +### 1. Convention Over Configuration + +Kits make reasonable assumptions: +- Standard network names +- Common VM types +- Typical sizing + +While allowing overrides when needed. + +### 2. Progressive Disclosure + +Start simple: +```yaml +kit: + name: vault +``` + +Add complexity as needed: +```yaml +kit: + name: vault + features: [consul, monitoring, auto-unseal] +params: + vault_instances: 5 + vault_vm_type: large +``` + +### 3. Operational Experience + +Kits encode real-world lessons: +- Recommended instance counts +- Proven update strategies +- Common troubleshooting steps + +## Kit Benefits + +### For Operators + +- **Faster deployments** - Minutes instead of days +- **Fewer mistakes** - Validation catches errors +- **Consistent environments** - Same kit = same setup +- **Easy updates** - Kit versions bring improvements + +### For Organizations + +- **Standardization** - Consistent across teams +- **Knowledge sharing** - Best practices in code +- **Reduced training** - Simpler operations +- **Compliance** - Security built in + +### For the Community + +- **Shared improvements** - Everyone benefits +- **Collective knowledge** - Lessons learned together +- **Reduced duplication** - Solve problems once + +## Getting Started with Kits + +### Using Existing Kits + +1. Browse available kits: + ```bash + genesis kits + ``` + +2. Initialize with a kit: + ```bash + genesis init --kit vault + ``` + +3. Deploy: + ```bash + genesis new prod-vault + genesis deploy prod-vault + ``` + +### Creating New Kits + +1. Start from template: + ```bash + genesis create-kit my-software + ``` + +2. Define your manifest structure +3. Add features and hooks +4. Test thoroughly +5. Share with community + +## Next Steps + +- Learn to [Use Kits](using-kits.md) +- Explore [Available Kits](available-kits.md) +- Understand [Kit Features](features.md) +- Start [Authoring Kits](authoring-kits.md) \ No newline at end of file diff --git a/docs/topics/50-kits/using-kits.md b/docs/topics/50-kits/using-kits.md new file mode 100644 index 00000000..723a1a54 --- /dev/null +++ b/docs/topics/50-kits/using-kits.md @@ -0,0 +1,486 @@ +# Using Genesis Kits + +This guide covers how to find, select, and use Genesis kits for your deployments. + +## Finding Kits + +### Official Kit Repositories + +Genesis kits are hosted on GitHub: +- **Organization**: https://github.com/genesis-community +- **Naming Convention**: `*-genesis-kit` + +### Listing Available Kits + +```bash +# List all known kits +genesis kits + +# Example output: +# BOSH Genesis Kit - https://github.com/genesis-community/bosh-genesis-kit +# Cloud Foundry Genesis Kit - https://github.com/genesis-community/cf-genesis-kit +# Vault Genesis Kit - https://github.com/genesis-community/vault-genesis-kit +``` + +### Getting Kit Information + +```bash +# Get detailed information about a kit +genesis info vault + +# Shows: +# - Current versions +# - Available features +# - Configuration parameters +# - Recent changes +``` + +## Selecting a Kit + +### During Repository Initialization + +```bash +# Initialize new repository with specific kit +genesis init --kit vault my-vault-deployments + +# Lists kits if not specified +genesis init my-deployments +> Select a kit: +> 1) bosh +> 2) cf +> 3) vault +> 4) concourse +``` + +### Kit Versioning + +Kits use semantic versioning (MAJOR.MINOR.PATCH): + +```yaml +# Specific version (recommended for production) +kit: + name: vault + version: 1.5.0 + +# Latest version (useful for development) +kit: + name: vault + version: latest + +# Version constraints (future feature) +kit: + name: vault + version: "~> 1.5" # Any 1.5.x version +``` + +## Understanding Kit Features + +### What Are Features? + +Features are optional kit components that modify the deployment: +- Infrastructure adaptations (AWS, Azure, vSphere) +- Add-on functionality (monitoring, backups) +- Architectural choices (HA, standalone) + +### Listing Available Features + +```bash +# During environment creation +genesis new my-env +> Which Vault backend would you like to use? +> 1) consul - Consul-backed storage +> 2) raft - Integrated Raft storage +> 3) file - File-based storage (dev only) + +# From kit info +genesis info vault --features +``` + +### Common Feature Patterns + +#### Infrastructure Features +```yaml +kit: + features: + - aws # AWS-specific configuration + - azure # Azure-specific configuration + - vsphere # vSphere-specific configuration +``` + +#### Functional Features +```yaml +kit: + features: + - monitoring # Prometheus exporters + - backups # Automated backup support + - ha # High availability mode +``` + +#### Integration Features +```yaml +kit: + features: + - ldap # LDAP authentication + - github-oauth # GitHub OAuth integration + - provided-cert # User-provided certificates +``` + +## Configuring Deployments + +### Required Parameters + +Kits define required parameters that must be set: + +```yaml +params: + # Always required + env: prod-vault + + # Kit-specific requirements + vault_disk_pool: fast-ssd + availability_zones: + - z1 + - z2 + - z3 +``` + +### Optional Parameters + +Customize behavior with optional parameters: + +```yaml +params: + # Override defaults + vault_instances: 5 # Default might be 3 + vault_vm_type: large # Default might be default + + # Feature-specific + consul_servers: # Only with consul feature + - 10.0.1.10 + - 10.0.1.11 + - 10.0.1.12 +``` + +### Parameter Discovery + +Find available parameters: + +1. **Kit documentation** + ```bash + genesis info vault --params + ``` + +2. **Environment file comments** + ```yaml + # Generated by genesis new + params: + # env: Name of your environment + env: my-env + ``` + +3. **Kit source code** + ```bash + # Check kit manifests + cat .genesis/kits/vault-1.5.0/manifests/base.yml + ``` + +## Working with Kit Versions + +### Upgrading Kits + +```yaml +# Before - old version +kit: + name: vault + version: 1.4.0 + +# After - new version +kit: + name: vault + version: 1.5.0 +``` + +Then redeploy: +```bash +genesis deploy my-env +``` + +### Version Compatibility + +Check compatibility before upgrading: +```bash +# Compare versions +genesis diff-kits vault 1.4.0 1.5.0 + +# Check breaking changes +genesis info vault --version 1.5.0 --changes +``` + +### Pinning Versions + +For production stability: +```yaml +# Always pin to specific versions +kit: + name: vault + version: 1.5.0 # NOT 'latest' +``` + +## Kit Development Mode + +### Using Local Kits + +For testing modifications: + +```bash +# Create dev directory +cd my-vault-deployments +mkdir dev + +# Copy and modify kit +cp -r .genesis/kits/vault-1.5.0/* dev/ + +# Use dev kit +cat > test-env.yml < ops/scale-up.yml < "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" < "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" <> "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" <> "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" </dev/null; then + echo >&2 "ERROR: jq is required but not installed" + exit 1 +fi + +# Validate critical inputs +if [[ -z "${base_domain:-}" ]]; then + echo >&2 "ERROR: base_domain cannot be empty" + exit 1 +fi +``` + +### 5. Idempotency + +Make hooks re-runnable: + +```bash +# Check if already configured +if [[ -f "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" ]]; then + prompt_for overwrite boolean \ + "Environment already exists. Overwrite?" \ + --default n + + [[ $overwrite == "false" ]] && exit 0 +fi +``` + +## Testing Your Hook + +### Manual Testing + +```bash +cd my-kit + +# Set test environment +export GENESIS_ROOT="/tmp/test" +export GENESIS_ENVIRONMENT="test-env" +export GENESIS_SECRETS_PATH="test/env" + +# Run hook +./hooks/new + +# Check output +cat /tmp/test/test-env.yml +``` + +### Automated Testing + +Create test scripts: + +```bash +#!/bin/bash +# test-new-hook.sh + +# Mock prompt_for +prompt_for() { + local var=$1 + local type=$2 + case "$var" in + base_domain) eval "$var='test.example.com'" ;; + use_ha) eval "$var='true'" ;; + instances) eval "$var='3'" ;; + esac +} + +# Source and run hook +source hooks/new + +# Validate output +grep -q "base_domain: test.example.com" "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" +``` + +## Common Patterns + +### IaaS-Specific Configuration + +```bash +case $iaas in + aws) + prompt_for aws_region line \ + 'AWS Region?' \ + --default 'us-east-1' + ;; + azure) + prompt_for azure_region line \ + 'Azure Region?' \ + --default 'eastus' + ;; + vsphere) + prompt_for vcenter_ip line \ + 'vCenter IP address?' \ + --validation ip + ;; +esac +``` + +### Database Selection + +```bash +prompt_for database select \ + 'Which database backend?' \ + -o '[postgres] PostgreSQL' \ + -o '[mysql] MySQL' \ + -o '[none] No database' + +if [[ $database != "none" ]]; then + features+=("$database") + + prompt_for db_persistent boolean \ + 'Use persistent disk for database?' + + if [[ $db_persistent == "true" ]]; then + prompt_for db_disk_size line \ + 'Database disk size?' \ + --default '10GB' + fi +fi +``` + +Writing effective hooks makes your kit user-friendly and reduces deployment errors by guiding users through configuration with appropriate validations and helpful defaults. \ No newline at end of file diff --git a/docs/topics/60-bosh/.keep b/docs/topics/60-bosh/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/60-bosh/bosh-directors.md b/docs/topics/60-bosh/bosh-directors.md new file mode 100644 index 00000000..d3ee969c --- /dev/null +++ b/docs/topics/60-bosh/bosh-directors.md @@ -0,0 +1,432 @@ +# BOSH Directors + +The BOSH Director is the core component that orchestrates deployments. This guide covers deploying and managing BOSH directors using Genesis. + +## Overview + +A BOSH Director: +- Manages the lifecycle of VMs and software +- Stores deployment state and configuration +- Monitors health and resurrects failed VMs +- Handles persistent disks and snapshots +- Manages releases, stemcells, and deployments + +## Deploying a BOSH Director with Genesis + +Genesis provides a BOSH kit for deploying directors: + +### Initial Setup + +```bash +# Create a new BOSH deployment repository +genesis init my-bosh --kit bosh +cd my-bosh + +# Create a new BOSH environment +genesis new my-bosh +``` + +### Configuration Options + +The BOSH kit will prompt for: + +1. **Static IP Address**: The director's IP +2. **IaaS Selection**: AWS, Azure, GCP, vSphere, etc. +3. **Network Configuration**: Subnet, gateway, DNS +4. **IaaS Credentials**: Cloud provider access + +### Example Environment File + +```yaml +--- +genesis: + env: my-bosh + secrets_path: my/bosh + +kit: + features: + - aws + - proto-bosh + - bosh-init + +params: + # Static IP for director + static_ip: 10.0.0.6 + + # AWS Configuration + aws_region: us-east-1 + aws_default_sgs: + - sg-0123456789abcdef0 # BOSH security group + + # Network Configuration + subnet_id: subnet-0123456789abcdef0 + external_domain: bosh.example.com + + # Director Name + director_name: my-bosh +``` + +### Deployment + +```bash +# Deploy the BOSH director +genesis deploy my-bosh + +# This will: +# 1. Create the director VM +# 2. Install BOSH software +# 3. Configure the database +# 4. Start BOSH services +``` + +## Proto-BOSH vs Regular BOSH + +### Proto-BOSH + +The first BOSH director in an environment (bootstrapping): +- Deployed using `bosh create-env` +- Manages its own lifecycle +- Requires the `proto-bosh` feature + +```yaml +kit: + features: + - proto-bosh + - aws +``` + +### Regular BOSH + +Subsequent directors managed by another BOSH: +- Deployed using standard `bosh deploy` +- Managed by a parent director +- More resilient and easier to update + +```yaml +kit: + features: + - aws + # No proto-bosh feature +``` + +## Managing Multiple Directors + +### Director Hierarchy + +Common patterns: + +``` +proto-bosh (global) +├── regional-bosh-us-east +├── regional-bosh-us-west +└── regional-bosh-eu-west + ├── env-bosh-dev + ├── env-bosh-staging + └── env-bosh-prod +``` + +### Configuration Management + +Use hierarchical configuration: + +```yaml +# global.yml +params: + trusted_certs: | + -----BEGIN CERTIFICATE----- + # Corporate CA cert + -----END CERTIFICATE----- + +# us-east.yml +params: + aws_region: us-east-1 + ntp_servers: + - 0.amazon.pool.ntp.org + - 1.amazon.pool.ntp.org + +# us-east-prod.yml +params: + static_ip: 10.0.0.6 + director_name: us-east-prod-bosh +``` + +## Director Features + +### Core Features + +Available in all deployments: +- **Health Monitor**: VM monitoring and resurrection +- **Database**: PostgreSQL for state storage +- **NATS**: Message bus for agent communication +- **Blobstore**: Release and package storage + +### Optional Features + +Enable via kit features: + +#### UAA Authentication + +```yaml +kit: + features: + - uaa +params: + uaa_admin_client_secret: ((uaa-admin-secret)) +``` + +#### CredHub Integration + +```yaml +kit: + features: + - credhub +params: + credhub_encryption_password: ((credhub-encryption)) +``` + +#### Compiled Releases + +```yaml +kit: + features: + - compiled-releases +params: + compiled_releases_bucket: my-compiled-releases +``` + +#### BBR (BOSH Backup and Restore) + +```yaml +kit: + features: + - bbr +``` + +## Director Operations + +### Accessing the Director + +```bash +# Get connection info +genesis bosh my-bosh + +# Target the director +export BOSH_ENVIRONMENT=10.0.0.6 +export BOSH_CLIENT=admin +export BOSH_CLIENT_SECRET=$(safe get secret/my/bosh/director:password) +export BOSH_CA_CERT=$(safe get secret/my/bosh/director:ca) + +# Verify connection +bosh env +``` + +### Common Management Tasks + +#### Update Cloud Config + +```bash +# After deploying director +bosh update-cloud-config cloud-config.yml + +# Verify +bosh cloud-config +``` + +#### Upload Stemcells + +```bash +# Upload Ubuntu stemcell +bosh upload-stemcell \ + https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# List stemcells +bosh stemcells +``` + +#### Manage Releases + +```bash +# Upload releases +bosh upload-release \ + https://bosh.io/d/github.com/cloudfoundry/cf-deployment + +# View releases +bosh releases +``` + +### Director Maintenance + +#### Updating the Director + +```bash +# Update BOSH deployment +genesis deploy my-bosh + +# This safely: +# 1. Updates director software +# 2. Migrates database if needed +# 3. Restarts services +``` + +#### Backing Up the Director + +```bash +# Using BBR +genesis do my-bosh -- backup + +# Manual backup +genesis do my-bosh -- bash +bosh create-env backup.yml \ + --vars-store backup-creds.yml +``` + +#### Monitoring Director Health + +```bash +# Check director status +bosh env + +# View director tasks +bosh tasks --recent + +# Check VM vitals +genesis do my-bosh -- bosh vms --vitals +``` + +## Advanced Configuration + +### Custom Properties + +```yaml +params: + # Database settings + postgres_max_connections: 100 + + # Director settings + director_worker_count: 8 + director_enable_snapshots: true + + # Health monitor + hm_email_recipients: + - ops-team@example.com + hm_email_from: bosh@example.com + + # Blobstore + blobstore_type: s3 + blobstore_bucket: my-bosh-blobstore +``` + +### Network Configuration + +```yaml +params: + # Multiple networks + networks: + - name: bosh + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + static: [10.0.0.6] + dns: [10.0.0.2] + cloud_properties: + subnet: subnet-0123456 +``` + +### Security Hardening + +```yaml +params: + # Remove default users + remove_dev_users: true + + # Enable audit logging + director_enable_audit: true + + # Restrict API access + director_api_accept_from: + - 10.0.0.0/16 + - 192.168.0.0/16 +``` + +## Troubleshooting Directors + +### Common Issues + +#### Director Unreachable + +```bash +# Check VM status (if using proto-bosh) +cd my-bosh-deployments +bosh create-env manifests/bosh.yml \ + --state state.json \ + --vars-store creds.yml + +# Check network connectivity +ping 10.0.0.6 +nc -zv 10.0.0.6 25555 +``` + +#### Database Issues + +```bash +# SSH to director +genesis do my-bosh -- bosh ssh + +# Check PostgreSQL +sudo -u vcap psql -U postgres +\l # List databases +\q # Quit + +# Check logs +sudo tail -f /var/vcap/sys/log/postgres/*.log +``` + +#### Certificate Issues + +```bash +# Regenerate certificates +safe x509 renew secret/my/bosh/director + +# Redeploy +genesis deploy my-bosh +``` + +### Recovery Procedures + +#### Restore from Backup + +```bash +# Using BBR +genesis do my-bosh -- restore --artifact-path=./backup + +# Manual restore +bosh create-env restore.yml \ + --state state.json \ + --vars-store creds.yml +``` + +#### Rebuild Director + +```bash +# Last resort - rebuild +# 1. Backup deployment manifests +# 2. Note all deployments +# 3. Redeploy director +genesis deploy my-bosh --recreate + +# 4. Restore cloud configs +# 5. Re-upload stemcells/releases +# 6. Redeploy all deployments +``` + +## Best Practices + +1. **Regular Backups**: Schedule automated BBR backups +2. **Monitor Health**: Set up alerts for director issues +3. **Update Regularly**: Keep director software current +4. **Separate Directors**: Use different directors for prod/non-prod +5. **Document Configuration**: Maintain clear documentation +6. **Test Recovery**: Regularly test backup/restore procedures + +Managing BOSH directors effectively is crucial for maintaining healthy Genesis deployments across your infrastructure. \ No newline at end of file diff --git a/docs/topics/60-bosh/bosh-overview.md b/docs/topics/60-bosh/bosh-overview.md new file mode 100644 index 00000000..f8606bfa --- /dev/null +++ b/docs/topics/60-bosh/bosh-overview.md @@ -0,0 +1,216 @@ +# BOSH Overview + +BOSH is a project that unifies release engineering, deployment, and lifecycle management of small and large-scale cloud software. Genesis builds on top of BOSH to provide a simpler, more opinionated deployment experience. + +## What is BOSH? + +BOSH is an open-source tool for release engineering, deployment, lifecycle management, and monitoring of distributed systems. Key features include: + +- **Reproducible Deployments**: BOSH ensures that deployments are reproducible across different environments +- **Health Monitoring**: Automatic monitoring and resurrection of VMs +- **Rolling Updates**: Safe, zero-downtime updates with automatic rollback +- **Multi-Cloud Support**: Works with AWS, Azure, GCP, vSphere, OpenStack, and more + +## How Genesis Uses BOSH + +Genesis acts as a layer on top of BOSH, providing: + +### 1. Simplified Manifest Generation + +Instead of writing complex BOSH manifests directly, Genesis: +- Uses kits to encapsulate best practices +- Merges environment-specific configurations +- Generates final BOSH manifests automatically + +```bash +# Genesis handles manifest generation +genesis manifest my-env + +# Equivalent to complex BOSH manifest management +bosh -d my-deployment manifest +``` + +### 2. Streamlined Deployment Workflow + +Genesis wraps BOSH commands with additional features: +- Pre-deployment validation +- Secret management integration +- Post-deployment hooks + +```bash +# Genesis deployment +genesis deploy my-env + +# Handles multiple BOSH operations: +# - Uploads releases +# - Validates cloud config +# - Manages secrets +# - Deploys manifest +# - Runs errands +``` + +### 3. Environment Management + +Genesis provides a hierarchical environment structure that BOSH doesn't natively support: + +``` +environments/ +├── us.yml # Shared US configuration +├── us-east.yml # Shared US-East configuration +├── us-east-1.yml # Specific environment +└── us-east-2.yml # Another specific environment +``` + +## BOSH Components + +### BOSH Director + +The BOSH Director is the core component that orchestrates deployments: +- Manages VMs lifecycle +- Stores deployment state +- Handles persistent disks +- Monitors system health + +Genesis can deploy and manage BOSH directors using the BOSH Genesis kit: + +```bash +genesis new my-bosh --kit bosh +genesis deploy my-bosh +``` + +### Cloud Config + +Cloud configuration defines IaaS-specific settings: +- Networks and subnets +- VM types (sizes) +- Availability zones +- Disk types + +Genesis validates that required cloud config elements exist: + +```bash +# Check cloud config compatibility +genesis check my-env + +# Update cloud config +bosh update-cloud-config cloud.yml +``` + +### Releases + +BOSH releases contain the software to be deployed: +- Source code +- Configuration files +- Scripts +- Dependencies + +Genesis kits specify which releases to use: + +```yaml +# In kit.yml +releases: + - name: concourse + version: 7.8.3 + - name: postgres + version: 43 +``` + +### Stemcells + +Stemcells are base OS images that BOSH uses to create VMs: +- Ubuntu-based by default +- IaaS-specific versions +- Security-hardened + +Genesis kits define required stemcells: + +```yaml +# In kit.yml +stemcells: + - os: ubuntu-jammy + version: latest +``` + +## BOSH vs Genesis Concepts + +| BOSH Concept | Genesis Equivalent | Description | +|--------------|-------------------|-------------| +| Deployment | Environment | A running instance of software | +| Manifest | Generated from kit + environment | Deployment configuration | +| Cloud Config | Cloud Config (same) | IaaS settings | +| Runtime Config | Runtime Config (same) | Cross-deployment configuration | +| Release | Specified in kit | Software packages | +| Stemcell | Specified in kit | Base OS image | + +## BOSH State Management + +BOSH maintains state about deployments: +- Current VM instances +- Persistent disk attachments +- Network configurations +- Software versions + +Genesis respects BOSH state while adding: +- Secret rotation tracking +- Feature flag management +- Deployment history + +## Integration Points + +### Direct BOSH Commands + +You can always use BOSH commands directly: + +```bash +# Get BOSH environment details +genesis bosh my-env + +# Then use any BOSH command +bosh -d my-deployment vms +bosh -d my-deployment ssh +bosh -d my-deployment logs +``` + +### BOSH Targeting + +Genesis automatically configures BOSH targeting: + +```bash +# Genesis sets up BOSH environment +genesis do my-env -- bash +# Now $BOSH_ENVIRONMENT, $BOSH_CLIENT, etc. are set +``` + +### Deployment Names + +Genesis uses consistent deployment naming: +- Environment name: `us-east-1-prod` +- BOSH deployment: `us-east-1-prod-concourse` +- Format: `[env-name]-[kit-name]` + +## When to Use BOSH Directly + +While Genesis handles most operations, use BOSH directly for: + +1. **Debugging**: Examining VM state, logs, processes +2. **Advanced Operations**: Recreating VMs, manual resurrection +3. **Emergency Recovery**: Fixing broken deployments +4. **Custom Errands**: Running deployment-specific tasks + +```bash +# Common BOSH operations +bosh -d my-deployment vms --vitals +bosh -d my-deployment recreate web/0 +bosh -d my-deployment cloud-check +bosh -d my-deployment run-errand smoke-tests +``` + +## Best Practices + +1. **Let Genesis Handle Manifests**: Don't modify generated manifests directly +2. **Use Genesis Deploy**: Prefer `genesis deploy` over `bosh deploy` +3. **Understand the Stack**: Know when to use Genesis vs BOSH commands +4. **Monitor BOSH Health**: Keep directors updated and healthy +5. **Backup BOSH State**: Regular director database backups + +Understanding BOSH fundamentals helps you troubleshoot issues and perform advanced operations while leveraging Genesis for day-to-day deployment management. \ No newline at end of file diff --git a/docs/topics/60-bosh/bosh-troubleshooting.md b/docs/topics/60-bosh/bosh-troubleshooting.md new file mode 100644 index 00000000..8310fc35 --- /dev/null +++ b/docs/topics/60-bosh/bosh-troubleshooting.md @@ -0,0 +1,526 @@ +# BOSH Troubleshooting + +This guide helps diagnose and resolve common BOSH-related issues in Genesis deployments. + +## Common Issues + +### Deployment Failures + +#### Symptom: Deployment Times Out + +```bash +Task 1234 | Error: Timed out sending 'apply' to instance 'web/abc-123' +``` + +**Diagnosis:** +```bash +# Check task details +bosh task 1234 --debug + +# Check instance status +bosh -d my-deployment instances --ps + +# SSH to problematic instance +bosh -d my-deployment ssh web/abc-123 +``` + +**Common Causes:** +1. VM not starting properly +2. Network connectivity issues +3. BOSH agent not responding +4. Insufficient resources + +**Solutions:** +```bash +# Recreate the instance +bosh -d my-deployment recreate web/abc-123 + +# Check cloud infrastructure +bosh -d my-deployment cloud-check + +# Increase timeout (if appropriate) +bosh -d my-deployment deploy --max-in-flight=1 +``` + +#### Symptom: Package Compilation Failures + +```bash +Task 1234 | Error: Package compilation failed +``` + +**Diagnosis:** +```bash +# View compilation logs +bosh task 1234 --debug | grep -A50 "compilation failed" + +# Check compilation VMs +bosh -d my-deployment vms --details +``` + +**Solutions:** +```bash +# Use compiled releases +genesis set my-env compiled_releases true + +# Increase compilation resources +# In cloud-config.yml: +compilation: + workers: 5 + vm_type: large # Bigger VMs + network: default +``` + +### VM Issues + +#### Symptom: VMs Not Starting + +```bash +# Instance stuck in "starting" state +web/0 (abc-123) starting +``` + +**Diagnosis:** +```bash +# Check VM vitals +bosh -d my-deployment vms --vitals + +# View agent logs +bosh -d my-deployment ssh web/0 +sudo tail -f /var/vcap/bosh/log/current + +# Check monit status +sudo monit summary +``` + +**Common Issues:** +1. **Disk full:** + ```bash + df -h + # Clear logs if needed + sudo find /var/vcap/sys/log -name "*.log" -mtime +7 -delete + ``` + +2. **Memory exhausted:** + ```bash + free -m + ps aux --sort=-%mem | head + ``` + +3. **Process failing to start:** + ```bash + sudo tail -f /var/vcap/sys/log/*/current + sudo monit restart all + ``` + +#### Symptom: VM Unresponsive + +**Quick Checks:** +```bash +# From director +bosh -d my-deployment ssh web/0 -c "echo 'VM responsive'" + +# Check from director VM +ssh vcap@ + +# Network connectivity +bosh -d my-deployment ssh other-vm +ping +``` + +**Recovery:** +```bash +# Restart VM +bosh -d my-deployment restart web/0 + +# Hard recreate +bosh -d my-deployment recreate web/0 --force +``` + +### Network Issues + +#### Symptom: Cannot Reach Other VMs + +**Diagnosis:** +```bash +# Check network configuration +bosh -d my-deployment ssh web/0 +ip addr show +ip route show +cat /etc/resolv.conf + +# Test connectivity +ping +nslookup other-vm.deployment.bosh +``` + +**Common Fixes:** +1. **DNS Issues:** + ```bash + # Check BOSH DNS + sudo monit summary | grep bosh-dns + dig @169.254.0.2 google.com + + # Restart BOSH DNS + sudo monit restart bosh-dns + ``` + +2. **Firewall/Security Groups:** + ```bash + # Verify security groups (AWS) + aws ec2 describe-security-groups --group-ids sg-xxxxx + + # Test specific ports + nc -zv other-vm 8080 + ``` + +### Persistent Disk Issues + +#### Symptom: Disk Full or Missing + +**Check Disk Status:** +```bash +# List disks +bosh -d my-deployment disks + +# On VM +df -h +lsblk +mount | grep persistent +``` + +**Solutions:** + +1. **Expand Disk:** + ```yaml + # Update manifest + instance_groups: + - name: database + persistent_disk_type: large # Bigger disk type + ``` + ```bash + # Apply change + genesis deploy my-env + ``` + +2. **Migrate Data:** + ```bash + # Stop jobs + bosh -d my-deployment stop database/0 + + # Attach new disk + bosh -d my-deployment attach-disk database/0 disk-xxxxx + + # Start and migrate + bosh -d my-deployment start database/0 + ``` + +### Certificate Issues + +#### Symptom: TLS/Certificate Errors + +**Diagnosis:** +```bash +# Check certificate expiry +bosh -d my-deployment ssh web/0 +openssl x509 -in /var/vcap/jobs/web/config/cert.pem -noout -dates + +# Verify certificate chain +openssl verify -CAfile ca.pem cert.pem +``` + +**Solutions:** +```bash +# Regenerate certificates via Genesis +genesis rotate-certs my-env + +# Or manually via Vault +safe x509 renew secret/my/env/ssl/server --ttl 90d + +# Redeploy +genesis deploy my-env +``` + +## Director Issues + +### Director Unreachable + +**Quick Diagnostics:** +```bash +# Test connectivity +curl -k https://:25555/info + +# Check from jump box +nc -zv 25555 + +# Verify environment variables +echo $BOSH_ENVIRONMENT +echo $BOSH_CLIENT +``` + +**Common Fixes:** + +1. **Network Path:** + ```bash + # Trace route + traceroute + + # Check security groups/firewalls + ``` + +2. **Director Services:** + ```bash + # SSH to director (if proto-bosh) + # Check services + sudo monit summary + sudo tail -f /var/vcap/sys/log/director/current + ``` + +### Database Issues + +**Symptoms:** +- Slow deployments +- "Database is locked" errors +- Connection timeouts + +**Diagnosis:** +```bash +# On director VM +sudo -u vcap psql -U postgres +\l # List databases +\c bosh # Connect to bosh db +SELECT count(*) FROM deployments; +SELECT count(*) FROM tasks; +``` + +**Maintenance:** +```bash +# Clean old tasks +bosh clean-up --all + +# Vacuum database +sudo -u vcap psql -U postgres -d bosh -c "VACUUM ANALYZE;" + +# Restart director +sudo monit restart director +``` + +## Advanced Troubleshooting + +### Enable Debug Logging + +```bash +# For specific deployment +bosh -d my-deployment deploy manifest.yml --debug + +# For specific instance +bosh -d my-deployment ssh web/0 +sudo su - +echo "debug" > /var/vcap/bosh/etc/level +``` + +### Cloud Check + +Automated problem resolution: + +```bash +# Interactive mode +bosh -d my-deployment cloud-check + +# Automatic resolution +bosh -d my-deployment cloud-check --auto + +# Report only +bosh -d my-deployment cloud-check --report +``` + +Common resolutions: +- Recreate unresponsive VMs +- Reattach persistent disks +- Delete missing VMs from state + +### Manual State Cleanup + +**Warning: Advanced operation** + +```bash +# Export current state +bosh -d my-deployment manifest > current-manifest.yml + +# Remove instance from state +bosh -d my-deployment delete-vm + +# Recreate +bosh -d my-deployment deploy current-manifest.yml +``` + +### Task Analysis + +```bash +# List recent failed tasks +bosh tasks --recent --failed + +# Analyze specific task +bosh task --debug > task-debug.log + +# Common error patterns +grep -E "(error|failed|timeout)" task-debug.log +``` + +## Performance Issues + +### Slow Deployments + +**Diagnosis:** +```bash +# Check task timing +bosh task --event + +# Monitor director load +bosh -d director ssh +top +iostat -x 1 +``` + +**Optimizations:** + +1. **Parallel Operations:** + ```yaml + # In manifest + update: + max_in_flight: 10 # Increase parallelism + ``` + +2. **Compiled Releases:** + ```bash + # Use pre-compiled releases + bosh upload-release compiled-release.tgz + ``` + +3. **Local Blobstore:** + ```yaml + # For directors with many deployments + blobstore: + provider: local + path: /var/vcap/store/blobstore + ``` + +## Recovery Procedures + +### Emergency VM Recovery + +```bash +#!/bin/bash +# emergency-recover.sh + +DEPLOYMENT=$1 +INSTANCE=$2 + +echo "Attempting recovery of $INSTANCE in $DEPLOYMENT" + +# Stop instance +bosh -d $DEPLOYMENT stop $INSTANCE + +# Cloud check +bosh -d $DEPLOYMENT cloud-check --auto + +# Recreate +bosh -d $DEPLOYMENT recreate $INSTANCE + +# Verify +bosh -d $DEPLOYMENT instances --ps +``` + +### State File Recovery + +When deployment state is corrupted: + +```bash +# Backup current state +cp ~/.bosh/state.json state.json.backup + +# Recreate from manifest +bosh create-env manifest.yml \ + --state=state.json \ + --vars-store=creds.yml \ + --recreate + +# For managed deployments +bosh -d my-deployment deploy manifest.yml --recreate +``` + +## Monitoring and Prevention + +### Health Checks + +Regular health monitoring: + +```bash +#!/bin/bash +# bosh-health-check.sh + +echo "=== Director Health ===" +bosh env + +echo "=== Deployments ===" +bosh deployments + +echo "=== Problem Instances ===" +for d in $(bosh deployments --json | jq -r '.Tables[0].Rows[].name'); do + echo "Checking $d..." + bosh -d $d instances --ps | grep -v running || true +done + +echo "=== Recent Failed Tasks ===" +bosh tasks --recent=10 --failed +``` + +### Preventive Maintenance + +```bash +# Weekly maintenance script +#!/bin/bash + +# Clean up old releases +bosh clean-up --all + +# Check disk usage +bosh -d director ssh -c "df -h" + +# Verify backups +genesis do my-bosh -- bbr deployment backup + +# Update stemcells +bosh stemcells --recent +``` + +## Getting Help + +### Collecting Diagnostics + +When reporting issues: + +```bash +# Collect bundle +bosh -d my-deployment logs --all + +# Director info +bosh env --json > director-info.json + +# Task details +bosh task --debug > task-output.log + +# Manifest (sanitized) +bosh -d my-deployment manifest | \ + sed 's/password: .*/password: REDACTED/g' > manifest.yml +``` + +### Debug Information + +Include in bug reports: +- Genesis version: `genesis version` +- BOSH version: `bosh env` +- Kit version: `genesis kit-info` +- Error messages and task IDs +- Steps to reproduce + +Effective troubleshooting combines understanding BOSH internals with systematic diagnosis and proper tooling. \ No newline at end of file diff --git a/docs/topics/60-bosh/cloud-config.md b/docs/topics/60-bosh/cloud-config.md new file mode 100644 index 00000000..0d3da33c --- /dev/null +++ b/docs/topics/60-bosh/cloud-config.md @@ -0,0 +1,512 @@ +# Cloud Config Management + +Cloud configuration in BOSH defines IaaS-specific settings that are shared across deployments. This guide covers managing cloud configs for Genesis deployments. + +## Overview + +Cloud config separates IaaS settings from deployment manifests: +- **Networks**: Subnets, gateways, DNS servers +- **VM Types**: Instance sizes (t2.micro, Standard_DS1_v2, etc.) +- **Disk Types**: Persistent disk configurations +- **Availability Zones**: IaaS-specific zones/regions +- **Compilation**: Workers for package compilation + +## Cloud Config Structure + +### Basic Structure + +```yaml +azs: +- name: z1 + cloud_properties: + availability_zone: us-east-1a + +- name: z2 + cloud_properties: + availability_zone: us-east-1b + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: z1 + static: [10.0.0.5-10.0.0.50] + dns: [8.8.8.8, 8.8.4.4] + cloud_properties: + subnet: subnet-0123456789abcdef0 + +vm_types: +- name: small + cloud_properties: + instance_type: t3.small + ephemeral_disk: + size: 10240 + type: gp3 + +- name: large + cloud_properties: + instance_type: t3.large + ephemeral_disk: + size: 32768 + type: gp3 + +disk_types: +- name: small + disk_size: 10240 + cloud_properties: + type: gp3 + +- name: large + disk_size: 51200 + cloud_properties: + type: gp3 + +compilation: + workers: 5 + reuse_compilation_vms: true + az: z1 + vm_type: large + network: default +``` + +## Managing Cloud Configs + +### Viewing Current Config + +```bash +# View current cloud config +bosh cloud-config + +# Save to file +bosh cloud-config > cloud-config.yml +``` + +### Updating Cloud Config + +```bash +# Update cloud config +bosh update-cloud-config cloud-config.yml + +# Update with variables +bosh update-cloud-config cloud-config.yml \ + -v vpc_id=vpc-12345 \ + -v subnet_id=subnet-67890 +``` + +### Multiple Cloud Configs + +BOSH 2.0+ supports multiple named configs: + +```bash +# Upload named configs +bosh update-config --type=cloud --name=base base-cloud.yml +bosh update-config --type=cloud --name=aws aws-cloud.yml + +# List configs +bosh configs +``` + +## IaaS-Specific Examples + +### AWS Cloud Config + +```yaml +azs: +- name: us-east-1a + cloud_properties: + availability_zone: us-east-1a + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: us-east-1a + reserved: [10.0.0.1-10.0.0.5] + static: [10.0.0.6-10.0.0.50] + dns: [10.0.0.2] + cloud_properties: + subnet: subnet-0123456789abcdef0 + security_groups: [sg-0123456789abcdef0] + +vm_types: +- name: small + cloud_properties: + instance_type: t3.small + ephemeral_disk: + size: 10240 + type: gp3 + security_groups: [bosh-vms] + iam_instance_profile: bosh-vm-role + +disk_types: +- name: default + disk_size: 10240 + cloud_properties: + type: gp3 + encrypted: true + kms_key_id: alias/bosh-disks + +vm_extensions: +- name: elb + cloud_properties: + elbs: [my-elb] +``` + +### Azure Cloud Config + +```yaml +azs: +- name: z1 + cloud_properties: + availability_zone: "1" + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: z1 + dns: [168.63.129.16] + cloud_properties: + virtual_network_name: bosh-vnet + subnet_name: bosh-subnet + resource_group_name: bosh-rg + +vm_types: +- name: small + cloud_properties: + instance_type: Standard_B2s + root_disk: + size: 30720 + ephemeral_disk: + use_root_disk: false + size: 10240 + +disk_types: +- name: default + disk_size: 10240 + cloud_properties: + storage_account_type: Standard_LRS + caching: ReadWrite +``` + +### vSphere Cloud Config + +```yaml +azs: +- name: z1 + cloud_properties: + datacenters: + - name: dc1 + clusters: + - cluster1: + resource_pool: bosh-rp + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: z1 + dns: [10.0.0.2] + cloud_properties: + name: VM Network + +vm_types: +- name: small + cloud_properties: + cpu: 2 + ram: 2048 + disk: 10240 + +disk_types: +- name: default + disk_size: 10240 + cloud_properties: + type: thin +``` + +## Genesis Integration + +### Validation + +Genesis validates cloud config before deployment: + +```bash +# Check if cloud config has required resources +genesis check my-env + +# Example output: +# Checking cloud config... +# ✓ VM type 'small' exists +# ✓ VM type 'large' exists +# ✓ Network 'default' exists +# ✓ Disk type 'default' exists +``` + +### Kit Requirements + +Kits specify cloud config requirements: + +```yaml +# In kit.yml +cloud_config_requirements: + vm_types: + - name: small + minimum_instance_size: + cpu: 2 + ram: 2048 + - name: large + minimum_instance_size: + cpu: 4 + ram: 8192 + + networks: + - name: default + type: manual + + disk_types: + - name: default + minimum_size: 10240 +``` + +### Environment Overrides + +Override cloud config names in environments: + +```yaml +# my-env.yml +params: + # Use different VM types + vm_type: custom-small + + # Use different network + network: production + + # Use different disk type + persistent_disk_type: fast-ssd +``` + +## Advanced Features + +### VM Extensions + +Add cloud properties to specific instance groups: + +```yaml +vm_extensions: +- name: load-balancer + cloud_properties: + elbs: [web-elb] + +- name: public-ip + cloud_properties: + associate_public_ip_address: true +``` + +Use in deployment: + +```yaml +instance_groups: +- name: web + vm_type: small + vm_extensions: [load-balancer, public-ip] +``` + +### Custom Cloud Properties + +Pass IaaS-specific settings: + +```yaml +vm_types: +- name: gpu + cloud_properties: + instance_type: p3.2xlarge + placement_group: gpu-cluster + dedicated_host_id: h-0123456789abcdef0 +``` + +### Compilation Workers + +Optimize compilation: + +```yaml +compilation: + workers: 10 + reuse_compilation_vms: true + az: z1 + vm_type: xlarge # Fast compilation + network: compilation # Dedicated network + env: + bosh: + password: $6$salt$encrypted # For SSH access +``` + +## Multi-Cloud Configurations + +### Separate Configs by IaaS + +```bash +# AWS environments +bosh update-config --type=cloud --name=aws \ + aws-cloud-config.yml + +# Azure environments +bosh update-config --type=cloud --name=azure \ + azure-cloud-config.yml + +# vSphere environments +bosh update-config --type=cloud --name=vsphere \ + vsphere-cloud-config.yml +``` + +### Environment Selection + +```yaml +# aws-prod.yml +cloud_config: + - aws + - production-overrides + +# azure-dev.yml +cloud_config: + - azure + - development-overrides +``` + +## Best Practices + +### 1. Standardize Naming + +Use consistent names across environments: + +```yaml +vm_types: +- name: small # 2 CPU, 4GB RAM +- name: medium # 4 CPU, 8GB RAM +- name: large # 8 CPU, 16GB RAM +- name: xlarge # 16 CPU, 32GB RAM +``` + +### 2. Document Sizing + +Include comments for clarity: + +```yaml +vm_types: +- name: web + # Web servers: 2 CPU, 4GB RAM, 10GB disk + cloud_properties: + instance_type: t3.medium +``` + +### 3. Network Segmentation + +Separate networks by purpose: + +```yaml +networks: +- name: management # BOSH directors +- name: data # Databases +- name: web # Web-facing +- name: compilation # Compilation only +``` + +### 4. Reserve IPs + +Prevent conflicts: + +```yaml +subnets: +- range: 10.0.0.0/24 + reserved: + - 10.0.0.1-10.0.0.10 # Network devices + - 10.0.0.100-10.0.0.110 # Future use + static: + - 10.0.0.11-10.0.0.99 # Static assignments +``` + +### 5. Version Control + +Track cloud config changes: + +```bash +# Before updating +bosh cloud-config > cloud-config-backup-$(date +%Y%m%d).yml + +# Commit to git +git add cloud-config.yml +git commit -m "Add new GPU VM types" +``` + +## Troubleshooting + +### Missing Resources + +```bash +# Error: Can't find VM type 'large' +# Solution: Check cloud config +bosh cloud-config | grep -A5 "vm_types" + +# Add missing type +bosh update-cloud-config updated-cloud.yml +``` + +### Network Issues + +```bash +# Error: No IP available in network 'default' +# Check subnet allocation +bosh cloud-config | grep -A20 "networks" + +# Expand static range if needed +``` + +### Compilation Failures + +```bash +# Increase compilation workers +compilation: + workers: 10 # Increase from 5 + +# Use bigger VMs + vm_type: xlarge # Instead of large +``` + +## Migration Strategies + +### Updating Existing Deployments + +```bash +# 1. Update cloud config +bosh update-cloud-config new-cloud-config.yml + +# 2. Recreate deployments to pick up changes +genesis deploy my-env --recreate + +# Or selectively update +bosh -d my-deployment recreate +``` + +### Renaming Resources + +Handle with aliases: + +```yaml +vm_types: +- name: small + cloud_properties: + instance_type: t3.small + +- name: default # Alias for backward compatibility + cloud_properties: + instance_type: t3.small +``` + +Effective cloud config management ensures your Genesis deployments have the proper IaaS resources while maintaining consistency across environments. \ No newline at end of file diff --git a/docs/topics/60-bosh/index.md b/docs/topics/60-bosh/index.md new file mode 100644 index 00000000..f87883a7 --- /dev/null +++ b/docs/topics/60-bosh/index.md @@ -0,0 +1,32 @@ +# BOSH Integration + +Genesis leverages BOSH as its underlying deployment engine. This section covers how Genesis integrates with BOSH and how to effectively use BOSH commands with Genesis deployments. + +## Topics in this Section + +### [BOSH Overview](bosh-overview.md) +Understanding BOSH and its role in Genesis deployments. + +### [Working with BOSH](working-with-bosh.md) +Common BOSH operations and how they relate to Genesis. + +### [BOSH Directors](bosh-directors.md) +Managing BOSH directors with Genesis. + +### [Cloud Config Management](cloud-config.md) +Managing BOSH cloud configurations for Genesis deployments. + +### [Runtime Config Management](runtime-config.md) +Using BOSH runtime configs with Genesis. + +### [Stemcells and Releases](stemcells-releases.md) +Managing BOSH stemcells and releases in Genesis deployments. + +### [BOSH Troubleshooting](bosh-troubleshooting.md) +Debugging BOSH-related issues in Genesis deployments. + +## Quick Links + +- [Genesis deploy command](../20-commands/deploy.md) +- [BOSH CLI Reference](https://bosh.io/docs/cli-v2/) +- [Cloud Config Concepts](https://bosh.io/docs/cloud-config/) \ No newline at end of file diff --git a/docs/topics/60-bosh/runtime-config.md b/docs/topics/60-bosh/runtime-config.md new file mode 100644 index 00000000..9629362c --- /dev/null +++ b/docs/topics/60-bosh/runtime-config.md @@ -0,0 +1,533 @@ +# Runtime Config Management + +Runtime configurations in BOSH apply settings across all deployments on a director. This guide covers managing runtime configs with Genesis. + +## Overview + +Runtime configs provide: +- **Cross-cutting concerns**: DNS, syslog, monitoring agents +- **Security policies**: OS hardening, compliance tools +- **Operational tools**: Debugging utilities, backup agents +- **Network policies**: MTU settings, custom routes + +## Runtime Config Structure + +### Basic Structure + +```yaml +releases: +- name: os-conf + version: 22.1.0 + +addons: +- name: os-configuration + jobs: + - name: sysctl + release: os-conf + properties: + sysctl: + kernel.panic: 10 + net.ipv4.tcp_syncookies: 1 + include: + deployments: [all] + +- name: dns + jobs: + - name: bosh-dns + release: bosh-dns + properties: + cache: + enabled: true + api: + server: + tls: ((/dns_api_server_tls)) +``` + +## Common Runtime Configs + +### DNS Configuration + +Modern BOSH DNS setup: + +```yaml +releases: +- name: bosh-dns + version: 1.36.0 + +addons: +- name: bosh-dns + jobs: + - name: bosh-dns + release: bosh-dns + properties: + cache: + enabled: true + max_entries: 10000 + health: + enabled: true + server: + tls: ((/dns_healthcheck_server_tls)) + api: + server: + tls: ((/dns_api_server_tls)) + include: + deployments: [all] +``` + +### Syslog Forwarding + +Centralized logging: + +```yaml +releases: +- name: syslog + version: 11.7.0 + +addons: +- name: syslog-forwarder + jobs: + - name: syslog_forwarder + release: syslog + properties: + syslog: + address: syslog.example.com + port: 514 + transport: tcp + tls: + enabled: true + ca_cert: | + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- + include: + deployments: [all] + exclude: + deployments: [bosh] # Don't forward BOSH's own logs +``` + +### Monitoring Agents + +Prometheus node exporter: + +```yaml +releases: +- name: node-exporter + version: 4.2.0 + +addons: +- name: node-exporter + jobs: + - name: node_exporter + release: node-exporter + properties: + node_exporter: + collectors: + - cpu + - diskstats + - filesystem + - loadavg + - meminfo + - netstat + - time + - vmstat + include: + deployments: [all] +``` + +### OS Hardening + +Security baseline: + +```yaml +releases: +- name: os-conf + version: 22.1.0 + +addons: +- name: os-hardening + jobs: + - name: sysctl + release: os-conf + properties: + sysctl: + # Kernel hardening + kernel.randomize_va_space: 2 + kernel.exec-shield: 1 + + # Network hardening + net.ipv4.conf.all.accept_source_route: 0 + net.ipv4.conf.all.accept_redirects: 0 + net.ipv4.conf.all.send_redirects: 0 + net.ipv4.conf.all.log_martians: 1 + net.ipv4.tcp_syncookies: 1 + + # Disable IPv6 if not used + net.ipv6.conf.all.disable_ipv6: 1 + + - name: login_banner + release: os-conf + properties: + login_banner: + text: | + UNAUTHORIZED ACCESS TO THIS DEVICE IS PROHIBITED + All activities performed on this device are logged. + include: + deployments: [all] +``` + +## Managing Runtime Configs + +### Viewing Runtime Configs + +```bash +# View current runtime config +bosh runtime-config + +# List all runtime configs +bosh configs --type=runtime + +# View specific named config +bosh config --type=runtime --name=dns +``` + +### Updating Runtime Configs + +```bash +# Update default runtime config +bosh update-runtime-config runtime.yml + +# Update named runtime config +bosh update-config --type=runtime --name=dns dns-runtime.yml + +# Update with variables +bosh update-runtime-config runtime.yml \ + -v syslog_address=10.0.0.100 +``` + +### Multiple Runtime Configs + +Layer configs for different purposes: + +```bash +# Base OS configuration +bosh update-config --type=runtime --name=os-baseline \ + os-baseline.yml + +# Monitoring agents +bosh update-config --type=runtime --name=monitoring \ + monitoring.yml + +# Security tools +bosh update-config --type=runtime --name=security \ + security.yml +``` + +## Genesis Integration + +### Kit-Provided Runtime Configs + +Some kits include runtime configs: + +```yaml +# In kit.yml +runtime_configs: + - name: dns + file: runtime-configs/dns.yml + - name: syslog + file: runtime-configs/syslog.yml +``` + +Apply them: + +```bash +# Apply kit runtime configs +genesis do my-env -- apply-runtime-configs +``` + +### Environment-Specific Configs + +Override for specific environments: + +```yaml +# production.yml +params: + runtime_config_overrides: + syslog_address: prod-syslog.example.com + monitoring_enabled: true +``` + +## Advanced Usage + +### Conditional Inclusion + +Target specific deployments: + +```yaml +addons: +- name: debug-tools + jobs: + - name: toolbelt + release: toolbelt + include: + deployments: + - /.*-dev$/ # Dev deployments only + - /.*-staging$/ # Staging deployments + exclude: + deployments: + - /.*-prod$/ # Not in production + +- name: production-monitoring + jobs: + - name: enhanced-monitoring + release: monitoring + include: + deployments: + - /.*-prod$/ # Production only +``` + +### Instance Group Targeting + +Apply to specific instance groups: + +```yaml +addons: +- name: database-tools + jobs: + - name: db-backup-agent + release: backup-tools + include: + instance_groups: + - database + - mysql + - postgres + +- name: web-monitoring + jobs: + - name: nginx-exporter + release: prometheus-exporters + include: + instance_groups: + - web + - api + - router +``` + +### Job Placement + +Control where jobs run: + +```yaml +addons: +- name: colocated-dns + placement: + include: + - colocated: true # Only on VMs with other jobs + jobs: + - name: bosh-dns + release: bosh-dns + +- name: dedicated-monitoring + placement: + exclude: + - colocated: true # Only on dedicated VMs + jobs: + - name: telegraf + release: telegraf +``` + +## Best Practices + +### 1. Layered Configuration + +Organize configs by concern: + +```bash +# Structure +runtime-configs/ +├── 01-os-baseline.yml # OS settings +├── 02-dns.yml # DNS configuration +├── 03-monitoring.yml # Monitoring agents +├── 04-security.yml # Security tools +└── 05-logging.yml # Log forwarding +``` + +### 2. Version Control + +Track all runtime configs: + +```bash +# Before updating +bosh runtime-config > backup/runtime-$(date +%Y%m%d).yml + +# After updating +git add runtime-configs/ +git commit -m "Enable TLS for syslog forwarding" +``` + +### 3. Test in Non-Production + +```bash +# Test in dev first +bosh -e dev-bosh update-runtime-config new-runtime.yml + +# Verify with deployment +bosh -d test-deployment recreate + +# Then apply to production +bosh -e prod-bosh update-runtime-config new-runtime.yml +``` + +### 4. Document Dependencies + +```yaml +# monitoring.yml +# Dependencies: +# - Prometheus server at prometheus.example.com:9090 +# - Grafana dashboards: https://grafana.example.com +# - Alert manager: https://alerts.example.com + +releases: +- name: node-exporter + version: 4.2.0 + # Download: bosh upload-release https://bosh.io/d/github.com/cloudfoundry-community/node-exporter-boshrelease +``` + +### 5. Monitor Impact + +Check runtime config effects: + +```bash +# Check addon resource usage +bosh -d my-deployment ssh web/0 +ps aux | grep node_exporter +df -h # Check disk usage + +# Verify functionality +curl localhost:9100/metrics # Node exporter +``` + +## Common Patterns + +### Multi-Site Configuration + +Different configs per site: + +```yaml +# us-east runtime config +addons: +- name: dns + jobs: + - name: bosh-dns + properties: + handlers: + - domain: east.example.com + forward: 10.1.0.2 + +# us-west runtime config +addons: +- name: dns + jobs: + - name: bosh-dns + properties: + handlers: + - domain: west.example.com + forward: 10.2.0.2 +``` + +### Progressive Rollout + +Test new configs gradually: + +```yaml +# Phase 1: Dev only +include: + deployments: [/.*-dev$/] + +# Phase 2: Dev + Staging +include: + deployments: [/.*-(dev|staging)$/] + +# Phase 3: All environments +include: + deployments: [all] +``` + +## Troubleshooting + +### Addon Not Applied + +```bash +# Check if addon matches +bosh -d my-deployment manifest | grep -A20 addons + +# Verify inclusion rules +# Does deployment name match? +# Is instance group included? +``` + +### Conflicts with Deployment + +```bash +# Error: Job 'syslog_forwarder' already exists +# Solution: Check deployment manifest +bosh -d my-deployment manifest | grep syslog_forwarder + +# Remove from deployment or runtime config +``` + +### Performance Impact + +```bash +# Too many addons slowing deployments +# Solution: Consolidate addons +addons: +- name: monitoring-suite # Combine multiple agents + jobs: + - name: node_exporter + - name: process_exporter + - name: postgres_exporter +``` + +## Migration Strategies + +### From Deployment to Runtime + +Move common jobs to runtime config: + +```bash +# 1. Identify common jobs across deployments +for d in $(bosh deployments --json | jq -r '.Tables[0].Rows[].name'); do + echo "=== $d ===" + bosh -d $d manifest | grep -A5 "jobs:" | grep "name:" +done + +# 2. Create runtime config +# 3. Remove from deployment manifests +# 4. Apply runtime config +# 5. Update deployments +``` + +### Updating Releases + +Safely update runtime releases: + +```bash +# 1. Upload new release +bosh upload-release new-release.tgz + +# 2. Update runtime config with new version +bosh update-runtime-config updated-runtime.yml + +# 3. Recreate deployments to pick up changes +# Option 1: All at once +for d in $(bosh deployments --json | jq -r '.Tables[0].Rows[].name'); do + bosh -d $d recreate +done + +# Option 2: Canary approach +bosh -d canary-deployment recreate +# Verify... +bosh -d production-deployment recreate +``` + +Runtime configs provide powerful cross-cutting functionality for all Genesis deployments while maintaining separation of concerns. \ No newline at end of file diff --git a/docs/topics/60-bosh/stemcells-releases.md b/docs/topics/60-bosh/stemcells-releases.md new file mode 100644 index 00000000..2dc1434d --- /dev/null +++ b/docs/topics/60-bosh/stemcells-releases.md @@ -0,0 +1,471 @@ +# Stemcells and Releases + +BOSH uses stemcells and releases as the building blocks for deployments. This guide covers managing these components in Genesis deployments. + +## Overview + +### Stemcells +- Base operating system images +- IaaS-specific versions +- Security-hardened and minimal +- Regular updates for patches + +### Releases +- Packaged software and configurations +- Jobs, packages, and templates +- Version-controlled artifacts +- Compiled or source format + +## Working with Stemcells + +### Understanding Stemcells + +Stemcells follow a naming convention: +``` +bosh-[iaas]-[hypervisor]-[os]-[version] + +Examples: +bosh-aws-xen-hvm-ubuntu-jammy-go_agent +bosh-azure-hyperv-ubuntu-jammy-go_agent +bosh-vsphere-esxi-ubuntu-jammy-go_agent +``` + +### Managing Stemcells + +```bash +# List uploaded stemcells +bosh stemcells + +# Upload a stemcell +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# Upload specific version +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent?v=1.123 + +# Upload from file +bosh upload-stemcell ~/downloads/bosh-stemcell-1.123-aws-xen-hvm-ubuntu-jammy-go_agent.tgz + +# Delete a stemcell +bosh delete-stemcell ubuntu-jammy/1.123 + +# Clean up unused stemcells +bosh clean-up --all +``` + +### Kit Stemcell Requirements + +Genesis kits specify required stemcells: + +```yaml +# In kit.yml +stemcells: + - os: ubuntu-jammy + version: latest + - os: ubuntu-bionic + version: 621.+ # Minimum version +``` + +Check current kit requirements: + +```bash +# View kit metadata +genesis kit-info my-kit + +# Example output: +# Stemcells: +# - ubuntu-jammy (latest) +# - ubuntu-bionic (621.+) +``` + +### Stemcell Updates + +Keep stemcells current for security: + +```bash +# Check for updates +bosh stemcells --recent + +# Update procedure +# 1. Upload new stemcell +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# 2. Update deployment (Genesis handles manifest update) +genesis deploy my-env + +# 3. Clean up old stemcell +bosh clean-up +``` + +## Working with Releases + +### Understanding Releases + +BOSH releases contain: +- **Jobs**: Running processes and configurations +- **Packages**: Compiled software and dependencies +- **Source**: Original source code +- **Manifest**: Release metadata + +### Managing Releases + +```bash +# List uploaded releases +bosh releases + +# Upload a release from URL +bosh upload-release https://bosh.io/d/github.com/cloudfoundry/cf-deployment + +# Upload specific version +bosh upload-release https://bosh.io/d/github.com/cloudfoundry/cf-deployment?v=16.1.0 + +# Upload from file +bosh upload-release ~/releases/concourse-7.8.3.tgz + +# Delete a release +bosh delete-release concourse/7.8.2 + +# Clean up unused releases +bosh clean-up --all +``` + +### Kit Release Management + +Genesis kits manage releases automatically: + +```yaml +# In kit.yml +releases: + - name: concourse + version: 7.8.3 + url: https://bosh.io/d/github.com/concourse/concourse-bosh-release?v=7.8.3 + sha1: abcd1234... + + - name: postgres + version: "43" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=43 + sha1: efgh5678... + + - name: bpm + version: 1.1.21 + url: https://bosh.io/d/github.com/cloudfoundry/bpm-release?v=1.1.21 + sha1: ijkl9012... +``` + +Genesis handles release uploads during deployment: + +```bash +# Genesis automatically uploads required releases +genesis deploy my-env + +# Manual release management +genesis do my-env -- upload-releases +``` + +### Compiled Releases + +Use compiled releases for faster deployments: + +```bash +# Export compiled release +bosh -d my-deployment export-release concourse/7.8.3 ubuntu-jammy/1.123 + +# Creates: concourse-7.8.3-ubuntu-jammy-1.123.tgz + +# Upload compiled release +bosh upload-release concourse-7.8.3-ubuntu-jammy-1.123.tgz +``` + +Enable in Genesis: + +```yaml +# In environment file +params: + use_compiled_releases: true + compiled_release_bucket: my-compiled-releases +``` + +## Release Development + +### Creating Custom Releases + +For Genesis kit development: + +```bash +# Initialize release +bosh init-release + +# Create job +bosh generate-job my-service + +# Create package +bosh generate-package my-app + +# Build release +bosh create-release --force + +# Upload dev release +bosh upload-release +``` + +### Local Release Testing + +```yaml +# In kit development +releases: + - name: my-release + version: latest + url: file:///home/user/my-release +``` + +## Advanced Management + +### Release Dependencies + +Handle transitive dependencies: + +```yaml +# Some releases need others +releases: + - name: routing # Depends on bpm + version: 0.213.0 + + - name: bpm # Required by routing + version: 1.1.21 +``` + +### Version Constraints + +Specify version requirements: + +```yaml +releases: + - name: concourse + version: 7.8.+ # Any 7.8.x version + + - name: postgres + version: ">=42" # Version 42 or higher + + - name: garden + version: 1.19.16 # Exact version +``` + +### Multi-OS Support + +Different stemcells for different jobs: + +```yaml +stemcells: + - alias: default + os: ubuntu-jammy + version: latest + + - alias: windows + os: windows2019 + version: latest + +instance_groups: + - name: web + stemcell: default + + - name: mssql + stemcell: windows +``` + +## Best Practices + +### 1. Regular Updates + +Create an update schedule: + +```bash +#!/bin/bash +# check-updates.sh + +echo "=== Stemcell Updates ===" +bosh stemcells --recent + +echo "=== Release Updates ===" +for release in $(bosh releases --json | jq -r '.Tables[0].Rows[].name'); do + echo "Checking $release..." + # Check for updates on bosh.io +done +``` + +### 2. Version Pinning + +Pin versions in production: + +```yaml +# production.yml +params: + releases: + concourse: + version: 7.8.3 # Explicit version + postgres: + version: "43" # Tested version + + stemcell_version: "1.123" # Specific stemcell +``` + +### 3. Offline Environments + +Prepare for air-gapped deployments: + +```bash +# Download all artifacts +mkdir offline-artifacts + +# Stemcells +wget https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent?v=1.123 \ + -O offline-artifacts/stemcell.tgz + +# Releases +genesis download-kit-releases my-kit \ + --output-dir offline-artifacts/ + +# Upload from local files +cd offline-artifacts +bosh upload-stemcell stemcell.tgz +for release in *.tgz; do + bosh upload-release "$release" +done +``` + +### 4. Cleanup Strategy + +Maintain director health: + +```bash +# Automated cleanup script +#!/bin/bash + +# Keep last 3 versions of each stemcell +bosh clean-up --all + +# Manual cleanup for specific items +bosh stemcells --json | jq -r '.Tables[0].Rows[] | + select(.version | tonumber < 120) | + "\(.os)/\(.version)"' | + xargs -I{} bosh delete-stemcell {} --force +``` + +### 5. Security Scanning + +Verify stemcell security: + +```bash +# Extract and scan stemcell +mkdir stemcell-check +cd stemcell-check +tar -xzf ../stemcell.tgz +tar -xzf image + +# Run security scans +sudo lynis audit system +sudo chkrootkit +``` + +## Troubleshooting + +### Upload Failures + +```bash +# Error: Timed out uploading release +# Solution 1: Use compiled releases +bosh upload-release compiled-release.tgz + +# Solution 2: Increase timeout +export BOSH_CLIENT_TIMEOUT=300 +bosh upload-release large-release.tgz + +# Solution 3: Upload from closer location +# Download first, then upload from jump box +``` + +### Version Conflicts + +```bash +# Error: Release 'X' version 'Y' already exists +# Check current version +bosh releases | grep X + +# Force upload if needed (dev only) +bosh upload-release --force + +# Or delete and re-upload +bosh delete-release X/Y +bosh upload-release X-Y.tgz +``` + +### Compilation Issues + +```bash +# Error: Failed to compile packages +# Solution: Check compilation VMs +bosh -d my-deployment task --debug + +# Common fixes: +# 1. Increase compilation VM size +# 2. Check internet access +# 3. Verify dependencies +``` + +## Integration with CI/CD + +### Automated Updates + +```yaml +# Concourse pipeline +resources: +- name: stemcell + type: bosh-io-stemcell + source: + name: bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +- name: concourse-release + type: bosh-io-release + source: + repository: concourse/concourse-bosh-release + +jobs: +- name: update-genesis-deployment + plan: + - get: stemcell + trigger: true + - get: concourse-release + trigger: true + - task: update-manifest + config: + platform: linux + image_resource: + type: docker-image + source: + repository: genesiscommunity/genesis + run: + path: bash + args: + - -c + - | + genesis deploy my-env --yes +``` + +### Release Notes Tracking + +Track what changes between versions: + +```bash +# Check release notes +curl -s https://api.github.com/repos/concourse/concourse-bosh-release/releases/latest | \ + jq -r '.body' + +# Document in deployment +cat >> deployment-notes.md < ubuntu-jammy/1.124 + - Security patches: CVE-2023-XXXXX +- Concourse: 7.8.2 -> 7.8.3 + - Bug fixes: [link to release notes] +EOF +``` + +Managing stemcells and releases effectively ensures your Genesis deployments stay secure, performant, and up-to-date. \ No newline at end of file diff --git a/docs/topics/60-bosh/working-with-bosh.md b/docs/topics/60-bosh/working-with-bosh.md new file mode 100644 index 00000000..47e467cf --- /dev/null +++ b/docs/topics/60-bosh/working-with-bosh.md @@ -0,0 +1,379 @@ +# Working with BOSH + +This guide covers common BOSH operations in the context of Genesis deployments and when to use BOSH commands directly. + +## Accessing BOSH Through Genesis + +### Setting BOSH Environment + +Genesis provides several ways to access the underlying BOSH director: + +```bash +# Method 1: Get BOSH connection details +genesis bosh my-env + +# Method 2: Open a shell with BOSH environment set +genesis do my-env -- bash +# $BOSH_ENVIRONMENT, $BOSH_CLIENT, etc. are now set + +# Method 3: Run a specific BOSH command +genesis do my-env -- bosh vms +``` + +### Environment Variables + +When Genesis sets up BOSH access, it configures: + +- `BOSH_ENVIRONMENT` - Director URL +- `BOSH_CLIENT` - Authentication client +- `BOSH_CLIENT_SECRET` - Authentication secret +- `BOSH_CA_CERT` - CA certificate for TLS +- `BOSH_DEPLOYMENT` - Current deployment name + +## Common BOSH Operations + +### Viewing Deployment Information + +```bash +# List all deployments +bosh deployments + +# View VMs in a deployment +bosh -d my-deployment vms + +# Detailed VM information with vitals +bosh -d my-deployment vms --vitals + +# View current manifest +bosh -d my-deployment manifest + +# View deployment properties +bosh -d my-deployment properties +``` + +### Managing VMs + +```bash +# SSH into a VM +bosh -d my-deployment ssh web/0 + +# Restart a VM +bosh -d my-deployment restart web/0 + +# Recreate a VM (fresh instance) +bosh -d my-deployment recreate web/0 + +# Stop a VM +bosh -d my-deployment stop web/0 + +# Start a VM +bosh -d my-deployment start web/0 + +# Delete a VM (be careful!) +bosh -d my-deployment delete-vm +``` + +### Logs and Debugging + +```bash +# Download logs from all VMs +bosh -d my-deployment logs + +# Download logs from specific VM +bosh -d my-deployment logs web/0 + +# Download logs for specific job +bosh -d my-deployment logs web/0 --job=nginx + +# Follow logs (tail) +bosh -d my-deployment ssh web/0 -c "sudo tail -f /var/vcap/sys/log/**/*.log" + +# View BOSH agent logs +bosh -d my-deployment ssh web/0 -c "sudo tail -f /var/vcap/bosh/log/current" +``` + +### Running Errands + +```bash +# List available errands +bosh -d my-deployment errands + +# Run an errand +bosh -d my-deployment run-errand smoke-tests + +# Run errand with specific instance +bosh -d my-deployment run-errand backup --instance=database/0 + +# Download errand logs +bosh -d my-deployment run-errand diagnostics --download-logs +``` + +### Task Management + +```bash +# List recent tasks +bosh tasks + +# List all tasks +bosh tasks --all + +# View task details +bosh task 123 + +# View task output +bosh task 123 --debug + +# Cancel a running task +bosh cancel-task 123 +``` + +## Advanced Operations + +### Cloud Check + +Fix deployment issues: + +```bash +# Run cloud check (interactive) +bosh -d my-deployment cloud-check + +# Auto-resolve problems +bosh -d my-deployment cloud-check --auto + +# Report only +bosh -d my-deployment cloud-check --report +``` + +### Managing Releases + +```bash +# List uploaded releases +bosh releases + +# Upload a release +bosh upload-release https://bosh.io/d/github.com/cloudfoundry/cf-release + +# Delete unused releases +bosh delete-release my-release/1.2.3 + +# Export a release +bosh -d my-deployment export-release my-release/1.2.3 ubuntu-jammy/1.123 +``` + +### Managing Stemcells + +```bash +# List uploaded stemcells +bosh stemcells + +# Upload a stemcell +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# Delete unused stemcells +bosh delete-stemcell ubuntu-jammy/1.123 + +# Clean up old stemcells +bosh clean-up --all +``` + +### Persistent Disks + +```bash +# List persistent disks +bosh -d my-deployment disks + +# Orphaned disks +bosh disks --orphaned + +# Attach orphaned disk +bosh -d my-deployment attach-disk web/0 disk-123456 +``` + +## BOSH and Genesis Integration + +### Pre-deployment Checks + +Before `genesis deploy`, you might need to: + +```bash +# Verify cloud config exists +bosh cloud-config + +# Check for required VM types +bosh cloud-config | grep vm_type + +# Verify networks +bosh cloud-config | grep -A5 networks + +# Check available stemcells +bosh stemcells +``` + +### During Deployment + +Monitor deployment progress: + +```bash +# Watch deployment task +genesis deploy my-env +# In another terminal: +bosh task --debug + +# Monitor VM creation +watch -n 2 'bosh -d my-deployment vms' +``` + +### Post-deployment Verification + +```bash +# Check instance health +bosh -d my-deployment instances --ps + +# Verify persistent disks +bosh -d my-deployment disks + +# Run smoke tests +bosh -d my-deployment run-errand smoke-tests +``` + +## Troubleshooting with BOSH + +### Common Issues + +#### VM Not Starting + +```bash +# Check VM vitals +bosh -d my-deployment vms --vitals + +# SSH and check logs +bosh -d my-deployment ssh failing-vm +sudo tail -f /var/vcap/sys/log/**/*.log +sudo tail -f /var/vcap/monit/monit.log +``` + +#### Network Issues + +```bash +# Verify VM can reach director +bosh -d my-deployment ssh web/0 +curl -k https://$BOSH_ENVIRONMENT:25555/info + +# Check network configuration +ip addr +ip route +cat /etc/resolv.conf +``` + +#### Disk Issues + +```bash +# Check disk usage +bosh -d my-deployment ssh database/0 +df -h +du -sh /var/vcap/store/* +``` + +### Recovery Operations + +#### Recreate VM with Persistent Disk + +```bash +# Stop VM +bosh -d my-deployment stop database/0 + +# Recreate (keeps persistent disk) +bosh -d my-deployment recreate database/0 +``` + +#### Manual Resurrection + +```bash +# Disable resurrection +bosh -d my-deployment update-resurrection off + +# Fix issues... + +# Re-enable resurrection +bosh -d my-deployment update-resurrection on +``` + +## Best Practices + +### 1. Use Genesis When Possible + +- Deploy with `genesis deploy` not `bosh deploy` +- Let Genesis manage manifest generation +- Use Genesis for secrets rotation + +### 2. Know When to Use BOSH + +- Debugging VM issues +- Emergency recovery +- Advanced operations (recreate, cloud-check) +- Log collection + +### 3. Monitor Task Output + +```bash +# Always check task output for errors +bosh task --debug | grep -i error +``` + +### 4. Clean Up Regularly + +```bash +# Remove unused releases and stemcells +bosh clean-up --all + +# Remove orphaned disks +bosh disks --orphaned +bosh delete-disk +``` + +### 5. Document Custom Operations + +When you need to use BOSH directly, document: +- What you did +- Why Genesis couldn't handle it +- Any manual steps needed + +## Integration Tips + +### Shell Aliases + +Add to your shell configuration: + +```bash +# Quick BOSH access +alias gb='genesis bosh' + +# Common operations +bosh-vms() { + genesis do "$1" -- bosh vms --vitals +} + +bosh-ssh() { + genesis do "$1" -- bosh ssh "$2" +} +``` + +### Scripting + +Automate common tasks: + +```bash +#!/bin/bash +# check-deployment.sh +ENV=$1 +genesis do "$ENV" -- bash -c ' + echo "=== VMs ===" + bosh vms --vitals + echo "=== Disks ===" + bosh disks + echo "=== Recent Tasks ===" + bosh tasks --recent +' +``` + +Working effectively with BOSH through Genesis requires understanding both tools and knowing when to use each for maximum efficiency. \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/.keep b/docs/topics/70-troubleshooting/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/70-troubleshooting/common-issues.md b/docs/topics/70-troubleshooting/common-issues.md new file mode 100644 index 00000000..6c6e4416 --- /dev/null +++ b/docs/topics/70-troubleshooting/common-issues.md @@ -0,0 +1,507 @@ +# Common Issues + +This guide covers frequently encountered Genesis issues and their solutions. + +## Installation Issues + +### Genesis Command Not Found + +**Symptom:** +```bash +$ genesis +-bash: genesis: command not found +``` + +**Solutions:** + +1. **Add to PATH:** + ```bash + echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc + source ~/.bashrc + ``` + +2. **Verify installation:** + ```bash + ls -la ~/bin/genesis + # Should show executable file + ``` + +3. **Reinstall Genesis:** + ```bash + curl -sL https://get.genesisproject.io/install | bash + ``` + +### Permission Denied + +**Symptom:** +```bash +$ genesis new my-env +Permission denied: cannot write to /path/to/repo +``` + +**Solution:** +```bash +# Fix permissions +sudo chown -R $(whoami):$(whoami) /path/to/repo + +# Or use proper directory +cd ~/deployments/my-kit +genesis new my-env +``` + +## Deployment Issues + +### Kit Not Found + +**Symptom:** +``` +Error: Kit 'my-kit/1.2.3' not found +``` + +**Solutions:** + +1. **Check available versions:** + ```bash + genesis list-kits my-kit + ``` + +2. **Update kit cache:** + ```bash + genesis fetch-kit my-kit + ``` + +3. **Use local kit:** + ```bash + genesis new my-env --kit ./path/to/kit + ``` + +### Environment File Not Found + +**Symptom:** +``` +Error: Could not find environment 'my-env' +``` + +**Solutions:** + +1. **Check current directory:** + ```bash + pwd # Should be in deployment repo root + ls *.yml # Should see environment files + ``` + +2. **Verify environment exists:** + ```bash + genesis list + find . -name "my-env.yml" + ``` + +3. **Create environment:** + ```bash + genesis new my-env + ``` + +### Merge Conflicts + +**Symptom:** +``` +Error: Merge conflict in parameters +``` + +**Solutions:** + +1. **Debug merge order:** + ```bash + genesis manifest my-env --trace + ``` + +2. **Check for duplicate keys:** + ```bash + # Look for duplicate parameters + grep -n "param_name:" *.yml + ``` + +3. **Use explicit null values:** + ```yaml + # In environment file + params: + unwanted_param: null # Remove inherited value + ``` + +## Vault/Secret Issues + +### Cannot Connect to Vault + +**Symptom:** +``` +Error: Could not connect to Vault at https://127.0.0.1:8200 +``` + +**Solutions:** + +1. **Check Vault status:** + ```bash + safe target + safe status + ``` + +2. **Set Vault target:** + ```bash + safe target my-vault https://vault.example.com:8200 + ``` + +3. **Skip TLS verification (dev only):** + ```bash + safe target my-vault https://vault.example.com:8200 -k + ``` + +### Missing Secrets + +**Symptom:** +``` +Error: Could not find secret at path/to/secret:key +``` + +**Solutions:** + +1. **Check secret path:** + ```bash + safe tree path/to + safe get path/to/secret + ``` + +2. **Generate missing secrets:** + ```bash + genesis add-secrets my-env + ``` + +3. **Check environment Vault path:** + ```bash + genesis secrets-path my-env + ``` + +## BOSH Connection Issues + +### Cannot Target BOSH Director + +**Symptom:** +``` +Error: Could not authenticate with BOSH director +``` + +**Solutions:** + +1. **Check BOSH environment:** + ```bash + genesis bosh my-env + bosh env + ``` + +2. **Update BOSH credentials:** + ```bash + # Re-fetch from Vault + genesis bosh my-env --reset + ``` + +3. **Verify network connectivity:** + ```bash + curl -k https://:25555/info + ``` + +### Deployment Not Found + +**Symptom:** +``` +Error: Deployment 'my-env-kit' not found +``` + +**Solutions:** + +1. **Check deployment name:** + ```bash + bosh deployments + genesis info my-env | grep "BOSH Deployment" + ``` + +2. **Deploy first:** + ```bash + genesis deploy my-env + ``` + +## State Corruption + +### Invalid State File + +**Symptom:** +``` +Error: State file corrupted or invalid +``` + +**Solutions:** + +1. **Backup and recreate:** + ```bash + # Backup current state + cp .genesis/state.yml .genesis/state.yml.backup + + # Remove corrupted state + rm .genesis/state.yml + + # Reinitialize + genesis init --kit my-kit . + ``` + +2. **Recover from BOSH:** + ```bash + # Get deployment manifest from BOSH + bosh -d my-deployment manifest > recovered.yml + ``` + +### Cache Corruption + +**Symptom:** +``` +Error: Invalid cached kit or corrupted download +``` + +**Solutions:** + +1. **Clear cache:** + ```bash + rm -rf ~/.genesis/cache/* + genesis fetch-kit my-kit + ``` + +2. **Force redownload:** + ```bash + genesis compile-kit --force + ``` + +## Network Issues + +### Proxy Configuration + +**Symptom:** +``` +Error: Could not download kit - connection timeout +``` + +**Solutions:** + +1. **Set proxy variables:** + ```bash + export http_proxy=http://proxy.example.com:8080 + export https_proxy=http://proxy.example.com:8080 + export no_proxy=localhost,127.0.0.1,.example.com + ``` + +2. **Git proxy configuration:** + ```bash + git config --global http.proxy http://proxy.example.com:8080 + ``` + +### SSL Certificate Issues + +**Symptom:** +``` +Error: x509: certificate signed by unknown authority +``` + +**Solutions:** + +1. **Add CA certificate:** + ```bash + export SSL_CERT_FILE=/path/to/ca-bundle.crt + export CURL_CA_BUNDLE=/path/to/ca-bundle.crt + ``` + +2. **Skip verification (dev only):** + ```bash + export GENESIS_SKIP_VAULT_VERIFY=1 + export BOSH_SKIP_SSL_VALIDATION=true + ``` + +## Performance Issues + +### Slow Manifest Generation + +**Symptom:** +Manifest generation takes several minutes + +**Solutions:** + +1. **Enable caching:** + ```bash + export GENESIS_MANIFEST_CACHE=1 + ``` + +2. **Reduce spruce operations:** + - Minimize grab operations + - Use static references where possible + - Avoid complex array operations + +3. **Profile generation:** + ```bash + genesis manifest my-env --trace --time + ``` + +### Memory Issues + +**Symptom:** +``` +Error: Cannot allocate memory +``` + +**Solutions:** + +1. **Increase limits:** + ```bash + ulimit -m unlimited + ulimit -v unlimited + ``` + +2. **Use streaming for large files:** + ```bash + # Split large arrays + # Use references instead of inline data + ``` + +## Development Issues + +### Hook Failures + +**Symptom:** +``` +Error: Hook 'new' exited with status 1 +``` + +**Solutions:** + +1. **Debug hook:** + ```bash + cd dev/ + GENESIS_TRACE=1 ./hooks/new + ``` + +2. **Check hook permissions:** + ```bash + chmod +x hooks/* + ``` + +3. **Validate bash syntax:** + ```bash + bash -n hooks/new + ``` + +### Kit Compilation Errors + +**Symptom:** +``` +Error: Failed to compile kit +``` + +**Solutions:** + +1. **Check kit.yml syntax:** + ```bash + yamllint kit.yml + spruce merge kit.yml > /dev/null + ``` + +2. **Validate directory structure:** + ```bash + # Required directories + ls -d hooks/ manifests/ + ``` + +3. **Test compilation:** + ```bash + genesis compile-kit --dev + ``` + +## Recovery Procedures + +### Emergency Deployment Recovery + +```bash +#!/bin/bash +# emergency-recovery.sh + +ENV=$1 +KIT=$2 + +echo "Attempting recovery of $ENV" + +# 1. Backup current state +mkdir -p backups/$(date +%Y%m%d) +cp -r . backups/$(date +%Y%m%d)/ + +# 2. Get manifest from BOSH +bosh -d "$ENV-$KIT" manifest > recovered-manifest.yml + +# 3. Extract parameters +spruce json recovered-manifest.yml | \ + jq '.params' > recovered-params.json + +# 4. Recreate environment file +cat > "$ENV.yml" <&1 | grep -E "(Loading|Merging)" + +# Example output: +# Loading us.yml +# Loading us-east.yml +# Loading us-east-prod.yml +# Merging 3 environment files... +``` + +**Common problems:** + +1. **Missing parent files:** + ```bash + # Check file existence + genesis manifest my-env 2>&1 | grep "Could not find" + + # Fix: Create missing files + touch us.yml us-east.yml + ``` + +2. **Circular dependencies:** + ```bash + # Error: Circular dependency detected + # Check for files that reference each other + grep -l "genesis.env:" *.yml + ``` + +### Feature Validation + +**Debug feature issues:** + +```bash +# List available features +genesis info my-env | grep -A20 "Available Features" + +# Check enabled features +genesis manifest my-env | grep -A10 "kit.features" + +# Validate feature combination +genesis check my-env --trace +``` + +**Common feature problems:** + +```yaml +# Incompatible features +kit: + features: + - azure + - aws # Error: Can't use multiple IaaS + +# Missing dependencies +kit: + features: + - ha # Might require minimum instances +``` + +### Secret Debugging + +**Trace secret retrieval:** + +```bash +# List required secrets +genesis secrets-plan my-env + +# Check missing secrets +genesis check-secrets my-env + +# Debug secret paths +GENESIS_TRACE=1 genesis manifest my-env 2>&1 | grep -i vault +``` + +**Debug Vault connectivity:** + +```bash +# Test Vault access +safe target +safe tree $(genesis secrets-path my-env) + +# Manual secret check +safe get $(genesis secrets-path my-env)/admin:password +``` + +## Manifest Generation Debugging + +### Trace Manifest Building + +**Full trace of manifest generation:** + +```bash +# Save trace output +genesis manifest my-env --trace > trace.log 2>&1 + +# Analyze phases +grep -n "Phase:" trace.log +``` + +**Step-by-step debugging:** + +```bash +# 1. Base manifest only +genesis manifest my-env --partial base + +# 2. With features +genesis manifest my-env --partial features + +# 3. With secrets (no Vault lookup) +genesis manifest my-env --no-resolve + +# 4. Final manifest +genesis manifest my-env +``` + +### Spruce Merge Issues + +**Debug merge operations:** + +```bash +# Extract spruce operations +genesis manifest my-env --trace 2>&1 | \ + grep -E "(spruce merge|Error.*spruce)" + +# Test specific merge +spruce merge file1.yml file2.yml + +# Debug grab operations +spruce merge --trace manifest.yml 2>&1 | grep grab +``` + +**Common spruce errors:** + +1. **Undefined variables:** + ```yaml + # Error: (( grab params.missing )) - params.missing not found + # Fix: Define in environment or use default + value: (( grab params.missing || "default" )) + ``` + +2. **Type mismatches:** + ```yaml + # Error: Cannot merge string into array + # Check data types + spruce diff base.yml override.yml + ``` + +### Parameter Resolution + +**Debug parameter lookup:** + +```bash +# Show all parameters +genesis manifest my-env | spruce json | jq '.params' + +# Trace parameter source +for file in $(genesis manifest my-env --trace 2>&1 | grep Loading | awk '{print $2}'); do + echo "=== $file ===" + grep "param_name:" "$file" || true +done +``` + +## Deployment Debugging + +### Pre-Deployment Validation + +**Run comprehensive checks:** + +```bash +# Full validation +genesis check my-env + +# Individual checks +genesis check-secrets my-env +genesis check-cloud-config my-env +genesis check-stemcells my-env +``` + +**Manual BOSH validation:** + +```bash +# Get manifest +genesis manifest my-env > manifest.yml + +# Validate with BOSH +bosh -d my-deployment deploy manifest.yml --dry-run + +# Check interpolation +bosh int manifest.yml +``` + +### Deployment Execution + +**Monitor deployment progress:** + +```bash +# Deploy with verbose output +genesis deploy my-env --trace + +# In another terminal, watch BOSH task +bosh tasks --recent +bosh task --debug +``` + +**Debug deployment failures:** + +```bash +# Get failing task details +bosh task --debug | less + +# Common patterns to search +/error +/failed +/timeout +/not found +``` + +### Instance-Level Debugging + +**Access problematic instances:** + +```bash +# List instances with issues +bosh -d my-deployment instances --ps + +# SSH to instance +bosh -d my-deployment ssh web/0 + +# Check logs +sudo tail -f /var/vcap/sys/log/**/*.log + +# Check monit +sudo monit summary +``` + +## Post-Deployment Debugging + +### Hook Failures + +**Debug post-deploy hooks:** + +```bash +# Run hook manually +cd /path/to/kit +GENESIS_ENVIRONMENT=my-env \ +GENESIS_VAULT_PREFIX=$(genesis secrets-path my-env) \ +GENESIS_TRACE=1 \ +./hooks/post-deploy +``` + +### Smoke Test Failures + +**Debug smoke tests:** + +```bash +# Run errand manually +bosh -d my-deployment run-errand smoke-tests + +# Get errand logs +bosh -d my-deployment run-errand smoke-tests --download-logs +tar xzf smoke-tests-logs.tgz +``` + +## Advanced Debugging Techniques + +### Manifest Diffing + +**Compare manifests:** + +```bash +# Compare with last deployment +bosh -d my-deployment manifest > current.yml +genesis manifest my-env > new.yml +diff -u current.yml new.yml + +# Semantic diff +spruce diff current.yml new.yml +``` + +### State Analysis + +**Check Genesis state:** + +```bash +# View cached information +cat .genesis/manifests/my-env.yml +cat .genesis/configs/my-env.yml + +# Check deployment state +cat .genesis/deployments/my-env.yml +``` + +### Environment Variable Debugging + +**Check Genesis environment:** + +```bash +# Show all Genesis variables +env | grep GENESIS | sort + +# Run with specific debug flags +GENESIS_TRACE=1 \ +GENESIS_DEBUG=1 \ +GENESIS_VAULT_VERIFY=0 \ +genesis deploy my-env +``` + +## Recovery Procedures + +### Partial Deployment Recovery + +```bash +#!/bin/bash +# recover-deployment.sh + +DEPLOYMENT=$1 + +# 1. Get current state from BOSH +echo "Fetching current deployment state..." +bosh -d $DEPLOYMENT manifest > current-state.yml + +# 2. Compare with desired state +echo "Comparing states..." +genesis manifest ${DEPLOYMENT%-*} > desired-state.yml +spruce diff current-state.yml desired-state.yml > state-diff.txt + +# 3. Identify stuck instances +echo "Checking instances..." +bosh -d $DEPLOYMENT instances --ps | grep -v running > stuck-instances.txt + +# 4. Attempt recovery +if [[ -s stuck-instances.txt ]]; then + echo "Found stuck instances:" + cat stuck-instances.txt + + # Restart stuck instances + while read instance; do + inst=$(echo $instance | awk '{print $1}') + echo "Restarting $inst..." + bosh -d $DEPLOYMENT restart $inst + done < stuck-instances.txt +fi +``` + +### Manual State Correction + +```bash +# Force convergence +bosh -d my-deployment cloud-check --auto + +# Recreate specific instances +bosh -d my-deployment recreate web/0 + +# Full recreation (last resort) +bosh -d my-deployment recreate +``` + +## Debugging Checklist + +### Before Deployment + +- [ ] Environment files exist and are valid YAML +- [ ] All parent files are present +- [ ] Features are compatible +- [ ] Required parameters are set +- [ ] Vault is accessible +- [ ] Secrets exist or can be generated +- [ ] Cloud config has required resources +- [ ] Stemcells are uploaded + +### During Deployment + +- [ ] Monitor BOSH task output +- [ ] Check for compilation failures +- [ ] Verify network connectivity +- [ ] Watch for timeout errors +- [ ] Check instance health + +### After Deployment Failure + +- [ ] Collect BOSH task logs +- [ ] Save current manifest +- [ ] Check instance states +- [ ] Review error messages +- [ ] Verify cloud resources +- [ ] Check persistent disks + +## Common Patterns + +### Timeout Issues + +```bash +# Increase timeouts +export BOSH_CLIENT_TIMEOUT=300 + +# Deploy with reduced parallelism +genesis deploy my-env -- --max-in-flight=1 +``` + +### Resource Constraints + +```bash +# Check cloud usage +bosh cloud-config | grep -A5 compilation + +# Reduce compilation workers +bosh update-cloud-config <( + bosh cloud-config | + sed 's/workers: .*/workers: 2/' +) +``` + +### Network Problems + +```bash +# Test from director +bosh -d my-deployment ssh web/0 -c "ping -c 3 8.8.8.8" + +# Check DNS resolution +bosh -d my-deployment ssh web/0 -c "nslookup google.com" +``` + +Effective debugging combines systematic analysis with understanding of the deployment pipeline. Always collect evidence before attempting fixes. \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/error-messages.md b/docs/topics/70-troubleshooting/error-messages.md new file mode 100644 index 00000000..85df96c4 --- /dev/null +++ b/docs/topics/70-troubleshooting/error-messages.md @@ -0,0 +1,516 @@ +# Error Messages + +This reference guide explains common Genesis error messages and how to resolve them. + +## Environment Errors + +### "Could not find environment 'X'" + +**Full Error:** +``` +Error: Could not find environment 'my-env' in /path/to/deployments +``` + +**Cause:** Genesis cannot find the environment YAML file. + +**Resolution:** +```bash +# Check current directory +pwd # Must be in deployment repository root + +# List available environments +genesis list + +# Create if missing +genesis new my-env +``` + +### "No deployment type specified" + +**Full Error:** +``` +Error: No deployment type specified in 'my-env.yml' +``` + +**Cause:** Environment file missing kit information. + +**Resolution:** +```yaml +# Add to environment file +kit: + name: concourse # or your kit name + version: 4.0.0 # optional +``` + +### "Circular dependency detected" + +**Full Error:** +``` +Error: Circular dependency detected in environment hierarchy +``` + +**Cause:** Environment files reference each other in a loop. + +**Resolution:** +```bash +# Check environment references +grep "genesis.env:" *.yml + +# Fix circular reference +# Remove or correct the circular dependency +``` + +## Kit Errors + +### "Kit 'X' not found" + +**Full Error:** +``` +Error: Kit 'my-kit/1.0.0' not found in any known location +``` + +**Cause:** Kit not available locally or in upstream. + +**Resolution:** +```bash +# List available kits +genesis list-kits my-kit + +# Fetch from upstream +genesis fetch-kit my-kit + +# Use local kit +genesis init --kit ./path/to/kit +``` + +### "Kit version mismatch" + +**Full Error:** +``` +Error: Environment requires kit version 2.0.0 but 1.0.0 is installed +``` + +**Cause:** Environment specifies different kit version than available. + +**Resolution:** +```bash +# Update kit +genesis fetch-kit my-kit@2.0.0 + +# Or update environment +# Remove version requirement from kit: section +``` + +### "Invalid kit structure" + +**Full Error:** +``` +Error: Invalid kit structure: missing required directory 'manifests' +``` + +**Cause:** Kit missing required files/directories. + +**Resolution:** +```bash +# Check kit structure +ls -la dev/ +# Must have: kit.yml, manifests/, hooks/ + +# Create missing directories +mkdir -p dev/manifests dev/hooks +``` + +## Manifest Errors + +### "Merge conflict detected" + +**Full Error:** +``` +Error: Merge conflict detected at $.instance_groups[0].name +``` + +**Cause:** YAML merge conflict between files. + +**Resolution:** +```bash +# Debug merge +genesis manifest my-env --trace + +# Test individual merges +spruce merge base.yml overlay.yml + +# Use explicit operators +# (( replace )) to replace +# (( append )) to append +``` + +### "Could not resolve (( grab ... ))" + +**Full Error:** +``` +Error: Could not resolve (( grab params.missing_param )) +``` + +**Cause:** Referenced parameter not defined. + +**Resolution:** +```yaml +# Define in environment +params: + missing_param: "value" + +# Or provide default +value: (( grab params.missing_param || "default" )) +``` + +### "Type mismatch in merge" + +**Full Error:** +``` +Error: Cannot merge string with array at $.networks[0] +``` + +**Cause:** Trying to merge incompatible types. + +**Resolution:** +```yaml +# Ensure consistent types +# Bad: +base: networks: "default" +overlay: networks: ["default", "other"] + +# Good: +base: networks: ["default"] +overlay: networks: ["default", "other"] +``` + +## Vault/Secret Errors + +### "Could not connect to Vault" + +**Full Error:** +``` +Error: Could not connect to Vault at https://127.0.0.1:8200: connection refused +``` + +**Cause:** Vault not accessible. + +**Resolution:** +```bash +# Check Vault target +safe target + +# Set correct target +safe target my-vault https://vault.example.com:8200 + +# Verify connectivity +safe status +``` + +### "Secret not found" + +**Full Error:** +``` +Error: Could not retrieve secret 'secret/my/env/password:key' from Vault +``` + +**Cause:** Secret doesn't exist in Vault. + +**Resolution:** +```bash +# Check if secret exists +safe exists secret/my/env/password + +# Generate missing secrets +genesis add-secrets my-env + +# Or create manually +safe set secret/my/env/password key=value +``` + +### "Permission denied" + +**Full Error:** +``` +Error: 403 permission denied accessing 'secret/my/env' +``` + +**Cause:** Vault token lacks required permissions. + +**Resolution:** +```bash +# Check token permissions +safe vault token lookup + +# Re-authenticate +safe auth + +# Check policies +safe vault policy read my-policy +``` + +## BOSH Errors + +### "Could not authenticate with BOSH" + +**Full Error:** +``` +Error: Could not authenticate with BOSH director: 401 Unauthorized +``` + +**Cause:** Invalid or expired BOSH credentials. + +**Resolution:** +```bash +# Refresh BOSH credentials +genesis bosh my-env --reset + +# Verify connection +bosh env +``` + +### "Deployment not found" + +**Full Error:** +``` +Error: Deployment 'my-env-concourse' not found on BOSH director +``` + +**Cause:** Deployment doesn't exist yet or wrong name. + +**Resolution:** +```bash +# Check existing deployments +bosh deployments + +# Deploy first +genesis deploy my-env + +# Verify deployment name +genesis info my-env | grep "BOSH Deployment" +``` + +### "Cloud config missing required elements" + +**Full Error:** +``` +Error: Cloud config missing required vm_type 'small' +``` + +**Cause:** BOSH cloud config incomplete. + +**Resolution:** +```bash +# Check cloud config +bosh cloud-config | grep vm_type + +# Update cloud config +bosh update-cloud-config cloud.yml +``` + +## Hook Errors + +### "Hook 'X' failed with exit code Y" + +**Full Error:** +``` +Error: Hook 'check' failed with exit code 1 +``` + +**Cause:** Kit hook script failed. + +**Resolution:** +```bash +# Debug hook +cd /path/to/kit +GENESIS_TRACE=1 ./hooks/check + +# Check hook permissions +chmod +x hooks/check + +# Review hook output for specific errors +``` + +### "Hook not found or not executable" + +**Full Error:** +``` +Error: Hook 'new' not found or not executable +``` + +**Cause:** Missing hook or wrong permissions. + +**Resolution:** +```bash +# Check hook exists +ls -la hooks/new + +# Fix permissions +chmod +x hooks/new + +# Verify shebang +head -1 hooks/new # Should be #!/bin/bash +``` + +## Validation Errors + +### "Invalid YAML syntax" + +**Full Error:** +``` +Error: Invalid YAML in 'my-env.yml': found character that cannot start any token +``` + +**Cause:** YAML syntax error. + +**Resolution:** +```bash +# Validate YAML +yamllint my-env.yml + +# Common issues: +# - Tabs instead of spaces +# - Missing quotes around values with ':' +# - Incorrect indentation +``` + +### "Missing required parameter" + +**Full Error:** +``` +Error: Missing required parameter 'base_domain' +``` + +**Cause:** Required parameter not provided. + +**Resolution:** +```yaml +# Add to environment file +params: + base_domain: example.com +``` + +## State Errors + +### "State file corrupted" + +**Full Error:** +``` +Error: State file corrupted or unreadable +``` + +**Cause:** Genesis state file damaged. + +**Resolution:** +```bash +# Backup corrupted state +mv .genesis/state.yml .genesis/state.yml.backup + +# Reinitialize +genesis init --kit my-kit . +``` + +### "Cache corrupted" + +**Full Error:** +``` +Error: Cached manifest corrupted for environment 'my-env' +``` + +**Cause:** Cached files corrupted. + +**Resolution:** +```bash +# Clear cache +rm -rf .genesis/manifests/my-env.yml +rm -rf .genesis/cache/* + +# Regenerate +genesis manifest my-env +``` + +## Network Errors + +### "Connection timeout" + +**Full Error:** +``` +Error: Connection timeout downloading kit from upstream +``` + +**Cause:** Network connectivity issues. + +**Resolution:** +```bash +# Check proxy settings +export http_proxy=http://proxy:8080 +export https_proxy=http://proxy:8080 + +# Increase timeout +export GENESIS_DOWNLOAD_TIMEOUT=300 +``` + +### "Certificate verification failed" + +**Full Error:** +``` +Error: x509: certificate signed by unknown authority +``` + +**Cause:** TLS certificate not trusted. + +**Resolution:** +```bash +# Add CA certificate +export SSL_CERT_FILE=/path/to/ca-bundle.crt + +# Or skip verification (dev only) +export GENESIS_SKIP_VERIFY=1 +``` + +## Recovery Commands + +### General Debugging + +```bash +# Enable maximum debugging +export GENESIS_DEBUG=1 +export GENESIS_TRACE=1 +genesis deploy my-env + +# Check Genesis version +genesis version + +# Validate environment +genesis check my-env +``` + +### Quick Fixes + +```bash +# Clear all caches +rm -rf ~/.genesis/cache/* +rm -rf .genesis/manifests/* + +# Reset BOSH connection +genesis bosh my-env --reset + +# Regenerate secrets +genesis rotate-secrets my-env + +# Force manifest regeneration +rm .genesis/manifests/my-env.yml +genesis manifest my-env +``` + +### Getting Help + +When reporting errors: + +1. **Exact error message** +2. **Genesis version**: `genesis version` +3. **Command that failed**: `genesis deploy my-env` +4. **Trace output**: Run with `--trace` +5. **Environment details**: OS, network setup + +Understanding error messages helps quickly identify and resolve issues. Most errors provide clear guidance on the problem and solution. \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/index.md b/docs/topics/70-troubleshooting/index.md new file mode 100644 index 00000000..38f403db --- /dev/null +++ b/docs/topics/70-troubleshooting/index.md @@ -0,0 +1,57 @@ +# Troubleshooting + +This section provides guidance for diagnosing and resolving common issues with Genesis deployments. + +## Topics in this Section + +### [Common Issues](common-issues.md) +Frequently encountered problems and their solutions. + +### [Debugging Deployments](debugging-deployments.md) +Techniques for troubleshooting deployment failures. + +### [Trace Logging](trace-logging.md) +Using Genesis trace logs for detailed debugging. + +### [Manifest Debugging](manifest-debugging.md) +Troubleshooting manifest generation and merge issues. + +### [Secret Problems](secret-problems.md) +Resolving issues with Vault and secret management. + +### [Kit Development Issues](kit-development-issues.md) +Common problems when developing Genesis kits. + +### [Error Messages](error-messages.md) +Understanding and resolving Genesis error messages. + +## Quick Diagnostics + +### Basic Health Check + +```bash +# Check Genesis version +genesis version + +# Verify environment +genesis list + +# Check deployment status +genesis info my-env + +# Validate environment +genesis check my-env +``` + +### Getting Help + +- Check error messages carefully - they often contain the solution +- Use `--trace` flag for detailed debugging output +- Review logs in `~/.genesis/logs/` +- Search GitHub issues: https://github.com/genesis-community/genesis/issues + +## Emergency Procedures + +- [Deployment Recovery](debugging-deployments.md#recovery-procedures) +- [Secret Recovery](secret-problems.md#recovery) +- [State Corruption](common-issues.md#state-corruption) \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/kit-development-issues.md b/docs/topics/70-troubleshooting/kit-development-issues.md new file mode 100644 index 00000000..a9eaa95f --- /dev/null +++ b/docs/topics/70-troubleshooting/kit-development-issues.md @@ -0,0 +1,527 @@ +# Kit Development Issues + +This guide helps troubleshoot common problems encountered when developing Genesis kits. + +## Development Environment Setup + +### Kit Development Structure + +```bash +my-kit/ +├── kit.yml # Kit metadata +├── manifests/ # BOSH manifests +│ ├── base.yml # Base manifest +│ └── features/ # Feature-specific manifests +├── hooks/ # Lifecycle hooks +│ ├── blueprint # Required: manifest selection +│ ├── new # Environment creation +│ ├── check # Pre-deployment validation +│ └── info # Post-deployment information +└── spec/ # Test specifications +``` + +### Common Setup Issues + +**Missing kit.yml:** +```bash +Error: Could not find kit.yml in current directory +``` + +**Solution:** +```bash +# Create minimal kit.yml +cat > kit.yml < +EOF +``` + +**Invalid directory structure:** +```bash +Error: No manifests directory found +``` + +**Solution:** +```bash +# Create required directories +mkdir -p manifests/features hooks +touch manifests/base.yml +chmod +x hooks/* +``` + +## Hook Development Issues + +### Hook Not Executing + +**Symptoms:** +``` +Hook 'new' not found or not executable +``` + +**Diagnostics:** +```bash +# Check file existence and permissions +ls -la hooks/ +file hooks/new +bash -n hooks/new # Syntax check +``` + +**Solutions:** +```bash +# Fix permissions +chmod +x hooks/* + +# Add shebang +echo '#!/bin/bash' | cat - hooks/new > temp && mv temp hooks/new + +# Test directly +cd /path/to/kit +GENESIS_ENVIRONMENT=test ./hooks/new +``` + +### Hook Environment Variables + +**Missing variables:** +```bash +# Debug hook environment +cat > hooks/debug <<'EOF' +#!/bin/bash +echo "=== Genesis Environment Variables ===" +env | grep GENESIS | sort +echo "=== Other Relevant Variables ===" +echo "PATH: $PATH" +echo "PWD: $PWD" +EOF +chmod +x hooks/debug +``` + +**Common required variables:** +```bash +#!/bin/bash +# In hook scripts + +# Always available +echo "Kit: $GENESIS_KIT_NAME v$GENESIS_KIT_VERSION" +echo "Environment: $GENESIS_ENVIRONMENT" +echo "Root: $GENESIS_ROOT" + +# Hook-specific +echo "Vault prefix: ${GENESIS_SECRETS_PATH:-$GENESIS_VAULT_PREFIX}" +echo "Features: $GENESIS_REQUESTED_FEATURES" +``` + +### Blueprint Hook Issues + +**No manifests returned:** +```bash +Error: Blueprint hook returned no manifest files +``` + +**Debug blueprint:** +```bash +#!/bin/bash +# hooks/blueprint +set -eu + +# Debug mode +if [[ "${GENESIS_TRACE:-}" == "1" ]]; then + set -x +fi + +# Always include base +echo "manifests/base.yml" + +# Add features +for feature in $GENESIS_REQUESTED_FEATURES; do + case "$feature" in + ha|ssl|monitoring) + if [[ -f "manifests/features/$feature.yml" ]]; then + echo "manifests/features/$feature.yml" + else + echo >&2 "Warning: Feature $feature requested but manifests/features/$feature.yml not found" + fi + ;; + *) + echo >&2 "Error: Unknown feature: $feature" + exit 1 + ;; + esac +done +``` + +### Check Hook Validation + +**Hook failing silently:** +```bash +# Add debugging to check hook +#!/bin/bash +# hooks/check +set -eu + +# Enable tracing +[[ "${GENESIS_TRACE:-}" == "1" ]] && set -x + +# Verbose error reporting +error() { + echo >&2 "CHECK FAILED: $*" + exit 1 +} + +# Check cloud config +echo "Checking cloud config..." +if ! cloud_config_has vm_type "small"; then + error "Cloud config missing required vm_type 'small'" +fi + +echo "All checks passed!" +``` + +## Manifest Issues + +### YAML Syntax Errors + +**Invalid YAML:** +```bash +Error: yaml: line 10: found character that cannot start any token +``` + +**Debugging:** +```bash +# Validate all YAML files +for file in manifests/**/*.yml; do + echo "Checking $file..." + yaml-lint "$file" || yamllint "$file" +done + +# Common issues: +# - Tabs instead of spaces +# - Incorrect indentation +# - Missing quotes around values with colons +``` + +### Spruce Errors + +**Merge failures:** +```bash +Error: spruce merge failed: conflicting key types +``` + +**Debug approach:** +```bash +# Test manifest merging +cd /path/to/kit + +# Base only +spruce merge manifests/base.yml + +# With features +spruce merge manifests/base.yml manifests/features/ha.yml + +# With environment +cat > test-env.yml <&2 "Error: Cannot use both 'aws' and 'azure' features" + exit 1 +fi +``` + +## Testing Issues + +### Local Testing + +**Test kit without compilation:** +```bash +# Use dev directory +mkdir -p ~/deployments/test-kit +cd ~/deployments/test-kit +genesis init --kit /path/to/kit/dev + +# Create test environment +genesis new test-env +``` + +**Mock Genesis environment:** +```bash +#!/bin/bash +# test-kit.sh + +export GENESIS_KIT_NAME="my-kit" +export GENESIS_KIT_VERSION="0.1.0" +export GENESIS_ENVIRONMENT="test" +export GENESIS_ROOT="/tmp/test-deployments" +export GENESIS_SECRETS_PATH="test/env" +export GENESIS_REQUESTED_FEATURES="ha ssl" +export GENESIS_TRACE=1 + +mkdir -p "$GENESIS_ROOT" + +# Test hooks +echo "=== Testing blueprint hook ===" +./hooks/blueprint + +echo "=== Testing new hook ===" +./hooks/new +``` + +### Spec Test Failures + +**Ginkgo test issues:** +```bash +# Run tests with verbose output +cd spec +ginkgo -v --trace + +# Run specific test +ginkgo --focus "should deploy with HA" +``` + +**Common test problems:** + +```go +// spec/spec_test.go +var _ = Describe("My Kit", func() { + BeforeEach(func() { + // Ensure clean state + Setup(kit, "default") + }) + + It("should have required properties", func() { + manifest := Manifest() + + // Debug manifest + fmt.Printf("Manifest: %+v\n", manifest) + + // Assertions with clear errors + Expect(manifest).NotTo(BeNil(), + "Manifest should not be nil") + Expect(manifest.InstanceGroups).To(HaveLen(1), + "Should have exactly one instance group") + }) +}) +``` + +## Compilation Issues + +### Kit Compilation Failures + +**Compilation errors:** +```bash +Error: Failed to compile kit: manifest validation failed +``` + +**Debug compilation:** +```bash +# Compile with verbose output +genesis compile-kit --name my-kit --version 0.1.0 --verbose + +# Dev compilation (no tarball) +genesis compile-kit --dev + +# Force recompilation +rm -rf .genesis/kits/my-kit* +genesis compile-kit +``` + +### Packaging Problems + +**Missing files in compiled kit:** +```bash +# Check kit contents +tar -tzf my-kit-0.1.0.tar.gz | grep -E "(hooks|manifests)" + +# Ensure files are tracked +git add -A +genesis compile-kit --version 0.1.0 +``` + +## Runtime Issues + +### Memory/Performance + +**Slow manifest generation:** +```bash +# Profile manifest generation +time genesis manifest test-env + +# Optimize spruce operations +# Bad: Multiple grabs +a: (( grab params.a )) +b: (( grab params.b )) +c: (( grab params.c )) + +# Better: Single grab +_params: (( grab params )) +a: (( grab _params.a )) +b: (( grab _params.b )) +c: (( grab _params.c )) +``` + +### Large Manifests + +**Memory exhaustion:** +```bash +# Split large arrays +# Instead of inline: +instances: + - { name: web-1, ... } + - { name: web-2, ... } + # ... 100 more + +# Use references: +instance_definitions: + web: { ... } +instances: + - (( grab instance_definitions.web )) + - (( grab instance_definitions.web )) +``` + +## Debugging Tools + +### Kit Validation Script + +```bash +#!/bin/bash +# validate-kit.sh + +echo "=== Validating Kit Structure ===" + +# Check required files +required_files="kit.yml manifests/base.yml hooks/blueprint" +for file in $required_files; do + if [[ -f "$file" ]]; then + echo "✓ $file exists" + else + echo "✗ $file missing" + exit 1 + fi +done + +# Check hook permissions +for hook in hooks/*; do + if [[ -x "$hook" ]]; then + echo "✓ $hook is executable" + else + echo "✗ $hook not executable" + fi +done + +# Validate YAML +for yaml in manifests/**/*.yml; do + if yamllint "$yaml" >/dev/null 2>&1; then + echo "✓ $yaml valid" + else + echo "✗ $yaml invalid" + yamllint "$yaml" + fi +done + +echo "=== Testing Blueprint ===" +GENESIS_REQUESTED_FEATURES="" ./hooks/blueprint +``` + +### Development Workflow + +```bash +#!/bin/bash +# dev-workflow.sh + +# 1. Make changes +vi manifests/base.yml + +# 2. Validate +./validate-kit.sh + +# 3. Test locally +cd ~/deployments/test +genesis manifest test-env + +# 4. Run tests +cd spec && ginkgo + +# 5. Compile +genesis compile-kit --dev + +# 6. Full test +genesis deploy test-env --dry-run +``` + +## Best Practices + +1. **Always test locally** before committing +2. **Use trace mode** for debugging: `GENESIS_TRACE=1` +3. **Validate YAML** syntax regularly +4. **Test each feature** independently +5. **Document complex logic** in comments +6. **Handle errors gracefully** in hooks +7. **Provide helpful error messages** + +Kit development requires attention to detail and systematic testing. Use these debugging techniques to identify and resolve issues quickly. \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/manifest-debugging.md b/docs/topics/70-troubleshooting/manifest-debugging.md new file mode 100644 index 00000000..7be14aa9 --- /dev/null +++ b/docs/topics/70-troubleshooting/manifest-debugging.md @@ -0,0 +1,493 @@ +# Manifest Debugging + +This guide helps troubleshoot issues with Genesis manifest generation, merging, and validation. + +## Understanding Manifest Generation + +### The Manifest Pipeline + +Genesis builds manifests through several stages: + +1. **Environment Resolution** - Load environment files hierarchically +2. **Kit Integration** - Apply base manifest and features +3. **Parameter Injection** - Add environment-specific parameters +4. **Secret Resolution** - Replace Vault references +5. **Final Evaluation** - Process Spruce operators + +## Common Manifest Issues + +### Merge Conflicts + +**Symptom:** +``` +Error: merge conflict detected +``` + +**Debug approach:** + +```bash +# Identify conflict source +genesis manifest my-env --trace 2>&1 | grep -B10 "conflict" + +# Test individual merges +spruce merge base.yml overlay.yml + +# Show differences +spruce diff base.yml overlay.yml +``` + +**Common solutions:** + +```yaml +# Problem: Array merge conflict +# base.yml +instances: + - name: web + - name: api + +# overlay.yml +instances: # This replaces instead of merging + - name: worker + +# Solution: Use explicit array indices or replace operator +instances: + - (( replace )) + - name: worker + +# Or use index notation +instances.2: + name: worker +``` + +### Missing Parameters + +**Symptom:** +``` +Error: (( grab params.missing_value )) could not be resolved +``` + +**Debug approach:** + +```bash +# List all grab operations +genesis manifest my-env --no-resolve | \ + grep -o "(( grab [^)]*" | sort -u + +# Check parameter definitions +genesis manifest my-env | \ + spruce json | jq '.params' | \ + grep -i "missing_value" +``` + +**Solutions:** + +```yaml +# Add default values +value: (( grab params.optional || "default" )) + +# Or define in environment +params: + missing_value: "now defined" +``` + +### Type Mismatches + +**Symptom:** +``` +Error: cannot merge string with array +``` + +**Debug approach:** + +```bash +# Find type conflicts +genesis manifest my-env --trace 2>&1 | \ + grep -E "(cannot merge|type mismatch)" + +# Check data types +spruce json base.yml | jq '.path.to.value' +spruce json overlay.yml | jq '.path.to.value' +``` + +**Solutions:** + +```yaml +# Ensure consistent types +# Bad: +base.yml: ports: "8080" +overlay.yml: ports: [8080, 8443] + +# Good: +base.yml: ports: ["8080"] +overlay.yml: ports: ["8080", "8443"] +``` + +## Advanced Debugging Techniques + +### Partial Manifest Generation + +Build manifests step-by-step: + +```bash +# 1. Base manifest only +cat > debug-base.yml < step1.yml + +# 2. Add features +spruce merge \ + step1.yml \ + dev/manifests/features/ha.yml > step2.yml + +# 3. Add environment +spruce merge \ + step2.yml \ + my-env.yml > step3.yml + +# Compare with full generation +genesis manifest my-env > full.yml +diff step3.yml full.yml +``` + +### Operator Debugging + +Debug Spruce operators: + +```bash +# Extract operators +genesis manifest my-env --no-resolve | \ + grep -E "\(\(" | \ + sed 's/.*\(\((.*)\)\).*/\1/' | \ + sort | uniq -c | sort -nr + +# Test operators individually +cat > test-operator.yml <&1 | grep -A5 -B5 "$VAR" +``` + +## Manifest Validation + +### Pre-flight Checks + +```bash +# Validate YAML syntax +for file in *.yml; do + echo "Checking $file..." + yaml-lint "$file" || yamllint "$file" +done + +# Check manifest structure +genesis manifest my-env | \ + bosh int - --path /name >/dev/null && echo "Name: OK" + +genesis manifest my-env | \ + bosh int - --path /instance_groups >/dev/null && echo "Instance Groups: OK" +``` + +### BOSH Validation + +```bash +# Full BOSH validation +genesis manifest my-env > manifest.yml +bosh int manifest.yml + +# Check specific paths +bosh int manifest.yml --path /instance_groups/0/name +bosh int manifest.yml --path /releases +bosh int manifest.yml --path /stemcells +``` + +### Schema Validation + +```yaml +# Create validation schema +# schema.yml +type: map +mapping: + name: + type: str + required: true + instance_groups: + type: seq + sequence: + - type: map + mapping: + name: + type: str + required: true + instances: + type: int + range: + min: 1 +``` + +```bash +# Validate against schema +genesis manifest my-env | \ + python -c "import yaml, sys; yaml.safe_load(sys.stdin)" && \ + echo "Valid YAML structure" +``` + +## Debugging Merge Order + +### Trace File Loading + +```bash +# Show merge order +genesis manifest my-env --trace 2>&1 | \ + grep "Loading" | nl + +# Visualize hierarchy +genesis manifest my-env --trace 2>&1 | \ + grep "Loading environment" | \ + sed 's/.*Loading environment file: //' | \ + awk '{print NR-1 ":" $0}' | \ + sed 's/^/ /' | sed 's/^ 0://' +``` + +### Test Merge Order Impact + +```bash +#!/bin/bash +# test-merge-order.sh + +# Test different merge orders +echo "=== Original Order ===" +spruce merge a.yml b.yml c.yml | spruce json + +echo "=== Reversed Order ===" +spruce merge c.yml b.yml a.yml | spruce json + +echo "=== Differences ===" +diff <(spruce merge a.yml b.yml c.yml | spruce json) \ + <(spruce merge c.yml b.yml a.yml | spruce json) +``` + +## Secret Debugging + +### Mock Secrets for Testing + +```bash +# Test without Vault +genesis manifest my-env --no-resolve > manifest-no-secrets.yml + +# Create mock secrets +cat > mock-secrets.yml < vault-paths.txt + +# Check each path +while read -r path; do + echo -n "Checking $path: " + safe exists "$path" && echo "EXISTS" || echo "MISSING" +done < vault-paths.txt +``` + +## Common Patterns and Solutions + +### Array Manipulation + +```yaml +# Appending to arrays +base_array: + - item1 + - item2 + +# Append +extended_array: (( concat base_array "[\"item3\"]" )) + +# Prepend +extended_array: (( concat "[\"item0\"]" base_array )) + +# Replace specific index +base_array.1: "modified_item2" +``` + +### Conditional Inclusion + +```yaml +# Include based on feature +instance_groups: + - name: web + instances: 2 + - (( grab meta.ha_enabled ? ha_instances : null )) + +ha_instances: + name: web-ha + instances: 3 + +meta: + ha_enabled: (( grab params.enable_ha || false )) +``` + +### Deep Merging + +```yaml +# Control merge behavior +properties: + # Deep merge (default) + database: + host: localhost + port: 5432 + + # Replace entire structure + redis: (( replace )) + host: redis.example.com + port: 6379 +``` + +## Troubleshooting Workflow + +### 1. Isolate the Problem + +```bash +# Generate partial manifests +genesis manifest my-env --partial base > base-only.yml +genesis manifest my-env --partial features > with-features.yml +genesis manifest my-env --no-resolve > without-secrets.yml +genesis manifest my-env > complete.yml + +# Compare stages +diff base-only.yml with-features.yml +diff with-features.yml without-secrets.yml +diff without-secrets.yml complete.yml +``` + +### 2. Binary Search + +```bash +#!/bin/bash +# Find problematic file + +files=(base.yml feature1.yml feature2.yml env.yml) +working=() + +for file in "${files[@]}"; do + if spruce merge "${working[@]}" "$file" >/dev/null 2>&1; then + working+=("$file") + echo "✓ $file merges successfully" + else + echo "✗ $file causes merge failure" + spruce merge "${working[@]}" "$file" + break + fi +done +``` + +### 3. Manual Resolution + +```bash +# Step through resolution +cat > manual-test.yml </dev/null || exit 1 +``` + +### 2. Use Explicit Operations + +```yaml +# Be explicit about intentions +array_items: + - (( append )) # Clearly append + - new_item + +replaced_value: (( replace )) # Clearly replace + completely: new + +merged_map: # Default deep merge + existing_key: modified_value + new_key: new_value +``` + +### 3. Document Complex Merges + +```yaml +# Document merge behavior +instance_groups: + # This will be modified by HA feature to add instances + # DO NOT use (( replace )) here + - name: web + instances: (( grab params.web_instances || 1 )) +``` + +Effective manifest debugging requires understanding both the Genesis merging process and Spruce operators. Use systematic approaches to isolate and resolve issues. \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/secret-problems.md b/docs/topics/70-troubleshooting/secret-problems.md new file mode 100644 index 00000000..dc501b73 --- /dev/null +++ b/docs/topics/70-troubleshooting/secret-problems.md @@ -0,0 +1,491 @@ +# Secret Problems + +This guide helps diagnose and resolve issues with Vault integration and secret management in Genesis. + +## Common Secret Issues + +### Cannot Connect to Vault + +**Symptoms:** +``` +Error: Could not connect to Vault at https://127.0.0.1:8200 +Error: x509: certificate signed by unknown authority +Error: 403 permission denied +``` + +**Diagnostics:** + +```bash +# Check Vault target +safe target + +# Test connectivity +safe status + +# Verify authentication +safe auth status + +# Check network +curl -k https://your-vault:8200/v1/sys/health +``` + +**Solutions:** + +1. **Set correct target:** + ```bash + safe target my-vault https://vault.example.com:8200 + ``` + +2. **Skip TLS verification (dev only):** + ```bash + safe target my-vault https://vault.example.com:8200 --skip-verify + # Or + export VAULT_SKIP_VERIFY=1 + ``` + +3. **Add CA certificate:** + ```bash + export VAULT_CACERT=/path/to/ca.crt + safe target my-vault https://vault.example.com:8200 + ``` + +### Authentication Failures + +**Symptoms:** +``` +Error: Vault token has expired +Error: permission denied +Error: 403 Forbidden +``` + +**Diagnostics:** + +```bash +# Check current token +safe vault token lookup + +# Verify token capabilities +safe vault token capabilities secret/path + +# Test authentication +safe auth status +``` + +**Solutions:** + +1. **Re-authenticate:** + ```bash + safe auth + # Or with specific method + safe auth ldap + safe auth github + safe auth token + ``` + +2. **Token renewal:** + ```bash + safe vault token renew + ``` + +3. **Check policies:** + ```bash + # List policies + safe vault policy list + + # Read policy + safe vault policy read my-policy + ``` + +### Missing Secrets + +**Symptoms:** +``` +Error: secret/path/to/secret:key not found +Error: Could not retrieve secret from Vault +``` + +**Diagnostics:** + +```bash +# Check if secret exists +safe exists secret/path/to/secret + +# List secrets in path +safe tree secret/path/to + +# Check exact path +safe get secret/path/to/secret + +# Verify secrets for environment +genesis secrets-plan my-env +``` + +**Solutions:** + +1. **Generate missing secrets:** + ```bash + genesis add-secrets my-env + ``` + +2. **Create manually:** + ```bash + # Password + safe gen secret/path password + + # SSH key + safe ssh secret/path/ssh + + # Certificate + safe x509 issue secret/path/cert \ + --name example.com \ + --ttl 365d + ``` + +3. **Check path correctness:** + ```bash + # Get actual secrets path + genesis secrets-path my-env + + # Should match references in manifest + genesis manifest my-env --no-resolve | grep vault + ``` + +## Secret Path Issues + +### Incorrect Paths + +**Diagnostics:** + +```bash +# Show expected secrets path +genesis secrets-path my-env + +# Compare with actual usage +genesis manifest my-env --no-resolve | \ + grep -o '(( *vault *"[^"]*"' | \ + sed 's/.*"\([^"]*\)".*/\1/' | \ + sort -u + +# Check path hierarchy +safe tree $(genesis secrets-path my-env) +``` + +**Common path problems:** + +```yaml +# Wrong: Hardcoded path +admin_password: (( vault "secret/prod/admin:password" )) + +# Right: Use relative path +admin_password: (( vault meta.vault "/admin:password" )) + +# Or with Genesis 2.8+ +admin_password: (( vault $GENESIS_SECRETS_PATH "/admin:password" )) +``` + +### Path Migration + +When moving environments: + +```bash +#!/bin/bash +# migrate-secrets.sh + +OLD_PATH="secret/old/path" +NEW_PATH="secret/new/path" + +# Export secrets +safe export $OLD_PATH > secrets-backup.json + +# Import to new location +safe import < secrets-backup.json +safe move $OLD_PATH $NEW_PATH + +# Update environment +sed -i "s|$OLD_PATH|$NEW_PATH|g" my-env.yml +``` + +## Secret Generation Issues + +### Failed Auto-Generation + +**Symptoms:** +``` +Error: Failed to generate secret: x509 certificate generation failed +Error: Could not generate SSH key +``` + +**Diagnostics:** + +```bash +# Check kit secret definitions +grep -A20 "credentials:" kit.yml + +# Test generation manually +safe x509 issue test-cert --ttl 90d +safe ssh test-ssh +safe gen test-password +``` + +**Solutions:** + +1. **Generate manually:** + ```bash + # For certificates + safe x509 issue secret/path/cert \ + --ca secret/path/ca \ + --ttl 365d \ + --subject "/C=US/O=Company/CN=example.com" \ + --san "*.example.com" \ + --san "10.0.0.5" + ``` + +2. **Custom generation:** + ```bash + # Complex password + safe set secret/path password=value < <(pwgen -s 32 1) + + # Multiple values + safe set secret/path \ + username=admin \ + password=secret \ + api_key=abcd1234 + ``` + +### Certificate Problems + +**Common certificate issues:** + +```bash +# Expired certificate +safe x509 show secret/path/cert | grep "Not After" + +# Wrong CA +safe x509 verify secret/path/cert --ca secret/path/ca + +# Missing SANs +safe x509 show secret/path/cert | grep -A5 "Subject Alternative Name" +``` + +**Certificate renewal:** + +```bash +# Renew existing certificate +safe x509 renew secret/path/cert --ttl 365d + +# Reissue with new parameters +safe x509 reissue secret/path/cert \ + --san "new.example.com" \ + --ttl 365d +``` + +## Secret Rotation + +### Manual Rotation + +```bash +#!/bin/bash +# rotate-secrets.sh + +ENV=$1 +SECRET_PATH=$(genesis secrets-path $ENV) + +# Rotate passwords +for path in admin db api; do + echo "Rotating $path password..." + safe gen "$SECRET_PATH/$path" password +done + +# Rotate SSH keys +safe ssh "$SECRET_PATH/ssh" --no-clobber + +# Rotate certificates (keep same CA) +safe x509 renew "$SECRET_PATH/cert" --ttl 365d +``` + +### Automated Rotation + +Using Genesis rotation features: + +```bash +# Rotate all secrets +genesis rotate-secrets my-env + +# Rotate specific secrets +genesis rotate-secrets my-env --only passwords +genesis rotate-secrets my-env --only certificates + +# Dry run +genesis rotate-secrets my-env --dry-run +``` + +## CredHub Integration + +### Switching from Vault to CredHub + +```yaml +# Environment configuration +genesis: + secrets_provider: credhub + credhub_env: my-bosh-director + +# Update references +properties: + password: (( credhub "admin-password" )) +``` + +### CredHub Debugging + +```bash +# Check CredHub connection +credhub api + +# List secrets +credhub find -n "/" + +# Get specific secret +credhub get -n "/bosh/deployment/secret" +``` + +## Recovery Procedures + +### Vault Sealed + +```bash +# Check seal status +safe vault status + +# Unseal with keys +safe vault operator unseal +# Enter unseal key when prompted + +# Or with multiple keys +for i in 1 2 3; do + echo "Unseal key $i:" + safe vault operator unseal +done +``` + +### Lost Secrets + +**Recovery from backups:** + +```bash +# From Vault backup +safe import < vault-backup-20231201.json + +# From Genesis deployment +bosh -d my-deployment manifest > manifest.yml +# Extract secrets from manifest +``` + +**Regenerate from deployment:** + +```bash +#!/bin/bash +# extract-deployed-secrets.sh + +DEPLOYMENT=$1 +OUTPUT_PATH=$2 + +# Get manifest from BOSH +bosh -d $DEPLOYMENT manifest > deployed-manifest.yml + +# Extract credentials +spruce json deployed-manifest.yml | \ + jq -r '.properties | to_entries[] | + select(.value | type == "string") | + "\(.key)=\(.value)"' > extracted-secrets.txt + +# Store in Vault +while IFS='=' read -r key value; do + safe set "$OUTPUT_PATH/$key" value="$value" +done < extracted-secrets.txt +``` + +## Best Practices + +### 1. Regular Backups + +```bash +#!/bin/bash +# backup-secrets.sh + +BACKUP_DIR="/secure/backups" +DATE=$(date +%Y%m%d-%H%M%S) + +# Export all secrets +safe export secret > "$BACKUP_DIR/vault-$DATE.json" + +# Encrypt backup +gpg --encrypt --recipient backup@example.com \ + "$BACKUP_DIR/vault-$DATE.json" + +# Remove unencrypted +rm "$BACKUP_DIR/vault-$DATE.json" +``` + +### 2. Access Policies + +```hcl +# genesis-policy.hcl +path "secret/data/genesis/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/metadata/genesis/*" { + capabilities = ["list", "read"] +} +``` + +Apply policy: +```bash +safe vault policy write genesis genesis-policy.hcl +``` + +### 3. Secret Hygiene + +```bash +# Check for weak passwords +for secret in $(safe find secret --type password); do + length=$(safe get $secret | wc -c) + if [ $length -lt 20 ]; then + echo "Weak password: $secret (length: $length)" + fi +done + +# Find expired certificates +for cert in $(safe find secret --type x509); do + if ! safe x509 validate $cert --ttl 30d; then + echo "Certificate expiring soon: $cert" + fi +done +``` + +## Troubleshooting Checklist + +### Connection Issues +- [ ] Vault target configured correctly +- [ ] Network connectivity to Vault +- [ ] TLS certificates valid +- [ ] Authentication current + +### Secret Issues +- [ ] Secrets exist at expected paths +- [ ] Correct secret path in environment +- [ ] Proper permissions on paths +- [ ] Secrets have required keys + +### Generation Issues +- [ ] Kit defines secret correctly +- [ ] CA certificates available +- [ ] Sufficient entropy for generation +- [ ] No naming conflicts + +### Rotation Issues +- [ ] Backup before rotation +- [ ] All instances updated +- [ ] Services restarted +- [ ] Old secrets archived + +Effective secret management requires understanding both Vault operations and Genesis integration patterns. Always backup before making changes. \ No newline at end of file diff --git a/docs/topics/70-troubleshooting/trace-logging.md b/docs/topics/70-troubleshooting/trace-logging.md new file mode 100644 index 00000000..7a2ef0c0 --- /dev/null +++ b/docs/topics/70-troubleshooting/trace-logging.md @@ -0,0 +1,435 @@ +# Trace Logging + +Genesis provides comprehensive trace logging capabilities for debugging complex issues. This guide covers how to enable, interpret, and use trace logs effectively. + +## Enabling Trace Logging + +### Command-Line Flag + +The simplest way to enable tracing: + +```bash +# Add --trace to any Genesis command +genesis manifest my-env --trace +genesis deploy my-env --trace +genesis check my-env --trace +``` + +### Environment Variable + +Enable tracing for all commands: + +```bash +# Set environment variable +export GENESIS_TRACE=1 + +# Now all commands include trace output +genesis manifest my-env +genesis deploy my-env + +# Disable tracing +unset GENESIS_TRACE +``` + +### Debug Mode + +For even more verbose output: + +```bash +# Maximum verbosity +export GENESIS_DEBUG=1 +export GENESIS_TRACE=1 + +genesis deploy my-env +``` + +## Understanding Trace Output + +### Log Levels + +Genesis uses different prefixes for log levels: + +``` +TRACE - Detailed execution flow +DEBUG - Debugging information +INFO - General information +WARNING - Potential issues +ERROR - Actual problems +``` + +### Trace Output Structure + +```bash +# Example trace output +TRACE> Loading environment file: us.yml +TRACE> Loading environment file: us-east.yml +TRACE> Loading environment file: us-east-prod.yml +DEBUG> Merging 3 environment files with spruce +TRACE> Executing: spruce merge --skip-eval us.yml us-east.yml us-east-prod.yml +DEBUG> Environment merge completed +TRACE> Applying kit overlay: manifests/base.yml +TRACE> Applying feature overlay: manifests/features/ha.yml +``` + +## Common Trace Patterns + +### Environment Loading + +```bash +genesis manifest my-env --trace 2>&1 | grep "Loading" + +# Output shows file loading order: +# TRACE> Loading environment file: us.yml +# TRACE> Loading environment file: us-east.yml +# TRACE> Loading environment file: us-east-1.yml +# TRACE> Loading kit manifest: manifests/base.yml +# TRACE> Loading kit manifest: manifests/features/ssl.yml +``` + +### Secret Resolution + +```bash +genesis manifest my-env --trace 2>&1 | grep -E "(vault|secret)" + +# Shows secret lookups: +# TRACE> Resolving secret: (( vault "secret/us/east/prod/admin:password" )) +# DEBUG> Executing: safe get secret/us/east/prod/admin:password +# TRACE> Secret resolved successfully +``` + +### Spruce Operations + +```bash +genesis manifest my-env --trace 2>&1 | grep -E "(spruce|merge)" + +# Shows merge operations: +# TRACE> Executing: spruce merge --skip-eval base.yml overrides.yml +# DEBUG> Spruce merge completed successfully +# TRACE> Executing: spruce eval manifest.yml +``` + +## Debugging Specific Issues + +### Manifest Generation + +**Trace manifest building process:** + +```bash +# Save full trace +genesis manifest my-env --trace > manifest-trace.log 2>&1 + +# Analyze phases +echo "=== Phase Analysis ===" +grep -n "Phase:" manifest-trace.log + +echo "=== File Loading ===" +grep -n "Loading" manifest-trace.log + +echo "=== Merge Operations ===" +grep -n "merg" manifest-trace.log + +echo "=== Errors ===" +grep -n -i "error" manifest-trace.log +``` + +### Feature Resolution + +**Debug feature selection:** + +```bash +genesis manifest my-env --trace 2>&1 | \ + grep -E "(feature|blueprint)" | \ + tee feature-trace.log + +# Analyze feature application +grep "Applying feature" feature-trace.log +grep "blueprint hook" feature-trace.log +``` + +### Hook Execution + +**Trace hook execution:** + +```bash +# Enable hook tracing +GENESIS_TRACE=1 genesis new my-test-env 2>&1 | \ + grep -E "(hook|executing)" + +# Shows: +# TRACE> Executing hook: new +# TRACE> Hook environment: GENESIS_ROOT=/path/to/repo +# TRACE> Hook environment: GENESIS_ENVIRONMENT=my-test-env +# DEBUG> Hook completed with exit code: 0 +``` + +## Advanced Tracing + +### Time-Based Analysis + +```bash +# Add timestamps to trace +genesis manifest my-env --trace 2>&1 | \ + while IFS= read -r line; do + echo "[$(date '+%Y-%m-%d %H:%M:%S.%3N')] $line" + done | tee timed-trace.log + +# Find slow operations +awk '/TRACE.*Executing/ { + cmd=$0; getline; + if (/completed/) print cmd " - " $0 +}' timed-trace.log +``` + +### Filtered Tracing + +```bash +# Trace only specific components +genesis manifest my-env --trace 2>&1 | \ + grep -E "(vault|secret|spruce)" > filtered-trace.log + +# Trace errors and warnings only +genesis deploy my-env --trace 2>&1 | \ + grep -E "^(ERROR|WARNING)" > issues.log +``` + +### Structured Logging + +```bash +#!/bin/bash +# structured-trace.sh + +# Parse trace into JSON +genesis manifest my-env --trace 2>&1 | \ + perl -ne ' + if (/^(TRACE|DEBUG|INFO|WARNING|ERROR)>\s*(.*)/) { + $level = $1; + $msg = $2; + $time = `date -u +%s`; + chomp $time; + print qq({"time":$time,"level":"$level","message":"$msg"}\n); + } + ' > trace.jsonl + +# Query with jq +jq 'select(.level == "ERROR")' trace.jsonl +``` + +## Trace Log Analysis + +### Common Patterns + +**Identify bottlenecks:** + +```bash +# Find long-running operations +genesis manifest my-env --trace --time 2>&1 | \ + grep -E "took [0-9]+\.[0-9]+s" | \ + sort -k2 -n -r | head -10 +``` + +**Track execution flow:** + +```bash +# Create execution graph +genesis manifest my-env --trace 2>&1 | \ + grep "TRACE>" | \ + awk '{$1=""; print NR ": " $0}' > execution-flow.txt +``` + +### Error Analysis + +```bash +#!/bin/bash +# analyze-errors.sh + +LOG_FILE="genesis-trace.log" +genesis deploy my-env --trace > $LOG_FILE 2>&1 + +echo "=== Error Summary ===" +grep -i "error" $LOG_FILE | wc -l +echo " errors found" + +echo -e "\n=== Error Context ===" +grep -B5 -A5 -i "error" $LOG_FILE + +echo -e "\n=== Failed Operations ===" +grep -E "(failed|exit code: [^0])" $LOG_FILE +``` + +## Performance Profiling + +### Trace Timing + +```bash +# Enable timing information +genesis manifest my-env --trace --time 2>&1 | \ + tee performance-trace.log + +# Extract timing data +grep "took" performance-trace.log | \ + sed 's/.*took \([0-9.]*\)s.*/\1/' | \ + awk '{sum+=$1; count++} END { + print "Total: " sum "s"; + print "Average: " sum/count "s"; + }' +``` + +### Operation Breakdown + +```bash +# Categorize operations by time +genesis manifest my-env --trace --time 2>&1 | \ + grep -E "(Loading|Merging|Executing|Resolving).*took" | \ + awk -F'took ' '{ + split($1, op, ">"); + split($2, time, "s"); + category = op[2]; + gsub(/^[ \t]+|[ \t]+$/, "", category); + split(category, cat, " "); + times[cat[1]] += time[1]; + counts[cat[1]]++; + } + END { + for (c in times) { + printf "%-20s: %8.3fs (%d operations, avg: %.3fs)\n", + c, times[c], counts[c], times[c]/counts[c]; + } + }' | sort -k2 -n -r +``` + +## Logging Best Practices + +### 1. Targeted Tracing + +Don't enable trace for everything: + +```bash +# Good: Trace specific issue +genesis manifest problematic-env --trace > issue.log 2>&1 + +# Bad: Trace everything always +export GENESIS_TRACE=1 # In .bashrc +``` + +### 2. Log Rotation + +Manage trace log files: + +```bash +# Rotate logs script +#!/bin/bash +LOG_DIR="$HOME/.genesis/logs" +mkdir -p "$LOG_DIR" + +# Run with logging +genesis deploy my-env --trace > \ + "$LOG_DIR/deploy-$(date +%Y%m%d-%H%M%S).log" 2>&1 + +# Clean old logs +find "$LOG_DIR" -name "*.log" -mtime +30 -delete +``` + +### 3. Structured Debugging + +Create debugging workflows: + +```bash +#!/bin/bash +# debug-deployment.sh + +ENV=$1 +ISSUE=$2 +DEBUG_DIR="debug-$ENV-$(date +%Y%m%d-%H%M%S)" + +mkdir -p "$DEBUG_DIR" + +echo "Collecting debug information for $ENV..." + +# Manifest trace +genesis manifest $ENV --trace > \ + "$DEBUG_DIR/manifest-trace.log" 2>&1 + +# Check trace +genesis check $ENV --trace > \ + "$DEBUG_DIR/check-trace.log" 2>&1 + +# Environment info +genesis info $ENV > \ + "$DEBUG_DIR/info.txt" 2>&1 + +# Create summary +cat > "$DEBUG_DIR/summary.txt" < Resolving secret: (( vault "secret/path:key" )) +DEBUG> Executing: safe get secret/path:key +ERROR> Failed to retrieve secret: dial tcp 127.0.0.1:8200: connection refused +``` + +**Interpretation**: Vault is not accessible at the expected address. + +### Merge Conflicts + +``` +TRACE> Executing: spruce merge base.yml overlay.yml +ERROR> merge conflict: key 'params.size' has conflicting values +DEBUG> base.yml defines params.size as integer +DEBUG> overlay.yml defines params.size as string +``` + +**Interpretation**: Type mismatch in parameter override. + +### Missing Files + +``` +TRACE> Loading environment file: production.yml +TRACE> Looking for parent: prod.yml +ERROR> Could not find parent environment: prod.yml +TRACE> Searched in: ., .., ../.. +``` + +**Interpretation**: Hierarchical environment file missing. + +## Trace Output Reference + +### Standard Trace Messages + +| Pattern | Meaning | +|---------|---------| +| `Loading environment file:` | Reading YAML environment file | +| `Loading kit manifest:` | Reading kit-provided YAML | +| `Executing:` | Running external command | +| `Resolving secret:` | Looking up Vault secret | +| `Applying feature:` | Adding feature-specific configuration | +| `Merging files with spruce` | Combining YAML files | +| `Hook environment:` | Environment variables for hooks | +| `Validating manifest` | Pre-deployment checks | + +### Debug Flags + +| Flag | Purpose | Use Case | +|------|---------|----------| +| `--trace` | Enable trace logging | General debugging | +| `--debug` | Extra debug output | Deep troubleshooting | +| `--time` | Add timing information | Performance analysis | +| `--no-color` | Disable color output | Log processing | +| `--json` | JSON output (where supported) | Automation | + +Trace logging is a powerful debugging tool. Use it judiciously to diagnose issues without overwhelming yourself with information. \ No newline at end of file diff --git a/docs/topics/90-reference-guides/.keep b/docs/topics/90-reference-guides/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/topics/90-reference-guides/environment-variables.md b/docs/topics/90-reference-guides/environment-variables.md new file mode 100644 index 00000000..68919a66 --- /dev/null +++ b/docs/topics/90-reference-guides/environment-variables.md @@ -0,0 +1,596 @@ +# Environment Variables Reference + +This document provides a comprehensive reference for all environment variables used by Genesis, organized by category for easier navigation. + +## Core System & Configuration + +These fundamental variables control Genesis operation and basic configuration. + +### GENESIS_VERSION +- **Description**: Current version of Genesis being used. Set internally during startup. +- **Default**: Set automatically +- **Used By**: Version compatibility checks, prerequisite validation +- **Example**: `GENESIS_VERSION="2.8.0"` + +### GENESIS_LIB +- **Description**: Path to Genesis library directory. Can be overridden to use alternate library location. +- **Default**: `bin/lib` under Genesis installation directory +- **Used By**: Loading kit modules, command modules, library components +- **Example**: `GENESIS_LIB="/opt/genesis/lib"` + +### GENESIS_CONFIG_NO_CHECK +- **Description**: Skip configuration validation checks when set. +- **Used By**: Kit validation, deployment operations +- **Example**: `GENESIS_CONFIG_NO_CHECK=1` + +### GENESIS_CONFIG_AUTOMATIC_UPGRADE +- **Description**: Controls automatic configuration upgrades during tests. +- **Values**: `no`, `yes`, `silent` +- **Used By**: Test scripts, configuration management +- **Example**: `GENESIS_CONFIG_AUTOMATIC_UPGRADE=yes` + +### GENESIS_MIN_VERSION +- **Description**: Minimum Genesis version required for compatibility. +- **Used By**: Compatibility checks, environment validation +- **Example**: `GENESIS_MIN_VERSION="2.7.0"` + +### GENESIS_MIN_VERSION_FOR_KIT +- **Description**: Minimum Genesis version required for a specific kit. +- **Used By**: Kit compatibility validation +- **Example**: `GENESIS_MIN_VERSION_FOR_KIT="2.8.0"` + +### GENESIS_USING_EMBEDDED +- **Description**: Indicates Genesis is using embedded mode. +- **Default**: `1` when applicable +- **Used By**: Command execution, state management + +### GENESIS_IS_HELPING_YOU +- **Description**: Enables extended help and assistance mode. +- **Used By**: Operation control, state management + +## Output, Logging & Display Control + +Variables affecting output formatting, logging, and terminal display. + +### GENESIS_SHOW_TIMINGS +- **Description**: Show duration of key operations when set. +- **Used By**: Timing output, operation monitoring +- **Example**: `GENESIS_SHOW_TIMINGS=1` + +### GENESIS_NO_UTF8 +- **Description**: Disable UTF-8 output for limited character support environments. +- **Used By**: Character output control, display formatting +- **Example**: `GENESIS_NO_UTF8=1` + +### GENESIS_QUIET +- **Description**: Reduce output verbosity, showing only errors and critical information. +- **Used By**: Output control across all commands +- **Example**: `GENESIS_QUIET=1` + +### GENESIS_LOG_STYLE +- **Description**: Control output style formatting. +- **Values**: `plain`, `color`, `html` +- **Default**: `plain` +- **Example**: `GENESIS_LOG_STYLE=color` + +### GENESIS_OUTPUT_COLUMNS +- **Description**: Control width of text output. +- **Default**: `80` columns +- **Used By**: Terminal output formatting +- **Example**: `GENESIS_OUTPUT_COLUMNS=120` + +### GENESIS_NO_BOXES +- **Description**: Disable box-drawing characters in terminal output. +- **Used By**: Terminal formatting +- **Example**: `GENESIS_NO_BOXES=1` + +### GENESIS_NOCOLOR +- **Description**: Disable colored output in terminal messages. +- **Used By**: Color formatting control +- **Example**: `GENESIS_NOCOLOR=1` + +### GENESIS_STACK_TRACE +- **Description**: Enable stack trace logging for debugging. +- **Values**: `true` when enabled +- **Used By**: Error reporting, debugging +- **Example**: `GENESIS_STACK_TRACE=true` + +### GENESIS_TRACE +- **Description**: Enable trace-level logging for detailed debugging. +- **Values**: `true` when enabled +- **Used By**: Detailed trace output, Vault operations +- **Example**: `GENESIS_TRACE=true` + +### GENESIS_DEBUG +- **Description**: Enable debug-level logging for Genesis operations. +- **Values**: `true` when enabled +- **Used By**: Debug logging, test scripts +- **Example**: `GENESIS_DEBUG=true` + +### GENESIS_SHOW_BOSH_CMD +- **Description**: Display BOSH commands during execution. +- **Values**: `true` when enabled +- **Example**: `GENESIS_SHOW_BOSH_CMD=true` + +## Path & Directory Management + +Variables for managing directories and file paths. + +### GENESIS_CALLER_DIR +- **Description**: Directory where Genesis was originally invoked. +- **Used By**: Path resolution, context maintenance +- **Note**: Preferred over deprecated GENESIS_ORIGINATING_DIR + +### GENESIS_DEPLOYMENT_ROOT +- **Description**: Root directory of current deployment. +- **Set When**: Using @-notation for environments +- **Used By**: Repository location, environment files + +### GENESIS_HOME +- **Description**: Home directory for Genesis. +- **Default**: `$HOME` +- **Used By**: Environment setup, directory initialization + +### GENESIS_KIT_PATH +- **Description**: File path to the current kit. +- **Set By**: Kit initialization +- **Used By**: Resource location, path validation + +### GENESIS_PACK_PATH +- **Description**: Path for Genesis pack operations. +- **Used By**: Pack command, test cases + +### GENESIS_ORIGINATING_DIR (Deprecated) +- **Description**: Directory from which Genesis was invoked. +- **Status**: Deprecated - use GENESIS_CALLER_DIR instead + +### GENESIS_ROOT +- **Description**: Root directory for Genesis operations. +- **Used By**: Root directory configuration, pipeline adjustments + +### GENESIS_ROOT_CA_PATH +- **Description**: Path to root CA certificate. +- **Used By**: CA path configuration, Vault operations + +### GENESIS_TOPDIR +- **Description**: Top-level directory for Genesis operations. +- **Used By**: Test scripts +- **Example**: `GENESIS_TOPDIR="/path/to/genesis"` + +### GENESIS_MANIFEST_FILE +- **Description**: Path to unredacted, unpruned manifest. +- **Set By**: Kit during manifest generation + +### GENESIS_PREDEPLOY_DATAFILE +- **Description**: File path for pre-deployment data. +- **Used By**: Pre-deployment data storage + +## Command, Hook & Execution Control + +Variables controlling command execution and hooks. + +### GENESIS_CALLBACK_BIN +- **Description**: Path to Genesis binary for callbacks. +- **Used By**: Command execution, embedding + +### GENESIS_CALL_BIN +- **Description**: Binary path for Genesis commands. +- **Used By**: Command embedding and execution + +### GENESIS_CALL_ENV +- **Description**: Environment-specific command execution. +- **Note**: Preferred over deprecated GENESIS_CALL + +### GENESIS_CALL_FULL +- **Description**: Full command call for Genesis. +- **Used By**: Command logging + +### GENESIS_KIT_HOOK +- **Description**: Current hook being executed. +- **Used By**: Hook-specific operations + +### GENESIS_COMMAND +- **Description**: Current command being executed. +- **Used By**: Command execution and logging + +### GENESIS_COMMANDS +- **Description**: Mapping of command names to definitions. +- **Used By**: Command registration and validation + +### GENESIS_ADDON_SCRIPT +- **Description**: Name of addon script to execute. +- **Used By**: Addon script execution + +### GENESIS_NO_MODULE_HOOKS +- **Description**: Disable module hooks during operations. +- **Used By**: Hook loading control + +### GENESIS_DEPLOY_DRYRUN +- **Description**: Indicates deployment is a dry-run. +- **Values**: `true` or `false` + +### GENESIS_DEPLOY_OPTIONS +- **Description**: JSON representation of deployment options. +- **Set By**: Deployment initialization + +### GENESIS_DEPLOY_RC +- **Description**: Return code of BOSH deploy call. +- **Values**: `0` for success, non-zero for failure + +## Environment & Kit Management + +Variables for environment configurations and kit management. + +### GENESIS_ENVIRONMENT +- **Description**: Name of current environment. +- **Used By**: Environment-specific operations +- **Example**: `GENESIS_ENVIRONMENT="us-east-prod"` + +### GENESIS_ENV_IAAS +- **Description**: Infrastructure as a Service type. +- **Values**: `aws`, `azure`, `gcp`, `vsphere`, etc. +- **Example**: `GENESIS_ENV_IAAS="aws"` + +### GENESIS_PREFIX_TYPE +- **Description**: How environment prefixes are handled. +- **Used By**: Prefix configuration + +### GENESIS_PREFIX_SEARCH +- **Description**: Search pattern for environment prefixes. +- **Used By**: Prefix search operations + +### GENESIS_ENV_KIT_OVERRIDE_FILES +- **Description**: Override files for environment's kit. +- **Used By**: Kit override handling + +### GENESIS_ENV_REF +- **Description**: Reference to the environment. +- **Used By**: Environment reference management + +### GENESIS_ENV_SCALE +- **Description**: Scale of the environment. +- **Used By**: Scale-specific operations + +### GENESIS_ENV_VAULT_DESCRIPTOR +- **Description**: Vault descriptor for environment. +- **Used By**: Vault operations + +### GENESIS_ENVIRONMENT_NAME +- **Description**: Environment name for logging. +- **Used By**: Hooks and scripts + +### GENESIS_ENVIRONMENT_PARAMS +- **Description**: Environment parameters in JSON format. +- **Used By**: Parameter management + +### GENESIS_EXECUTABLE_ENVS +- **Description**: Configuration for executable environments. +- **Used By**: Environment execution control + +### GENESIS_HONOR_ENV +- **Description**: Honor current environment settings. +- **Used By**: BOSH operations, CI pipelines + +### GENESIS_LEGACY +- **Description**: Allow environment name mismatches. +- **Used By**: Conditional checks, testing + +### GENESIS_REQUESTED_FEATURES +- **Description**: List of requested features. +- **Used By**: Feature processing and management + +### GENESIS_RUNTIME_CONFIG +- **Description**: Runtime configuration file path. +- **Used By**: Runtime config validation + +### GENESIS_TYPE +- **Description**: Type of Genesis environment. +- **Example**: `GENESIS_TYPE="bosh"` + +### GENESIS_UNEVALED_PARAMS +- **Description**: Prevent parameter evaluation. +- **Values**: `1` when enabled +- **Example**: `GENESIS_UNEVALED_PARAMS=1` + +### GENESIS_KIT_ID +- **Description**: ID of current kit. +- **Used By**: Kit identification + +### GENESIS_KIT_NAME +- **Description**: Name of current kit. +- **Used By**: Kit-specific operations +- **Example**: `GENESIS_KIT_NAME="concourse"` + +### GENESIS_KIT_VERSION +- **Description**: Version of current kit. +- **Used By**: Version-specific operations +- **Example**: `GENESIS_KIT_VERSION="4.0.0"` + +### GENESIS_PREFIX +- **Description**: Prefix for environment operations. +- **Used By**: Environment prefixes + +### GENESIS_CLOUD_CONFIG +- **Description**: Cloud configuration data. +- **Used By**: Cloud config parsing + +### GENESIS_CLOUD_CONFIG_SUBTYPE +- **Description**: Subtype of cloud configuration. +- **Used By**: Cloud-config hook determination + +### GENESIS_OCFP_CONFIG_MOUNT +- **Description**: Vault path for ocfp_config data. +- **Used By**: Config data retrieval + +### GENESIS_CREDHUB_EXODUS_SOURCE +- **Description**: Source for CredHub Exodus data. +- **Used By**: CredHub parameter setup + +### GENESIS_CREDHUB_EXODUS_SOURCE_OVERRIDE +- **Description**: Override default CredHub Exodus source. +- **Used By**: Custom CredHub configurations + +### GENESIS_CREDHUB_ROOT +- **Description**: Root path for CredHub operations. +- **Used By**: CredHub path construction + +### GENESIS_EXODUS +- **Description**: Exodus data handling. +- **Used By**: Exodus data operations + +### GENESIS_EXODUS_BASE +- **Description**: Full Vault path of Exodus data. +- **Used By**: Vault path construction + +### GENESIS_EXODUS_MOUNT +- **Description**: Vault path for Exodus data storage. +- **Used By**: Data storage management + +### GENESIS_EXODUS_MOUNT_OVERRIDE +- **Description**: Override default Exodus mount point. +- **Used By**: Custom mount handling + +### GENESIS_CHECK_YAML_ON_DEPLOY +- **Description**: Enable YAML validation during deployment. +- **Used By**: YAML validation control + +### GENESIS_CONFIRM_RELEASE_OVERRIDES +- **Description**: Control release override confirmation. +- **Used By**: Release override handling + +### GENESIS__LOOKUP_MERGED_MANIFEST +- **Description**: Enable merged manifest lookup. +- **Used By**: Manifest lookup control + +## BOSH Integration + +Variables for BOSH director interaction. + +### GENESIS_BOSH_COMMAND +- **Description**: Path to BOSH command binary. +- **Used By**: BOSH command execution +- **Example**: `GENESIS_BOSH_COMMAND="/usr/local/bin/bosh"` + +### GENESIS_BOSH_ENVIRONMENT +- **Description**: URI of BOSH environment. +- **Used By**: Environment setup and validation +- **Example**: `GENESIS_BOSH_ENVIRONMENT="https://10.0.0.6:25555"` + +### GENESIS_DEFAULT_BOSH_TARGET +- **Description**: Default BOSH target selection. +- **Values**: `parent`, `self`, `ask` +- **Default**: `ask` + +### GENESIS_BOSH_VERIFIED +- **Description**: Track BOSH alias verification. +- **Used By**: Alias verification logic + +### GENESIS_BOSHVARS_FILE +- **Description**: Path to BOSH variables file. +- **Used By**: Variable file handling + +### GENESIS_USE_CREATE_ENV +- **Description**: Use create-env for deployments. +- **Values**: `true` when applicable +- **Example**: `GENESIS_USE_CREATE_ENV=true` + +## Vault & Secrets Management + +Variables for Vault and secret handling. + +### GENESIS_TARGET_VAULT +- **Description**: Target Vault URL. +- **Used By**: Vault operations +- **Example**: `GENESIS_TARGET_VAULT="https://vault.example.com"` + +### GENESIS_SECRETS_MOUNT +- **Description**: Vault mount path for secrets. +- **Default**: `/` within Vault +- **Example**: `GENESIS_SECRETS_MOUNT="/secret"` + +### GENESIS_NO_VAULT +- **Description**: Disable Vault integration. +- **Used By**: Vault usage configuration + +### GENESIS_SECRETS_BASE +- **Description**: Base Vault path for secrets. +- **Example**: `GENESIS_SECRETS_BASE="/secret/genesis"` + +### GENESIS_SECRETS_MOUNT_OVERRIDE +- **Description**: Override default secrets mount. +- **Values**: `true` when enabled + +### GENESIS_SECRETS_SLUG +- **Description**: Vault path component for environment. +- **Example**: `GENESIS_SECRETS_SLUG="us-east-prod"` + +### GENESIS_SECRETS_SLUG_OVERRIDE +- **Description**: Override default secrets slug. +- **Values**: `true` when enabled + +### GENESIS_VAULT_ENV_SLUG +- **Description**: Vault slug for environment. +- **Example**: `GENESIS_VAULT_ENV_SLUG="base/extended"` + +### GENESIS_VERIFY_VAULT +- **Description**: Vault connection verification status. +- **Values**: `1` when verified + +### GENESIS_SECRET_ACTION +- **Description**: Action to perform on secrets. +- **Values**: `add`, `rotate`, `check` +- **Example**: `GENESIS_SECRET_ACTION="rotate"` + +### GENESIS_RENEW_SUBJECT +- **Description**: Update certificate subject during renewal. +- **Used By**: Certificate renewal operations + +### GENESIS_HIDE_PROBLEMATIC_SECRETS +- **Description**: Hide problematic secrets from output. +- **Used By**: Secret visibility control + +### GENESIS_SECRETS_DATAFILE +- **Description**: File path for storing secrets. +- **Example**: `GENESIS_SECRETS_DATAFILE="/tmp/secrets.yml"` + +### GENESIS_SKIP_SECRET_DEFINITION_VALIDATION +- **Description**: Skip secret definition validation. +- **Values**: `true` when enabled + +### GENESIS_SECRETS_PATH (Deprecated) +- **Description**: Path for secrets. +- **Status**: Deprecated in v2.7.0 +- **Note**: Use GENESIS_SECRETS_BASE instead + +### GENESIS_VAULT_PREFIX (Deprecated) +- **Description**: Vault prefix. +- **Status**: Deprecated in v2.7.0 +- **Note**: Use GENESIS_SECRETS_BASE instead + +## CI/CD Pipeline Variables + +Variables for continuous integration and deployment. + +### GENESIS_PIPELINE_DEPLOY_BRANCH +- **Description**: Git branch for pipeline deployments. +- **Used By**: CI pipeline operations + +### GENESIS_CI +- **Description**: Indicates CI environment. +- **Used By**: Pipeline behavior adjustment + +### GENESIS_CI_BASE +- **Description**: Base path for CI secrets in Vault. +- **Used By**: CI-specific data organization + +### GENESIS_CI_DIR +- **Description**: Directory containing CI scripts. +- **Used By**: CI resource location + +### GENESIS_CI_MOUNT +- **Description**: Mount point for CI secrets. +- **Default**: `/` + +### GENESIS_CI_MOUNT_OVERRIDE +- **Description**: Override default CI mount point. +- **Used By**: Custom CI Vault paths + +## Testing & Development + +Variables for testing and development. + +### GENESIS_DEV_MODE +- **Description**: Enable development mode features. +- **Used By**: Development-specific code paths + +### GENESIS_UNDER_TEST +- **Description**: Running under test harness. +- **Used By**: Test behavior modifications + +### GENESIS_TESTING +- **Description**: Running in testing mode. +- **Values**: `yes` when applicable +- **Example**: `GENESIS_TESTING=yes` + +### GENESIS_IGNORE_EVAL +- **Description**: Prevent evaluation catching exits. +- **Used By**: Test evaluation control + +### GENESIS_INDEX +- **Description**: Index-related test configuration. +- **Used By**: Test index validation + +### GENESIS_EXPECT_TRACE +- **Description**: Enable trace logging in tests. +- **Used By**: Test trace control + +### GENESIS_TEST_VAULT_VERSION +- **Description**: Version of test Vault. +- **Example**: `GENESIS_TEST_VAULT_VERSION="1.0.2"` + +### GENESIS_TESTING_BOSH_CPI +- **Description**: Custom BOSH CPI for testing. +- **Example**: `GENESIS_TESTING_BOSH_CPI="warden"` + +### GENESIS_TESTING_CHECK_SECRETS_PRESENCE_ONLY +- **Description**: Only check secret presence in tests. +- **Values**: `true` when enabled + +### GENESIS_TESTING_DEV_VERSION_DETECTION +- **Description**: Control dev version detection. +- **Values**: `false` to disable + +## Miscellaneous + +Other variables and settings. + +### GENESIS_NETWORK_TIMEOUT +- **Description**: Network operation timeout. +- **Default**: `10` seconds +- **Used By**: Network timeout configuration + +### GENESIS_CALL (Deprecated) +- **Description**: Command execution. +- **Status**: Deprecated - use GENESIS_CALL_ENV + +## Usage Examples + +### Enable Full Debugging +```bash +export GENESIS_DEBUG=true +export GENESIS_TRACE=true +export GENESIS_STACK_TRACE=true +export GENESIS_SHOW_BOSH_CMD=true +genesis deploy my-env +``` + +### CI/CD Pipeline Setup +```bash +export GENESIS_CI=true +export GENESIS_CI_BASE="/secret/ci" +export GENESIS_PIPELINE_DEPLOY_BRANCH="main" +export GENESIS_QUIET=1 +``` + +### Development Environment +```bash +export GENESIS_DEV_MODE=1 +export GENESIS_TESTING=yes +export GENESIS_SHOW_TIMINGS=1 +export GENESIS_LOG_STYLE=color +``` + +### Vault Configuration +```bash +export GENESIS_TARGET_VAULT="https://vault.example.com:8200" +export GENESIS_SECRETS_MOUNT="/secret" +export GENESIS_SECRETS_BASE="/secret/genesis/prod" +``` + +## Best Practices + +1. **Use Configuration File**: For persistent settings, use `~/.genesis/config` instead of environment variables +2. **Debugging**: Enable trace and debug only when needed to avoid verbose output +3. **CI/CD**: Set appropriate variables in pipeline configurations +4. **Security**: Avoid exposing sensitive values in environment variables +5. **Documentation**: Document custom environment variable usage in your deployment repos \ No newline at end of file diff --git a/docs/topics/90-reference-guides/genesis-configuration.md b/docs/topics/90-reference-guides/genesis-configuration.md new file mode 100644 index 00000000..4387730e --- /dev/null +++ b/docs/topics/90-reference-guides/genesis-configuration.md @@ -0,0 +1,641 @@ +# Genesis Configuration + +This guide provides comprehensive documentation for configuring Genesis using the `~/.genesis/config` file. + +## Overview + +Genesis uses a YAML configuration file to customize its behavior across environments and deployments. This configuration file provides a centralized way to manage Genesis settings without relying on environment variables. + +## Configuration File Location + +The configuration file is located at: +``` +~/.genesis/config +``` + +Genesis automatically creates this directory and file on first use if they don't exist. + +## Configuration Options + +### BOSH Target Configuration + +Control how Genesis selects BOSH directors when multiple options are available. + +#### default_bosh_target + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `default_bosh_target` | enum | `ask` | `ask`, `self`, `parent` | `GENESIS_DEFAULT_BOSH_TARGET` | + +**Description**: Controls default BOSH director targeting behavior. + +**Values**: +- `ask`: Prompt user to select a BOSH director (default) +- `self`: Use current environment as BOSH director +- `parent`: Use BOSH director that deployed current environment + +**Example**: +```yaml +default_bosh_target: ask +``` + +**Notes**: +- BOSH environments using create-env always use `self` +- Non-BOSH director environments always use `parent` +- This setting only applies when there's ambiguity + +### Repository Configuration + +Manage how Genesis handles deployment repositories. + +#### legacy_repo_suffix + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `legacy_repo_suffix` | boolean | `false` | `true`, `false` | `GENESIS_LEGACY_REPO_SUFFIX` | + +**Description**: Enable support for legacy repository naming conventions (e.g., `concourse-deployments`). + +**Example**: +```yaml +legacy_repo_suffix: false +``` + +#### deployment_roots + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `deployment_roots` | array | `[]` | paths or labeled paths | `GENESIS_DEPLOYMENT_ROOTS` | + +**Description**: Configure deployment root directories for organizing Genesis repositories. + +**Format Options**: + +1. **Simple paths**: + ```yaml + deployment_roots: + - /home/user/deployments + - /opt/genesis/deployments + ``` + +2. **Labeled paths**: + ```yaml + deployment_roots: + - production: /opt/genesis/prod + - staging: /opt/genesis/staging + - development: /tmp/genesis-dev + ``` + +3. **Mixed format**: + ```yaml + deployment_roots: + - /home/user/deployments + - prod: /opt/genesis/prod + - staging: /opt/genesis/staging + ``` + +**Environment Variable Format**: +```bash +# Colon-separated paths +export GENESIS_DEPLOYMENT_ROOTS="/path1:/path2" + +# With labels (semicolon for label=path) +export GENESIS_DEPLOYMENT_ROOTS="/path1;prod=/opt/prod;staging=/opt/staging" +``` + +**Usage**: Labels allow referencing deployment roots by name in commands. + +### Genesis Behavior + +Control core Genesis operational behavior. + +#### embedded_genesis + +| Option | Type | Default | Values | +|--------|------|---------|--------| +| `embedded_genesis` | enum | `ignore` | `ignore`, `check`, `warn` | + +**Description**: Control behavior when detecting embedded Genesis installations. + +**Values**: +- `ignore`: Don't check for embedded Genesis +- `check`: Check but don't warn users +- `warn`: Check and warn about embedded Genesis + +**Example**: +```yaml +embedded_genesis: ignore +``` + +#### automatic_config_upgrade + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `automatic_config_upgrade` | enum | `no` | `no`, `yes`, `silent` | `GENESIS_CONFIG_AUTOMATIC_UPGRADE` | + +**Description**: Control automatic configuration file upgrades. + +**Values**: +- `no`: Never automatically upgrade +- `yes`: Upgrade with user confirmation +- `silent`: Upgrade without prompting + +**Example**: +```yaml +automatic_config_upgrade: no +``` + +### Display Configuration + +Customize Genesis output and display. + +#### output_style + +| Option | Type | Default | Values | +|--------|------|---------|--------| +| `output_style` | enum | `plain` | `plain`, `fun`, `pointer` | + +**Description**: Configure visual style of Genesis output. + +**Values**: +- `plain`: Simple text output +- `fun`: Enhanced output with emojis and colors +- `pointer`: Output with pointer indicators + +**Example**: +```yaml +output_style: fun +``` + +#### show_duration + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `show_duration` | boolean | `false` | `true`, `false` | `GENESIS_SHOW_DURATION` | + +**Description**: Display execution time for operations. + +**Example**: +```yaml +show_duration: true +``` + +### Deployment Behavior + +Control deployment-specific operations. + +#### fix_on_deploy + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `fix_on_deploy` | enum | `never` | `always`, `ask`, `never` | `GENESIS_FIX_ON_DEPLOY` | + +**Description**: Automatically fix issues during deployment. + +**Values**: +- `always`: Automatically fix without prompting +- `ask`: Prompt before fixing issues +- `never`: Never attempt automatic fixes + +**Example**: +```yaml +fix_on_deploy: ask +``` + +#### confirm_release_overrides + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `confirm_release_overrides` | enum | - | `always`, `outdated`, `never` | `GENESIS_CONFIRM_RELEASE_OVERRIDES` | + +**Description**: When to confirm BOSH release overrides. + +**Values**: +- `always`: Always confirm overrides +- `outdated`: Only confirm outdated releases +- `never`: Never confirm overrides + +**Example**: +```yaml +confirm_release_overrides: outdated +``` + +### Cache and Storage + +Configure caching and storage locations. + +#### spec_cache_dir + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `spec_cache_dir` | string | `""` | any path | `GENESIS_SPEC_CACHE_DIR` | + +**Description**: Directory for caching specification files. + +**Example**: +```yaml +spec_cache_dir: "/var/cache/genesis/specs" +``` + +#### bosh_logs_path + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `bosh_logs_path` | string | `/bosh_logs` | path template | `GENESIS_DEPLOYMENT_LOGS_PATH` | + +**Description**: Path template for BOSH deployment logs. + +**Placeholders**: +- ``: Replaced with actual deployment root + +**Example**: +```yaml +bosh_logs_path: "/var/log/genesis//bosh_logs" +``` + +### Warning Suppression + +Control which warnings Genesis displays. + +#### suppress_warnings + +| Option | Type | Default | +|--------|------|---------| +| `suppress_warnings` | hash | see below | + +**Sub-options**: + +| Warning | Type | Default | Environment Variable | +|---------|------|---------|---------------------| +| `oversized_secrets` | boolean | `false` | `GENESIS_SUPRESS_OVERSIZED_SECRETS_WARNING` | +| `bosh_target` | boolean | `false` | `GENESIS_SUPPRESS_BOSH_TARGET_WARNING` | + +**Description**: Selectively suppress specific warnings. + +**Example**: +```yaml +suppress_warnings: + oversized_secrets: true + bosh_target: false +``` + +### Logging Configuration + +Configure detailed logging for Genesis operations. + +#### logs + +| Option | Type | Default | +|--------|------|---------| +| `logs` | array | `[]` | + +**Description**: Array of log configurations, each defining a separate log destination. + +**Log Entry Schema**: + +| Option | Type | Default | Values | Required | +|--------|------|---------|--------|----------| +| `file` | string | - | any path | ✓ | +| `level` | enum | `INFO` | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OUTPUT` | | +| `show_stack` | enum | `default` | `default`, `none`, `full`, `current`, `fatal` | | +| `style` | enum | `plain` | `plain`, `fun`, `pointer`, `rfc-5424` | | +| `timestamp` | boolean | `false` | `true`, `false` | | +| `truncate` | boolean | `false` | `true`, `false` | *future* | +| `lifespan` | enum | `forever` | `forever`, `current`, `N days` | *future* | + +**Log Levels**: +- `TRACE`: Most verbose, all operations +- `DEBUG`: Detailed debugging +- `INFO`: General information +- `WARN`: Warning messages +- `ERROR`: Error messages only +- `OUTPUT`: Command output only + +**Stack Trace Options**: +- `default`: Based on log level +- `none`: Never show traces +- `full`: Always show full traces +- `current`: Current context only +- `fatal`: Fatal errors only + +**Style Options**: +- `plain`: Simple text +- `fun`: Enhanced with colors +- `pointer`: Pointer indicators +- `rfc-5424`: Standard syslog format + +**Example**: +```yaml +logs: + # Main application log + - file: "/var/log/genesis/genesis.log" + level: INFO + timestamp: true + style: plain + + # Debug log + - file: "/tmp/genesis-debug.log" + level: DEBUG + style: rfc-5424 + show_stack: full + + # Error log + - file: "/var/log/genesis/errors.log" + level: ERROR + timestamp: true + show_stack: fatal +``` + +## Complete Example Configuration + +```yaml +# ~/.genesis/config + +# BOSH targeting +default_bosh_target: ask + +# Repository management +legacy_repo_suffix: false +deployment_roots: + - /home/genesis/deployments + - production: /opt/genesis/prod + - staging: /opt/genesis/staging + - development: /tmp/genesis-dev + +# Display preferences +output_style: fun +show_duration: true + +# Deployment behavior +fix_on_deploy: ask +confirm_release_overrides: outdated + +# Cache and storage +spec_cache_dir: "/var/cache/genesis/specs" +bosh_logs_path: "/var/log/genesis/bosh_logs" + +# Warning suppression +suppress_warnings: + oversized_secrets: false + bosh_target: true + +# Genesis behavior +embedded_genesis: warn +automatic_config_upgrade: yes + +# Logging configuration +logs: + # Main log + - file: "/var/log/genesis/genesis.log" + level: INFO + timestamp: true + style: plain + + # Debug log + - file: "/tmp/genesis-debug.log" + level: DEBUG + style: rfc-5424 + timestamp: true + show_stack: full + + # Error log + - file: "/var/log/genesis/errors.log" + level: ERROR + timestamp: true + show_stack: fatal +``` + +## Environment Variable Overrides + +Most configuration options can be overridden using environment variables. When set, environment variables take precedence over configuration file settings. + +### Override Examples + +```bash +# Override BOSH target behavior +export GENESIS_DEFAULT_BOSH_TARGET=self + +# Override deployment roots +export GENESIS_DEPLOYMENT_ROOTS="/alt/path;prod=/alt/prod" + +# Override display settings +export GENESIS_SHOW_DURATION=true + +# Override fix behavior +export GENESIS_FIX_ON_DEPLOY=always +``` + +### Available Environment Variables + +- `GENESIS_DEFAULT_BOSH_TARGET` +- `GENESIS_LEGACY_REPO_SUFFIX` +- `GENESIS_DEPLOYMENT_ROOTS` +- `GENESIS_SHOW_DURATION` +- `GENESIS_CONFIG_AUTOMATIC_UPGRADE` +- `GENESIS_FIX_ON_DEPLOY` +- `GENESIS_CONFIRM_RELEASE_OVERRIDES` +- `GENESIS_SPEC_CACHE_DIR` +- `GENESIS_DEPLOYMENT_LOGS_PATH` +- `GENESIS_SUPRESS_OVERSIZED_SECRETS_WARNING` +- `GENESIS_SUPPRESS_BOSH_TARGET_WARNING` + +## Configuration Validation + +Genesis validates configuration on startup. Invalid configurations result in: +- Clear error messages +- Suggested corrections +- Refusal to run until fixed + +### Common Validation Errors + +1. **Invalid enum values**: + ```yaml + # ERROR: 'maybe' is not valid + fix_on_deploy: maybe + # Valid: always, ask, never + ``` + +2. **Type mismatches**: + ```yaml + # ERROR: boolean expected + show_duration: "yes" + # Valid: true or false + ``` + +3. **Invalid paths**: + ```yaml + # ERROR: must be array + deployment_roots: "/single/path" + # Valid: array format + deployment_roots: + - /single/path + ``` + +## Advanced Usage + +### Multiple Log Destinations + +Configure comprehensive logging: + +```yaml +logs: + # Audit trail - everything + - file: "/var/log/genesis/audit.log" + level: INFO + style: rfc-5424 + timestamp: true + + # Development debugging + - file: "/tmp/genesis-trace.log" + level: TRACE + style: plain + show_stack: full + + # Error monitoring + - file: "/var/log/genesis/errors.log" + level: ERROR + style: plain + timestamp: true + show_stack: fatal + + # Operations log + - file: "/var/log/genesis/ops.log" + level: OUTPUT + timestamp: true +``` + +### Environment-Specific Configuration + +Use deployment roots with labels: + +```yaml +deployment_roots: + - local: ~/genesis/local + - dev: /mnt/nfs/genesis/dev + - staging: /mnt/nfs/genesis/staging + - prod: /secure/genesis/prod +``` + +Then reference by label: +```bash +genesis @prod list +genesis @staging deploy my-env +``` + +### CI/CD Configuration + +Optimize for automation: + +```yaml +# Minimal output for CI +output_style: plain +show_duration: false + +# No confirmations +fix_on_deploy: always +confirm_release_overrides: never +automatic_config_upgrade: silent + +# Suppress warnings +suppress_warnings: + oversized_secrets: true + bosh_target: true + +# Log everything +logs: + - file: "/var/log/ci/genesis.log" + level: DEBUG + timestamp: true + style: plain +``` + +## Migration Guide + +### From Environment Variables + +To migrate from environment variables to configuration file: + +1. **Identify current variables**: + ```bash + env | grep GENESIS_ + ``` + +2. **Create configuration**: + ```yaml + # Map variables to config options + default_bosh_target: parent # from GENESIS_DEFAULT_BOSH_TARGET + show_duration: true # from GENESIS_SHOW_DURATION + ``` + +3. **Test configuration**: + ```bash + # Unset variables + unset GENESIS_DEFAULT_BOSH_TARGET + # Test with config file + genesis list + ``` + +### Upgrading Configuration + +When Genesis detects outdated configuration: + +1. **Backup current config**: + ```bash + cp ~/.genesis/config ~/.genesis/config.backup + ``` + +2. **Enable automatic upgrade**: + ```yaml + automatic_config_upgrade: yes + ``` + +3. **Run Genesis command**: + ```bash + genesis version # Triggers upgrade check + ``` + +## Best Practices + +1. **Version Control**: Keep configuration in version control for team consistency +2. **Comments**: Document configuration choices +3. **Environment Variables**: Use for temporary overrides only +4. **Logging**: Configure appropriate log levels for your needs +5. **Validation**: Test configuration changes before deploying +6. **Backups**: Keep backups before major changes + +## Troubleshooting + +### Configuration Not Loading + +```bash +# Check file location +ls -la ~/.genesis/config + +# Validate YAML syntax +yamllint ~/.genesis/config + +# Test with trace logging +GENESIS_TRACE=1 genesis version +``` + +### Override Not Working + +```bash +# Check environment variable +echo $GENESIS_DEFAULT_BOSH_TARGET + +# Verify precedence (env vars override config) +unset GENESIS_DEFAULT_BOSH_TARGET +genesis version # Now uses config value +``` + +### Permission Issues + +```bash +# Fix permissions +chmod 600 ~/.genesis/config +chmod 700 ~/.genesis + +# Check ownership +chown $(whoami) ~/.genesis/config +``` \ No newline at end of file diff --git a/docs/topics/90-reference-guides/hook-reference.md b/docs/topics/90-reference-guides/hook-reference.md new file mode 100644 index 00000000..805f5b4b --- /dev/null +++ b/docs/topics/90-reference-guides/hook-reference.md @@ -0,0 +1,667 @@ +# Hook Reference + +This document provides a complete reference for all Genesis hooks, their parameters, environment variables, and usage patterns. + +## Hook Types + +Genesis supports two types of hooks: + +1. **Bash Scripts** - Traditional shell scripts in the `hooks/` directory +2. **Perl Modules** - Advanced hooks using Genesis::Hook modules + +## Hook Execution Order + +During a typical deployment, hooks execute in this order: + +1. `new` - When creating a new environment +2. `blueprint` - To determine manifest files +3. `secrets` - To check/add/rotate secrets +4. `check` - Pre-deployment validation +5. `pre-deploy` - Just before deployment +6. `deploy` - (Internal - not a hook) +7. `post-deploy` - After deployment +8. `info` - Display deployment information + +## Core Hooks + +### new + +**Purpose**: Interactive environment setup when running `genesis new` + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_ROOT # Repository root directory +GENESIS_ENVIRONMENT # Environment name +GENESIS_SECRETS_PATH # Vault secrets path +GENESIS_VAULT_PREFIX # Legacy: Vault prefix +GENESIS_KIT_NAME # Kit name +GENESIS_KIT_VERSION # Kit version +GENESIS_MIN_VERSION # Minimum Genesis version +``` + +**Helper Functions**: +- `prompt_for` - Interactive prompting +- `genesis_config_block` - Generate Genesis config +- `offer_environment_editor` - Offer to edit file + +**Example**: +```bash +#!/bin/bash +set -eu + +prompt_for base_domain line \ + "What is your base domain?" \ + --default "example.com" \ + --validation dns + +cat > "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" <&2 "Error: Unknown feature '$feature'" + exit 1 + ;; + esac +done +``` + +**Example (Perl)**: +```perl +package Genesis::Hook::Blueprint::MyKit; +use parent qw(Genesis::Hook::Blueprint); + +sub perform { + my ($self) = @_; + + $self->add_files("base.yml"); + $self->add_files("features/ha.yml") if $self->want_feature('ha'); + + return $self->done(1); +} +1; +``` + +### secrets + +**Purpose**: Manage secrets beyond kit.yml definitions + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_SECRET_ACTION # add, check, rotate +GENESIS_ENVIRONMENT +GENESIS_SECRETS_PATH +GENESIS_KIT_NAME +``` + +**Example**: +```bash +#!/bin/bash +set -eu + +case "${GENESIS_SECRET_ACTION}" in + add) + # Generate additional secrets + if want_feature "custom-ca"; then + safe x509 issue "$GENESIS_SECRETS_PATH/custom-ca" \ + --signed-by "$GENESIS_SECRETS_PATH/ca" \ + --ttl 365d \ + --subject "/CN=Custom CA" + fi + ;; + + check) + # Validate secrets exist + if want_feature "provided-cert"; then + safe exists "$GENESIS_SECRETS_PATH/ssl/cert" || \ + echo >&2 "Missing provided certificate" + fi + ;; + + rotate) + # Rotate specific secrets + safe regen "$GENESIS_SECRETS_PATH/api-key" + ;; +esac +``` + +### check + +**Purpose**: Pre-deployment validation + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_ENVIRONMENT +GENESIS_CLOUD_CONFIG # Cloud config YAML +GENESIS_KIT_NAME +GENESIS_REQUESTED_FEATURES +``` + +**Helper Functions**: +- `cloud_config_has` - Check cloud config resources +- `lookup` - Get parameter values +- `want_feature` - Check if feature enabled + +**Example**: +```bash +#!/bin/bash +set -eu + +# Check VM types +vm_type=$(lookup params.vm_type default) +if ! cloud_config_has vm_type "$vm_type"; then + echo >&2 "Error: VM type '$vm_type' not found in cloud config" + exit 1 +fi + +# Check networks +network=$(lookup params.network default) +if ! cloud_config_has network "$network"; then + echo >&2 "Error: Network '$network' not found" + exit 1 +fi + +# Feature-specific checks +if want_feature "ha"; then + instances=$(lookup params.instances 1) + if [[ $instances -lt 3 ]]; then + echo >&2 "Error: HA requires at least 3 instances" + exit 1 + fi +fi +``` + +### pre-deploy + +**Purpose**: Final actions before deployment + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_PREDEPLOY_DATAFILE # File to store data +GENESIS_MANIFEST_FILE # Full manifest path +GENESIS_DEPLOY_OPTIONS # JSON deployment options +GENESIS_ENVIRONMENT +``` + +**Example**: +```bash +#!/bin/bash +set -eu + +# Store current state +echo "timestamp: $(date -u +%s)" > "$GENESIS_PREDEPLOY_DATAFILE" +echo "version: $(get_deployed_version)" >> "$GENESIS_PREDEPLOY_DATAFILE" + +# Validate major version upgrade +if is_major_upgrade; then + if [[ "${GENESIS_CONFIRM:-}" != "yes" ]]; then + describe "" \ + "WARNING: Major version upgrade detected!" \ + "This may require manual intervention." + + prompt_for confirm boolean \ + "Continue with deployment?" + + [[ "$confirm" == "true" ]] || exit 1 + fi +fi + +# Run pre-deployment tasks +if deployment_exists; then + bosh -d "$BOSH_DEPLOYMENT" run-errand pre-upgrade || true +fi +``` + +### post-deploy + +**Purpose**: Actions after deployment completes + +**Type**: Bash script or Perl module + +**Environment Variables**: +```bash +GENESIS_DEPLOY_RC # Deployment return code +GENESIS_PREDEPLOY_DATAFILE # Pre-deploy data +GENESIS_ENVIRONMENT +GENESIS_CALL_BIN # Genesis binary path +``` + +**Example (Bash)**: +```bash +#!/bin/bash +set -eu + +if [[ "$GENESIS_DEPLOY_RC" != "0" ]]; then + echo "Deployment failed - skipping post-deploy actions" + exit 0 +fi + +# Run smoke tests +describe "Running smoke tests..." +bosh -d "$BOSH_DEPLOYMENT" run-errand smoke-tests + +# Update DNS +if want_feature "external-dns"; then + update_external_dns "$(lookup params.external_url)" +fi + +# Display success +describe "" "Deployment successful!" +``` + +**Example (Perl)**: +```perl +package Genesis::Hook::PostDeploy::MyKit; +use parent qw(Genesis::Hook::PostDeploy); + +sub perform { + my ($self) = @_; + + return 0 unless $self->deploy_successful; + + $self->run_errand('smoke-tests'); + $self->upload_runtime_configs if $self->config('runtime'); + + return $self->done(1); +} +1; +``` + +### info + +**Purpose**: Display deployment information + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_ENVIRONMENT +GENESIS_SECRETS_PATH +BOSH_DEPLOYMENT # BOSH deployment name +``` + +**Example**: +```bash +#!/bin/bash +set -eu + +base_url="https://$(lookup params.base_domain)" +username="admin" +password="$(safe get $GENESIS_SECRETS_PATH/admin:password)" + +describe "" \ + "Deployment Information" \ + "" \ + " URL: $base_url" \ + " Username: $username" \ + " Password: $password" \ + "" \ + "To access the dashboard:" \ + " genesis do $GENESIS_ENVIRONMENT login" +``` + +### addon + +**Purpose**: Provide additional commands via `genesis do` + +**Type**: Bash script or Perl module + +**Environment Variables**: +```bash +GENESIS_ADDON_SCRIPT # Addon being executed +GENESIS_ADDON_ARGS # Arguments array +GENESIS_ENVIRONMENT +GENESIS_SECRETS_PATH +``` + +**Example (Bash)**: +```bash +#!/bin/bash +set -eu + +case "$GENESIS_ADDON_SCRIPT" in + list) + echo "Available addons:" + echo " login - Log into the system" + echo " backup - Perform backup" + echo " restore - Restore from backup" + ;; + + login) + url="https://$(lookup params.base_domain)" + password="$(safe get $GENESIS_SECRETS_PATH/admin:password)" + + echo "Logging into $url..." + open "$url" || xdg-open "$url" + echo "Password: $password" + ;; + + backup) + bosh -d "$BOSH_DEPLOYMENT" run-errand backup + ;; + + restore) + backup_file="${1:?Usage: genesis do $GENESIS_ENVIRONMENT restore }" + bosh -d "$BOSH_DEPLOYMENT" run-errand restore -v "backup_file=$backup_file" + ;; + + *) + echo >&2 "Error: Unknown addon '$GENESIS_ADDON_SCRIPT'" + exit 1 + ;; +esac +``` + +**Example (Perl)**: +```perl +package Genesis::Hook::Addon::MyKit::backup; +use parent qw(Genesis::Hook::Addon); + +sub init { + my $class = shift; + my $obj = $class->SUPER::init(@_); + $obj->parse_options(['full', 'incremental']); + return $obj; +} + +sub perform { + my ($self) = @_; + + my $type = $self->has_option('incremental') ? 'incremental' : 'full'; + my $result = $self->bosh->run_errand("backup-$type"); + + return $self->done($result); +} + +sub cmd_details { + return "Perform system backup (--full or --incremental)"; +} +1; +``` + +## Helper Functions Reference + +### Prompting Functions + +```bash +# Basic prompt +prompt_for varname "Question?" + +# With default +prompt_for varname line "Question?" --default "value" + +# With validation +prompt_for varname line "Question?" \ + --validation ip \ + --validation port \ + --validation dns \ + --validation url \ + --validation email \ + --validation "/^[A-Z]+$/" + +# Boolean prompt +prompt_for confirm boolean "Continue?" --default y + +# Selection menu +prompt_for choice select "Choose:" \ + -o "[option1] First Option" \ + -o "[option2] Second Option" + +# Multi-line input +prompt_for content block "Enter content (Ctrl-D to finish):" + +# Secret prompts +prompt_for "$GENESIS_SECRETS_PATH/password" secret-line \ + "Enter password:" + +prompt_for "$GENESIS_SECRETS_PATH/cert" secret-block \ + "Paste certificate:" +``` + +### Lookup Functions + +```bash +# Get parameter value with default +value=$(lookup params.key default_value) + +# Check if parameter exists +if param_exists params.key; then + echo "Parameter is set" +fi + +# Get deployment name +deployment=$(lookup genesis.bosh_deployment) +``` + +### Feature Functions + +```bash +# Check single feature +if want_feature "monitoring"; then + echo "Monitoring enabled" +fi + +# Check multiple features +if features_enabled "ha" "ssl"; then + echo "Both HA and SSL enabled" +fi + +# Get feature list +for feature in $GENESIS_REQUESTED_FEATURES; do + echo "Feature: $feature" +done +``` + +### Cloud Config Functions + +```bash +# Check VM type exists +if cloud_config_has vm_type "large"; then + echo "Large VM type available" +fi + +# Check network +if cloud_config_has network "default"; then + echo "Default network exists" +fi + +# Check disk type +if cloud_config_has disk_type "ssd"; then + echo "SSD disk type available" +fi + +# Get cloud config value +value=$(cloud_config_get networks.0.name) +``` + +### Output Functions + +```bash +# Formatted output +describe "Setting up deployment" +describe "" "Line 1" "Line 2" "Line 3" + +# Colored output +echo "$(green "Success"): Operation completed" +echo "$(yellow "Warning"): Check configuration" +echo "$(red "Error"): Operation failed" + +# Stylized output +header "Deployment Configuration" +bullet "First item" +bullet "Second item" +``` + +## Environment Variables Reference + +### Always Available + +| Variable | Description | +|----------|-------------| +| `GENESIS_ROOT` | Repository root directory | +| `GENESIS_ENVIRONMENT` | Environment name | +| `GENESIS_KIT_NAME` | Kit name | +| `GENESIS_KIT_VERSION` | Kit version | +| `GENESIS_SECRETS_PATH` | Vault secrets base path | +| `GENESIS_VAULT_PREFIX` | Legacy Vault prefix | + +### Hook-Specific + +| Hook | Variables | +|------|-----------| +| `new` | `GENESIS_MIN_VERSION` | +| `blueprint` | `GENESIS_REQUESTED_FEATURES` | +| `secrets` | `GENESIS_SECRET_ACTION` | +| `check` | `GENESIS_CLOUD_CONFIG` | +| `pre-deploy` | `GENESIS_PREDEPLOY_DATAFILE`, `GENESIS_MANIFEST_FILE`, `GENESIS_DEPLOY_OPTIONS` | +| `post-deploy` | `GENESIS_DEPLOY_RC`, `GENESIS_PREDEPLOY_DATAFILE` | +| `addon` | `GENESIS_ADDON_SCRIPT`, `GENESIS_ADDON_ARGS` | + +### BOSH Variables + +When in BOSH context: + +| Variable | Description | +|----------|-------------| +| `BOSH_ENVIRONMENT` | BOSH director URL | +| `BOSH_CLIENT` | BOSH authentication client | +| `BOSH_CLIENT_SECRET` | BOSH authentication secret | +| `BOSH_CA_CERT` | BOSH CA certificate | +| `BOSH_DEPLOYMENT` | Deployment name | + +## Best Practices + +### 1. Error Handling + +Always use proper error handling: + +```bash +#!/bin/bash +set -eu # Exit on error, undefined variables + +# Explicit error checking +if ! command_that_might_fail; then + echo >&2 "Error: Command failed" + exit 1 +fi +``` + +### 2. Idempotency + +Make hooks idempotent: + +```bash +# Check before creating +if ! safe exists "$GENESIS_SECRETS_PATH/generated"; then + safe gen "$GENESIS_SECRETS_PATH/generated" password +fi + +# Check before running errands +if ! errand_has_run "configure-database"; then + bosh -d "$BOSH_DEPLOYMENT" run-errand configure-database +fi +``` + +### 3. User Communication + +Provide clear feedback: + +```bash +describe "Validating deployment configuration..." + +# Detailed progress +describe "✓ Cloud config validated" +describe "✓ Secrets present" +describe "✓ Network connectivity confirmed" + +# Errors with context +if [[ $error ]]; then + describe "" \ + "$(red "ERROR"): Deployment validation failed" \ + "" \ + " Missing VM type: $vm_type" \ + " Please update your cloud config" \ + "" \ + "Run: bosh update-cloud-config" +fi +``` + +### 4. Feature Validation + +Validate feature combinations: + +```bash +# Check incompatible features +if want_feature "standalone" && want_feature "ha"; then + echo >&2 "Error: Cannot use both 'standalone' and 'ha' features" + exit 1 +fi + +# Check required parameters for features +if want_feature "ssl"; then + if ! param_exists params.certificate; then + echo >&2 "Error: SSL feature requires params.certificate" + exit 1 + fi +fi +``` + +### 5. Documentation + +Document complex logic: + +```bash +# This check ensures that HA deployments have sufficient +# instances across multiple AZs for proper redundancy +if want_feature "ha"; then + # Minimum 3 instances for quorum + # Should be odd number to prevent split-brain + # Distributed across AZs for fault tolerance +fi +``` + +Hooks provide the extensibility that makes Genesis kits powerful and flexible. Understanding their capabilities enables creating sophisticated deployment automation. \ No newline at end of file diff --git a/docs/topics/90-reference-guides/index.md b/docs/topics/90-reference-guides/index.md new file mode 100644 index 00000000..cc1a551d --- /dev/null +++ b/docs/topics/90-reference-guides/index.md @@ -0,0 +1,29 @@ +# Reference Guides + +This section contains comprehensive reference documentation for Genesis configuration, environment variables, and advanced features. + +## Topics in this Section + +### [Environment Variables](environment-variables.md) +Complete reference for all Genesis environment variables and their usage. + +### [Genesis Configuration](genesis-configuration.md) +Detailed guide to configuring Genesis using the `~/.genesis/config` file. + +### [Runtime Configs](runtime-configs.md) +How to specify and manage BOSH runtime configurations in Genesis. + +### [Kit Configuration Reference](kit-configuration.md) +Reference for kit.yml configuration options and structure. + +### [Hook Reference](hook-reference.md) +Complete reference for all Genesis hooks and their parameters. + +### [Manifest Operators](manifest-operators.md) +Reference for Spruce operators used in Genesis manifests. + +## Quick Links + +- [Environment Setup](../10-environments/setting-up.md) +- [Kit Development](../50-kits/authoring-kits.md) +- [Troubleshooting](../70-troubleshooting/index.md) \ No newline at end of file diff --git a/docs/topics/90-reference-guides/kit-configuration.md b/docs/topics/90-reference-guides/kit-configuration.md new file mode 100644 index 00000000..e4546427 --- /dev/null +++ b/docs/topics/90-reference-guides/kit-configuration.md @@ -0,0 +1,619 @@ +# Kit Configuration Reference + +This document provides a complete reference for the `kit.yml` configuration file used in Genesis kits. + +## Overview + +The `kit.yml` file defines kit metadata, dependencies, secrets, and configuration options. It serves as the primary configuration point for Genesis kits. + +## File Structure + +```yaml +# Basic kit information +name: my-kit +authors: + - Your Name +docs: https://github.com/genesis-community/my-kit +code: https://github.com/genesis-community/my-kit + +# Version constraints +genesis_version_min: 2.8.0 + +# Dependencies +releases: + - name: my-release + version: 1.2.3 + url: https://bosh.io/d/github.com/org/release + sha1: abc123... + +stemcells: + - os: ubuntu-jammy + version: latest + +# Features +features: + - name: ha + description: Enable high availability mode + - name: ssl + description: Enable SSL/TLS encryption + +# Secrets and certificates +credentials: + - name: admin_password + description: Administrative user password + +certificates: + - name: server + description: Server certificate for TLS +``` + +## Configuration Sections + +### Basic Information + +#### name +**Required**: Yes +**Type**: String +**Description**: The name of the kit. Must match the directory name for compiled kits. + +```yaml +name: concourse +``` + +#### authors +**Required**: No +**Type**: Array of strings +**Description**: List of kit authors with optional email addresses. + +```yaml +authors: + - Jane Doe + - John Smith +``` + +#### docs +**Required**: No +**Type**: String (URL) +**Description**: URL to kit documentation. + +```yaml +docs: https://github.com/genesis-community/concourse-genesis-kit +``` + +#### code +**Required**: No +**Type**: String (URL) +**Description**: URL to kit source code repository. + +```yaml +code: https://github.com/genesis-community/concourse-genesis-kit +``` + +#### description +**Required**: No +**Type**: String +**Description**: Brief description of the kit's purpose. + +```yaml +description: | + Deploys Concourse CI/CD platform with Genesis +``` + +### Version Constraints + +#### genesis_version_min +**Required**: No +**Type**: String (Semantic Version) +**Description**: Minimum Genesis version required for this kit. + +```yaml +genesis_version_min: 2.8.0 +``` + +#### genesis_version_max +**Required**: No +**Type**: String (Semantic Version) +**Description**: Maximum Genesis version supported by this kit. + +```yaml +genesis_version_max: 2.9.99 +``` + +### Dependencies + +#### releases +**Required**: No +**Type**: Array of release specifications +**Description**: BOSH releases required by the kit. + +**Release Specification**: +```yaml +releases: + - name: concourse # Required: Release name + version: 7.8.3 # Required: Version (can use patterns) + url: https://... # Optional: Download URL + sha1: abc123... # Optional: SHA1 checksum + github: owner/repo # Optional: GitHub repository + + # Version patterns + - name: postgres + version: "43" # Exact version + + - name: bpm + version: 1.1.+ # Any 1.1.x version + + - name: routing + version: ">=0.200.0" # Version 0.200.0 or higher +``` + +#### stemcells +**Required**: No +**Type**: Array of stemcell specifications +**Description**: Stemcells required by the kit. + +```yaml +stemcells: + - os: ubuntu-jammy # Required: OS type + version: latest # Required: Version or "latest" + + - os: ubuntu-bionic + version: 621.+ # Minimum version pattern + + # Multiple stemcells for different instance groups + - alias: default + os: ubuntu-jammy + version: latest + + - alias: windows + os: windows2019 + version: latest +``` + +### Features + +#### features +**Required**: No +**Type**: Array of feature definitions +**Description**: Optional features that can be enabled. + +```yaml +features: + - name: ha + description: | + Enable high availability mode with 3 instances + deprecated: false # Optional: Mark as deprecated + + - name: monitoring + description: Enable Prometheus exporters + + - name: shield-agent + deprecated: true + description: | + DEPRECATED: Use Shield runtime config instead +``` + +### Secrets Configuration + +#### credentials +**Required**: No +**Type**: Array of credential definitions +**Description**: Password and random secret definitions. + +```yaml +credentials: + # Basic password + - name: admin_password + description: Administrator password + + # With constraints + - name: api_key + description: API authentication key + length: 32 + fixed: true # Don't rotate + + # With character set + - name: db_password + description: Database password + length: 20 + allowed_chars: "a-zA-Z0-9" +``` + +#### certificates +**Required**: No +**Type**: Array of certificate definitions +**Description**: X.509 certificate definitions. + +```yaml +certificates: + # Basic certificate + - name: server + description: Server TLS certificate + + # With components + - name: ca + description: Certificate Authority + self_signed: true + + - name: server + description: Server certificate + signed_by: ca + common_name: "*.example.com" + alternative_names: + - "*.example.com" + - "10.0.0.5" + - "localhost" + + # With custom validity + - name: client + description: Client certificate + ttl: 90d # 90 days + signed_by: ca + + # With specific usage + - name: etcd-peer + description: etcd peer certificate + key_usage: + - digital_signature + - key_encipherment + extended_key_usage: + - server_auth + - client_auth +``` + +#### provided +**Required**: No +**Type**: Array of provided secret definitions +**Description**: Secrets that users must provide. + +```yaml +provided: + - name: ssl_cert + description: | + SSL certificate for external access. + Must include full certificate chain. + example: | + -----BEGIN CERTIFICATE----- + MIIDXTCCAkWgAwIBAgIJAKl... + -----END CERTIFICATE----- + + - name: slack_webhook + description: Slack webhook URL for notifications + example: https://hooks.slack.com/services/XXX/YYY/ZZZ +``` + +### Parameters + +#### params +**Required**: No +**Type**: Hash +**Description**: Default parameter values. + +```yaml +params: + # Simple defaults + instances: 1 + vm_type: default + + # Complex defaults + networks: + - name: default + static_ips: [] +``` + +### Subkits (Deprecated) + +The `subkits` section is deprecated in favor of `features`: + +```yaml +# Old format (deprecated) +subkits: + - name: ha + description: High availability + +# New format +features: + - name: ha + description: High availability +``` + +## Advanced Configuration + +### Conditional Features + +Features can have dependencies and conflicts: + +```yaml +features: + - name: ha + description: High availability (requires 3+ instances) + + - name: single-node + description: Single node deployment + conflicts: [ha] # Cannot use with HA + + - name: ssl + description: Enable SSL/TLS + + - name: mtls + description: Mutual TLS authentication + requires: [ssl] # Requires SSL feature +``` + +### Complex Secrets + +Advanced secret configurations: + +```yaml +credentials: + # User-provided with validation + - name: admin_password + description: Admin password + min_length: 12 + require_special: true + require_numeric: true + + # Generated with specific format + - name: session_key + description: Session encryption key + format: base64 + length: 32 + +certificates: + # CA with specific DN + - name: ca + description: Root CA + self_signed: true + ttl: 10y + subject: + C: US + ST: California + L: San Francisco + O: Example Corp + OU: IT Department + CN: Example Root CA + + # Server with IP SANs + - name: server + description: Server certificate + signed_by: ca + common_name: server.example.com + ip_sans: + - 10.0.0.5 + - 10.0.0.6 + dns_sans: + - server.example.com + - api.example.com +``` + +### Release Versions + +Complex version specifications: + +```yaml +releases: + # Latest from GitHub + - name: concourse + github: concourse/concourse-bosh-release + version: latest + + # Specific version with fallback + - name: postgres + version: "43" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=43 + sha1: abc123 + fallback: + version: "42" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=42 + sha1: def456 + + # Version range + - name: routing + version: ">=0.200.0 <1.0.0" +``` + +### Environment Types + +Kits can define environment types: + +```yaml +environment_types: + - name: development + features: + - single-node + params: + instances: 1 + + - name: production + features: + - ha + - ssl + - monitoring + params: + instances: 3 +``` + +### Deployment Parameters + +Control deployment behavior: + +```yaml +deployment: + # Canary settings + canaries: 1 + max_in_flight: 10 + canary_watch_time: 30000-600000 + update_watch_time: 30000-600000 + + # Serial deployment + serial: false + + # AZ configuration + availability_zones: + - z1 + - z2 + - z3 +``` + +## Validation Schema + +Genesis validates kit.yml against this schema: + +```yaml +type: map +mapping: + name: + type: str + required: true + authors: + type: seq + sequence: + - type: str + genesis_version_min: + type: str + pattern: /^\d+\.\d+\.\d+$/ + releases: + type: seq + sequence: + - type: map + mapping: + name: {type: str, required: true} + version: {type: str, required: true} + url: {type: str} + sha1: {type: str} + # ... etc +``` + +## Complete Example + +Comprehensive kit.yml example: + +```yaml +name: concourse +authors: + - Genesis Community + - Concourse Team +docs: https://concourse-ci.org +code: https://github.com/genesis-community/concourse-genesis-kit +description: | + Deploy Concourse CI/CD platform using Genesis + + Supports standalone and clustered deployments + with optional GitHub authentication. + +genesis_version_min: 2.8.0 + +releases: + - name: concourse + version: 7.8.3 + url: https://bosh.io/d/github.com/concourse/concourse-bosh-release?v=7.8.3 + sha1: abc123def456 + + - name: postgres + version: "43" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=43 + sha1: 789ghi012jkl + + - name: bpm + version: 1.1.+ + + - name: routing + version: latest + +stemcells: + - alias: default + os: ubuntu-jammy + version: latest + +features: + - name: workers + description: | + Deploy external workers for job processing + + - name: github-oauth + description: | + Enable GitHub OAuth for authentication + + - name: prometheus + description: | + Export Prometheus metrics + + - name: vault + description: | + Use Vault for credential management + deprecated: true + +params: + # Instance configuration + instances: 1 + vm_type: default + network: concourse + disk_type: default + + # Concourse configuration + external_url: https://concourse.example.com + worker_count: 3 + +credentials: + - name: local_user_password + description: Password for local admin user + + - name: postgresql_password + description: PostgreSQL database password + length: 32 + + - name: token_signing_key + description: Key for signing auth tokens + format: rsa + bits: 4096 + +certificates: + - name: ca + description: Concourse CA certificate + self_signed: true + ttl: 10y + + - name: tls + description: Concourse web TLS certificate + signed_by: ca + ttl: 1y + common_name: concourse.example.com + alternative_names: + - "*.concourse.example.com" + - "127.0.0.1" + + - name: worker + description: Worker certificate + signed_by: ca + ttl: 90d + common_name: worker.concourse.internal + +provided: + - name: github_oauth_client_id + description: | + GitHub OAuth application client ID + Create at: https://github.com/settings/applications/new + example: "0123456789abcdef0123" + + - name: github_oauth_client_secret + description: | + GitHub OAuth application client secret + example: "0123456789abcdef0123456789abcdef01234567" + +deployment: + canaries: 1 + max_in_flight: 4 + canary_watch_time: 30000-600000 + update_watch_time: 30000-600000 + serial: false +``` + +## Best Practices + +1. **Version Constraints**: Always specify minimum Genesis version +2. **Descriptions**: Provide clear descriptions for all features and secrets +3. **Examples**: Include examples for provided secrets +4. **Deprecation**: Mark deprecated features clearly +5. **Documentation**: Link to comprehensive documentation +6. **Validation**: Test kit.yml with `genesis compile-kit` + +The kit.yml file is the heart of a Genesis kit, defining its capabilities, requirements, and configuration options. \ No newline at end of file diff --git a/docs/topics/90-reference-guides/manifest-operators.md b/docs/topics/90-reference-guides/manifest-operators.md new file mode 100644 index 00000000..93eaf615 --- /dev/null +++ b/docs/topics/90-reference-guides/manifest-operators.md @@ -0,0 +1,628 @@ +# Manifest Operators Reference + +This document provides a comprehensive reference for Spruce operators used in Genesis manifests. Spruce is the YAML merging tool that powers Genesis's hierarchical configuration system. + +## Overview + +Spruce operators are special directives enclosed in `(( ))` that perform operations during manifest generation. They enable dynamic values, references, conditionals, and complex data transformations. + +## Basic Operators + +### grab + +Retrieves values from elsewhere in the document. + +**Syntax**: `(( grab path.to.value ))` + +**Example**: +```yaml +meta: + domain: example.com + +params: + url: (( grab meta.domain )) + # Result: url: example.com +``` + +**With defaults**: +```yaml +params: + # Use default if not found + port: (( grab meta.port || 8080 )) + + # Multiple fallbacks + env: (( grab meta.environment || params.env || "development" )) +``` + +### concat + +Concatenates strings or arrays. + +**Syntax**: `(( concat arg1 arg2 ... ))` + +**String concatenation**: +```yaml +meta: + domain: example.com + env: prod + +params: + # Result: "https://prod.example.com" + url: (( concat "https://" meta.env "." meta.domain )) + + # With separator + fqdn: (( join "." meta.env meta.domain )) +``` + +**Array concatenation**: +```yaml +base_features: + - dns + - ntp + +params: + features: (( concat base_features "[\"monitoring\"]" )) + # Result: [dns, ntp, monitoring] +``` + +### vault + +Retrieves secrets from Vault. + +**Syntax**: `(( vault "path:key" ))` + +**Examples**: +```yaml +params: + # Simple secret + password: (( vault "secret/prod/admin:password" )) + + # With path construction + api_key: (( vault meta.vault "/api:key" )) + + # Using environment variable + db_pass: (( vault $GENESIS_SECRETS_PATH "/database:password" )) +``` + +### static_ips + +Generates static IPs from network definitions. + +**Syntax**: `(( static_ips INTEGER ... ))` + +**Example**: +```yaml +networks: + - name: default + static: [10.0.0.5 - 10.0.0.100] + +instance_groups: + - name: web + instances: 3 + networks: + - name: default + static_ips: (( static_ips 0 1 2 )) + # Result: [10.0.0.5, 10.0.0.6, 10.0.0.7] +``` + +## Reference Operators + +### meta + +References to the `meta` section (common pattern in Genesis). + +```yaml +meta: + az: [z1, z2, z3] + network: default + +instance_groups: + - name: web + azs: (( grab meta.az )) + networks: + - name: (( grab meta.network )) +``` + +### params + +References to the `params` section (user parameters). + +```yaml +params: + base_domain: example.com + instances: 3 + +instance_groups: + - name: web + instances: (( grab params.instances )) + +properties: + domain: (( grab params.base_domain )) +``` + +### self-reference + +Reference current level using `.`: + +```yaml +server: + host: example.com + port: 443 + url: (( concat "https://" .host ":" .port )) + # Result: "https://example.com:443" +``` + +## Conditional Operators + +### Ternary operator + +Conditional selection based on boolean. + +**Syntax**: `(( condition ? true_value : false_value ))` + +**Examples**: +```yaml +meta: + production: true + +params: + # Simple conditional + instances: (( meta.production ? 3 : 1 )) + + # Nested conditionals + vm_type: (( grab meta.scale || "small" == "large" ? "n1-highmem-8" : "n1-standard-2" )) +``` + +### Logical operators + +Boolean operations for conditions. + +```yaml +meta: + ha_enabled: true + instances: 3 + +params: + # AND operator + use_ha: (( meta.ha_enabled && meta.instances >= 3 )) + + # OR operator + enable_monitoring: (( grab meta.monitoring || meta.production )) + + # NOT operator + skip_backups: (( !meta.production )) +``` + +## Array Operators + +### join + +Joins array elements into a string. + +**Syntax**: `(( join SEPARATOR ARRAY ))` + +```yaml +meta: + domains: + - api + - www + - admin + +params: + # Result: "api,www,admin" + domain_list: (( join "," meta.domains )) + + # Result: "api.example.com www.example.com admin.example.com" + fqdns: (( join " " meta.domains ".example.com" )) +``` + +### elem + +Extracts element from array by index. + +**Syntax**: `(( elem INDEX ARRAY ))` + +```yaml +meta: + azs: [us-east-1a, us-east-1b, us-east-1c] + +params: + # Result: "us-east-1b" + primary_az: (( elem 1 meta.azs )) +``` + +### append + +Appends to arrays (used with merge). + +```yaml +# base.yml +features: + - dns + - ntp + +# overlay.yml +features: + - (( append )) + - monitoring + - logging +# Result: [dns, ntp, monitoring, logging] +``` + +### replace + +Replaces entire structure. + +```yaml +# base.yml +databases: + - name: postgres + port: 5432 + +# overlay.yml +databases: (( replace )) + - name: mysql + port: 3306 +# Result: only mysql, postgres removed +``` + +### inline + +Merges array elements inline. + +```yaml +# base.yml +jobs: + - name: web + templates: [nginx] + +# overlay.yml +jobs: + - (( inline )) + - name: web + templates: + - (( append )) + - php-fpm +# Result: web job with [nginx, php-fpm] +``` + +## Map/Object Operators + +### keys + +Extracts keys from a map. + +**Syntax**: `(( keys MAP ))` + +```yaml +services: + web: + port: 80 + api: + port: 8080 + db: + port: 5432 + +service_names: (( keys services )) +# Result: [web, api, db] +``` + +### values + +Extracts values from a map. + +**Syntax**: `(( values MAP ))` + +```yaml +services: + web: 80 + api: 8080 + db: 5432 + +ports: (( values services )) +# Result: [80, 8080, 5432] +``` + +## String Operators + +### base64 + +Base64 encodes a string. + +**Syntax**: `(( base64 STRING ))` + +```yaml +params: + encoded_password: (( base64 "my-secret-password" )) + # Result: "bXktc2VjcmV0LXBhc3N3b3Jk" +``` + +### sha1/sha256 + +Generates hash of string. + +```yaml +params: + password_hash: (( sha256 "password" )) + file_checksum: (( sha1 meta.file_contents )) +``` + +### regexp + +Regular expression matching and replacement. + +**Syntax**: `(( regexp PATTERN REPLACEMENT STRING ))` + +```yaml +meta: + version: "v1.2.3" + +params: + # Remove 'v' prefix + clean_version: (( regexp "^v" "" meta.version )) + # Result: "1.2.3" + + # Extract major version + major: (( regexp "^v?([0-9]+)\\..*" "$1" meta.version )) + # Result: "1" +``` + +## Special Operators + +### inject + +Injects sub-documents. + +**Syntax**: `(( inject FILE ))` + +```yaml +# main.yml +base_config: (( inject "configs/base.yml" )) + +overrides: + <<: (( inject "configs/overrides.yml" )) +``` + +### file + +Reads file contents as string. + +**Syntax**: `(( file PATH ))` + +```yaml +params: + certificate: (( file "certs/server.crt" )) + config_data: (( file "/etc/app/config.json" )) +``` + +### env + +Accesses environment variables. + +**Syntax**: `(( env "VARIABLE" ))` + +```yaml +params: + home_dir: (( env "HOME" )) + deployment: (( env "GENESIS_ENVIRONMENT" )) + + # With default + log_level: (( env "LOG_LEVEL" || "info" )) +``` + +### null + +Represents null/nil value. + +```yaml +params: + # Remove inherited value + unwanted_param: (( null )) + + # Conditional null + optional: (( meta.enabled ? meta.value : null )) +``` + +## Advanced Patterns + +### Pipeline Operations + +Chain multiple operations: + +```yaml +meta: + raw_domains: + - " api.example.com " + - " www.example.com " + +params: + # Trim whitespace and join + domains: (( join "," ( map regexp "^\\s+|\\s+$" "" meta.raw_domains ) )) +``` + +### Complex Conditionals + +Multi-condition logic: + +```yaml +meta: + env: production + region: us-east + ha_enabled: true + +params: + instances: (( + meta.env == "production" && meta.ha_enabled ? 5 : + meta.env == "production" ? 3 : + meta.env == "staging" ? 2 : + 1 + )) +``` + +### Dynamic Key Names + +Generate keys dynamically: + +```yaml +meta: + env: prod + region: us-east-1 + +params: + (( concat meta.env "-config" )): + region: (( grab meta.region )) + # Result: prod-config: { region: us-east-1 } +``` + +### Nested Grabs + +Navigate complex structures: + +```yaml +meta: + environments: + prod: + us-east: + instances: 5 + us-west: + instances: 3 + +params: + count: (( grab meta.environments.prod.us-east.instances )) +``` + +## Error Handling + +### Default Values + +Always provide defaults for optional values: + +```yaml +params: + # Single default + port: (( grab meta.port || 8080 )) + + # Chain of defaults + environment: (( grab meta.env || params.env || "development" )) + + # Complex default + config: (( grab meta.config || { "timeout": 30, "retries": 3 } )) +``` + +### Type Safety + +Ensure correct types in operations: + +```yaml +# BAD: May cause type errors +total: (( grab meta.count + 1 )) + +# GOOD: Ensure numeric default +total: (( ( grab meta.count || 0 ) + 1 )) +``` + +### Existence Checks + +Check before using: + +```yaml +# Only add if exists +features: (( + has meta.optional_feature ? + concat base_features "[\"" meta.optional_feature "\"]" : + base_features +)) +``` + +## Best Practices + +### 1. Use Descriptive Paths + +```yaml +# BAD +value: (( grab m.d )) + +# GOOD +value: (( grab meta.deployment.domain )) +``` + +### 2. Provide Meaningful Defaults + +```yaml +# BAD +port: (( grab params.port || 0 )) + +# GOOD +port: (( grab params.port || 8080 )) # Default HTTP port +``` + +### 3. Group Related Operations + +```yaml +meta: + # Group related calculations + sizing: + base_instances: 3 + ha_multiplier: (( grab params.ha_enabled ? 3 : 1 )) + total_instances: (( meta.sizing.base_instances * meta.sizing.ha_multiplier )) +``` + +### 4. Document Complex Operations + +```yaml +params: + # Calculate required IPs: instances + 2 (for load balancers) + # Must account for multiple AZs in HA mode + required_ips: (( + ( grab params.instances || 1 ) + + 2 + + ( grab params.ha_enabled ? length(meta.azs) : 0 ) + )) +``` + +### 5. Avoid Deep Nesting + +```yaml +# BAD: Hard to read and maintain +value: (( grab meta.config.services.web.endpoints.primary.port || grab meta.defaults.services.web.port || 80 )) + +# GOOD: Use intermediate values +meta: + web_config: (( grab meta.config.services.web || {} )) + web_endpoint: (( grab meta.web_config.endpoints.primary || {} )) + +params: + web_port: (( grab meta.web_endpoint.port || 80 )) +``` + +## Common Pitfalls + +### 1. Circular References + +```yaml +# BAD: Causes infinite loop +a: (( grab b )) +b: (( grab a )) +``` + +### 2. Type Mismatches + +```yaml +# BAD: Concatenating different types +result: (( concat meta.string meta.number )) + +# GOOD: Convert to string first +result: (( concat meta.string ( string meta.number ) )) +``` + +### 3. Missing Defaults + +```yaml +# BAD: Fails if meta.value not present +calculation: (( grab meta.value * 2 )) + +# GOOD: Provide default +calculation: (( ( grab meta.value || 1 ) * 2 )) +``` + +Understanding Spruce operators is essential for creating flexible and maintainable Genesis deployments. These operators provide the power to create sophisticated configuration templates while maintaining clarity and reusability. \ No newline at end of file diff --git a/docs/topics/90-reference-guides/runtime-configs.md b/docs/topics/90-reference-guides/runtime-configs.md new file mode 100644 index 00000000..dababdcc --- /dev/null +++ b/docs/topics/90-reference-guides/runtime-configs.md @@ -0,0 +1,636 @@ +# Runtime Configs Reference + +This document provides a comprehensive reference for specifying and managing BOSH runtime configurations in Genesis environment files. + +## Overview + +Runtime configs are BOSH configurations that apply to all deployments on a BOSH director. Genesis kits can provide runtime config hooks that generate these configurations based on your environment settings, allowing you to standardize operational concerns across all deployments. + +## Configuration Location + +Runtime config options are specified under the `bosh-configs` top-level key in your environment file: + +```yaml +# my-env.yml +bosh-configs: + runtime: + # Runtime config specifications +``` + +## Specification Formats + +Genesis supports multiple formats for specifying runtime configs, from simple boolean flags to complex configurations with options. + +### 1. Boolean Format + +Enable all available runtime configs with default options: + +```yaml +bosh-configs: + runtime: true +``` + +This enables all runtime configs defined by the kit with their default settings. + +### 2. String Format (Single Config) + +Request a specific runtime config by name: + +```yaml +bosh-configs: + runtime: "dns" +``` + +Only the specified runtime config will be generated. + +### 3. Comma-Separated String (Multiple Configs) + +Request multiple runtime configs in a single string: + +```yaml +bosh-configs: + runtime: "dns,toolbelt,monitoring" +``` + +Each named config will be generated with default options. + +### 4. Array Format + +List multiple runtime configs using YAML array syntax: + +```yaml +bosh-configs: + runtime: + - dns + - toolbelt + - monitoring + - security +``` + +### 5. Hash Format (Configs with Options) + +Specify runtime configs with custom options: + +```yaml +bosh-configs: + runtime: + dns: + timeout: 30 + retries: 3 + cache_size: 1000 + security: + enforce_tls: true + audit_logging: enabled + monitoring: true # Use defaults + toolbelt: + packages: + - htop + - tmux + - vim +``` + +### 6. Mixed Configurations + +Combine different specification methods for flexibility: + +```yaml +bosh-configs: + runtime: + # Apply shared options to all configs + "*": + environment: production + region: us-east-1 + + # Config-specific options + dns: + timeout: 30 + upstream_dns: + - 8.8.8.8 + - 8.8.4.4 + + # Exclude specific config + legacy: false + + # Enable with defaults + monitoring: true +``` + +## Advanced Configuration + +### Wildcard Selection + +Use `*` to apply options to all available runtime configs: + +```yaml +bosh-configs: + runtime: + "*": + environment: production + datacenter: us-east-1 + contact: ops-team@example.com +``` + +### Excluding Configs + +Explicitly exclude specific runtime configs: + +```yaml +bosh-configs: + runtime: + "*": true # Enable all configs + legacy: false # Except legacy + experimental: false # And experimental +``` + +When only exclusions are specified, all other configs are enabled by default: + +```yaml +bosh-configs: + runtime: + # All configs enabled except these + legacy: false + deprecated: false +``` + +### Grouped Configuration + +Apply shared options to multiple configs: + +```yaml +bosh-configs: + runtime: + # Group configs with comma-separated names + "dns,security,monitoring": + environment: production + log_level: info + + # Additional config-specific options + dns: + cache_size: 2000 + security: + strict_mode: true +``` + +## Common Runtime Config Types + +### DNS Configuration + +Modern BOSH DNS setup: + +```yaml +bosh-configs: + runtime: + dns: + # DNS-specific options + cache: + enabled: true + max_entries: 10000 + health_check: + enabled: true + interval: 30 + handlers: + - domain: consul.local + forward: 10.0.0.10 +``` + +### Monitoring Configuration + +Prometheus node exporter and monitoring agents: + +```yaml +bosh-configs: + runtime: + monitoring: + node_exporter: + enabled: true + port: 9100 + collectors: + - cpu + - memory + - disk + - network + telegraf: + enabled: true + outputs: + - influxdb: "http://metrics.example.com:8086" +``` + +### Security Configuration + +OS hardening and security tools: + +```yaml +bosh-configs: + runtime: + security: + sysctl: + kernel_hardening: true + network_hardening: true + login_banner: + enabled: true + text: | + AUTHORIZED ACCESS ONLY + All activity is monitored + fail2ban: + enabled: true + max_retries: 3 +``` + +### Toolbelt Configuration + +Development and debugging tools: + +```yaml +bosh-configs: + runtime: + toolbelt: + packages: + - vim + - tmux + - htop + - tcpdump + - strace + custom_scripts: + enabled: true + path: /var/vcap/toolbelt/scripts +``` + +### Logging Configuration + +Centralized logging setup: + +```yaml +bosh-configs: + runtime: + logging: + syslog: + enabled: true + address: syslog.example.com + port: 514 + protocol: tcp + tls: + enabled: true + verify: true + format: rfc5424 + include_audit_logs: true +``` + +## Kit Integration + +### Kit-Defined Runtime Configs + +Kits define available runtime configs in their metadata: + +```yaml +# kit.yml +runtime_configs: + - name: dns + description: "BOSH DNS configuration" + default: true + - name: monitoring + description: "Prometheus monitoring agents" + default: false + - name: security + description: "OS hardening and security policies" + default: true +``` + +### Runtime Config Hooks + +Kits implement runtime config generation through hooks: + +```bash +# hooks/runtime-config +#!/bin/bash +set -eu + +config_type=$1 +shift + +case "$config_type" in + dns) + generate_dns_runtime_config "$@" + ;; + monitoring) + generate_monitoring_runtime_config "$@" + ;; + security) + generate_security_runtime_config "$@" + ;; + *) + echo >&2 "Unknown runtime config: $config_type" + exit 1 + ;; +esac +``` + +## Environment-Specific Overrides + +### Development Environment + +Minimal runtime configs for development: + +```yaml +# dev.yml +bosh-configs: + runtime: + dns: true # Only DNS + # All others disabled by default +``` + +### Production Environment + +Full runtime configs with strict settings: + +```yaml +# prod.yml +bosh-configs: + runtime: + "*": + environment: production + alert_email: ops@example.com + dns: + cache_size: 50000 + strict_mode: true + security: + enforce_tls: true + audit_all: true + compliance_mode: pci + monitoring: + retention: 90d + high_frequency: true + logging: + archive: true + compress: true +``` + +## Best Practices + +### 1. Hierarchical Configuration + +Use environment hierarchy for runtime configs: + +```yaml +# base.yml - Shared configs +bosh-configs: + runtime: + dns: true + monitoring: true + +# prod.yml - Production additions +bosh-configs: + runtime: + security: + strict_mode: true + logging: + archive: true +``` + +### 2. Document Options + +Include comments explaining options: + +```yaml +bosh-configs: + runtime: + dns: + # Increased cache for high-traffic environment + cache_size: 50000 + + # Custom upstream for internal domains + handlers: + - domain: internal.company.com + forward: 10.0.0.100 +``` + +### 3. Validate Compatibility + +Ensure runtime configs are compatible: + +```yaml +bosh-configs: + runtime: + # These work together + monitoring: true + logging: true + + # But not with this (example) + legacy_monitoring: false +``` + +### 4. Use Defaults Wisely + +Leverage kit defaults when appropriate: + +```yaml +bosh-configs: + runtime: + # Use all kit defaults + "*": true + + # Except customize DNS + dns: + cache_size: 20000 +``` + +## Troubleshooting + +### Runtime Config Not Applied + +Check if config is generated: + +```bash +# List runtime configs +genesis do my-env -- list-runtime-configs + +# View generated config +genesis do my-env -- runtime-config dns +``` + +### Option Not Recognized + +Runtime config hooks should gracefully handle unknown options: + +```yaml +bosh-configs: + runtime: + dns: + unknown_option: value # Should be ignored, not error +``` + +### Conflicts Between Configs + +Some runtime configs may conflict: + +```yaml +bosh-configs: + runtime: + # Error: Both provide syslog forwarding + logging: true + legacy_syslog: true +``` + +## Migration Examples + +### From Manual Runtime Configs + +Migrating from manually managed runtime configs: + +```bash +# Export current runtime config +bosh runtime-config > current-runtime.yml + +# Analyze and map to Genesis options +# Add to environment file: +bosh-configs: + runtime: + dns: + # Options matching current-runtime.yml +``` + +### Upgrading Runtime Configs + +When upgrading kits with new runtime configs: + +```yaml +# Before upgrade - explicit list +bosh-configs: + runtime: + - dns + - monitoring + +# After upgrade - use new configs +bosh-configs: + runtime: + - dns + - monitoring + - security # New in kit v2.0 +``` + +## Complete Example + +Comprehensive runtime config setup: + +```yaml +# production.yml +genesis: + env: production + +bosh-configs: + runtime: + # Global options for all configs + "*": + environment: production + region: us-east-1 + owner: platform-team + + # DNS with production settings + dns: + cache: + enabled: true + size: 100000 + ttl: 300 + recursors: + - 8.8.8.8 + - 8.8.4.4 + handlers: + - domain: consul.service.consul + forward: 127.0.0.1:8600 + - domain: internal.company.com + forward: 10.0.0.53 + + # Comprehensive monitoring + monitoring: + node_exporter: + enabled: true + port: 9100 + prometheus: + scrape_interval: 15s + external_labels: + environment: production + region: us-east-1 + telegraf: + enabled: true + interval: 10s + outputs: + - influxdb: "https://metrics.company.com:8086" + + # Strict security settings + security: + os_hardening: + kernel: true + network: true + filesystem: true + compliance: + mode: pci-dss + audit_level: detailed + tls: + min_version: "1.2" + cipher_suites: modern + + # Centralized logging + logging: + syslog: + address: syslog-aggregator.company.com + port: 6514 + protocol: tcp + tls: + enabled: true + verify: true + format: json + buffer_size: 65536 + include: + - system + - audit + - application + + # Exclude development tools + toolbelt: false +``` + +## Future Enhancements + +### Cross-Kit Runtime Configs + +Future versions may support specifying runtime configs from other kits: + +```yaml +bosh-configs: + runtime: + # From BOSH kit + dns: true + + # From Shield kit + "shield/backup-agent": + schedule: "0 2 * * *" + + # From Prometheus kit + "prometheus/exporters": + - node + - process + - postgres +``` + +### Runtime Config Dependencies + +Automatic dependency resolution: + +```yaml +bosh-configs: + runtime: + monitoring: true # Automatically enables dns if required +``` + +### Conditional Runtime Configs + +Environment-aware configurations: + +```yaml +bosh-configs: + runtime: + monitoring: + enabled: (( grab meta.monitoring_enabled || false )) + endpoint: (( concat "https://prometheus." params.base_domain ":9090" )) +``` + +Runtime configurations provide powerful cross-cutting functionality for all deployments while maintaining flexibility through Genesis's configuration system. \ No newline at end of file diff --git a/lib/Genesis/Commands.pm b/lib/Genesis/Commands.pm index ecb1ae37..530917b8 100644 --- a/lib/Genesis/Commands.pm +++ b/lib/Genesis/Commands.pm @@ -85,13 +85,13 @@ our @global_options = ( # {{{ [ "help|h" => "Show this help screen.", - + "help-full" => "Show help screen with all available options including global options.", - + "helpful" => "Show help screen with all available options including global options (same as --help-full, but more fun!).", - + "globals" => "Show only the global options available to all commands.", ], @@ -228,6 +228,7 @@ sub known_commands { # list the known genesis commands specified by define_comma sub prepare_command { # {{{ ($CALLED, my @args) = @_; $COMMAND = $GENESIS_COMMANDS{$CALLED}; + $ENV{'GENESIS_COMMAND'} = $COMMAND; trace "Preparing genesis command '$COMMAND'".($CALLED ne $COMMAND ? ' (called as $CALLED)':''); parse_options(\@args); set_logging_state(); @@ -364,7 +365,7 @@ sub get_args { # {{{ sub has_option { # {{{ # Returns 0 if the option does not exists # Returns 1 if it does and no test is provided - # Compares the content of the option to the test if provided, + # Compares the content of the option to the test if provided, # which can be undef (returns true if the option is also undef), # a string (returns true if the option is equal to the string), # or a regex (returns true if the option matches the regex). @@ -373,7 +374,7 @@ sub has_option { # {{{ return 1 unless @_; my $test = shift; if (!defined($COMMAND_OPTIONS->{$option}) || !defined($test)) { - return !defined($COMMAND_OPTIONS->{$option}) && !defined($test) + return !defined($COMMAND_OPTIONS->{$option}) && !defined($test) } elsif (ref($test) eq "Regexp") { return $COMMAND_OPTIONS->{$option} =~ $test ? 1 : 0; } else { @@ -493,6 +494,13 @@ sub command_help { # {{{ } } + $out .= "\n"; + $out .= wrap( + "For comprehensive documentation on Genesis concepts and usage, run " . + "#C{genesis help topics} to browse available help topics.", + terminal_width + )."\n"; + $out .= "\n$ver$hr\n"; info({raw => 1}, $out); exit $rc; @@ -552,10 +560,10 @@ sub command_usage { # {{{ my @sources = ( [args => $PROPS{$COMMAND}{arguments} || [], 'Argument'], [vars => $PROPS{$COMMAND}{variables} || [], 'Environmental Variable'], - [command =>$PROPS{$COMMAND}{options} || [], 'Option'], [legacy => $PROPS{$COMMAND}{deprecated_options} || []], + [command => $PROPS{$COMMAND}{options} || [], 'Option'], ); - + # Only add global options if explicitly requested or if we're checking help from command line if ($show_global || (!defined($show_global) && get_options->{help})) { push @sources, [global => [(map {@$_} @global_options[0..$PROPS{$COMMAND}{option_group}])]]; @@ -672,7 +680,7 @@ sub show_global_options { # {{{ my $out = ""; $out .= wrap("#G{Global Options} - Available to all Genesis commands", terminal_width)."\n\n"; $out .= wrap("#g{${\(humanize_bin)}} [] #G{} []",terminal_width,"#Wku{Usage:} ", 7)."\n"; - + my (%options_desc, %options_def, %options_order); my $section = 0; for my $global_opt_group (@global_options) { @@ -713,9 +721,9 @@ sub show_global_options { # {{{ $options_def{$opt_def} = "#y{$opt_label}#B{$opt_arg}"; } } - + my $def_width = (sort {$b <=> $a} map {csize($_)} values(%options_def))[0] + 4; - + if (defined $options_order{global}) { $out .= "\n#Wku{Global Options}\n"; for (@{$options_order{global}}) { diff --git a/lib/Genesis/Commands/Core.pm b/lib/Genesis/Commands/Core.pm index ab6b7a9f..88bee8d0 100644 --- a/lib/Genesis/Commands/Core.pm +++ b/lib/Genesis/Commands/Core.pm @@ -193,6 +193,49 @@ EOF exec {$target} $target, 'version'; } +sub help { + + # First check if we just want to see global options alone + if (!@_ && get_options->{globals}) { + # Show only global options + Genesis::Commands::show_global_options(); + return; + } + + if (@_) { + my $cmd = shift; + + # Check for help topics command + if ($cmd eq 'topics') { + require Genesis::HelpTopics; + Genesis::HelpTopics::list_help_topics(); + return; + } + + # Check if it's a help topic + require Genesis::HelpTopics; + if (Genesis::HelpTopics::is_help_topic($cmd)) { + Genesis::HelpTopics::show_help_topic($cmd); + return; + } + + # Check if command exists + if (exists $Genesis::Commands::GENESIS_COMMANDS{$cmd}) { + # Prepare command context for usage display + $Genesis::Commands::CALLED = $cmd; + $Genesis::Commands::COMMAND = $Genesis::Commands::GENESIS_COMMANDS{$cmd}; + # Show globals if --globals, --help-full, or --helpful flag is present + my $show_global = (get_options->{globals} || get_options->{'help-full'} || get_options->{helpful}) ? 1 : 0; + command_usage(0, undef, $show_global); + } else { + command_help("Unknown command or topic: #G{$cmd}", 2); + } + } else { + # Show general help listing + command_help(); + } +} + sub hack { my ($cmd, @args) = @_; @@ -283,7 +326,7 @@ sub hack { bail( "Improperly formatted expression: unexpected opening parenthesis while waiting for argment", ) if ($waiting_for eq 'arg'); - $waiting_for = 'arg'; + $waiting_for = 'arg'; my $obj = $obj->$method_name(@method_args); $call_ready = 0; } diff --git a/lib/Genesis/Help/Topics/00-getting-started/.keep b/lib/Genesis/Help/Topics/00-getting-started/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/00-getting-started/concepts.md b/lib/Genesis/Help/Topics/00-getting-started/concepts.md new file mode 100644 index 00000000..b5cb58c2 --- /dev/null +++ b/lib/Genesis/Help/Topics/00-getting-started/concepts.md @@ -0,0 +1,212 @@ +# Core Genesis Concepts + +Understanding these fundamental concepts will help you use Genesis effectively. + +## Kits + +A **kit** is a pre-packaged template for deploying a specific type of software with BOSH. Kits encapsulate: + +- **Manifest Templates** - YAML templates that generate BOSH manifests +- **Default Configuration** - Sensible defaults and best practices +- **Features** - Optional components you can enable/disable +- **Secrets Definitions** - What credentials and certificates to generate +- **Lifecycle Hooks** - Scripts that run during deployment phases + +### Example Kits +- `bosh-genesis-kit` - Deploy BOSH directors +- `cf-genesis-kit` - Deploy Cloud Foundry +- `vault-genesis-kit` - Deploy Vault clusters +- `concourse-genesis-kit` - Deploy Concourse CI + +## Repositories + +A **repository** is a Git repository containing related Genesis deployments. Repositories provide: + +- Version control for your infrastructure +- Shared configuration across environments +- Audit trail of changes +- Collaboration through pull requests + +### Repository Structure +``` +my-deployments/ +├── .genesis/ +│ ├── bin/ # Repository-specific scripts +│ ├── cache/ # Downloaded kit cache +│ └── kits/ # Local kit overrides +├── us-east-1.yml # Region configuration +├── us-east-1-prod.yml # Environment file +└── us-east-1-dev.yml # Environment file +``` + +## Environments + +An **environment** represents a single deployment. Each environment: + +- Has its own YAML configuration file +- Inherits from parent configurations +- Generates a unique BOSH manifest +- Maintains its own secrets in Vault + +### Environment Files +```yaml +--- +kit: + name: bosh + version: 2.2.0 + features: + - aws + - proto + +params: + env: us-east-1-prod + aws_region: us-east-1 +``` + +## Hierarchical Configuration + +Genesis uses **hierarchical configuration** to avoid repetition: + +1. **Global** - Repository-wide defaults +2. **Regional** - Infrastructure-specific settings +3. **Environmental** - Deployment-specific overrides + +### Example Hierarchy +``` +site.yml # Global settings for all environments +└── us.yml # US-specific settings + └── us-east.yml # us-east region settings + └── us-east-1.yml # Specific environment + └── us-east-1-prod.yml # Most specific +``` + +### Configuration Merging +```yaml +# site.yml +params: + vault: https://vault.example.com:8200 + +# us.yml +params: + domain: us.example.com + +# us-east-1-prod.yml +params: + env: prod + # Inherits vault and domain from parents +``` + +## Features + +**Features** are optional kit components you can enable: + +```yaml +kit: + features: + - vsphere # vSphere infrastructure + - syslog # Syslog forwarding + - prometheus # Metrics exporter +``` + +Features can: +- Add manifest snippets +- Require additional parameters +- Generate specific secrets +- Run validation checks + +## Secrets Management + +Genesis integrates with **Vault** (or CredHub) for secrets: + +### Automatic Generation +- Passwords and credentials +- SSH keys +- X.509 certificates +- RSA key pairs + +### Secret Paths +Secrets follow a predictable path structure: +``` +secret/us-east-1/prod/bosh/ +├── admin_password +├── ca +├── director_tls +└── db_password +``` + +### Secret Rotation +```bash +# Rotate specific secrets +genesis rotate-secrets my-env admin_password + +# Rotate all secrets +genesis rotate-secrets my-env --all +``` + +## Lifecycle Hooks + +**Hooks** are scripts that run at specific times: + +- **new** - When creating a new environment +- **blueprint** - When generating the manifest +- **check** - Pre-deployment validation +- **pre-deploy** - Before deployment +- **post-deploy** - After deployment +- **addon** - Custom operator scripts + +## Deployment Workflow + +The typical Genesis workflow: + +1. **Initialize** - Create a repository with a kit +2. **Configure** - Create environment files +3. **Generate Secrets** - Auto-generate credentials +4. **Deploy** - Push to BOSH +5. **Manage** - Update, rotate secrets, scale + +### Example Workflow +```bash +# Initialize repository +genesis init --kit vault my-vault-deployments +cd my-vault-deployments + +# Create environment +genesis new us-east-prod + +# Edit configuration +vim us-east-prod.yml + +# Check and deploy +genesis check us-east-prod +genesis deploy us-east-prod +``` + +## Manifest Generation + +Genesis generates BOSH manifests by: + +1. Loading the kit's base manifest +2. Applying features +3. Merging environment parameters +4. Injecting secrets from Vault +5. Running blueprint hooks + +You can view the generated manifest: +```bash +genesis manifest my-env +``` + +## Best Practices + +1. **Use Version Control** - Commit all environment files +2. **Hierarchical Config** - Share common settings +3. **Feature Flags** - Use features instead of manual overrides +4. **Secret Rotation** - Regularly rotate credentials +5. **Environment Naming** - Use consistent naming patterns + +## Next Steps + +Now that you understand the concepts: +- [Configure Genesis](configuration.md) for your needs +- Create your [First Deployment](first-deployment.md) +- Learn about [Environment Management](../10-environments/index.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/00-getting-started/configuration.md b/lib/Genesis/Help/Topics/00-getting-started/configuration.md new file mode 100644 index 00000000..60a90b75 --- /dev/null +++ b/lib/Genesis/Help/Topics/00-getting-started/configuration.md @@ -0,0 +1,202 @@ +# Basic Genesis Configuration + +This guide covers essential Genesis configuration for new users. For a complete configuration reference, see the [Configuration Reference Guide](../90-reference-guides/configuration.md). + +## Configuration File + +Genesis stores its configuration in `~/.genesis/config` (YAML format). + +```bash +# Create the configuration directory +mkdir -p ~/.genesis + +# Create a basic configuration file +vim ~/.genesis/config +``` + +## Essential Settings + +### BOSH Target Behavior + +When deploying, Genesis needs to know which BOSH director to use. Configure the default behavior: + +```yaml +--- +# How to select BOSH directors when multiple options exist +default_bosh_target: ask # ask, parent, or self +``` + +Options: +- **ask** - Prompt to select a director (recommended for beginners) +- **parent** - Use the director that deployed this environment +- **self** - Use this environment as the director (for BOSH directors) + +### Deployment Roots + +Organize your Genesis repositories in standard locations: + +```yaml +deployment_roots: + - ~/deployments # Personal deployments + - work: ~/work/deploy # Work deployments (with label) +``` + +This helps Genesis: +- Find repositories with `genesis switch` +- Organize the `genesis list` output +- Provide better command completion + +## Common Configurations + +### For Development Environments + +```yaml +--- +default_bosh_target: ask + +deployment_roots: + - ~/dev/genesis + +# Suppress warnings about embedded Genesis +embedded_genesis: ignore + +# Automatically upgrade configs without prompting +automatic_config_upgrade: yes +``` + +### For Production Environments + +```yaml +--- +default_bosh_target: parent + +deployment_roots: + - prod: /opt/genesis/production + - staging: /opt/genesis/staging + +# Check for embedded Genesis issues +embedded_genesis: warn + +# Never auto-upgrade configs +automatic_config_upgrade: no +``` + +### For CI/CD Systems + +```yaml +--- +default_bosh_target: parent + +# Silent config upgrades for automation +automatic_config_upgrade: silent + +# Use environment variables for dynamic config +# Set GENESIS_BOSH_ENVIRONMENT, GENESIS_VAULT_PREFIX, etc. +``` + +## Environment Variables + +Genesis configuration can also be set via environment variables: + +```bash +# Override config file settings +export GENESIS_DEFAULT_BOSH_TARGET=parent +export GENESIS_LEGACY_REPO_SUFFIX=false + +# Set deployment roots +export GENESIS_DEPLOYMENT_ROOTS="$HOME/deployments;work=$HOME/work/deploy" + +# Configure default behaviors +export GENESIS_CONFIG_AUTOMATIC_UPGRADE=yes +``` + +### Precedence + +Environment variables take precedence over config file settings. + +## Vault Configuration + +While Vault settings are typically per-environment, you can set defaults: + +```bash +# Default Vault server +export GENESIS_VAULT_SERVER=https://vault.example.com:8200 + +# Skip TLS verification (development only!) +export VAULT_SKIP_VERIFY=1 +``` + +## Shell Completion + +Enable command completion for better usability: + +### Bash +```bash +echo 'source <(genesis completion bash)' >> ~/.bashrc +``` + +### Zsh +```bash +echo 'source <(genesis completion zsh)' >> ~/.zshrc +``` + +## Verifying Configuration + +Check your configuration: + +```bash +# Show effective configuration +genesis config + +# Test BOSH connectivity +genesis ping + +# List known deployments +genesis list +``` + +## Common Issues + +### Permission Denied + +If Genesis can't write to `~/.genesis/config`: +```bash +# Fix permissions +chmod 755 ~/.genesis +chmod 644 ~/.genesis/config +``` + +### Config Not Loading + +Genesis looks for config in this order: +1. `$GENESIS_CONFIG_FILE` (if set) +2. `~/.genesis/config` +3. Built-in defaults + +### Environment Variable Syntax + +For arrays in environment variables, use `:` as separator: +```bash +# Multiple deployment roots +export GENESIS_DEPLOYMENT_ROOTS="/opt/genesis:$HOME/deployments" + +# With labels, use = and ; +export GENESIS_DEPLOYMENT_ROOTS="prod=/opt/prod;dev=/opt/dev" +``` + +## Advanced Configuration + +For more configuration options including: +- Pipeline automation settings +- Advanced BOSH configurations +- Custom hook behaviors +- Experimental features + +See the [Complete Configuration Reference](../90-reference-guides/configuration.md). + +## Next Steps + +With Genesis configured: +- Create your [First Deployment](first-deployment.md) +- Learn about [Environment Management](../10-environments/index.md) +- Explore [Kit Selection](../50-kits/using-kits.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/00-getting-started/first-deployment.md b/lib/Genesis/Help/Topics/00-getting-started/first-deployment.md new file mode 100644 index 00000000..96da4687 --- /dev/null +++ b/lib/Genesis/Help/Topics/00-getting-started/first-deployment.md @@ -0,0 +1,252 @@ +# Your First Genesis Deployment + +This guide walks you through deploying your first environment with Genesis. We'll deploy a BOSH director, which is the foundation for all other deployments. + +## Prerequisites + +Before starting, ensure you have: +- [Genesis installed](installation.md) with all dependencies +- [Basic configuration](configuration.md) in place +- Access to a supported IaaS (AWS, Azure, GCP, vSphere, or OpenStack) +- IaaS credentials ready + +## Step 1: Initialize a Repository + +Create a new Genesis repository for BOSH deployments: + +```bash +# Create and enter the repository +genesis init --kit bosh my-bosh-deployments +cd my-bosh-deployments +``` + +This creates: +- A Git repository for version control +- `.genesis/` directory for Genesis metadata +- Initial kit configuration + +## Step 2: Select Your Infrastructure + +Genesis needs to know what infrastructure you're using: + +```bash +# List available features for the BOSH kit +genesis info bosh +``` + +Common infrastructure features: +- `aws` - Amazon Web Services +- `azure` - Microsoft Azure +- `google` - Google Cloud Platform +- `vsphere` - VMware vSphere +- `openstack` - OpenStack + +## Step 3: Create an Environment + +Create your first environment file: + +```bash +# Create a new environment (interactive wizard) +genesis new my-lab +``` + +The wizard will ask for: +1. **Infrastructure type** - Select your IaaS +2. **Environment name** - A descriptive name +3. **Vault prefix** - Where to store secrets +4. **Network configuration** - Subnet ranges +5. **IaaS-specific details** - Credentials, regions, etc. + +## Step 4: Review Configuration + +Examine the generated environment file: + +```bash +# View the environment configuration +cat my-lab.yml +``` + +Example AWS configuration: +```yaml +--- +kit: + name: bosh + version: 2.2.0 + features: + - aws + - proto + +params: + env: my-lab + bosh_vm_type: t3.small + + # AWS Configuration + aws_region: us-east-1 + aws_default_sgs: + - bosh + + # Networking + subnet_addr: 10.128.0.0/24 + default_gateway: 10.128.0.1 + dns: + - 8.8.8.8 + - 8.8.4.4 +``` + +## Step 5: Configure Vault + +Genesis uses Vault to store secrets. If you don't have Vault running: + +```bash +# Start a development Vault (for testing only!) +safe init +safe verify +``` + +For production, use a properly configured Vault cluster. + +## Step 6: Generate Cloud Config + +For AWS, Azure, or GCP, generate the required cloud config: + +```bash +# Generate IaaS configuration +genesis do my-lab -- cloud-config +``` + +This creates the necessary IaaS resources: +- Networks and subnets +- Security groups +- SSH keys +- Other IaaS-specific resources + +## Step 7: Deploy + +Now deploy your BOSH director: + +```bash +# Verify everything looks correct +genesis check my-lab + +# Deploy (this takes 15-30 minutes) +genesis deploy my-lab +``` + +Genesis will: +1. Generate required secrets in Vault +2. Create the BOSH manifest +3. Deploy the BOSH director +4. Configure local BOSH CLI access + +## Step 8: Verify Deployment + +Once deployed, verify your BOSH director: + +```bash +# Target the new BOSH director +genesis do my-lab -- login + +# Check BOSH status +bosh env + +# View deployments (should be empty) +bosh deployments +``` + +## Common Issues + +### Deployment Fails + +If deployment fails: +```bash +# Check the deployment log +genesis deploy my-lab -l debug + +# View BOSH task output +bosh task --debug +``` + +### Network Issues + +Ensure: +- Subnet ranges don't overlap +- Security groups allow required ports +- DNS servers are reachable + +### Credential Problems + +For IaaS credential issues: +```bash +# Re-run the new wizard +genesis new my-lab --force + +# Or edit directly +vim my-lab.yml +``` + +## Next Steps + +Congratulations! You've deployed your first Genesis environment. Now you can: + +### Deploy Additional Software + +```bash +# Initialize a Vault deployment repository +cd .. +genesis init --kit vault my-vault-deployments +cd my-vault-deployments + +# Create Vault environment targeting your BOSH +genesis new my-vault +``` + +### Learn More + +- [Environment Management](../10-environments/index.md) - Managing multiple environments +- [Secrets Management](../30-secrets-management/index.md) - Working with Vault +- [Using Kits](../50-kits/index.md) - Deploying other software + +### Useful Commands + +```bash +# List all Genesis environments +genesis list + +# Show environment details +genesis describe my-lab + +# Rotate credentials +genesis rotate-secrets my-lab + +# SSH to BOSH director +genesis do my-lab -- ssh + +# View generated manifest +genesis manifest my-lab +``` + +## Clean Up + +To destroy the environment when done testing: + +```bash +# Delete the deployment +genesis do my-lab -- destroy + +# Remove environment file +rm my-lab.yml +git add -A +git commit -m "Removed lab environment" +``` + +## Production Considerations + +For production deployments: + +1. **Use proper Vault** - Not the dev server +2. **Configure backups** - Use Shield or BBR +3. **Enable monitoring** - Prometheus exporters +4. **Set up CI/CD** - Concourse pipelines +5. **Document everything** - Including credentials and procedures + +See the [BOSH kit documentation](../50-kits/bosh.md) for production configuration details. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/00-getting-started/index.md b/lib/Genesis/Help/Topics/00-getting-started/index.md new file mode 100644 index 00000000..14126df7 --- /dev/null +++ b/lib/Genesis/Help/Topics/00-getting-started/index.md @@ -0,0 +1,74 @@ +# Getting Started with Genesis + +Welcome to Genesis! This guide will help you understand Genesis concepts and get your first deployment running. + +## Topics in This Section + +1. **[Introduction](introduction.md)** - What is Genesis and why use it? +2. **[Installation](installation.md)** - Installing Genesis and required dependencies +3. **[Concepts](concepts.md)** - Core Genesis concepts and terminology +4. **[Configuration](configuration.md)** - Basic Genesis configuration +5. **[First Deployment](first-deployment.md)** - Deploy your first environment +6. **[Next Steps](next-steps.md)** - Where to go from here + +## Quick Start + +If you're in a hurry, here's the minimum you need to get started: + +### Install Genesis + +```bash +# Download and install the latest Genesis +curl -sL https://github.com/genesis-community/genesis/releases/latest/download/genesis -o genesis +chmod +x genesis +sudo mv genesis /usr/local/bin/ + +# Verify installation +genesis version +``` + +### Install Dependencies + +Genesis requires several tools to function: + +```bash +# Required tools +# - safe (Vault CLI) +# - spruce (YAML processor) +# - bosh (BOSH CLI v2) +# - jq (JSON processor) + +# On macOS with Homebrew: +brew install starkandwayne/cf/safe +brew install starkandwayne/cf/spruce +brew install cloudfoundry/tap/bosh-cli +brew install jq + +# On Linux, follow individual tool installation guides +``` + +### Initialize Your First Repository + +```bash +# Create a new Genesis repository for BOSH deployments +genesis init --kit bosh my-bosh-deployments +cd my-bosh-deployments + +# Create your first environment +genesis new my-lab +``` + +### Next Steps + +Continue with the detailed guides in this section to: +- Understand Genesis architecture and concepts +- Configure Genesis for your environment +- Deploy and manage your first BOSH director +- Learn about environment hierarchies and configuration management + +## Getting Help + +- Run `genesis help` for command reference +- Visit specific help topics with `genesis help ` +- Check the [troubleshooting guide](../70-troubleshooting/index.md) for common issues +- Join the Genesis community Slack for support \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/00-getting-started/installation.md b/lib/Genesis/Help/Topics/00-getting-started/installation.md new file mode 100644 index 00000000..4fedf0a5 --- /dev/null +++ b/lib/Genesis/Help/Topics/00-getting-started/installation.md @@ -0,0 +1,223 @@ +# Installing Genesis + +This guide covers installing Genesis and its required dependencies. + +## System Requirements + +Genesis runs on: +- macOS (Intel and Apple Silicon) +- Linux (x86_64) +- Windows (via WSL2) + +## Installing Genesis + +### Quick Install (Recommended) + +Download the latest release directly from GitHub: + +```bash +# Download the latest Genesis binary +curl -sL https://github.com/genesis-community/genesis/releases/latest/download/genesis -o genesis + +# Make it executable +chmod +x genesis + +# Move to your PATH (may require sudo) +sudo mv genesis /usr/local/bin/ + +# Verify installation +genesis version +``` + +### Alternative Installation Methods + +#### Using Homebrew (macOS) + +```bash +brew tap genesis-community/genesis +brew install genesis +``` + +#### Manual Download + +1. Visit the [Genesis releases page](https://github.com/genesis-community/genesis/releases) +2. Download the appropriate binary for your platform +3. Make it executable and place it in your PATH + +## Required Dependencies + +Genesis requires several tools to function properly. Install all of these before using Genesis: + +### 1. Safe (Vault CLI) + +Safe is used for secrets management with Vault. + +```bash +# macOS +brew install starkandwayne/cf/safe + +# Linux (64-bit) +curl -sL https://github.com/starkandwayne/safe/releases/latest/download/safe-linux-amd64 -o safe +chmod +x safe +sudo mv safe /usr/local/bin/ +``` + +### 2. Spruce + +Spruce is used for YAML manipulation and merging. + +```bash +# macOS +brew install starkandwayne/cf/spruce + +# Linux +curl -sL https://github.com/geofffranks/spruce/releases/latest/download/spruce-linux-amd64 -o spruce +chmod +x spruce +sudo mv spruce /usr/local/bin/ +``` + +### 3. BOSH CLI v2 + +The BOSH CLI is used for deploying to BOSH directors. + +```bash +# macOS +brew install cloudfoundry/tap/bosh-cli + +# Linux +curl -sL https://github.com/cloudfoundry/bosh-cli/releases/latest/download/bosh-cli-*-linux-amd64 -o bosh +chmod +x bosh +sudo mv bosh /usr/local/bin/ +``` + +### 4. jq + +jq is used for JSON processing. + +```bash +# macOS +brew install jq + +# Linux (Ubuntu/Debian) +sudo apt-get update && sudo apt-get install -y jq + +# Linux (RedHat/CentOS) +sudo yum install -y jq +``` + +### 5. Git + +Git is used for version control of your deployment repositories. + +```bash +# macOS (usually pre-installed) +git --version + +# Linux (Ubuntu/Debian) +sudo apt-get update && sudo apt-get install -y git + +# Linux (RedHat/CentOS) +sudo yum install -y git +``` + +## Optional Dependencies + +These tools enhance Genesis functionality but aren't strictly required: + +### CredHub CLI + +For deployments using CredHub instead of Vault: + +```bash +# macOS +brew install cloudfoundry/tap/credhub-cli + +# Linux +curl -sL https://github.com/cloudfoundry-incubator/credhub-cli/releases/latest/download/credhub-linux-*.tgz -o credhub.tgz +tar -xzf credhub.tgz +sudo mv credhub /usr/local/bin/ +``` + +### Vault + +For running a local Vault server: + +```bash +# macOS +brew install vault + +# Linux +curl -sL https://releases.hashicorp.com/vault/*/vault_*_linux_amd64.zip -o vault.zip +unzip vault.zip +sudo mv vault /usr/local/bin/ +``` + +## Verify Installation + +After installing Genesis and its dependencies, verify everything is working: + +```bash +# Check Genesis +genesis version + +# Check dependencies +safe version +spruce --version +bosh --version +jq --version +git --version + +# Optional: Check if all dependencies are found +genesis ping +``` + +## Initial Configuration + +Genesis stores its configuration in `~/.genesis/config`. Create this file with basic settings: + +```bash +# Create Genesis configuration directory +mkdir -p ~/.genesis + +# Create basic configuration +cat > ~/.genesis/config <` for detailed guides +- Check kit documentation with `genesis info ` + +### Community + +- **Slack** - Join [Genesis Community Slack](https://genesiscommunity.slack.com) +- **GitHub** - Report issues and contribute +- **Office Hours** - Weekly community calls + +### Learning Resources + +- **[Genesis Examples](https://github.com/genesis-community/examples)** - Sample deployments +- **[Kit Repositories](https://github.com/genesis-community)** - All official kits +- **[Training Materials](https://genesis-community.io/docs)** - Workshops and tutorials + +## Certification Path + +Consider this learning progression: + +1. **Genesis Basics** ✓ + - First deployment + - Environment management + - Basic operations + +2. **Intermediate Skills** + - Multi-environment deployments + - Pipeline automation + - Troubleshooting + +3. **Advanced Topics** + - Kit development + - Complex architectures + - Performance tuning + +4. **Expert Level** + - Contributing to Genesis + - Creating community kits + - Training others + +## Quick Reference + +Essential commands for your journey: + +```bash +# Deployment lifecycle +genesis init --kit # Start new repository +genesis new # Create environment +genesis deploy # Deploy environment +genesis info # Kit documentation + +# Operations +genesis list # List all environments +genesis switch # Change repositories +genesis describe # Environment details +genesis manifest # View manifest + +# Maintenance +genesis rotate-secrets # Rotate credentials +genesis check # Pre-deployment checks +genesis do -- # Run kit addons + +# Help +genesis help # General help +genesis help # Topic help +genesis -h # Command help +``` + +## Your Genesis Journey + +Remember: +- Start small and iterate +- Use version control for everything +- Ask questions in the community +- Share your experiences + +Welcome to the Genesis community! \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/.keep b/lib/Genesis/Help/Topics/10-environments/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/10-environments/best-practices.md b/lib/Genesis/Help/Topics/10-environments/best-practices.md new file mode 100644 index 00000000..eeb8f4bb --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/best-practices.md @@ -0,0 +1,462 @@ +# Environment Best Practices + +This guide provides recommendations for organizing and managing Genesis environments effectively, based on real-world experience with large-scale deployments. + +## Naming Conventions + +### Choose a Consistent Pattern + +Pick one pattern and use it everywhere: + +```yaml +# Pattern 1: Organization-first (Recommended) +acme-aws-us-east-1-prod +acme-aws-us-west-2-staging +acme-vsphere-dc1-dev + +# Pattern 2: Purpose-last (Also good) +aws-us-east-1-acme-prod +aws-us-west-2-acme-staging +vsphere-dc1-acme-dev +``` + +### Keep Names Meaningful + +Each segment should convey information: + +```yaml +# Good - Clear hierarchy +acme-aws-us-east-1-prod +#│ │ │ │ └─ Purpose/Stage +#│ │ │ └────── Availability Zone +#│ │ └─────────── Region +#│ └──────────────── Infrastructure +#└───────────────────── Organization + +# Bad - Unclear segments +acme-aws-use1-p +env-1-prod +``` + +### Document Your Convention + +Create a README explaining your naming: + +```markdown +# Environment Naming Convention + +All environments follow this pattern: +`----` + +- org: Organization identifier (acme, globex) +- cloud: Infrastructure provider (aws, azure, gcp, vsphere) +- region: Geographic region (us-east-1, europe-west1) +- az: Availability zone or datacenter (optional) +- purpose: Environment purpose (prod, staging, dev, sandbox) +``` + +## Configuration Organization + +### Use Hierarchy Effectively + +Organize configurations from general to specific: + +```yaml +# base.yml - Global settings +params: + company: ACME Corp + ntp_servers: [0.pool.ntp.org, 1.pool.ntp.org] + +# aws.yml - AWS-wide settings +params: + stemcell_os: ubuntu-bionic + stemcell_version: latest + +# aws-us-east-1.yml - Region settings +params: + region: us-east-1 + availability_zones: [a, b, c] + +# aws-us-east-1-prod.yml - Environment specific +params: + instances: 5 + enable_monitoring: true +``` + +### Avoid Duplication + +Put shared settings at the appropriate level: + +```yaml +# Bad - Duplicated in every environment +# aws-us-east-1-dev.yml +params: + ntp_servers: [10.0.0.1, 10.0.0.2] + dns_servers: [10.0.0.3, 10.0.0.4] + +# aws-us-east-1-prod.yml +params: + ntp_servers: [10.0.0.1, 10.0.0.2] # Duplicate! + dns_servers: [10.0.0.3, 10.0.0.4] # Duplicate! + +# Good - Shared at region level +# aws-us-east-1.yml +params: + ntp_servers: [10.0.0.1, 10.0.0.2] + dns_servers: [10.0.0.3, 10.0.0.4] +``` + +### Feature Management + +Use features consistently: + +```yaml +# base.yml - Default features +kit: + features: + - base-monitoring + - base-logging + +# prod.yml - Production additions +kit: + features: + - base-monitoring + - base-logging + - haproxy # Add load balancer + - shield-agent # Add backups +``` + +## Directory Structure + +### Standard Layout + +Maintain consistent directory structure: + +``` +deployments/ +├── README.md # Document your conventions +├── .gitignore # Exclude caches and secrets +├── bin/ # Shared scripts and reactions +│ ├── common-functions +│ ├── notify-slack +│ └── update-dns +├── bosh/ # BOSH directors +│ ├── base.yml +│ ├── aws.yml +│ └── aws-us-east-1.yml +├── vault/ # Vault clusters +│ ├── base.yml +│ └── aws-us-east-1.yml +└── cf/ # Cloud Foundry + ├── base.yml + ├── aws.yml + ├── aws-us-east-1.yml + └── aws-us-east-1-prod.yml +``` + +### Separate Concerns + +Keep different deployment types in separate directories: + +```bash +# Good - Clear separation +deployments/cf/ +deployments/concourse/ +deployments/vault/ + +# Bad - Mixed types +deployments/ +├── cf-prod.yml +├── vault-prod.yml +└── concourse-prod.yml +``` + +## Version Control + +### What to Commit + +```gitignore +# Always commit +*.yml # Environment files +bin/ # Scripts +ci/ # Pipeline definitions +README.md # Documentation + +# Never commit +.genesis/cache/ # Downloaded kits +.genesis/manifests/ # Generated manifests +*-secrets.yml # Any actual secrets +*.key # Private keys +*.pem # Certificates +``` + +### Branching Strategy + +Use branches for environment promotion: + +```bash +# Feature branch for changes +git checkout -b add-monitoring + +# Make changes +vim base.yml + +# Test in dev +genesis deploy aws-us-east-1-dev + +# Merge to main +git checkout main +git merge add-monitoring + +# Deploy through environments +genesis deploy aws-us-east-1-staging +genesis deploy aws-us-east-1-prod +``` + +### Commit Messages + +Be descriptive: + +```bash +# Good +git commit -m "Enable Shield backups for production CF" +git commit -m "Scale web instances from 3 to 5 in us-east-1" + +# Bad +git commit -m "Update config" +git commit -m "Changes" +``` + +## Security Practices + +### Never Store Secrets + +Always use Vault references: + +```yaml +# Bad - Hardcoded secret +params: + admin_password: "SuperSecret123!" + +# Good - Vault reference +params: + admin_password: ((vault "secret/path:password")) +``` + +### Protect Sensitive Configurations + +Some configurations reveal infrastructure: + +```yaml +# Consider making these Vault references +params: + aws_access_key: ((vault "secret/aws:access_key")) + aws_secret_key: ((vault "secret/aws:secret_key")) + internal_domain: ((vault "secret/networking:internal_domain")) +``` + +### Audit Access + +Regular review access patterns: + +```bash +# Check who can deploy to production +safe auth list + +# Review Vault policies +safe policy list +``` + +## Operational Practices + +### Environment Promotion + +Follow a consistent promotion path: + +``` +Development → Staging → Production + +sandbox → dev → qa → staging → prod +``` + +### Testing Changes + +Always test in lower environments: + +```bash +# 1. Deploy to dev +genesis deploy aws-us-east-1-dev + +# 2. Run smoke tests +genesis do aws-us-east-1-dev -- smoke-tests + +# 3. Promote to staging +genesis deploy aws-us-east-1-staging + +# 4. Full integration tests +run-integration-tests staging + +# 5. Deploy to production +genesis deploy aws-us-east-1-prod +``` + +### Documentation + +Document everything: + +```markdown +## Environment Overview + +### Production +- **Environment**: aws-us-east-1-prod +- **Purpose**: Production customer-facing services +- **Maintenance Window**: Sunday 2-4 AM EST +- **Contacts**: ops-team@example.com + +### Staging +- **Environment**: aws-us-east-1-staging +- **Purpose**: Pre-production testing +- **Refresh Schedule**: Weekly from production +- **Contacts**: dev-team@example.com +``` + +## Troubleshooting Practices + +### Manifest Validation + +Always check before deploying: + +```bash +# Check manifest generation +genesis manifest aws-us-east-1-prod + +# Validate changes +genesis manifest aws-us-east-1-prod > new.yml +genesis manifest aws-us-east-1-prod --cached > old.yml +diff old.yml new.yml +``` + +### Debugging Inheritance + +Understand your configuration chain: + +```bash +# See full inheritance +genesis describe aws-us-east-1-prod + +# Check specific values +genesis lookup aws-us-east-1-prod params.instances +``` + +### Rollback Procedures + +Document rollback steps: + +```markdown +## Rollback Procedure + +1. Revert Git commit: + ```bash + git revert HEAD + git push + ``` + +2. Redeploy previous version: + ```bash + genesis deploy aws-us-east-1-prod + ``` + +3. Verify services: + ```bash + genesis do aws-us-east-1-prod -- smoke-tests + ``` +``` + +## Performance Tips + +### Use Match Mode + +Enable for faster operations: + +```bash +# Setup in ~/.genesis/config +deployment_roots: + - ~/deployments + +# Use patterns +genesis deploy @prod:cf +genesis list @*:vault +``` + +### Cache Manifests + +For repeated operations: + +```bash +# Cache manifest for debugging +genesis manifest my-env --cache + +# Use cached version +genesis manifest my-env --cached +``` + +### Parallel Operations + +When safe, run in parallel: + +```bash +# Deploy multiple dev environments +genesis deploy aws-us-east-1-dev & +genesis deploy aws-us-west-2-dev & +wait +``` + +## Common Pitfalls to Avoid + +### 1. Inconsistent Naming + +Stick to your pattern: +```bash +# Bad - Mixed patterns +aws-us-east-1-prod +aws-west-2-prod # Missing 'us' +production-aws-east # Different order +``` + +### 2. Over-Nesting + +Don't create too many levels: +```bash +# Too deep +acme-aws-us-east-1-az-a-vpc-123-subnet-456-prod + +# Better +acme-aws-us-east-1a-prod +``` + +### 3. Environment Sprawl + +Regular cleanup: +```bash +# Find unused environments +genesis list | grep -E '(old|test|tmp)' + +# Archive old environments +mkdir archived +git mv *-old.yml archived/ +``` + +### 4. Forgetting Vault Paths + +Document special paths: +```yaml +# In environment file +# Note: This environment uses custom Vault paths +# Secrets: /secret/special/acme/prod/cf +# Exodus: /secret/exodus/acme-prod/cf +genesis: + secrets_slug: special/acme/prod + exodus_slug: acme-prod +``` + +By following these best practices, you'll maintain clean, understandable, and manageable Genesis deployments that scale with your organization. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/bosh-integration.md b/lib/Genesis/Help/Topics/10-environments/bosh-integration.md new file mode 100644 index 00000000..d98bcf8b --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/bosh-integration.md @@ -0,0 +1,402 @@ +# BOSH Integration + +Genesis environments map directly to BOSH deployments. Understanding this relationship is crucial for debugging, manual BOSH operations, and advanced deployment scenarios. + +## BOSH Director Selection + +### Automatic Selection + +By default, Genesis deploys to a BOSH director with the same name as the environment: + +```yaml +# Environment: acme-aws-us-east-1-prod.yml +# Deploys to: acme-aws-us-east-1-prod BOSH director +``` + +### Manual Override + +Override the target BOSH director: + +```yaml +genesis: + env: acme-aws-us-east-1-prod + bosh_env: acme-aws-us-east-1-mgmt # Use different director +``` + +Common override scenarios: +- BOSH directors (can't deploy to themselves) +- Shared management directors +- Cross-region deployments + +## Deployment Names + +### Naming Convention + +BOSH deployment names follow the pattern: +``` +- +``` + +Examples: +- Environment: `acme-aws-us-east-1-prod.yml` +- Kit: `cf-genesis-kit` +- BOSH deployment: `acme-aws-us-east-1-prod-cf` + +### Viewing Deployments + +```bash +# List all deployments on targeted director +bosh deployments + +# Filter by Genesis pattern +bosh deployments | grep -- '-cf$' +``` + +## BOSH Configuration Management + +### Cloud Config + +Genesis manages BOSH cloud configs with prefixed names: + +```yaml +# VM types become prefixed +vm_types: +- name: acme-aws-us-east-1-prod-small + cloud_properties: + instance_type: t3.small + +# Disk types are prefixed +disk_types: +- name: acme-aws-us-east-1-prod-small + disk_size: 10240 + +# Networks remain unprefixed +networks: +- name: default + type: manual + subnets: [...] +``` + +### Runtime Config + +Runtime configs can be specified per environment: + +```yaml +# In environment file +genesis: + runtime_configs: + - my-runtime-config + - dns-runtime-config +``` + +### CPI Config + +For multi-CPI directors: + +```yaml +genesis: + cpi_configs: + - aws-cpi-config +``` + +## Environment Variables + +### BOSH Connection + +Genesis sets these for BOSH operations: + +```bash +BOSH_ENVIRONMENT=10.0.0.6 +BOSH_CA_CERT=/tmp/genesis-ca-cert.XXXX +BOSH_CLIENT=admin +BOSH_CLIENT_SECRET= +``` + +### Manual BOSH Access + +```bash +# Get BOSH credentials +genesis do my-env -- login + +# Now use BOSH directly +bosh deployments +bosh vms +``` + +## Deployment Lifecycle + +### What Genesis Does + +1. **Pre-deployment**: + - Targets correct BOSH director + - Uploads required releases + - Updates cloud/runtime configs + - Generates manifest + +2. **Deployment**: + - Runs `bosh deploy` + - Monitors deployment progress + - Handles errors + +3. **Post-deployment**: + - Runs post-deploy hooks + - Updates exodus data + - Cleans up temporary files + +### Manual Deployment + +For troubleshooting, deploy manually: + +```bash +# Generate manifest +genesis manifest my-env > manifest.yml + +# Target BOSH +genesis do my-env -- login + +# Deploy manually +bosh -d my-env-cf deploy manifest.yml +``` + +## Advanced Integration + +### Instance Management + +```bash +# Through Genesis +genesis do my-env -- ssh router/0 + +# Direct BOSH commands +bosh -d acme-aws-us-east-1-prod-cf ssh router/0 +bosh -d acme-aws-us-east-1-prod-cf restart router +``` + +### Logs and Debugging + +```bash +# Get deployment logs +genesis do my-env -- logs + +# Specific instance logs +bosh -d my-env-cf logs router/0 + +# Recent BOSH tasks +bosh tasks --recent +bosh task --debug +``` + +### Errands + +```bash +# Run smoke tests +genesis do my-env -- run-errand smoke-tests + +# Direct BOSH errand +bosh -d my-env-cf run-errand smoke-tests +``` + +## BOSH Teams and UAA + +### Multi-Tenancy + +Configure BOSH teams in your environment: + +```yaml +params: + bosh_teams: + - name: developers + auth: + type: uaa + provider: github + permissions: + - deployment: my-env-cf + operations: ["read", "ssh"] +``` + +### Authentication + +```yaml +params: + bosh_auth: + type: uaa + uaa_url: https://uaa.example.com + client_id: genesis + client_secret: ((uaa_client_secret)) +``` + +## Cloud Config Details + +### VM Type Mapping + +Genesis maps kit VM types to cloud config: + +```yaml +# Kit requests +instance_groups: +- name: web + vm_type: small + +# Genesis prefixes for uniqueness +# Uses: acme-aws-us-east-1-prod-small +``` + +### Network Selection + +Networks are not prefixed: + +```yaml +# Environment file +params: + cf_network: cf-net + +# Cloud config +networks: +- name: cf-net # Used as-is + subnets: [...] +``` + +### Availability Zones + +```yaml +params: + availability_zones: + - z1 + - z2 + - z3 +``` + +## Troubleshooting + +### Deployment Not Found + +Check: +- Correct BOSH director targeted +- Deployment name includes kit suffix +- Environment was actually deployed + +### Cloud Config Issues + +```bash +# View current cloud config +bosh cloud-config + +# Check for prefixed types +bosh cloud-config | grep my-env + +# Update cloud config +genesis do my-env -- cloud-config +``` + +### Version Mismatches + +```bash +# Check BOSH version +bosh env + +# Genesis expects BOSH v2 CLI +genesis -v +``` + +### Authentication Problems + +```bash +# Re-authenticate +genesis do my-env -- login + +# Check credentials in Vault +safe get secret/exodus/my-env-bosh/bosh +``` + +## Best Practices + +### 1. Use Genesis Commands + +Prefer Genesis commands over direct BOSH: +- Handles authentication +- Maintains consistency +- Includes Genesis features + +### 2. Understand the Mapping + +Know how Genesis names map to BOSH: +- Helps with debugging +- Enables manual intervention +- Useful for monitoring + +### 3. Document Overrides + +When overriding BOSH director: +```yaml +genesis: + # Document why this override exists + bosh_env: shared-mgmt # Using shared director for cost savings +``` + +### 4. Monitor Both Layers + +Monitor at both levels: +- Genesis operations (deployments, rotations) +- BOSH health (VMs, disks, compilations) + +### 5. Backup Considerations + +```bash +# Backup BOSH director state +genesis do my-bosh -- bbr backup + +# Includes: +# - Deployment manifests +# - Cloud configs +# - BOSH database +``` + +## Integration Examples + +### CI/CD Pipeline + +```yaml +# Concourse task +- name: deploy-cf + plan: + - task: genesis-deploy + config: + run: + path: genesis + args: ["deploy", "my-env", "--yes"] +``` + +### Monitoring Integration + +```bash +# Prometheus BOSH exporter config +jobs: +- name: bosh_exporter + properties: + bosh: + url: ((exodus.my-env-bosh.bosh.url)) + ca_cert: ((exodus.my-env-bosh.bosh.ca_cert)) + username: ((exodus.my-env-bosh.bosh.admin_username)) + password: ((exodus.my-env-bosh.bosh.admin_password)) +``` + +### Custom Scripts + +```bash +#!/bin/bash +# Scale CF cells + +ENV="acme-aws-us-east-1-prod" +DEPLOYMENT="${ENV}-cf" + +# Login to BOSH +genesis do $ENV -- login + +# Scale cells +bosh -d $DEPLOYMENT scale diego-cell=10 +``` + +Understanding BOSH integration enables you to: +- Debug deployment issues +- Perform manual operations +- Integrate with existing tools +- Build custom automation \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/configuration-merging.md b/lib/Genesis/Help/Topics/10-environments/configuration-merging.md new file mode 100644 index 00000000..4af7512a --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/configuration-merging.md @@ -0,0 +1,413 @@ +# Configuration Merging + +Genesis uses a powerful hierarchical merging system to manage configuration across environments. This guide explains how configurations are merged, override rules, and best practices. + +## How Merging Works + +Genesis merges configuration files in a specific order, with later values overriding earlier ones. This allows you to define common settings once and override them where needed. + +### Merge Order + +For an environment named `acme-aws-us-east-1-prod.yml`, Genesis merges in this order: + +1. Kit base manifest +2. Kit features (ops files) +3. `acme.yml` +4. `acme-aws.yml` +5. `acme-aws-us.yml` +6. `acme-aws-us-east.yml` +7. `acme-aws-us-east-1.yml` +8. `acme-aws-us-east-1-prod.yml` +9. Any files from `genesis.inherits` + +### Basic Override Example + +```yaml +# acme.yml +params: + company: ACME Corp + instances: 1 + enable_monitoring: true + +# acme-aws.yml +params: + cloud: aws + instances: 2 # Overrides acme.yml + +# acme-aws-us-east-1-prod.yml +params: + env: production + instances: 5 # Overrides both previous files +``` + +Final result: +```yaml +params: + company: ACME Corp # From acme.yml + enable_monitoring: true # From acme.yml + cloud: aws # From acme-aws.yml + env: production # From acme-aws-us-east-1-prod.yml + instances: 5 # From acme-aws-us-east-1-prod.yml (last wins) +``` + +## Merge Types + +### Simple Values + +Later values completely replace earlier ones: + +```yaml +# parent.yml +params: + port: 8080 + +# child.yml +params: + port: 443 # Replaces 8080 +``` + +### Arrays + +Arrays are replaced, not merged: + +```yaml +# parent.yml +params: + availability_zones: + - us-east-1a + - us-east-1b + +# child.yml +params: + availability_zones: + - us-east-1c # Only us-east-1c remains +``` + +To append to arrays, you must include all values: + +```yaml +# child.yml +params: + availability_zones: + - us-east-1a # Include original values + - us-east-1b + - us-east-1c # Add new value +``` + +### Maps (Hashes) + +Maps are deep-merged: + +```yaml +# parent.yml +params: + database: + host: localhost + port: 5432 + pool: 10 + +# child.yml +params: + database: + host: prod-db.example.com # Overrides + ssl: true # Adds new key + # port: 5432 (inherited) + # pool: 10 (inherited) +``` + +Result: +```yaml +params: + database: + host: prod-db.example.com + port: 5432 + pool: 10 + ssl: true +``` + +## Special Merge Keys + +### The `(( merge ))` Operator + +While Genesis doesn't use Spruce operators during environment file merging, understanding this pattern helps when working with ops files: + +```yaml +# In ops files or kit manifests +meta: + things: (( merge )) # Indicates this should be merged +``` + +### Null Values + +Use `null` to remove inherited values: + +```yaml +# parent.yml +params: + debug_mode: true + log_level: debug + +# production.yml +params: + debug_mode: false + log_level: null # Removes this key entirely +``` + +## Complex Merging Examples + +### Network Configuration + +```yaml +# base.yml +params: + networks: + default: + dns: + - 8.8.8.8 + - 8.8.4.4 + mtu: 1500 + +# aws.yml +params: + networks: + default: + dns: + - 10.0.0.2 # Replaces public DNS + - 10.0.0.3 + type: manual + # mtu: 1500 (inherited) + +# aws-us-east-1-prod.yml +params: + networks: + default: + subnets: + - range: 10.0.1.0/24 + gateway: 10.0.1.1 + # dns inherited from aws.yml + # type inherited from aws.yml + # mtu inherited from base.yml +``` + +### Feature Flags + +```yaml +# base.yml +params: + features: + monitoring: enabled + backups: enabled + debug: disabled + +# dev.yml +params: + features: + debug: enabled # Override for dev + test_mode: enabled # Add new feature + # monitoring: enabled (inherited) + # backups: enabled (inherited) +``` + +## Using genesis.inherits + +For non-hierarchical inheritance: + +```yaml +# special-security.yml +params: + security: + require_https: true + min_tls_version: "1.2" + +# aws-us-east-1-prod.yml +genesis: + inherits: + - special-security # Merged after hierarchical files +params: + env: production +``` + +### Multiple Inherits + +```yaml +genesis: + inherits: + - base-networking # First + - security-policies # Second + - performance-tuning # Third (wins conflicts) +``` + +## Best Practices + +### 1. Design for Inheritance + +Structure your configurations to minimize overrides: + +```yaml +# Good: Use specific keys +params: + cell_instances: 3 + router_instances: 2 + +# Bad: Generic names cause conflicts +params: + instances: 3 # Which component? +``` + +### 2. Document Inheritance + +Add comments explaining inheritance: + +```yaml +# aws-us-east-1-prod.yml +params: + # Inherits from: base.yml -> aws.yml -> aws-us-east-1.yml + instances: 5 # Override: was 2 in aws.yml +``` + +### 3. Use Intermediate Files + +Create logical groupings: + +```yaml +# aws-networking.yml - Shared AWS network config +params: + networks: + default: + type: manual + dns: ["10.0.0.2"] + +# aws-security.yml - Shared AWS security +params: + security_groups: + - default + - bosh +``` + +### 4. Avoid Deep Nesting + +Flatten when possible: + +```yaml +# Good +params: + database_host: prod-db.example.com + database_port: 5432 + +# Harder to override +params: + database: + connection: + host: prod-db.example.com + port: 5432 +``` + +## Debugging Merge Issues + +### View Effective Configuration + +```bash +# See what values an environment will use +genesis describe aws-us-east-1-prod + +# View the final manifest +genesis manifest aws-us-east-1-prod +``` + +### Check Inheritance Chain + +```bash +# List all files in merge order +genesis describe aws-us-east-1-prod --show-hierarchy +``` + +### Common Issues + +#### Values Not Overriding + +Check: +- Correct key names (typos prevent overrides) +- Proper YAML indentation +- File naming follows hierarchy + +#### Unexpected Array Behavior + +Remember arrays replace entirely: +```yaml +# Wrong: Expecting append +child: + my_array: + - new_value # Old values lost! + +# Right: Include all values +child: + my_array: + - old_value_1 + - old_value_2 + - new_value +``` + +#### Missing Inherited Values + +Verify: +- Parent file exists +- No `null` assignments +- Correct merge order + +## Advanced Patterns + +### Environment-Specific Overrides + +```yaml +# base.yml +params: + log_level: (( grab params.environment_log_level || "info" )) + +# dev.yml +params: + environment_log_level: debug + +# prod.yml +params: + environment_log_level: error +``` + +### Conditional Features + +```yaml +# base.yml +params: + enable_feature_x: false + +# staging.yml +params: + enable_feature_x: true # Test in staging first +``` + +### Shared Configurations + +```yaml +# tls-config.yml +params: + tls: + certificate: | + -----BEGIN CERTIFICATE----- + ... + protocols: + - TLSv1.2 + - TLSv1.3 + +# Multiple environments inherit +genesis: + inherits: + - tls-config +``` + +## Summary + +- Genesis merges hierarchically based on environment name +- Later files override earlier files +- Simple values replace, maps deep-merge, arrays replace entirely +- Use `genesis.inherits` for non-hierarchical inclusion +- Design configurations for inheritance from the start +- Test with `genesis describe` and `genesis manifest` \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/file-structure.md b/lib/Genesis/Help/Topics/10-environments/file-structure.md new file mode 100644 index 00000000..1092ba0e --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/file-structure.md @@ -0,0 +1,383 @@ +# Environment File Structure + +Understanding how to organize your Genesis environment files is crucial for maintainable deployments. This guide covers directory layouts, file organization patterns, and best practices. + +## Basic Structure + +### Single Kit Repository +``` +my-cf-deployments/ +├── .genesis/ +│ ├── config # Repository configuration +│ ├── cache/ # Downloaded kits +│ └── kits/ # Local kit overrides +├── .gitignore +├── README.md +├── base.yml # Global defaults (optional) +├── aws.yml # AWS-specific settings +├── aws-us.yml # US region settings +├── aws-us-east-1.yml # Specific region settings +├── aws-us-east-1-dev.yml # Development environment +├── aws-us-east-1-staging.yml # Staging environment +└── aws-us-east-1-prod.yml # Production environment +``` + +### Environment File Contents + +A typical environment file contains: + +```yaml +--- +# Kit configuration +kit: + name: cf + version: 2.3.0 + features: + - haproxy + - postgres + - routing-api + +# Environment parameters +params: + # Environment identification + env: aws-us-east-1-prod + + # Infrastructure settings + availability_zones: + - us-east-1a + - us-east-1b + - us-east-1c + + # CF-specific configuration + base_domain: cf.example.com + skip_ssl_validation: false + + # Resource sizing + cell_instances: 3 + router_instances: 2 +``` + +## Multi-Kit Organization + +### Deployment Root Structure + +For organizations with multiple kits: + +``` +deployments/ # Deployment root +├── .genesis/ +│ └── config # Root configuration +├── bosh/ # BOSH directors +│ ├── .genesis/config +│ ├── aws.yml +│ ├── aws-us-east-1.yml +│ └── aws-us-west-2.yml +├── vault/ # Vault deployments +│ ├── .genesis/config +│ ├── aws.yml +│ └── aws-us-east-1.yml +├── cf/ # Cloud Foundry +│ ├── .genesis/config +│ ├── base.yml +│ ├── aws.yml +│ ├── aws-us-east-1-dev.yml +│ ├── aws-us-east-1-staging.yml +│ └── aws-us-east-1-prod.yml +└── concourse/ # Concourse CI + ├── .genesis/config + ├── aws.yml + └── aws-us-east-1.yml +``` + +### Benefits of This Structure + +1. **Clear Separation** - Each kit has its own directory +2. **Shared Settings** - Common configs at deployment root +3. **Easy Navigation** - Predictable locations +4. **Git Flexibility** - Can be one repo or many + +## Operations Files + +### Using Ops Files + +Operations files modify the base manifest during compilation: + +``` +cf-deployments/ +├── aws-us-east-1-prod.yml +└── ops/ + ├── enable-debug.yml # Debugging features + ├── scale-cells.yml # Custom scaling + └── custom-certificates.yml # Additional certs +``` + +Reference in environment file: +```yaml +kit: + features: + - enable-debug # Looks for ops/enable-debug.yml + - scale-cells +``` + +### Ops File Example + +```yaml +# ops/scale-cells.yml +- type: replace + path: /instance_groups/name=diego-cell/instances + value: 10 + +- type: replace + path: /instance_groups/name=diego-cell/vm_type + value: large +``` + +## Hierarchical Files + +### Inheritance Chain Example + +``` +deployments/cf/ +├── base.yml # Level 1: Global defaults +├── aws.yml # Level 2: AWS-wide settings +├── aws-us.yml # Level 3: US regions +├── aws-us-east-1.yml # Level 4: Specific region +└── aws-us-east-1-prod.yml # Level 5: Final environment +``` + +### What Goes Where + +#### Global Level (`base.yml`) +```yaml +params: + # Company-wide settings + company_name: ACME Corp + + # Default DNS servers + dns: + - 8.8.8.8 + - 8.8.4.4 + + # Security policies + password_policy: + min_length: 14 + require_special: true +``` + +#### Infrastructure Level (`aws.yml`) +```yaml +params: + # AWS-specific settings + cloud_provider: aws + + # AWS instance types + default_vm_type: t3.small + + # Availability zones format + availability_zone_pattern: "{region}{az}" +``` + +#### Region Level (`aws-us-east-1.yml`) +```yaml +params: + # Region configuration + region: us-east-1 + + # Regional endpoints + s3_endpoint: https://s3.us-east-1.amazonaws.com + + # Network ranges + management_network: 10.0.0.0/16 +``` + +#### Environment Level (`aws-us-east-1-prod.yml`) +```yaml +params: + # Environment specifics + env: production + + # Scaling parameters + instances: 5 + + # Environment-specific domains + system_domain: prod.cf.example.com + apps_domain: apps.example.com +``` + +## Alternative Patterns + +### By Purpose First +``` +deployments/ +├── production/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +├── staging/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +└── development/ + ├── cf/ + ├── bosh/ + └── vault/ +``` + +### By Region First +``` +deployments/ +├── us-east-1/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +├── us-west-2/ +│ ├── cf/ +│ ├── bosh/ +│ └── vault/ +└── eu-west-1/ + ├── cf/ + ├── bosh/ + └── vault/ +``` + +## Supporting Files + +### README Files + +Include documentation: +```markdown +# Cloud Foundry Deployments + +This repository contains Genesis CF deployments. + +## Environments + +- `aws-us-east-1-dev` - Development environment +- `aws-us-east-1-staging` - Staging (pre-production) +- `aws-us-east-1-prod` - Production + +## Deployment + +```bash +genesis deploy aws-us-east-1-prod +``` +``` + +### .gitignore + +Standard Genesis gitignore: +``` +# Genesis +.genesis/cache/ +.genesis/config +.genesis/manifests/ +.genesis/releases/ +.genesis/kits/ + +# Editor files +.*.sw? +*~ + +# OS files +.DS_Store +Thumbs.db + +# Temporary files +*.tmp +``` + +### CI/CD Files + +Pipeline configuration: +``` +cf-deployments/ +├── ci/ +│ ├── pipeline.yml +│ ├── scripts/ +│ │ ├── test.sh +│ │ └── deploy.sh +│ └── settings.yml +└── .concourse/ + └── secrets.yml +``` + +## Best Practices + +### 1. Consistent Naming +- Use the same pattern everywhere +- Document your conventions +- Stick to lowercase and hyphens + +### 2. Logical Grouping +- Group by kit type, not by environment +- Keep related environments together +- Use hierarchy to reduce duplication + +### 3. Version Control +```bash +# Track everything except caches +git add -A +git commit -m "Added production environment" + +# Don't track +# - .genesis/cache/ +# - .genesis/manifests/ +# - Any secrets +``` + +### 4. Documentation +- README in each kit directory +- Comment complex configurations +- Document non-obvious choices + +### 5. Secrets Management +- Never commit secrets +- Use Vault references +- Document secret requirements + +## Common Patterns + +### Development Workflow +``` +cf/ +├── dev.yml # Shared dev settings +├── john-dev.yml # Personal dev environment +├── mary-dev.yml # Personal dev environment +└── ci-dev.yml # CI test environment +``` + +### Multi-Datacenter +``` +cf/ +├── dc1.yml # Datacenter 1 base +├── dc1-prod.yml # DC1 production +├── dc1-dr.yml # DC1 disaster recovery +├── dc2.yml # Datacenter 2 base +├── dc2-prod.yml # DC2 production +└── dc2-dr.yml # DC2 disaster recovery +``` + +### Blue-Green Deployments +``` +cf/ +├── prod.yml # Shared production settings +├── prod-blue.yml # Blue environment +└── prod-green.yml # Green environment +``` + +## Troubleshooting + +### File Not Found +- Check exact filename and extension +- Verify you're in the right directory +- Ensure .yml extension is present + +### Inheritance Issues +- Verify parent files exist +- Check for typos in names +- Review hyphen placement + +### Merge Conflicts +- Use explicit keys in child files +- Override entire structures when needed +- Test with `genesis manifest` to verify \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/index.md b/lib/Genesis/Help/Topics/10-environments/index.md new file mode 100644 index 00000000..f0412fee --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/index.md @@ -0,0 +1,104 @@ +# Environment Management + +This section covers everything you need to know about Genesis environments - from naming conventions to configuration management. + +## Topics in This Section + +1. **[Naming Conventions](naming-conventions.md)** - Environment naming rules and patterns +2. **[File Structure](file-structure.md)** - Organizing environment files +3. **[Configuration Merging](configuration-merging.md)** - How hierarchical inheritance works +4. **[Match Mode](match-mode.md)** - Quick environment selection +5. **[Vault Paths](vault-paths.md)** - Secret storage conventions +6. **[BOSH Integration](bosh-integration.md)** - How environments map to BOSH +7. **[Reactions](reactions.md)** - Pre and post-deploy scripts +8. **[Best Practices](best-practices.md)** - Recommendations and patterns + +## Quick Overview + +Genesis environments are the heart of your infrastructure-as-code. Each environment represents a single deployment with its own: + +- YAML configuration file +- Hierarchical inheritance from parent configs +- Secrets stored in Vault +- BOSH deployment manifest + +### Key Concepts + +**Environment File**: A YAML file (e.g., `us-east-1-prod.yml`) that defines a deployment's configuration. + +**Hierarchical Merging**: Configurations inherit from parent files based on naming patterns: +``` +us.yml # US-wide settings +└── us-east.yml # US East settings + └── us-east-1.yml # Specific region + └── us-east-1-prod.yml # Production environment +``` + +**Match Mode**: Quick selection using patterns: +```bash +genesis deploy @prod:cf # Deploy any CF prod environment +``` + +## Common Patterns + +### Standard Naming Convention +``` +---.yml +``` + +Examples: +- `acme-aws-us-east-1-prod.yml` +- `globex-azure-westeurope-staging.yml` +- `startup-gcp-us-central1-dev.yml` + +### Directory Organization +``` +deployments/ +├── bosh/ +│ ├── acme.yml # Company-wide BOSH settings +│ ├── acme-aws.yml # AWS-specific BOSH settings +│ └── acme-aws-us-east-1.yml # Region-specific BOSH +├── vault/ +│ └── acme-aws-us-east-1.yml # Vault deployment +└── cf/ + ├── acme.yml # Company-wide CF settings + ├── acme-prod.yml # Production CF settings + └── acme-aws-us-east-1-prod.yml # Full CF deployment +``` + +## Getting Started + +1. **Learn the naming rules** in [Naming Conventions](naming-conventions.md) +2. **Understand inheritance** with [Configuration Merging](configuration-merging.md) +3. **Organize your files** using [File Structure](file-structure.md) +4. **Speed up workflows** with [Match Mode](match-mode.md) + +## Common Tasks + +### Create a New Environment +```bash +genesis new us-east-1-prod +``` + +### View Environment Hierarchy +```bash +genesis describe us-east-1-prod +``` + +### Check What Will Be Deployed +```bash +genesis manifest us-east-1-prod +``` + +### Deploy an Environment +```bash +genesis deploy us-east-1-prod +``` + +## Tips + +- Use consistent naming across all deployments +- Leverage hierarchy to avoid repetition +- Document your naming conventions +- Test changes in lower environments first +- Use match mode for faster operations \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/match-mode.md b/lib/Genesis/Help/Topics/10-environments/match-mode.md new file mode 100644 index 00000000..a3e497eb --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/match-mode.md @@ -0,0 +1,362 @@ +# Match Mode + +Match mode provides a powerful way to quickly reference Genesis environments using glob-style patterns instead of typing full environment names. This is especially useful with long, hierarchical environment names. + +## Overview + +Instead of typing: +```bash +genesis deploy acme-aws-us-east-1-production +``` + +You can use: +```bash +genesis deploy @prod:cf +``` + +The `@` prefix activates match mode, allowing pattern matching against environment names. + +## Enabling Match Mode + +Match mode requires configuring deployment roots in your `~/.genesis/config`: + +```yaml +--- +deployment_roots: + - ~/deployments # Simple path + - work: ~/work/deployments # Labeled path + - prod: /opt/genesis/prod # Production deployments +``` + +Without deployment roots configured, match mode is not available. + +## Match Mode Syntax + +### Basic Pattern +``` +@: +``` + +- `@` - Activates match mode +- `` - Glob pattern to match environment names +- `:` - Kit type (optional but recommended) + +### Examples + +```bash +# Match any production CF environment +genesis deploy @prod:cf + +# Match us-east production +genesis deploy @*east*prod:cf + +# Match anything in us-west-2 +genesis deploy @*west-2*:bosh + +# Match dev environments +genesis deploy @*dev:vault +``` + +## Pattern Matching + +### Wildcards + +- `*` - Matches any characters +- `?` - Matches single character + +```bash +@prod # Matches: prod, production, acme-prod +@*-prod # Matches: us-east-1-prod, aws-prod +@us-*-1-* # Matches: us-east-1-dev, us-west-1-prod +@us-????-1-prod # Matches: us-east-1-prod, us-west-1-prod +``` + +### Case Sensitivity + +Matches are case-sensitive: +```bash +@prod # Won't match: Prod, PROD +``` + +## Interactive Selection + +When multiple environments match, Genesis presents a menu: + +```bash +$ genesis deploy @*:cf + +Multiple environment files found matching @*:cf: + + 📁 Deployment Root 'work': ~/work/deployments + 1) cf/acme-aws-us-east-1-dev (default) + 2) cf/acme-aws-us-east-1-staging + 3) cf/acme-aws-us-east-1-prod + 4) cf/acme-aws-us-west-2-prod + + 5) None of these - cancel + +Select the desired environment file > +``` + +## Deployment Types + +The `:` suffix specifies which kit type to search: + +```bash +@prod:cf # Cloud Foundry deployments +@prod:bosh # BOSH directors +@prod:vault # Vault deployments +@prod:concourse # Concourse deployments +``` + +### Benefits of Specifying Type + +1. **Faster** - Only searches relevant directories +2. **Accurate** - Avoids matching similarly named environments +3. **Clear** - Shows intent in commands + +## Working with Multiple Roots + +With multiple deployment roots: + +```yaml +deployment_roots: + - personal: ~/my-deployments + - work: ~/work/deployments + - client: ~/client/infrastructure +``` + +Matches search all roots: + +```bash +$ genesis list @prod:* + +personal: + bosh/home-prod + vault/personal-prod + +work: + cf/acme-aws-us-east-1-prod + cf/acme-aws-us-west-2-prod + +client: + cf/bigco-azure-eastus-prod + concourse/bigco-ci-prod +``` + +## Common Patterns + +### By Environment Stage + +```bash +# Development environments +genesis deploy @*dev*:cf +genesis check @*development*:vault + +# Staging environments +genesis manifest @*staging*:cf +genesis rotate-secrets @*stage*:bosh + +# Production environments +genesis deploy @*prod*:cf +genesis describe @*production*:vault +``` + +### By Region + +```bash +# US East environments +genesis deploy @*us-east*:cf +genesis list @*east-1*:* + +# Europe environments +genesis check @*eu-*:bosh +genesis manifest @*europe*:vault + +# All AWS environments +genesis list @*aws*:* +``` + +### By Organization + +```bash +# ACME environments +genesis deploy @acme*:cf +genesis list @acme-*:* + +# Department-specific +genesis deploy @*finance*:vault +genesis check @*engineering*:cf +``` + +## Advanced Usage + +### Combining with Other Commands + +Match mode works with most Genesis commands: + +```bash +# Deployment operations +genesis deploy @prod:cf +genesis check @staging:vault +genesis manifest @dev:bosh + +# Information commands +genesis describe @prod:cf +genesis list @*:vault +genesis info @dev:* + +# Maintenance commands +genesis rotate-secrets @prod:vault +genesis do @staging:cf -- smoke-tests + +# Pipeline operations +genesis repipe @*:cf +``` + +### Scripting with Match Mode + +For scripts, use exact matches when possible: + +```bash +#!/bin/bash +# Deploy all production CF environments + +for env in $(genesis list @*prod:cf --json | jq -r '.[].name'); do + echo "Deploying $env..." + genesis deploy "$env" +done +``` + +### Unique Patterns + +Design patterns that uniquely identify environments: + +```bash +# Too broad +@prod # Matches: prod, production, non-prod + +# More specific +@*-prod # Matches: us-east-1-prod (not non-prod) +@prod:cf # Only CF production environments +``` + +## Best Practices + +### 1. Use Type Suffixes + +Always include the kit type for clarity: +```bash +# Good +genesis deploy @prod:cf + +# Less clear +genesis deploy @prod +``` + +### 2. Test Patterns First + +Use `list` to verify your pattern: +```bash +# Check what matches before deploying +genesis list @*west*:cf +genesis deploy @*west*:cf +``` + +### 3. Be Specific in Production + +For production operations, use specific patterns: +```bash +# Good - very specific +genesis deploy @acme-aws-us-east-1-prod:cf + +# Risky - might match unexpected environments +genesis deploy @prod:cf +``` + +### 4. Document Common Patterns + +Keep a reference of useful patterns: +```markdown +## Common Match Patterns + +- `@*dev*:cf` - All CF dev environments +- `@*-prod:vault` - All production Vaults +- `@acme-*:*` - All ACME environments +- `@*us-east-1*:bosh` - US East 1 BOSH directors +``` + +## Troubleshooting + +### No Matches Found + +Check: +- Deployment roots are configured +- Pattern is correct +- Environment files exist +- Kit type is correct + +### Too Many Matches + +Make pattern more specific: +```bash +# Too broad +@*:cf + +# Better +@*prod:cf +@*us-east*prod:cf +``` + +### Match Mode Not Working + +Verify deployment roots: +```bash +# Check configuration +cat ~/.genesis/config + +# Should include: +deployment_roots: + - /path/to/deployments +``` + +### Wrong Environment Selected + +- Double-check the selection number +- Use more specific patterns +- Consider using full environment name + +## Examples + +### Quick Deployment Check +```bash +# Check all production environments before deploying +genesis check @*prod:cf +genesis check @*prod:vault +genesis check @*prod:bosh +``` + +### Regional Operations +```bash +# Rotate secrets for all US East production +genesis rotate-secrets @*us-east*prod:cf +genesis rotate-secrets @*us-east*prod:vault +``` + +### Development Workflow +```bash +# Deploy to your personal dev environment +genesis deploy @john-dev:cf + +# Check all team dev environments +genesis list @*-dev:cf +``` + +### Disaster Recovery +```bash +# Quick DR environment access +genesis do @*-dr:vault -- unseal +genesis deploy @*-dr:cf +``` + +Match mode significantly speeds up Genesis operations, especially in environments with many deployments and long naming conventions. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/naming-conventions.md b/lib/Genesis/Help/Topics/10-environments/naming-conventions.md new file mode 100644 index 00000000..f474b2bb --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/naming-conventions.md @@ -0,0 +1,273 @@ +# Environment Naming Conventions + +Genesis uses environment names to automatically build configuration hierarchies, determine BOSH deployments, and organize secrets in Vault. Understanding these conventions is crucial for effective Genesis usage. + +## Naming Rules + +### Valid Characters and Format + +Environment filenames must follow these rules: + +- **Extension**: Must end with `.yml` +- **Characters**: Only lowercase letters, numbers, underscores, and hyphens +- **Start**: Must begin with a letter +- **End**: Cannot end with a hyphen +- **Hyphens**: No consecutive hyphens (`--`) + +### Valid Examples +``` +env1.yml +us-east-1-prod.yml +acme_aws_us_east_1_prod.yml +my-really-long-hyphenated-name.yml +``` + +### Invalid Examples +``` +-prod.yml # Starts with hyphen +prod-.yml # Ends with hyphen +prod--east.yml # Consecutive hyphens +PROD.yml # Uppercase letters +prod@east.yml # Invalid character (@) +``` + +## Hierarchical Structure + +Genesis uses hyphens to create a configuration hierarchy. Each hyphen-separated segment represents a level that can have its own configuration file. + +### How It Works + +For an environment named `acme-aws-us-east-1-prod.yml`, Genesis automatically looks for and merges these files in order: + +1. `acme.yml` - Organization level +2. `acme-aws.yml` - Infrastructure level +3. `acme-aws-us.yml` - Country/region level +4. `acme-aws-us-east.yml` - Region level +5. `acme-aws-us-east-1.yml` - Availability zone level +6. `acme-aws-us-east-1-prod.yml` - Environment level + +Each level inherits from the previous, with later values overriding earlier ones. + +### Common Naming Patterns + +#### Organization-First Pattern +``` +--- + +Examples: +- acme-aws-us-east-1-prod +- acme-azure-westeurope-staging +- acme-vsphere-dc1-dev +``` + +#### Infrastructure-First Pattern +``` +--- + +Examples: +- aws-us-east-1-acme-prod +- gcp-us-central1-startup-dev +``` + +#### Purpose-Last Pattern (Recommended) +``` +-- + +Examples: +- acme-aws-prod +- startup-onprem-datacenter1-staging +- enterprise-cloud-region2-zone-a-dev +``` + +## Configuration Inheritance + +### Example Hierarchy + +Given these files: +```yaml +# acme.yml +params: + company: ACME Corp + dns: + - 10.0.0.1 + - 10.0.0.2 + +# acme-aws.yml +params: + cloud: aws + region: us-east-1 + +# acme-aws-us-east-1.yml +params: + availability_zone: us-east-1a + +# acme-aws-us-east-1-prod.yml +params: + env: production + instances: 3 +``` + +The final configuration for `acme-aws-us-east-1-prod` includes all settings: +```yaml +params: + company: ACME Corp + dns: + - 10.0.0.1 + - 10.0.0.2 + cloud: aws + region: us-east-1 + availability_zone: us-east-1a + env: production + instances: 3 +``` + +### Override Behavior + +Later files override earlier ones: +```yaml +# acme.yml +params: + instances: 1 + +# acme-aws-us-east-1-prod.yml +params: + instances: 3 # This wins +``` + +## BOSH Deployment Names + +Genesis creates BOSH deployment names using the pattern: +``` +- +``` + +Examples: +- Environment: `acme-aws-us-east-1-prod.yml` +- Kit: `cf-genesis-kit` +- BOSH deployment: `acme-aws-us-east-1-prod-cf` + +## Vault Path Structure + +### Secrets Path + +Secrets are stored with the environment name split into segments: +``` +/secret/// + +Example: +Environment: aws-us-east-1-prod.yml +Kit: cf +Path: /secret/aws/us/east/1/prod/cf/ +``` + +### Exodus Path + +Exodus data uses the full environment name: +``` +/secret/exodus// + +Example: +Environment: aws-us-east-1-prod.yml +Kit: cf +Path: /secret/exodus/aws-us-east-1-prod/cf +``` + +## Custom Paths + +### Overriding Secrets Path +```yaml +genesis: + secrets_mount: custom-secrets # default: "secret" + secrets_slug: prod-aws # default: split name +``` + +### Overriding Exodus Path +```yaml +genesis: + exodus_mount: custom-exodus # default: "/exodus" + exodus_slug: cf-production # default: full name +``` + +## Special Cases + +### BOSH Directors + +BOSH directors cannot deploy themselves, so use: +```yaml +genesis: + env: aws-us-east-1-bosh + bosh_env: aws-us-east-1-proto # Different director +``` + +### Non-Hierarchical Inheritance + +Use `genesis.inherits` for custom inheritance: +```yaml +genesis: + inherits: + - base-config + - regional-overrides + - security-policies +``` + +## Best Practices + +1. **Be Consistent** - Use the same pattern across all environments +2. **Purpose Last** - Put environment purpose (dev/staging/prod) at the end +3. **Meaningful Segments** - Each segment should represent a logical grouping +4. **Document Your Schema** - Keep a README explaining your naming convention +5. **Avoid Over-Nesting** - 4-6 segments is usually sufficient + +## Examples by Use Case + +### Multi-Region AWS +``` +acme-aws-us-east-1-prod.yml +acme-aws-us-west-2-prod.yml +acme-aws-eu-west-1-prod.yml +``` + +### Multi-Cloud +``` +startup-aws-us-east-1-prod.yml +startup-gcp-us-central1-prod.yml +startup-azure-eastus-prod.yml +``` + +### Development Stages +``` +app-cloud-region-dev.yml +app-cloud-region-staging.yml +app-cloud-region-prod.yml +``` + +### By Department +``` +acme-finance-aws-prod.yml +acme-hr-aws-prod.yml +acme-engineering-aws-prod.yml +``` + +## Troubleshooting + +### Environment Not Found + +Check: +- File has `.yml` extension +- Using exact name (unless using match mode) +- In correct directory + +### Inheritance Not Working + +Verify: +- Parent files exist +- Names follow hyphen hierarchy +- No typos in filenames + +### Vault Paths Too Long + +Use `secrets_slug` to shorten: +```yaml +genesis: + secrets_slug: prod-east # Instead of very/long/path/segments +``` \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/reactions.md b/lib/Genesis/Help/Topics/10-environments/reactions.md new file mode 100644 index 00000000..02cd9923 --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/reactions.md @@ -0,0 +1,399 @@ +# Reactions + +Reactions allow you to run custom scripts before and after deployments on a per-environment basis. This enables environment-specific automation like maintenance notifications, integration updates, or custom validations. + +## Overview + +Reactions are scripts that execute at specific points in the deployment lifecycle: +- **Pre-deploy**: Before the deployment starts +- **Post-deploy**: After the deployment completes (or fails) + +## Configuration + +Add reactions to your environment file under the `genesis.reactions` key: + +```yaml +genesis: + reactions: + pre-deploy: + - script: put-up-maintenance-page + - script: update-jira + args: ['PROD-123', 'Deploying CF'] + post-deploy: + - addon: run-smoke-tests + - script: remove-maintenance-page + - script: notify-slack + args: ['#deployments', 'CF Production deployed'] +``` + +## Script Location + +Scripts must be placed in the `bin/` directory at the repository root: + +``` +cf-deployments/ +├── bin/ +│ ├── put-up-maintenance-page +│ ├── remove-maintenance-page +│ ├── update-jira +│ └── notify-slack +├── base.yml +└── aws-us-east-1-prod.yml +``` + +Scripts are automatically included in pipeline caches and made available during deployment. + +## Script Arguments + +### Static Arguments + +Pass fixed arguments to scripts: + +```yaml +reactions: + pre-deploy: + - script: notify-team + args: ['production', 'cf', 'starting'] +``` + +### Environment Variables + +Use environment variables in arguments: + +```yaml +reactions: + post-deploy: + - script: update-dashboard + args: ['$GENESIS_ENVIRONMENT', '$DEPLOYMENT_STATUS'] +``` + +## Available Environment Variables + +Scripts have access to these environment variables: + +### Always Available + +- `GENESIS_ENVIRONMENT` - Current environment name +- `GENESIS_KIT_NAME` - Kit being deployed +- `GENESIS_KIT_VERSION` - Kit version +- `GENESIS_VAULT_PREFIX` - Vault path prefix +- `GENESIS_MANIFEST_FILE` - Path to the full manifest +- `GENESIS_BOSHVARS_FILE` - Path to BOSH variables file +- `GENESIS_DEPLOY_OPTIONS` - JSON of deployment options +- `GENESIS_DEPLOY_DRYRUN` - `true` if dry-run, `false` otherwise + +### Pre-deploy Only + +- `GENESIS_PREDEPLOY_DATAFILE` - Data from pre-deploy hook + +### Post-deploy Only + +- `GENESIS_DEPLOY_RC` - Deployment return code (0=success, 1=failure) + +## Script Examples + +### Maintenance Page Script + +```bash +#!/bin/bash +# bin/put-up-maintenance-page + +set -e + +ENVIRONMENT="${GENESIS_ENVIRONMENT}" +MAINTENANCE_BUCKET="s3://maintenance-pages" + +# Generate maintenance page +cat > /tmp/maintenance.html < + +Maintenance + +

System Maintenance

+

We're updating ${ENVIRONMENT}. Back soon!

+ + +EOF + +# Upload to CDN +aws s3 cp /tmp/maintenance.html "$MAINTENANCE_BUCKET/${ENVIRONMENT}.html" + +# Update load balancer +aws elb configure-health-check \ + --load-balancer-name "${ENVIRONMENT}-lb" \ + --health-check Target=HTTP:80/maintenance.html + +echo "Maintenance page activated for ${ENVIRONMENT}" +``` + +### Jira Integration + +```bash +#!/bin/bash +# bin/update-jira + +set -e + +TICKET_ID="$1" +COMMENT="$2" +JIRA_URL="https://jira.example.com" + +# Add deployment comment +curl -X POST \ + -H "Authorization: Bearer $JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + "$JIRA_URL/rest/api/2/issue/$TICKET_ID/comment" \ + -d "{\"body\": \"Deployment: $COMMENT\"}" + +# Transition ticket if successful +if [ "$GENESIS_DEPLOY_RC" = "0" ]; then + curl -X POST \ + -H "Authorization: Bearer $JIRA_API_TOKEN" \ + "$JIRA_URL/rest/api/2/issue/$TICKET_ID/transitions" \ + -d '{"transition": {"id": "31"}}' # Deploy Complete +fi +``` + +### Slack Notification + +```bash +#!/bin/bash +# bin/notify-slack + +CHANNEL="$1" +MESSAGE="$2" +WEBHOOK_URL="$SLACK_WEBHOOK_URL" + +STATUS="success" +COLOR="good" + +if [ "$GENESIS_DEPLOY_RC" = "1" ]; then + STATUS="failed" + COLOR="danger" +fi + +curl -X POST "$WEBHOOK_URL" \ + -H "Content-Type: application/json" \ + -d @- < -- run-smoke-tests +genesis do -- update-dns +``` + +## Advanced Patterns + +### Conditional Execution + +```bash +#!/bin/bash +# Only run in production + +if [[ "$GENESIS_ENVIRONMENT" == *-prod ]]; then + echo "Running production-only task..." + # Production logic here +fi +``` + +### Using Manifest Data + +```bash +#!/bin/bash +# Extract data from manifest + +# Get instance count +INSTANCES=$(spruce json "$GENESIS_MANIFEST_FILE" | \ + jq '.instance_groups[] | select(.name=="web") | .instances') + +# Alert if scaling up significantly +if [ "$INSTANCES" -gt 10 ]; then + send-alert "Scaling to $INSTANCES instances!" +fi +``` + +### Error Handling + +```bash +#!/bin/bash +# Handle deployment failures + +if [ "$GENESIS_DEPLOY_RC" != "0" ]; then + # Rollback actions + restore-database-snapshot + clear-cache + + # Alert on-call + pagerduty-alert "Deployment failed for $GENESIS_ENVIRONMENT" + + exit 1 +fi +``` + +## Best Practices + +### 1. Make Scripts Idempotent + +Scripts should handle being run multiple times: + +```bash +# Good - checks before acting +if ! maintenance-page-exists; then + create-maintenance-page +fi + +# Bad - assumes state +rm /var/www/index.html # Fails if already removed +``` + +### 2. Handle Failures Gracefully + +```bash +#!/bin/bash +set -e # Exit on error + +# Cleanup function +cleanup() { + echo "Cleaning up..." + remove-temp-files +} +trap cleanup EXIT + +# Main logic +do-deployment-task || { + echo "Task failed, but continuing deployment" + exit 0 # Don't fail the deployment +} +``` + +### 3. Log Appropriately + +```bash +#!/bin/bash +LOG_FILE="/var/log/genesis-reactions.log" + +log() { + echo "[$(date)] $GENESIS_ENVIRONMENT: $1" | tee -a "$LOG_FILE" +} + +log "Starting pre-deploy reaction" +# ... script logic ... +log "Pre-deploy reaction complete" +``` + +### 4. Use Version Control + +Always commit reaction scripts: + +```bash +git add bin/ +git commit -m "Add deployment reaction scripts" +``` + +### 5. Test Scripts Locally + +```bash +# Test with mock environment +export GENESIS_ENVIRONMENT="test-env" +export GENESIS_DEPLOY_RC="0" +./bin/notify-slack "#test" "Test message" +``` + +## Common Use Cases + +### Database Migrations + +```yaml +reactions: + pre-deploy: + - script: backup-database + - script: run-migrations +``` + +### Cache Management + +```yaml +reactions: + post-deploy: + - script: clear-cdn-cache + - script: warm-application-cache +``` + +### External Service Updates + +```yaml +reactions: + post-deploy: + - script: update-load-balancer + - script: register-service-discovery + - script: update-monitoring +``` + +### Compliance and Auditing + +```yaml +reactions: + pre-deploy: + - script: log-deployment-start + args: ['audit-system'] + post-deploy: + - script: log-deployment-complete + args: ['audit-system', '$GENESIS_DEPLOY_RC'] +``` + +## Troubleshooting + +### Script Not Found + +Ensure: +- Script is in `bin/` directory +- Script has execute permissions: `chmod +x bin/script-name` +- Script name matches exactly (case-sensitive) + +### Environment Variables Not Set + +Check: +- Using correct variable names +- Variables are exported in script +- Not overwriting Genesis variables + +### Script Failures + +- Check script logs +- Run script manually to test +- Verify all dependencies available +- Check script exit codes + +### Pipeline Issues + +For CI/CD pipelines: +- Ensure bin/ directory is included +- Scripts are committed to Git +- Pipeline has necessary credentials + +Reactions provide powerful automation capabilities while maintaining environment-specific flexibility. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/10-environments/vault-paths.md b/lib/Genesis/Help/Topics/10-environments/vault-paths.md new file mode 100644 index 00000000..939fc78c --- /dev/null +++ b/lib/Genesis/Help/Topics/10-environments/vault-paths.md @@ -0,0 +1,361 @@ +# Vault Path Structure + +Genesis automatically organizes secrets in Vault using a predictable path structure based on environment names. Understanding these paths is essential for debugging, manual secret management, and integration with other tools. + +## Default Path Structure + +### Secrets Path + +Genesis stores deployment secrets using a hierarchical path that mirrors your environment naming: + +``` +/secret/// + +Example: +Environment: acme-aws-us-east-1-prod.yml +Kit: cf +Vault path: /secret/acme/aws/us/east/1/prod/cf/ +``` + +The environment name is split on hyphens, with each segment becoming a directory level in Vault. + +### Exodus Path + +Exodus data (deployment outputs shared with other deployments) uses a different structure: + +``` +/secret/exodus// + +Example: +Environment: acme-aws-us-east-1-prod.yml +Kit: bosh +Vault path: /secret/exodus/acme-aws-us-east-1-prod/bosh +``` + +Exodus paths keep the environment name intact rather than splitting it. + +## Path Components + +### Mount Points + +- **Secrets Mount**: `/secret` (default) +- **Exodus Mount**: `/secret/exodus` (default) + +### Environment Segments + +Environment name split on hyphens: +- `acme-aws-us-east-1-prod` → `acme/aws/us/east/1/prod` +- `company-vsphere-dc1-dev` → `company/vsphere/dc1/dev` + +### Kit Type + +The deployment type (kit name without `-genesis-kit`): +- `cf-genesis-kit` → `cf` +- `bosh-genesis-kit` → `bosh` +- `vault-genesis-kit` → `vault` + +## Secret Organization + +### Common Secret Patterns + +Within each deployment's Vault path: + +``` +/secret/acme/aws/us/east/1/prod/cf/ +├── admin_password # User credentials +├── app_domain_cert # X.509 certificates +│ ├── cert +│ ├── key +│ └── ca +├── bbs_encryption_key # Encryption keys +├── db/ # Database credentials +│ ├── password +│ └── username +└── jwt_signing_key # JWT keys + ├── private + └── public +``` + +### Secret Types + +Genesis automatically generates various secret types: + +#### Passwords +``` +/secret/.../admin_password +/secret/.../db/password +/secret/.../nats_password +``` + +#### SSH Keys +``` +/secret/.../jumpbox_ssh +├── private +└── public +``` + +#### X.509 Certificates +``` +/secret/.../router_ssl +├── cert +├── key +├── ca +└── combined # Sometimes includes cert+key +``` + +#### RSA Keys +``` +/secret/.../jwt_signing_key +├── private +└── public +``` + +## Exodus Data + +### What Is Exodus? + +Exodus data provides deployment information to other deployments: + +```yaml +# BOSH director exodus +/secret/exodus/acme-aws-us-east-1-bosh/bosh +├── url # https://10.0.0.6:25555 +├── ca_cert # BOSH director CA +├── admin_username # admin +└── admin_password # generated password +``` + +### Using Exodus Data + +Other deployments reference exodus data: + +```yaml +# In CF deployment +params: + bosh: acme-aws-us-east-1-bosh # References exodus data +``` + +Genesis automatically retrieves: +- BOSH URL +- CA certificate +- Admin credentials + +## Custom Paths + +### Overriding Secrets Paths + +In your environment file: + +```yaml +genesis: + # Change the mount point + secrets_mount: secret/genesis # Default: secret + + # Change the path structure + secrets_slug: production/cf # Default: split by hyphens +``` + +Results in: `/secret/genesis/production/cf/` + +### Overriding Exodus Paths + +```yaml +genesis: + # Custom exodus mount + exodus_mount: secret/shared # Default: /exodus + + # Custom exodus slug + exodus_slug: cf-production # Default: full environment name +``` + +Results in: `/secret/shared/cf-production/cf` + +### When to Customize + +Consider custom paths when: +- Organization Vault policies restrict paths +- Migrating from another system +- Integrating with existing Vault structure +- Path segments exceed Vault limits + +## Vault Operations + +### Viewing Secrets + +```bash +# List all secrets for an environment +safe tree secret/acme/aws/us/east/1/prod/cf + +# View specific secret +safe get secret/acme/aws/us/east/1/prod/cf/admin_password + +# Export all secrets +safe export secret/acme/aws/us/east/1/prod/cf +``` + +### Manual Secret Management + +```bash +# Set a specific secret +safe set secret/acme/aws/us/east/1/prod/cf/custom_key value=mysecret + +# Generate a new password +safe gen secret/acme/aws/us/east/1/prod/cf/new_password + +# Create SSH key +safe ssh secret/acme/aws/us/east/1/prod/cf/ssh_key +``` + +### Copying Secrets + +```bash +# Copy between environments +safe cp \ + secret/acme/aws/us/east/1/dev/cf \ + secret/acme/aws/us/east/1/staging/cf +``` + +## Path Discovery + +### Finding Paths + +```bash +# Show environment's Vault paths +genesis describe acme-aws-us-east-1-prod + +# In deployment output +Secrets Path: secret/acme/aws/us/east/1/prod/cf +Exodus Path: secret/exodus/acme-aws-us-east-1-prod/cf +``` + +### Debugging Path Issues + +Check for: +1. Correct environment name +2. Proper hyphen placement +3. Kit type identification +4. Mount point permissions + +## Best Practices + +### 1. Use Default Paths + +Stick to defaults unless necessary: +- Predictable for team members +- Easier troubleshooting +- Better tool integration + +### 2. Document Custom Paths + +If using custom paths: +```yaml +# Document WHY in environment file +genesis: + secrets_mount: restricted/project-x # Required by security policy XYZ +``` + +### 3. Consistent Naming + +Keep environment names consistent: +- Easier path prediction +- Simpler secret management +- Clearer organization + +### 4. Access Control + +Set Vault policies by path: +```hcl +# Dev team access to dev environments +path "secret/acme/*/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Read-only prod access +path "secret/acme/*/prod/*" { + capabilities = ["read", "list"] +} +``` + +### 5. Backup Considerations + +When backing up: +```bash +# Backup entire environment +safe export secret/acme/aws/us/east/1/prod/cf > cf-prod-backup.json + +# Include exodus data +safe export secret/exodus/acme-aws-us-east-1-prod/cf > cf-prod-exodus.json +``` + +## Common Issues + +### Secrets Not Found + +Check: +- Environment name spelling +- Hyphen placement +- Kit type detection +- Vault authentication + +### Path Too Long + +Vault has segment limits. Solutions: +1. Shorten environment names +2. Use `secrets_slug` override +3. Reduce hierarchy depth + +### Permission Denied + +Verify: +- Vault token permissions +- Policy allows path access +- Mount point exists + +### Exodus Data Missing + +Ensure: +- Source deployment succeeded +- Exodus path is correct +- No custom path overrides conflict + +## Integration Examples + +### CI/CD Integration + +```yaml +# Concourse pipeline +- name: get-cf-secrets + plan: + - task: export-secrets + config: + run: + path: safe + args: + - export + - secret/acme/aws/us/east/1/prod/cf +``` + +### Terraform Integration + +```hcl +# Read Genesis secrets in Terraform +data "vault_generic_secret" "cf_admin" { + path = "secret/acme/aws/us/east/1/prod/cf/admin_password" +} +``` + +### Monitoring Integration + +```bash +# Script to check certificate expiration +for cert in $(safe find secret | grep cert$); do + expiry=$(safe get $cert | openssl x509 -noout -dates) + echo "$cert: $expiry" +done +``` + +Understanding Vault paths helps you: +- Debug secret issues +- Integrate with other tools +- Implement access controls +- Manage secrets manually when needed \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/.keep b/lib/Genesis/Help/Topics/30-secrets-management/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/30-secrets-management/best-practices.md b/lib/Genesis/Help/Topics/30-secrets-management/best-practices.md new file mode 100644 index 00000000..f0e0e558 --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/best-practices.md @@ -0,0 +1,446 @@ +# Secrets Management Best Practices + +This guide provides security best practices for managing secrets in Genesis deployments. Following these practices helps maintain a strong security posture. + +## General Principles + +### 1. Never Commit Secrets + +**Never** store secrets in version control: + +```yaml +# BAD - Hardcoded secret +params: + admin_password: "SuperSecret123!" # NEVER DO THIS + +# GOOD - Reference from Vault +params: + admin_password: ((vault "secret/path:password")) +``` + +Use `.gitignore`: +```gitignore +# Ignore all potential secret files +*-secrets.yml +*.key +*.pem +*.crt +credentials.json +.env +``` + +### 2. Use Strong Secrets + +Configure appropriate secret strength: + +```yaml +# Weak - Too short +credentials: + base: + password: random 8 # BAD + +# Strong - Sufficient length and complexity +credentials: + base: + password: random 32 # GOOD + api_key: "random 40 fmt base64" # BETTER +``` + +### 3. Rotate Regularly + +Establish rotation schedules: + +| Secret Type | Rotation Frequency | Notes | +|------------|-------------------|-------| +| Passwords | 90 days | More frequent for privileged accounts | +| API Keys | 180 days | Depends on provider requirements | +| SSH Keys | 365 days | Rotate immediately if compromised | +| Server Certificates | 30 days before expiry | Automate monitoring | +| CA Certificates | 1 year before expiry | Plan carefully | + +### 4. Principle of Least Privilege + +Grant minimal necessary access: + +```hcl +# Vault policy - Developer +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/staging/*" { + capabilities = ["read", "list"] # Read-only +} + +path "secret/prod/*" { + capabilities = ["deny"] # No access +} +``` + +## Vault Security + +### Secure Vault Deployment + +```yaml +# Production Vault configuration +params: + # Use auto-unseal + vault_seal_type: awskms + vault_awskms_key_id: ((aws_kms_key_id)) + + # Enable audit logging + vault_audit_enabled: true + + # Use TLS + vault_tls_cert: ((vault_tls_cert)) + vault_tls_key: ((vault_tls_key)) + + # High availability + vault_instances: 3 +``` + +### Audit Logging + +Always enable audit logs: + +```bash +# Enable file audit backend +vault audit enable file \ + file_path=/vault/logs/audit.log \ + log_raw=false + +# Enable syslog for SIEM integration +vault audit enable syslog \ + tag="vault" \ + facility="LOCAL7" +``` + +### Backup Procedures + +Regular encrypted backups: + +```bash +#!/bin/bash +# backup-vault.sh + +DATE=$(date +%Y%m%d-%H%M%S) +BACKUP_FILE="vault-backup-${DATE}.tar.gz" + +# Create backup +genesis do vault-prod -- backup + +# Encrypt backup +gpg --encrypt \ + --recipient backup@example.com \ + "$BACKUP_FILE" + +# Upload to secure storage +aws s3 cp "${BACKUP_FILE}.gpg" \ + s3://secure-backups/vault/ + +# Clean up +rm -f "$BACKUP_FILE" "${BACKUP_FILE}.gpg" +``` + +## Access Control + +### Multi-Factor Authentication + +Enable MFA for Vault access: + +```bash +# Enable TOTP MFA +vault write sys/mfa/method/totp/my_totp \ + issuer=Genesis \ + period=30 \ + algorithm=SHA256 \ + digits=6 + +# Require MFA for production paths +vault write sys/policy/mfa/production_mfa \ + enforcement_config='[{ + "mfa_method_ids": ["method_id"], + "auth_method_types": ["token"] + }]' +``` + +### Time-Based Access + +Use temporary credentials: + +```bash +# Create time-limited token +safe auth token create \ + --policy=deployment \ + --ttl=1h \ + --max-ttl=2h \ + --display-name="CI deployment" +``` + +### Service Account Management + +```yaml +# Separate accounts for each service +credentials: + base: + # Don't reuse accounts + cf/nats_password: random 32 + cf/router_password: random 32 + cf/controller_password: random 32 + + # Not this + # shared_service_password: random 32 # BAD +``` + +## Secret Hygiene + +### Regular Audits + +```bash +#!/bin/bash +# audit-secrets.sh - Run monthly + +echo "=== Secret Age Report ===" + +# Check password age +for env in dev staging prod; do + echo "Environment: $env" + + # List secrets with metadata + safe export "secret/$env" | \ + jq -r 'to_entries[] | + select(.key | contains("password")) | + "\(.key): \(.value.updated_at // "unknown")"' +done + +echo "=== Expiring Certificates ===" +# Find certificates expiring soon +safe find secret | grep cert$ | while read -r cert; do + if safe x509 expires "$cert" --within 30d; then + echo "WARNING: $cert expires soon" + fi +done +``` + +### Cleanup Unused Secrets + +```bash +# Find potentially unused secrets +genesis list --json | jq -r '.[].name' > active-envs.txt + +safe find secret | while read -r secret; do + # Extract environment from path + env=$(echo "$secret" | cut -d/ -f2-3) + + if ! grep -q "$env" active-envs.txt; then + echo "Potentially unused: $secret" + fi +done +``` + +### Document Secret Usage + +```yaml +# In environment files, document external usage +genesis: + secrets_notes: | + admin_password: Used by monitoring system (Datadog) + api_key: Shared with partner integration + db_password: Also configured in backup scripts +``` + +## Secure Development + +### Development Environments + +Use separate Vault instances: + +```bash +# Development Vault (unsealed, insecure) +safe init dev --memory + +# Never use dev mode for real secrets +safe set secret/dev/test password=test123 +``` + +### Secret Scanning + +Pre-commit hooks to catch secrets: + +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] +``` + +### Environment Isolation + +```bash +# Separate Vault paths by environment +/secret/dev/... # Development +/secret/staging/... # Staging +/secret/prod/... # Production + +# Different access policies +/secret/sandbox/... # Wide open for experiments +``` + +## Incident Response + +### Compromised Secrets + +If a secret is compromised: + +1. **Rotate immediately** + ```bash + genesis rotate-secrets prod compromised_password + genesis deploy prod + ``` + +2. **Audit access** + ```bash + grep "compromised_password" /var/log/vault-audit.log + ``` + +3. **Update dependencies** + ```bash + # Find all uses + genesis manifest prod | grep compromised_password + ``` + +4. **Document incident** + ```yaml + # In environment file + genesis: + security_incidents: + - date: 2024-01-15 + secret: admin_password + action: rotated + reason: potential exposure in logs + ``` + +### Emergency Access + +Break-glass procedures: + +```bash +# Sealed Vault emergency access +export VAULT_UNSEAL_KEY_1="..." +export VAULT_UNSEAL_KEY_2="..." +export VAULT_UNSEAL_KEY_3="..." + +vault operator unseal $VAULT_UNSEAL_KEY_1 +vault operator unseal $VAULT_UNSEAL_KEY_2 +vault operator unseal $VAULT_UNSEAL_KEY_3 + +# Use root token only in emergency +vault login $VAULT_ROOT_TOKEN +``` + +## Monitoring and Alerting + +### Certificate Expiration + +```bash +#!/bin/bash +# monitor-certs.sh - Run daily via cron + +ALERT_DAYS=30 +SLACK_WEBHOOK="https://hooks.slack.com/..." + +check_cert_expiry() { + local cert_path=$1 + local days_left=$(safe x509 expires "$cert_path" --json | \ + jq -r '.days_until_expiration') + + if [ "$days_left" -lt "$ALERT_DAYS" ]; then + curl -X POST "$SLACK_WEBHOOK" \ + -H "Content-Type: application/json" \ + -d "{\"text\": \"Certificate $cert_path expires in $days_left days\"}" + fi +} + +# Check all certificates +safe find secret | grep cert$ | while read -r cert; do + check_cert_expiry "$cert" +done +``` + +### Failed Authentication + +Monitor Vault audit logs: + +```bash +# Count failed authentications +grep "error" /var/log/vault-audit.log | \ + grep "permission denied" | \ + jq -r '.auth.display_name' | \ + sort | uniq -c | sort -rn +``` + +## Compliance + +### Regulatory Requirements + +Common compliance needs: + +```yaml +# PCI-DSS Compliance +credentials: + base: + # Requirement 8.2.4 - Change passwords every 90 days + payment_api_key: "random 40 rotate_days=90" + + # Requirement 8.2.3 - Strong passwords + admin_password: "random 32 complexity=high" + +# HIPAA Compliance +certificates: + base: + # Encryption in transit + api/tls: + valid_for: 1y + min_tls_version: "1.2" +``` + +### Audit Trail + +Maintain compliance records: + +```bash +# Generate compliance report +cat > compliance-report.sh <<'EOF' +#!/bin/bash + +echo "=== Secret Rotation Compliance Report ===" +echo "Generated: $(date)" +echo + +# Check rotation compliance +for secret in $(safe find secret/prod | grep password); do + last_rotated=$(safe get "$secret:updated_at" 2>/dev/null || echo "unknown") + echo "$secret: Last rotated $last_rotated" +done +EOF +``` + +## Security Checklist + +Before deploying to production: + +- [ ] All secrets in Vault (no hardcoded values) +- [ ] Appropriate secret strength (32+ chars for passwords) +- [ ] Rotation schedule defined +- [ ] Access policies configured +- [ ] Audit logging enabled +- [ ] Backup procedures tested +- [ ] Emergency access documented +- [ ] Monitoring alerts configured +- [ ] Compliance requirements met +- [ ] Team trained on procedures + +Following these best practices ensures your Genesis deployments remain secure while maintaining operational efficiency. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/credhub-support.md b/lib/Genesis/Help/Topics/30-secrets-management/credhub-support.md new file mode 100644 index 00000000..ba977243 --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/credhub-support.md @@ -0,0 +1,453 @@ +# CredHub Support + +Genesis supports VMware CredHub as an alternative to HashiCorp Vault for secrets management. CredHub is particularly popular in Cloud Foundry environments due to its tight BOSH integration. + +## Overview + +CredHub provides: +- **Native BOSH integration** - Direct support in BOSH Director +- **Typed credentials** - Structured secret types +- **Automatic generation** - BOSH can generate missing credentials +- **ACL support** - Fine-grained access control +- **Certificate rotation** - Built-in certificate management + +## Enabling CredHub + +### BOSH Director Configuration + +Deploy BOSH with CredHub enabled: + +```yaml +# In BOSH environment file +kit: + features: + - aws + - credhub + +params: + credhub_enabled: true +``` + +### Environment Configuration + +Configure Genesis to use CredHub: + +```yaml +# In deployment environment file +genesis: + secrets_provider: credhub + credhub_env: my-bosh-director +``` + +## CredHub vs Vault + +### Feature Comparison + +| Feature | Vault | CredHub | +|---------|-------|---------| +| Secret Types | Generic KV | Typed (password, cert, etc.) | +| BOSH Integration | Via Genesis | Native | +| Access Control | Policies | ACLs | +| UI | Yes | Limited | +| Multi-DC | Yes | Per-BOSH | +| Audit Logs | Comprehensive | Basic | + +### When to Use CredHub + +Choose CredHub when: +- Deploying primarily Cloud Foundry +- Using BOSH heavily +- Want native BOSH integration +- Prefer typed credentials + +Choose Vault when: +- Need enterprise features +- Multiple secret backends +- Complex access policies +- Non-BOSH workloads + +## Secret Management + +### Viewing Secrets + +```bash +# Target CredHub +credhub api https://credhub.example.com:8844 + +# Login +credhub login --client-name genesis --client-secret + +# List secrets +credhub find -n '/genesis/us-east-1-prod' + +# Get specific secret +credhub get -n '/genesis/us-east-1-prod/cf/admin_password' +``` + +### Manual Secret Operations + +```bash +# Set a password +credhub set -n '/genesis/us-east-1-prod/cf/api_key' \ + -t password \ + -w 'super-secret-key' + +# Generate a password +credhub generate -n '/genesis/us-east-1-prod/cf/new_password' \ + -t password \ + -l 32 + +# Create certificate +credhub generate -n '/genesis/us-east-1-prod/cf/web_cert' \ + -t certificate \ + -c 'web.example.com' \ + -a 'web.example.com,*.apps.example.com' \ + --duration 365 \ + --ca '/genesis/us-east-1-prod/cf/ca' +``` + +## Path Structure + +### Genesis Paths in CredHub + +CredHub paths follow this pattern: +``` +/// + +Example: +/my-bosh/us-east-1-prod-cf/admin_password +``` + +### Custom Path Configuration + +```yaml +genesis: + credhub_prefix: /genesis/custom + env: us-east-1-prod +``` + +Results in paths like: +``` +/genesis/custom/us-east-1-prod/admin_password +``` + +## Certificate Management + +### Certificate Generation + +CredHub excels at certificate management: + +```bash +# Generate CA +credhub generate -n '/genesis/prod/ca' \ + -t certificate \ + --is-ca \ + --common-name 'Genesis CA' + +# Generate server certificate +credhub generate -n '/genesis/prod/server-cert' \ + -t certificate \ + --ca '/genesis/prod/ca' \ + --common-name 'server.example.com' \ + --alternative-names 'server.example.com,*.example.com' +``` + +### Certificate Rotation + +```bash +# Regenerate certificate +credhub regenerate -n '/genesis/prod/server-cert' + +# Bulk regenerate +credhub bulk-regenerate --signed-by '/genesis/prod/ca' +``` + +## Access Control + +### CredHub ACLs + +Define who can access secrets: + +```bash +# Grant read access +credhub set-permission \ + -n '/genesis/prod/*' \ + -a 'uaa-client:app1' \ + -p read + +# Grant write access +credhub set-permission \ + -n '/genesis/dev/*' \ + -a 'uaa-user:developer' \ + -p read,write +``` + +### UAA Integration + +CredHub uses UAA for authentication: + +```yaml +# In CF deployment +params: + credhub_uaa_clients: + - name: genesis + secret: ((credhub_genesis_client_secret)) + scopes: + - credhub.read + - credhub.write +``` + +## Integration with Genesis + +### Automatic Secret Generation + +Genesis kits work seamlessly with CredHub: + +```yaml +# Kit defines requirements +credentials: + base: + admin_password: random 32 + +# CredHub generates automatically during deploy +``` + +### Manual Provided Secrets + +For user-provided secrets: + +```bash +# Set before deployment +credhub set -n '/my-bosh/prod-cf/external_api_key' \ + -t value \ + -v 'provided-by-user' +``` + +### Interpolation + +CredHub interpolates at runtime: + +```yaml +# In manifest +properties: + admin_password: ((admin_password)) + +# CredHub provides value during deployment +``` + +## Migration + +### From Vault to CredHub + +```bash +#!/bin/bash +# Migrate secrets from Vault to CredHub + +VAULT_PATH="secret/us-east-1/prod/cf" +CREDHUB_PATH="/genesis/us-east-1-prod/cf" + +# Export from Vault +safe export $VAULT_PATH > secrets.json + +# Import to CredHub +for secret in $(jq -r 'keys[]' secrets.json); do + value=$(jq -r ".$secret" secrets.json) + + # Detect type and import + if [[ $secret == *"password"* ]]; then + credhub set -n "$CREDHUB_PATH/$secret" -t password -w "$value" + elif [[ $secret == *"cert"* ]]; then + credhub set -n "$CREDHUB_PATH/$secret" -t certificate -c "$value" + else + credhub set -n "$CREDHUB_PATH/$secret" -t value -v "$value" + fi +done +``` + +### From CredHub to Vault + +```bash +#!/bin/bash +# Migrate from CredHub to Vault + +# Export from CredHub +credhub find -n '/genesis/prod' -j | \ + jq -r '.credentials[].name' | \ + while read -r name; do + credhub get -n "$name" -j > "/tmp/$(basename $name).json" + done + +# Import to Vault +# ... conversion logic ... +``` + +## Operations + +### Backup and Restore + +```bash +# Backup CredHub database +bosh -d credhub-deployment \ + run-errand bbr-backup + +# Restore +bosh -d credhub-deployment \ + run-errand bbr-restore \ + --backup-artifact /path/to/backup +``` + +### Monitoring + +Monitor CredHub health: + +```yaml +# Prometheus metrics +- job_name: credhub + static_configs: + - targets: ['credhub.example.com:9000'] + metrics_path: /metrics +``` + +Key metrics: +- `credhub_credential_count` +- `credhub_operation_duration` +- `credhub_api_requests_total` + +### Performance Tuning + +```yaml +# In CredHub deployment +params: + credhub_encryption_keys: 2 # Multiple keys + credhub_db_connections: 20 # Connection pool + credhub_threads: 100 # Request threads +``` + +## Best Practices + +### 1. Use Typed Credentials + +```bash +# Good - typed password +credhub generate -n /path -t password + +# Less ideal - generic value +credhub set -n /path -t value -v "password" +``` + +### 2. Leverage Certificate Features + +```bash +# Use CA signing +credhub generate -n /ca -t certificate --is-ca +credhub generate -n /server -t certificate --ca /ca + +# Set expiry alerts +credhub set-permission -n /certs/* \ + -a 'monitoring-system' -p read +``` + +### 3. Implement ACLs + +```bash +# Principle of least privilege +credhub set-permission \ + -n '/prod/*' \ + -a 'prod-team' \ + -p read,write + +credhub set-permission \ + -n '/prod/*' \ + -a 'dev-team' \ + -p read +``` + +### 4. Regular Rotation + +```bash +# Rotate passwords +credhub regenerate -n /path/to/password + +# Bulk rotate certificates +credhub bulk-regenerate --signed-by /my-ca +``` + +### 5. Monitor Certificate Expiry + +```bash +# Check certificate expiration +credhub get -n /path/to/cert -j | \ + jq -r '.value.certificate' | \ + openssl x509 -noout -enddate +``` + +## Troubleshooting + +### Connection Issues + +```bash +# Check CredHub API +curl -k https://credhub.example.com:8844/info + +# Verify UAA connectivity +curl -k https://uaa.example.com:8443/info + +# Check client permissions +credhub login --client-name my-client +``` + +### Permission Denied + +```bash +# List permissions +credhub get-permission -n /path + +# Check UAA token +credhub --version # Shows current auth + +# Re-authenticate +credhub logout +credhub login +``` + +### Secret Not Found + +```bash +# Search for secret +credhub find -n prod + +# Check exact path +credhub get -n /full/path/to/secret + +# Verify BOSH interpolation +bosh interpolate manifest.yml \ + --vars-store=credhub +``` + +## CredHub CLI Reference + +Common commands: + +```bash +# Authentication +credhub login +credhub logout + +# Secret operations +credhub get -n +credhub set -n -t -v +credhub delete -n +credhub generate -n -t +credhub regenerate -n + +# Bulk operations +credhub find -n +credhub bulk-regenerate --signed-by + +# Permissions +credhub set-permission -n -a -p +credhub get-permission -n +credhub delete-permission -n -a +``` + +CredHub provides a robust, BOSH-native alternative to Vault for organizations heavily invested in the Cloud Foundry ecosystem. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/index.md b/lib/Genesis/Help/Topics/30-secrets-management/index.md new file mode 100644 index 00000000..b00c8496 --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/index.md @@ -0,0 +1,105 @@ +# Secrets Management + +Genesis provides comprehensive secrets management through integration with HashiCorp Vault and VMware CredHub. This section covers everything from basic secret generation to advanced rotation procedures. + +## Topics in This Section + +1. **[Overview](overview.md)** - Introduction to Genesis secrets management +2. **[Vault Integration](vault-integration.md)** - Working with HashiCorp Vault +3. **[Secret Types](secret-types.md)** - Passwords, certificates, SSH keys, and more +4. **[Kit Secrets](kit-secrets.md)** - Defining secrets in kit.yml files +5. **[Rotation Procedures](rotation-procedures.md)** - Rotating credentials safely +6. **[CredHub Support](credhub-support.md)** - Using CredHub as an alternative +7. **[Manual Management](manual-management.md)** - Direct secret manipulation +8. **[Best Practices](best-practices.md)** - Security recommendations + +## Quick Overview + +Genesis automatically manages secrets for your deployments: + +- **Automatic Generation** - Credentials created on first deployment +- **Secure Storage** - Stored in Vault or CredHub +- **Easy Rotation** - Built-in rotation commands +- **Type Safety** - Specific generators for each secret type + +### Common Secret Types + +- **Passwords** - Random strings with configurable complexity +- **SSH Keys** - Public/private key pairs +- **X.509 Certificates** - TLS certificates with CA chains +- **RSA Keys** - For JWT signing and encryption +- **UUIDs** - Unique identifiers + +## Basic Usage + +### View Secrets + +```bash +# List all secrets for an environment +safe tree secret/us-east-1/prod/cf + +# View specific secret +safe get secret/us-east-1/prod/cf/admin_password +``` + +### Rotate Secrets + +```bash +# Rotate specific secret +genesis rotate-secrets us-east-1-prod admin_password + +# Rotate all secrets (careful!) +genesis rotate-secrets us-east-1-prod --all +``` + +### Manual Generation + +```bash +# Generate a password +safe gen secret/us-east-1/prod/cf/custom_password + +# Create SSH key +safe ssh secret/us-east-1/prod/cf/jumpbox_ssh + +# Generate certificate +safe x509 issue secret/us-east-1/prod/cf/web_cert \ + --name example.com \ + --ca secret/us-east-1/prod/cf/ca +``` + +## Integration with Kits + +Kits define required secrets in their `kit.yml`: + +```yaml +credentials: + base: + admin_user: + username: admin + password: random 32 + +certificates: + base: + ca: + valid_for: 10y + server: + valid_for: 1y + names: + - "*.system.${params.base_domain}" + - "*.apps.${params.base_domain}" +``` + +## Security Considerations + +1. **Never commit secrets** to version control +2. **Use strong passwords** - Minimum 16 characters +3. **Rotate regularly** - Especially after personnel changes +4. **Limit access** - Use Vault policies +5. **Audit usage** - Enable Vault audit logs + +## Getting Started + +- New to secrets? Start with the [Overview](overview.md) +- Setting up Vault? See [Vault Integration](vault-integration.md) +- Need to rotate? Check [Rotation Procedures](rotation-procedures.md) +- Using CredHub? Read [CredHub Support](credhub-support.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/kit-secrets.md b/lib/Genesis/Help/Topics/30-secrets-management/kit-secrets.md new file mode 100644 index 00000000..a885895a --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/kit-secrets.md @@ -0,0 +1,478 @@ +# Kit Secrets Definition + +This guide explains how to define secrets in Genesis kit.yml files. Kit authors use these definitions to specify what secrets their deployments need. + +## Overview + +Kits define secrets in three main sections of `kit.yml`: + +1. **credentials** - Passwords, keys, and other generated secrets +2. **certificates** - X.509 certificates and CAs +3. **provided** - User-supplied secrets + +## Credentials Section + +### Basic Structure + +```yaml +credentials: + : + : +``` + +### Simple Credentials + +```yaml +credentials: + base: + # Simple password + admin_password: random 32 + + # Password with options + db/password: "random 64 fmt base64" + + # SSH key + jumpbox/ssh: ssh 2048 + + # RSA key + jwt/signing_key: rsa 4096 + + # UUID + consul/gossip: uuid +``` + +### Complex Credentials + +For secrets with multiple components: + +```yaml +credentials: + base: + # Multiple keys under one path + nats: + username: nats + password: random 32 + + # Nested structure + db/admin: + username: admin + password: "random 40 allowed-chars A-Za-z0-9" +``` + +### Credential Parameters + +#### Random Passwords + +```yaml +"random [options]" + +Options: +- fmt base64|bcrypt # Encoding format +- allowed-chars # Character set +- fixed # Prevent rotation +- at # Store at specific key + +Examples: +- "random 16" # 16-char password +- "random 32 fmt base64" # Base64 encoded +- "random 8 allowed-chars 0-9" # Numeric only +- "random 40 fixed" # Non-rotating +``` + +#### SSH Keys + +```yaml +"ssh [fixed]" + +Examples: +- "ssh 2048" # 2048-bit RSA key +- "ssh 4096 fixed" # Non-rotating 4096-bit key +``` + +#### RSA Keys + +```yaml +"rsa [fixed]" + +Examples: +- "rsa 2048" # 2048-bit RSA key +- "rsa 4096 fixed" # Non-rotating 4096-bit key +``` + +#### DH Parameters + +```yaml +"dhparam [fixed]" + +Examples: +- "dhparam 2048" # 2048-bit DH params +- "dhparam 4096 fixed" # Non-rotating 4096-bit +``` + +#### UUIDs + +```yaml +"uuid [version] [namespace name ]" + +Examples: +- "uuid" # Random v4 UUID +- "uuid v4" # Explicit v4 +- "uuid v5 namespace dns name example.com" # Deterministic +``` + +## Certificates Section + +### Basic Structure + +```yaml +certificates: + : + : + : + +``` + +### Certificate Properties + +```yaml +certificates: + base: + certs: + ca: + is_ca: true + valid_for: 10y + + server: + valid_for: 1y + names: + - "*.system.cf.example.com" + - "*.apps.cf.example.com" + - "10.0.0.5" + signed_by: certs/ca +``` + +### Certificate Parameters + +- **is_ca**: Boolean, marks as CA certificate +- **valid_for**: Duration (e.g., `1y`, `90d`, `8760h`) +- **names**: List of DNS names and IPs +- **signed_by**: Path to signing CA (optional) + +### Using Parameters + +Reference environment parameters: + +```yaml +certificates: + base: + haproxy/ssl: + server: + valid_for: "${params.cert_validity}" + names: "${params.haproxy_domains}" +``` + +### Certificate Hierarchies + +```yaml +certificates: + base: + # Root CA + root/ca: + is_ca: true + valid_for: 20y + + # Intermediate CA + intermediate/ca: + is_ca: true + valid_for: 10y + signed_by: root/ca + + # Server certs + internal/server: + valid_for: 1y + signed_by: intermediate/ca + names: ["internal.example.com"] +``` + +## Provided Section + +### Basic Structure + +```yaml +provided: + : + : + type: generic + keys: + : + +``` + +### Provided Secret Properties + +```yaml +provided: + base: + external/oauth: + type: generic + keys: + client_id: + type: string + prompt: "Enter OAuth Client ID" + + client_secret: + type: string + sensitive: true + prompt: "Enter OAuth Client Secret" + + private_key: + type: string + multiline: true + prompt: "Paste private key (Ctrl-D when done)" +``` + +### Key Properties + +- **type**: Always `string` currently +- **sensitive**: Hide input (boolean) +- **multiline**: Accept multiple lines (boolean) +- **prompt**: Message shown to user +- **fixed**: Prevent regeneration (boolean) + +## Feature-Based Organization + +### Conditional Secrets + +Secrets can be organized by feature: + +```yaml +credentials: + # Always generated + base: + admin_password: random 32 + + # Only with postgres feature + postgres: + db/password: random 32 + db/username: cfdb + + # Only with mysql feature + mysql: + db/password: random 40 + db/root_password: random 40 + +certificates: + # Only with haproxy feature + haproxy: + haproxy/ssl: + ca: + is_ca: true + valid_for: 10y + server: + valid_for: 1y + names: ["*.${params.system_domain}"] +``` + +### Feature Activation + +In environment file: + +```yaml +kit: + features: + - postgres # Activates postgres secrets + - haproxy # Activates haproxy certificates +``` + +## Advanced Patterns + +### Shared CAs + +```yaml +certificates: + base: + # Shared CA for all features + shared/ca: + ca: + is_ca: true + valid_for: 10y + + routing: + # Uses shared CA + router/ssl: + server: + signed_by: shared/ca + valid_for: 1y + names: ["*.router.${params.base_domain}"] + + uaa: + # Also uses shared CA + uaa/ssl: + server: + signed_by: shared/ca + valid_for: 1y + names: ["uaa.${params.system_domain}"] +``` + +### Computed Secrets + +Some kits compute secrets from others: + +```yaml +credentials: + base: + # Base components + db/username: cfdb + db/password: random 32 + + # Computed in manifest + # db/uri: postgres://cfdb:password@host:5432/cf +``` + +### Secret Groups + +Organize related secrets: + +```yaml +credentials: + shield: + # Agent credentials + agent/shield: + username: shield-agent + password: random 32 + + # Backup target credentials + backups/s3: + access_key: "provided" + secret_key: "provided" + + # Encryption key + backups/cipher: + key: "random 32 fmt base64" +``` + +## Validation + +### Required Fields + +Genesis validates secret definitions: + +```yaml +# This will fail - certificates need names +certificates: + base: + bad/cert: + server: + valid_for: 1y + # Missing: names +``` + +### Type Checking + +```yaml +# This will fail - invalid secret type +credentials: + base: + bad/secret: "invalid-type 32" +``` + +## Best Practices + +### 1. Use Clear Paths + +```yaml +# Good - clear purpose +credentials: + base: + nats/server_password: random 32 + nats/client_password: random 32 + +# Bad - ambiguous +credentials: + base: + password1: random 32 + password2: random 32 +``` + +### 2. Group Related Secrets + +```yaml +credentials: + base: + # Group by component + diego/ssh: + private_key: "rsa 2048" + diego/bbs/encryption: + key: "random 32 fmt base64" + diego/rep/password: random 32 +``` + +### 3. Document Provided Secrets + +```yaml +provided: + newrelic: + monitoring/newrelic: + keys: + license_key: + prompt: | + Enter New Relic License Key + (Get from: https://rpm.newrelic.com/accounts/xxx) +``` + +### 4. Use Parameters + +```yaml +# In kit.yml +certificates: + base: + web/ssl: + server: + valid_for: "${params.cert_validity_period}" + names: "${params.web_domains}" + +# Allows environment customization +params: + cert_validity_period: 90d + web_domains: + - example.com + - www.example.com +``` + +### 5. Consider Rotation + +```yaml +credentials: + base: + # Rotatable + app/password: random 32 + + # Fixed - external dependency + legacy/api_key: "random 40 fixed" +``` + +## Testing Secret Definitions + +### Manual Testing + +```bash +# Deploy to test environment +genesis new test-secrets +genesis deploy test-secrets + +# Check generated secrets +safe tree secret/test/secrets +``` + +### Validation Commands + +```bash +# Validate kit +genesis kit validate + +# Check specific feature +genesis new test --features haproxy +genesis check test +``` + +Understanding kit secret definitions helps you create secure, maintainable Genesis kits with proper credential management. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/manual-management.md b/lib/Genesis/Help/Topics/30-secrets-management/manual-management.md new file mode 100644 index 00000000..6879067e --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/manual-management.md @@ -0,0 +1,456 @@ +# Manual Secret Management + +While Genesis automates most secret operations, sometimes you need direct control. This guide covers manual secret management techniques for special cases and troubleshooting. + +## Direct Vault Access + +### Using Safe CLI + +The `safe` command provides direct Vault access: + +```bash +# Target Vault +safe target prod https://vault.example.com:8200 +safe auth + +# Basic operations +safe set secret/path key=value +safe get secret/path +safe delete secret/path +safe move secret/old/path secret/new/path +safe copy secret/source secret/dest +``` + +### Complex Secret Operations + +```bash +# Set multiple keys +safe set secret/us-east-1/prod/cf/database \ + username=dbadmin \ + password=complex-password \ + host=db.example.com \ + port=5432 + +# Set from file +safe set secret/path/cert value=@/path/to/cert.pem + +# Set JSON data +safe set secret/path/config value='{"key": "value", "foo": "bar"}' + +# Interactive mode +safe set secret/path/password +# Prompts for value (hidden) +``` + +## Viewing and Exporting Secrets + +### Individual Secrets + +```bash +# View specific key +safe get secret/us-east-1/prod/cf/admin_password + +# Get just the value +safe get secret/us-east-1/prod/cf/admin_password:value + +# Format output +safe get secret/path --format json +safe get secret/path --format yaml +``` + +### Bulk Operations + +```bash +# List all secrets +safe tree secret/us-east-1/prod/cf + +# Export entire tree +safe export secret/us-east-1/prod/cf > cf-secrets.json + +# Export with paths +safe export --all secret/us-east-1/prod > all-secrets.json + +# Find secrets by pattern +safe find secret/us-east-1 | grep password +``` + +## Manual Generation + +### Passwords + +```bash +# Generate password in Vault +safe gen secret/path/password + +# With specific length +safe gen secret/path/password length=40 + +# Custom parameters +safe gen secret/path/password \ + length=32 \ + policy=printable + +# Generate locally and set +PASSWORD=$(openssl rand -base64 32) +safe set secret/path value="$PASSWORD" +``` + +### SSH Keys + +```bash +# Generate SSH key +safe ssh secret/path/ssh-key + +# With specific size +safe ssh secret/path/ssh-key size=4096 + +# Extract public key +safe get secret/path/ssh-key:public > id_rsa.pub + +# Generate locally +ssh-keygen -t rsa -b 4096 -f temp_key -N "" +safe set secret/path/ssh \ + private=@temp_key \ + public=@temp_key.pub +rm temp_key temp_key.pub +``` + +### Certificates + +```bash +# Create CA +safe x509 ca secret/path/ca \ + --common-name "Genesis CA" \ + --valid-for 10y + +# Issue certificate +safe x509 issue secret/path/server \ + --ca secret/path/ca \ + --common-name server.example.com \ + --alternative-names "*.example.com,10.0.0.5" \ + --valid-for 1y + +# Self-signed certificate +safe x509 self-signed secret/path/self \ + --common-name test.example.com \ + --valid-for 90d +``` + +### RSA Keys + +```bash +# Generate RSA key pair +openssl genrsa -out private.pem 4096 +openssl rsa -in private.pem -pubout -out public.pem + +# Store in Vault +safe set secret/path/rsa \ + private=@private.pem \ + public=@public.pem + +# Clean up +rm private.pem public.pem +``` + +## Fixing Secret Issues + +### Wrong Format + +```bash +# Certificate stored incorrectly +safe get secret/path/cert + +# Fix by reformatting +CERT=$(safe get secret/path/cert:value) +safe set secret/path/cert \ + cert="$CERT" \ + key=@private.key \ + ca=@ca.crt +``` + +### Missing Components + +```bash +# SSH key missing public component +PRIVATE=$(safe get secret/path/ssh:private) + +# Generate public from private +echo "$PRIVATE" > temp.key +chmod 600 temp.key +ssh-keygen -y -f temp.key > temp.pub + +# Update secret +safe set secret/path/ssh \ + private="$PRIVATE" \ + public=@temp.pub + +rm temp.key temp.pub +``` + +### Corrupted Secrets + +```bash +# Backup current state +safe export secret/path > backup.json + +# Check for issues +safe get secret/path | jq . + +# Restore from backup if needed +safe import < backup.json +``` + +## Path Management + +### Moving Secrets + +```bash +# Move single secret +safe move secret/old/path secret/new/path + +# Move entire tree +safe export secret/old/tree > temp.json +safe import --at secret/new/tree < temp.json +safe delete secret/old/tree --recursive +``` + +### Copying Between Environments + +```bash +# Copy from dev to staging +safe export secret/dev/cf > dev-secrets.json + +# Modify paths +sed 's|secret/dev|secret/staging|g' dev-secrets.json > staging-secrets.json + +# Import to staging +safe import < staging-secrets.json +``` + +### Cleaning Up + +```bash +# Delete single secret +safe delete secret/path/to/delete + +# Delete with confirmation +safe delete secret/important/path --prompt + +# Recursive delete +safe delete secret/entire/tree --recursive + +# Dry run +safe delete secret/path --recursive --dry-run +``` + +## Advanced Techniques + +### Templating Secrets + +```bash +#!/bin/bash +# Generate environment-specific secrets + +ENVS="dev staging prod" +TEMPLATE='{ + "admin_password": "$(safe gen password)", + "api_key": "$(uuidgen)", + "deployed_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)" +}' + +for env in $ENVS; do + eval "echo '$TEMPLATE'" | \ + jq . | \ + safe import --at "secret/$env/cf/metadata" +done +``` + +### Bulk Updates + +```bash +#!/bin/bash +# Update all passwords in an environment + +BASE_PATH="secret/us-east-1/prod/cf" + +# Find all passwords +safe find "$BASE_PATH" | grep password$ | while read -r path; do + echo "Rotating: $path" + safe gen "$path" length=32 +done +``` + +### Secret Validation + +```bash +#!/bin/bash +# Validate secret structure + +validate_secret() { + local path=$1 + local required_keys=$2 + + for key in $required_keys; do + if ! safe exists "$path:$key"; then + echo "ERROR: Missing $key in $path" + return 1 + fi + done + + echo "OK: $path has all required keys" + return 0 +} + +# Check database secret +validate_secret "secret/prod/cf/db" "username password host port" + +# Check certificate +validate_secret "secret/prod/cf/cert" "cert key ca" +``` + +## Integration Scripts + +### Pre-deployment Validation + +```bash +#!/bin/bash +# check-secrets.sh - Run before deployment + +ENV=$1 +BASE="secret/$ENV/cf" + +echo "Checking secrets for $ENV..." + +# Required secrets +REQUIRED=( + "admin_password" + "db/password" + "nats/password" + "router/ca" +) + +MISSING=() +for secret in "${REQUIRED[@]}"; do + if ! safe exists "$BASE/$secret"; then + MISSING+=("$secret") + fi +done + +if [ ${#MISSING[@]} -ne 0 ]; then + echo "ERROR: Missing secrets:" + printf ' - %s\n' "${MISSING[@]}" + exit 1 +fi + +echo "All required secrets present" +``` + +### External Service Integration + +```bash +#!/bin/bash +# Sync external API keys + +# Fetch from external service +API_KEY=$(aws secretsmanager get-secret-value \ + --secret-id prod/api-key \ + --query SecretString \ + --output text) + +# Store in Vault +safe set secret/us-east-1/prod/cf/external/aws \ + api_key="$API_KEY" \ + updated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" +``` + +## Debugging + +### Trace Secret Usage + +```bash +# Find where a secret is used +SECRET_NAME="admin_password" +ENV="us-east-1-prod" + +# Check manifest +genesis manifest $ENV | grep -n "$SECRET_NAME" + +# Check generated manifest +bosh -d $ENV-cf manifest | grep -n "$SECRET_NAME" + +# Check runtime config +bosh runtime-config | grep -n "$SECRET_NAME" +``` + +### Audit Access + +```bash +# Enable audit logging +vault audit enable file file_path=/var/log/vault-audit.log + +# Check who accessed a secret +grep "secret/us-east-1/prod" /var/log/vault-audit.log | \ + jq -r '[.time, .auth.display_name, .request.path] | @csv' +``` + +## Best Practices + +### 1. Document Manual Changes + +```bash +# Add metadata when manually setting +safe set secret/path/manual-secret \ + value="special-value" \ + created_by="$USER" \ + created_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + reason="Required for legacy system X" +``` + +### 2. Use Atomic Operations + +```bash +# Update multiple related secrets together +cat < "backup-$(date +%Y%m%d-%H%M%S).json" + +# Verify backup +jq . backup-*.json +``` + +### 4. Test Changes + +```bash +# Test in lower environment first +safe copy secret/prod/setting secret/dev/setting-test +# Test deployment with dev environment +# If successful, apply to prod +``` + +### 5. Clean Up Temporary Files + +```bash +# Use trap for cleanup +cleanup() { + rm -f /tmp/temp-key-* +} +trap cleanup EXIT + +# Work with temporary files +TEMP_KEY=$(mktemp /tmp/temp-key-XXXXXX) +# ... use temp file ... +# Cleanup happens automatically +``` + +Manual secret management gives you full control when Genesis automation isn't sufficient, but use it judiciously to maintain security and consistency. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/overview.md b/lib/Genesis/Help/Topics/30-secrets-management/overview.md new file mode 100644 index 00000000..2f7836f5 --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/overview.md @@ -0,0 +1,243 @@ +# Secrets Management Overview + +Genesis integrates deeply with secret management systems to handle credentials, certificates, and other sensitive data required by your deployments. This overview explains the concepts and architecture. + +## Why Secrets Management? + +Modern infrastructure requires numerous credentials: +- Database passwords +- API keys +- SSH keys for access +- TLS certificates +- Service account credentials +- Encryption keys + +Managing these manually is: +- **Error-prone** - Easy to expose or lose secrets +- **Time-consuming** - Generating and distributing takes effort +- **Risky** - Rotation requires coordination +- **Difficult to audit** - Who has access to what? + +## How Genesis Handles Secrets + +Genesis automates secret management through: + +### 1. Automatic Generation + +When you deploy an environment, Genesis: +- Detects required secrets from the kit +- Checks if they already exist in Vault +- Generates missing secrets automatically +- Stores them securely + +### 2. Consistent Paths + +Secrets follow predictable paths: +``` +/secret/// + +Example: +/secret/us/east/1/prod/cf/admin_password +``` + +### 3. Manifest Integration + +Genesis injects secrets during manifest generation: +```yaml +# In manifest template +admin_password: ((vault "secret/path:password")) + +# Genesis replaces with actual value during deployment +admin_password: "GeneratedSecurePassword123!" +``` + +### 4. Rotation Support + +Built-in commands for credential rotation: +```bash +genesis rotate-secrets my-env admin_password +``` + +## Supported Secret Stores + +### HashiCorp Vault (Primary) + +The preferred secret backend: +- **Encrypted storage** - All secrets encrypted at rest +- **Access control** - Fine-grained policies +- **Audit logging** - Track all access +- **High availability** - Clustered deployment +- **Secret engines** - Multiple backend types + +### VMware CredHub + +Alternative for Cloud Foundry environments: +- **BOSH integration** - Native BOSH support +- **Credential types** - Structured secret types +- **ACLs** - Access control lists +- **Interpolation** - Runtime secret injection + +## Secret Lifecycle + +### Generation Phase + +1. **Kit Definition** - Kit specifies required secrets +2. **Deployment Check** - Genesis checks what's missing +3. **Automatic Generation** - Creates missing secrets +4. **Secure Storage** - Saves to Vault/CredHub + +### Usage Phase + +1. **Manifest Generation** - Genesis retrieves secrets +2. **Injection** - Replaces placeholders +3. **Deployment** - BOSH uses secrets +4. **Runtime** - Applications access as needed + +### Rotation Phase + +1. **Identify** - Determine what needs rotation +2. **Generate** - Create new credentials +3. **Update** - Store in secret backend +4. **Deploy** - Apply to infrastructure +5. **Verify** - Ensure services still work + +## Secret Types + +### Passwords +```yaml +credentials: + base: + db/password: random 32 +``` +- Random generation +- Configurable length +- Character set control + +### SSH Keys +```yaml +credentials: + base: + jumpbox/ssh: ssh 2048 +``` +- RSA key pairs +- Configurable key size +- Public/private keys + +### X.509 Certificates +```yaml +certificates: + base: + ca: + valid_for: 10y + server: + valid_for: 1y + names: ["*.example.com"] +``` +- Certificate authorities +- Server/client certificates +- Automatic renewal warnings + +### RSA Keys +```yaml +credentials: + base: + jwt/signing: rsa 4096 +``` +- JWT signing +- Encryption keys +- Configurable key size + +## Security Architecture + +### Vault Policies + +Control access by path: +```hcl +# Dev team policy +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete"] +} + +# Prod read-only +path "secret/prod/*" { + capabilities = ["read"] +} +``` + +### Network Security + +- **TLS everywhere** - Encrypted communications +- **mTLS** - Mutual TLS for authentication +- **Network isolation** - Vault in secure subnet +- **Firewall rules** - Restrict access + +### Operational Security + +- **Regular rotation** - Scheduled credential updates +- **Audit logs** - Track all secret access +- **Backup procedures** - Encrypted secret backups +- **Break-glass access** - Emergency procedures + +## Common Patterns + +### Shared Secrets + +Some secrets shared across environments: +```yaml +# Shared CA certificate +/secret/shared/ca-cert + +# Environment-specific servers +/secret/dev/cf/server-cert # Signed by shared CA +/secret/prod/cf/server-cert # Signed by shared CA +``` + +### External Secrets + +Integrating existing secrets: +```yaml +provided: + base: + external/api: + keys: + - api_key + - api_secret +``` + +### Multi-Tenant Isolation + +Separate secrets by tenant: +``` +/secret/tenant-a/prod/cf/ +/secret/tenant-b/prod/cf/ +``` + +## Benefits + +### For Operators + +- **No manual generation** - Automated secret creation +- **Consistent storage** - Predictable locations +- **Easy rotation** - Simple commands +- **Audit trail** - Who accessed what + +### For Security Teams + +- **Encrypted storage** - Secrets never in plaintext +- **Access control** - Policy-based permissions +- **Compliance** - Audit logs for regulations +- **Rotation tracking** - Know secret ages + +### For Developers + +- **No hardcoded secrets** - Everything from Vault +- **Environment isolation** - Dev can't access prod +- **Self-service** - Generate dev secrets easily +- **Integration support** - SDKs for all languages + +## Next Steps + +- Learn about [Vault Integration](vault-integration.md) +- Understand [Secret Types](secret-types.md) in detail +- Master [Rotation Procedures](rotation-procedures.md) +- Review [Best Practices](best-practices.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/rotation-procedures.md b/lib/Genesis/Help/Topics/30-secrets-management/rotation-procedures.md new file mode 100644 index 00000000..d7ab803f --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/rotation-procedures.md @@ -0,0 +1,463 @@ +# Secret Rotation Procedures + +Regular secret rotation is crucial for maintaining security. This guide covers how to safely rotate credentials in Genesis deployments. + +## Overview + +Secret rotation involves: +1. Generating new credentials +2. Updating Vault +3. Deploying with new secrets +4. Verifying services work +5. Cleaning up old credentials + +## Using Genesis Rotate Command + +### Basic Rotation + +```bash +# Rotate specific secret +genesis rotate-secrets my-env admin_password + +# Rotate multiple secrets +genesis rotate-secrets my-env admin_password nats_password + +# Rotate all secrets (use with caution!) +genesis rotate-secrets my-env --all +``` + +### What Gets Rotated + +The command rotates secrets marked as rotatable: +- Passwords (unless marked `fixed`) +- SSH keys (unless marked `fixed`) +- Certificates (regenerated with same parameters) +- Other generated credentials + +Not rotated: +- Secrets marked with `fixed` +- User-provided secrets +- CA certificates (by default) + +## Planning Rotation + +### 1. Identify What to Rotate + +```bash +# List all secrets +safe tree secret/us-east-1/prod/cf + +# Check secret age +safe get secret/us-east-1/prod/cf/admin_password | \ + safe x509 show --json | jq .not_before + +# Find old passwords +genesis info my-env --secrets +``` + +### 2. Assess Impact + +Consider: +- **Service dependencies** - What uses this credential? +- **Downtime requirements** - Can services handle rotation? +- **External systems** - Any hardcoded references? +- **Backup systems** - Will backups still work? + +### 3. Create Rotation Plan + +```markdown +## Rotation Plan - Production CF + +### Phase 1: Non-Critical (No Downtime) +- [ ] admin_password +- [ ] smoke_test_password +- [ ] autoscaler_password + +### Phase 2: Internal Services (Brief Downtime) +- [ ] nats_password +- [ ] router_password +- [ ] bbs_password + +### Phase 3: Critical (Maintenance Window) +- [ ] database_password +- [ ] blobstore_password +``` + +## Rotation Procedures by Type + +### Password Rotation + +#### Simple Password + +```bash +# 1. Rotate the password +genesis rotate-secrets my-env admin_password + +# 2. Deploy immediately +genesis deploy my-env + +# 3. Test login with new password +cf login -a https://api.system.example.com +``` + +#### Database Password + +Requires coordination: + +```bash +# 1. Check current connections +bosh -d my-env-cf ssh database/0 \ + 'sudo -u vcap psql -c "SELECT * FROM pg_stat_activity"' + +# 2. Rotate password +genesis rotate-secrets my-env db/password + +# 3. Deploy database first +genesis deploy my-env --skip-unchanged + +# 4. Update applications +genesis deploy my-env + +# 5. Verify connectivity +genesis do my-env -- run-errand smoke-tests +``` + +### SSH Key Rotation + +```bash +# 1. Generate new key +genesis rotate-secrets my-env jumpbox/ssh + +# 2. Deploy to update authorized_keys +genesis deploy my-env + +# 3. Test new key +safe get secret/path/jumpbox/ssh:private > new_key +chmod 600 new_key +ssh -i new_key vcap@jumpbox + +# 4. Remove old key from local systems +rm ~/.ssh/old_jumpbox_key +``` + +### Certificate Rotation + +#### Server Certificate + +```bash +# 1. Check expiration +safe x509 expires secret/us-east-1/prod/cf/haproxy/ssl + +# 2. Rotate certificate +genesis rotate-secrets my-env haproxy/ssl + +# 3. Deploy with new cert +genesis deploy my-env + +# 4. Verify certificate +echo | openssl s_client -connect haproxy.example.com:443 2>/dev/null | \ + openssl x509 -noout -dates +``` + +#### CA Certificate Rotation + +CA rotation is complex - requires careful planning: + +```bash +# 1. Create new CA alongside old +safe x509 issue secret/path/new-ca \ + --ca \ + --valid-for 10y + +# 2. Sign new certificates with new CA +genesis rotate-secrets my-env server/cert \ + --sign-with secret/path/new-ca + +# 3. Deploy with both CAs trusted +# 4. Rotate all dependent certificates +# 5. Remove old CA +``` + +## Advanced Rotation Scenarios + +### Zero-Downtime Password Rotation + +For services supporting multiple credentials: + +```yaml +# 1. Add new credential +credentials: + base: + db/password: random 32 + db/password_new: random 32 + +# 2. Deploy with both passwords +# 3. Switch to new password +# 4. Remove old password +``` + +### Rotating External Integrations + +```bash +# 1. Create new credentials in external system +# AWS example: +aws iam create-access-key --user-name genesis-user + +# 2. Update in Vault +safe set secret/us-east-1/prod/cf/aws \ + access_key=NEW_ACCESS_KEY \ + secret_key=NEW_SECRET_KEY + +# 3. Deploy +genesis deploy my-env + +# 4. Verify external access +genesis do my-env -- test-s3-access + +# 5. Delete old credentials +aws iam delete-access-key \ + --user-name genesis-user \ + --access-key-id OLD_ACCESS_KEY +``` + +### Coordinated Multi-Environment Rotation + +```bash +#!/bin/bash +# Rotate shared database password across environments + +ENVIRONMENTS="dev staging prod" +SECRET="db/password" + +# 1. Generate new password +NEW_PASS=$(safe gen password) + +# 2. Update all environments +for env in $ENVIRONMENTS; do + safe set secret/$env/cf/$SECRET value="$NEW_PASS" +done + +# 3. Deploy in order +for env in $ENVIRONMENTS; do + genesis deploy $env + genesis do $env -- run-errand smoke-tests +done +``` + +## Monitoring and Verification + +### Pre-Rotation Checks + +```bash +# Check service health +bosh -d my-env-cf vms --vitals + +# Verify current credentials work +genesis do my-env -- run-errand smoke-tests + +# Backup current secrets +safe export secret/us-east-1/prod/cf > backup-before-rotation.json +``` + +### Post-Rotation Verification + +```bash +# 1. Check deployment health +bosh -d my-env-cf vms --vitals + +# 2. Run smoke tests +genesis do my-env -- run-errand smoke-tests + +# 3. Check application logs +bosh -d my-env-cf logs api/0 --follow + +# 4. Verify external integrations +curl -H "Authorization: Bearer $(safe get secret/path:token)" \ + https://api.example.com/health +``` + +## Rollback Procedures + +### Immediate Rollback + +If rotation causes issues: + +```bash +# 1. Restore from backup +safe import < backup-before-rotation.json + +# 2. Redeploy with old secrets +genesis deploy my-env + +# 3. Verify services restored +genesis do my-env -- run-errand smoke-tests +``` + +### Partial Rollback + +For specific secrets: + +```bash +# Get old value from backup +OLD_VALUE=$(jq -r '.admin_password' backup-before-rotation.json) + +# Restore specific secret +safe set secret/us-east-1/prod/cf/admin_password value="$OLD_VALUE" + +# Redeploy +genesis deploy my-env +``` + +## Automation + +### Scheduled Rotation Script + +```bash +#!/bin/bash +# rotate-passwords.sh - Run monthly via cron + +set -e + +REPO="/home/genesis/cf-deployments" +ENVIRONMENTS="dev staging prod" +PASSWORDS="admin_password smoke_test_password autoscaler_password" + +cd $REPO + +for env in $ENVIRONMENTS; do + echo "Rotating passwords for $env" + + # Rotate passwords + genesis rotate-secrets $env $PASSWORDS + + # Deploy + genesis deploy $env --yes + + # Test + if ! genesis do $env -- run-errand smoke-tests; then + echo "ERROR: Smoke tests failed for $env" + exit 1 + fi + + echo "Successfully rotated $env" +done +``` + +### Certificate Expiration Monitoring + +```bash +#!/bin/bash +# check-certs.sh - Run daily + +THRESHOLD_DAYS=30 + +# Find expiring certificates +for env in $(genesis list); do + certs=$(safe find secret/$env | grep cert$) + + for cert in $certs; do + expires=$(safe x509 expires $cert --json | jq -r .not_after) + expires_epoch=$(date -d "$expires" +%s) + now_epoch=$(date +%s) + days_left=$(( ($expires_epoch - $now_epoch) / 86400 )) + + if [ $days_left -lt $THRESHOLD_DAYS ]; then + echo "WARNING: $cert expires in $days_left days" + # Send alert + fi + done +done +``` + +## Best Practices + +### 1. Regular Rotation Schedule + +- **Passwords**: Every 90 days +- **SSH Keys**: Every 180 days +- **Server Certificates**: 30 days before expiry +- **CA Certificates**: 1 year before expiry + +### 2. Test in Lower Environments + +```bash +# Test rotation procedure +genesis rotate-secrets dev admin_password +genesis deploy dev + +# If successful, proceed to staging and prod +``` + +### 3. Document External Dependencies + +```yaml +# In environment file comments +# admin_password used by: +# - CF CLI admin scripts +# - Monitoring system (update manually) +# - Backup scripts (auto-updated) +``` + +### 4. Use Maintenance Windows + +For critical rotations: +1. Schedule maintenance window +2. Notify users +3. Perform rotation +4. Verify thoroughly +5. Document completion + +### 5. Maintain Audit Trail + +```bash +# Before rotation +safe get secret/path | jq > audit/secret-before-$(date +%Y%m%d).json + +# After rotation +genesis rotate-secrets my-env secret-name | tee audit/rotation-$(date +%Y%m%d).log +``` + +## Troubleshooting + +### Service Won't Start + +```bash +# Check logs for auth errors +bosh -d my-env-cf logs failing-job/0 + +# Verify secret was rotated +safe get secret/path/to/password + +# Ensure deployment completed +bosh -d my-env-cf task +``` + +### External Integration Broken + +```bash +# Verify new credential format +safe get secret/path/api_key + +# Test credential manually +curl -H "Authorization: $(safe get secret/path:key)" \ + https://api.example.com + +# Check for hardcoded values +grep -r "old-password" /var/vcap/jobs/ +``` + +### Rollback Failed + +```bash +# Force redeploy with manifest +genesis manifest my-env > manifest.yml +bosh -d my-env-cf deploy manifest.yml \ + --vars-store=/dev/null \ + --recreate + +# Manual secret injection if needed +bosh -d my-env-cf ssh job/0 +# Update config files manually +``` + +Regular, well-planned rotation keeps your Genesis deployments secure while minimizing operational risk. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/secret-types.md b/lib/Genesis/Help/Topics/30-secrets-management/secret-types.md new file mode 100644 index 00000000..813bbbb5 --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/secret-types.md @@ -0,0 +1,434 @@ +# Secret Types + +Genesis supports various types of secrets for different use cases. Each type has specific generation parameters and storage formats. + +## Password Secrets + +### Basic Passwords + +Simple random password generation: + +```yaml +credentials: + base: + admin_password: random 32 +``` + +Generates a 32-character random password. + +### Advanced Password Options + +```yaml +credentials: + base: + db/password: + password: "random 64 fmt base64" + + api/key: + key: "random 40 allowed-chars a-zA-Z0-9_-" + + simple/pin: + pin: "random 6 allowed-chars 0-9" +``` + +Parameters: +- **Length**: Number of characters (e.g., `32`, `64`) +- **Format**: `fmt base64` for base64 encoding +- **Allowed chars**: Specify character set +- **Fixed**: Add `fixed` to prevent rotation + +### Password Storage + +Stored as simple key-value: +``` +secret/us-east-1/prod/cf/admin_password +└── value: "GeneratedPassword123!" +``` + +## SSH Keys + +### Standard SSH Keys + +```yaml +credentials: + base: + jumpbox/ssh: ssh 2048 + bastion/ssh: ssh 4096 fixed +``` + +Generates RSA keypair with specified bit size. + +### SSH Key Storage + +Stored with public and private keys: +``` +secret/us-east-1/prod/cf/jumpbox/ssh +├── private: "-----BEGIN RSA PRIVATE KEY-----..." +├── public: "ssh-rsa AAAAB3NzaC1yc2EA..." +├── fingerprint: "SHA256:..." +└── format: "openssh" +``` + +### Using SSH Keys + +```bash +# Extract private key +safe get secret/path/to/ssh:private > id_rsa +chmod 600 id_rsa + +# Get public key +safe get secret/path/to/ssh:public > id_rsa.pub + +# SSH using the key +ssh -i id_rsa user@host +``` + +## X.509 Certificates + +### Certificate Definition + +```yaml +certificates: + base: + ca: + valid_for: 10y + is_ca: true + + server: + valid_for: 1y + names: + - "*.system.cf.example.com" + - "*.apps.cf.example.com" + - "10.0.0.5" +``` + +### Certificate Parameters + +- **valid_for**: Duration (e.g., `1y`, `365d`, `8760h`) +- **is_ca**: Boolean for CA certificates +- **names**: DNS names and IPs (SAN entries) +- **signed_by**: Path to signing CA + +### Advanced Certificate Options + +```yaml +certificates: + haproxy: + ssl/ca: + is_ca: true + valid_for: "${params.ca_validity_period}" + + ssl/server: + signed_by: ssl/ca + names: "${params.haproxy_domains}" + valid_for: 90d + + mtls/client: + signed_by: ssl/ca + names: ["client.internal"] + valid_for: 30d +``` + +### Certificate Storage + +``` +secret/us-east-1/prod/cf/ssl/server +├── cert: "-----BEGIN CERTIFICATE-----..." +├── key: "-----BEGIN RSA PRIVATE KEY-----..." +├── ca: "-----BEGIN CERTIFICATE-----..." +├── combined: "cert + key concatenated" +└── chain: "cert + ca concatenated" +``` + +### Certificate Operations + +```bash +# View certificate details +safe x509 show secret/path/to/cert + +# Validate certificate +safe x509 validate secret/path/to/cert \ + --ca secret/path/to/ca + +# Check expiration +safe x509 expires secret/path/to/cert +``` + +## RSA Keys + +### RSA Key Generation + +```yaml +credentials: + base: + jwt/signing_key: rsa 4096 + encryption/key: rsa 2048 fixed +``` + +### RSA Key Storage + +``` +secret/us-east-1/prod/cf/jwt/signing_key +├── private: "-----BEGIN RSA PRIVATE KEY-----..." +├── public: "-----BEGIN PUBLIC KEY-----..." +└── format: "pem" +``` + +### Using RSA Keys + +```bash +# Extract for JWT libraries +safe get secret/path/jwt/signing_key:private > jwt.key +safe get secret/path/jwt/signing_key:public > jwt.pub + +# Convert formats if needed +openssl rsa -in jwt.key -pubout -out jwt.pub.pem +``` + +## DH Parameters + +### Diffie-Hellman Parameters + +```yaml +credentials: + base: + nginx/dhparams: dhparam 2048 + haproxy/dhparams: dhparam 4096 fixed +``` + +### DH Storage + +``` +secret/us-east-1/prod/cf/nginx/dhparams +└── value: "-----BEGIN DH PARAMETERS-----..." +``` + +## UUIDs + +### UUID Generation + +```yaml +credentials: + base: + consul/encryption_key: + key: uuid + + bbs/encryption_key: + key: "uuid v4" + + app/instance_id: + id: "uuid v4 namespace dns name app.example.com" +``` + +### UUID Types + +- **v4**: Random UUID (most common) +- **v5**: Namespace-based (deterministic) + +### UUID Storage + +``` +secret/us-east-1/prod/cf/consul/encryption_key +└── key: "550e8400-e29b-41d4-a716-446655440000" +``` + +## User-Provided Secrets + +### Definition + +For secrets that can't be generated: + +```yaml +provided: + base: + external/api: + type: generic + keys: + client_id: + type: string + prompt: "Enter the OAuth client ID" + + client_secret: + type: string + sensitive: true + prompt: "Enter the OAuth client secret" + + private_key: + type: string + multiline: true + prompt: "Paste the private key (Ctrl-D when done)" +``` + +### Provided Secret Parameters + +- **type**: Always `generic` currently +- **sensitive**: Hide input (for passwords) +- **multiline**: Accept multiple lines +- **prompt**: User prompt message +- **fixed**: Prevent regeneration + +## Complex Secret Structures + +### Multi-Component Secrets + +Some secrets have multiple related parts: + +```yaml +# Database with multiple credentials +credentials: + base: + db/admin: + username: "admin" + password: "random 32" + + db/app: + username: "app_user" + password: "random 32" + + db/read_only: + username: "reader" + password: "random 24" +``` + +### Hierarchical Secrets + +Organize related secrets: + +``` +secret/us-east-1/prod/cf/ +├── db/ +│ ├── admin/ +│ │ ├── username +│ │ └── password +│ ├── app/ +│ │ ├── username +│ │ └── password +│ └── uri # Constructed from components +├── nats/ +│ ├── username +│ ├── password +│ └── client_cert/ +│ ├── cert +│ └── key +``` + +## Secret Validation + +### Built-in Validation + +Genesis validates secrets during generation: + +```yaml +# This will fail - names required for non-CA certs +certificates: + base: + bad/cert: + valid_for: 1y + # Missing: names +``` + +### Manual Validation + +```bash +# Check certificate validity +safe x509 validate secret/path/to/cert + +# Verify SSH key +ssh-keygen -l -f <(safe get secret/path/to/ssh:public) + +# Test password complexity +safe get secret/path/to/password | pwscore +``` + +## Secret References + +### Using Parameters + +Reference kit parameters in secret definitions: + +```yaml +# In kit.yml +certificates: + base: + haproxy/ssl: + valid_for: "${params.cert_validity_period}" + names: "${params.haproxy_domains}" + +# In environment file +params: + cert_validity_period: 90d + haproxy_domains: + - haproxy.example.com + - lb.example.com +``` + +### Cross-References + +Reference other secrets: + +```yaml +certificates: + base: + intermediate/ca: + is_ca: true + signed_by: root/ca # References another cert + + server/cert: + signed_by: intermediate/ca + names: ["web.example.com"] +``` + +## Best Practices + +### 1. Use Appropriate Types + +Choose the right secret type: +- Passwords for authentication +- SSH keys for system access +- Certificates for TLS +- RSA keys for signing/encryption + +### 2. Set Proper Lifetimes + +```yaml +certificates: + base: + ca: + valid_for: 10y # Long for CAs + server: + valid_for: 90d # Short for servers +``` + +### 3. Use Fixed Sparingly + +Only use `fixed` for: +- External integrations +- Shared secrets +- Keys that can't be rotated + +### 4. Organize Hierarchically + +```yaml +credentials: + base: + # Group by component + router/password: random 32 + router/ssl/cert: ... + + # Group by function + admin/ui_password: random 32 + admin/api_key: random 64 +``` + +### 5. Document Requirements + +```yaml +provided: + slack: + notifications/webhook: + keys: + url: + prompt: "Enter Slack webhook URL (from https://slack.com/apps/)" +``` + +Understanding these secret types helps you properly secure your Genesis deployments while maintaining operational simplicity. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/30-secrets-management/vault-integration.md b/lib/Genesis/Help/Topics/30-secrets-management/vault-integration.md new file mode 100644 index 00000000..4473b991 --- /dev/null +++ b/lib/Genesis/Help/Topics/30-secrets-management/vault-integration.md @@ -0,0 +1,492 @@ +# Vault Integration + +Genesis uses HashiCorp Vault as its primary secret storage backend. This guide covers setup, configuration, and operational procedures for Vault with Genesis. + +## Vault Setup + +### Quick Start (Development) + +For testing, use the Genesis built-in Vault: + +```bash +# Start a dev Vault instance +safe init + +# Target and authenticate +safe target dev http://127.0.0.1:8201 +safe auth + +# Verify connection +safe status +``` + +### Production Deployment + +Deploy a production Vault cluster using Genesis: + +```bash +# Initialize Vault deployment repository +genesis init --kit vault my-vault-deployments +cd my-vault-deployments + +# Create production environment +genesis new prod-vault + +# Deploy +genesis deploy prod-vault +``` + +## Connecting Genesis to Vault + +### Environment Variables + +Genesis uses these variables to connect to Vault: + +```bash +# Vault server address +export VAULT_ADDR=https://vault.example.com:8200 + +# Skip TLS verification (dev only!) +export VAULT_SKIP_VERIFY=1 + +# Authentication token (not recommended) +export VAULT_TOKEN=s.abcdef123456 + +# Namespace (Vault Enterprise) +export VAULT_NAMESPACE=genesis +``` + +### Safe CLI Configuration + +The `safe` CLI manages Vault targets: + +```bash +# Add a Vault target +safe target add prod https://vault.example.com:8200 + +# List targets +safe targets + +# Switch targets +safe target prod + +# Authenticate +safe auth +``` + +### Authentication Methods + +#### Token Authentication + +```bash +# Interactive login +safe auth + +# Using existing token +safe auth token +``` + +#### GitHub Authentication + +```bash +# Configure GitHub auth in Vault +safe auth-configure github \ + --organization=myorg \ + --team=ops-team + +# Login with GitHub +safe auth github +``` + +#### LDAP Authentication + +```bash +# Configure LDAP +safe auth-configure ldap \ + --url=ldap://ldap.example.com \ + --binddn="cn=vault,ou=service,dc=example,dc=com" \ + --userdn="ou=users,dc=example,dc=com" + +# Login with LDAP +safe auth ldap +``` + +## Secret Paths + +### Standard Genesis Paths + +Genesis organizes secrets hierarchically: + +``` +/secret/// +├── admin_password +├── ca_cert +├── db/ +│ ├── username +│ └── password +└── ssl/ + ├── cert + ├── key + └── ca +``` + +### Exodus Data + +Shared deployment information: + +``` +/secret/exodus/// +├── url +├── username +├── password +└── ca_cert +``` + +### Custom Paths + +Override default paths in environment files: + +```yaml +genesis: + secrets_mount: secret/custom + secrets_slug: prod/cf + exodus_mount: secret/shared + exodus_slug: cf-prod +``` + +## Vault Policies + +### Basic Policy Structure + +```hcl +# Read-only access to production +path "secret/prod/*" { + capabilities = ["read", "list"] +} + +# Full access to development +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Deny access to specific paths +path "secret/prod/*/admin_password" { + capabilities = ["deny"] +} +``` + +### Genesis-Specific Policies + +#### Operator Policy + +```hcl +# Full access to all Genesis secrets +path "secret/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Access to Vault tools +path "sys/tools/*" { + capabilities = ["read"] +} + +# Mount management +path "sys/mounts/*" { + capabilities = ["read", "list"] +} +``` + +#### Developer Policy + +```hcl +# Read dev/staging, no prod access +path "secret/dev/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/staging/*" { + capabilities = ["read", "list"] +} + +path "secret/prod/*" { + capabilities = ["deny"] +} +``` + +#### CI/CD Policy + +```hcl +# Read-only for deployments +path "secret/+/+/+/*" { + capabilities = ["read"] +} + +# Write exodus data +path "secret/exodus/*" { + capabilities = ["create", "read", "update"] +} +``` + +### Applying Policies + +```bash +# Create policy +safe policy write operator-policy policy.hcl + +# Assign to user +safe auth token create \ + --policy=operator-policy \ + --display-name="John Doe" + +# Assign to GitHub team +safe write auth/github/map/teams/ops-team \ + value=operator-policy +``` + +## Secret Operations + +### Viewing Secrets + +```bash +# List secrets for environment +safe tree secret/us-east-1/prod/cf + +# View specific secret +safe get secret/us-east-1/prod/cf/admin_password + +# Export all secrets +safe export secret/us-east-1/prod/cf > cf-secrets.json +``` + +### Manual Secret Management + +```bash +# Set a secret +safe set secret/us-east-1/prod/cf/api_key value=abc123 + +# Generate password +safe gen secret/us-east-1/prod/cf/new_password + +# Create SSH key +safe ssh secret/us-east-1/prod/cf/bastion_ssh + +# Issue certificate +safe x509 issue secret/us-east-1/prod/cf/web_cert \ + --ca secret/us-east-1/prod/cf/ca \ + --name web.example.com \ + --ttl 365d +``` + +### Copying Secrets + +```bash +# Copy between environments +safe cp \ + secret/us-east-1/dev/cf \ + secret/us-east-1/staging/cf + +# Copy specific secret +safe cp \ + secret/us-east-1/prod/cf/ca \ + secret/us-west-2/prod/cf/ca +``` + +## High Availability + +### Multi-Node Vault + +Deploy Vault in HA mode: + +```yaml +# In Vault environment file +params: + vault_num_instances: 3 + + consul_servers: + - 10.0.1.10 + - 10.0.1.11 + - 10.0.1.12 +``` + +### Backup and Recovery + +```bash +# Backup Vault data +genesis do vault-prod -- backup + +# Create snapshot (Vault Enterprise) +vault operator raft snapshot save backup.snap + +# Restore from backup +genesis do vault-prod -- restore backup.tar.gz +``` + +## Monitoring and Maintenance + +### Health Checks + +```bash +# Check Vault status +safe status + +# Detailed status +vault status -format=json + +# Check seal status +safe sealed? +``` + +### Audit Logging + +Enable audit logging: + +```bash +# File audit backend +vault audit enable file \ + file_path=/var/log/vault/audit.log + +# Syslog audit backend +vault audit enable syslog \ + tag="vault" \ + facility="LOCAL7" +``` + +### Performance Tuning + +```bash +# Enable metrics +vault write sys/config/telemetry \ + prometheus_retention_time="30s" \ + disable_hostname=true + +# Monitor key metrics +- vault.core.handle_request +- vault.token.lookup +- vault.barrier.get +- vault.barrier.put +``` + +## Troubleshooting + +### Connection Issues + +```bash +# Test connectivity +safe target check + +# Verify environment +env | grep VAULT + +# Check TLS +openssl s_client -connect vault.example.com:8200 +``` + +### Authentication Problems + +```bash +# Check token validity +safe token + +# Renew token +safe renew + +# Re-authenticate +safe auth +``` + +### Permission Denied + +```bash +# Check policies +safe vault policy read my-policy + +# List token policies +vault token lookup + +# Test specific path +safe exists secret/path/to/test +``` + +## Best Practices + +### 1. Use Policies + +Always use policies instead of root tokens: +- Create specific policies for each role +- Follow principle of least privilege +- Regularly audit policy assignments + +### 2. Enable Auditing + +```bash +vault audit enable file \ + file_path=/vault/logs/audit.log \ + log_raw=true +``` + +### 3. Regular Backups + +```bash +# Automated backup script +#!/bin/bash +genesis do vault-prod -- backup +aws s3 cp vault-backup.tar.gz s3://backups/vault/ +``` + +### 4. Monitor Unseal Keys + +- Distribute unseal keys securely +- Never store together +- Regular key rotation +- Use auto-unseal when possible + +### 5. TLS Everywhere + +- Valid certificates on Vault +- Verify certificates in production +- Use mTLS for added security + +## Integration Examples + +### CI/CD Pipeline + +```yaml +# Concourse pipeline +resources: +- name: secrets + type: vault + source: + url: ((vault_addr)) + path: secret/us-east-1/prod + client_token: ((vault_token)) +``` + +### Application Integration + +```python +# Python example +import hvac + +client = hvac.Client( + url='https://vault.example.com:8200', + token=os.environ['VAULT_TOKEN'] +) + +secret = client.read('secret/data/app/database') +db_password = secret['data']['data']['password'] +``` + +### Kubernetes Integration + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: db-creds + annotations: + vault.hashicorp.com/agent-inject: "true" + vault.hashicorp.com/agent-inject-secret-db: "secret/app/db" + vault.hashicorp.com/role: "app" +``` + +Proper Vault integration ensures your Genesis deployments remain secure while maintaining operational efficiency. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/.keep b/lib/Genesis/Help/Topics/50-kits/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/50-kits/authoring-kits.md b/lib/Genesis/Help/Topics/50-kits/authoring-kits.md new file mode 100644 index 00000000..fedd7767 --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/authoring-kits.md @@ -0,0 +1,599 @@ +# Authoring Genesis Kits + +This guide covers creating your own Genesis kits to package deployment knowledge for reuse across teams and environments. + +## Getting Started + +### When to Create a Kit + +Create a kit when: +- Deploying software not covered by existing kits +- Standardizing deployment patterns across teams +- Packaging proprietary software deployments +- Sharing deployment expertise + +### Kit Philosophy + +Remember these principles: + +1. **Kit Authors are Trusted** - You have full control +2. **User Parameters under `params`** - Keep configuration organized +3. **Secrets in Vault** - Never hardcode credentials +4. **Multiple Ways to Deploy** - Support variations via features + +### Development Setup + +```bash +# Create kit skeleton +genesis create-kit my-software + +# Directory structure created: +my-software-genesis-kit/ +├── kit.yml # Kit metadata +├── manifests/ # BOSH manifests +│ └── base.yml +└── hooks/ # Lifecycle scripts + └── blueprint + +cd my-software-genesis-kit +``` + +## Kit Structure + +### kit.yml - Metadata + +Define your kit's identity and behavior: + +```yaml +name: my-software +version: 0.1.0 +author: Your Name +docs: https://github.com/yourorg/my-software-genesis-kit +code: https://github.com/yourorg/my-software-genesis-kit + +description: | + Deploys My Software, a revolutionary application that + solves all your problems. + +# Define required credentials +credentials: + base: + admin: + password: random 32 + database: + password: random 64 fmt base64 + +# Define certificates +certificates: + base: + server: + ca: + valid_for: 10y + web: + valid_for: 1y + names: + - "*.${params.base_domain}" +``` + +### Base Manifest + +Start with `manifests/base.yml`: + +```yaml +--- +name: (( grab params.env )) + +releases: +- name: my-software + version: "1.2.3" + url: https://github.com/org/releases/download/v1.2.3/release.tgz + sha1: abc123... + +stemcells: +- alias: default + os: ubuntu-jammy + version: latest + +update: + canaries: 1 + max_in_flight: 1 + canary_watch_time: 30000-120000 + update_watch_time: 30000-120000 + +instance_groups: +- name: my-software + instances: (( grab params.instances || 1 )) + vm_type: (( grab params.vm_type || "default" )) + stemcell: default + networks: + - name: (( grab params.network || "default" )) + jobs: + - name: my-software + release: my-software + properties: + admin_password: (( vault "secret/" params.vault "/admin:password" )) + database_password: (( vault "secret/" params.vault "/database:password" )) +``` + +## Features + +### Adding Features + +Create feature manifests in `manifests/features/`: + +```yaml +# manifests/features/ha.yml +--- +# High Availability Feature +- type: replace + path: /instance_groups/name=my-software/instances + value: 3 + +- type: replace + path: /instance_groups/name=my-software/jobs/name=my-software/properties/cluster? + value: + enabled: true + members: 3 +``` + +```yaml +# manifests/features/monitoring.yml +--- +# Prometheus Monitoring +- type: replace + path: /instance_groups/name=my-software/jobs/- + value: + name: prometheus_exporter + release: prometheus + properties: + prometheus: + port: 9100 +``` + +### Feature-Specific Secrets + +```yaml +# kit.yml +credentials: + base: + admin: + password: random 32 + + ldap: # Only with LDAP feature + ldap/bind: + password: random 32 + + ssl: # Only with SSL feature + ssl/server: cert +``` + +## Lifecycle Hooks + +### blueprint Hook + +Controls manifest generation: + +```bash +#!/bin/bash +# hooks/blueprint +set -eu + +# Base manifest is always first +declare -a manifests +manifests+=( "manifests/base.yml" ) + +# Process requested features +for want in ${GENESIS_REQUESTED_FEATURES}; do + case "$want" in + ha|monitoring|ssl) + manifests+=( "manifests/features/$want.yml" ) + ;; + *) + echo >&2 "Unrecognized feature: $want" + exit 1 + ;; + esac +done + +# Output manifest list +printf "%s\n" "${manifests[@]}" +``` + +### new Hook + +Interactive environment setup: + +```bash +#!/bin/bash +# hooks/new +set -eu + +# Prompt for basic configuration +prompt_for "base_domain" \ + "What is your base domain?" \ + --validation "/^[a-z0-9.-]+$/" + +# Feature selection +feature_wanted "ha" \ + "Do you want High Availability mode?" + +if feature_wanted "ha"; then + prompt_for "instances" \ + "How many instances?" \ + --default 3 \ + --validation "/^[3-9]$/" +else + prompt_for "instances" \ + "How many instances?" \ + --default 1 +fi + +# Infrastructure features +describe "What infrastructure are you deploying to?" +features+=( \ + "$(prompt_for_choice \ + "Infrastructure?" \ + "aws" \ + "azure" \ + "gcp" \ + "vsphere" \ + "openstack" \ + )" \ +) + +# Save configuration +genesis_config_set params.base_domain "$base_domain" +genesis_config_set params.instances "$instances" +``` + +### check Hook + +Pre-deployment validation: + +```bash +#!/bin/bash +# hooks/check +set -eu + +# Validate cloud config +if ! bosh_cloud_config_has vm_type $(genesis_config_get params.vm_type); then + describe >&2 \ + "VM type '#R{$(genesis_config_get params.vm_type)}' not found in cloud config" + exit 1 +fi + +# Check for required secrets +if want_feature "provided-cert"; then + if ! safe exists "$GENESIS_SECRETS_BASE/ssl/server"; then + describe >&2 \ + "Feature 'provided-cert' requires certificate at $GENESIS_SECRETS_BASE/ssl/server" + exit 1 + fi +fi + +describe "Environment looks good!" +``` + +### info Hook + +Display deployment information: + +```bash +#!/bin/bash +# hooks/info +set -eu + +# Get deployment info +FQDN="$(genesis_config_get params.base_domain)" +PASS="$(safe get "$GENESIS_SECRETS_BASE/admin:password")" + +describe "#G{My Software Information}" +echo +describe " URL: #C{https://app.$FQDN}" +describe " Username: #C{admin}" +describe " Password: #C{$PASS}" +echo +describe "To visit the web UI, run:" +echo +describe " #G{genesis do $GENESIS_ENVIRONMENT visit-ui}" +``` + +### addon Hook + +Operational tasks: + +```bash +#!/bin/bash +# hooks/addon +set -eu + +case "$GENESIS_ADDON_SCRIPT" in + visit-ui) + URL="https://app.$(genesis_config_get params.base_domain)" + describe "Opening $URL in your browser..." + open "$URL" || xdg-open "$URL" || echo "Please visit: $URL" + ;; + + backup) + describe "Running backup..." + genesis bosh run-errand backup + ;; + + list) + describe "Available addons:" + describe " #G{visit-ui} - Open the web interface" + describe " #G{backup} - Run a backup" + ;; + + *) + describe >&2 "Unknown addon: $GENESIS_ADDON_SCRIPT" + exit 1 + ;; +esac +``` + +## Development Workflow + +### Local Development + +Use the `dev/` directory for rapid iteration: + +```bash +# In your deployment repo +mkdir dev +cp -r /path/to/my-software-genesis-kit/* dev/ + +# Use dev kit +cat > test.yml <&2 \ + "#R{Missing required parameter 'base_domain'}" \ + "" \ + "Please add to your environment file:" \ + " #C{params:}" \ + " #C{ base_domain: example.com}" + exit 1 +fi +``` + +### 4. Feature Organization + +Group related changes: +``` +manifests/features/ +├── aws.yml # IaaS-specific +├── azure.yml +├── ha.yml # Architecture +├── standalone.yml +├── monitoring.yml # Operations +└── shield.yml +``` + +### 5. Version Management + +```yaml +# kit.yml +name: my-software +version: 1.0.0 # Semantic versioning + +# Track BOSH release versions +releases: + my-software: 2.3.4 + prometheus: 25.0.0 +``` + +## Publishing Your Kit + +### Prepare for Release + +1. **Test thoroughly** across scenarios +2. **Document** in README.md +3. **Version** appropriately +4. **Include examples** + +### Compile and Release + +```bash +# Compile kit +genesis compile-kit \ + --version 1.0.0 \ + --name my-software + +# Creates: my-software-1.0.0.tar.gz + +# Upload to GitHub releases +# Tag repository with v1.0.0 +``` + +### Sharing with Community + +1. Open source on GitHub +2. Follow naming convention: `*-genesis-kit` +3. Submit to Genesis community registry +4. Announce in Genesis Slack + +## Troubleshooting + +### Manifest Generation Issues + +```bash +# Debug blueprint hook +cd dev +GENESIS_REQUESTED_FEATURES="ha monitoring" ./hooks/blueprint + +# Check generated manifest +genesis manifest test -P | spruce diff base.yml - +``` + +### Secret Generation Problems + +```bash +# Check what secrets are needed +genesis check-secrets test + +# Manually generate if needed +safe gen "$VAULT_PREFIX/test/admin" password +``` + +### Hook Failures + +```bash +# Run hooks manually +cd dev +export GENESIS_ENVIRONMENT=test +export GENESIS_SECRETS_BASE=secret/test/my-software +./hooks/info +``` + +## Next Steps + +- Study existing kits for patterns +- Start with simple kits +- Iterate based on user feedback +- Contribute improvements back + +Creating kits shares your operational knowledge and makes deployments consistent and reliable across your organization. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/available-kits.md b/lib/Genesis/Help/Topics/50-kits/available-kits.md new file mode 100644 index 00000000..cb82f5c6 --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/available-kits.md @@ -0,0 +1,376 @@ +# Available Genesis Kits + +This catalog lists official Genesis kits maintained by the Genesis Community, along with their primary use cases and key features. + +## Infrastructure Kits + +### BOSH Director Kit + +**Repository**: [bosh-genesis-kit](https://github.com/genesis-community/bosh-genesis-kit) + +Deploy BOSH directors for managing your infrastructure. + +**Key Features**: +- `aws`, `azure`, `gcp`, `vsphere`, `openstack` - IaaS support +- `proto` - Proto-BOSH for bootstrapping +- `bosh-init` - Legacy create-env support +- `bbr` - BOSH Backup & Restore +- `vault-credhub-proxy` - CredHub integration + +**Common Usage**: +```yaml +kit: + name: bosh + features: + - aws + - proto + - vault-credhub-proxy +``` + +### Vault Kit + +**Repository**: [vault-genesis-kit](https://github.com/genesis-community/vault-genesis-kit) + +Deploy HashiCorp Vault for secrets management. + +**Key Features**: +- `consul`, `raft`, `file` - Storage backends +- `auto-unseal` - Cloud KMS unsealing +- `ha` - High availability mode +- `monitoring` - Prometheus metrics + +**Common Usage**: +```yaml +kit: + name: vault + features: + - raft + - auto-unseal + - monitoring +``` + +## Platform Kits + +### Cloud Foundry Kit + +**Repository**: [cf-genesis-kit](https://github.com/genesis-community/cf-genesis-kit) + +Deploy full Cloud Foundry platforms. + +**Key Features**: +- `haproxy`, `routing-api` - Routing options +- `postgres`, `mysql` - Database backends +- `azure-blobstore`, `s3-blobstore` - Blob storage +- `container-routing`, `loggregator-forwarder-agent` +- `small-footprint`, `minimum-vms` - Sizing options + +**Common Usage**: +```yaml +kit: + name: cf + features: + - haproxy + - postgres + - s3-blobstore + - routing-api +``` + +### Kubernetes Kit + +**Repository**: [k8s-genesis-kit](https://github.com/genesis-community/k8s-genesis-kit) + +Deploy Kubernetes clusters with BOSH. + +**Key Features**: +- `flannel`, `calico` - Network providers +- `dashboard` - Kubernetes dashboard +- `monitoring` - Cluster monitoring +- `ingress` - Ingress controller + +**Common Usage**: +```yaml +kit: + name: k8s + features: + - flannel + - dashboard + - monitoring +``` + +## CI/CD Kits + +### Concourse Kit + +**Repository**: [concourse-genesis-kit](https://github.com/genesis-community/concourse-genesis-kit) + +Deploy Concourse CI/CD systems. + +**Key Features**: +- `github-oauth`, `cf-auth` - Authentication +- `prometheus` - Metrics exporter +- `vault` - Vault integration +- `workers` - External workers +- `no-tls`, `provided-cert` - Certificate options + +**Common Usage**: +```yaml +kit: + name: concourse + features: + - github-oauth + - prometheus + - vault +``` + +### Jenkins Kit + +**Repository**: [jenkins-genesis-kit](https://github.com/genesis-community/jenkins-genesis-kit) + +Deploy Jenkins automation servers. + +**Key Features**: +- `github-oauth` - GitHub authentication +- `ldap` - LDAP integration +- `slaves` - Distributed builds +- `backup` - Automated backups + +## Database Kits + +### PostgreSQL Kit + +**Repository**: [postgres-genesis-kit](https://github.com/genesis-community/postgres-genesis-kit) + +Deploy standalone PostgreSQL databases. + +**Key Features**: +- `ha` - High availability +- `monitoring` - Database metrics +- `backups` - Automated backups +- `tls` - Encrypted connections + +**Common Usage**: +```yaml +kit: + name: postgres + features: + - ha + - monitoring + - backups +``` + +### Redis Kit + +**Repository**: [redis-genesis-kit](https://github.com/genesis-community/redis-genesis-kit) + +Deploy Redis key-value stores. + +**Key Features**: +- `cluster` - Redis cluster mode +- `sentinel` - High availability +- `persistent` - Disk persistence +- `shield` - Backup integration + +## Monitoring Kits + +### Prometheus Kit + +**Repository**: [prometheus-genesis-kit](https://github.com/genesis-community/prometheus-genesis-kit) + +Deploy Prometheus monitoring stacks. + +**Key Features**: +- `grafana` - Visualization +- `alertmanager` - Alert routing +- `node-exporter` - System metrics +- `postgres-exporter`, `mysql-exporter` - Database monitoring + +**Common Usage**: +```yaml +kit: + name: prometheus + features: + - grafana + - alertmanager + - node-exporter +``` + +### Blacksmith Kit + +**Repository**: [blacksmith-genesis-kit](https://github.com/genesis-community/blacksmith-genesis-kit) + +Deploy on-demand service brokers. + +**Key Features**: +- `redis-forge` - Redis services +- `postgres-forge` - PostgreSQL services +- `rabbitmq-forge` - RabbitMQ services +- `cf-integration` - Cloud Foundry broker + +## Backup & Recovery Kits + +### Shield Kit + +**Repository**: [shield-genesis-kit](https://github.com/genesis-community/shield-genesis-kit) + +Deploy Shield backup/restore solutions. + +**Key Features**: +- `postgres`, `mysql` - Database backends +- `minio` - Object storage +- `monitoring` - Backup metrics +- `oauth` - External authentication + +**Common Usage**: +```yaml +kit: + name: shield + features: + - postgres + - monitoring + - oauth +``` + +### Minio Kit + +**Repository**: [minio-genesis-kit](https://github.com/genesis-community/minio-genesis-kit) + +Deploy Minio S3-compatible object storage. + +**Key Features**: +- `distributed` - Multi-node setup +- `tls` - Encrypted connections +- `monitoring` - Storage metrics + +## Utility Kits + +### Jumpbox Kit + +**Repository**: [jumpbox-genesis-kit](https://github.com/genesis-community/jumpbox-genesis-kit) + +Deploy secure bastion hosts. + +**Key Features**: +- `openvpn` - VPN server +- `shield` - Backup agent +- `all-tools` - Extra utilities +- `golang`, `ruby` - Development tools + +**Common Usage**: +```yaml +kit: + name: jumpbox + features: + - openvpn + - all-tools +``` + +### Docker Registry Kit + +**Repository**: [docker-registry-genesis-kit](https://github.com/genesis-community/docker-registry-genesis-kit) + +Deploy private Docker registries. + +**Key Features**: +- `s3-storage`, `swift-storage` - Backend storage +- `auth` - Authentication +- `proxy` - Pull-through cache +- `monitoring` - Registry metrics + +## Using Official Kits + +### Installation + +All official kits are automatically available: + +```bash +# List all kits +genesis kits + +# Initialize with kit +genesis init --kit +``` + +### Version Selection + +Check available versions: + +```bash +# Show kit versions +genesis info --versions + +# Use specific version +kit: + version: 2.3.0 # Recommended for production +``` + +### Getting Help + +For each kit: + +```bash +# View documentation +genesis info + +# See available features +genesis info --features + +# Check parameters +genesis info --params +``` + +## Community Kits + +Beyond official kits, community members create kits for: +- Custom applications +- Proprietary software +- Specialized configurations + +Find community kits: +- Search GitHub for `*-genesis-kit` +- Check Genesis community forums +- Ask in Genesis Slack + +## Creating Your Own Kit + +If you need a kit that doesn't exist: + +1. **Check existing kits** - Maybe adapt one +2. **Use generic kit** - For simple cases +3. **Create new kit** - See [Authoring Kits](authoring-kits.md) + +## Kit Selection Guide + +### For New Users + +Start with these well-documented kits: +1. **BOSH** - Essential infrastructure +2. **Vault** - Secrets management +3. **Concourse** - CI/CD pipelines +4. **Jumpbox** - Secure access + +### For Cloud Foundry + +Complete CF deployment stack: +1. **BOSH** - Infrastructure layer +2. **Vault** - Secrets backend +3. **Postgres** - CF database +4. **CF** - Cloud Foundry itself +5. **Shield** - Backup solution + +### For Kubernetes + +Kubernetes on BOSH: +1. **BOSH** - Infrastructure +2. **Vault** - Secrets +3. **K8s** - Kubernetes cluster +4. **Prometheus** - Monitoring + +## Support + +For kit issues: +- Check kit repository issues +- Ask in Genesis Slack +- Consult kit documentation +- Review kit release notes + +Official kits are actively maintained and tested across common deployment scenarios. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/features.md b/lib/Genesis/Help/Topics/50-kits/features.md new file mode 100644 index 00000000..328b43e3 --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/features.md @@ -0,0 +1,544 @@ +# Kit Features + +Features are optional components in Genesis kits that allow you to customize deployments for different scenarios. This guide explains how features work and how to use them effectively. + +## Understanding Features + +### What Are Features? + +Features are modular extensions to a kit's base configuration: +- Add or modify deployment components +- Enable integrations with external systems +- Adapt to different infrastructures +- Toggle functionality on/off + +### How Features Work + +When you enable a feature: +1. Genesis includes additional YAML files +2. New parameters may be required +3. Different secrets might be generated +4. Validation rules can change + +## Feature Types + +### Infrastructure Features + +Adapt to different IaaS providers: + +```yaml +kit: + features: + - aws # Amazon Web Services + - azure # Microsoft Azure + - gcp # Google Cloud Platform + - vsphere # VMware vSphere + - openstack # OpenStack +``` + +Each provides: +- IaaS-specific resource types +- Network configurations +- Storage options +- Instance metadata + +### Architectural Features + +Change deployment topology: + +```yaml +kit: + features: + # High Availability + - ha # Multi-instance, clustered + - standalone # Single instance + + # Scaling + - minimum-vms # Colocate jobs + - distributed # Separate job instances +``` + +### Storage Features + +Different backend options: + +```yaml +# Vault kit example +kit: + features: + - consul # Consul storage backend + - raft # Integrated Raft storage + - file # File-based (dev only) + +# CF kit example +kit: + features: + - postgres # PostgreSQL database + - mysql # MySQL database + - external-db # User-provided database +``` + +### Security Features + +Enhanced security options: + +```yaml +kit: + features: + # Authentication + - ldap # LDAP integration + - github-oauth # GitHub OAuth + - uaa # UAA integration + + # Certificates + - self-signed-cert # Generate certificates + - provided-cert # User-provided certificates + + # Encryption + - encryption-at-rest + - mtls # Mutual TLS +``` + +### Operational Features + +Monitoring and maintenance: + +```yaml +kit: + features: + # Monitoring + - monitoring # Prometheus exporters + - logging # Enhanced logging + + # Backup + - shield # Shield backup agent + - native-backup # Built-in backup + + # Debugging + - debug # Debug logging + - trace # Trace-level output +``` + +## Feature Dependencies + +### Mutually Exclusive Features + +Some features cannot be used together: + +```yaml +# Error - multiple databases +kit: + features: + - postgres # Can't use both + - mysql # database types + +# Error - conflicting architectures +kit: + features: + - ha # Can't be both HA + - standalone # and standalone +``` + +### Required Combinations + +Some features require others: + +```yaml +# github-oauth requires UAA +kit: + features: + - uaa # Required by + - github-oauth # this feature +``` + +### Implicit Features + +Features activated automatically: + +```yaml +# If no storage backend specified +# Might implicitly activate +internal-storage +kit: + features: [] # +internal-storage added +``` + +## Feature Parameters + +### Feature-Specific Parameters + +Features often introduce new parameters: + +```yaml +# With 'aws' feature +params: + aws_region: us-east-1 + aws_default_sgs: [bosh] + +# With 'github-oauth' feature +params: + github_client_id: abc123 + github_client_secret: ((github_oauth_secret)) + github_orgs: [myorg] +``` + +### Conditional Parameters + +Parameters that only apply with certain features: + +```yaml +params: + # Always required + base_domain: example.com + + # Only with 'ha' feature + cluster_members: 3 + + # Only with 'postgres' feature + postgres_version: "13" +``` + +## Feature Discovery + +### List Available Features + +```bash +# During environment creation +genesis new prod-env +> Select features to enable: +> [ ] aws - AWS infrastructure support +> [ ] monitoring - Prometheus metrics +> [ ] shield - Backup integration +> [x] ha - High availability mode + +# From kit info +genesis info vault --features +``` + +### Feature Documentation + +```bash +# Get feature details +genesis info vault --feature consul + +# Shows: +# - Description +# - Required parameters +# - Dependencies +# - Conflicts +``` + +### In Kit Source + +```bash +# Feature manifests +ls .genesis/kits/vault-1.5.0/manifests/features/ +consul.yml +monitoring.yml +provided-cert.yml +``` + +## Common Feature Patterns + +### Progressive Enhancement + +Start simple, add features: + +```yaml +# Initial deployment +kit: + name: concourse + version: 5.0.0 + features: [] + +# Add authentication +kit: + features: + - github-oauth + +# Add monitoring +kit: + features: + - github-oauth + - prometheus + +# Add backups +kit: + features: + - github-oauth + - prometheus + - shield +``` + +### Environment-Specific Features + +Different features per environment: + +```yaml +# development.yml +kit: + features: + - minimum-vms + - self-signed-cert + +# staging.yml +kit: + features: + - ha + - self-signed-cert + - monitoring + +# production.yml +kit: + features: + - ha + - provided-cert + - monitoring + - shield +``` + +### Infrastructure Adaptation + +```yaml +# AWS deployment +kit: + features: + - aws + - ha + - monitoring + +# vSphere deployment +kit: + features: + - vsphere + - ha + - monitoring + - nfs-volume-services +``` + +## Feature Implementation + +### How Kits Define Features + +In the kit's `manifests/features/` directory: + +```yaml +# manifests/features/monitoring.yml +- type: replace + path: /instance_groups/name=vault/jobs/- + value: + name: prometheus_exporter + release: prometheus + properties: + prometheus: + port: 9100 +``` + +### Feature Activation + +The `blueprint` hook determines active features: + +```bash +#!/bin/bash +# hooks/blueprint + +# Base manifest always included +manifest_files="manifests/base.yml" + +# Add feature manifests +for feature in $GENESIS_REQUESTED_FEATURES; do + manifest_files="$manifest_files manifests/features/$feature.yml" +done + +echo "$manifest_files" +``` + +### Conditional Logic + +Features can include logic: + +```yaml +# Only add if using PostgreSQL +- type: replace + path: /instance_groups/name=postgres? + value: + name: postgres + instances: (( grab params.postgres_instances || 1 )) +``` + +## Advanced Feature Usage + +### Custom Features + +Add your own features via ops files: + +```bash +# Create custom feature +mkdir -p ops +cat > ops/custom-logging.yml < with-feature.yml + +# Remove feature and compare +# Edit environment file +genesis manifest my-env > without-feature.yml + +diff without-feature.yml with-feature.yml +``` + +## Summary + +Features provide powerful customization: +- Adapt to any infrastructure +- Enable optional functionality +- Maintain clean base configurations +- Share common patterns + +Use them wisely to create flexible, maintainable deployments. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/index.md b/lib/Genesis/Help/Topics/50-kits/index.md new file mode 100644 index 00000000..2229836c --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/index.md @@ -0,0 +1,138 @@ +# Genesis Kits + +Genesis Kits are pre-packaged deployment templates that encapsulate best practices for deploying software with BOSH. This section covers everything from using existing kits to creating your own. + +## Topics in This Section + +1. **[Overview](overview.md)** - Understanding Genesis kits +2. **[Using Kits](using-kits.md)** - Finding, selecting, and deploying with kits +3. **[Kit Features](features.md)** - Working with optional kit components +4. **[Available Kits](available-kits.md)** - Catalog of official Genesis kits +5. **[Authoring Kits](authoring-kits.md)** - Creating your own Genesis kits +6. **[Kit Structure](kit-structure.md)** - Anatomy of a kit +7. **[Kit Hooks](kit-hooks.md)** - Lifecycle hooks and scripts +8. **[Writing Hooks](writing-hooks.md)** - Hook development guide +9. **[Kit Testing](kit-testing.md)** - Testing and validation +10. **[Best Practices](best-practices.md)** - Kit development recommendations + +## Quick Overview + +Genesis Kits provide: + +- **Pre-built Templates** - YAML manifests with sensible defaults +- **Feature Flags** - Optional components you can enable +- **Secret Management** - Automatic credential generation +- **Lifecycle Hooks** - Scripts for customization +- **Best Practices** - Years of deployment experience + +### Common Kits + +- **BOSH** - Deploy BOSH directors +- **Cloud Foundry** - Full CF deployments +- **Vault** - HashiCorp Vault clusters +- **Concourse** - CI/CD pipelines +- **Shield** - Backup solutions +- **Prometheus** - Monitoring stacks + +## Using Kits + +### Finding Kits + +```bash +# List available kits +genesis kits + +# Search for specific kit +genesis kits | grep vault + +# Get kit information +genesis info vault +``` + +### Selecting Kit Version + +```yaml +# In environment file +kit: + name: vault + version: 1.5.0 # Specific version + # or + version: latest # Always use latest +``` + +### Enabling Features + +```yaml +kit: + features: + - postgres # Use PostgreSQL + - haproxy # Enable load balancer + - tls # Enable TLS/SSL +``` + +## Creating Kits + +### Basic Kit Structure + +``` +my-genesis-kit/ +├── kit.yml # Kit metadata +├── hooks/ # Lifecycle scripts +│ ├── new +│ ├── blueprint +│ └── check +├── manifests/ # YAML templates +│ └── base.yml +└── spec/ # Test specifications +``` + +### Development Workflow + +```bash +# Create new kit +genesis create-kit my-software + +# Work in dev mode +cd deployments/my-software +mkdir dev +# ... develop kit in dev/ ... + +# Test your kit +genesis new test-env --kit dev + +# Compile kit +genesis compile-kit --version 1.0.0 +``` + +## Key Concepts + +### Kit Metadata (kit.yml) + +Defines kit properties: +- Name and version +- Author information +- Required secrets +- Available features +- Dependencies + +### Features + +Optional components: +- Infrastructure-specific (AWS, Azure, vSphere) +- Add-ons (monitoring, backups) +- Integrations (SSO, external databases) + +### Hooks + +Scripts that run at specific times: +- **new** - Environment creation +- **blueprint** - Manifest generation +- **check** - Pre-deployment validation +- **addon** - Operational tasks + +## Getting Started + +- New to kits? Start with [Overview](overview.md) +- Want to use a kit? See [Using Kits](using-kits.md) +- Ready to create? Read [Authoring Kits](authoring-kits.md) +- Need examples? Check [Available Kits](available-kits.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/kit-hooks.md b/lib/Genesis/Help/Topics/50-kits/kit-hooks.md new file mode 100644 index 00000000..f4c59ffc --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/kit-hooks.md @@ -0,0 +1,514 @@ +# Kit Hooks + +Genesis hooks provide an extensible interface for customizing deployment behavior at various stages. They allow kit authors to inject custom code that executes during different phases of the deployment lifecycle. + +## Overview + +Genesis hooks are executable scripts (typically Bash) or Perl modules that extend Genesis functionality. Each hook serves a specific purpose in the deployment workflow and is invoked automatically by Genesis at the appropriate time. + +## Hook Types + +### Core Hooks (Bash Scripts) + +Located in the `hooks/` directory of a kit: + +#### new + +Runs when creating a new environment with `genesis new`. + +**Purpose**: Interactive environment setup, prompting for configuration values. + +```bash +#!/bin/bash +# hooks/new +set -eu + +# Prompt for required configuration +prompt_for base_domain \ + "What is your base domain?" \ + --validation "valid_domain" + +# Feature selection +if features_enabled "ssl"; then + prompt_for cert_path \ + "Path to SSL certificate?" \ + --default "/path/to/cert.pem" +fi +``` + +#### blueprint + +Determines which manifest files to merge for the deployment. + +**Purpose**: Build the ordered list of YAML files based on features. + +```bash +#!/bin/bash +# hooks/blueprint +set -eu + +# Always start with base +manifests=(manifests/base.yml) + +# Add feature manifests +for want in $GENESIS_REQUESTED_FEATURES; do + case $want in + ha|monitoring|ssl) + manifests+=(manifests/features/$want.yml) + ;; + aws|azure|gcp) + manifests+=(manifests/iaas/$want.yml) + ;; + esac +done + +# Output the list +printf "%s\n" "${manifests[@]}" +``` + +#### check + +Validates the environment before deployment. + +**Purpose**: Pre-deployment validation of configuration and requirements. + +```bash +#!/bin/bash +# hooks/check +set -eu + +# Validate cloud config +vm_type=$(lookup params.vm_type default) +if ! cloud_config_has vm_type "$vm_type"; then + echo >&2 "VM type '$vm_type' not found in cloud config" + exit 1 +fi + +# Check secrets +if want_feature "provided-cert" && ! safe exists "$VAULT_PREFIX/ssl/cert"; then + echo >&2 "Feature 'provided-cert' requires certificate in Vault" + exit 1 +fi +``` + +#### secrets + +Manages secrets beyond what's defined in kit.yml. + +**Purpose**: Handle complex secret generation or rotation scenarios. + +```bash +#!/bin/bash +# hooks/secrets +set -eu + +case $GENESIS_SECRET_ACTION in + add) + # Generate additional secrets + if want_feature "custom-ca"; then + safe x509 ca "$VAULT_PREFIX/custom/ca" \ + --ttl 10y \ + --subject "/CN=Custom CA" + fi + ;; + + rotate) + # Custom rotation logic + ;; +esac +``` + +#### info + +Displays deployment information after successful deployment. + +**Purpose**: Show URLs, credentials, and next steps. + +```bash +#!/bin/bash +# hooks/info +set -eu + +echo "Deployment Information:" +echo +echo "URL: https://$(lookup params.base_domain)" +echo "Username: admin" +echo "Password: $(safe get "$VAULT_PREFIX/admin:password")" +echo +echo "To access the dashboard, run:" +echo " genesis do $GENESIS_ENVIRONMENT dashboard" +``` + +#### addon + +Provides operational commands via `genesis do`. + +**Purpose**: Extend Genesis with kit-specific operations. + +```bash +#!/bin/bash +# hooks/addon +set -eu + +case $GENESIS_ADDON_SCRIPT in + list) + echo "Available addons:" + echo " login - Log into the system" + echo " backup - Run a backup" + echo " restore - Restore from backup" + ;; + + login) + url="https://$(lookup params.base_domain)" + password=$(safe get "$VAULT_PREFIX/admin:password") + echo "Logging into $url..." + # Login logic here + ;; + + backup) + echo "Starting backup..." + $GENESIS_BOSH_COMMAND -d "$BOSH_DEPLOYMENT" run-errand backup + ;; + + *) + echo >&2 "Unknown addon: $GENESIS_ADDON_SCRIPT" + exit 1 + ;; +esac +``` + +#### pre-deploy + +Runs before deployment begins. + +**Purpose**: Final validation, data collection for post-deploy. + +```bash +#!/bin/bash +# hooks/pre-deploy +set -eu + +# Collect current state +echo "Current version: $(get_deployed_version)" > "$GENESIS_PREDEPLOY_DATAFILE" + +# Final checks +if deploying_major_version_change; then + echo "WARNING: Major version upgrade detected!" + if [[ "$GENESIS_DEPLOY_CONFIRM" != "yes" ]]; then + read -p "Continue? [y/N] " confirm + [[ "$confirm" == "y" ]] || exit 1 + fi +fi +``` + +#### post-deploy + +Runs after deployment (successful or failed). + +**Purpose**: Cleanup, notifications, follow-up tasks. + +```bash +#!/bin/bash +# hooks/post-deploy +set -eu + +if [[ "$GENESIS_DEPLOY_RC" == "0" ]]; then + echo "Deployment successful!" + + # Run smoke tests + $GENESIS_BOSH_COMMAND -d "$BOSH_DEPLOYMENT" run-errand smoke-tests + + # Update DNS + update_dns_records "$(lookup params.base_domain)" +else + echo "Deployment failed - check logs" + notify_ops_team "Deployment of $GENESIS_ENVIRONMENT failed" +fi +``` + +### Advanced Hooks (Perl Modules) + +For complex kits, hooks can be written as Perl modules: + +#### Addon Hook Module + +```perl +package Genesis::Hook::Addon::MyKit::backup; +use parent qw(Genesis::Hook::Addon); + +sub init { + my $class = shift; + my $obj = $class->SUPER::init(@_); + $obj->check_minimum_genesis_version('3.1.0'); + return $obj; +} + +sub perform { + my ($self) = @_; + + # Parse options + my %options = $self->parse_options(['force']); + + # Execute backup + my $result = $self->env->bosh->run_errand('backup'); + + return $self->done($result); +} + +sub cmd_details { + return "Performs a backup of the deployment"; +} + +1; +``` + +## Hook Environment Variables + +Hooks have access to these environment variables: + +### Always Available + +- `GENESIS_ROOT` - Repository root directory +- `GENESIS_ENVIRONMENT` - Environment name +- `GENESIS_VAULT_PREFIX` - Vault path prefix +- `GENESIS_KIT_NAME` - Kit name +- `GENESIS_KIT_VERSION` - Kit version +- `GENESIS_REQUESTED_FEATURES` - Space-separated feature list + +### Hook-Specific + +#### new Hook +- `GENESIS_MIN_VERSION` - Minimum Genesis version required + +#### blueprint Hook +- `GENESIS_REQUESTED_FEATURES` - Features to enable + +#### addon Hook +- `GENESIS_ADDON_SCRIPT` - Addon being executed +- `GENESIS_ADDON_ARGS` - Arguments passed to addon + +#### pre-deploy Hook +- `GENESIS_PREDEPLOY_DATAFILE` - File for storing pre-deploy data +- `GENESIS_MANIFEST_FILE` - Path to deployment manifest +- `GENESIS_DEPLOY_OPTIONS` - JSON deployment options + +#### post-deploy Hook +- `GENESIS_DEPLOY_RC` - Deployment return code (0=success) +- `GENESIS_PREDEPLOY_DATAFILE` - Pre-deploy data file + +## Helper Functions + +Genesis provides Bash helper functions for hooks: + +### Prompting Functions + +```bash +# Basic prompt +prompt_for varname "Question?" + +# With default +prompt_for_or_use_default varname "default" "Question?" + +# With validation +prompt_for varname "Question?" \ + --validation "/^[a-z]+$/" + +# Multiple choice +choose varname \ + "option1" "Description 1" \ + "option2" "Description 2" +``` + +### Lookup Functions + +```bash +# Get parameter value +value=$(lookup params.key default_value) + +# Check if parameter exists +if param_exists params.key; then + # Parameter is set +fi +``` + +### Feature Functions + +```bash +# Check if feature is enabled +if want_feature "monitoring"; then + # Add monitoring configuration +fi + +# Check multiple features +if features_enabled "ha" "ssl"; then + # Both features enabled +fi +``` + +### Cloud Config Functions + +```bash +# Check if resource exists +if cloud_config_has vm_type "large"; then + # VM type exists +fi + +# Get cloud config value +network=$(cloud_config_get networks.0.name) +``` + +## Best Practices + +### 1. Error Handling + +Always use proper error handling: + +```bash +#!/bin/bash +set -eu # Exit on error, undefined variables + +# Explicit error checking +if ! command_that_might_fail; then + echo >&2 "ERROR: Command failed" + exit 1 +fi +``` + +### 2. User-Friendly Output + +Use color and formatting: + +```bash +# Use describe for formatted output +describe "Setting up #C{My Software} deployment" + +# Success messages +success "Deployment configured successfully!" + +# Warnings +warning "Using default configuration" + +# Errors +error "Missing required parameter" +``` + +### 3. Idempotency + +Make hooks idempotent when possible: + +```bash +# Check before creating +if ! safe exists "$VAULT_PREFIX/generated"; then + safe gen "$VAULT_PREFIX/generated" password +fi +``` + +### 4. Validation + +Validate early and clearly: + +```bash +# In check hook +errors=() + +[[ -n "${base_domain:-}" ]] || errors+=("Missing base_domain") +[[ -n "${instances:-}" ]] || errors+=("Missing instances") + +if [[ ${#errors[@]} -gt 0 ]]; then + printf "Validation errors:\n" >&2 + printf " - %s\n" "${errors[@]}" >&2 + exit 1 +fi +``` + +### 5. Documentation + +Document complex logic: + +```bash +# Feature compatibility matrix: +# - 'ha' requires minimum 3 instances +# - 'ssl' conflicts with 'self-signed' +# - 'monitoring' adds Prometheus exporters +``` + +## Testing Hooks + +Test hooks during development: + +```bash +# Test blueprint hook +cd my-kit +export GENESIS_REQUESTED_FEATURES="ha monitoring" +./hooks/blueprint + +# Test addon hook +export GENESIS_ADDON_SCRIPT="backup" +export GENESIS_ENVIRONMENT="test" +./hooks/addon + +# Test with Genesis +genesis new test-env --kit ./ +``` + +## Common Patterns + +### Feature Detection + +```bash +# Single feature +if want_feature "ssl"; then + add_ssl_configuration +fi + +# Multiple features (OR) +if want_feature "mysql" || want_feature "postgres"; then + configure_database +fi + +# Multiple features (AND) +if want_feature "ha" && want_feature "ssl"; then + configure_ha_ssl +fi +``` + +### Dynamic Manifest Building + +```bash +#!/bin/bash +# hooks/blueprint + +manifests=(manifests/base.yml) + +# IaaS-specific +case "$(iaas)" in + aws) manifests+=(manifests/iaas/aws.yml) ;; + azure) manifests+=(manifests/iaas/azure.yml) ;; + *) manifests+=(manifests/iaas/generic.yml) ;; +esac + +# Optional features +for feature in $GENESIS_REQUESTED_FEATURES; do + [[ -f "manifests/features/$feature.yml" ]] && \ + manifests+=(manifests/features/$feature.yml) +done + +printf "%s\n" "${manifests[@]}" +``` + +### Conditional Parameters + +```bash +# In new hook +if want_feature "ha"; then + prompt_for instances \ + "Number of instances (minimum 3 for HA)?" \ + --validation "/^[3-9][0-9]*$/" +else + prompt_for instances \ + "Number of instances?" \ + --default 1 +fi +``` + +Hooks are the key to creating flexible, user-friendly Genesis kits that encode operational knowledge while remaining adaptable to different deployment scenarios. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/kit-structure.md b/lib/Genesis/Help/Topics/50-kits/kit-structure.md new file mode 100644 index 00000000..2a80ca12 --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/kit-structure.md @@ -0,0 +1,526 @@ +# Kit Structure + +This guide details the anatomy of a Genesis kit, explaining each component and how they work together. + +## Directory Layout + +A complete Genesis kit has this structure: + +``` +my-genesis-kit/ +├── kit.yml # Kit metadata and configuration +├── hooks/ # Lifecycle scripts +│ ├── addon # Operational tasks +│ ├── blueprint # Manifest generation +│ ├── check # Pre-deployment validation +│ ├── features # Feature detection +│ ├── info # Information display +│ ├── new # Environment creation +│ ├── post-deploy # Post-deployment actions +│ ├── pre-deploy # Pre-deployment actions +│ └── secrets # Secret management +├── manifests/ # BOSH manifest templates +│ ├── base.yml # Base manifest +│ └── features/ # Feature-specific manifests +│ ├── aws.yml +│ ├── monitoring.yml +│ └── ha.yml +├── ops/ # Additional ops files (optional) +├── spec/ # Test specifications +├── ci/ # CI/CD pipeline definitions +└── README.md # Documentation + +``` + +## Core Components + +### kit.yml + +The kit metadata file defines identity and behavior: + +```yaml +# Identity +name: my-software +version: 1.2.0 +author: Genesis Community +docs: https://github.com/genesis-community/my-software-genesis-kit +code: https://github.com/genesis-community/my-software-genesis-kit + +# Description +description: | + This kit deploys My Software, providing scalable + services for your infrastructure. + +# Genesis version requirement +genesis_version_min: 2.8.0 + +# Dependencies +depends_on: + - vault + +# Provided features +provides: + - my-software-api + +# Subkits (deprecated - use features) +# subkits: [] + +# Certificates +certificates: + base: + server/ca: + ca: + valid_for: 10y + names: ["My Software CA"] + server/cert: + server: + valid_for: 1y + names: ["server.${params.base_domain}"] + signed_by: server/ca + +# Credentials +credentials: + base: + admin: + password: random 32 + system/db: + username: dbadmin + password: random 40 fmt base64 + +# User-provided secrets +provided: + base: + external/api: + keys: + - client_id + - client_secret +``` + +### Manifest Files + +#### Base Manifest (manifests/base.yml) + +The foundation all deployments build upon: + +```yaml +--- +# Basic structure +name: (( grab params.env )) + +# Releases +releases: +- name: my-software + version: 3.4.5 + url: https://github.com/.../my-software-3.4.5.tgz + sha1: abc123def456... + +# Stemcells +stemcells: +- alias: default + os: ubuntu-jammy + version: latest + +# Update settings +update: + canaries: 1 + max_in_flight: 1 + canary_watch_time: 1000-60000 + update_watch_time: 1000-60000 + serial: false + +# Instance groups +instance_groups: +- name: api + instances: (( grab params.api_instances || 1 )) + vm_type: (( grab params.api_vm_type || "default" )) + stemcell: default + networks: + - name: (( grab params.network || "default" )) + jobs: + - name: api + release: my-software + properties: + api: + port: 8080 + admin_password: (( vault "secret/" params.vault "/admin:password" )) + +# Required parameters +params: + env: (( param "What environment is this?" )) + network: (( param "What network should VMs be placed on?" )) +``` + +#### Feature Manifests (manifests/features/) + +Modifications applied when features are enabled: + +```yaml +# manifests/features/ha.yml +--- +# Enable high availability +- type: replace + path: /instance_groups/name=api/instances + value: 3 + +- type: replace + path: /instance_groups/name=api/jobs/name=api/properties/api/cluster? + value: + enabled: true + quorum: 2 + +# Add load balancer +- type: replace + path: /instance_groups/- + value: + name: haproxy + instances: 2 + vm_type: (( grab params.haproxy_vm_type || "small" )) + stemcell: default + networks: + - name: (( grab params.network )) + jobs: + - name: haproxy + release: haproxy + properties: + ha_proxy: + backend_port: 8080 + backend_servers: (( grab instance_groups.api.networks[0].static_ips )) +``` + +### Hook Scripts + +#### blueprint Hook + +Determines which manifests to merge: + +```bash +#!/bin/bash +set -eu + +# Start with base +manifests=( manifests/base.yml ) + +# Add features +for want in $GENESIS_REQUESTED_FEATURES; do + case "$want" in + # Infrastructure features + aws|azure|gcp|vsphere|openstack) + manifests+=( manifests/iaas/$want.yml ) + ;; + + # Standard features + ha|monitoring|shield) + manifests+=( manifests/features/$want.yml ) + ;; + + # Implicit features + +internal-db) + manifests+=( manifests/addons/internal-db.yml ) + ;; + + *) + echo >&2 "Unrecognized feature: $want" + exit 1 + ;; + esac +done + +# Output manifest list +printf "%s\n" "${manifests[@]}" +``` + +#### new Hook + +Interactive environment creation: + +```bash +#!/bin/bash +set -eu + +# Load Genesis helpers +source $GENESIS_ROOT/.genesis/lib/genesis.sh + +# Basic information +describe "Setting up new My Software deployment" +echo + +# Required parameters +prompt_for base_domain \ + "What is your base domain (e.g., example.com)?" \ + --validation dns_domain + +# Optional parameters with defaults +prompt_for_or_use_default api_instances "1" \ + "How many API instances do you want?" + +# Feature selection +if features_enabled ha; then + prompt_for_or_use_default api_instances "3" \ + "How many API instances? (minimum 3 for HA)" +fi + +# Infrastructure selection +infrastructure_menu() { + describe "Select your infrastructure:" + choose "aws" "Amazon Web Services" \ + "azure" "Microsoft Azure" \ + "gcp" "Google Cloud Platform" \ + "vsphere" "VMware vSphere" \ + "openstack" "OpenStack" +} + +infrastructure=$(infrastructure_menu) +features+=( "$infrastructure" ) + +# Save configuration +param_entry params.base_domain "$base_domain" +param_entry params.api_instances "$api_instances" +``` + +#### check Hook + +Validate before deployment: + +```bash +#!/bin/bash +set -eu + +# Check BOSH +describe "Validating BOSH environment..." + +# Verify cloud config +for type in vm network disk; do + value=$(lookup params.${type}_type "default") + if ! bosh_cloud_config_has ${type}_type "$value"; then + fail "Cloud config missing ${type} type '$value'" + fi +done + +# Verify secrets +describe "Checking Vault secrets..." + +if want_feature provided-cert; then + for secret in ssl/server:certificate ssl/server:key; then + if ! safe exists "$GENESIS_SECRETS_BASE/$secret"; then + fail "Missing required secret: $secret" + fi + done +fi + +describe "#G{All checks passed!}" +``` + +#### info Hook + +Display deployment information: + +```bash +#!/bin/bash +set -eu + +base_domain=$(lookup params.base_domain) +url="https://api.$base_domain" +username="admin" +password=$(safe get "$GENESIS_SECRETS_BASE/admin:password") + +describe "#Yi{My Software Deployment Information}" +echo +describe " API URL: #C{$url}" +describe " Username: #C{$username}" +describe " Password: #C{$password}" +echo +describe "Need to do something? Try these addons:" +echo +genesis do "$GENESIS_ENVIRONMENT" list +``` + +#### addon Hook + +Operational tasks: + +```bash +#!/bin/bash +set -eu + +list() { + describe "Available addons:" + describe " #G{login} Login to API" + describe " #G{setup} Initial setup" + describe " #G{backup} Run backup" + describe " #G{restore} Restore from backup" +} + +case $GENESIS_ADDON_SCRIPT in + list) list ;; + + login) + api_url="https://api.$(lookup params.base_domain)" + password=$(safe get "$GENESIS_SECRETS_BASE/admin:password") + + describe "Logging into $api_url..." + curl -X POST "$api_url/login" \ + -d "username=admin&password=$password" \ + -c cookie.txt + ;; + + backup) + describe "Running backup errand..." + genesis bosh run-errand backup + ;; + + *) + echo >&2 "Unrecognized addon: $GENESIS_ADDON_SCRIPT" + list >&2 + exit 1 + ;; +esac +``` + +### Supporting Files + +#### spec/ - Test Specifications + +Ginkgo tests for validating kit behavior: + +```go +// spec/spec_test.go +var _ = Describe("My Software Kit", func() { + BeforeEach(func() { + kit = "my-software" + version = "latest" + }) + + Context("Base Manifest", func() { + BeforeEach(func() { + features = []string{} + }) + + It("should deploy with defaults", func() { + manifest := GetManifest() + Expect(manifest.Name).To(Equal("my-env-my-software")) + + ig := manifest.InstanceGroups.Lookup("api") + Expect(ig.Instances).To(Equal(1)) + }) + }) + + Context("HA Feature", func() { + BeforeEach(func() { + features = []string{"ha"} + }) + + It("should scale instances", func() { + manifest := GetManifest() + + ig := manifest.InstanceGroups.Lookup("api") + Expect(ig.Instances).To(Equal(3)) + }) + }) +}) +``` + +#### ci/ - Pipeline Configuration + +Concourse pipeline for testing: + +```yaml +# ci/pipeline.yml +resources: +- name: git + type: git + source: + uri: ((github.uri)) + branch: develop + +- name: version + type: semver + source: + driver: git + uri: ((github.uri)) + branch: version + file: version + +jobs: +- name: test + plan: + - get: git + trigger: true + - task: test-kit + file: git/ci/tasks/test.yml + +- name: release + plan: + - aggregate: + - get: git + passed: [test] + - get: version + params: {bump: final} + - task: release + file: git/ci/tasks/release.yml + - put: version + params: {file: version/version} +``` + +## File Interactions + +### Manifest Assembly Flow + +1. **Genesis** calls `blueprint` hook +2. **Blueprint** returns ordered manifest list +3. **Genesis** merges manifests with Spruce +4. **Parameters** from environment file applied +5. **Secrets** retrieved from Vault +6. **Final manifest** sent to BOSH + +### Secret Generation Flow + +1. **Kit.yml** defines required secrets +2. **Genesis** checks Vault for existence +3. **Missing secrets** generated automatically +4. **Manifests** reference via `(( vault ))` operator + +### Hook Execution Order + +1. **features** - Determine active features +2. **new** - Create new environment (once) +3. **blueprint** - Generate manifest list +4. **secrets** - Manage secrets +5. **check** - Validate configuration +6. **pre-deploy** - Pre-deployment tasks +7. *[Genesis deploys to BOSH]* +8. **post-deploy** - Post-deployment tasks +9. **info** - Display information +10. **addon** - Run operational tasks + +## Best Practices + +### Manifest Organization + +- Keep `base.yml` minimal and focused +- One feature per file in `features/` +- Use ops file format for modifications +- Document parameter requirements + +### Hook Guidelines + +- Always `set -eu` for safety +- Use Genesis helper functions +- Provide helpful error messages +- Make scripts idempotent + +### Testing Structure + +- Test base configuration +- Test each feature independently +- Test feature combinations +- Validate error conditions + +### Documentation + +Always include: +- README.md with examples +- Parameter documentation +- Feature descriptions +- Upgrade notes + +Understanding kit structure helps you create maintainable, reusable deployment templates that encode your operational knowledge. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/kit-testing.md b/lib/Genesis/Help/Topics/50-kits/kit-testing.md new file mode 100644 index 00000000..b2cde69a --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/kit-testing.md @@ -0,0 +1,516 @@ +# Kit Testing + +Testing Genesis kits ensures they work correctly across different scenarios and configurations. This guide covers testing strategies, tools, and best practices. + +## Testing Overview + +Kit testing involves: +- Unit testing individual hooks +- Integration testing with Genesis +- Manifest generation validation +- Secret generation verification +- Deployment testing with BOSH + +## Testing Tools + +### Spec Testing with Ginkgo + +Genesis kits use Ginkgo for automated testing: + +```bash +# Install Ginkgo +go get -u github.com/onsi/ginkgo/ginkgo +go get -u github.com/onsi/gomega/... + +# Run tests +cd spec +ginkgo -p +``` + +### Basic Spec Structure + +```go +// spec/spec_test.go +package spec_test + +import ( + . "github.com/genesis-community/testkit/testing" + . "github.com/onsi/ginkgo" + . "github.com/onsi/gomega" +) + +var _ = Describe("My Kit", func() { + kit := "my-software" + + Context("Base Manifest", func() { + BeforeEach(func() { + Setup(kit, "default") + }) + + It("uses the requested VM type", func() { + manifest := Manifest( + WithParam("vm_type", "large"), + ) + Expect(manifest).To(HaveInstanceGroup("my-software", + WithVMType("large"))) + }) + }) +}) +``` + +## Hook Testing + +### Testing the `new` Hook + +Create a test wrapper for the `new` hook: + +```bash +#!/bin/bash +# test/test-new-hook.sh + +# Mock Genesis environment +export GENESIS_ROOT="/tmp/test-$$" +export GENESIS_ENVIRONMENT="test-env" +export GENESIS_SECRETS_PATH="test/env" +export GENESIS_MIN_VERSION="2.8.0" + +mkdir -p "$GENESIS_ROOT" + +# Mock prompt_for responses +cat > /tmp/responses </dev/null; then + echo "FAIL: Invalid VM type not caught" + exit 1 +fi + +echo "PASS: check hook test" +``` + +## Manifest Testing + +### Testing Manifest Generation + +```bash +#!/bin/bash +# test/test-manifests.sh + +kit_dir="$(cd ..; pwd)" + +# Test base manifest +genesis compile-kit --dev --name test +genesis new test-base --kit test + +# Validate structure +genesis manifest test-base > /tmp/manifest.yml +bosh int /tmp/manifest.yml --path /name | grep -q "test-base" +``` + +### Spec Tests for Manifests + +```go +var _ = Describe("Manifest Generation", func() { + Context("with HA feature", func() { + BeforeEach(func() { + Setup(kit, "ha") + }) + + It("creates 3 instances", func() { + manifest := Manifest() + ig := manifest.InstanceGroups.Lookup("my-software") + Expect(ig.Instances).To(Equal(3)) + }) + + It("enables clustering", func() { + manifest := Manifest() + props := manifest.InstanceGroups.Lookup("my-software"). + Jobs[0].Properties + Expect(props).To(HaveKeyWithValue("cluster", + HaveKeyWithValue("enabled", true))) + }) + }) +}) +``` + +## Secret Testing + +### Testing Secret Generation + +```go +var _ = Describe("Secrets", func() { + It("generates required passwords", func() { + manifest := Manifest() + + // Check password references + Expect(manifest).To(HaveSecret("admin_password")) + Expect(manifest).To(HaveSecret("database_password")) + }) + + It("generates certificates with correct SANs", func() { + manifest := Manifest( + WithParam("base_domain", "example.com"), + ) + + cert := GetCertificate("server") + Expect(cert.SANs).To(ContainElement("*.example.com")) + }) +}) +``` + +### Manual Secret Testing + +```bash +#!/bin/bash +# test/test-secrets.sh + +# Create test Vault +safe target test --memory +safe auth + +# Test secret generation +export VAULT_PREFIX="secret/test" +genesis add-secrets test-env + +# Verify secrets created +safe exists secret/test/admin:password || exit 1 +safe exists secret/test/ssl/ca:certificate || exit 1 + +echo "PASS: Secrets generated correctly" +``` + +## Integration Testing + +### Full Deployment Test + +```bash +#!/bin/bash +# test/integration-test.sh + +# Setup +genesis init --kit ../my-kit test-deployments +cd test-deployments + +# Create test environment +genesis new integration-test < /dev/null + + local end=$(date +%s.%N) + echo "$features: $(echo "$end - $start" | bc)s" +} + +# Test different feature combinations +time_genesis "" +time_genesis "ha" +time_genesis "ha monitoring ssl" +``` + +### Memory Usage + +```bash +# Monitor memory during tests +/usr/bin/time -v genesis manifest large-env 2>&1 | \ + grep "Maximum resident set size" +``` + +Testing thoroughly ensures your kit works reliably across all supported configurations and provides a good user experience. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/overview.md b/lib/Genesis/Help/Topics/50-kits/overview.md new file mode 100644 index 00000000..74e8b4e7 --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/overview.md @@ -0,0 +1,292 @@ +# Genesis Kits Overview + +Genesis Kits are the heart of the Genesis deployment system. They encapsulate years of operational experience into reusable, parameterized templates that make deploying complex software simple and repeatable. + +## What Is a Kit? + +A Genesis Kit is a packaged collection of: + +- **Manifest Templates** - YAML files defining BOSH deployments +- **Configuration Defaults** - Sensible default values +- **Feature Definitions** - Optional components and variations +- **Secret Specifications** - What credentials to generate +- **Lifecycle Hooks** - Scripts for customization and validation +- **Documentation** - Usage instructions and examples + +Think of a kit as a blueprint for deploying a specific type of software, complete with all the knowledge needed to do it right. + +## Why Use Kits? + +### Without Kits + +Deploying software with BOSH traditionally requires: +- Writing hundreds of lines of YAML +- Understanding every configuration option +- Managing credentials manually +- Keeping up with best practices +- Avoiding common pitfalls + +### With Kits + +Genesis Kits provide: +- **Pre-built configurations** - Start with working defaults +- **Curated options** - Only expose what matters +- **Automatic secrets** - Credentials generated for you +- **Built-in validation** - Catch errors before deployment +- **Community knowledge** - Best practices built in + +## How Kits Work + +### 1. Kit Selection + +Choose a kit for what you want to deploy: + +```yaml +kit: + name: vault # Deploy HashiCorp Vault + version: 1.5.0 # Specific kit version +``` + +### 2. Feature Activation + +Enable optional components: + +```yaml +kit: + features: + - consul # Use Consul backend + - monitoring # Enable Prometheus metrics + - auto-unseal # AWS KMS auto-unseal +``` + +### 3. Parameter Configuration + +Provide environment-specific values: + +```yaml +params: + env: production + vault_disk_size: 50_GB + availability_zones: + - us-east-1a + - us-east-1b + - us-east-1c +``` + +### 4. Manifest Generation + +Genesis combines: +- Kit base manifests +- Feature modifications +- Your parameters +- Generated secrets + +Into a complete BOSH manifest. + +## Kit Components + +### Base Manifest + +The foundation all deployments start from: + +```yaml +# manifests/base.yml +name: (( grab params.env )) +instance_groups: +- name: vault + instances: 3 + vm_type: (( grab params.vm_type )) + jobs: + - name: vault + release: vault + properties: + # Sensible defaults here +``` + +### Features + +Optional modifications: + +```yaml +# manifests/features/consul.yml +instance_groups: +- name: vault + jobs: + - name: vault + properties: + vault: + backend: + type: consul + consul: + address: (( grab params.consul_address )) +``` + +### Hooks + +Lifecycle automation: + +```bash +#!/bin/bash +# hooks/new +prompt_for "vault_disk_size" \ + "How much disk space for Vault data?" \ + --default "10G" +``` + +### Secrets Definition + +```yaml +# kit.yml +credentials: + base: + vault/seal: + seal_key: random 32 fmt base64 +``` + +## Kit Lifecycle + +### Development Time + +1. **Author creates kit** - Encodes deployment knowledge +2. **Testing and refinement** - Validates across scenarios +3. **Release** - Published for community use + +### Deployment Time + +1. **Operator selects kit** - Chooses software to deploy +2. **Configuration** - Provides environment details +3. **Generation** - Genesis creates full manifest +4. **Deployment** - BOSH deploys the software + +### Operational Time + +1. **Updates** - New kit versions bring improvements +2. **Modifications** - Features can be added/removed +3. **Maintenance** - Hooks provide operational tasks + +## Types of Kits + +### Infrastructure Kits + +Deploy foundational services: +- **BOSH** - BOSH directors +- **Vault** - Secret management +- **Concourse** - CI/CD systems + +### Platform Kits + +Deploy application platforms: +- **Cloud Foundry** - PaaS platform +- **Kubernetes** - Container orchestration +- **Nomad** - Workload scheduling + +### Service Kits + +Deploy supporting services: +- **PostgreSQL** - Databases +- **RabbitMQ** - Message queues +- **Elasticsearch** - Search and analytics + +### Monitoring Kits + +Deploy observability stacks: +- **Prometheus** - Metrics collection +- **Grafana** - Visualization +- **ELK Stack** - Log aggregation + +## Kit Philosophy + +### 1. Convention Over Configuration + +Kits make reasonable assumptions: +- Standard network names +- Common VM types +- Typical sizing + +While allowing overrides when needed. + +### 2. Progressive Disclosure + +Start simple: +```yaml +kit: + name: vault +``` + +Add complexity as needed: +```yaml +kit: + name: vault + features: [consul, monitoring, auto-unseal] +params: + vault_instances: 5 + vault_vm_type: large +``` + +### 3. Operational Experience + +Kits encode real-world lessons: +- Recommended instance counts +- Proven update strategies +- Common troubleshooting steps + +## Kit Benefits + +### For Operators + +- **Faster deployments** - Minutes instead of days +- **Fewer mistakes** - Validation catches errors +- **Consistent environments** - Same kit = same setup +- **Easy updates** - Kit versions bring improvements + +### For Organizations + +- **Standardization** - Consistent across teams +- **Knowledge sharing** - Best practices in code +- **Reduced training** - Simpler operations +- **Compliance** - Security built in + +### For the Community + +- **Shared improvements** - Everyone benefits +- **Collective knowledge** - Lessons learned together +- **Reduced duplication** - Solve problems once + +## Getting Started with Kits + +### Using Existing Kits + +1. Browse available kits: + ```bash + genesis kits + ``` + +2. Initialize with a kit: + ```bash + genesis init --kit vault + ``` + +3. Deploy: + ```bash + genesis new prod-vault + genesis deploy prod-vault + ``` + +### Creating New Kits + +1. Start from template: + ```bash + genesis create-kit my-software + ``` + +2. Define your manifest structure +3. Add features and hooks +4. Test thoroughly +5. Share with community + +## Next Steps + +- Learn to [Use Kits](using-kits.md) +- Explore [Available Kits](available-kits.md) +- Understand [Kit Features](features.md) +- Start [Authoring Kits](authoring-kits.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/50-kits/using-kits.md b/lib/Genesis/Help/Topics/50-kits/using-kits.md new file mode 100644 index 00000000..723a1a54 --- /dev/null +++ b/lib/Genesis/Help/Topics/50-kits/using-kits.md @@ -0,0 +1,486 @@ +# Using Genesis Kits + +This guide covers how to find, select, and use Genesis kits for your deployments. + +## Finding Kits + +### Official Kit Repositories + +Genesis kits are hosted on GitHub: +- **Organization**: https://github.com/genesis-community +- **Naming Convention**: `*-genesis-kit` + +### Listing Available Kits + +```bash +# List all known kits +genesis kits + +# Example output: +# BOSH Genesis Kit - https://github.com/genesis-community/bosh-genesis-kit +# Cloud Foundry Genesis Kit - https://github.com/genesis-community/cf-genesis-kit +# Vault Genesis Kit - https://github.com/genesis-community/vault-genesis-kit +``` + +### Getting Kit Information + +```bash +# Get detailed information about a kit +genesis info vault + +# Shows: +# - Current versions +# - Available features +# - Configuration parameters +# - Recent changes +``` + +## Selecting a Kit + +### During Repository Initialization + +```bash +# Initialize new repository with specific kit +genesis init --kit vault my-vault-deployments + +# Lists kits if not specified +genesis init my-deployments +> Select a kit: +> 1) bosh +> 2) cf +> 3) vault +> 4) concourse +``` + +### Kit Versioning + +Kits use semantic versioning (MAJOR.MINOR.PATCH): + +```yaml +# Specific version (recommended for production) +kit: + name: vault + version: 1.5.0 + +# Latest version (useful for development) +kit: + name: vault + version: latest + +# Version constraints (future feature) +kit: + name: vault + version: "~> 1.5" # Any 1.5.x version +``` + +## Understanding Kit Features + +### What Are Features? + +Features are optional kit components that modify the deployment: +- Infrastructure adaptations (AWS, Azure, vSphere) +- Add-on functionality (monitoring, backups) +- Architectural choices (HA, standalone) + +### Listing Available Features + +```bash +# During environment creation +genesis new my-env +> Which Vault backend would you like to use? +> 1) consul - Consul-backed storage +> 2) raft - Integrated Raft storage +> 3) file - File-based storage (dev only) + +# From kit info +genesis info vault --features +``` + +### Common Feature Patterns + +#### Infrastructure Features +```yaml +kit: + features: + - aws # AWS-specific configuration + - azure # Azure-specific configuration + - vsphere # vSphere-specific configuration +``` + +#### Functional Features +```yaml +kit: + features: + - monitoring # Prometheus exporters + - backups # Automated backup support + - ha # High availability mode +``` + +#### Integration Features +```yaml +kit: + features: + - ldap # LDAP authentication + - github-oauth # GitHub OAuth integration + - provided-cert # User-provided certificates +``` + +## Configuring Deployments + +### Required Parameters + +Kits define required parameters that must be set: + +```yaml +params: + # Always required + env: prod-vault + + # Kit-specific requirements + vault_disk_pool: fast-ssd + availability_zones: + - z1 + - z2 + - z3 +``` + +### Optional Parameters + +Customize behavior with optional parameters: + +```yaml +params: + # Override defaults + vault_instances: 5 # Default might be 3 + vault_vm_type: large # Default might be default + + # Feature-specific + consul_servers: # Only with consul feature + - 10.0.1.10 + - 10.0.1.11 + - 10.0.1.12 +``` + +### Parameter Discovery + +Find available parameters: + +1. **Kit documentation** + ```bash + genesis info vault --params + ``` + +2. **Environment file comments** + ```yaml + # Generated by genesis new + params: + # env: Name of your environment + env: my-env + ``` + +3. **Kit source code** + ```bash + # Check kit manifests + cat .genesis/kits/vault-1.5.0/manifests/base.yml + ``` + +## Working with Kit Versions + +### Upgrading Kits + +```yaml +# Before - old version +kit: + name: vault + version: 1.4.0 + +# After - new version +kit: + name: vault + version: 1.5.0 +``` + +Then redeploy: +```bash +genesis deploy my-env +``` + +### Version Compatibility + +Check compatibility before upgrading: +```bash +# Compare versions +genesis diff-kits vault 1.4.0 1.5.0 + +# Check breaking changes +genesis info vault --version 1.5.0 --changes +``` + +### Pinning Versions + +For production stability: +```yaml +# Always pin to specific versions +kit: + name: vault + version: 1.5.0 # NOT 'latest' +``` + +## Kit Development Mode + +### Using Local Kits + +For testing modifications: + +```bash +# Create dev directory +cd my-vault-deployments +mkdir dev + +# Copy and modify kit +cp -r .genesis/kits/vault-1.5.0/* dev/ + +# Use dev kit +cat > test-env.yml < ops/scale-up.yml < "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" < "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" <> "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" <> "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" </dev/null; then + echo >&2 "ERROR: jq is required but not installed" + exit 1 +fi + +# Validate critical inputs +if [[ -z "${base_domain:-}" ]]; then + echo >&2 "ERROR: base_domain cannot be empty" + exit 1 +fi +``` + +### 5. Idempotency + +Make hooks re-runnable: + +```bash +# Check if already configured +if [[ -f "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" ]]; then + prompt_for overwrite boolean \ + "Environment already exists. Overwrite?" \ + --default n + + [[ $overwrite == "false" ]] && exit 0 +fi +``` + +## Testing Your Hook + +### Manual Testing + +```bash +cd my-kit + +# Set test environment +export GENESIS_ROOT="/tmp/test" +export GENESIS_ENVIRONMENT="test-env" +export GENESIS_SECRETS_PATH="test/env" + +# Run hook +./hooks/new + +# Check output +cat /tmp/test/test-env.yml +``` + +### Automated Testing + +Create test scripts: + +```bash +#!/bin/bash +# test-new-hook.sh + +# Mock prompt_for +prompt_for() { + local var=$1 + local type=$2 + case "$var" in + base_domain) eval "$var='test.example.com'" ;; + use_ha) eval "$var='true'" ;; + instances) eval "$var='3'" ;; + esac +} + +# Source and run hook +source hooks/new + +# Validate output +grep -q "base_domain: test.example.com" "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" +``` + +## Common Patterns + +### IaaS-Specific Configuration + +```bash +case $iaas in + aws) + prompt_for aws_region line \ + 'AWS Region?' \ + --default 'us-east-1' + ;; + azure) + prompt_for azure_region line \ + 'Azure Region?' \ + --default 'eastus' + ;; + vsphere) + prompt_for vcenter_ip line \ + 'vCenter IP address?' \ + --validation ip + ;; +esac +``` + +### Database Selection + +```bash +prompt_for database select \ + 'Which database backend?' \ + -o '[postgres] PostgreSQL' \ + -o '[mysql] MySQL' \ + -o '[none] No database' + +if [[ $database != "none" ]]; then + features+=("$database") + + prompt_for db_persistent boolean \ + 'Use persistent disk for database?' + + if [[ $db_persistent == "true" ]]; then + prompt_for db_disk_size line \ + 'Database disk size?' \ + --default '10GB' + fi +fi +``` + +Writing effective hooks makes your kit user-friendly and reduces deployment errors by guiding users through configuration with appropriate validations and helpful defaults. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/.keep b/lib/Genesis/Help/Topics/60-bosh/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/60-bosh/bosh-directors.md b/lib/Genesis/Help/Topics/60-bosh/bosh-directors.md new file mode 100644 index 00000000..d3ee969c --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/bosh-directors.md @@ -0,0 +1,432 @@ +# BOSH Directors + +The BOSH Director is the core component that orchestrates deployments. This guide covers deploying and managing BOSH directors using Genesis. + +## Overview + +A BOSH Director: +- Manages the lifecycle of VMs and software +- Stores deployment state and configuration +- Monitors health and resurrects failed VMs +- Handles persistent disks and snapshots +- Manages releases, stemcells, and deployments + +## Deploying a BOSH Director with Genesis + +Genesis provides a BOSH kit for deploying directors: + +### Initial Setup + +```bash +# Create a new BOSH deployment repository +genesis init my-bosh --kit bosh +cd my-bosh + +# Create a new BOSH environment +genesis new my-bosh +``` + +### Configuration Options + +The BOSH kit will prompt for: + +1. **Static IP Address**: The director's IP +2. **IaaS Selection**: AWS, Azure, GCP, vSphere, etc. +3. **Network Configuration**: Subnet, gateway, DNS +4. **IaaS Credentials**: Cloud provider access + +### Example Environment File + +```yaml +--- +genesis: + env: my-bosh + secrets_path: my/bosh + +kit: + features: + - aws + - proto-bosh + - bosh-init + +params: + # Static IP for director + static_ip: 10.0.0.6 + + # AWS Configuration + aws_region: us-east-1 + aws_default_sgs: + - sg-0123456789abcdef0 # BOSH security group + + # Network Configuration + subnet_id: subnet-0123456789abcdef0 + external_domain: bosh.example.com + + # Director Name + director_name: my-bosh +``` + +### Deployment + +```bash +# Deploy the BOSH director +genesis deploy my-bosh + +# This will: +# 1. Create the director VM +# 2. Install BOSH software +# 3. Configure the database +# 4. Start BOSH services +``` + +## Proto-BOSH vs Regular BOSH + +### Proto-BOSH + +The first BOSH director in an environment (bootstrapping): +- Deployed using `bosh create-env` +- Manages its own lifecycle +- Requires the `proto-bosh` feature + +```yaml +kit: + features: + - proto-bosh + - aws +``` + +### Regular BOSH + +Subsequent directors managed by another BOSH: +- Deployed using standard `bosh deploy` +- Managed by a parent director +- More resilient and easier to update + +```yaml +kit: + features: + - aws + # No proto-bosh feature +``` + +## Managing Multiple Directors + +### Director Hierarchy + +Common patterns: + +``` +proto-bosh (global) +├── regional-bosh-us-east +├── regional-bosh-us-west +└── regional-bosh-eu-west + ├── env-bosh-dev + ├── env-bosh-staging + └── env-bosh-prod +``` + +### Configuration Management + +Use hierarchical configuration: + +```yaml +# global.yml +params: + trusted_certs: | + -----BEGIN CERTIFICATE----- + # Corporate CA cert + -----END CERTIFICATE----- + +# us-east.yml +params: + aws_region: us-east-1 + ntp_servers: + - 0.amazon.pool.ntp.org + - 1.amazon.pool.ntp.org + +# us-east-prod.yml +params: + static_ip: 10.0.0.6 + director_name: us-east-prod-bosh +``` + +## Director Features + +### Core Features + +Available in all deployments: +- **Health Monitor**: VM monitoring and resurrection +- **Database**: PostgreSQL for state storage +- **NATS**: Message bus for agent communication +- **Blobstore**: Release and package storage + +### Optional Features + +Enable via kit features: + +#### UAA Authentication + +```yaml +kit: + features: + - uaa +params: + uaa_admin_client_secret: ((uaa-admin-secret)) +``` + +#### CredHub Integration + +```yaml +kit: + features: + - credhub +params: + credhub_encryption_password: ((credhub-encryption)) +``` + +#### Compiled Releases + +```yaml +kit: + features: + - compiled-releases +params: + compiled_releases_bucket: my-compiled-releases +``` + +#### BBR (BOSH Backup and Restore) + +```yaml +kit: + features: + - bbr +``` + +## Director Operations + +### Accessing the Director + +```bash +# Get connection info +genesis bosh my-bosh + +# Target the director +export BOSH_ENVIRONMENT=10.0.0.6 +export BOSH_CLIENT=admin +export BOSH_CLIENT_SECRET=$(safe get secret/my/bosh/director:password) +export BOSH_CA_CERT=$(safe get secret/my/bosh/director:ca) + +# Verify connection +bosh env +``` + +### Common Management Tasks + +#### Update Cloud Config + +```bash +# After deploying director +bosh update-cloud-config cloud-config.yml + +# Verify +bosh cloud-config +``` + +#### Upload Stemcells + +```bash +# Upload Ubuntu stemcell +bosh upload-stemcell \ + https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# List stemcells +bosh stemcells +``` + +#### Manage Releases + +```bash +# Upload releases +bosh upload-release \ + https://bosh.io/d/github.com/cloudfoundry/cf-deployment + +# View releases +bosh releases +``` + +### Director Maintenance + +#### Updating the Director + +```bash +# Update BOSH deployment +genesis deploy my-bosh + +# This safely: +# 1. Updates director software +# 2. Migrates database if needed +# 3. Restarts services +``` + +#### Backing Up the Director + +```bash +# Using BBR +genesis do my-bosh -- backup + +# Manual backup +genesis do my-bosh -- bash +bosh create-env backup.yml \ + --vars-store backup-creds.yml +``` + +#### Monitoring Director Health + +```bash +# Check director status +bosh env + +# View director tasks +bosh tasks --recent + +# Check VM vitals +genesis do my-bosh -- bosh vms --vitals +``` + +## Advanced Configuration + +### Custom Properties + +```yaml +params: + # Database settings + postgres_max_connections: 100 + + # Director settings + director_worker_count: 8 + director_enable_snapshots: true + + # Health monitor + hm_email_recipients: + - ops-team@example.com + hm_email_from: bosh@example.com + + # Blobstore + blobstore_type: s3 + blobstore_bucket: my-bosh-blobstore +``` + +### Network Configuration + +```yaml +params: + # Multiple networks + networks: + - name: bosh + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + static: [10.0.0.6] + dns: [10.0.0.2] + cloud_properties: + subnet: subnet-0123456 +``` + +### Security Hardening + +```yaml +params: + # Remove default users + remove_dev_users: true + + # Enable audit logging + director_enable_audit: true + + # Restrict API access + director_api_accept_from: + - 10.0.0.0/16 + - 192.168.0.0/16 +``` + +## Troubleshooting Directors + +### Common Issues + +#### Director Unreachable + +```bash +# Check VM status (if using proto-bosh) +cd my-bosh-deployments +bosh create-env manifests/bosh.yml \ + --state state.json \ + --vars-store creds.yml + +# Check network connectivity +ping 10.0.0.6 +nc -zv 10.0.0.6 25555 +``` + +#### Database Issues + +```bash +# SSH to director +genesis do my-bosh -- bosh ssh + +# Check PostgreSQL +sudo -u vcap psql -U postgres +\l # List databases +\q # Quit + +# Check logs +sudo tail -f /var/vcap/sys/log/postgres/*.log +``` + +#### Certificate Issues + +```bash +# Regenerate certificates +safe x509 renew secret/my/bosh/director + +# Redeploy +genesis deploy my-bosh +``` + +### Recovery Procedures + +#### Restore from Backup + +```bash +# Using BBR +genesis do my-bosh -- restore --artifact-path=./backup + +# Manual restore +bosh create-env restore.yml \ + --state state.json \ + --vars-store creds.yml +``` + +#### Rebuild Director + +```bash +# Last resort - rebuild +# 1. Backup deployment manifests +# 2. Note all deployments +# 3. Redeploy director +genesis deploy my-bosh --recreate + +# 4. Restore cloud configs +# 5. Re-upload stemcells/releases +# 6. Redeploy all deployments +``` + +## Best Practices + +1. **Regular Backups**: Schedule automated BBR backups +2. **Monitor Health**: Set up alerts for director issues +3. **Update Regularly**: Keep director software current +4. **Separate Directors**: Use different directors for prod/non-prod +5. **Document Configuration**: Maintain clear documentation +6. **Test Recovery**: Regularly test backup/restore procedures + +Managing BOSH directors effectively is crucial for maintaining healthy Genesis deployments across your infrastructure. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/bosh-overview.md b/lib/Genesis/Help/Topics/60-bosh/bosh-overview.md new file mode 100644 index 00000000..f8606bfa --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/bosh-overview.md @@ -0,0 +1,216 @@ +# BOSH Overview + +BOSH is a project that unifies release engineering, deployment, and lifecycle management of small and large-scale cloud software. Genesis builds on top of BOSH to provide a simpler, more opinionated deployment experience. + +## What is BOSH? + +BOSH is an open-source tool for release engineering, deployment, lifecycle management, and monitoring of distributed systems. Key features include: + +- **Reproducible Deployments**: BOSH ensures that deployments are reproducible across different environments +- **Health Monitoring**: Automatic monitoring and resurrection of VMs +- **Rolling Updates**: Safe, zero-downtime updates with automatic rollback +- **Multi-Cloud Support**: Works with AWS, Azure, GCP, vSphere, OpenStack, and more + +## How Genesis Uses BOSH + +Genesis acts as a layer on top of BOSH, providing: + +### 1. Simplified Manifest Generation + +Instead of writing complex BOSH manifests directly, Genesis: +- Uses kits to encapsulate best practices +- Merges environment-specific configurations +- Generates final BOSH manifests automatically + +```bash +# Genesis handles manifest generation +genesis manifest my-env + +# Equivalent to complex BOSH manifest management +bosh -d my-deployment manifest +``` + +### 2. Streamlined Deployment Workflow + +Genesis wraps BOSH commands with additional features: +- Pre-deployment validation +- Secret management integration +- Post-deployment hooks + +```bash +# Genesis deployment +genesis deploy my-env + +# Handles multiple BOSH operations: +# - Uploads releases +# - Validates cloud config +# - Manages secrets +# - Deploys manifest +# - Runs errands +``` + +### 3. Environment Management + +Genesis provides a hierarchical environment structure that BOSH doesn't natively support: + +``` +environments/ +├── us.yml # Shared US configuration +├── us-east.yml # Shared US-East configuration +├── us-east-1.yml # Specific environment +└── us-east-2.yml # Another specific environment +``` + +## BOSH Components + +### BOSH Director + +The BOSH Director is the core component that orchestrates deployments: +- Manages VMs lifecycle +- Stores deployment state +- Handles persistent disks +- Monitors system health + +Genesis can deploy and manage BOSH directors using the BOSH Genesis kit: + +```bash +genesis new my-bosh --kit bosh +genesis deploy my-bosh +``` + +### Cloud Config + +Cloud configuration defines IaaS-specific settings: +- Networks and subnets +- VM types (sizes) +- Availability zones +- Disk types + +Genesis validates that required cloud config elements exist: + +```bash +# Check cloud config compatibility +genesis check my-env + +# Update cloud config +bosh update-cloud-config cloud.yml +``` + +### Releases + +BOSH releases contain the software to be deployed: +- Source code +- Configuration files +- Scripts +- Dependencies + +Genesis kits specify which releases to use: + +```yaml +# In kit.yml +releases: + - name: concourse + version: 7.8.3 + - name: postgres + version: 43 +``` + +### Stemcells + +Stemcells are base OS images that BOSH uses to create VMs: +- Ubuntu-based by default +- IaaS-specific versions +- Security-hardened + +Genesis kits define required stemcells: + +```yaml +# In kit.yml +stemcells: + - os: ubuntu-jammy + version: latest +``` + +## BOSH vs Genesis Concepts + +| BOSH Concept | Genesis Equivalent | Description | +|--------------|-------------------|-------------| +| Deployment | Environment | A running instance of software | +| Manifest | Generated from kit + environment | Deployment configuration | +| Cloud Config | Cloud Config (same) | IaaS settings | +| Runtime Config | Runtime Config (same) | Cross-deployment configuration | +| Release | Specified in kit | Software packages | +| Stemcell | Specified in kit | Base OS image | + +## BOSH State Management + +BOSH maintains state about deployments: +- Current VM instances +- Persistent disk attachments +- Network configurations +- Software versions + +Genesis respects BOSH state while adding: +- Secret rotation tracking +- Feature flag management +- Deployment history + +## Integration Points + +### Direct BOSH Commands + +You can always use BOSH commands directly: + +```bash +# Get BOSH environment details +genesis bosh my-env + +# Then use any BOSH command +bosh -d my-deployment vms +bosh -d my-deployment ssh +bosh -d my-deployment logs +``` + +### BOSH Targeting + +Genesis automatically configures BOSH targeting: + +```bash +# Genesis sets up BOSH environment +genesis do my-env -- bash +# Now $BOSH_ENVIRONMENT, $BOSH_CLIENT, etc. are set +``` + +### Deployment Names + +Genesis uses consistent deployment naming: +- Environment name: `us-east-1-prod` +- BOSH deployment: `us-east-1-prod-concourse` +- Format: `[env-name]-[kit-name]` + +## When to Use BOSH Directly + +While Genesis handles most operations, use BOSH directly for: + +1. **Debugging**: Examining VM state, logs, processes +2. **Advanced Operations**: Recreating VMs, manual resurrection +3. **Emergency Recovery**: Fixing broken deployments +4. **Custom Errands**: Running deployment-specific tasks + +```bash +# Common BOSH operations +bosh -d my-deployment vms --vitals +bosh -d my-deployment recreate web/0 +bosh -d my-deployment cloud-check +bosh -d my-deployment run-errand smoke-tests +``` + +## Best Practices + +1. **Let Genesis Handle Manifests**: Don't modify generated manifests directly +2. **Use Genesis Deploy**: Prefer `genesis deploy` over `bosh deploy` +3. **Understand the Stack**: Know when to use Genesis vs BOSH commands +4. **Monitor BOSH Health**: Keep directors updated and healthy +5. **Backup BOSH State**: Regular director database backups + +Understanding BOSH fundamentals helps you troubleshoot issues and perform advanced operations while leveraging Genesis for day-to-day deployment management. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/bosh-troubleshooting.md b/lib/Genesis/Help/Topics/60-bosh/bosh-troubleshooting.md new file mode 100644 index 00000000..8310fc35 --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/bosh-troubleshooting.md @@ -0,0 +1,526 @@ +# BOSH Troubleshooting + +This guide helps diagnose and resolve common BOSH-related issues in Genesis deployments. + +## Common Issues + +### Deployment Failures + +#### Symptom: Deployment Times Out + +```bash +Task 1234 | Error: Timed out sending 'apply' to instance 'web/abc-123' +``` + +**Diagnosis:** +```bash +# Check task details +bosh task 1234 --debug + +# Check instance status +bosh -d my-deployment instances --ps + +# SSH to problematic instance +bosh -d my-deployment ssh web/abc-123 +``` + +**Common Causes:** +1. VM not starting properly +2. Network connectivity issues +3. BOSH agent not responding +4. Insufficient resources + +**Solutions:** +```bash +# Recreate the instance +bosh -d my-deployment recreate web/abc-123 + +# Check cloud infrastructure +bosh -d my-deployment cloud-check + +# Increase timeout (if appropriate) +bosh -d my-deployment deploy --max-in-flight=1 +``` + +#### Symptom: Package Compilation Failures + +```bash +Task 1234 | Error: Package compilation failed +``` + +**Diagnosis:** +```bash +# View compilation logs +bosh task 1234 --debug | grep -A50 "compilation failed" + +# Check compilation VMs +bosh -d my-deployment vms --details +``` + +**Solutions:** +```bash +# Use compiled releases +genesis set my-env compiled_releases true + +# Increase compilation resources +# In cloud-config.yml: +compilation: + workers: 5 + vm_type: large # Bigger VMs + network: default +``` + +### VM Issues + +#### Symptom: VMs Not Starting + +```bash +# Instance stuck in "starting" state +web/0 (abc-123) starting +``` + +**Diagnosis:** +```bash +# Check VM vitals +bosh -d my-deployment vms --vitals + +# View agent logs +bosh -d my-deployment ssh web/0 +sudo tail -f /var/vcap/bosh/log/current + +# Check monit status +sudo monit summary +``` + +**Common Issues:** +1. **Disk full:** + ```bash + df -h + # Clear logs if needed + sudo find /var/vcap/sys/log -name "*.log" -mtime +7 -delete + ``` + +2. **Memory exhausted:** + ```bash + free -m + ps aux --sort=-%mem | head + ``` + +3. **Process failing to start:** + ```bash + sudo tail -f /var/vcap/sys/log/*/current + sudo monit restart all + ``` + +#### Symptom: VM Unresponsive + +**Quick Checks:** +```bash +# From director +bosh -d my-deployment ssh web/0 -c "echo 'VM responsive'" + +# Check from director VM +ssh vcap@ + +# Network connectivity +bosh -d my-deployment ssh other-vm +ping +``` + +**Recovery:** +```bash +# Restart VM +bosh -d my-deployment restart web/0 + +# Hard recreate +bosh -d my-deployment recreate web/0 --force +``` + +### Network Issues + +#### Symptom: Cannot Reach Other VMs + +**Diagnosis:** +```bash +# Check network configuration +bosh -d my-deployment ssh web/0 +ip addr show +ip route show +cat /etc/resolv.conf + +# Test connectivity +ping +nslookup other-vm.deployment.bosh +``` + +**Common Fixes:** +1. **DNS Issues:** + ```bash + # Check BOSH DNS + sudo monit summary | grep bosh-dns + dig @169.254.0.2 google.com + + # Restart BOSH DNS + sudo monit restart bosh-dns + ``` + +2. **Firewall/Security Groups:** + ```bash + # Verify security groups (AWS) + aws ec2 describe-security-groups --group-ids sg-xxxxx + + # Test specific ports + nc -zv other-vm 8080 + ``` + +### Persistent Disk Issues + +#### Symptom: Disk Full or Missing + +**Check Disk Status:** +```bash +# List disks +bosh -d my-deployment disks + +# On VM +df -h +lsblk +mount | grep persistent +``` + +**Solutions:** + +1. **Expand Disk:** + ```yaml + # Update manifest + instance_groups: + - name: database + persistent_disk_type: large # Bigger disk type + ``` + ```bash + # Apply change + genesis deploy my-env + ``` + +2. **Migrate Data:** + ```bash + # Stop jobs + bosh -d my-deployment stop database/0 + + # Attach new disk + bosh -d my-deployment attach-disk database/0 disk-xxxxx + + # Start and migrate + bosh -d my-deployment start database/0 + ``` + +### Certificate Issues + +#### Symptom: TLS/Certificate Errors + +**Diagnosis:** +```bash +# Check certificate expiry +bosh -d my-deployment ssh web/0 +openssl x509 -in /var/vcap/jobs/web/config/cert.pem -noout -dates + +# Verify certificate chain +openssl verify -CAfile ca.pem cert.pem +``` + +**Solutions:** +```bash +# Regenerate certificates via Genesis +genesis rotate-certs my-env + +# Or manually via Vault +safe x509 renew secret/my/env/ssl/server --ttl 90d + +# Redeploy +genesis deploy my-env +``` + +## Director Issues + +### Director Unreachable + +**Quick Diagnostics:** +```bash +# Test connectivity +curl -k https://:25555/info + +# Check from jump box +nc -zv 25555 + +# Verify environment variables +echo $BOSH_ENVIRONMENT +echo $BOSH_CLIENT +``` + +**Common Fixes:** + +1. **Network Path:** + ```bash + # Trace route + traceroute + + # Check security groups/firewalls + ``` + +2. **Director Services:** + ```bash + # SSH to director (if proto-bosh) + # Check services + sudo monit summary + sudo tail -f /var/vcap/sys/log/director/current + ``` + +### Database Issues + +**Symptoms:** +- Slow deployments +- "Database is locked" errors +- Connection timeouts + +**Diagnosis:** +```bash +# On director VM +sudo -u vcap psql -U postgres +\l # List databases +\c bosh # Connect to bosh db +SELECT count(*) FROM deployments; +SELECT count(*) FROM tasks; +``` + +**Maintenance:** +```bash +# Clean old tasks +bosh clean-up --all + +# Vacuum database +sudo -u vcap psql -U postgres -d bosh -c "VACUUM ANALYZE;" + +# Restart director +sudo monit restart director +``` + +## Advanced Troubleshooting + +### Enable Debug Logging + +```bash +# For specific deployment +bosh -d my-deployment deploy manifest.yml --debug + +# For specific instance +bosh -d my-deployment ssh web/0 +sudo su - +echo "debug" > /var/vcap/bosh/etc/level +``` + +### Cloud Check + +Automated problem resolution: + +```bash +# Interactive mode +bosh -d my-deployment cloud-check + +# Automatic resolution +bosh -d my-deployment cloud-check --auto + +# Report only +bosh -d my-deployment cloud-check --report +``` + +Common resolutions: +- Recreate unresponsive VMs +- Reattach persistent disks +- Delete missing VMs from state + +### Manual State Cleanup + +**Warning: Advanced operation** + +```bash +# Export current state +bosh -d my-deployment manifest > current-manifest.yml + +# Remove instance from state +bosh -d my-deployment delete-vm + +# Recreate +bosh -d my-deployment deploy current-manifest.yml +``` + +### Task Analysis + +```bash +# List recent failed tasks +bosh tasks --recent --failed + +# Analyze specific task +bosh task --debug > task-debug.log + +# Common error patterns +grep -E "(error|failed|timeout)" task-debug.log +``` + +## Performance Issues + +### Slow Deployments + +**Diagnosis:** +```bash +# Check task timing +bosh task --event + +# Monitor director load +bosh -d director ssh +top +iostat -x 1 +``` + +**Optimizations:** + +1. **Parallel Operations:** + ```yaml + # In manifest + update: + max_in_flight: 10 # Increase parallelism + ``` + +2. **Compiled Releases:** + ```bash + # Use pre-compiled releases + bosh upload-release compiled-release.tgz + ``` + +3. **Local Blobstore:** + ```yaml + # For directors with many deployments + blobstore: + provider: local + path: /var/vcap/store/blobstore + ``` + +## Recovery Procedures + +### Emergency VM Recovery + +```bash +#!/bin/bash +# emergency-recover.sh + +DEPLOYMENT=$1 +INSTANCE=$2 + +echo "Attempting recovery of $INSTANCE in $DEPLOYMENT" + +# Stop instance +bosh -d $DEPLOYMENT stop $INSTANCE + +# Cloud check +bosh -d $DEPLOYMENT cloud-check --auto + +# Recreate +bosh -d $DEPLOYMENT recreate $INSTANCE + +# Verify +bosh -d $DEPLOYMENT instances --ps +``` + +### State File Recovery + +When deployment state is corrupted: + +```bash +# Backup current state +cp ~/.bosh/state.json state.json.backup + +# Recreate from manifest +bosh create-env manifest.yml \ + --state=state.json \ + --vars-store=creds.yml \ + --recreate + +# For managed deployments +bosh -d my-deployment deploy manifest.yml --recreate +``` + +## Monitoring and Prevention + +### Health Checks + +Regular health monitoring: + +```bash +#!/bin/bash +# bosh-health-check.sh + +echo "=== Director Health ===" +bosh env + +echo "=== Deployments ===" +bosh deployments + +echo "=== Problem Instances ===" +for d in $(bosh deployments --json | jq -r '.Tables[0].Rows[].name'); do + echo "Checking $d..." + bosh -d $d instances --ps | grep -v running || true +done + +echo "=== Recent Failed Tasks ===" +bosh tasks --recent=10 --failed +``` + +### Preventive Maintenance + +```bash +# Weekly maintenance script +#!/bin/bash + +# Clean up old releases +bosh clean-up --all + +# Check disk usage +bosh -d director ssh -c "df -h" + +# Verify backups +genesis do my-bosh -- bbr deployment backup + +# Update stemcells +bosh stemcells --recent +``` + +## Getting Help + +### Collecting Diagnostics + +When reporting issues: + +```bash +# Collect bundle +bosh -d my-deployment logs --all + +# Director info +bosh env --json > director-info.json + +# Task details +bosh task --debug > task-output.log + +# Manifest (sanitized) +bosh -d my-deployment manifest | \ + sed 's/password: .*/password: REDACTED/g' > manifest.yml +``` + +### Debug Information + +Include in bug reports: +- Genesis version: `genesis version` +- BOSH version: `bosh env` +- Kit version: `genesis kit-info` +- Error messages and task IDs +- Steps to reproduce + +Effective troubleshooting combines understanding BOSH internals with systematic diagnosis and proper tooling. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/cloud-config.md b/lib/Genesis/Help/Topics/60-bosh/cloud-config.md new file mode 100644 index 00000000..0d3da33c --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/cloud-config.md @@ -0,0 +1,512 @@ +# Cloud Config Management + +Cloud configuration in BOSH defines IaaS-specific settings that are shared across deployments. This guide covers managing cloud configs for Genesis deployments. + +## Overview + +Cloud config separates IaaS settings from deployment manifests: +- **Networks**: Subnets, gateways, DNS servers +- **VM Types**: Instance sizes (t2.micro, Standard_DS1_v2, etc.) +- **Disk Types**: Persistent disk configurations +- **Availability Zones**: IaaS-specific zones/regions +- **Compilation**: Workers for package compilation + +## Cloud Config Structure + +### Basic Structure + +```yaml +azs: +- name: z1 + cloud_properties: + availability_zone: us-east-1a + +- name: z2 + cloud_properties: + availability_zone: us-east-1b + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: z1 + static: [10.0.0.5-10.0.0.50] + dns: [8.8.8.8, 8.8.4.4] + cloud_properties: + subnet: subnet-0123456789abcdef0 + +vm_types: +- name: small + cloud_properties: + instance_type: t3.small + ephemeral_disk: + size: 10240 + type: gp3 + +- name: large + cloud_properties: + instance_type: t3.large + ephemeral_disk: + size: 32768 + type: gp3 + +disk_types: +- name: small + disk_size: 10240 + cloud_properties: + type: gp3 + +- name: large + disk_size: 51200 + cloud_properties: + type: gp3 + +compilation: + workers: 5 + reuse_compilation_vms: true + az: z1 + vm_type: large + network: default +``` + +## Managing Cloud Configs + +### Viewing Current Config + +```bash +# View current cloud config +bosh cloud-config + +# Save to file +bosh cloud-config > cloud-config.yml +``` + +### Updating Cloud Config + +```bash +# Update cloud config +bosh update-cloud-config cloud-config.yml + +# Update with variables +bosh update-cloud-config cloud-config.yml \ + -v vpc_id=vpc-12345 \ + -v subnet_id=subnet-67890 +``` + +### Multiple Cloud Configs + +BOSH 2.0+ supports multiple named configs: + +```bash +# Upload named configs +bosh update-config --type=cloud --name=base base-cloud.yml +bosh update-config --type=cloud --name=aws aws-cloud.yml + +# List configs +bosh configs +``` + +## IaaS-Specific Examples + +### AWS Cloud Config + +```yaml +azs: +- name: us-east-1a + cloud_properties: + availability_zone: us-east-1a + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: us-east-1a + reserved: [10.0.0.1-10.0.0.5] + static: [10.0.0.6-10.0.0.50] + dns: [10.0.0.2] + cloud_properties: + subnet: subnet-0123456789abcdef0 + security_groups: [sg-0123456789abcdef0] + +vm_types: +- name: small + cloud_properties: + instance_type: t3.small + ephemeral_disk: + size: 10240 + type: gp3 + security_groups: [bosh-vms] + iam_instance_profile: bosh-vm-role + +disk_types: +- name: default + disk_size: 10240 + cloud_properties: + type: gp3 + encrypted: true + kms_key_id: alias/bosh-disks + +vm_extensions: +- name: elb + cloud_properties: + elbs: [my-elb] +``` + +### Azure Cloud Config + +```yaml +azs: +- name: z1 + cloud_properties: + availability_zone: "1" + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: z1 + dns: [168.63.129.16] + cloud_properties: + virtual_network_name: bosh-vnet + subnet_name: bosh-subnet + resource_group_name: bosh-rg + +vm_types: +- name: small + cloud_properties: + instance_type: Standard_B2s + root_disk: + size: 30720 + ephemeral_disk: + use_root_disk: false + size: 10240 + +disk_types: +- name: default + disk_size: 10240 + cloud_properties: + storage_account_type: Standard_LRS + caching: ReadWrite +``` + +### vSphere Cloud Config + +```yaml +azs: +- name: z1 + cloud_properties: + datacenters: + - name: dc1 + clusters: + - cluster1: + resource_pool: bosh-rp + +networks: +- name: default + type: manual + subnets: + - range: 10.0.0.0/24 + gateway: 10.0.0.1 + az: z1 + dns: [10.0.0.2] + cloud_properties: + name: VM Network + +vm_types: +- name: small + cloud_properties: + cpu: 2 + ram: 2048 + disk: 10240 + +disk_types: +- name: default + disk_size: 10240 + cloud_properties: + type: thin +``` + +## Genesis Integration + +### Validation + +Genesis validates cloud config before deployment: + +```bash +# Check if cloud config has required resources +genesis check my-env + +# Example output: +# Checking cloud config... +# ✓ VM type 'small' exists +# ✓ VM type 'large' exists +# ✓ Network 'default' exists +# ✓ Disk type 'default' exists +``` + +### Kit Requirements + +Kits specify cloud config requirements: + +```yaml +# In kit.yml +cloud_config_requirements: + vm_types: + - name: small + minimum_instance_size: + cpu: 2 + ram: 2048 + - name: large + minimum_instance_size: + cpu: 4 + ram: 8192 + + networks: + - name: default + type: manual + + disk_types: + - name: default + minimum_size: 10240 +``` + +### Environment Overrides + +Override cloud config names in environments: + +```yaml +# my-env.yml +params: + # Use different VM types + vm_type: custom-small + + # Use different network + network: production + + # Use different disk type + persistent_disk_type: fast-ssd +``` + +## Advanced Features + +### VM Extensions + +Add cloud properties to specific instance groups: + +```yaml +vm_extensions: +- name: load-balancer + cloud_properties: + elbs: [web-elb] + +- name: public-ip + cloud_properties: + associate_public_ip_address: true +``` + +Use in deployment: + +```yaml +instance_groups: +- name: web + vm_type: small + vm_extensions: [load-balancer, public-ip] +``` + +### Custom Cloud Properties + +Pass IaaS-specific settings: + +```yaml +vm_types: +- name: gpu + cloud_properties: + instance_type: p3.2xlarge + placement_group: gpu-cluster + dedicated_host_id: h-0123456789abcdef0 +``` + +### Compilation Workers + +Optimize compilation: + +```yaml +compilation: + workers: 10 + reuse_compilation_vms: true + az: z1 + vm_type: xlarge # Fast compilation + network: compilation # Dedicated network + env: + bosh: + password: $6$salt$encrypted # For SSH access +``` + +## Multi-Cloud Configurations + +### Separate Configs by IaaS + +```bash +# AWS environments +bosh update-config --type=cloud --name=aws \ + aws-cloud-config.yml + +# Azure environments +bosh update-config --type=cloud --name=azure \ + azure-cloud-config.yml + +# vSphere environments +bosh update-config --type=cloud --name=vsphere \ + vsphere-cloud-config.yml +``` + +### Environment Selection + +```yaml +# aws-prod.yml +cloud_config: + - aws + - production-overrides + +# azure-dev.yml +cloud_config: + - azure + - development-overrides +``` + +## Best Practices + +### 1. Standardize Naming + +Use consistent names across environments: + +```yaml +vm_types: +- name: small # 2 CPU, 4GB RAM +- name: medium # 4 CPU, 8GB RAM +- name: large # 8 CPU, 16GB RAM +- name: xlarge # 16 CPU, 32GB RAM +``` + +### 2. Document Sizing + +Include comments for clarity: + +```yaml +vm_types: +- name: web + # Web servers: 2 CPU, 4GB RAM, 10GB disk + cloud_properties: + instance_type: t3.medium +``` + +### 3. Network Segmentation + +Separate networks by purpose: + +```yaml +networks: +- name: management # BOSH directors +- name: data # Databases +- name: web # Web-facing +- name: compilation # Compilation only +``` + +### 4. Reserve IPs + +Prevent conflicts: + +```yaml +subnets: +- range: 10.0.0.0/24 + reserved: + - 10.0.0.1-10.0.0.10 # Network devices + - 10.0.0.100-10.0.0.110 # Future use + static: + - 10.0.0.11-10.0.0.99 # Static assignments +``` + +### 5. Version Control + +Track cloud config changes: + +```bash +# Before updating +bosh cloud-config > cloud-config-backup-$(date +%Y%m%d).yml + +# Commit to git +git add cloud-config.yml +git commit -m "Add new GPU VM types" +``` + +## Troubleshooting + +### Missing Resources + +```bash +# Error: Can't find VM type 'large' +# Solution: Check cloud config +bosh cloud-config | grep -A5 "vm_types" + +# Add missing type +bosh update-cloud-config updated-cloud.yml +``` + +### Network Issues + +```bash +# Error: No IP available in network 'default' +# Check subnet allocation +bosh cloud-config | grep -A20 "networks" + +# Expand static range if needed +``` + +### Compilation Failures + +```bash +# Increase compilation workers +compilation: + workers: 10 # Increase from 5 + +# Use bigger VMs + vm_type: xlarge # Instead of large +``` + +## Migration Strategies + +### Updating Existing Deployments + +```bash +# 1. Update cloud config +bosh update-cloud-config new-cloud-config.yml + +# 2. Recreate deployments to pick up changes +genesis deploy my-env --recreate + +# Or selectively update +bosh -d my-deployment recreate +``` + +### Renaming Resources + +Handle with aliases: + +```yaml +vm_types: +- name: small + cloud_properties: + instance_type: t3.small + +- name: default # Alias for backward compatibility + cloud_properties: + instance_type: t3.small +``` + +Effective cloud config management ensures your Genesis deployments have the proper IaaS resources while maintaining consistency across environments. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/index.md b/lib/Genesis/Help/Topics/60-bosh/index.md new file mode 100644 index 00000000..f87883a7 --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/index.md @@ -0,0 +1,32 @@ +# BOSH Integration + +Genesis leverages BOSH as its underlying deployment engine. This section covers how Genesis integrates with BOSH and how to effectively use BOSH commands with Genesis deployments. + +## Topics in this Section + +### [BOSH Overview](bosh-overview.md) +Understanding BOSH and its role in Genesis deployments. + +### [Working with BOSH](working-with-bosh.md) +Common BOSH operations and how they relate to Genesis. + +### [BOSH Directors](bosh-directors.md) +Managing BOSH directors with Genesis. + +### [Cloud Config Management](cloud-config.md) +Managing BOSH cloud configurations for Genesis deployments. + +### [Runtime Config Management](runtime-config.md) +Using BOSH runtime configs with Genesis. + +### [Stemcells and Releases](stemcells-releases.md) +Managing BOSH stemcells and releases in Genesis deployments. + +### [BOSH Troubleshooting](bosh-troubleshooting.md) +Debugging BOSH-related issues in Genesis deployments. + +## Quick Links + +- [Genesis deploy command](../20-commands/deploy.md) +- [BOSH CLI Reference](https://bosh.io/docs/cli-v2/) +- [Cloud Config Concepts](https://bosh.io/docs/cloud-config/) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/runtime-config.md b/lib/Genesis/Help/Topics/60-bosh/runtime-config.md new file mode 100644 index 00000000..9629362c --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/runtime-config.md @@ -0,0 +1,533 @@ +# Runtime Config Management + +Runtime configurations in BOSH apply settings across all deployments on a director. This guide covers managing runtime configs with Genesis. + +## Overview + +Runtime configs provide: +- **Cross-cutting concerns**: DNS, syslog, monitoring agents +- **Security policies**: OS hardening, compliance tools +- **Operational tools**: Debugging utilities, backup agents +- **Network policies**: MTU settings, custom routes + +## Runtime Config Structure + +### Basic Structure + +```yaml +releases: +- name: os-conf + version: 22.1.0 + +addons: +- name: os-configuration + jobs: + - name: sysctl + release: os-conf + properties: + sysctl: + kernel.panic: 10 + net.ipv4.tcp_syncookies: 1 + include: + deployments: [all] + +- name: dns + jobs: + - name: bosh-dns + release: bosh-dns + properties: + cache: + enabled: true + api: + server: + tls: ((/dns_api_server_tls)) +``` + +## Common Runtime Configs + +### DNS Configuration + +Modern BOSH DNS setup: + +```yaml +releases: +- name: bosh-dns + version: 1.36.0 + +addons: +- name: bosh-dns + jobs: + - name: bosh-dns + release: bosh-dns + properties: + cache: + enabled: true + max_entries: 10000 + health: + enabled: true + server: + tls: ((/dns_healthcheck_server_tls)) + api: + server: + tls: ((/dns_api_server_tls)) + include: + deployments: [all] +``` + +### Syslog Forwarding + +Centralized logging: + +```yaml +releases: +- name: syslog + version: 11.7.0 + +addons: +- name: syslog-forwarder + jobs: + - name: syslog_forwarder + release: syslog + properties: + syslog: + address: syslog.example.com + port: 514 + transport: tcp + tls: + enabled: true + ca_cert: | + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- + include: + deployments: [all] + exclude: + deployments: [bosh] # Don't forward BOSH's own logs +``` + +### Monitoring Agents + +Prometheus node exporter: + +```yaml +releases: +- name: node-exporter + version: 4.2.0 + +addons: +- name: node-exporter + jobs: + - name: node_exporter + release: node-exporter + properties: + node_exporter: + collectors: + - cpu + - diskstats + - filesystem + - loadavg + - meminfo + - netstat + - time + - vmstat + include: + deployments: [all] +``` + +### OS Hardening + +Security baseline: + +```yaml +releases: +- name: os-conf + version: 22.1.0 + +addons: +- name: os-hardening + jobs: + - name: sysctl + release: os-conf + properties: + sysctl: + # Kernel hardening + kernel.randomize_va_space: 2 + kernel.exec-shield: 1 + + # Network hardening + net.ipv4.conf.all.accept_source_route: 0 + net.ipv4.conf.all.accept_redirects: 0 + net.ipv4.conf.all.send_redirects: 0 + net.ipv4.conf.all.log_martians: 1 + net.ipv4.tcp_syncookies: 1 + + # Disable IPv6 if not used + net.ipv6.conf.all.disable_ipv6: 1 + + - name: login_banner + release: os-conf + properties: + login_banner: + text: | + UNAUTHORIZED ACCESS TO THIS DEVICE IS PROHIBITED + All activities performed on this device are logged. + include: + deployments: [all] +``` + +## Managing Runtime Configs + +### Viewing Runtime Configs + +```bash +# View current runtime config +bosh runtime-config + +# List all runtime configs +bosh configs --type=runtime + +# View specific named config +bosh config --type=runtime --name=dns +``` + +### Updating Runtime Configs + +```bash +# Update default runtime config +bosh update-runtime-config runtime.yml + +# Update named runtime config +bosh update-config --type=runtime --name=dns dns-runtime.yml + +# Update with variables +bosh update-runtime-config runtime.yml \ + -v syslog_address=10.0.0.100 +``` + +### Multiple Runtime Configs + +Layer configs for different purposes: + +```bash +# Base OS configuration +bosh update-config --type=runtime --name=os-baseline \ + os-baseline.yml + +# Monitoring agents +bosh update-config --type=runtime --name=monitoring \ + monitoring.yml + +# Security tools +bosh update-config --type=runtime --name=security \ + security.yml +``` + +## Genesis Integration + +### Kit-Provided Runtime Configs + +Some kits include runtime configs: + +```yaml +# In kit.yml +runtime_configs: + - name: dns + file: runtime-configs/dns.yml + - name: syslog + file: runtime-configs/syslog.yml +``` + +Apply them: + +```bash +# Apply kit runtime configs +genesis do my-env -- apply-runtime-configs +``` + +### Environment-Specific Configs + +Override for specific environments: + +```yaml +# production.yml +params: + runtime_config_overrides: + syslog_address: prod-syslog.example.com + monitoring_enabled: true +``` + +## Advanced Usage + +### Conditional Inclusion + +Target specific deployments: + +```yaml +addons: +- name: debug-tools + jobs: + - name: toolbelt + release: toolbelt + include: + deployments: + - /.*-dev$/ # Dev deployments only + - /.*-staging$/ # Staging deployments + exclude: + deployments: + - /.*-prod$/ # Not in production + +- name: production-monitoring + jobs: + - name: enhanced-monitoring + release: monitoring + include: + deployments: + - /.*-prod$/ # Production only +``` + +### Instance Group Targeting + +Apply to specific instance groups: + +```yaml +addons: +- name: database-tools + jobs: + - name: db-backup-agent + release: backup-tools + include: + instance_groups: + - database + - mysql + - postgres + +- name: web-monitoring + jobs: + - name: nginx-exporter + release: prometheus-exporters + include: + instance_groups: + - web + - api + - router +``` + +### Job Placement + +Control where jobs run: + +```yaml +addons: +- name: colocated-dns + placement: + include: + - colocated: true # Only on VMs with other jobs + jobs: + - name: bosh-dns + release: bosh-dns + +- name: dedicated-monitoring + placement: + exclude: + - colocated: true # Only on dedicated VMs + jobs: + - name: telegraf + release: telegraf +``` + +## Best Practices + +### 1. Layered Configuration + +Organize configs by concern: + +```bash +# Structure +runtime-configs/ +├── 01-os-baseline.yml # OS settings +├── 02-dns.yml # DNS configuration +├── 03-monitoring.yml # Monitoring agents +├── 04-security.yml # Security tools +└── 05-logging.yml # Log forwarding +``` + +### 2. Version Control + +Track all runtime configs: + +```bash +# Before updating +bosh runtime-config > backup/runtime-$(date +%Y%m%d).yml + +# After updating +git add runtime-configs/ +git commit -m "Enable TLS for syslog forwarding" +``` + +### 3. Test in Non-Production + +```bash +# Test in dev first +bosh -e dev-bosh update-runtime-config new-runtime.yml + +# Verify with deployment +bosh -d test-deployment recreate + +# Then apply to production +bosh -e prod-bosh update-runtime-config new-runtime.yml +``` + +### 4. Document Dependencies + +```yaml +# monitoring.yml +# Dependencies: +# - Prometheus server at prometheus.example.com:9090 +# - Grafana dashboards: https://grafana.example.com +# - Alert manager: https://alerts.example.com + +releases: +- name: node-exporter + version: 4.2.0 + # Download: bosh upload-release https://bosh.io/d/github.com/cloudfoundry-community/node-exporter-boshrelease +``` + +### 5. Monitor Impact + +Check runtime config effects: + +```bash +# Check addon resource usage +bosh -d my-deployment ssh web/0 +ps aux | grep node_exporter +df -h # Check disk usage + +# Verify functionality +curl localhost:9100/metrics # Node exporter +``` + +## Common Patterns + +### Multi-Site Configuration + +Different configs per site: + +```yaml +# us-east runtime config +addons: +- name: dns + jobs: + - name: bosh-dns + properties: + handlers: + - domain: east.example.com + forward: 10.1.0.2 + +# us-west runtime config +addons: +- name: dns + jobs: + - name: bosh-dns + properties: + handlers: + - domain: west.example.com + forward: 10.2.0.2 +``` + +### Progressive Rollout + +Test new configs gradually: + +```yaml +# Phase 1: Dev only +include: + deployments: [/.*-dev$/] + +# Phase 2: Dev + Staging +include: + deployments: [/.*-(dev|staging)$/] + +# Phase 3: All environments +include: + deployments: [all] +``` + +## Troubleshooting + +### Addon Not Applied + +```bash +# Check if addon matches +bosh -d my-deployment manifest | grep -A20 addons + +# Verify inclusion rules +# Does deployment name match? +# Is instance group included? +``` + +### Conflicts with Deployment + +```bash +# Error: Job 'syslog_forwarder' already exists +# Solution: Check deployment manifest +bosh -d my-deployment manifest | grep syslog_forwarder + +# Remove from deployment or runtime config +``` + +### Performance Impact + +```bash +# Too many addons slowing deployments +# Solution: Consolidate addons +addons: +- name: monitoring-suite # Combine multiple agents + jobs: + - name: node_exporter + - name: process_exporter + - name: postgres_exporter +``` + +## Migration Strategies + +### From Deployment to Runtime + +Move common jobs to runtime config: + +```bash +# 1. Identify common jobs across deployments +for d in $(bosh deployments --json | jq -r '.Tables[0].Rows[].name'); do + echo "=== $d ===" + bosh -d $d manifest | grep -A5 "jobs:" | grep "name:" +done + +# 2. Create runtime config +# 3. Remove from deployment manifests +# 4. Apply runtime config +# 5. Update deployments +``` + +### Updating Releases + +Safely update runtime releases: + +```bash +# 1. Upload new release +bosh upload-release new-release.tgz + +# 2. Update runtime config with new version +bosh update-runtime-config updated-runtime.yml + +# 3. Recreate deployments to pick up changes +# Option 1: All at once +for d in $(bosh deployments --json | jq -r '.Tables[0].Rows[].name'); do + bosh -d $d recreate +done + +# Option 2: Canary approach +bosh -d canary-deployment recreate +# Verify... +bosh -d production-deployment recreate +``` + +Runtime configs provide powerful cross-cutting functionality for all Genesis deployments while maintaining separation of concerns. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/stemcells-releases.md b/lib/Genesis/Help/Topics/60-bosh/stemcells-releases.md new file mode 100644 index 00000000..2dc1434d --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/stemcells-releases.md @@ -0,0 +1,471 @@ +# Stemcells and Releases + +BOSH uses stemcells and releases as the building blocks for deployments. This guide covers managing these components in Genesis deployments. + +## Overview + +### Stemcells +- Base operating system images +- IaaS-specific versions +- Security-hardened and minimal +- Regular updates for patches + +### Releases +- Packaged software and configurations +- Jobs, packages, and templates +- Version-controlled artifacts +- Compiled or source format + +## Working with Stemcells + +### Understanding Stemcells + +Stemcells follow a naming convention: +``` +bosh-[iaas]-[hypervisor]-[os]-[version] + +Examples: +bosh-aws-xen-hvm-ubuntu-jammy-go_agent +bosh-azure-hyperv-ubuntu-jammy-go_agent +bosh-vsphere-esxi-ubuntu-jammy-go_agent +``` + +### Managing Stemcells + +```bash +# List uploaded stemcells +bosh stemcells + +# Upload a stemcell +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# Upload specific version +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent?v=1.123 + +# Upload from file +bosh upload-stemcell ~/downloads/bosh-stemcell-1.123-aws-xen-hvm-ubuntu-jammy-go_agent.tgz + +# Delete a stemcell +bosh delete-stemcell ubuntu-jammy/1.123 + +# Clean up unused stemcells +bosh clean-up --all +``` + +### Kit Stemcell Requirements + +Genesis kits specify required stemcells: + +```yaml +# In kit.yml +stemcells: + - os: ubuntu-jammy + version: latest + - os: ubuntu-bionic + version: 621.+ # Minimum version +``` + +Check current kit requirements: + +```bash +# View kit metadata +genesis kit-info my-kit + +# Example output: +# Stemcells: +# - ubuntu-jammy (latest) +# - ubuntu-bionic (621.+) +``` + +### Stemcell Updates + +Keep stemcells current for security: + +```bash +# Check for updates +bosh stemcells --recent + +# Update procedure +# 1. Upload new stemcell +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# 2. Update deployment (Genesis handles manifest update) +genesis deploy my-env + +# 3. Clean up old stemcell +bosh clean-up +``` + +## Working with Releases + +### Understanding Releases + +BOSH releases contain: +- **Jobs**: Running processes and configurations +- **Packages**: Compiled software and dependencies +- **Source**: Original source code +- **Manifest**: Release metadata + +### Managing Releases + +```bash +# List uploaded releases +bosh releases + +# Upload a release from URL +bosh upload-release https://bosh.io/d/github.com/cloudfoundry/cf-deployment + +# Upload specific version +bosh upload-release https://bosh.io/d/github.com/cloudfoundry/cf-deployment?v=16.1.0 + +# Upload from file +bosh upload-release ~/releases/concourse-7.8.3.tgz + +# Delete a release +bosh delete-release concourse/7.8.2 + +# Clean up unused releases +bosh clean-up --all +``` + +### Kit Release Management + +Genesis kits manage releases automatically: + +```yaml +# In kit.yml +releases: + - name: concourse + version: 7.8.3 + url: https://bosh.io/d/github.com/concourse/concourse-bosh-release?v=7.8.3 + sha1: abcd1234... + + - name: postgres + version: "43" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=43 + sha1: efgh5678... + + - name: bpm + version: 1.1.21 + url: https://bosh.io/d/github.com/cloudfoundry/bpm-release?v=1.1.21 + sha1: ijkl9012... +``` + +Genesis handles release uploads during deployment: + +```bash +# Genesis automatically uploads required releases +genesis deploy my-env + +# Manual release management +genesis do my-env -- upload-releases +``` + +### Compiled Releases + +Use compiled releases for faster deployments: + +```bash +# Export compiled release +bosh -d my-deployment export-release concourse/7.8.3 ubuntu-jammy/1.123 + +# Creates: concourse-7.8.3-ubuntu-jammy-1.123.tgz + +# Upload compiled release +bosh upload-release concourse-7.8.3-ubuntu-jammy-1.123.tgz +``` + +Enable in Genesis: + +```yaml +# In environment file +params: + use_compiled_releases: true + compiled_release_bucket: my-compiled-releases +``` + +## Release Development + +### Creating Custom Releases + +For Genesis kit development: + +```bash +# Initialize release +bosh init-release + +# Create job +bosh generate-job my-service + +# Create package +bosh generate-package my-app + +# Build release +bosh create-release --force + +# Upload dev release +bosh upload-release +``` + +### Local Release Testing + +```yaml +# In kit development +releases: + - name: my-release + version: latest + url: file:///home/user/my-release +``` + +## Advanced Management + +### Release Dependencies + +Handle transitive dependencies: + +```yaml +# Some releases need others +releases: + - name: routing # Depends on bpm + version: 0.213.0 + + - name: bpm # Required by routing + version: 1.1.21 +``` + +### Version Constraints + +Specify version requirements: + +```yaml +releases: + - name: concourse + version: 7.8.+ # Any 7.8.x version + + - name: postgres + version: ">=42" # Version 42 or higher + + - name: garden + version: 1.19.16 # Exact version +``` + +### Multi-OS Support + +Different stemcells for different jobs: + +```yaml +stemcells: + - alias: default + os: ubuntu-jammy + version: latest + + - alias: windows + os: windows2019 + version: latest + +instance_groups: + - name: web + stemcell: default + + - name: mssql + stemcell: windows +``` + +## Best Practices + +### 1. Regular Updates + +Create an update schedule: + +```bash +#!/bin/bash +# check-updates.sh + +echo "=== Stemcell Updates ===" +bosh stemcells --recent + +echo "=== Release Updates ===" +for release in $(bosh releases --json | jq -r '.Tables[0].Rows[].name'); do + echo "Checking $release..." + # Check for updates on bosh.io +done +``` + +### 2. Version Pinning + +Pin versions in production: + +```yaml +# production.yml +params: + releases: + concourse: + version: 7.8.3 # Explicit version + postgres: + version: "43" # Tested version + + stemcell_version: "1.123" # Specific stemcell +``` + +### 3. Offline Environments + +Prepare for air-gapped deployments: + +```bash +# Download all artifacts +mkdir offline-artifacts + +# Stemcells +wget https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent?v=1.123 \ + -O offline-artifacts/stemcell.tgz + +# Releases +genesis download-kit-releases my-kit \ + --output-dir offline-artifacts/ + +# Upload from local files +cd offline-artifacts +bosh upload-stemcell stemcell.tgz +for release in *.tgz; do + bosh upload-release "$release" +done +``` + +### 4. Cleanup Strategy + +Maintain director health: + +```bash +# Automated cleanup script +#!/bin/bash + +# Keep last 3 versions of each stemcell +bosh clean-up --all + +# Manual cleanup for specific items +bosh stemcells --json | jq -r '.Tables[0].Rows[] | + select(.version | tonumber < 120) | + "\(.os)/\(.version)"' | + xargs -I{} bosh delete-stemcell {} --force +``` + +### 5. Security Scanning + +Verify stemcell security: + +```bash +# Extract and scan stemcell +mkdir stemcell-check +cd stemcell-check +tar -xzf ../stemcell.tgz +tar -xzf image + +# Run security scans +sudo lynis audit system +sudo chkrootkit +``` + +## Troubleshooting + +### Upload Failures + +```bash +# Error: Timed out uploading release +# Solution 1: Use compiled releases +bosh upload-release compiled-release.tgz + +# Solution 2: Increase timeout +export BOSH_CLIENT_TIMEOUT=300 +bosh upload-release large-release.tgz + +# Solution 3: Upload from closer location +# Download first, then upload from jump box +``` + +### Version Conflicts + +```bash +# Error: Release 'X' version 'Y' already exists +# Check current version +bosh releases | grep X + +# Force upload if needed (dev only) +bosh upload-release --force + +# Or delete and re-upload +bosh delete-release X/Y +bosh upload-release X-Y.tgz +``` + +### Compilation Issues + +```bash +# Error: Failed to compile packages +# Solution: Check compilation VMs +bosh -d my-deployment task --debug + +# Common fixes: +# 1. Increase compilation VM size +# 2. Check internet access +# 3. Verify dependencies +``` + +## Integration with CI/CD + +### Automated Updates + +```yaml +# Concourse pipeline +resources: +- name: stemcell + type: bosh-io-stemcell + source: + name: bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +- name: concourse-release + type: bosh-io-release + source: + repository: concourse/concourse-bosh-release + +jobs: +- name: update-genesis-deployment + plan: + - get: stemcell + trigger: true + - get: concourse-release + trigger: true + - task: update-manifest + config: + platform: linux + image_resource: + type: docker-image + source: + repository: genesiscommunity/genesis + run: + path: bash + args: + - -c + - | + genesis deploy my-env --yes +``` + +### Release Notes Tracking + +Track what changes between versions: + +```bash +# Check release notes +curl -s https://api.github.com/repos/concourse/concourse-bosh-release/releases/latest | \ + jq -r '.body' + +# Document in deployment +cat >> deployment-notes.md < ubuntu-jammy/1.124 + - Security patches: CVE-2023-XXXXX +- Concourse: 7.8.2 -> 7.8.3 + - Bug fixes: [link to release notes] +EOF +``` + +Managing stemcells and releases effectively ensures your Genesis deployments stay secure, performant, and up-to-date. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/60-bosh/working-with-bosh.md b/lib/Genesis/Help/Topics/60-bosh/working-with-bosh.md new file mode 100644 index 00000000..47e467cf --- /dev/null +++ b/lib/Genesis/Help/Topics/60-bosh/working-with-bosh.md @@ -0,0 +1,379 @@ +# Working with BOSH + +This guide covers common BOSH operations in the context of Genesis deployments and when to use BOSH commands directly. + +## Accessing BOSH Through Genesis + +### Setting BOSH Environment + +Genesis provides several ways to access the underlying BOSH director: + +```bash +# Method 1: Get BOSH connection details +genesis bosh my-env + +# Method 2: Open a shell with BOSH environment set +genesis do my-env -- bash +# $BOSH_ENVIRONMENT, $BOSH_CLIENT, etc. are now set + +# Method 3: Run a specific BOSH command +genesis do my-env -- bosh vms +``` + +### Environment Variables + +When Genesis sets up BOSH access, it configures: + +- `BOSH_ENVIRONMENT` - Director URL +- `BOSH_CLIENT` - Authentication client +- `BOSH_CLIENT_SECRET` - Authentication secret +- `BOSH_CA_CERT` - CA certificate for TLS +- `BOSH_DEPLOYMENT` - Current deployment name + +## Common BOSH Operations + +### Viewing Deployment Information + +```bash +# List all deployments +bosh deployments + +# View VMs in a deployment +bosh -d my-deployment vms + +# Detailed VM information with vitals +bosh -d my-deployment vms --vitals + +# View current manifest +bosh -d my-deployment manifest + +# View deployment properties +bosh -d my-deployment properties +``` + +### Managing VMs + +```bash +# SSH into a VM +bosh -d my-deployment ssh web/0 + +# Restart a VM +bosh -d my-deployment restart web/0 + +# Recreate a VM (fresh instance) +bosh -d my-deployment recreate web/0 + +# Stop a VM +bosh -d my-deployment stop web/0 + +# Start a VM +bosh -d my-deployment start web/0 + +# Delete a VM (be careful!) +bosh -d my-deployment delete-vm +``` + +### Logs and Debugging + +```bash +# Download logs from all VMs +bosh -d my-deployment logs + +# Download logs from specific VM +bosh -d my-deployment logs web/0 + +# Download logs for specific job +bosh -d my-deployment logs web/0 --job=nginx + +# Follow logs (tail) +bosh -d my-deployment ssh web/0 -c "sudo tail -f /var/vcap/sys/log/**/*.log" + +# View BOSH agent logs +bosh -d my-deployment ssh web/0 -c "sudo tail -f /var/vcap/bosh/log/current" +``` + +### Running Errands + +```bash +# List available errands +bosh -d my-deployment errands + +# Run an errand +bosh -d my-deployment run-errand smoke-tests + +# Run errand with specific instance +bosh -d my-deployment run-errand backup --instance=database/0 + +# Download errand logs +bosh -d my-deployment run-errand diagnostics --download-logs +``` + +### Task Management + +```bash +# List recent tasks +bosh tasks + +# List all tasks +bosh tasks --all + +# View task details +bosh task 123 + +# View task output +bosh task 123 --debug + +# Cancel a running task +bosh cancel-task 123 +``` + +## Advanced Operations + +### Cloud Check + +Fix deployment issues: + +```bash +# Run cloud check (interactive) +bosh -d my-deployment cloud-check + +# Auto-resolve problems +bosh -d my-deployment cloud-check --auto + +# Report only +bosh -d my-deployment cloud-check --report +``` + +### Managing Releases + +```bash +# List uploaded releases +bosh releases + +# Upload a release +bosh upload-release https://bosh.io/d/github.com/cloudfoundry/cf-release + +# Delete unused releases +bosh delete-release my-release/1.2.3 + +# Export a release +bosh -d my-deployment export-release my-release/1.2.3 ubuntu-jammy/1.123 +``` + +### Managing Stemcells + +```bash +# List uploaded stemcells +bosh stemcells + +# Upload a stemcell +bosh upload-stemcell https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-jammy-go_agent + +# Delete unused stemcells +bosh delete-stemcell ubuntu-jammy/1.123 + +# Clean up old stemcells +bosh clean-up --all +``` + +### Persistent Disks + +```bash +# List persistent disks +bosh -d my-deployment disks + +# Orphaned disks +bosh disks --orphaned + +# Attach orphaned disk +bosh -d my-deployment attach-disk web/0 disk-123456 +``` + +## BOSH and Genesis Integration + +### Pre-deployment Checks + +Before `genesis deploy`, you might need to: + +```bash +# Verify cloud config exists +bosh cloud-config + +# Check for required VM types +bosh cloud-config | grep vm_type + +# Verify networks +bosh cloud-config | grep -A5 networks + +# Check available stemcells +bosh stemcells +``` + +### During Deployment + +Monitor deployment progress: + +```bash +# Watch deployment task +genesis deploy my-env +# In another terminal: +bosh task --debug + +# Monitor VM creation +watch -n 2 'bosh -d my-deployment vms' +``` + +### Post-deployment Verification + +```bash +# Check instance health +bosh -d my-deployment instances --ps + +# Verify persistent disks +bosh -d my-deployment disks + +# Run smoke tests +bosh -d my-deployment run-errand smoke-tests +``` + +## Troubleshooting with BOSH + +### Common Issues + +#### VM Not Starting + +```bash +# Check VM vitals +bosh -d my-deployment vms --vitals + +# SSH and check logs +bosh -d my-deployment ssh failing-vm +sudo tail -f /var/vcap/sys/log/**/*.log +sudo tail -f /var/vcap/monit/monit.log +``` + +#### Network Issues + +```bash +# Verify VM can reach director +bosh -d my-deployment ssh web/0 +curl -k https://$BOSH_ENVIRONMENT:25555/info + +# Check network configuration +ip addr +ip route +cat /etc/resolv.conf +``` + +#### Disk Issues + +```bash +# Check disk usage +bosh -d my-deployment ssh database/0 +df -h +du -sh /var/vcap/store/* +``` + +### Recovery Operations + +#### Recreate VM with Persistent Disk + +```bash +# Stop VM +bosh -d my-deployment stop database/0 + +# Recreate (keeps persistent disk) +bosh -d my-deployment recreate database/0 +``` + +#### Manual Resurrection + +```bash +# Disable resurrection +bosh -d my-deployment update-resurrection off + +# Fix issues... + +# Re-enable resurrection +bosh -d my-deployment update-resurrection on +``` + +## Best Practices + +### 1. Use Genesis When Possible + +- Deploy with `genesis deploy` not `bosh deploy` +- Let Genesis manage manifest generation +- Use Genesis for secrets rotation + +### 2. Know When to Use BOSH + +- Debugging VM issues +- Emergency recovery +- Advanced operations (recreate, cloud-check) +- Log collection + +### 3. Monitor Task Output + +```bash +# Always check task output for errors +bosh task --debug | grep -i error +``` + +### 4. Clean Up Regularly + +```bash +# Remove unused releases and stemcells +bosh clean-up --all + +# Remove orphaned disks +bosh disks --orphaned +bosh delete-disk +``` + +### 5. Document Custom Operations + +When you need to use BOSH directly, document: +- What you did +- Why Genesis couldn't handle it +- Any manual steps needed + +## Integration Tips + +### Shell Aliases + +Add to your shell configuration: + +```bash +# Quick BOSH access +alias gb='genesis bosh' + +# Common operations +bosh-vms() { + genesis do "$1" -- bosh vms --vitals +} + +bosh-ssh() { + genesis do "$1" -- bosh ssh "$2" +} +``` + +### Scripting + +Automate common tasks: + +```bash +#!/bin/bash +# check-deployment.sh +ENV=$1 +genesis do "$ENV" -- bash -c ' + echo "=== VMs ===" + bosh vms --vitals + echo "=== Disks ===" + bosh disks + echo "=== Recent Tasks ===" + bosh tasks --recent +' +``` + +Working effectively with BOSH through Genesis requires understanding both tools and knowing when to use each for maximum efficiency. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/.keep b/lib/Genesis/Help/Topics/70-troubleshooting/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/common-issues.md b/lib/Genesis/Help/Topics/70-troubleshooting/common-issues.md new file mode 100644 index 00000000..6c6e4416 --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/common-issues.md @@ -0,0 +1,507 @@ +# Common Issues + +This guide covers frequently encountered Genesis issues and their solutions. + +## Installation Issues + +### Genesis Command Not Found + +**Symptom:** +```bash +$ genesis +-bash: genesis: command not found +``` + +**Solutions:** + +1. **Add to PATH:** + ```bash + echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc + source ~/.bashrc + ``` + +2. **Verify installation:** + ```bash + ls -la ~/bin/genesis + # Should show executable file + ``` + +3. **Reinstall Genesis:** + ```bash + curl -sL https://get.genesisproject.io/install | bash + ``` + +### Permission Denied + +**Symptom:** +```bash +$ genesis new my-env +Permission denied: cannot write to /path/to/repo +``` + +**Solution:** +```bash +# Fix permissions +sudo chown -R $(whoami):$(whoami) /path/to/repo + +# Or use proper directory +cd ~/deployments/my-kit +genesis new my-env +``` + +## Deployment Issues + +### Kit Not Found + +**Symptom:** +``` +Error: Kit 'my-kit/1.2.3' not found +``` + +**Solutions:** + +1. **Check available versions:** + ```bash + genesis list-kits my-kit + ``` + +2. **Update kit cache:** + ```bash + genesis fetch-kit my-kit + ``` + +3. **Use local kit:** + ```bash + genesis new my-env --kit ./path/to/kit + ``` + +### Environment File Not Found + +**Symptom:** +``` +Error: Could not find environment 'my-env' +``` + +**Solutions:** + +1. **Check current directory:** + ```bash + pwd # Should be in deployment repo root + ls *.yml # Should see environment files + ``` + +2. **Verify environment exists:** + ```bash + genesis list + find . -name "my-env.yml" + ``` + +3. **Create environment:** + ```bash + genesis new my-env + ``` + +### Merge Conflicts + +**Symptom:** +``` +Error: Merge conflict in parameters +``` + +**Solutions:** + +1. **Debug merge order:** + ```bash + genesis manifest my-env --trace + ``` + +2. **Check for duplicate keys:** + ```bash + # Look for duplicate parameters + grep -n "param_name:" *.yml + ``` + +3. **Use explicit null values:** + ```yaml + # In environment file + params: + unwanted_param: null # Remove inherited value + ``` + +## Vault/Secret Issues + +### Cannot Connect to Vault + +**Symptom:** +``` +Error: Could not connect to Vault at https://127.0.0.1:8200 +``` + +**Solutions:** + +1. **Check Vault status:** + ```bash + safe target + safe status + ``` + +2. **Set Vault target:** + ```bash + safe target my-vault https://vault.example.com:8200 + ``` + +3. **Skip TLS verification (dev only):** + ```bash + safe target my-vault https://vault.example.com:8200 -k + ``` + +### Missing Secrets + +**Symptom:** +``` +Error: Could not find secret at path/to/secret:key +``` + +**Solutions:** + +1. **Check secret path:** + ```bash + safe tree path/to + safe get path/to/secret + ``` + +2. **Generate missing secrets:** + ```bash + genesis add-secrets my-env + ``` + +3. **Check environment Vault path:** + ```bash + genesis secrets-path my-env + ``` + +## BOSH Connection Issues + +### Cannot Target BOSH Director + +**Symptom:** +``` +Error: Could not authenticate with BOSH director +``` + +**Solutions:** + +1. **Check BOSH environment:** + ```bash + genesis bosh my-env + bosh env + ``` + +2. **Update BOSH credentials:** + ```bash + # Re-fetch from Vault + genesis bosh my-env --reset + ``` + +3. **Verify network connectivity:** + ```bash + curl -k https://:25555/info + ``` + +### Deployment Not Found + +**Symptom:** +``` +Error: Deployment 'my-env-kit' not found +``` + +**Solutions:** + +1. **Check deployment name:** + ```bash + bosh deployments + genesis info my-env | grep "BOSH Deployment" + ``` + +2. **Deploy first:** + ```bash + genesis deploy my-env + ``` + +## State Corruption + +### Invalid State File + +**Symptom:** +``` +Error: State file corrupted or invalid +``` + +**Solutions:** + +1. **Backup and recreate:** + ```bash + # Backup current state + cp .genesis/state.yml .genesis/state.yml.backup + + # Remove corrupted state + rm .genesis/state.yml + + # Reinitialize + genesis init --kit my-kit . + ``` + +2. **Recover from BOSH:** + ```bash + # Get deployment manifest from BOSH + bosh -d my-deployment manifest > recovered.yml + ``` + +### Cache Corruption + +**Symptom:** +``` +Error: Invalid cached kit or corrupted download +``` + +**Solutions:** + +1. **Clear cache:** + ```bash + rm -rf ~/.genesis/cache/* + genesis fetch-kit my-kit + ``` + +2. **Force redownload:** + ```bash + genesis compile-kit --force + ``` + +## Network Issues + +### Proxy Configuration + +**Symptom:** +``` +Error: Could not download kit - connection timeout +``` + +**Solutions:** + +1. **Set proxy variables:** + ```bash + export http_proxy=http://proxy.example.com:8080 + export https_proxy=http://proxy.example.com:8080 + export no_proxy=localhost,127.0.0.1,.example.com + ``` + +2. **Git proxy configuration:** + ```bash + git config --global http.proxy http://proxy.example.com:8080 + ``` + +### SSL Certificate Issues + +**Symptom:** +``` +Error: x509: certificate signed by unknown authority +``` + +**Solutions:** + +1. **Add CA certificate:** + ```bash + export SSL_CERT_FILE=/path/to/ca-bundle.crt + export CURL_CA_BUNDLE=/path/to/ca-bundle.crt + ``` + +2. **Skip verification (dev only):** + ```bash + export GENESIS_SKIP_VAULT_VERIFY=1 + export BOSH_SKIP_SSL_VALIDATION=true + ``` + +## Performance Issues + +### Slow Manifest Generation + +**Symptom:** +Manifest generation takes several minutes + +**Solutions:** + +1. **Enable caching:** + ```bash + export GENESIS_MANIFEST_CACHE=1 + ``` + +2. **Reduce spruce operations:** + - Minimize grab operations + - Use static references where possible + - Avoid complex array operations + +3. **Profile generation:** + ```bash + genesis manifest my-env --trace --time + ``` + +### Memory Issues + +**Symptom:** +``` +Error: Cannot allocate memory +``` + +**Solutions:** + +1. **Increase limits:** + ```bash + ulimit -m unlimited + ulimit -v unlimited + ``` + +2. **Use streaming for large files:** + ```bash + # Split large arrays + # Use references instead of inline data + ``` + +## Development Issues + +### Hook Failures + +**Symptom:** +``` +Error: Hook 'new' exited with status 1 +``` + +**Solutions:** + +1. **Debug hook:** + ```bash + cd dev/ + GENESIS_TRACE=1 ./hooks/new + ``` + +2. **Check hook permissions:** + ```bash + chmod +x hooks/* + ``` + +3. **Validate bash syntax:** + ```bash + bash -n hooks/new + ``` + +### Kit Compilation Errors + +**Symptom:** +``` +Error: Failed to compile kit +``` + +**Solutions:** + +1. **Check kit.yml syntax:** + ```bash + yamllint kit.yml + spruce merge kit.yml > /dev/null + ``` + +2. **Validate directory structure:** + ```bash + # Required directories + ls -d hooks/ manifests/ + ``` + +3. **Test compilation:** + ```bash + genesis compile-kit --dev + ``` + +## Recovery Procedures + +### Emergency Deployment Recovery + +```bash +#!/bin/bash +# emergency-recovery.sh + +ENV=$1 +KIT=$2 + +echo "Attempting recovery of $ENV" + +# 1. Backup current state +mkdir -p backups/$(date +%Y%m%d) +cp -r . backups/$(date +%Y%m%d)/ + +# 2. Get manifest from BOSH +bosh -d "$ENV-$KIT" manifest > recovered-manifest.yml + +# 3. Extract parameters +spruce json recovered-manifest.yml | \ + jq '.params' > recovered-params.json + +# 4. Recreate environment file +cat > "$ENV.yml" <&1 | grep -E "(Loading|Merging)" + +# Example output: +# Loading us.yml +# Loading us-east.yml +# Loading us-east-prod.yml +# Merging 3 environment files... +``` + +**Common problems:** + +1. **Missing parent files:** + ```bash + # Check file existence + genesis manifest my-env 2>&1 | grep "Could not find" + + # Fix: Create missing files + touch us.yml us-east.yml + ``` + +2. **Circular dependencies:** + ```bash + # Error: Circular dependency detected + # Check for files that reference each other + grep -l "genesis.env:" *.yml + ``` + +### Feature Validation + +**Debug feature issues:** + +```bash +# List available features +genesis info my-env | grep -A20 "Available Features" + +# Check enabled features +genesis manifest my-env | grep -A10 "kit.features" + +# Validate feature combination +genesis check my-env --trace +``` + +**Common feature problems:** + +```yaml +# Incompatible features +kit: + features: + - azure + - aws # Error: Can't use multiple IaaS + +# Missing dependencies +kit: + features: + - ha # Might require minimum instances +``` + +### Secret Debugging + +**Trace secret retrieval:** + +```bash +# List required secrets +genesis secrets-plan my-env + +# Check missing secrets +genesis check-secrets my-env + +# Debug secret paths +GENESIS_TRACE=1 genesis manifest my-env 2>&1 | grep -i vault +``` + +**Debug Vault connectivity:** + +```bash +# Test Vault access +safe target +safe tree $(genesis secrets-path my-env) + +# Manual secret check +safe get $(genesis secrets-path my-env)/admin:password +``` + +## Manifest Generation Debugging + +### Trace Manifest Building + +**Full trace of manifest generation:** + +```bash +# Save trace output +genesis manifest my-env --trace > trace.log 2>&1 + +# Analyze phases +grep -n "Phase:" trace.log +``` + +**Step-by-step debugging:** + +```bash +# 1. Base manifest only +genesis manifest my-env --partial base + +# 2. With features +genesis manifest my-env --partial features + +# 3. With secrets (no Vault lookup) +genesis manifest my-env --no-resolve + +# 4. Final manifest +genesis manifest my-env +``` + +### Spruce Merge Issues + +**Debug merge operations:** + +```bash +# Extract spruce operations +genesis manifest my-env --trace 2>&1 | \ + grep -E "(spruce merge|Error.*spruce)" + +# Test specific merge +spruce merge file1.yml file2.yml + +# Debug grab operations +spruce merge --trace manifest.yml 2>&1 | grep grab +``` + +**Common spruce errors:** + +1. **Undefined variables:** + ```yaml + # Error: (( grab params.missing )) - params.missing not found + # Fix: Define in environment or use default + value: (( grab params.missing || "default" )) + ``` + +2. **Type mismatches:** + ```yaml + # Error: Cannot merge string into array + # Check data types + spruce diff base.yml override.yml + ``` + +### Parameter Resolution + +**Debug parameter lookup:** + +```bash +# Show all parameters +genesis manifest my-env | spruce json | jq '.params' + +# Trace parameter source +for file in $(genesis manifest my-env --trace 2>&1 | grep Loading | awk '{print $2}'); do + echo "=== $file ===" + grep "param_name:" "$file" || true +done +``` + +## Deployment Debugging + +### Pre-Deployment Validation + +**Run comprehensive checks:** + +```bash +# Full validation +genesis check my-env + +# Individual checks +genesis check-secrets my-env +genesis check-cloud-config my-env +genesis check-stemcells my-env +``` + +**Manual BOSH validation:** + +```bash +# Get manifest +genesis manifest my-env > manifest.yml + +# Validate with BOSH +bosh -d my-deployment deploy manifest.yml --dry-run + +# Check interpolation +bosh int manifest.yml +``` + +### Deployment Execution + +**Monitor deployment progress:** + +```bash +# Deploy with verbose output +genesis deploy my-env --trace + +# In another terminal, watch BOSH task +bosh tasks --recent +bosh task --debug +``` + +**Debug deployment failures:** + +```bash +# Get failing task details +bosh task --debug | less + +# Common patterns to search +/error +/failed +/timeout +/not found +``` + +### Instance-Level Debugging + +**Access problematic instances:** + +```bash +# List instances with issues +bosh -d my-deployment instances --ps + +# SSH to instance +bosh -d my-deployment ssh web/0 + +# Check logs +sudo tail -f /var/vcap/sys/log/**/*.log + +# Check monit +sudo monit summary +``` + +## Post-Deployment Debugging + +### Hook Failures + +**Debug post-deploy hooks:** + +```bash +# Run hook manually +cd /path/to/kit +GENESIS_ENVIRONMENT=my-env \ +GENESIS_VAULT_PREFIX=$(genesis secrets-path my-env) \ +GENESIS_TRACE=1 \ +./hooks/post-deploy +``` + +### Smoke Test Failures + +**Debug smoke tests:** + +```bash +# Run errand manually +bosh -d my-deployment run-errand smoke-tests + +# Get errand logs +bosh -d my-deployment run-errand smoke-tests --download-logs +tar xzf smoke-tests-logs.tgz +``` + +## Advanced Debugging Techniques + +### Manifest Diffing + +**Compare manifests:** + +```bash +# Compare with last deployment +bosh -d my-deployment manifest > current.yml +genesis manifest my-env > new.yml +diff -u current.yml new.yml + +# Semantic diff +spruce diff current.yml new.yml +``` + +### State Analysis + +**Check Genesis state:** + +```bash +# View cached information +cat .genesis/manifests/my-env.yml +cat .genesis/configs/my-env.yml + +# Check deployment state +cat .genesis/deployments/my-env.yml +``` + +### Environment Variable Debugging + +**Check Genesis environment:** + +```bash +# Show all Genesis variables +env | grep GENESIS | sort + +# Run with specific debug flags +GENESIS_TRACE=1 \ +GENESIS_DEBUG=1 \ +GENESIS_VAULT_VERIFY=0 \ +genesis deploy my-env +``` + +## Recovery Procedures + +### Partial Deployment Recovery + +```bash +#!/bin/bash +# recover-deployment.sh + +DEPLOYMENT=$1 + +# 1. Get current state from BOSH +echo "Fetching current deployment state..." +bosh -d $DEPLOYMENT manifest > current-state.yml + +# 2. Compare with desired state +echo "Comparing states..." +genesis manifest ${DEPLOYMENT%-*} > desired-state.yml +spruce diff current-state.yml desired-state.yml > state-diff.txt + +# 3. Identify stuck instances +echo "Checking instances..." +bosh -d $DEPLOYMENT instances --ps | grep -v running > stuck-instances.txt + +# 4. Attempt recovery +if [[ -s stuck-instances.txt ]]; then + echo "Found stuck instances:" + cat stuck-instances.txt + + # Restart stuck instances + while read instance; do + inst=$(echo $instance | awk '{print $1}') + echo "Restarting $inst..." + bosh -d $DEPLOYMENT restart $inst + done < stuck-instances.txt +fi +``` + +### Manual State Correction + +```bash +# Force convergence +bosh -d my-deployment cloud-check --auto + +# Recreate specific instances +bosh -d my-deployment recreate web/0 + +# Full recreation (last resort) +bosh -d my-deployment recreate +``` + +## Debugging Checklist + +### Before Deployment + +- [ ] Environment files exist and are valid YAML +- [ ] All parent files are present +- [ ] Features are compatible +- [ ] Required parameters are set +- [ ] Vault is accessible +- [ ] Secrets exist or can be generated +- [ ] Cloud config has required resources +- [ ] Stemcells are uploaded + +### During Deployment + +- [ ] Monitor BOSH task output +- [ ] Check for compilation failures +- [ ] Verify network connectivity +- [ ] Watch for timeout errors +- [ ] Check instance health + +### After Deployment Failure + +- [ ] Collect BOSH task logs +- [ ] Save current manifest +- [ ] Check instance states +- [ ] Review error messages +- [ ] Verify cloud resources +- [ ] Check persistent disks + +## Common Patterns + +### Timeout Issues + +```bash +# Increase timeouts +export BOSH_CLIENT_TIMEOUT=300 + +# Deploy with reduced parallelism +genesis deploy my-env -- --max-in-flight=1 +``` + +### Resource Constraints + +```bash +# Check cloud usage +bosh cloud-config | grep -A5 compilation + +# Reduce compilation workers +bosh update-cloud-config <( + bosh cloud-config | + sed 's/workers: .*/workers: 2/' +) +``` + +### Network Problems + +```bash +# Test from director +bosh -d my-deployment ssh web/0 -c "ping -c 3 8.8.8.8" + +# Check DNS resolution +bosh -d my-deployment ssh web/0 -c "nslookup google.com" +``` + +Effective debugging combines systematic analysis with understanding of the deployment pipeline. Always collect evidence before attempting fixes. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/error-messages.md b/lib/Genesis/Help/Topics/70-troubleshooting/error-messages.md new file mode 100644 index 00000000..85df96c4 --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/error-messages.md @@ -0,0 +1,516 @@ +# Error Messages + +This reference guide explains common Genesis error messages and how to resolve them. + +## Environment Errors + +### "Could not find environment 'X'" + +**Full Error:** +``` +Error: Could not find environment 'my-env' in /path/to/deployments +``` + +**Cause:** Genesis cannot find the environment YAML file. + +**Resolution:** +```bash +# Check current directory +pwd # Must be in deployment repository root + +# List available environments +genesis list + +# Create if missing +genesis new my-env +``` + +### "No deployment type specified" + +**Full Error:** +``` +Error: No deployment type specified in 'my-env.yml' +``` + +**Cause:** Environment file missing kit information. + +**Resolution:** +```yaml +# Add to environment file +kit: + name: concourse # or your kit name + version: 4.0.0 # optional +``` + +### "Circular dependency detected" + +**Full Error:** +``` +Error: Circular dependency detected in environment hierarchy +``` + +**Cause:** Environment files reference each other in a loop. + +**Resolution:** +```bash +# Check environment references +grep "genesis.env:" *.yml + +# Fix circular reference +# Remove or correct the circular dependency +``` + +## Kit Errors + +### "Kit 'X' not found" + +**Full Error:** +``` +Error: Kit 'my-kit/1.0.0' not found in any known location +``` + +**Cause:** Kit not available locally or in upstream. + +**Resolution:** +```bash +# List available kits +genesis list-kits my-kit + +# Fetch from upstream +genesis fetch-kit my-kit + +# Use local kit +genesis init --kit ./path/to/kit +``` + +### "Kit version mismatch" + +**Full Error:** +``` +Error: Environment requires kit version 2.0.0 but 1.0.0 is installed +``` + +**Cause:** Environment specifies different kit version than available. + +**Resolution:** +```bash +# Update kit +genesis fetch-kit my-kit@2.0.0 + +# Or update environment +# Remove version requirement from kit: section +``` + +### "Invalid kit structure" + +**Full Error:** +``` +Error: Invalid kit structure: missing required directory 'manifests' +``` + +**Cause:** Kit missing required files/directories. + +**Resolution:** +```bash +# Check kit structure +ls -la dev/ +# Must have: kit.yml, manifests/, hooks/ + +# Create missing directories +mkdir -p dev/manifests dev/hooks +``` + +## Manifest Errors + +### "Merge conflict detected" + +**Full Error:** +``` +Error: Merge conflict detected at $.instance_groups[0].name +``` + +**Cause:** YAML merge conflict between files. + +**Resolution:** +```bash +# Debug merge +genesis manifest my-env --trace + +# Test individual merges +spruce merge base.yml overlay.yml + +# Use explicit operators +# (( replace )) to replace +# (( append )) to append +``` + +### "Could not resolve (( grab ... ))" + +**Full Error:** +``` +Error: Could not resolve (( grab params.missing_param )) +``` + +**Cause:** Referenced parameter not defined. + +**Resolution:** +```yaml +# Define in environment +params: + missing_param: "value" + +# Or provide default +value: (( grab params.missing_param || "default" )) +``` + +### "Type mismatch in merge" + +**Full Error:** +``` +Error: Cannot merge string with array at $.networks[0] +``` + +**Cause:** Trying to merge incompatible types. + +**Resolution:** +```yaml +# Ensure consistent types +# Bad: +base: networks: "default" +overlay: networks: ["default", "other"] + +# Good: +base: networks: ["default"] +overlay: networks: ["default", "other"] +``` + +## Vault/Secret Errors + +### "Could not connect to Vault" + +**Full Error:** +``` +Error: Could not connect to Vault at https://127.0.0.1:8200: connection refused +``` + +**Cause:** Vault not accessible. + +**Resolution:** +```bash +# Check Vault target +safe target + +# Set correct target +safe target my-vault https://vault.example.com:8200 + +# Verify connectivity +safe status +``` + +### "Secret not found" + +**Full Error:** +``` +Error: Could not retrieve secret 'secret/my/env/password:key' from Vault +``` + +**Cause:** Secret doesn't exist in Vault. + +**Resolution:** +```bash +# Check if secret exists +safe exists secret/my/env/password + +# Generate missing secrets +genesis add-secrets my-env + +# Or create manually +safe set secret/my/env/password key=value +``` + +### "Permission denied" + +**Full Error:** +``` +Error: 403 permission denied accessing 'secret/my/env' +``` + +**Cause:** Vault token lacks required permissions. + +**Resolution:** +```bash +# Check token permissions +safe vault token lookup + +# Re-authenticate +safe auth + +# Check policies +safe vault policy read my-policy +``` + +## BOSH Errors + +### "Could not authenticate with BOSH" + +**Full Error:** +``` +Error: Could not authenticate with BOSH director: 401 Unauthorized +``` + +**Cause:** Invalid or expired BOSH credentials. + +**Resolution:** +```bash +# Refresh BOSH credentials +genesis bosh my-env --reset + +# Verify connection +bosh env +``` + +### "Deployment not found" + +**Full Error:** +``` +Error: Deployment 'my-env-concourse' not found on BOSH director +``` + +**Cause:** Deployment doesn't exist yet or wrong name. + +**Resolution:** +```bash +# Check existing deployments +bosh deployments + +# Deploy first +genesis deploy my-env + +# Verify deployment name +genesis info my-env | grep "BOSH Deployment" +``` + +### "Cloud config missing required elements" + +**Full Error:** +``` +Error: Cloud config missing required vm_type 'small' +``` + +**Cause:** BOSH cloud config incomplete. + +**Resolution:** +```bash +# Check cloud config +bosh cloud-config | grep vm_type + +# Update cloud config +bosh update-cloud-config cloud.yml +``` + +## Hook Errors + +### "Hook 'X' failed with exit code Y" + +**Full Error:** +``` +Error: Hook 'check' failed with exit code 1 +``` + +**Cause:** Kit hook script failed. + +**Resolution:** +```bash +# Debug hook +cd /path/to/kit +GENESIS_TRACE=1 ./hooks/check + +# Check hook permissions +chmod +x hooks/check + +# Review hook output for specific errors +``` + +### "Hook not found or not executable" + +**Full Error:** +``` +Error: Hook 'new' not found or not executable +``` + +**Cause:** Missing hook or wrong permissions. + +**Resolution:** +```bash +# Check hook exists +ls -la hooks/new + +# Fix permissions +chmod +x hooks/new + +# Verify shebang +head -1 hooks/new # Should be #!/bin/bash +``` + +## Validation Errors + +### "Invalid YAML syntax" + +**Full Error:** +``` +Error: Invalid YAML in 'my-env.yml': found character that cannot start any token +``` + +**Cause:** YAML syntax error. + +**Resolution:** +```bash +# Validate YAML +yamllint my-env.yml + +# Common issues: +# - Tabs instead of spaces +# - Missing quotes around values with ':' +# - Incorrect indentation +``` + +### "Missing required parameter" + +**Full Error:** +``` +Error: Missing required parameter 'base_domain' +``` + +**Cause:** Required parameter not provided. + +**Resolution:** +```yaml +# Add to environment file +params: + base_domain: example.com +``` + +## State Errors + +### "State file corrupted" + +**Full Error:** +``` +Error: State file corrupted or unreadable +``` + +**Cause:** Genesis state file damaged. + +**Resolution:** +```bash +# Backup corrupted state +mv .genesis/state.yml .genesis/state.yml.backup + +# Reinitialize +genesis init --kit my-kit . +``` + +### "Cache corrupted" + +**Full Error:** +``` +Error: Cached manifest corrupted for environment 'my-env' +``` + +**Cause:** Cached files corrupted. + +**Resolution:** +```bash +# Clear cache +rm -rf .genesis/manifests/my-env.yml +rm -rf .genesis/cache/* + +# Regenerate +genesis manifest my-env +``` + +## Network Errors + +### "Connection timeout" + +**Full Error:** +``` +Error: Connection timeout downloading kit from upstream +``` + +**Cause:** Network connectivity issues. + +**Resolution:** +```bash +# Check proxy settings +export http_proxy=http://proxy:8080 +export https_proxy=http://proxy:8080 + +# Increase timeout +export GENESIS_DOWNLOAD_TIMEOUT=300 +``` + +### "Certificate verification failed" + +**Full Error:** +``` +Error: x509: certificate signed by unknown authority +``` + +**Cause:** TLS certificate not trusted. + +**Resolution:** +```bash +# Add CA certificate +export SSL_CERT_FILE=/path/to/ca-bundle.crt + +# Or skip verification (dev only) +export GENESIS_SKIP_VERIFY=1 +``` + +## Recovery Commands + +### General Debugging + +```bash +# Enable maximum debugging +export GENESIS_DEBUG=1 +export GENESIS_TRACE=1 +genesis deploy my-env + +# Check Genesis version +genesis version + +# Validate environment +genesis check my-env +``` + +### Quick Fixes + +```bash +# Clear all caches +rm -rf ~/.genesis/cache/* +rm -rf .genesis/manifests/* + +# Reset BOSH connection +genesis bosh my-env --reset + +# Regenerate secrets +genesis rotate-secrets my-env + +# Force manifest regeneration +rm .genesis/manifests/my-env.yml +genesis manifest my-env +``` + +### Getting Help + +When reporting errors: + +1. **Exact error message** +2. **Genesis version**: `genesis version` +3. **Command that failed**: `genesis deploy my-env` +4. **Trace output**: Run with `--trace` +5. **Environment details**: OS, network setup + +Understanding error messages helps quickly identify and resolve issues. Most errors provide clear guidance on the problem and solution. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/index.md b/lib/Genesis/Help/Topics/70-troubleshooting/index.md new file mode 100644 index 00000000..38f403db --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/index.md @@ -0,0 +1,57 @@ +# Troubleshooting + +This section provides guidance for diagnosing and resolving common issues with Genesis deployments. + +## Topics in this Section + +### [Common Issues](common-issues.md) +Frequently encountered problems and their solutions. + +### [Debugging Deployments](debugging-deployments.md) +Techniques for troubleshooting deployment failures. + +### [Trace Logging](trace-logging.md) +Using Genesis trace logs for detailed debugging. + +### [Manifest Debugging](manifest-debugging.md) +Troubleshooting manifest generation and merge issues. + +### [Secret Problems](secret-problems.md) +Resolving issues with Vault and secret management. + +### [Kit Development Issues](kit-development-issues.md) +Common problems when developing Genesis kits. + +### [Error Messages](error-messages.md) +Understanding and resolving Genesis error messages. + +## Quick Diagnostics + +### Basic Health Check + +```bash +# Check Genesis version +genesis version + +# Verify environment +genesis list + +# Check deployment status +genesis info my-env + +# Validate environment +genesis check my-env +``` + +### Getting Help + +- Check error messages carefully - they often contain the solution +- Use `--trace` flag for detailed debugging output +- Review logs in `~/.genesis/logs/` +- Search GitHub issues: https://github.com/genesis-community/genesis/issues + +## Emergency Procedures + +- [Deployment Recovery](debugging-deployments.md#recovery-procedures) +- [Secret Recovery](secret-problems.md#recovery) +- [State Corruption](common-issues.md#state-corruption) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/kit-development-issues.md b/lib/Genesis/Help/Topics/70-troubleshooting/kit-development-issues.md new file mode 100644 index 00000000..a9eaa95f --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/kit-development-issues.md @@ -0,0 +1,527 @@ +# Kit Development Issues + +This guide helps troubleshoot common problems encountered when developing Genesis kits. + +## Development Environment Setup + +### Kit Development Structure + +```bash +my-kit/ +├── kit.yml # Kit metadata +├── manifests/ # BOSH manifests +│ ├── base.yml # Base manifest +│ └── features/ # Feature-specific manifests +├── hooks/ # Lifecycle hooks +│ ├── blueprint # Required: manifest selection +│ ├── new # Environment creation +│ ├── check # Pre-deployment validation +│ └── info # Post-deployment information +└── spec/ # Test specifications +``` + +### Common Setup Issues + +**Missing kit.yml:** +```bash +Error: Could not find kit.yml in current directory +``` + +**Solution:** +```bash +# Create minimal kit.yml +cat > kit.yml < +EOF +``` + +**Invalid directory structure:** +```bash +Error: No manifests directory found +``` + +**Solution:** +```bash +# Create required directories +mkdir -p manifests/features hooks +touch manifests/base.yml +chmod +x hooks/* +``` + +## Hook Development Issues + +### Hook Not Executing + +**Symptoms:** +``` +Hook 'new' not found or not executable +``` + +**Diagnostics:** +```bash +# Check file existence and permissions +ls -la hooks/ +file hooks/new +bash -n hooks/new # Syntax check +``` + +**Solutions:** +```bash +# Fix permissions +chmod +x hooks/* + +# Add shebang +echo '#!/bin/bash' | cat - hooks/new > temp && mv temp hooks/new + +# Test directly +cd /path/to/kit +GENESIS_ENVIRONMENT=test ./hooks/new +``` + +### Hook Environment Variables + +**Missing variables:** +```bash +# Debug hook environment +cat > hooks/debug <<'EOF' +#!/bin/bash +echo "=== Genesis Environment Variables ===" +env | grep GENESIS | sort +echo "=== Other Relevant Variables ===" +echo "PATH: $PATH" +echo "PWD: $PWD" +EOF +chmod +x hooks/debug +``` + +**Common required variables:** +```bash +#!/bin/bash +# In hook scripts + +# Always available +echo "Kit: $GENESIS_KIT_NAME v$GENESIS_KIT_VERSION" +echo "Environment: $GENESIS_ENVIRONMENT" +echo "Root: $GENESIS_ROOT" + +# Hook-specific +echo "Vault prefix: ${GENESIS_SECRETS_PATH:-$GENESIS_VAULT_PREFIX}" +echo "Features: $GENESIS_REQUESTED_FEATURES" +``` + +### Blueprint Hook Issues + +**No manifests returned:** +```bash +Error: Blueprint hook returned no manifest files +``` + +**Debug blueprint:** +```bash +#!/bin/bash +# hooks/blueprint +set -eu + +# Debug mode +if [[ "${GENESIS_TRACE:-}" == "1" ]]; then + set -x +fi + +# Always include base +echo "manifests/base.yml" + +# Add features +for feature in $GENESIS_REQUESTED_FEATURES; do + case "$feature" in + ha|ssl|monitoring) + if [[ -f "manifests/features/$feature.yml" ]]; then + echo "manifests/features/$feature.yml" + else + echo >&2 "Warning: Feature $feature requested but manifests/features/$feature.yml not found" + fi + ;; + *) + echo >&2 "Error: Unknown feature: $feature" + exit 1 + ;; + esac +done +``` + +### Check Hook Validation + +**Hook failing silently:** +```bash +# Add debugging to check hook +#!/bin/bash +# hooks/check +set -eu + +# Enable tracing +[[ "${GENESIS_TRACE:-}" == "1" ]] && set -x + +# Verbose error reporting +error() { + echo >&2 "CHECK FAILED: $*" + exit 1 +} + +# Check cloud config +echo "Checking cloud config..." +if ! cloud_config_has vm_type "small"; then + error "Cloud config missing required vm_type 'small'" +fi + +echo "All checks passed!" +``` + +## Manifest Issues + +### YAML Syntax Errors + +**Invalid YAML:** +```bash +Error: yaml: line 10: found character that cannot start any token +``` + +**Debugging:** +```bash +# Validate all YAML files +for file in manifests/**/*.yml; do + echo "Checking $file..." + yaml-lint "$file" || yamllint "$file" +done + +# Common issues: +# - Tabs instead of spaces +# - Incorrect indentation +# - Missing quotes around values with colons +``` + +### Spruce Errors + +**Merge failures:** +```bash +Error: spruce merge failed: conflicting key types +``` + +**Debug approach:** +```bash +# Test manifest merging +cd /path/to/kit + +# Base only +spruce merge manifests/base.yml + +# With features +spruce merge manifests/base.yml manifests/features/ha.yml + +# With environment +cat > test-env.yml <&2 "Error: Cannot use both 'aws' and 'azure' features" + exit 1 +fi +``` + +## Testing Issues + +### Local Testing + +**Test kit without compilation:** +```bash +# Use dev directory +mkdir -p ~/deployments/test-kit +cd ~/deployments/test-kit +genesis init --kit /path/to/kit/dev + +# Create test environment +genesis new test-env +``` + +**Mock Genesis environment:** +```bash +#!/bin/bash +# test-kit.sh + +export GENESIS_KIT_NAME="my-kit" +export GENESIS_KIT_VERSION="0.1.0" +export GENESIS_ENVIRONMENT="test" +export GENESIS_ROOT="/tmp/test-deployments" +export GENESIS_SECRETS_PATH="test/env" +export GENESIS_REQUESTED_FEATURES="ha ssl" +export GENESIS_TRACE=1 + +mkdir -p "$GENESIS_ROOT" + +# Test hooks +echo "=== Testing blueprint hook ===" +./hooks/blueprint + +echo "=== Testing new hook ===" +./hooks/new +``` + +### Spec Test Failures + +**Ginkgo test issues:** +```bash +# Run tests with verbose output +cd spec +ginkgo -v --trace + +# Run specific test +ginkgo --focus "should deploy with HA" +``` + +**Common test problems:** + +```go +// spec/spec_test.go +var _ = Describe("My Kit", func() { + BeforeEach(func() { + // Ensure clean state + Setup(kit, "default") + }) + + It("should have required properties", func() { + manifest := Manifest() + + // Debug manifest + fmt.Printf("Manifest: %+v\n", manifest) + + // Assertions with clear errors + Expect(manifest).NotTo(BeNil(), + "Manifest should not be nil") + Expect(manifest.InstanceGroups).To(HaveLen(1), + "Should have exactly one instance group") + }) +}) +``` + +## Compilation Issues + +### Kit Compilation Failures + +**Compilation errors:** +```bash +Error: Failed to compile kit: manifest validation failed +``` + +**Debug compilation:** +```bash +# Compile with verbose output +genesis compile-kit --name my-kit --version 0.1.0 --verbose + +# Dev compilation (no tarball) +genesis compile-kit --dev + +# Force recompilation +rm -rf .genesis/kits/my-kit* +genesis compile-kit +``` + +### Packaging Problems + +**Missing files in compiled kit:** +```bash +# Check kit contents +tar -tzf my-kit-0.1.0.tar.gz | grep -E "(hooks|manifests)" + +# Ensure files are tracked +git add -A +genesis compile-kit --version 0.1.0 +``` + +## Runtime Issues + +### Memory/Performance + +**Slow manifest generation:** +```bash +# Profile manifest generation +time genesis manifest test-env + +# Optimize spruce operations +# Bad: Multiple grabs +a: (( grab params.a )) +b: (( grab params.b )) +c: (( grab params.c )) + +# Better: Single grab +_params: (( grab params )) +a: (( grab _params.a )) +b: (( grab _params.b )) +c: (( grab _params.c )) +``` + +### Large Manifests + +**Memory exhaustion:** +```bash +# Split large arrays +# Instead of inline: +instances: + - { name: web-1, ... } + - { name: web-2, ... } + # ... 100 more + +# Use references: +instance_definitions: + web: { ... } +instances: + - (( grab instance_definitions.web )) + - (( grab instance_definitions.web )) +``` + +## Debugging Tools + +### Kit Validation Script + +```bash +#!/bin/bash +# validate-kit.sh + +echo "=== Validating Kit Structure ===" + +# Check required files +required_files="kit.yml manifests/base.yml hooks/blueprint" +for file in $required_files; do + if [[ -f "$file" ]]; then + echo "✓ $file exists" + else + echo "✗ $file missing" + exit 1 + fi +done + +# Check hook permissions +for hook in hooks/*; do + if [[ -x "$hook" ]]; then + echo "✓ $hook is executable" + else + echo "✗ $hook not executable" + fi +done + +# Validate YAML +for yaml in manifests/**/*.yml; do + if yamllint "$yaml" >/dev/null 2>&1; then + echo "✓ $yaml valid" + else + echo "✗ $yaml invalid" + yamllint "$yaml" + fi +done + +echo "=== Testing Blueprint ===" +GENESIS_REQUESTED_FEATURES="" ./hooks/blueprint +``` + +### Development Workflow + +```bash +#!/bin/bash +# dev-workflow.sh + +# 1. Make changes +vi manifests/base.yml + +# 2. Validate +./validate-kit.sh + +# 3. Test locally +cd ~/deployments/test +genesis manifest test-env + +# 4. Run tests +cd spec && ginkgo + +# 5. Compile +genesis compile-kit --dev + +# 6. Full test +genesis deploy test-env --dry-run +``` + +## Best Practices + +1. **Always test locally** before committing +2. **Use trace mode** for debugging: `GENESIS_TRACE=1` +3. **Validate YAML** syntax regularly +4. **Test each feature** independently +5. **Document complex logic** in comments +6. **Handle errors gracefully** in hooks +7. **Provide helpful error messages** + +Kit development requires attention to detail and systematic testing. Use these debugging techniques to identify and resolve issues quickly. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/manifest-debugging.md b/lib/Genesis/Help/Topics/70-troubleshooting/manifest-debugging.md new file mode 100644 index 00000000..7be14aa9 --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/manifest-debugging.md @@ -0,0 +1,493 @@ +# Manifest Debugging + +This guide helps troubleshoot issues with Genesis manifest generation, merging, and validation. + +## Understanding Manifest Generation + +### The Manifest Pipeline + +Genesis builds manifests through several stages: + +1. **Environment Resolution** - Load environment files hierarchically +2. **Kit Integration** - Apply base manifest and features +3. **Parameter Injection** - Add environment-specific parameters +4. **Secret Resolution** - Replace Vault references +5. **Final Evaluation** - Process Spruce operators + +## Common Manifest Issues + +### Merge Conflicts + +**Symptom:** +``` +Error: merge conflict detected +``` + +**Debug approach:** + +```bash +# Identify conflict source +genesis manifest my-env --trace 2>&1 | grep -B10 "conflict" + +# Test individual merges +spruce merge base.yml overlay.yml + +# Show differences +spruce diff base.yml overlay.yml +``` + +**Common solutions:** + +```yaml +# Problem: Array merge conflict +# base.yml +instances: + - name: web + - name: api + +# overlay.yml +instances: # This replaces instead of merging + - name: worker + +# Solution: Use explicit array indices or replace operator +instances: + - (( replace )) + - name: worker + +# Or use index notation +instances.2: + name: worker +``` + +### Missing Parameters + +**Symptom:** +``` +Error: (( grab params.missing_value )) could not be resolved +``` + +**Debug approach:** + +```bash +# List all grab operations +genesis manifest my-env --no-resolve | \ + grep -o "(( grab [^)]*" | sort -u + +# Check parameter definitions +genesis manifest my-env | \ + spruce json | jq '.params' | \ + grep -i "missing_value" +``` + +**Solutions:** + +```yaml +# Add default values +value: (( grab params.optional || "default" )) + +# Or define in environment +params: + missing_value: "now defined" +``` + +### Type Mismatches + +**Symptom:** +``` +Error: cannot merge string with array +``` + +**Debug approach:** + +```bash +# Find type conflicts +genesis manifest my-env --trace 2>&1 | \ + grep -E "(cannot merge|type mismatch)" + +# Check data types +spruce json base.yml | jq '.path.to.value' +spruce json overlay.yml | jq '.path.to.value' +``` + +**Solutions:** + +```yaml +# Ensure consistent types +# Bad: +base.yml: ports: "8080" +overlay.yml: ports: [8080, 8443] + +# Good: +base.yml: ports: ["8080"] +overlay.yml: ports: ["8080", "8443"] +``` + +## Advanced Debugging Techniques + +### Partial Manifest Generation + +Build manifests step-by-step: + +```bash +# 1. Base manifest only +cat > debug-base.yml < step1.yml + +# 2. Add features +spruce merge \ + step1.yml \ + dev/manifests/features/ha.yml > step2.yml + +# 3. Add environment +spruce merge \ + step2.yml \ + my-env.yml > step3.yml + +# Compare with full generation +genesis manifest my-env > full.yml +diff step3.yml full.yml +``` + +### Operator Debugging + +Debug Spruce operators: + +```bash +# Extract operators +genesis manifest my-env --no-resolve | \ + grep -E "\(\(" | \ + sed 's/.*\(\((.*)\)\).*/\1/' | \ + sort | uniq -c | sort -nr + +# Test operators individually +cat > test-operator.yml <&1 | grep -A5 -B5 "$VAR" +``` + +## Manifest Validation + +### Pre-flight Checks + +```bash +# Validate YAML syntax +for file in *.yml; do + echo "Checking $file..." + yaml-lint "$file" || yamllint "$file" +done + +# Check manifest structure +genesis manifest my-env | \ + bosh int - --path /name >/dev/null && echo "Name: OK" + +genesis manifest my-env | \ + bosh int - --path /instance_groups >/dev/null && echo "Instance Groups: OK" +``` + +### BOSH Validation + +```bash +# Full BOSH validation +genesis manifest my-env > manifest.yml +bosh int manifest.yml + +# Check specific paths +bosh int manifest.yml --path /instance_groups/0/name +bosh int manifest.yml --path /releases +bosh int manifest.yml --path /stemcells +``` + +### Schema Validation + +```yaml +# Create validation schema +# schema.yml +type: map +mapping: + name: + type: str + required: true + instance_groups: + type: seq + sequence: + - type: map + mapping: + name: + type: str + required: true + instances: + type: int + range: + min: 1 +``` + +```bash +# Validate against schema +genesis manifest my-env | \ + python -c "import yaml, sys; yaml.safe_load(sys.stdin)" && \ + echo "Valid YAML structure" +``` + +## Debugging Merge Order + +### Trace File Loading + +```bash +# Show merge order +genesis manifest my-env --trace 2>&1 | \ + grep "Loading" | nl + +# Visualize hierarchy +genesis manifest my-env --trace 2>&1 | \ + grep "Loading environment" | \ + sed 's/.*Loading environment file: //' | \ + awk '{print NR-1 ":" $0}' | \ + sed 's/^/ /' | sed 's/^ 0://' +``` + +### Test Merge Order Impact + +```bash +#!/bin/bash +# test-merge-order.sh + +# Test different merge orders +echo "=== Original Order ===" +spruce merge a.yml b.yml c.yml | spruce json + +echo "=== Reversed Order ===" +spruce merge c.yml b.yml a.yml | spruce json + +echo "=== Differences ===" +diff <(spruce merge a.yml b.yml c.yml | spruce json) \ + <(spruce merge c.yml b.yml a.yml | spruce json) +``` + +## Secret Debugging + +### Mock Secrets for Testing + +```bash +# Test without Vault +genesis manifest my-env --no-resolve > manifest-no-secrets.yml + +# Create mock secrets +cat > mock-secrets.yml < vault-paths.txt + +# Check each path +while read -r path; do + echo -n "Checking $path: " + safe exists "$path" && echo "EXISTS" || echo "MISSING" +done < vault-paths.txt +``` + +## Common Patterns and Solutions + +### Array Manipulation + +```yaml +# Appending to arrays +base_array: + - item1 + - item2 + +# Append +extended_array: (( concat base_array "[\"item3\"]" )) + +# Prepend +extended_array: (( concat "[\"item0\"]" base_array )) + +# Replace specific index +base_array.1: "modified_item2" +``` + +### Conditional Inclusion + +```yaml +# Include based on feature +instance_groups: + - name: web + instances: 2 + - (( grab meta.ha_enabled ? ha_instances : null )) + +ha_instances: + name: web-ha + instances: 3 + +meta: + ha_enabled: (( grab params.enable_ha || false )) +``` + +### Deep Merging + +```yaml +# Control merge behavior +properties: + # Deep merge (default) + database: + host: localhost + port: 5432 + + # Replace entire structure + redis: (( replace )) + host: redis.example.com + port: 6379 +``` + +## Troubleshooting Workflow + +### 1. Isolate the Problem + +```bash +# Generate partial manifests +genesis manifest my-env --partial base > base-only.yml +genesis manifest my-env --partial features > with-features.yml +genesis manifest my-env --no-resolve > without-secrets.yml +genesis manifest my-env > complete.yml + +# Compare stages +diff base-only.yml with-features.yml +diff with-features.yml without-secrets.yml +diff without-secrets.yml complete.yml +``` + +### 2. Binary Search + +```bash +#!/bin/bash +# Find problematic file + +files=(base.yml feature1.yml feature2.yml env.yml) +working=() + +for file in "${files[@]}"; do + if spruce merge "${working[@]}" "$file" >/dev/null 2>&1; then + working+=("$file") + echo "✓ $file merges successfully" + else + echo "✗ $file causes merge failure" + spruce merge "${working[@]}" "$file" + break + fi +done +``` + +### 3. Manual Resolution + +```bash +# Step through resolution +cat > manual-test.yml </dev/null || exit 1 +``` + +### 2. Use Explicit Operations + +```yaml +# Be explicit about intentions +array_items: + - (( append )) # Clearly append + - new_item + +replaced_value: (( replace )) # Clearly replace + completely: new + +merged_map: # Default deep merge + existing_key: modified_value + new_key: new_value +``` + +### 3. Document Complex Merges + +```yaml +# Document merge behavior +instance_groups: + # This will be modified by HA feature to add instances + # DO NOT use (( replace )) here + - name: web + instances: (( grab params.web_instances || 1 )) +``` + +Effective manifest debugging requires understanding both the Genesis merging process and Spruce operators. Use systematic approaches to isolate and resolve issues. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/secret-problems.md b/lib/Genesis/Help/Topics/70-troubleshooting/secret-problems.md new file mode 100644 index 00000000..dc501b73 --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/secret-problems.md @@ -0,0 +1,491 @@ +# Secret Problems + +This guide helps diagnose and resolve issues with Vault integration and secret management in Genesis. + +## Common Secret Issues + +### Cannot Connect to Vault + +**Symptoms:** +``` +Error: Could not connect to Vault at https://127.0.0.1:8200 +Error: x509: certificate signed by unknown authority +Error: 403 permission denied +``` + +**Diagnostics:** + +```bash +# Check Vault target +safe target + +# Test connectivity +safe status + +# Verify authentication +safe auth status + +# Check network +curl -k https://your-vault:8200/v1/sys/health +``` + +**Solutions:** + +1. **Set correct target:** + ```bash + safe target my-vault https://vault.example.com:8200 + ``` + +2. **Skip TLS verification (dev only):** + ```bash + safe target my-vault https://vault.example.com:8200 --skip-verify + # Or + export VAULT_SKIP_VERIFY=1 + ``` + +3. **Add CA certificate:** + ```bash + export VAULT_CACERT=/path/to/ca.crt + safe target my-vault https://vault.example.com:8200 + ``` + +### Authentication Failures + +**Symptoms:** +``` +Error: Vault token has expired +Error: permission denied +Error: 403 Forbidden +``` + +**Diagnostics:** + +```bash +# Check current token +safe vault token lookup + +# Verify token capabilities +safe vault token capabilities secret/path + +# Test authentication +safe auth status +``` + +**Solutions:** + +1. **Re-authenticate:** + ```bash + safe auth + # Or with specific method + safe auth ldap + safe auth github + safe auth token + ``` + +2. **Token renewal:** + ```bash + safe vault token renew + ``` + +3. **Check policies:** + ```bash + # List policies + safe vault policy list + + # Read policy + safe vault policy read my-policy + ``` + +### Missing Secrets + +**Symptoms:** +``` +Error: secret/path/to/secret:key not found +Error: Could not retrieve secret from Vault +``` + +**Diagnostics:** + +```bash +# Check if secret exists +safe exists secret/path/to/secret + +# List secrets in path +safe tree secret/path/to + +# Check exact path +safe get secret/path/to/secret + +# Verify secrets for environment +genesis secrets-plan my-env +``` + +**Solutions:** + +1. **Generate missing secrets:** + ```bash + genesis add-secrets my-env + ``` + +2. **Create manually:** + ```bash + # Password + safe gen secret/path password + + # SSH key + safe ssh secret/path/ssh + + # Certificate + safe x509 issue secret/path/cert \ + --name example.com \ + --ttl 365d + ``` + +3. **Check path correctness:** + ```bash + # Get actual secrets path + genesis secrets-path my-env + + # Should match references in manifest + genesis manifest my-env --no-resolve | grep vault + ``` + +## Secret Path Issues + +### Incorrect Paths + +**Diagnostics:** + +```bash +# Show expected secrets path +genesis secrets-path my-env + +# Compare with actual usage +genesis manifest my-env --no-resolve | \ + grep -o '(( *vault *"[^"]*"' | \ + sed 's/.*"\([^"]*\)".*/\1/' | \ + sort -u + +# Check path hierarchy +safe tree $(genesis secrets-path my-env) +``` + +**Common path problems:** + +```yaml +# Wrong: Hardcoded path +admin_password: (( vault "secret/prod/admin:password" )) + +# Right: Use relative path +admin_password: (( vault meta.vault "/admin:password" )) + +# Or with Genesis 2.8+ +admin_password: (( vault $GENESIS_SECRETS_PATH "/admin:password" )) +``` + +### Path Migration + +When moving environments: + +```bash +#!/bin/bash +# migrate-secrets.sh + +OLD_PATH="secret/old/path" +NEW_PATH="secret/new/path" + +# Export secrets +safe export $OLD_PATH > secrets-backup.json + +# Import to new location +safe import < secrets-backup.json +safe move $OLD_PATH $NEW_PATH + +# Update environment +sed -i "s|$OLD_PATH|$NEW_PATH|g" my-env.yml +``` + +## Secret Generation Issues + +### Failed Auto-Generation + +**Symptoms:** +``` +Error: Failed to generate secret: x509 certificate generation failed +Error: Could not generate SSH key +``` + +**Diagnostics:** + +```bash +# Check kit secret definitions +grep -A20 "credentials:" kit.yml + +# Test generation manually +safe x509 issue test-cert --ttl 90d +safe ssh test-ssh +safe gen test-password +``` + +**Solutions:** + +1. **Generate manually:** + ```bash + # For certificates + safe x509 issue secret/path/cert \ + --ca secret/path/ca \ + --ttl 365d \ + --subject "/C=US/O=Company/CN=example.com" \ + --san "*.example.com" \ + --san "10.0.0.5" + ``` + +2. **Custom generation:** + ```bash + # Complex password + safe set secret/path password=value < <(pwgen -s 32 1) + + # Multiple values + safe set secret/path \ + username=admin \ + password=secret \ + api_key=abcd1234 + ``` + +### Certificate Problems + +**Common certificate issues:** + +```bash +# Expired certificate +safe x509 show secret/path/cert | grep "Not After" + +# Wrong CA +safe x509 verify secret/path/cert --ca secret/path/ca + +# Missing SANs +safe x509 show secret/path/cert | grep -A5 "Subject Alternative Name" +``` + +**Certificate renewal:** + +```bash +# Renew existing certificate +safe x509 renew secret/path/cert --ttl 365d + +# Reissue with new parameters +safe x509 reissue secret/path/cert \ + --san "new.example.com" \ + --ttl 365d +``` + +## Secret Rotation + +### Manual Rotation + +```bash +#!/bin/bash +# rotate-secrets.sh + +ENV=$1 +SECRET_PATH=$(genesis secrets-path $ENV) + +# Rotate passwords +for path in admin db api; do + echo "Rotating $path password..." + safe gen "$SECRET_PATH/$path" password +done + +# Rotate SSH keys +safe ssh "$SECRET_PATH/ssh" --no-clobber + +# Rotate certificates (keep same CA) +safe x509 renew "$SECRET_PATH/cert" --ttl 365d +``` + +### Automated Rotation + +Using Genesis rotation features: + +```bash +# Rotate all secrets +genesis rotate-secrets my-env + +# Rotate specific secrets +genesis rotate-secrets my-env --only passwords +genesis rotate-secrets my-env --only certificates + +# Dry run +genesis rotate-secrets my-env --dry-run +``` + +## CredHub Integration + +### Switching from Vault to CredHub + +```yaml +# Environment configuration +genesis: + secrets_provider: credhub + credhub_env: my-bosh-director + +# Update references +properties: + password: (( credhub "admin-password" )) +``` + +### CredHub Debugging + +```bash +# Check CredHub connection +credhub api + +# List secrets +credhub find -n "/" + +# Get specific secret +credhub get -n "/bosh/deployment/secret" +``` + +## Recovery Procedures + +### Vault Sealed + +```bash +# Check seal status +safe vault status + +# Unseal with keys +safe vault operator unseal +# Enter unseal key when prompted + +# Or with multiple keys +for i in 1 2 3; do + echo "Unseal key $i:" + safe vault operator unseal +done +``` + +### Lost Secrets + +**Recovery from backups:** + +```bash +# From Vault backup +safe import < vault-backup-20231201.json + +# From Genesis deployment +bosh -d my-deployment manifest > manifest.yml +# Extract secrets from manifest +``` + +**Regenerate from deployment:** + +```bash +#!/bin/bash +# extract-deployed-secrets.sh + +DEPLOYMENT=$1 +OUTPUT_PATH=$2 + +# Get manifest from BOSH +bosh -d $DEPLOYMENT manifest > deployed-manifest.yml + +# Extract credentials +spruce json deployed-manifest.yml | \ + jq -r '.properties | to_entries[] | + select(.value | type == "string") | + "\(.key)=\(.value)"' > extracted-secrets.txt + +# Store in Vault +while IFS='=' read -r key value; do + safe set "$OUTPUT_PATH/$key" value="$value" +done < extracted-secrets.txt +``` + +## Best Practices + +### 1. Regular Backups + +```bash +#!/bin/bash +# backup-secrets.sh + +BACKUP_DIR="/secure/backups" +DATE=$(date +%Y%m%d-%H%M%S) + +# Export all secrets +safe export secret > "$BACKUP_DIR/vault-$DATE.json" + +# Encrypt backup +gpg --encrypt --recipient backup@example.com \ + "$BACKUP_DIR/vault-$DATE.json" + +# Remove unencrypted +rm "$BACKUP_DIR/vault-$DATE.json" +``` + +### 2. Access Policies + +```hcl +# genesis-policy.hcl +path "secret/data/genesis/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/metadata/genesis/*" { + capabilities = ["list", "read"] +} +``` + +Apply policy: +```bash +safe vault policy write genesis genesis-policy.hcl +``` + +### 3. Secret Hygiene + +```bash +# Check for weak passwords +for secret in $(safe find secret --type password); do + length=$(safe get $secret | wc -c) + if [ $length -lt 20 ]; then + echo "Weak password: $secret (length: $length)" + fi +done + +# Find expired certificates +for cert in $(safe find secret --type x509); do + if ! safe x509 validate $cert --ttl 30d; then + echo "Certificate expiring soon: $cert" + fi +done +``` + +## Troubleshooting Checklist + +### Connection Issues +- [ ] Vault target configured correctly +- [ ] Network connectivity to Vault +- [ ] TLS certificates valid +- [ ] Authentication current + +### Secret Issues +- [ ] Secrets exist at expected paths +- [ ] Correct secret path in environment +- [ ] Proper permissions on paths +- [ ] Secrets have required keys + +### Generation Issues +- [ ] Kit defines secret correctly +- [ ] CA certificates available +- [ ] Sufficient entropy for generation +- [ ] No naming conflicts + +### Rotation Issues +- [ ] Backup before rotation +- [ ] All instances updated +- [ ] Services restarted +- [ ] Old secrets archived + +Effective secret management requires understanding both Vault operations and Genesis integration patterns. Always backup before making changes. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/70-troubleshooting/trace-logging.md b/lib/Genesis/Help/Topics/70-troubleshooting/trace-logging.md new file mode 100644 index 00000000..7a2ef0c0 --- /dev/null +++ b/lib/Genesis/Help/Topics/70-troubleshooting/trace-logging.md @@ -0,0 +1,435 @@ +# Trace Logging + +Genesis provides comprehensive trace logging capabilities for debugging complex issues. This guide covers how to enable, interpret, and use trace logs effectively. + +## Enabling Trace Logging + +### Command-Line Flag + +The simplest way to enable tracing: + +```bash +# Add --trace to any Genesis command +genesis manifest my-env --trace +genesis deploy my-env --trace +genesis check my-env --trace +``` + +### Environment Variable + +Enable tracing for all commands: + +```bash +# Set environment variable +export GENESIS_TRACE=1 + +# Now all commands include trace output +genesis manifest my-env +genesis deploy my-env + +# Disable tracing +unset GENESIS_TRACE +``` + +### Debug Mode + +For even more verbose output: + +```bash +# Maximum verbosity +export GENESIS_DEBUG=1 +export GENESIS_TRACE=1 + +genesis deploy my-env +``` + +## Understanding Trace Output + +### Log Levels + +Genesis uses different prefixes for log levels: + +``` +TRACE - Detailed execution flow +DEBUG - Debugging information +INFO - General information +WARNING - Potential issues +ERROR - Actual problems +``` + +### Trace Output Structure + +```bash +# Example trace output +TRACE> Loading environment file: us.yml +TRACE> Loading environment file: us-east.yml +TRACE> Loading environment file: us-east-prod.yml +DEBUG> Merging 3 environment files with spruce +TRACE> Executing: spruce merge --skip-eval us.yml us-east.yml us-east-prod.yml +DEBUG> Environment merge completed +TRACE> Applying kit overlay: manifests/base.yml +TRACE> Applying feature overlay: manifests/features/ha.yml +``` + +## Common Trace Patterns + +### Environment Loading + +```bash +genesis manifest my-env --trace 2>&1 | grep "Loading" + +# Output shows file loading order: +# TRACE> Loading environment file: us.yml +# TRACE> Loading environment file: us-east.yml +# TRACE> Loading environment file: us-east-1.yml +# TRACE> Loading kit manifest: manifests/base.yml +# TRACE> Loading kit manifest: manifests/features/ssl.yml +``` + +### Secret Resolution + +```bash +genesis manifest my-env --trace 2>&1 | grep -E "(vault|secret)" + +# Shows secret lookups: +# TRACE> Resolving secret: (( vault "secret/us/east/prod/admin:password" )) +# DEBUG> Executing: safe get secret/us/east/prod/admin:password +# TRACE> Secret resolved successfully +``` + +### Spruce Operations + +```bash +genesis manifest my-env --trace 2>&1 | grep -E "(spruce|merge)" + +# Shows merge operations: +# TRACE> Executing: spruce merge --skip-eval base.yml overrides.yml +# DEBUG> Spruce merge completed successfully +# TRACE> Executing: spruce eval manifest.yml +``` + +## Debugging Specific Issues + +### Manifest Generation + +**Trace manifest building process:** + +```bash +# Save full trace +genesis manifest my-env --trace > manifest-trace.log 2>&1 + +# Analyze phases +echo "=== Phase Analysis ===" +grep -n "Phase:" manifest-trace.log + +echo "=== File Loading ===" +grep -n "Loading" manifest-trace.log + +echo "=== Merge Operations ===" +grep -n "merg" manifest-trace.log + +echo "=== Errors ===" +grep -n -i "error" manifest-trace.log +``` + +### Feature Resolution + +**Debug feature selection:** + +```bash +genesis manifest my-env --trace 2>&1 | \ + grep -E "(feature|blueprint)" | \ + tee feature-trace.log + +# Analyze feature application +grep "Applying feature" feature-trace.log +grep "blueprint hook" feature-trace.log +``` + +### Hook Execution + +**Trace hook execution:** + +```bash +# Enable hook tracing +GENESIS_TRACE=1 genesis new my-test-env 2>&1 | \ + grep -E "(hook|executing)" + +# Shows: +# TRACE> Executing hook: new +# TRACE> Hook environment: GENESIS_ROOT=/path/to/repo +# TRACE> Hook environment: GENESIS_ENVIRONMENT=my-test-env +# DEBUG> Hook completed with exit code: 0 +``` + +## Advanced Tracing + +### Time-Based Analysis + +```bash +# Add timestamps to trace +genesis manifest my-env --trace 2>&1 | \ + while IFS= read -r line; do + echo "[$(date '+%Y-%m-%d %H:%M:%S.%3N')] $line" + done | tee timed-trace.log + +# Find slow operations +awk '/TRACE.*Executing/ { + cmd=$0; getline; + if (/completed/) print cmd " - " $0 +}' timed-trace.log +``` + +### Filtered Tracing + +```bash +# Trace only specific components +genesis manifest my-env --trace 2>&1 | \ + grep -E "(vault|secret|spruce)" > filtered-trace.log + +# Trace errors and warnings only +genesis deploy my-env --trace 2>&1 | \ + grep -E "^(ERROR|WARNING)" > issues.log +``` + +### Structured Logging + +```bash +#!/bin/bash +# structured-trace.sh + +# Parse trace into JSON +genesis manifest my-env --trace 2>&1 | \ + perl -ne ' + if (/^(TRACE|DEBUG|INFO|WARNING|ERROR)>\s*(.*)/) { + $level = $1; + $msg = $2; + $time = `date -u +%s`; + chomp $time; + print qq({"time":$time,"level":"$level","message":"$msg"}\n); + } + ' > trace.jsonl + +# Query with jq +jq 'select(.level == "ERROR")' trace.jsonl +``` + +## Trace Log Analysis + +### Common Patterns + +**Identify bottlenecks:** + +```bash +# Find long-running operations +genesis manifest my-env --trace --time 2>&1 | \ + grep -E "took [0-9]+\.[0-9]+s" | \ + sort -k2 -n -r | head -10 +``` + +**Track execution flow:** + +```bash +# Create execution graph +genesis manifest my-env --trace 2>&1 | \ + grep "TRACE>" | \ + awk '{$1=""; print NR ": " $0}' > execution-flow.txt +``` + +### Error Analysis + +```bash +#!/bin/bash +# analyze-errors.sh + +LOG_FILE="genesis-trace.log" +genesis deploy my-env --trace > $LOG_FILE 2>&1 + +echo "=== Error Summary ===" +grep -i "error" $LOG_FILE | wc -l +echo " errors found" + +echo -e "\n=== Error Context ===" +grep -B5 -A5 -i "error" $LOG_FILE + +echo -e "\n=== Failed Operations ===" +grep -E "(failed|exit code: [^0])" $LOG_FILE +``` + +## Performance Profiling + +### Trace Timing + +```bash +# Enable timing information +genesis manifest my-env --trace --time 2>&1 | \ + tee performance-trace.log + +# Extract timing data +grep "took" performance-trace.log | \ + sed 's/.*took \([0-9.]*\)s.*/\1/' | \ + awk '{sum+=$1; count++} END { + print "Total: " sum "s"; + print "Average: " sum/count "s"; + }' +``` + +### Operation Breakdown + +```bash +# Categorize operations by time +genesis manifest my-env --trace --time 2>&1 | \ + grep -E "(Loading|Merging|Executing|Resolving).*took" | \ + awk -F'took ' '{ + split($1, op, ">"); + split($2, time, "s"); + category = op[2]; + gsub(/^[ \t]+|[ \t]+$/, "", category); + split(category, cat, " "); + times[cat[1]] += time[1]; + counts[cat[1]]++; + } + END { + for (c in times) { + printf "%-20s: %8.3fs (%d operations, avg: %.3fs)\n", + c, times[c], counts[c], times[c]/counts[c]; + } + }' | sort -k2 -n -r +``` + +## Logging Best Practices + +### 1. Targeted Tracing + +Don't enable trace for everything: + +```bash +# Good: Trace specific issue +genesis manifest problematic-env --trace > issue.log 2>&1 + +# Bad: Trace everything always +export GENESIS_TRACE=1 # In .bashrc +``` + +### 2. Log Rotation + +Manage trace log files: + +```bash +# Rotate logs script +#!/bin/bash +LOG_DIR="$HOME/.genesis/logs" +mkdir -p "$LOG_DIR" + +# Run with logging +genesis deploy my-env --trace > \ + "$LOG_DIR/deploy-$(date +%Y%m%d-%H%M%S).log" 2>&1 + +# Clean old logs +find "$LOG_DIR" -name "*.log" -mtime +30 -delete +``` + +### 3. Structured Debugging + +Create debugging workflows: + +```bash +#!/bin/bash +# debug-deployment.sh + +ENV=$1 +ISSUE=$2 +DEBUG_DIR="debug-$ENV-$(date +%Y%m%d-%H%M%S)" + +mkdir -p "$DEBUG_DIR" + +echo "Collecting debug information for $ENV..." + +# Manifest trace +genesis manifest $ENV --trace > \ + "$DEBUG_DIR/manifest-trace.log" 2>&1 + +# Check trace +genesis check $ENV --trace > \ + "$DEBUG_DIR/check-trace.log" 2>&1 + +# Environment info +genesis info $ENV > \ + "$DEBUG_DIR/info.txt" 2>&1 + +# Create summary +cat > "$DEBUG_DIR/summary.txt" < Resolving secret: (( vault "secret/path:key" )) +DEBUG> Executing: safe get secret/path:key +ERROR> Failed to retrieve secret: dial tcp 127.0.0.1:8200: connection refused +``` + +**Interpretation**: Vault is not accessible at the expected address. + +### Merge Conflicts + +``` +TRACE> Executing: spruce merge base.yml overlay.yml +ERROR> merge conflict: key 'params.size' has conflicting values +DEBUG> base.yml defines params.size as integer +DEBUG> overlay.yml defines params.size as string +``` + +**Interpretation**: Type mismatch in parameter override. + +### Missing Files + +``` +TRACE> Loading environment file: production.yml +TRACE> Looking for parent: prod.yml +ERROR> Could not find parent environment: prod.yml +TRACE> Searched in: ., .., ../.. +``` + +**Interpretation**: Hierarchical environment file missing. + +## Trace Output Reference + +### Standard Trace Messages + +| Pattern | Meaning | +|---------|---------| +| `Loading environment file:` | Reading YAML environment file | +| `Loading kit manifest:` | Reading kit-provided YAML | +| `Executing:` | Running external command | +| `Resolving secret:` | Looking up Vault secret | +| `Applying feature:` | Adding feature-specific configuration | +| `Merging files with spruce` | Combining YAML files | +| `Hook environment:` | Environment variables for hooks | +| `Validating manifest` | Pre-deployment checks | + +### Debug Flags + +| Flag | Purpose | Use Case | +|------|---------|----------| +| `--trace` | Enable trace logging | General debugging | +| `--debug` | Extra debug output | Deep troubleshooting | +| `--time` | Add timing information | Performance analysis | +| `--no-color` | Disable color output | Log processing | +| `--json` | JSON output (where supported) | Automation | + +Trace logging is a powerful debugging tool. Use it judiciously to diagnose issues without overwhelming yourself with information. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/.keep b/lib/Genesis/Help/Topics/90-reference-guides/.keep new file mode 100644 index 00000000..e69de29b diff --git a/lib/Genesis/Help/Topics/90-reference-guides/environment-variables.md b/lib/Genesis/Help/Topics/90-reference-guides/environment-variables.md new file mode 100644 index 00000000..68919a66 --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/environment-variables.md @@ -0,0 +1,596 @@ +# Environment Variables Reference + +This document provides a comprehensive reference for all environment variables used by Genesis, organized by category for easier navigation. + +## Core System & Configuration + +These fundamental variables control Genesis operation and basic configuration. + +### GENESIS_VERSION +- **Description**: Current version of Genesis being used. Set internally during startup. +- **Default**: Set automatically +- **Used By**: Version compatibility checks, prerequisite validation +- **Example**: `GENESIS_VERSION="2.8.0"` + +### GENESIS_LIB +- **Description**: Path to Genesis library directory. Can be overridden to use alternate library location. +- **Default**: `bin/lib` under Genesis installation directory +- **Used By**: Loading kit modules, command modules, library components +- **Example**: `GENESIS_LIB="/opt/genesis/lib"` + +### GENESIS_CONFIG_NO_CHECK +- **Description**: Skip configuration validation checks when set. +- **Used By**: Kit validation, deployment operations +- **Example**: `GENESIS_CONFIG_NO_CHECK=1` + +### GENESIS_CONFIG_AUTOMATIC_UPGRADE +- **Description**: Controls automatic configuration upgrades during tests. +- **Values**: `no`, `yes`, `silent` +- **Used By**: Test scripts, configuration management +- **Example**: `GENESIS_CONFIG_AUTOMATIC_UPGRADE=yes` + +### GENESIS_MIN_VERSION +- **Description**: Minimum Genesis version required for compatibility. +- **Used By**: Compatibility checks, environment validation +- **Example**: `GENESIS_MIN_VERSION="2.7.0"` + +### GENESIS_MIN_VERSION_FOR_KIT +- **Description**: Minimum Genesis version required for a specific kit. +- **Used By**: Kit compatibility validation +- **Example**: `GENESIS_MIN_VERSION_FOR_KIT="2.8.0"` + +### GENESIS_USING_EMBEDDED +- **Description**: Indicates Genesis is using embedded mode. +- **Default**: `1` when applicable +- **Used By**: Command execution, state management + +### GENESIS_IS_HELPING_YOU +- **Description**: Enables extended help and assistance mode. +- **Used By**: Operation control, state management + +## Output, Logging & Display Control + +Variables affecting output formatting, logging, and terminal display. + +### GENESIS_SHOW_TIMINGS +- **Description**: Show duration of key operations when set. +- **Used By**: Timing output, operation monitoring +- **Example**: `GENESIS_SHOW_TIMINGS=1` + +### GENESIS_NO_UTF8 +- **Description**: Disable UTF-8 output for limited character support environments. +- **Used By**: Character output control, display formatting +- **Example**: `GENESIS_NO_UTF8=1` + +### GENESIS_QUIET +- **Description**: Reduce output verbosity, showing only errors and critical information. +- **Used By**: Output control across all commands +- **Example**: `GENESIS_QUIET=1` + +### GENESIS_LOG_STYLE +- **Description**: Control output style formatting. +- **Values**: `plain`, `color`, `html` +- **Default**: `plain` +- **Example**: `GENESIS_LOG_STYLE=color` + +### GENESIS_OUTPUT_COLUMNS +- **Description**: Control width of text output. +- **Default**: `80` columns +- **Used By**: Terminal output formatting +- **Example**: `GENESIS_OUTPUT_COLUMNS=120` + +### GENESIS_NO_BOXES +- **Description**: Disable box-drawing characters in terminal output. +- **Used By**: Terminal formatting +- **Example**: `GENESIS_NO_BOXES=1` + +### GENESIS_NOCOLOR +- **Description**: Disable colored output in terminal messages. +- **Used By**: Color formatting control +- **Example**: `GENESIS_NOCOLOR=1` + +### GENESIS_STACK_TRACE +- **Description**: Enable stack trace logging for debugging. +- **Values**: `true` when enabled +- **Used By**: Error reporting, debugging +- **Example**: `GENESIS_STACK_TRACE=true` + +### GENESIS_TRACE +- **Description**: Enable trace-level logging for detailed debugging. +- **Values**: `true` when enabled +- **Used By**: Detailed trace output, Vault operations +- **Example**: `GENESIS_TRACE=true` + +### GENESIS_DEBUG +- **Description**: Enable debug-level logging for Genesis operations. +- **Values**: `true` when enabled +- **Used By**: Debug logging, test scripts +- **Example**: `GENESIS_DEBUG=true` + +### GENESIS_SHOW_BOSH_CMD +- **Description**: Display BOSH commands during execution. +- **Values**: `true` when enabled +- **Example**: `GENESIS_SHOW_BOSH_CMD=true` + +## Path & Directory Management + +Variables for managing directories and file paths. + +### GENESIS_CALLER_DIR +- **Description**: Directory where Genesis was originally invoked. +- **Used By**: Path resolution, context maintenance +- **Note**: Preferred over deprecated GENESIS_ORIGINATING_DIR + +### GENESIS_DEPLOYMENT_ROOT +- **Description**: Root directory of current deployment. +- **Set When**: Using @-notation for environments +- **Used By**: Repository location, environment files + +### GENESIS_HOME +- **Description**: Home directory for Genesis. +- **Default**: `$HOME` +- **Used By**: Environment setup, directory initialization + +### GENESIS_KIT_PATH +- **Description**: File path to the current kit. +- **Set By**: Kit initialization +- **Used By**: Resource location, path validation + +### GENESIS_PACK_PATH +- **Description**: Path for Genesis pack operations. +- **Used By**: Pack command, test cases + +### GENESIS_ORIGINATING_DIR (Deprecated) +- **Description**: Directory from which Genesis was invoked. +- **Status**: Deprecated - use GENESIS_CALLER_DIR instead + +### GENESIS_ROOT +- **Description**: Root directory for Genesis operations. +- **Used By**: Root directory configuration, pipeline adjustments + +### GENESIS_ROOT_CA_PATH +- **Description**: Path to root CA certificate. +- **Used By**: CA path configuration, Vault operations + +### GENESIS_TOPDIR +- **Description**: Top-level directory for Genesis operations. +- **Used By**: Test scripts +- **Example**: `GENESIS_TOPDIR="/path/to/genesis"` + +### GENESIS_MANIFEST_FILE +- **Description**: Path to unredacted, unpruned manifest. +- **Set By**: Kit during manifest generation + +### GENESIS_PREDEPLOY_DATAFILE +- **Description**: File path for pre-deployment data. +- **Used By**: Pre-deployment data storage + +## Command, Hook & Execution Control + +Variables controlling command execution and hooks. + +### GENESIS_CALLBACK_BIN +- **Description**: Path to Genesis binary for callbacks. +- **Used By**: Command execution, embedding + +### GENESIS_CALL_BIN +- **Description**: Binary path for Genesis commands. +- **Used By**: Command embedding and execution + +### GENESIS_CALL_ENV +- **Description**: Environment-specific command execution. +- **Note**: Preferred over deprecated GENESIS_CALL + +### GENESIS_CALL_FULL +- **Description**: Full command call for Genesis. +- **Used By**: Command logging + +### GENESIS_KIT_HOOK +- **Description**: Current hook being executed. +- **Used By**: Hook-specific operations + +### GENESIS_COMMAND +- **Description**: Current command being executed. +- **Used By**: Command execution and logging + +### GENESIS_COMMANDS +- **Description**: Mapping of command names to definitions. +- **Used By**: Command registration and validation + +### GENESIS_ADDON_SCRIPT +- **Description**: Name of addon script to execute. +- **Used By**: Addon script execution + +### GENESIS_NO_MODULE_HOOKS +- **Description**: Disable module hooks during operations. +- **Used By**: Hook loading control + +### GENESIS_DEPLOY_DRYRUN +- **Description**: Indicates deployment is a dry-run. +- **Values**: `true` or `false` + +### GENESIS_DEPLOY_OPTIONS +- **Description**: JSON representation of deployment options. +- **Set By**: Deployment initialization + +### GENESIS_DEPLOY_RC +- **Description**: Return code of BOSH deploy call. +- **Values**: `0` for success, non-zero for failure + +## Environment & Kit Management + +Variables for environment configurations and kit management. + +### GENESIS_ENVIRONMENT +- **Description**: Name of current environment. +- **Used By**: Environment-specific operations +- **Example**: `GENESIS_ENVIRONMENT="us-east-prod"` + +### GENESIS_ENV_IAAS +- **Description**: Infrastructure as a Service type. +- **Values**: `aws`, `azure`, `gcp`, `vsphere`, etc. +- **Example**: `GENESIS_ENV_IAAS="aws"` + +### GENESIS_PREFIX_TYPE +- **Description**: How environment prefixes are handled. +- **Used By**: Prefix configuration + +### GENESIS_PREFIX_SEARCH +- **Description**: Search pattern for environment prefixes. +- **Used By**: Prefix search operations + +### GENESIS_ENV_KIT_OVERRIDE_FILES +- **Description**: Override files for environment's kit. +- **Used By**: Kit override handling + +### GENESIS_ENV_REF +- **Description**: Reference to the environment. +- **Used By**: Environment reference management + +### GENESIS_ENV_SCALE +- **Description**: Scale of the environment. +- **Used By**: Scale-specific operations + +### GENESIS_ENV_VAULT_DESCRIPTOR +- **Description**: Vault descriptor for environment. +- **Used By**: Vault operations + +### GENESIS_ENVIRONMENT_NAME +- **Description**: Environment name for logging. +- **Used By**: Hooks and scripts + +### GENESIS_ENVIRONMENT_PARAMS +- **Description**: Environment parameters in JSON format. +- **Used By**: Parameter management + +### GENESIS_EXECUTABLE_ENVS +- **Description**: Configuration for executable environments. +- **Used By**: Environment execution control + +### GENESIS_HONOR_ENV +- **Description**: Honor current environment settings. +- **Used By**: BOSH operations, CI pipelines + +### GENESIS_LEGACY +- **Description**: Allow environment name mismatches. +- **Used By**: Conditional checks, testing + +### GENESIS_REQUESTED_FEATURES +- **Description**: List of requested features. +- **Used By**: Feature processing and management + +### GENESIS_RUNTIME_CONFIG +- **Description**: Runtime configuration file path. +- **Used By**: Runtime config validation + +### GENESIS_TYPE +- **Description**: Type of Genesis environment. +- **Example**: `GENESIS_TYPE="bosh"` + +### GENESIS_UNEVALED_PARAMS +- **Description**: Prevent parameter evaluation. +- **Values**: `1` when enabled +- **Example**: `GENESIS_UNEVALED_PARAMS=1` + +### GENESIS_KIT_ID +- **Description**: ID of current kit. +- **Used By**: Kit identification + +### GENESIS_KIT_NAME +- **Description**: Name of current kit. +- **Used By**: Kit-specific operations +- **Example**: `GENESIS_KIT_NAME="concourse"` + +### GENESIS_KIT_VERSION +- **Description**: Version of current kit. +- **Used By**: Version-specific operations +- **Example**: `GENESIS_KIT_VERSION="4.0.0"` + +### GENESIS_PREFIX +- **Description**: Prefix for environment operations. +- **Used By**: Environment prefixes + +### GENESIS_CLOUD_CONFIG +- **Description**: Cloud configuration data. +- **Used By**: Cloud config parsing + +### GENESIS_CLOUD_CONFIG_SUBTYPE +- **Description**: Subtype of cloud configuration. +- **Used By**: Cloud-config hook determination + +### GENESIS_OCFP_CONFIG_MOUNT +- **Description**: Vault path for ocfp_config data. +- **Used By**: Config data retrieval + +### GENESIS_CREDHUB_EXODUS_SOURCE +- **Description**: Source for CredHub Exodus data. +- **Used By**: CredHub parameter setup + +### GENESIS_CREDHUB_EXODUS_SOURCE_OVERRIDE +- **Description**: Override default CredHub Exodus source. +- **Used By**: Custom CredHub configurations + +### GENESIS_CREDHUB_ROOT +- **Description**: Root path for CredHub operations. +- **Used By**: CredHub path construction + +### GENESIS_EXODUS +- **Description**: Exodus data handling. +- **Used By**: Exodus data operations + +### GENESIS_EXODUS_BASE +- **Description**: Full Vault path of Exodus data. +- **Used By**: Vault path construction + +### GENESIS_EXODUS_MOUNT +- **Description**: Vault path for Exodus data storage. +- **Used By**: Data storage management + +### GENESIS_EXODUS_MOUNT_OVERRIDE +- **Description**: Override default Exodus mount point. +- **Used By**: Custom mount handling + +### GENESIS_CHECK_YAML_ON_DEPLOY +- **Description**: Enable YAML validation during deployment. +- **Used By**: YAML validation control + +### GENESIS_CONFIRM_RELEASE_OVERRIDES +- **Description**: Control release override confirmation. +- **Used By**: Release override handling + +### GENESIS__LOOKUP_MERGED_MANIFEST +- **Description**: Enable merged manifest lookup. +- **Used By**: Manifest lookup control + +## BOSH Integration + +Variables for BOSH director interaction. + +### GENESIS_BOSH_COMMAND +- **Description**: Path to BOSH command binary. +- **Used By**: BOSH command execution +- **Example**: `GENESIS_BOSH_COMMAND="/usr/local/bin/bosh"` + +### GENESIS_BOSH_ENVIRONMENT +- **Description**: URI of BOSH environment. +- **Used By**: Environment setup and validation +- **Example**: `GENESIS_BOSH_ENVIRONMENT="https://10.0.0.6:25555"` + +### GENESIS_DEFAULT_BOSH_TARGET +- **Description**: Default BOSH target selection. +- **Values**: `parent`, `self`, `ask` +- **Default**: `ask` + +### GENESIS_BOSH_VERIFIED +- **Description**: Track BOSH alias verification. +- **Used By**: Alias verification logic + +### GENESIS_BOSHVARS_FILE +- **Description**: Path to BOSH variables file. +- **Used By**: Variable file handling + +### GENESIS_USE_CREATE_ENV +- **Description**: Use create-env for deployments. +- **Values**: `true` when applicable +- **Example**: `GENESIS_USE_CREATE_ENV=true` + +## Vault & Secrets Management + +Variables for Vault and secret handling. + +### GENESIS_TARGET_VAULT +- **Description**: Target Vault URL. +- **Used By**: Vault operations +- **Example**: `GENESIS_TARGET_VAULT="https://vault.example.com"` + +### GENESIS_SECRETS_MOUNT +- **Description**: Vault mount path for secrets. +- **Default**: `/` within Vault +- **Example**: `GENESIS_SECRETS_MOUNT="/secret"` + +### GENESIS_NO_VAULT +- **Description**: Disable Vault integration. +- **Used By**: Vault usage configuration + +### GENESIS_SECRETS_BASE +- **Description**: Base Vault path for secrets. +- **Example**: `GENESIS_SECRETS_BASE="/secret/genesis"` + +### GENESIS_SECRETS_MOUNT_OVERRIDE +- **Description**: Override default secrets mount. +- **Values**: `true` when enabled + +### GENESIS_SECRETS_SLUG +- **Description**: Vault path component for environment. +- **Example**: `GENESIS_SECRETS_SLUG="us-east-prod"` + +### GENESIS_SECRETS_SLUG_OVERRIDE +- **Description**: Override default secrets slug. +- **Values**: `true` when enabled + +### GENESIS_VAULT_ENV_SLUG +- **Description**: Vault slug for environment. +- **Example**: `GENESIS_VAULT_ENV_SLUG="base/extended"` + +### GENESIS_VERIFY_VAULT +- **Description**: Vault connection verification status. +- **Values**: `1` when verified + +### GENESIS_SECRET_ACTION +- **Description**: Action to perform on secrets. +- **Values**: `add`, `rotate`, `check` +- **Example**: `GENESIS_SECRET_ACTION="rotate"` + +### GENESIS_RENEW_SUBJECT +- **Description**: Update certificate subject during renewal. +- **Used By**: Certificate renewal operations + +### GENESIS_HIDE_PROBLEMATIC_SECRETS +- **Description**: Hide problematic secrets from output. +- **Used By**: Secret visibility control + +### GENESIS_SECRETS_DATAFILE +- **Description**: File path for storing secrets. +- **Example**: `GENESIS_SECRETS_DATAFILE="/tmp/secrets.yml"` + +### GENESIS_SKIP_SECRET_DEFINITION_VALIDATION +- **Description**: Skip secret definition validation. +- **Values**: `true` when enabled + +### GENESIS_SECRETS_PATH (Deprecated) +- **Description**: Path for secrets. +- **Status**: Deprecated in v2.7.0 +- **Note**: Use GENESIS_SECRETS_BASE instead + +### GENESIS_VAULT_PREFIX (Deprecated) +- **Description**: Vault prefix. +- **Status**: Deprecated in v2.7.0 +- **Note**: Use GENESIS_SECRETS_BASE instead + +## CI/CD Pipeline Variables + +Variables for continuous integration and deployment. + +### GENESIS_PIPELINE_DEPLOY_BRANCH +- **Description**: Git branch for pipeline deployments. +- **Used By**: CI pipeline operations + +### GENESIS_CI +- **Description**: Indicates CI environment. +- **Used By**: Pipeline behavior adjustment + +### GENESIS_CI_BASE +- **Description**: Base path for CI secrets in Vault. +- **Used By**: CI-specific data organization + +### GENESIS_CI_DIR +- **Description**: Directory containing CI scripts. +- **Used By**: CI resource location + +### GENESIS_CI_MOUNT +- **Description**: Mount point for CI secrets. +- **Default**: `/` + +### GENESIS_CI_MOUNT_OVERRIDE +- **Description**: Override default CI mount point. +- **Used By**: Custom CI Vault paths + +## Testing & Development + +Variables for testing and development. + +### GENESIS_DEV_MODE +- **Description**: Enable development mode features. +- **Used By**: Development-specific code paths + +### GENESIS_UNDER_TEST +- **Description**: Running under test harness. +- **Used By**: Test behavior modifications + +### GENESIS_TESTING +- **Description**: Running in testing mode. +- **Values**: `yes` when applicable +- **Example**: `GENESIS_TESTING=yes` + +### GENESIS_IGNORE_EVAL +- **Description**: Prevent evaluation catching exits. +- **Used By**: Test evaluation control + +### GENESIS_INDEX +- **Description**: Index-related test configuration. +- **Used By**: Test index validation + +### GENESIS_EXPECT_TRACE +- **Description**: Enable trace logging in tests. +- **Used By**: Test trace control + +### GENESIS_TEST_VAULT_VERSION +- **Description**: Version of test Vault. +- **Example**: `GENESIS_TEST_VAULT_VERSION="1.0.2"` + +### GENESIS_TESTING_BOSH_CPI +- **Description**: Custom BOSH CPI for testing. +- **Example**: `GENESIS_TESTING_BOSH_CPI="warden"` + +### GENESIS_TESTING_CHECK_SECRETS_PRESENCE_ONLY +- **Description**: Only check secret presence in tests. +- **Values**: `true` when enabled + +### GENESIS_TESTING_DEV_VERSION_DETECTION +- **Description**: Control dev version detection. +- **Values**: `false` to disable + +## Miscellaneous + +Other variables and settings. + +### GENESIS_NETWORK_TIMEOUT +- **Description**: Network operation timeout. +- **Default**: `10` seconds +- **Used By**: Network timeout configuration + +### GENESIS_CALL (Deprecated) +- **Description**: Command execution. +- **Status**: Deprecated - use GENESIS_CALL_ENV + +## Usage Examples + +### Enable Full Debugging +```bash +export GENESIS_DEBUG=true +export GENESIS_TRACE=true +export GENESIS_STACK_TRACE=true +export GENESIS_SHOW_BOSH_CMD=true +genesis deploy my-env +``` + +### CI/CD Pipeline Setup +```bash +export GENESIS_CI=true +export GENESIS_CI_BASE="/secret/ci" +export GENESIS_PIPELINE_DEPLOY_BRANCH="main" +export GENESIS_QUIET=1 +``` + +### Development Environment +```bash +export GENESIS_DEV_MODE=1 +export GENESIS_TESTING=yes +export GENESIS_SHOW_TIMINGS=1 +export GENESIS_LOG_STYLE=color +``` + +### Vault Configuration +```bash +export GENESIS_TARGET_VAULT="https://vault.example.com:8200" +export GENESIS_SECRETS_MOUNT="/secret" +export GENESIS_SECRETS_BASE="/secret/genesis/prod" +``` + +## Best Practices + +1. **Use Configuration File**: For persistent settings, use `~/.genesis/config` instead of environment variables +2. **Debugging**: Enable trace and debug only when needed to avoid verbose output +3. **CI/CD**: Set appropriate variables in pipeline configurations +4. **Security**: Avoid exposing sensitive values in environment variables +5. **Documentation**: Document custom environment variable usage in your deployment repos \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/genesis-configuration.md b/lib/Genesis/Help/Topics/90-reference-guides/genesis-configuration.md new file mode 100644 index 00000000..4387730e --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/genesis-configuration.md @@ -0,0 +1,641 @@ +# Genesis Configuration + +This guide provides comprehensive documentation for configuring Genesis using the `~/.genesis/config` file. + +## Overview + +Genesis uses a YAML configuration file to customize its behavior across environments and deployments. This configuration file provides a centralized way to manage Genesis settings without relying on environment variables. + +## Configuration File Location + +The configuration file is located at: +``` +~/.genesis/config +``` + +Genesis automatically creates this directory and file on first use if they don't exist. + +## Configuration Options + +### BOSH Target Configuration + +Control how Genesis selects BOSH directors when multiple options are available. + +#### default_bosh_target + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `default_bosh_target` | enum | `ask` | `ask`, `self`, `parent` | `GENESIS_DEFAULT_BOSH_TARGET` | + +**Description**: Controls default BOSH director targeting behavior. + +**Values**: +- `ask`: Prompt user to select a BOSH director (default) +- `self`: Use current environment as BOSH director +- `parent`: Use BOSH director that deployed current environment + +**Example**: +```yaml +default_bosh_target: ask +``` + +**Notes**: +- BOSH environments using create-env always use `self` +- Non-BOSH director environments always use `parent` +- This setting only applies when there's ambiguity + +### Repository Configuration + +Manage how Genesis handles deployment repositories. + +#### legacy_repo_suffix + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `legacy_repo_suffix` | boolean | `false` | `true`, `false` | `GENESIS_LEGACY_REPO_SUFFIX` | + +**Description**: Enable support for legacy repository naming conventions (e.g., `concourse-deployments`). + +**Example**: +```yaml +legacy_repo_suffix: false +``` + +#### deployment_roots + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `deployment_roots` | array | `[]` | paths or labeled paths | `GENESIS_DEPLOYMENT_ROOTS` | + +**Description**: Configure deployment root directories for organizing Genesis repositories. + +**Format Options**: + +1. **Simple paths**: + ```yaml + deployment_roots: + - /home/user/deployments + - /opt/genesis/deployments + ``` + +2. **Labeled paths**: + ```yaml + deployment_roots: + - production: /opt/genesis/prod + - staging: /opt/genesis/staging + - development: /tmp/genesis-dev + ``` + +3. **Mixed format**: + ```yaml + deployment_roots: + - /home/user/deployments + - prod: /opt/genesis/prod + - staging: /opt/genesis/staging + ``` + +**Environment Variable Format**: +```bash +# Colon-separated paths +export GENESIS_DEPLOYMENT_ROOTS="/path1:/path2" + +# With labels (semicolon for label=path) +export GENESIS_DEPLOYMENT_ROOTS="/path1;prod=/opt/prod;staging=/opt/staging" +``` + +**Usage**: Labels allow referencing deployment roots by name in commands. + +### Genesis Behavior + +Control core Genesis operational behavior. + +#### embedded_genesis + +| Option | Type | Default | Values | +|--------|------|---------|--------| +| `embedded_genesis` | enum | `ignore` | `ignore`, `check`, `warn` | + +**Description**: Control behavior when detecting embedded Genesis installations. + +**Values**: +- `ignore`: Don't check for embedded Genesis +- `check`: Check but don't warn users +- `warn`: Check and warn about embedded Genesis + +**Example**: +```yaml +embedded_genesis: ignore +``` + +#### automatic_config_upgrade + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `automatic_config_upgrade` | enum | `no` | `no`, `yes`, `silent` | `GENESIS_CONFIG_AUTOMATIC_UPGRADE` | + +**Description**: Control automatic configuration file upgrades. + +**Values**: +- `no`: Never automatically upgrade +- `yes`: Upgrade with user confirmation +- `silent`: Upgrade without prompting + +**Example**: +```yaml +automatic_config_upgrade: no +``` + +### Display Configuration + +Customize Genesis output and display. + +#### output_style + +| Option | Type | Default | Values | +|--------|------|---------|--------| +| `output_style` | enum | `plain` | `plain`, `fun`, `pointer` | + +**Description**: Configure visual style of Genesis output. + +**Values**: +- `plain`: Simple text output +- `fun`: Enhanced output with emojis and colors +- `pointer`: Output with pointer indicators + +**Example**: +```yaml +output_style: fun +``` + +#### show_duration + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `show_duration` | boolean | `false` | `true`, `false` | `GENESIS_SHOW_DURATION` | + +**Description**: Display execution time for operations. + +**Example**: +```yaml +show_duration: true +``` + +### Deployment Behavior + +Control deployment-specific operations. + +#### fix_on_deploy + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `fix_on_deploy` | enum | `never` | `always`, `ask`, `never` | `GENESIS_FIX_ON_DEPLOY` | + +**Description**: Automatically fix issues during deployment. + +**Values**: +- `always`: Automatically fix without prompting +- `ask`: Prompt before fixing issues +- `never`: Never attempt automatic fixes + +**Example**: +```yaml +fix_on_deploy: ask +``` + +#### confirm_release_overrides + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `confirm_release_overrides` | enum | - | `always`, `outdated`, `never` | `GENESIS_CONFIRM_RELEASE_OVERRIDES` | + +**Description**: When to confirm BOSH release overrides. + +**Values**: +- `always`: Always confirm overrides +- `outdated`: Only confirm outdated releases +- `never`: Never confirm overrides + +**Example**: +```yaml +confirm_release_overrides: outdated +``` + +### Cache and Storage + +Configure caching and storage locations. + +#### spec_cache_dir + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `spec_cache_dir` | string | `""` | any path | `GENESIS_SPEC_CACHE_DIR` | + +**Description**: Directory for caching specification files. + +**Example**: +```yaml +spec_cache_dir: "/var/cache/genesis/specs" +``` + +#### bosh_logs_path + +| Option | Type | Default | Values | Environment Variable | +|--------|------|---------|--------|---------------------| +| `bosh_logs_path` | string | `/bosh_logs` | path template | `GENESIS_DEPLOYMENT_LOGS_PATH` | + +**Description**: Path template for BOSH deployment logs. + +**Placeholders**: +- ``: Replaced with actual deployment root + +**Example**: +```yaml +bosh_logs_path: "/var/log/genesis//bosh_logs" +``` + +### Warning Suppression + +Control which warnings Genesis displays. + +#### suppress_warnings + +| Option | Type | Default | +|--------|------|---------| +| `suppress_warnings` | hash | see below | + +**Sub-options**: + +| Warning | Type | Default | Environment Variable | +|---------|------|---------|---------------------| +| `oversized_secrets` | boolean | `false` | `GENESIS_SUPRESS_OVERSIZED_SECRETS_WARNING` | +| `bosh_target` | boolean | `false` | `GENESIS_SUPPRESS_BOSH_TARGET_WARNING` | + +**Description**: Selectively suppress specific warnings. + +**Example**: +```yaml +suppress_warnings: + oversized_secrets: true + bosh_target: false +``` + +### Logging Configuration + +Configure detailed logging for Genesis operations. + +#### logs + +| Option | Type | Default | +|--------|------|---------| +| `logs` | array | `[]` | + +**Description**: Array of log configurations, each defining a separate log destination. + +**Log Entry Schema**: + +| Option | Type | Default | Values | Required | +|--------|------|---------|--------|----------| +| `file` | string | - | any path | ✓ | +| `level` | enum | `INFO` | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OUTPUT` | | +| `show_stack` | enum | `default` | `default`, `none`, `full`, `current`, `fatal` | | +| `style` | enum | `plain` | `plain`, `fun`, `pointer`, `rfc-5424` | | +| `timestamp` | boolean | `false` | `true`, `false` | | +| `truncate` | boolean | `false` | `true`, `false` | *future* | +| `lifespan` | enum | `forever` | `forever`, `current`, `N days` | *future* | + +**Log Levels**: +- `TRACE`: Most verbose, all operations +- `DEBUG`: Detailed debugging +- `INFO`: General information +- `WARN`: Warning messages +- `ERROR`: Error messages only +- `OUTPUT`: Command output only + +**Stack Trace Options**: +- `default`: Based on log level +- `none`: Never show traces +- `full`: Always show full traces +- `current`: Current context only +- `fatal`: Fatal errors only + +**Style Options**: +- `plain`: Simple text +- `fun`: Enhanced with colors +- `pointer`: Pointer indicators +- `rfc-5424`: Standard syslog format + +**Example**: +```yaml +logs: + # Main application log + - file: "/var/log/genesis/genesis.log" + level: INFO + timestamp: true + style: plain + + # Debug log + - file: "/tmp/genesis-debug.log" + level: DEBUG + style: rfc-5424 + show_stack: full + + # Error log + - file: "/var/log/genesis/errors.log" + level: ERROR + timestamp: true + show_stack: fatal +``` + +## Complete Example Configuration + +```yaml +# ~/.genesis/config + +# BOSH targeting +default_bosh_target: ask + +# Repository management +legacy_repo_suffix: false +deployment_roots: + - /home/genesis/deployments + - production: /opt/genesis/prod + - staging: /opt/genesis/staging + - development: /tmp/genesis-dev + +# Display preferences +output_style: fun +show_duration: true + +# Deployment behavior +fix_on_deploy: ask +confirm_release_overrides: outdated + +# Cache and storage +spec_cache_dir: "/var/cache/genesis/specs" +bosh_logs_path: "/var/log/genesis/bosh_logs" + +# Warning suppression +suppress_warnings: + oversized_secrets: false + bosh_target: true + +# Genesis behavior +embedded_genesis: warn +automatic_config_upgrade: yes + +# Logging configuration +logs: + # Main log + - file: "/var/log/genesis/genesis.log" + level: INFO + timestamp: true + style: plain + + # Debug log + - file: "/tmp/genesis-debug.log" + level: DEBUG + style: rfc-5424 + timestamp: true + show_stack: full + + # Error log + - file: "/var/log/genesis/errors.log" + level: ERROR + timestamp: true + show_stack: fatal +``` + +## Environment Variable Overrides + +Most configuration options can be overridden using environment variables. When set, environment variables take precedence over configuration file settings. + +### Override Examples + +```bash +# Override BOSH target behavior +export GENESIS_DEFAULT_BOSH_TARGET=self + +# Override deployment roots +export GENESIS_DEPLOYMENT_ROOTS="/alt/path;prod=/alt/prod" + +# Override display settings +export GENESIS_SHOW_DURATION=true + +# Override fix behavior +export GENESIS_FIX_ON_DEPLOY=always +``` + +### Available Environment Variables + +- `GENESIS_DEFAULT_BOSH_TARGET` +- `GENESIS_LEGACY_REPO_SUFFIX` +- `GENESIS_DEPLOYMENT_ROOTS` +- `GENESIS_SHOW_DURATION` +- `GENESIS_CONFIG_AUTOMATIC_UPGRADE` +- `GENESIS_FIX_ON_DEPLOY` +- `GENESIS_CONFIRM_RELEASE_OVERRIDES` +- `GENESIS_SPEC_CACHE_DIR` +- `GENESIS_DEPLOYMENT_LOGS_PATH` +- `GENESIS_SUPRESS_OVERSIZED_SECRETS_WARNING` +- `GENESIS_SUPPRESS_BOSH_TARGET_WARNING` + +## Configuration Validation + +Genesis validates configuration on startup. Invalid configurations result in: +- Clear error messages +- Suggested corrections +- Refusal to run until fixed + +### Common Validation Errors + +1. **Invalid enum values**: + ```yaml + # ERROR: 'maybe' is not valid + fix_on_deploy: maybe + # Valid: always, ask, never + ``` + +2. **Type mismatches**: + ```yaml + # ERROR: boolean expected + show_duration: "yes" + # Valid: true or false + ``` + +3. **Invalid paths**: + ```yaml + # ERROR: must be array + deployment_roots: "/single/path" + # Valid: array format + deployment_roots: + - /single/path + ``` + +## Advanced Usage + +### Multiple Log Destinations + +Configure comprehensive logging: + +```yaml +logs: + # Audit trail - everything + - file: "/var/log/genesis/audit.log" + level: INFO + style: rfc-5424 + timestamp: true + + # Development debugging + - file: "/tmp/genesis-trace.log" + level: TRACE + style: plain + show_stack: full + + # Error monitoring + - file: "/var/log/genesis/errors.log" + level: ERROR + style: plain + timestamp: true + show_stack: fatal + + # Operations log + - file: "/var/log/genesis/ops.log" + level: OUTPUT + timestamp: true +``` + +### Environment-Specific Configuration + +Use deployment roots with labels: + +```yaml +deployment_roots: + - local: ~/genesis/local + - dev: /mnt/nfs/genesis/dev + - staging: /mnt/nfs/genesis/staging + - prod: /secure/genesis/prod +``` + +Then reference by label: +```bash +genesis @prod list +genesis @staging deploy my-env +``` + +### CI/CD Configuration + +Optimize for automation: + +```yaml +# Minimal output for CI +output_style: plain +show_duration: false + +# No confirmations +fix_on_deploy: always +confirm_release_overrides: never +automatic_config_upgrade: silent + +# Suppress warnings +suppress_warnings: + oversized_secrets: true + bosh_target: true + +# Log everything +logs: + - file: "/var/log/ci/genesis.log" + level: DEBUG + timestamp: true + style: plain +``` + +## Migration Guide + +### From Environment Variables + +To migrate from environment variables to configuration file: + +1. **Identify current variables**: + ```bash + env | grep GENESIS_ + ``` + +2. **Create configuration**: + ```yaml + # Map variables to config options + default_bosh_target: parent # from GENESIS_DEFAULT_BOSH_TARGET + show_duration: true # from GENESIS_SHOW_DURATION + ``` + +3. **Test configuration**: + ```bash + # Unset variables + unset GENESIS_DEFAULT_BOSH_TARGET + # Test with config file + genesis list + ``` + +### Upgrading Configuration + +When Genesis detects outdated configuration: + +1. **Backup current config**: + ```bash + cp ~/.genesis/config ~/.genesis/config.backup + ``` + +2. **Enable automatic upgrade**: + ```yaml + automatic_config_upgrade: yes + ``` + +3. **Run Genesis command**: + ```bash + genesis version # Triggers upgrade check + ``` + +## Best Practices + +1. **Version Control**: Keep configuration in version control for team consistency +2. **Comments**: Document configuration choices +3. **Environment Variables**: Use for temporary overrides only +4. **Logging**: Configure appropriate log levels for your needs +5. **Validation**: Test configuration changes before deploying +6. **Backups**: Keep backups before major changes + +## Troubleshooting + +### Configuration Not Loading + +```bash +# Check file location +ls -la ~/.genesis/config + +# Validate YAML syntax +yamllint ~/.genesis/config + +# Test with trace logging +GENESIS_TRACE=1 genesis version +``` + +### Override Not Working + +```bash +# Check environment variable +echo $GENESIS_DEFAULT_BOSH_TARGET + +# Verify precedence (env vars override config) +unset GENESIS_DEFAULT_BOSH_TARGET +genesis version # Now uses config value +``` + +### Permission Issues + +```bash +# Fix permissions +chmod 600 ~/.genesis/config +chmod 700 ~/.genesis + +# Check ownership +chown $(whoami) ~/.genesis/config +``` \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/hook-reference.md b/lib/Genesis/Help/Topics/90-reference-guides/hook-reference.md new file mode 100644 index 00000000..805f5b4b --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/hook-reference.md @@ -0,0 +1,667 @@ +# Hook Reference + +This document provides a complete reference for all Genesis hooks, their parameters, environment variables, and usage patterns. + +## Hook Types + +Genesis supports two types of hooks: + +1. **Bash Scripts** - Traditional shell scripts in the `hooks/` directory +2. **Perl Modules** - Advanced hooks using Genesis::Hook modules + +## Hook Execution Order + +During a typical deployment, hooks execute in this order: + +1. `new` - When creating a new environment +2. `blueprint` - To determine manifest files +3. `secrets` - To check/add/rotate secrets +4. `check` - Pre-deployment validation +5. `pre-deploy` - Just before deployment +6. `deploy` - (Internal - not a hook) +7. `post-deploy` - After deployment +8. `info` - Display deployment information + +## Core Hooks + +### new + +**Purpose**: Interactive environment setup when running `genesis new` + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_ROOT # Repository root directory +GENESIS_ENVIRONMENT # Environment name +GENESIS_SECRETS_PATH # Vault secrets path +GENESIS_VAULT_PREFIX # Legacy: Vault prefix +GENESIS_KIT_NAME # Kit name +GENESIS_KIT_VERSION # Kit version +GENESIS_MIN_VERSION # Minimum Genesis version +``` + +**Helper Functions**: +- `prompt_for` - Interactive prompting +- `genesis_config_block` - Generate Genesis config +- `offer_environment_editor` - Offer to edit file + +**Example**: +```bash +#!/bin/bash +set -eu + +prompt_for base_domain line \ + "What is your base domain?" \ + --default "example.com" \ + --validation dns + +cat > "$GENESIS_ROOT/$GENESIS_ENVIRONMENT.yml" <&2 "Error: Unknown feature '$feature'" + exit 1 + ;; + esac +done +``` + +**Example (Perl)**: +```perl +package Genesis::Hook::Blueprint::MyKit; +use parent qw(Genesis::Hook::Blueprint); + +sub perform { + my ($self) = @_; + + $self->add_files("base.yml"); + $self->add_files("features/ha.yml") if $self->want_feature('ha'); + + return $self->done(1); +} +1; +``` + +### secrets + +**Purpose**: Manage secrets beyond kit.yml definitions + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_SECRET_ACTION # add, check, rotate +GENESIS_ENVIRONMENT +GENESIS_SECRETS_PATH +GENESIS_KIT_NAME +``` + +**Example**: +```bash +#!/bin/bash +set -eu + +case "${GENESIS_SECRET_ACTION}" in + add) + # Generate additional secrets + if want_feature "custom-ca"; then + safe x509 issue "$GENESIS_SECRETS_PATH/custom-ca" \ + --signed-by "$GENESIS_SECRETS_PATH/ca" \ + --ttl 365d \ + --subject "/CN=Custom CA" + fi + ;; + + check) + # Validate secrets exist + if want_feature "provided-cert"; then + safe exists "$GENESIS_SECRETS_PATH/ssl/cert" || \ + echo >&2 "Missing provided certificate" + fi + ;; + + rotate) + # Rotate specific secrets + safe regen "$GENESIS_SECRETS_PATH/api-key" + ;; +esac +``` + +### check + +**Purpose**: Pre-deployment validation + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_ENVIRONMENT +GENESIS_CLOUD_CONFIG # Cloud config YAML +GENESIS_KIT_NAME +GENESIS_REQUESTED_FEATURES +``` + +**Helper Functions**: +- `cloud_config_has` - Check cloud config resources +- `lookup` - Get parameter values +- `want_feature` - Check if feature enabled + +**Example**: +```bash +#!/bin/bash +set -eu + +# Check VM types +vm_type=$(lookup params.vm_type default) +if ! cloud_config_has vm_type "$vm_type"; then + echo >&2 "Error: VM type '$vm_type' not found in cloud config" + exit 1 +fi + +# Check networks +network=$(lookup params.network default) +if ! cloud_config_has network "$network"; then + echo >&2 "Error: Network '$network' not found" + exit 1 +fi + +# Feature-specific checks +if want_feature "ha"; then + instances=$(lookup params.instances 1) + if [[ $instances -lt 3 ]]; then + echo >&2 "Error: HA requires at least 3 instances" + exit 1 + fi +fi +``` + +### pre-deploy + +**Purpose**: Final actions before deployment + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_PREDEPLOY_DATAFILE # File to store data +GENESIS_MANIFEST_FILE # Full manifest path +GENESIS_DEPLOY_OPTIONS # JSON deployment options +GENESIS_ENVIRONMENT +``` + +**Example**: +```bash +#!/bin/bash +set -eu + +# Store current state +echo "timestamp: $(date -u +%s)" > "$GENESIS_PREDEPLOY_DATAFILE" +echo "version: $(get_deployed_version)" >> "$GENESIS_PREDEPLOY_DATAFILE" + +# Validate major version upgrade +if is_major_upgrade; then + if [[ "${GENESIS_CONFIRM:-}" != "yes" ]]; then + describe "" \ + "WARNING: Major version upgrade detected!" \ + "This may require manual intervention." + + prompt_for confirm boolean \ + "Continue with deployment?" + + [[ "$confirm" == "true" ]] || exit 1 + fi +fi + +# Run pre-deployment tasks +if deployment_exists; then + bosh -d "$BOSH_DEPLOYMENT" run-errand pre-upgrade || true +fi +``` + +### post-deploy + +**Purpose**: Actions after deployment completes + +**Type**: Bash script or Perl module + +**Environment Variables**: +```bash +GENESIS_DEPLOY_RC # Deployment return code +GENESIS_PREDEPLOY_DATAFILE # Pre-deploy data +GENESIS_ENVIRONMENT +GENESIS_CALL_BIN # Genesis binary path +``` + +**Example (Bash)**: +```bash +#!/bin/bash +set -eu + +if [[ "$GENESIS_DEPLOY_RC" != "0" ]]; then + echo "Deployment failed - skipping post-deploy actions" + exit 0 +fi + +# Run smoke tests +describe "Running smoke tests..." +bosh -d "$BOSH_DEPLOYMENT" run-errand smoke-tests + +# Update DNS +if want_feature "external-dns"; then + update_external_dns "$(lookup params.external_url)" +fi + +# Display success +describe "" "Deployment successful!" +``` + +**Example (Perl)**: +```perl +package Genesis::Hook::PostDeploy::MyKit; +use parent qw(Genesis::Hook::PostDeploy); + +sub perform { + my ($self) = @_; + + return 0 unless $self->deploy_successful; + + $self->run_errand('smoke-tests'); + $self->upload_runtime_configs if $self->config('runtime'); + + return $self->done(1); +} +1; +``` + +### info + +**Purpose**: Display deployment information + +**Type**: Bash script + +**Environment Variables**: +```bash +GENESIS_ENVIRONMENT +GENESIS_SECRETS_PATH +BOSH_DEPLOYMENT # BOSH deployment name +``` + +**Example**: +```bash +#!/bin/bash +set -eu + +base_url="https://$(lookup params.base_domain)" +username="admin" +password="$(safe get $GENESIS_SECRETS_PATH/admin:password)" + +describe "" \ + "Deployment Information" \ + "" \ + " URL: $base_url" \ + " Username: $username" \ + " Password: $password" \ + "" \ + "To access the dashboard:" \ + " genesis do $GENESIS_ENVIRONMENT login" +``` + +### addon + +**Purpose**: Provide additional commands via `genesis do` + +**Type**: Bash script or Perl module + +**Environment Variables**: +```bash +GENESIS_ADDON_SCRIPT # Addon being executed +GENESIS_ADDON_ARGS # Arguments array +GENESIS_ENVIRONMENT +GENESIS_SECRETS_PATH +``` + +**Example (Bash)**: +```bash +#!/bin/bash +set -eu + +case "$GENESIS_ADDON_SCRIPT" in + list) + echo "Available addons:" + echo " login - Log into the system" + echo " backup - Perform backup" + echo " restore - Restore from backup" + ;; + + login) + url="https://$(lookup params.base_domain)" + password="$(safe get $GENESIS_SECRETS_PATH/admin:password)" + + echo "Logging into $url..." + open "$url" || xdg-open "$url" + echo "Password: $password" + ;; + + backup) + bosh -d "$BOSH_DEPLOYMENT" run-errand backup + ;; + + restore) + backup_file="${1:?Usage: genesis do $GENESIS_ENVIRONMENT restore }" + bosh -d "$BOSH_DEPLOYMENT" run-errand restore -v "backup_file=$backup_file" + ;; + + *) + echo >&2 "Error: Unknown addon '$GENESIS_ADDON_SCRIPT'" + exit 1 + ;; +esac +``` + +**Example (Perl)**: +```perl +package Genesis::Hook::Addon::MyKit::backup; +use parent qw(Genesis::Hook::Addon); + +sub init { + my $class = shift; + my $obj = $class->SUPER::init(@_); + $obj->parse_options(['full', 'incremental']); + return $obj; +} + +sub perform { + my ($self) = @_; + + my $type = $self->has_option('incremental') ? 'incremental' : 'full'; + my $result = $self->bosh->run_errand("backup-$type"); + + return $self->done($result); +} + +sub cmd_details { + return "Perform system backup (--full or --incremental)"; +} +1; +``` + +## Helper Functions Reference + +### Prompting Functions + +```bash +# Basic prompt +prompt_for varname "Question?" + +# With default +prompt_for varname line "Question?" --default "value" + +# With validation +prompt_for varname line "Question?" \ + --validation ip \ + --validation port \ + --validation dns \ + --validation url \ + --validation email \ + --validation "/^[A-Z]+$/" + +# Boolean prompt +prompt_for confirm boolean "Continue?" --default y + +# Selection menu +prompt_for choice select "Choose:" \ + -o "[option1] First Option" \ + -o "[option2] Second Option" + +# Multi-line input +prompt_for content block "Enter content (Ctrl-D to finish):" + +# Secret prompts +prompt_for "$GENESIS_SECRETS_PATH/password" secret-line \ + "Enter password:" + +prompt_for "$GENESIS_SECRETS_PATH/cert" secret-block \ + "Paste certificate:" +``` + +### Lookup Functions + +```bash +# Get parameter value with default +value=$(lookup params.key default_value) + +# Check if parameter exists +if param_exists params.key; then + echo "Parameter is set" +fi + +# Get deployment name +deployment=$(lookup genesis.bosh_deployment) +``` + +### Feature Functions + +```bash +# Check single feature +if want_feature "monitoring"; then + echo "Monitoring enabled" +fi + +# Check multiple features +if features_enabled "ha" "ssl"; then + echo "Both HA and SSL enabled" +fi + +# Get feature list +for feature in $GENESIS_REQUESTED_FEATURES; do + echo "Feature: $feature" +done +``` + +### Cloud Config Functions + +```bash +# Check VM type exists +if cloud_config_has vm_type "large"; then + echo "Large VM type available" +fi + +# Check network +if cloud_config_has network "default"; then + echo "Default network exists" +fi + +# Check disk type +if cloud_config_has disk_type "ssd"; then + echo "SSD disk type available" +fi + +# Get cloud config value +value=$(cloud_config_get networks.0.name) +``` + +### Output Functions + +```bash +# Formatted output +describe "Setting up deployment" +describe "" "Line 1" "Line 2" "Line 3" + +# Colored output +echo "$(green "Success"): Operation completed" +echo "$(yellow "Warning"): Check configuration" +echo "$(red "Error"): Operation failed" + +# Stylized output +header "Deployment Configuration" +bullet "First item" +bullet "Second item" +``` + +## Environment Variables Reference + +### Always Available + +| Variable | Description | +|----------|-------------| +| `GENESIS_ROOT` | Repository root directory | +| `GENESIS_ENVIRONMENT` | Environment name | +| `GENESIS_KIT_NAME` | Kit name | +| `GENESIS_KIT_VERSION` | Kit version | +| `GENESIS_SECRETS_PATH` | Vault secrets base path | +| `GENESIS_VAULT_PREFIX` | Legacy Vault prefix | + +### Hook-Specific + +| Hook | Variables | +|------|-----------| +| `new` | `GENESIS_MIN_VERSION` | +| `blueprint` | `GENESIS_REQUESTED_FEATURES` | +| `secrets` | `GENESIS_SECRET_ACTION` | +| `check` | `GENESIS_CLOUD_CONFIG` | +| `pre-deploy` | `GENESIS_PREDEPLOY_DATAFILE`, `GENESIS_MANIFEST_FILE`, `GENESIS_DEPLOY_OPTIONS` | +| `post-deploy` | `GENESIS_DEPLOY_RC`, `GENESIS_PREDEPLOY_DATAFILE` | +| `addon` | `GENESIS_ADDON_SCRIPT`, `GENESIS_ADDON_ARGS` | + +### BOSH Variables + +When in BOSH context: + +| Variable | Description | +|----------|-------------| +| `BOSH_ENVIRONMENT` | BOSH director URL | +| `BOSH_CLIENT` | BOSH authentication client | +| `BOSH_CLIENT_SECRET` | BOSH authentication secret | +| `BOSH_CA_CERT` | BOSH CA certificate | +| `BOSH_DEPLOYMENT` | Deployment name | + +## Best Practices + +### 1. Error Handling + +Always use proper error handling: + +```bash +#!/bin/bash +set -eu # Exit on error, undefined variables + +# Explicit error checking +if ! command_that_might_fail; then + echo >&2 "Error: Command failed" + exit 1 +fi +``` + +### 2. Idempotency + +Make hooks idempotent: + +```bash +# Check before creating +if ! safe exists "$GENESIS_SECRETS_PATH/generated"; then + safe gen "$GENESIS_SECRETS_PATH/generated" password +fi + +# Check before running errands +if ! errand_has_run "configure-database"; then + bosh -d "$BOSH_DEPLOYMENT" run-errand configure-database +fi +``` + +### 3. User Communication + +Provide clear feedback: + +```bash +describe "Validating deployment configuration..." + +# Detailed progress +describe "✓ Cloud config validated" +describe "✓ Secrets present" +describe "✓ Network connectivity confirmed" + +# Errors with context +if [[ $error ]]; then + describe "" \ + "$(red "ERROR"): Deployment validation failed" \ + "" \ + " Missing VM type: $vm_type" \ + " Please update your cloud config" \ + "" \ + "Run: bosh update-cloud-config" +fi +``` + +### 4. Feature Validation + +Validate feature combinations: + +```bash +# Check incompatible features +if want_feature "standalone" && want_feature "ha"; then + echo >&2 "Error: Cannot use both 'standalone' and 'ha' features" + exit 1 +fi + +# Check required parameters for features +if want_feature "ssl"; then + if ! param_exists params.certificate; then + echo >&2 "Error: SSL feature requires params.certificate" + exit 1 + fi +fi +``` + +### 5. Documentation + +Document complex logic: + +```bash +# This check ensures that HA deployments have sufficient +# instances across multiple AZs for proper redundancy +if want_feature "ha"; then + # Minimum 3 instances for quorum + # Should be odd number to prevent split-brain + # Distributed across AZs for fault tolerance +fi +``` + +Hooks provide the extensibility that makes Genesis kits powerful and flexible. Understanding their capabilities enables creating sophisticated deployment automation. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/index.md b/lib/Genesis/Help/Topics/90-reference-guides/index.md new file mode 100644 index 00000000..cc1a551d --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/index.md @@ -0,0 +1,29 @@ +# Reference Guides + +This section contains comprehensive reference documentation for Genesis configuration, environment variables, and advanced features. + +## Topics in this Section + +### [Environment Variables](environment-variables.md) +Complete reference for all Genesis environment variables and their usage. + +### [Genesis Configuration](genesis-configuration.md) +Detailed guide to configuring Genesis using the `~/.genesis/config` file. + +### [Runtime Configs](runtime-configs.md) +How to specify and manage BOSH runtime configurations in Genesis. + +### [Kit Configuration Reference](kit-configuration.md) +Reference for kit.yml configuration options and structure. + +### [Hook Reference](hook-reference.md) +Complete reference for all Genesis hooks and their parameters. + +### [Manifest Operators](manifest-operators.md) +Reference for Spruce operators used in Genesis manifests. + +## Quick Links + +- [Environment Setup](../10-environments/setting-up.md) +- [Kit Development](../50-kits/authoring-kits.md) +- [Troubleshooting](../70-troubleshooting/index.md) \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/kit-configuration.md b/lib/Genesis/Help/Topics/90-reference-guides/kit-configuration.md new file mode 100644 index 00000000..e4546427 --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/kit-configuration.md @@ -0,0 +1,619 @@ +# Kit Configuration Reference + +This document provides a complete reference for the `kit.yml` configuration file used in Genesis kits. + +## Overview + +The `kit.yml` file defines kit metadata, dependencies, secrets, and configuration options. It serves as the primary configuration point for Genesis kits. + +## File Structure + +```yaml +# Basic kit information +name: my-kit +authors: + - Your Name +docs: https://github.com/genesis-community/my-kit +code: https://github.com/genesis-community/my-kit + +# Version constraints +genesis_version_min: 2.8.0 + +# Dependencies +releases: + - name: my-release + version: 1.2.3 + url: https://bosh.io/d/github.com/org/release + sha1: abc123... + +stemcells: + - os: ubuntu-jammy + version: latest + +# Features +features: + - name: ha + description: Enable high availability mode + - name: ssl + description: Enable SSL/TLS encryption + +# Secrets and certificates +credentials: + - name: admin_password + description: Administrative user password + +certificates: + - name: server + description: Server certificate for TLS +``` + +## Configuration Sections + +### Basic Information + +#### name +**Required**: Yes +**Type**: String +**Description**: The name of the kit. Must match the directory name for compiled kits. + +```yaml +name: concourse +``` + +#### authors +**Required**: No +**Type**: Array of strings +**Description**: List of kit authors with optional email addresses. + +```yaml +authors: + - Jane Doe + - John Smith +``` + +#### docs +**Required**: No +**Type**: String (URL) +**Description**: URL to kit documentation. + +```yaml +docs: https://github.com/genesis-community/concourse-genesis-kit +``` + +#### code +**Required**: No +**Type**: String (URL) +**Description**: URL to kit source code repository. + +```yaml +code: https://github.com/genesis-community/concourse-genesis-kit +``` + +#### description +**Required**: No +**Type**: String +**Description**: Brief description of the kit's purpose. + +```yaml +description: | + Deploys Concourse CI/CD platform with Genesis +``` + +### Version Constraints + +#### genesis_version_min +**Required**: No +**Type**: String (Semantic Version) +**Description**: Minimum Genesis version required for this kit. + +```yaml +genesis_version_min: 2.8.0 +``` + +#### genesis_version_max +**Required**: No +**Type**: String (Semantic Version) +**Description**: Maximum Genesis version supported by this kit. + +```yaml +genesis_version_max: 2.9.99 +``` + +### Dependencies + +#### releases +**Required**: No +**Type**: Array of release specifications +**Description**: BOSH releases required by the kit. + +**Release Specification**: +```yaml +releases: + - name: concourse # Required: Release name + version: 7.8.3 # Required: Version (can use patterns) + url: https://... # Optional: Download URL + sha1: abc123... # Optional: SHA1 checksum + github: owner/repo # Optional: GitHub repository + + # Version patterns + - name: postgres + version: "43" # Exact version + + - name: bpm + version: 1.1.+ # Any 1.1.x version + + - name: routing + version: ">=0.200.0" # Version 0.200.0 or higher +``` + +#### stemcells +**Required**: No +**Type**: Array of stemcell specifications +**Description**: Stemcells required by the kit. + +```yaml +stemcells: + - os: ubuntu-jammy # Required: OS type + version: latest # Required: Version or "latest" + + - os: ubuntu-bionic + version: 621.+ # Minimum version pattern + + # Multiple stemcells for different instance groups + - alias: default + os: ubuntu-jammy + version: latest + + - alias: windows + os: windows2019 + version: latest +``` + +### Features + +#### features +**Required**: No +**Type**: Array of feature definitions +**Description**: Optional features that can be enabled. + +```yaml +features: + - name: ha + description: | + Enable high availability mode with 3 instances + deprecated: false # Optional: Mark as deprecated + + - name: monitoring + description: Enable Prometheus exporters + + - name: shield-agent + deprecated: true + description: | + DEPRECATED: Use Shield runtime config instead +``` + +### Secrets Configuration + +#### credentials +**Required**: No +**Type**: Array of credential definitions +**Description**: Password and random secret definitions. + +```yaml +credentials: + # Basic password + - name: admin_password + description: Administrator password + + # With constraints + - name: api_key + description: API authentication key + length: 32 + fixed: true # Don't rotate + + # With character set + - name: db_password + description: Database password + length: 20 + allowed_chars: "a-zA-Z0-9" +``` + +#### certificates +**Required**: No +**Type**: Array of certificate definitions +**Description**: X.509 certificate definitions. + +```yaml +certificates: + # Basic certificate + - name: server + description: Server TLS certificate + + # With components + - name: ca + description: Certificate Authority + self_signed: true + + - name: server + description: Server certificate + signed_by: ca + common_name: "*.example.com" + alternative_names: + - "*.example.com" + - "10.0.0.5" + - "localhost" + + # With custom validity + - name: client + description: Client certificate + ttl: 90d # 90 days + signed_by: ca + + # With specific usage + - name: etcd-peer + description: etcd peer certificate + key_usage: + - digital_signature + - key_encipherment + extended_key_usage: + - server_auth + - client_auth +``` + +#### provided +**Required**: No +**Type**: Array of provided secret definitions +**Description**: Secrets that users must provide. + +```yaml +provided: + - name: ssl_cert + description: | + SSL certificate for external access. + Must include full certificate chain. + example: | + -----BEGIN CERTIFICATE----- + MIIDXTCCAkWgAwIBAgIJAKl... + -----END CERTIFICATE----- + + - name: slack_webhook + description: Slack webhook URL for notifications + example: https://hooks.slack.com/services/XXX/YYY/ZZZ +``` + +### Parameters + +#### params +**Required**: No +**Type**: Hash +**Description**: Default parameter values. + +```yaml +params: + # Simple defaults + instances: 1 + vm_type: default + + # Complex defaults + networks: + - name: default + static_ips: [] +``` + +### Subkits (Deprecated) + +The `subkits` section is deprecated in favor of `features`: + +```yaml +# Old format (deprecated) +subkits: + - name: ha + description: High availability + +# New format +features: + - name: ha + description: High availability +``` + +## Advanced Configuration + +### Conditional Features + +Features can have dependencies and conflicts: + +```yaml +features: + - name: ha + description: High availability (requires 3+ instances) + + - name: single-node + description: Single node deployment + conflicts: [ha] # Cannot use with HA + + - name: ssl + description: Enable SSL/TLS + + - name: mtls + description: Mutual TLS authentication + requires: [ssl] # Requires SSL feature +``` + +### Complex Secrets + +Advanced secret configurations: + +```yaml +credentials: + # User-provided with validation + - name: admin_password + description: Admin password + min_length: 12 + require_special: true + require_numeric: true + + # Generated with specific format + - name: session_key + description: Session encryption key + format: base64 + length: 32 + +certificates: + # CA with specific DN + - name: ca + description: Root CA + self_signed: true + ttl: 10y + subject: + C: US + ST: California + L: San Francisco + O: Example Corp + OU: IT Department + CN: Example Root CA + + # Server with IP SANs + - name: server + description: Server certificate + signed_by: ca + common_name: server.example.com + ip_sans: + - 10.0.0.5 + - 10.0.0.6 + dns_sans: + - server.example.com + - api.example.com +``` + +### Release Versions + +Complex version specifications: + +```yaml +releases: + # Latest from GitHub + - name: concourse + github: concourse/concourse-bosh-release + version: latest + + # Specific version with fallback + - name: postgres + version: "43" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=43 + sha1: abc123 + fallback: + version: "42" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=42 + sha1: def456 + + # Version range + - name: routing + version: ">=0.200.0 <1.0.0" +``` + +### Environment Types + +Kits can define environment types: + +```yaml +environment_types: + - name: development + features: + - single-node + params: + instances: 1 + + - name: production + features: + - ha + - ssl + - monitoring + params: + instances: 3 +``` + +### Deployment Parameters + +Control deployment behavior: + +```yaml +deployment: + # Canary settings + canaries: 1 + max_in_flight: 10 + canary_watch_time: 30000-600000 + update_watch_time: 30000-600000 + + # Serial deployment + serial: false + + # AZ configuration + availability_zones: + - z1 + - z2 + - z3 +``` + +## Validation Schema + +Genesis validates kit.yml against this schema: + +```yaml +type: map +mapping: + name: + type: str + required: true + authors: + type: seq + sequence: + - type: str + genesis_version_min: + type: str + pattern: /^\d+\.\d+\.\d+$/ + releases: + type: seq + sequence: + - type: map + mapping: + name: {type: str, required: true} + version: {type: str, required: true} + url: {type: str} + sha1: {type: str} + # ... etc +``` + +## Complete Example + +Comprehensive kit.yml example: + +```yaml +name: concourse +authors: + - Genesis Community + - Concourse Team +docs: https://concourse-ci.org +code: https://github.com/genesis-community/concourse-genesis-kit +description: | + Deploy Concourse CI/CD platform using Genesis + + Supports standalone and clustered deployments + with optional GitHub authentication. + +genesis_version_min: 2.8.0 + +releases: + - name: concourse + version: 7.8.3 + url: https://bosh.io/d/github.com/concourse/concourse-bosh-release?v=7.8.3 + sha1: abc123def456 + + - name: postgres + version: "43" + url: https://bosh.io/d/github.com/cloudfoundry/postgres-release?v=43 + sha1: 789ghi012jkl + + - name: bpm + version: 1.1.+ + + - name: routing + version: latest + +stemcells: + - alias: default + os: ubuntu-jammy + version: latest + +features: + - name: workers + description: | + Deploy external workers for job processing + + - name: github-oauth + description: | + Enable GitHub OAuth for authentication + + - name: prometheus + description: | + Export Prometheus metrics + + - name: vault + description: | + Use Vault for credential management + deprecated: true + +params: + # Instance configuration + instances: 1 + vm_type: default + network: concourse + disk_type: default + + # Concourse configuration + external_url: https://concourse.example.com + worker_count: 3 + +credentials: + - name: local_user_password + description: Password for local admin user + + - name: postgresql_password + description: PostgreSQL database password + length: 32 + + - name: token_signing_key + description: Key for signing auth tokens + format: rsa + bits: 4096 + +certificates: + - name: ca + description: Concourse CA certificate + self_signed: true + ttl: 10y + + - name: tls + description: Concourse web TLS certificate + signed_by: ca + ttl: 1y + common_name: concourse.example.com + alternative_names: + - "*.concourse.example.com" + - "127.0.0.1" + + - name: worker + description: Worker certificate + signed_by: ca + ttl: 90d + common_name: worker.concourse.internal + +provided: + - name: github_oauth_client_id + description: | + GitHub OAuth application client ID + Create at: https://github.com/settings/applications/new + example: "0123456789abcdef0123" + + - name: github_oauth_client_secret + description: | + GitHub OAuth application client secret + example: "0123456789abcdef0123456789abcdef01234567" + +deployment: + canaries: 1 + max_in_flight: 4 + canary_watch_time: 30000-600000 + update_watch_time: 30000-600000 + serial: false +``` + +## Best Practices + +1. **Version Constraints**: Always specify minimum Genesis version +2. **Descriptions**: Provide clear descriptions for all features and secrets +3. **Examples**: Include examples for provided secrets +4. **Deprecation**: Mark deprecated features clearly +5. **Documentation**: Link to comprehensive documentation +6. **Validation**: Test kit.yml with `genesis compile-kit` + +The kit.yml file is the heart of a Genesis kit, defining its capabilities, requirements, and configuration options. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/manifest-operators.md b/lib/Genesis/Help/Topics/90-reference-guides/manifest-operators.md new file mode 100644 index 00000000..93eaf615 --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/manifest-operators.md @@ -0,0 +1,628 @@ +# Manifest Operators Reference + +This document provides a comprehensive reference for Spruce operators used in Genesis manifests. Spruce is the YAML merging tool that powers Genesis's hierarchical configuration system. + +## Overview + +Spruce operators are special directives enclosed in `(( ))` that perform operations during manifest generation. They enable dynamic values, references, conditionals, and complex data transformations. + +## Basic Operators + +### grab + +Retrieves values from elsewhere in the document. + +**Syntax**: `(( grab path.to.value ))` + +**Example**: +```yaml +meta: + domain: example.com + +params: + url: (( grab meta.domain )) + # Result: url: example.com +``` + +**With defaults**: +```yaml +params: + # Use default if not found + port: (( grab meta.port || 8080 )) + + # Multiple fallbacks + env: (( grab meta.environment || params.env || "development" )) +``` + +### concat + +Concatenates strings or arrays. + +**Syntax**: `(( concat arg1 arg2 ... ))` + +**String concatenation**: +```yaml +meta: + domain: example.com + env: prod + +params: + # Result: "https://prod.example.com" + url: (( concat "https://" meta.env "." meta.domain )) + + # With separator + fqdn: (( join "." meta.env meta.domain )) +``` + +**Array concatenation**: +```yaml +base_features: + - dns + - ntp + +params: + features: (( concat base_features "[\"monitoring\"]" )) + # Result: [dns, ntp, monitoring] +``` + +### vault + +Retrieves secrets from Vault. + +**Syntax**: `(( vault "path:key" ))` + +**Examples**: +```yaml +params: + # Simple secret + password: (( vault "secret/prod/admin:password" )) + + # With path construction + api_key: (( vault meta.vault "/api:key" )) + + # Using environment variable + db_pass: (( vault $GENESIS_SECRETS_PATH "/database:password" )) +``` + +### static_ips + +Generates static IPs from network definitions. + +**Syntax**: `(( static_ips INTEGER ... ))` + +**Example**: +```yaml +networks: + - name: default + static: [10.0.0.5 - 10.0.0.100] + +instance_groups: + - name: web + instances: 3 + networks: + - name: default + static_ips: (( static_ips 0 1 2 )) + # Result: [10.0.0.5, 10.0.0.6, 10.0.0.7] +``` + +## Reference Operators + +### meta + +References to the `meta` section (common pattern in Genesis). + +```yaml +meta: + az: [z1, z2, z3] + network: default + +instance_groups: + - name: web + azs: (( grab meta.az )) + networks: + - name: (( grab meta.network )) +``` + +### params + +References to the `params` section (user parameters). + +```yaml +params: + base_domain: example.com + instances: 3 + +instance_groups: + - name: web + instances: (( grab params.instances )) + +properties: + domain: (( grab params.base_domain )) +``` + +### self-reference + +Reference current level using `.`: + +```yaml +server: + host: example.com + port: 443 + url: (( concat "https://" .host ":" .port )) + # Result: "https://example.com:443" +``` + +## Conditional Operators + +### Ternary operator + +Conditional selection based on boolean. + +**Syntax**: `(( condition ? true_value : false_value ))` + +**Examples**: +```yaml +meta: + production: true + +params: + # Simple conditional + instances: (( meta.production ? 3 : 1 )) + + # Nested conditionals + vm_type: (( grab meta.scale || "small" == "large" ? "n1-highmem-8" : "n1-standard-2" )) +``` + +### Logical operators + +Boolean operations for conditions. + +```yaml +meta: + ha_enabled: true + instances: 3 + +params: + # AND operator + use_ha: (( meta.ha_enabled && meta.instances >= 3 )) + + # OR operator + enable_monitoring: (( grab meta.monitoring || meta.production )) + + # NOT operator + skip_backups: (( !meta.production )) +``` + +## Array Operators + +### join + +Joins array elements into a string. + +**Syntax**: `(( join SEPARATOR ARRAY ))` + +```yaml +meta: + domains: + - api + - www + - admin + +params: + # Result: "api,www,admin" + domain_list: (( join "," meta.domains )) + + # Result: "api.example.com www.example.com admin.example.com" + fqdns: (( join " " meta.domains ".example.com" )) +``` + +### elem + +Extracts element from array by index. + +**Syntax**: `(( elem INDEX ARRAY ))` + +```yaml +meta: + azs: [us-east-1a, us-east-1b, us-east-1c] + +params: + # Result: "us-east-1b" + primary_az: (( elem 1 meta.azs )) +``` + +### append + +Appends to arrays (used with merge). + +```yaml +# base.yml +features: + - dns + - ntp + +# overlay.yml +features: + - (( append )) + - monitoring + - logging +# Result: [dns, ntp, monitoring, logging] +``` + +### replace + +Replaces entire structure. + +```yaml +# base.yml +databases: + - name: postgres + port: 5432 + +# overlay.yml +databases: (( replace )) + - name: mysql + port: 3306 +# Result: only mysql, postgres removed +``` + +### inline + +Merges array elements inline. + +```yaml +# base.yml +jobs: + - name: web + templates: [nginx] + +# overlay.yml +jobs: + - (( inline )) + - name: web + templates: + - (( append )) + - php-fpm +# Result: web job with [nginx, php-fpm] +``` + +## Map/Object Operators + +### keys + +Extracts keys from a map. + +**Syntax**: `(( keys MAP ))` + +```yaml +services: + web: + port: 80 + api: + port: 8080 + db: + port: 5432 + +service_names: (( keys services )) +# Result: [web, api, db] +``` + +### values + +Extracts values from a map. + +**Syntax**: `(( values MAP ))` + +```yaml +services: + web: 80 + api: 8080 + db: 5432 + +ports: (( values services )) +# Result: [80, 8080, 5432] +``` + +## String Operators + +### base64 + +Base64 encodes a string. + +**Syntax**: `(( base64 STRING ))` + +```yaml +params: + encoded_password: (( base64 "my-secret-password" )) + # Result: "bXktc2VjcmV0LXBhc3N3b3Jk" +``` + +### sha1/sha256 + +Generates hash of string. + +```yaml +params: + password_hash: (( sha256 "password" )) + file_checksum: (( sha1 meta.file_contents )) +``` + +### regexp + +Regular expression matching and replacement. + +**Syntax**: `(( regexp PATTERN REPLACEMENT STRING ))` + +```yaml +meta: + version: "v1.2.3" + +params: + # Remove 'v' prefix + clean_version: (( regexp "^v" "" meta.version )) + # Result: "1.2.3" + + # Extract major version + major: (( regexp "^v?([0-9]+)\\..*" "$1" meta.version )) + # Result: "1" +``` + +## Special Operators + +### inject + +Injects sub-documents. + +**Syntax**: `(( inject FILE ))` + +```yaml +# main.yml +base_config: (( inject "configs/base.yml" )) + +overrides: + <<: (( inject "configs/overrides.yml" )) +``` + +### file + +Reads file contents as string. + +**Syntax**: `(( file PATH ))` + +```yaml +params: + certificate: (( file "certs/server.crt" )) + config_data: (( file "/etc/app/config.json" )) +``` + +### env + +Accesses environment variables. + +**Syntax**: `(( env "VARIABLE" ))` + +```yaml +params: + home_dir: (( env "HOME" )) + deployment: (( env "GENESIS_ENVIRONMENT" )) + + # With default + log_level: (( env "LOG_LEVEL" || "info" )) +``` + +### null + +Represents null/nil value. + +```yaml +params: + # Remove inherited value + unwanted_param: (( null )) + + # Conditional null + optional: (( meta.enabled ? meta.value : null )) +``` + +## Advanced Patterns + +### Pipeline Operations + +Chain multiple operations: + +```yaml +meta: + raw_domains: + - " api.example.com " + - " www.example.com " + +params: + # Trim whitespace and join + domains: (( join "," ( map regexp "^\\s+|\\s+$" "" meta.raw_domains ) )) +``` + +### Complex Conditionals + +Multi-condition logic: + +```yaml +meta: + env: production + region: us-east + ha_enabled: true + +params: + instances: (( + meta.env == "production" && meta.ha_enabled ? 5 : + meta.env == "production" ? 3 : + meta.env == "staging" ? 2 : + 1 + )) +``` + +### Dynamic Key Names + +Generate keys dynamically: + +```yaml +meta: + env: prod + region: us-east-1 + +params: + (( concat meta.env "-config" )): + region: (( grab meta.region )) + # Result: prod-config: { region: us-east-1 } +``` + +### Nested Grabs + +Navigate complex structures: + +```yaml +meta: + environments: + prod: + us-east: + instances: 5 + us-west: + instances: 3 + +params: + count: (( grab meta.environments.prod.us-east.instances )) +``` + +## Error Handling + +### Default Values + +Always provide defaults for optional values: + +```yaml +params: + # Single default + port: (( grab meta.port || 8080 )) + + # Chain of defaults + environment: (( grab meta.env || params.env || "development" )) + + # Complex default + config: (( grab meta.config || { "timeout": 30, "retries": 3 } )) +``` + +### Type Safety + +Ensure correct types in operations: + +```yaml +# BAD: May cause type errors +total: (( grab meta.count + 1 )) + +# GOOD: Ensure numeric default +total: (( ( grab meta.count || 0 ) + 1 )) +``` + +### Existence Checks + +Check before using: + +```yaml +# Only add if exists +features: (( + has meta.optional_feature ? + concat base_features "[\"" meta.optional_feature "\"]" : + base_features +)) +``` + +## Best Practices + +### 1. Use Descriptive Paths + +```yaml +# BAD +value: (( grab m.d )) + +# GOOD +value: (( grab meta.deployment.domain )) +``` + +### 2. Provide Meaningful Defaults + +```yaml +# BAD +port: (( grab params.port || 0 )) + +# GOOD +port: (( grab params.port || 8080 )) # Default HTTP port +``` + +### 3. Group Related Operations + +```yaml +meta: + # Group related calculations + sizing: + base_instances: 3 + ha_multiplier: (( grab params.ha_enabled ? 3 : 1 )) + total_instances: (( meta.sizing.base_instances * meta.sizing.ha_multiplier )) +``` + +### 4. Document Complex Operations + +```yaml +params: + # Calculate required IPs: instances + 2 (for load balancers) + # Must account for multiple AZs in HA mode + required_ips: (( + ( grab params.instances || 1 ) + + 2 + + ( grab params.ha_enabled ? length(meta.azs) : 0 ) + )) +``` + +### 5. Avoid Deep Nesting + +```yaml +# BAD: Hard to read and maintain +value: (( grab meta.config.services.web.endpoints.primary.port || grab meta.defaults.services.web.port || 80 )) + +# GOOD: Use intermediate values +meta: + web_config: (( grab meta.config.services.web || {} )) + web_endpoint: (( grab meta.web_config.endpoints.primary || {} )) + +params: + web_port: (( grab meta.web_endpoint.port || 80 )) +``` + +## Common Pitfalls + +### 1. Circular References + +```yaml +# BAD: Causes infinite loop +a: (( grab b )) +b: (( grab a )) +``` + +### 2. Type Mismatches + +```yaml +# BAD: Concatenating different types +result: (( concat meta.string meta.number )) + +# GOOD: Convert to string first +result: (( concat meta.string ( string meta.number ) )) +``` + +### 3. Missing Defaults + +```yaml +# BAD: Fails if meta.value not present +calculation: (( grab meta.value * 2 )) + +# GOOD: Provide default +calculation: (( ( grab meta.value || 1 ) * 2 )) +``` + +Understanding Spruce operators is essential for creating flexible and maintainable Genesis deployments. These operators provide the power to create sophisticated configuration templates while maintaining clarity and reusability. \ No newline at end of file diff --git a/lib/Genesis/Help/Topics/90-reference-guides/runtime-configs.md b/lib/Genesis/Help/Topics/90-reference-guides/runtime-configs.md new file mode 100644 index 00000000..dababdcc --- /dev/null +++ b/lib/Genesis/Help/Topics/90-reference-guides/runtime-configs.md @@ -0,0 +1,636 @@ +# Runtime Configs Reference + +This document provides a comprehensive reference for specifying and managing BOSH runtime configurations in Genesis environment files. + +## Overview + +Runtime configs are BOSH configurations that apply to all deployments on a BOSH director. Genesis kits can provide runtime config hooks that generate these configurations based on your environment settings, allowing you to standardize operational concerns across all deployments. + +## Configuration Location + +Runtime config options are specified under the `bosh-configs` top-level key in your environment file: + +```yaml +# my-env.yml +bosh-configs: + runtime: + # Runtime config specifications +``` + +## Specification Formats + +Genesis supports multiple formats for specifying runtime configs, from simple boolean flags to complex configurations with options. + +### 1. Boolean Format + +Enable all available runtime configs with default options: + +```yaml +bosh-configs: + runtime: true +``` + +This enables all runtime configs defined by the kit with their default settings. + +### 2. String Format (Single Config) + +Request a specific runtime config by name: + +```yaml +bosh-configs: + runtime: "dns" +``` + +Only the specified runtime config will be generated. + +### 3. Comma-Separated String (Multiple Configs) + +Request multiple runtime configs in a single string: + +```yaml +bosh-configs: + runtime: "dns,toolbelt,monitoring" +``` + +Each named config will be generated with default options. + +### 4. Array Format + +List multiple runtime configs using YAML array syntax: + +```yaml +bosh-configs: + runtime: + - dns + - toolbelt + - monitoring + - security +``` + +### 5. Hash Format (Configs with Options) + +Specify runtime configs with custom options: + +```yaml +bosh-configs: + runtime: + dns: + timeout: 30 + retries: 3 + cache_size: 1000 + security: + enforce_tls: true + audit_logging: enabled + monitoring: true # Use defaults + toolbelt: + packages: + - htop + - tmux + - vim +``` + +### 6. Mixed Configurations + +Combine different specification methods for flexibility: + +```yaml +bosh-configs: + runtime: + # Apply shared options to all configs + "*": + environment: production + region: us-east-1 + + # Config-specific options + dns: + timeout: 30 + upstream_dns: + - 8.8.8.8 + - 8.8.4.4 + + # Exclude specific config + legacy: false + + # Enable with defaults + monitoring: true +``` + +## Advanced Configuration + +### Wildcard Selection + +Use `*` to apply options to all available runtime configs: + +```yaml +bosh-configs: + runtime: + "*": + environment: production + datacenter: us-east-1 + contact: ops-team@example.com +``` + +### Excluding Configs + +Explicitly exclude specific runtime configs: + +```yaml +bosh-configs: + runtime: + "*": true # Enable all configs + legacy: false # Except legacy + experimental: false # And experimental +``` + +When only exclusions are specified, all other configs are enabled by default: + +```yaml +bosh-configs: + runtime: + # All configs enabled except these + legacy: false + deprecated: false +``` + +### Grouped Configuration + +Apply shared options to multiple configs: + +```yaml +bosh-configs: + runtime: + # Group configs with comma-separated names + "dns,security,monitoring": + environment: production + log_level: info + + # Additional config-specific options + dns: + cache_size: 2000 + security: + strict_mode: true +``` + +## Common Runtime Config Types + +### DNS Configuration + +Modern BOSH DNS setup: + +```yaml +bosh-configs: + runtime: + dns: + # DNS-specific options + cache: + enabled: true + max_entries: 10000 + health_check: + enabled: true + interval: 30 + handlers: + - domain: consul.local + forward: 10.0.0.10 +``` + +### Monitoring Configuration + +Prometheus node exporter and monitoring agents: + +```yaml +bosh-configs: + runtime: + monitoring: + node_exporter: + enabled: true + port: 9100 + collectors: + - cpu + - memory + - disk + - network + telegraf: + enabled: true + outputs: + - influxdb: "http://metrics.example.com:8086" +``` + +### Security Configuration + +OS hardening and security tools: + +```yaml +bosh-configs: + runtime: + security: + sysctl: + kernel_hardening: true + network_hardening: true + login_banner: + enabled: true + text: | + AUTHORIZED ACCESS ONLY + All activity is monitored + fail2ban: + enabled: true + max_retries: 3 +``` + +### Toolbelt Configuration + +Development and debugging tools: + +```yaml +bosh-configs: + runtime: + toolbelt: + packages: + - vim + - tmux + - htop + - tcpdump + - strace + custom_scripts: + enabled: true + path: /var/vcap/toolbelt/scripts +``` + +### Logging Configuration + +Centralized logging setup: + +```yaml +bosh-configs: + runtime: + logging: + syslog: + enabled: true + address: syslog.example.com + port: 514 + protocol: tcp + tls: + enabled: true + verify: true + format: rfc5424 + include_audit_logs: true +``` + +## Kit Integration + +### Kit-Defined Runtime Configs + +Kits define available runtime configs in their metadata: + +```yaml +# kit.yml +runtime_configs: + - name: dns + description: "BOSH DNS configuration" + default: true + - name: monitoring + description: "Prometheus monitoring agents" + default: false + - name: security + description: "OS hardening and security policies" + default: true +``` + +### Runtime Config Hooks + +Kits implement runtime config generation through hooks: + +```bash +# hooks/runtime-config +#!/bin/bash +set -eu + +config_type=$1 +shift + +case "$config_type" in + dns) + generate_dns_runtime_config "$@" + ;; + monitoring) + generate_monitoring_runtime_config "$@" + ;; + security) + generate_security_runtime_config "$@" + ;; + *) + echo >&2 "Unknown runtime config: $config_type" + exit 1 + ;; +esac +``` + +## Environment-Specific Overrides + +### Development Environment + +Minimal runtime configs for development: + +```yaml +# dev.yml +bosh-configs: + runtime: + dns: true # Only DNS + # All others disabled by default +``` + +### Production Environment + +Full runtime configs with strict settings: + +```yaml +# prod.yml +bosh-configs: + runtime: + "*": + environment: production + alert_email: ops@example.com + dns: + cache_size: 50000 + strict_mode: true + security: + enforce_tls: true + audit_all: true + compliance_mode: pci + monitoring: + retention: 90d + high_frequency: true + logging: + archive: true + compress: true +``` + +## Best Practices + +### 1. Hierarchical Configuration + +Use environment hierarchy for runtime configs: + +```yaml +# base.yml - Shared configs +bosh-configs: + runtime: + dns: true + monitoring: true + +# prod.yml - Production additions +bosh-configs: + runtime: + security: + strict_mode: true + logging: + archive: true +``` + +### 2. Document Options + +Include comments explaining options: + +```yaml +bosh-configs: + runtime: + dns: + # Increased cache for high-traffic environment + cache_size: 50000 + + # Custom upstream for internal domains + handlers: + - domain: internal.company.com + forward: 10.0.0.100 +``` + +### 3. Validate Compatibility + +Ensure runtime configs are compatible: + +```yaml +bosh-configs: + runtime: + # These work together + monitoring: true + logging: true + + # But not with this (example) + legacy_monitoring: false +``` + +### 4. Use Defaults Wisely + +Leverage kit defaults when appropriate: + +```yaml +bosh-configs: + runtime: + # Use all kit defaults + "*": true + + # Except customize DNS + dns: + cache_size: 20000 +``` + +## Troubleshooting + +### Runtime Config Not Applied + +Check if config is generated: + +```bash +# List runtime configs +genesis do my-env -- list-runtime-configs + +# View generated config +genesis do my-env -- runtime-config dns +``` + +### Option Not Recognized + +Runtime config hooks should gracefully handle unknown options: + +```yaml +bosh-configs: + runtime: + dns: + unknown_option: value # Should be ignored, not error +``` + +### Conflicts Between Configs + +Some runtime configs may conflict: + +```yaml +bosh-configs: + runtime: + # Error: Both provide syslog forwarding + logging: true + legacy_syslog: true +``` + +## Migration Examples + +### From Manual Runtime Configs + +Migrating from manually managed runtime configs: + +```bash +# Export current runtime config +bosh runtime-config > current-runtime.yml + +# Analyze and map to Genesis options +# Add to environment file: +bosh-configs: + runtime: + dns: + # Options matching current-runtime.yml +``` + +### Upgrading Runtime Configs + +When upgrading kits with new runtime configs: + +```yaml +# Before upgrade - explicit list +bosh-configs: + runtime: + - dns + - monitoring + +# After upgrade - use new configs +bosh-configs: + runtime: + - dns + - monitoring + - security # New in kit v2.0 +``` + +## Complete Example + +Comprehensive runtime config setup: + +```yaml +# production.yml +genesis: + env: production + +bosh-configs: + runtime: + # Global options for all configs + "*": + environment: production + region: us-east-1 + owner: platform-team + + # DNS with production settings + dns: + cache: + enabled: true + size: 100000 + ttl: 300 + recursors: + - 8.8.8.8 + - 8.8.4.4 + handlers: + - domain: consul.service.consul + forward: 127.0.0.1:8600 + - domain: internal.company.com + forward: 10.0.0.53 + + # Comprehensive monitoring + monitoring: + node_exporter: + enabled: true + port: 9100 + prometheus: + scrape_interval: 15s + external_labels: + environment: production + region: us-east-1 + telegraf: + enabled: true + interval: 10s + outputs: + - influxdb: "https://metrics.company.com:8086" + + # Strict security settings + security: + os_hardening: + kernel: true + network: true + filesystem: true + compliance: + mode: pci-dss + audit_level: detailed + tls: + min_version: "1.2" + cipher_suites: modern + + # Centralized logging + logging: + syslog: + address: syslog-aggregator.company.com + port: 6514 + protocol: tcp + tls: + enabled: true + verify: true + format: json + buffer_size: 65536 + include: + - system + - audit + - application + + # Exclude development tools + toolbelt: false +``` + +## Future Enhancements + +### Cross-Kit Runtime Configs + +Future versions may support specifying runtime configs from other kits: + +```yaml +bosh-configs: + runtime: + # From BOSH kit + dns: true + + # From Shield kit + "shield/backup-agent": + schedule: "0 2 * * *" + + # From Prometheus kit + "prometheus/exporters": + - node + - process + - postgres +``` + +### Runtime Config Dependencies + +Automatic dependency resolution: + +```yaml +bosh-configs: + runtime: + monitoring: true # Automatically enables dns if required +``` + +### Conditional Runtime Configs + +Environment-aware configurations: + +```yaml +bosh-configs: + runtime: + monitoring: + enabled: (( grab meta.monitoring_enabled || false )) + endpoint: (( concat "https://prometheus." params.base_domain ":9090" )) +``` + +Runtime configurations provide powerful cross-cutting functionality for all deployments while maintaining flexibility through Genesis's configuration system. \ No newline at end of file diff --git a/lib/Genesis/HelpTopics.pm b/lib/Genesis/HelpTopics.pm new file mode 100644 index 00000000..852bcd0a --- /dev/null +++ b/lib/Genesis/HelpTopics.pm @@ -0,0 +1,258 @@ +package Genesis::HelpTopics; +use strict; +use warnings; + +use Genesis qw/info output error bail debug trace/; +use Genesis::Term qw/render_markdown terminal_width wrap/; +use File::Find; +use File::Spec; +use File::Basename; + +use base 'Exporter'; +our @EXPORT = qw/ + list_help_topics + show_help_topic + is_help_topic + get_topic_content +/; + +# Base path for help topics +sub help_topics_path { + my $base = $ENV{GENESIS_LIB} || File::Spec->catdir(dirname($INC{'Genesis.pm'})); + return File::Spec->catdir($base, 'Genesis', 'Help', 'Topics'); +} + +# List all available help topics +sub list_help_topics { + my $topics_dir = help_topics_path(); + + unless (-d $topics_dir) { + error "Help topics directory not found at $topics_dir"; + return; + } + + my @topics; + opendir(my $dh, $topics_dir) or bail "Cannot open help topics directory: $!"; + + while (my $entry = readdir($dh)) { + next if $entry =~ /^\./; # Skip hidden files + next unless -d File::Spec->catdir($topics_dir, $entry); + + # Parse topic directory name + my ($order, $name) = $entry =~ /^(\d+)-(.+)$/ ? ($1, $2) : (999, $entry); + + # Read topic metadata from index.md + my $index_file = File::Spec->catfile($topics_dir, $entry, 'index.md'); + my $title = $name; + my $description = ''; + + if (-f $index_file) { + if (open my $fh, '<', $index_file) { + my $first_line = 1; + while (my $line = <$fh>) { + if ($first_line && $line =~ /^#\s+(.+)/) { + $title = $1; + $first_line = 0; + } elsif ($line =~ /\S/ && $line !~ /^#/) { + $description = $line; + chomp $description; + last; + } + } + close $fh; + } + } + + push @topics, { + dir => $entry, + name => $name, + title => $title, + description => $description, + order => $order + }; + } + closedir($dh); + + # Sort by order number + @topics = sort { $a->{order} <=> $b->{order} } @topics; + + # Display topics list + my $width = terminal_width(); + + output "#G{Genesis Help Topics}\n"; + output "=" x $width . "\n\n"; + + for my $topic (@topics) { + my $header = sprintf("#C{%-20s} #G{%s}", $topic->{name}, $topic->{title}); + output wrap($header, $width, '', 22) . "\n"; + + if ($topic->{description}) { + output wrap($topic->{description}, $width, ' ' x 22, 22) . "\n"; + } + output "\n"; + } + + output wrap( + "Use '#C{genesis help }' to view a topic, or '#C{genesis help /}' " . + "for a specific subtopic.", + $width + ) . "\n"; +} + +# Check if a given string is a help topic +sub is_help_topic { + my ($topic) = @_; + + # Special case for 'topics' command + return 0 if $topic eq 'topics'; + + # Check if it's a command first + return 0 if defined($Genesis::Commands::GENESIS_COMMANDS{$topic}); + + # Check if topic directory exists + my $topics_dir = help_topics_path(); + return 0 unless -d $topics_dir; + + # Handle topic/subtopic format + my ($main_topic, $subtopic) = split('/', $topic, 2); + + # Find matching topic directory + my $dh; + unless (opendir($dh, $topics_dir)) { + debug "Cannot open help topics directory: $!"; + return 0; + } + + my $found = 0; + while (my $entry = readdir($dh)) { + next if $entry =~ /^\./; + next unless -d File::Spec->catdir($topics_dir, $entry); + + my ($order, $name) = $entry =~ /^(\d+)-(.+)$/ ? ($1, $2) : (999, $entry); + if ($name eq $main_topic) { + # If no subtopic, topic exists + unless (defined $subtopic) { + $found = 1; + last; + } + + # Check if subtopic file exists + my $subtopic_file = File::Spec->catfile($topics_dir, $entry, "$subtopic.md"); + if (-f $subtopic_file) { + $found = 1; + last; + } + } + } + closedir($dh); + + return $found; +} + +# Get the content of a help topic +sub get_topic_content { + my ($topic) = @_; + + my $topics_dir = help_topics_path(); + my ($main_topic, $subtopic) = split('/', $topic, 2); + + # Find the topic directory + my $topic_dir; + opendir(my $dh, $topics_dir) or bail "Cannot open help topics directory: $!"; + while (my $entry = readdir($dh)) { + next if $entry =~ /^\./; + next unless -d File::Spec->catdir($topics_dir, $entry); + + my ($order, $name) = $entry =~ /^(\d+)-(.+)$/ ? ($1, $2) : (999, $entry); + if ($name eq $main_topic) { + $topic_dir = File::Spec->catdir($topics_dir, $entry); + last; + } + } + closedir($dh); + + unless ($topic_dir) { + error "Help topic '#C{$main_topic}' not found"; + return undef; + } + + # Determine which file to read + my $file = $subtopic + ? File::Spec->catfile($topic_dir, "$subtopic.md") + : File::Spec->catfile($topic_dir, "index.md"); + + unless (-f $file) { + if ($subtopic) { + error "Subtopic '#C{$subtopic}' not found in topic '#C{$main_topic}'"; + } else { + error "Index file not found for topic '#C{$main_topic}'"; + } + return undef; + } + + # Read the file + open my $fh, '<', $file or bail "Cannot read help file: $!"; + my $content = do { local $/; <$fh> }; + close $fh; + + return $content; +} + +# Show a help topic +sub show_help_topic { + my ($topic) = @_; + + my $content = get_topic_content($topic); + return unless defined $content; + + # Add navigation breadcrumb + my ($main_topic, $subtopic) = split('/', $topic, 2); + my $breadcrumb = $subtopic + ? "#K{Help} > #K{$main_topic} > #K{$subtopic}" + : "#K{Help} > #K{$main_topic}"; + + output "$breadcrumb\n"; + output "#K{" . ("─" x terminal_width()) . "}\n\n"; + + # Render the markdown content + output render_markdown($content); + + # Add footer navigation + output "\n#K{" . ("─" x terminal_width()) . "}\n"; + if ($subtopic) { + output "See also: #C{genesis help $main_topic} (topic index)\n"; + } + output "For all topics: #C{genesis help topics}\n"; +} + +1; + +=head1 NAME + +Genesis::HelpTopics - Help topic system for Genesis + +=head1 DESCRIPTION + +This module provides the help topic system for Genesis, allowing users to +browse comprehensive documentation organized by topic. + +=head1 FUNCTIONS + +=head2 list_help_topics() + +Lists all available help topics with their descriptions. + +=head2 show_help_topic($topic) + +Displays the content of a specific help topic. Topics can be specified as +"topic" for the index or "topic/subtopic" for specific pages. + +=head2 is_help_topic($topic) + +Returns true if the given string corresponds to a valid help topic. + +=head2 get_topic_content($topic) + +Returns the raw content of a help topic file, or undef if not found. + +=cut \ No newline at end of file