From 798d8c459dd97adc6c44c77fca5d8ef7d2e51e48 Mon Sep 17 00:00:00 2001 From: "Dennis J. Bell" Date: Tue, 1 Jul 2025 16:10:35 -0700 Subject: [PATCH 1/2] WIP: Adding support for extended help topics Add docs/topics/ directory structure to provide comprehensive markdown documentation beyond basic CLI usage. This enables users to access detailed guides and examples for complex workflows through organized topic directories. Refactor help command implementation by moving logic from bin/genesis inline code to Genesis::Commands::Core::help() method for better maintainability and extensibility. Changes include: - New docs/topics/ with categorized subdirectories: * 00-getting-started/ - Initial setup guides * 10-environments/ - Environment file management * 30-secrets-management/ - Secrets handling * 50-kits/ - Kit access, usage and development * 60-bosh/ - BOSH integration topics * 70-troubleshooting/ - Debug and problem solving * 90-reference-guides/ - Technical references - Help command now supports new options: * --list-topics/-l: List available help topics * --topic/-t : Show specific topic help * --command/-c : Show specific command help - Removed GENESIS_COMMAND environment variable assignment from bin/genesis main loop, now handled in prepare_command() Users can access extended documentation through: genesis help --list-topics genesis help --topic Topic markdown files should be placed in appropriate docs/topics/ subdirectories for automatic discovery, and should be named using .md. Genesis will detect and format them into title-case for presentation. --- bin/genesis | 41 ++++++------------------- docs/topics/.keep | 0 docs/topics/00-getting-started/.keep | 0 docs/topics/10-environments/.keep | 0 docs/topics/30-secrets-management/.keep | 0 docs/topics/50-kits/.keep | 0 docs/topics/60-bosh/.keep | 0 docs/topics/70-troubleshooting/.keep | 0 docs/topics/90-reference-guides/.keep | 0 lib/Genesis/Commands.pm | 21 +++++++------ lib/Genesis/Commands/Core.pm | 33 +++++++++++++++++++- 11 files changed, 53 insertions(+), 42 deletions(-) create mode 100644 docs/topics/.keep create mode 100644 docs/topics/00-getting-started/.keep create mode 100644 docs/topics/10-environments/.keep create mode 100644 docs/topics/30-secrets-management/.keep create mode 100644 docs/topics/50-kits/.keep create mode 100644 docs/topics/60-bosh/.keep create mode 100644 docs/topics/70-troubleshooting/.keep create mode 100644 docs/topics/90-reference-guides/.keep 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/10-environments/.keep b/docs/topics/10-environments/.keep new file mode 100644 index 00000000..e69de29b 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/50-kits/.keep b/docs/topics/50-kits/.keep new file mode 100644 index 00000000..e69de29b 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/70-troubleshooting/.keep b/docs/topics/70-troubleshooting/.keep new file mode 100644 index 00000000..e69de29b 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/lib/Genesis/Commands.pm b/lib/Genesis/Commands.pm index ecb1ae37..ac370cfd 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 { @@ -552,10 +553,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 +673,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 +714,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..21a70b2f 100644 --- a/lib/Genesis/Commands/Core.pm +++ b/lib/Genesis/Commands/Core.pm @@ -193,6 +193,37 @@ 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 (@_) { + # 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(); + } +} + sub hack { my ($cmd, @args) = @_; @@ -283,7 +314,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; } From f6872f79551d7c05329186fb91922acb4b856df8 Mon Sep 17 00:00:00 2001 From: "Wayne E. Seguin" Date: Sun, 6 Jul 2025 06:38:14 -0400 Subject: [PATCH 2/2] Add help topics docs to Genesis CLI This commit introduces an extensive help topics system that provides in-depth documentation directly accessible through the Genesis CLI, going beyond basic command usage to cover concepts, best practices, and detailed guides. - **Help Topics Command**: `genesis help topics` lists all available documentation topics - **Topic Viewing**: `genesis help ` displays topic index with subtopics - **Subtopic Navigation**: `genesis help /` shows specific guides - **Markdown Rendering**: Full markdown support with proper formatting in terminal Created 53 documentation files organized into 7 main categories: 1. **Getting Started** (00-getting-started/) - Introduction to Genesis concepts - Installation guide - Basic configuration - First deployment walkthrough - Core concepts explained - Next steps guidance 2. **Environment Management** (10-environments/) - Naming conventions and hierarchical structure - Configuration file organization - BOSH integration details - Vault path management - Match mode operations - Best practices for production 3. **Secrets Management** (30-secrets-management/) - Vault and CredHub integration - Secret types and generation - Rotation procedures - Manual secret management - Security best practices 4. **Genesis Kits** (50-kits/) - Using existing kits - Authoring new kits - Hook development guide - Kit structure and features - Testing strategies - Available community kits 5. **BOSH Integration** (60-bosh/) - BOSH overview and concepts - Director management - Cloud and runtime configs - Stemcells and releases - Troubleshooting BOSH issues 6. **Troubleshooting** (70-troubleshooting/) - Common issues and solutions - Trace logging guide - Debugging deployments - Error message reference - Kit development problems 7. **Reference Guides** (90-reference-guides/) - Environment variables - Genesis configuration files - Hook reference - Manifest operators - Runtime configurations - **New Module**: `lib/Genesis/HelpTopics.pm` handles topic discovery and rendering - **Command Integration**: Modified `help()` in Commands/Core.pm to support topics - **General Help Update**: Added help topics mention in main help output - **Library Structure**: Topics stored in `lib/Genesis/Help/Topics/` for packaging - Proper error handling for missing topics - Breadcrumb navigation for context - Terminal width-aware rendering - Maintains backward compatibility with existing help system - Efficient topic discovery with numbered directory ordering This enhancement significantly improves the Genesis user experience by providing, easily accessible documentation without requiring external resources or internet access. --- docs/topics/00-getting-started/concepts.md | 212 ++++++ .../00-getting-started/configuration.md | 202 ++++++ .../00-getting-started/first-deployment.md | 252 +++++++ docs/topics/00-getting-started/index.md | 74 ++ .../topics/00-getting-started/installation.md | 223 ++++++ .../topics/00-getting-started/introduction.md | 86 +++ docs/topics/00-getting-started/next-steps.md | 210 ++++++ docs/topics/10-environments/best-practices.md | 462 ++++++++++++ .../10-environments/bosh-integration.md | 402 +++++++++++ .../10-environments/configuration-merging.md | 413 +++++++++++ docs/topics/10-environments/file-structure.md | 383 ++++++++++ docs/topics/10-environments/index.md | 104 +++ docs/topics/10-environments/match-mode.md | 362 ++++++++++ .../10-environments/naming-conventions.md | 273 +++++++ docs/topics/10-environments/reactions.md | 399 +++++++++++ docs/topics/10-environments/vault-paths.md | 361 ++++++++++ .../30-secrets-management/best-practices.md | 446 ++++++++++++ .../30-secrets-management/credhub-support.md | 453 ++++++++++++ docs/topics/30-secrets-management/index.md | 105 +++ .../30-secrets-management/kit-secrets.md | 478 +++++++++++++ .../manual-management.md | 456 ++++++++++++ docs/topics/30-secrets-management/overview.md | 243 +++++++ .../rotation-procedures.md | 463 ++++++++++++ .../30-secrets-management/secret-types.md | 434 ++++++++++++ .../vault-integration.md | 492 +++++++++++++ docs/topics/50-kits/authoring-kits.md | 599 ++++++++++++++++ docs/topics/50-kits/available-kits.md | 376 ++++++++++ docs/topics/50-kits/features.md | 544 ++++++++++++++ docs/topics/50-kits/index.md | 138 ++++ docs/topics/50-kits/kit-hooks.md | 514 ++++++++++++++ docs/topics/50-kits/kit-structure.md | 526 ++++++++++++++ docs/topics/50-kits/kit-testing.md | 516 ++++++++++++++ docs/topics/50-kits/overview.md | 292 ++++++++ docs/topics/50-kits/using-kits.md | 486 +++++++++++++ docs/topics/50-kits/writing-hooks.md | 526 ++++++++++++++ docs/topics/60-bosh/bosh-directors.md | 432 ++++++++++++ docs/topics/60-bosh/bosh-overview.md | 216 ++++++ docs/topics/60-bosh/bosh-troubleshooting.md | 526 ++++++++++++++ docs/topics/60-bosh/cloud-config.md | 512 ++++++++++++++ docs/topics/60-bosh/index.md | 32 + docs/topics/60-bosh/runtime-config.md | 533 ++++++++++++++ docs/topics/60-bosh/stemcells-releases.md | 471 +++++++++++++ docs/topics/60-bosh/working-with-bosh.md | 379 ++++++++++ .../70-troubleshooting/common-issues.md | 507 +++++++++++++ .../debugging-deployments.md | 444 ++++++++++++ .../70-troubleshooting/error-messages.md | 516 ++++++++++++++ docs/topics/70-troubleshooting/index.md | 57 ++ .../kit-development-issues.md | 527 ++++++++++++++ .../70-troubleshooting/manifest-debugging.md | 493 +++++++++++++ .../70-troubleshooting/secret-problems.md | 491 +++++++++++++ .../70-troubleshooting/trace-logging.md | 435 ++++++++++++ .../environment-variables.md | 596 ++++++++++++++++ .../genesis-configuration.md | 641 +++++++++++++++++ .../90-reference-guides/hook-reference.md | 667 ++++++++++++++++++ docs/topics/90-reference-guides/index.md | 29 + .../90-reference-guides/kit-configuration.md | 619 ++++++++++++++++ .../90-reference-guides/manifest-operators.md | 628 +++++++++++++++++ .../90-reference-guides/runtime-configs.md | 636 +++++++++++++++++ lib/Genesis/Commands.pm | 7 + lib/Genesis/Commands/Core.pm | 18 +- .../Help/Topics/00-getting-started/.keep | 0 .../Topics/00-getting-started/concepts.md | 212 ++++++ .../00-getting-started/configuration.md | 202 ++++++ .../00-getting-started/first-deployment.md | 252 +++++++ .../Help/Topics/00-getting-started/index.md | 74 ++ .../Topics/00-getting-started/installation.md | 223 ++++++ .../Topics/00-getting-started/introduction.md | 86 +++ .../Topics/00-getting-started/next-steps.md | 210 ++++++ lib/Genesis/Help/Topics/10-environments/.keep | 0 .../Topics/10-environments/best-practices.md | 462 ++++++++++++ .../10-environments/bosh-integration.md | 402 +++++++++++ .../10-environments/configuration-merging.md | 413 +++++++++++ .../Topics/10-environments/file-structure.md | 383 ++++++++++ .../Help/Topics/10-environments/index.md | 104 +++ .../Help/Topics/10-environments/match-mode.md | 362 ++++++++++ .../10-environments/naming-conventions.md | 273 +++++++ .../Help/Topics/10-environments/reactions.md | 399 +++++++++++ .../Topics/10-environments/vault-paths.md | 361 ++++++++++ .../Help/Topics/30-secrets-management/.keep | 0 .../30-secrets-management/best-practices.md | 446 ++++++++++++ .../30-secrets-management/credhub-support.md | 453 ++++++++++++ .../Topics/30-secrets-management/index.md | 105 +++ .../30-secrets-management/kit-secrets.md | 478 +++++++++++++ .../manual-management.md | 456 ++++++++++++ .../Topics/30-secrets-management/overview.md | 243 +++++++ .../rotation-procedures.md | 463 ++++++++++++ .../30-secrets-management/secret-types.md | 434 ++++++++++++ .../vault-integration.md | 492 +++++++++++++ lib/Genesis/Help/Topics/50-kits/.keep | 0 .../Help/Topics/50-kits/authoring-kits.md | 599 ++++++++++++++++ .../Help/Topics/50-kits/available-kits.md | 376 ++++++++++ lib/Genesis/Help/Topics/50-kits/features.md | 544 ++++++++++++++ lib/Genesis/Help/Topics/50-kits/index.md | 138 ++++ lib/Genesis/Help/Topics/50-kits/kit-hooks.md | 514 ++++++++++++++ .../Help/Topics/50-kits/kit-structure.md | 526 ++++++++++++++ .../Help/Topics/50-kits/kit-testing.md | 516 ++++++++++++++ lib/Genesis/Help/Topics/50-kits/overview.md | 292 ++++++++ lib/Genesis/Help/Topics/50-kits/using-kits.md | 486 +++++++++++++ .../Help/Topics/50-kits/writing-hooks.md | 526 ++++++++++++++ lib/Genesis/Help/Topics/60-bosh/.keep | 0 .../Help/Topics/60-bosh/bosh-directors.md | 432 ++++++++++++ .../Help/Topics/60-bosh/bosh-overview.md | 216 ++++++ .../Topics/60-bosh/bosh-troubleshooting.md | 526 ++++++++++++++ .../Help/Topics/60-bosh/cloud-config.md | 512 ++++++++++++++ lib/Genesis/Help/Topics/60-bosh/index.md | 32 + .../Help/Topics/60-bosh/runtime-config.md | 533 ++++++++++++++ .../Help/Topics/60-bosh/stemcells-releases.md | 471 +++++++++++++ .../Help/Topics/60-bosh/working-with-bosh.md | 379 ++++++++++ .../Help/Topics/70-troubleshooting/.keep | 0 .../70-troubleshooting/common-issues.md | 507 +++++++++++++ .../debugging-deployments.md | 444 ++++++++++++ .../70-troubleshooting/error-messages.md | 516 ++++++++++++++ .../Help/Topics/70-troubleshooting/index.md | 57 ++ .../kit-development-issues.md | 527 ++++++++++++++ .../70-troubleshooting/manifest-debugging.md | 493 +++++++++++++ .../70-troubleshooting/secret-problems.md | 491 +++++++++++++ .../70-troubleshooting/trace-logging.md | 435 ++++++++++++ .../Help/Topics/90-reference-guides/.keep | 0 .../environment-variables.md | 596 ++++++++++++++++ .../genesis-configuration.md | 641 +++++++++++++++++ .../90-reference-guides/hook-reference.md | 667 ++++++++++++++++++ .../Help/Topics/90-reference-guides/index.md | 29 + .../90-reference-guides/kit-configuration.md | 619 ++++++++++++++++ .../90-reference-guides/manifest-operators.md | 628 +++++++++++++++++ .../90-reference-guides/runtime-configs.md | 636 +++++++++++++++++ lib/Genesis/HelpTopics.pm | 258 +++++++ 126 files changed, 46064 insertions(+), 3 deletions(-) create mode 100644 docs/topics/00-getting-started/concepts.md create mode 100644 docs/topics/00-getting-started/configuration.md create mode 100644 docs/topics/00-getting-started/first-deployment.md create mode 100644 docs/topics/00-getting-started/index.md create mode 100644 docs/topics/00-getting-started/installation.md create mode 100644 docs/topics/00-getting-started/introduction.md create mode 100644 docs/topics/00-getting-started/next-steps.md create mode 100644 docs/topics/10-environments/best-practices.md create mode 100644 docs/topics/10-environments/bosh-integration.md create mode 100644 docs/topics/10-environments/configuration-merging.md create mode 100644 docs/topics/10-environments/file-structure.md create mode 100644 docs/topics/10-environments/index.md create mode 100644 docs/topics/10-environments/match-mode.md create mode 100644 docs/topics/10-environments/naming-conventions.md create mode 100644 docs/topics/10-environments/reactions.md create mode 100644 docs/topics/10-environments/vault-paths.md create mode 100644 docs/topics/30-secrets-management/best-practices.md create mode 100644 docs/topics/30-secrets-management/credhub-support.md create mode 100644 docs/topics/30-secrets-management/index.md create mode 100644 docs/topics/30-secrets-management/kit-secrets.md create mode 100644 docs/topics/30-secrets-management/manual-management.md create mode 100644 docs/topics/30-secrets-management/overview.md create mode 100644 docs/topics/30-secrets-management/rotation-procedures.md create mode 100644 docs/topics/30-secrets-management/secret-types.md create mode 100644 docs/topics/30-secrets-management/vault-integration.md create mode 100644 docs/topics/50-kits/authoring-kits.md create mode 100644 docs/topics/50-kits/available-kits.md create mode 100644 docs/topics/50-kits/features.md create mode 100644 docs/topics/50-kits/index.md create mode 100644 docs/topics/50-kits/kit-hooks.md create mode 100644 docs/topics/50-kits/kit-structure.md create mode 100644 docs/topics/50-kits/kit-testing.md create mode 100644 docs/topics/50-kits/overview.md create mode 100644 docs/topics/50-kits/using-kits.md create mode 100644 docs/topics/50-kits/writing-hooks.md create mode 100644 docs/topics/60-bosh/bosh-directors.md create mode 100644 docs/topics/60-bosh/bosh-overview.md create mode 100644 docs/topics/60-bosh/bosh-troubleshooting.md create mode 100644 docs/topics/60-bosh/cloud-config.md create mode 100644 docs/topics/60-bosh/index.md create mode 100644 docs/topics/60-bosh/runtime-config.md create mode 100644 docs/topics/60-bosh/stemcells-releases.md create mode 100644 docs/topics/60-bosh/working-with-bosh.md create mode 100644 docs/topics/70-troubleshooting/common-issues.md create mode 100644 docs/topics/70-troubleshooting/debugging-deployments.md create mode 100644 docs/topics/70-troubleshooting/error-messages.md create mode 100644 docs/topics/70-troubleshooting/index.md create mode 100644 docs/topics/70-troubleshooting/kit-development-issues.md create mode 100644 docs/topics/70-troubleshooting/manifest-debugging.md create mode 100644 docs/topics/70-troubleshooting/secret-problems.md create mode 100644 docs/topics/70-troubleshooting/trace-logging.md create mode 100644 docs/topics/90-reference-guides/environment-variables.md create mode 100644 docs/topics/90-reference-guides/genesis-configuration.md create mode 100644 docs/topics/90-reference-guides/hook-reference.md create mode 100644 docs/topics/90-reference-guides/index.md create mode 100644 docs/topics/90-reference-guides/kit-configuration.md create mode 100644 docs/topics/90-reference-guides/manifest-operators.md create mode 100644 docs/topics/90-reference-guides/runtime-configs.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/.keep create mode 100644 lib/Genesis/Help/Topics/00-getting-started/concepts.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/configuration.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/first-deployment.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/index.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/installation.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/introduction.md create mode 100644 lib/Genesis/Help/Topics/00-getting-started/next-steps.md create mode 100644 lib/Genesis/Help/Topics/10-environments/.keep create mode 100644 lib/Genesis/Help/Topics/10-environments/best-practices.md create mode 100644 lib/Genesis/Help/Topics/10-environments/bosh-integration.md create mode 100644 lib/Genesis/Help/Topics/10-environments/configuration-merging.md create mode 100644 lib/Genesis/Help/Topics/10-environments/file-structure.md create mode 100644 lib/Genesis/Help/Topics/10-environments/index.md create mode 100644 lib/Genesis/Help/Topics/10-environments/match-mode.md create mode 100644 lib/Genesis/Help/Topics/10-environments/naming-conventions.md create mode 100644 lib/Genesis/Help/Topics/10-environments/reactions.md create mode 100644 lib/Genesis/Help/Topics/10-environments/vault-paths.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/.keep create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/best-practices.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/credhub-support.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/index.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/kit-secrets.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/manual-management.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/overview.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/rotation-procedures.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/secret-types.md create mode 100644 lib/Genesis/Help/Topics/30-secrets-management/vault-integration.md create mode 100644 lib/Genesis/Help/Topics/50-kits/.keep create mode 100644 lib/Genesis/Help/Topics/50-kits/authoring-kits.md create mode 100644 lib/Genesis/Help/Topics/50-kits/available-kits.md create mode 100644 lib/Genesis/Help/Topics/50-kits/features.md create mode 100644 lib/Genesis/Help/Topics/50-kits/index.md create mode 100644 lib/Genesis/Help/Topics/50-kits/kit-hooks.md create mode 100644 lib/Genesis/Help/Topics/50-kits/kit-structure.md create mode 100644 lib/Genesis/Help/Topics/50-kits/kit-testing.md create mode 100644 lib/Genesis/Help/Topics/50-kits/overview.md create mode 100644 lib/Genesis/Help/Topics/50-kits/using-kits.md create mode 100644 lib/Genesis/Help/Topics/50-kits/writing-hooks.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/.keep create mode 100644 lib/Genesis/Help/Topics/60-bosh/bosh-directors.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/bosh-overview.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/bosh-troubleshooting.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/cloud-config.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/index.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/runtime-config.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/stemcells-releases.md create mode 100644 lib/Genesis/Help/Topics/60-bosh/working-with-bosh.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/.keep create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/common-issues.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/debugging-deployments.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/error-messages.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/index.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/kit-development-issues.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/manifest-debugging.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/secret-problems.md create mode 100644 lib/Genesis/Help/Topics/70-troubleshooting/trace-logging.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/.keep create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/environment-variables.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/genesis-configuration.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/hook-reference.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/index.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/kit-configuration.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/manifest-operators.md create mode 100644 lib/Genesis/Help/Topics/90-reference-guides/runtime-configs.md create mode 100644 lib/Genesis/HelpTopics.pm 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/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/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/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/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/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/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 ac370cfd..530917b8 100644 --- a/lib/Genesis/Commands.pm +++ b/lib/Genesis/Commands.pm @@ -494,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; diff --git a/lib/Genesis/Commands/Core.pm b/lib/Genesis/Commands/Core.pm index 21a70b2f..88bee8d0 100644 --- a/lib/Genesis/Commands/Core.pm +++ b/lib/Genesis/Commands/Core.pm @@ -194,7 +194,6 @@ EOF } sub help { - # First check if we just want to see global options alone if (!@_ && get_options->{globals}) { @@ -204,8 +203,21 @@ sub help { } if (@_) { - # Show help for specific command 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}) { @@ -216,7 +228,7 @@ sub help { 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); + command_help("Unknown command or topic: #G{$cmd}", 2); } } else { # Show general help listing 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