Andrew Kesterson requested to merge 2291_quickstart into master Dec 17, 2024

Documentation and Script Change

Summary

This MR rewrites significant portions of the quickstart guide, introduces a new quickstart script, and introduces a major k3d-dev.sh refactor to support both.

Quickstart guide

The quickstart guide is rewritten with the intention of enabling a much better user experience. The quickstart guide now:

Explicitly describes its target audience (SREs) at the top of the file
Has minimal boilerplate
Explicitly calls out the requirements for getting started at the top of the file, including links to installation instructions for required tools. Gives instructions for Linux, MacOS and Windows users.
Supports using any sufficiently large instance the user has available which can be logged into via SSH. To reduce the complexity on our side, ONLY Ubuntu instances are supported.
Relies on using a single script to complete the process of provisioning a k3d cluster, deploying flux, deploying bigbang, waiting for the release to complete, and deploying any changes the user desires to their quickstart configuration

The entire process takes less than an hour in the average case, with actual operator time being about 15 minutes, installing the prerequisites. The actual automated cluster config and big bang install takes about 45 minutes in the average case (using an AWS VM).

The quickstart guide does not reference bbctl or any other tools besides the quickstart script itself and kubectl in a couple of places. Once bbctl reaches a stable 1.0 release, we can revisit this.

k3d-dev.sh

In order to support its usage in the quickstart, k3d-dev required a reasonably large refactor. Most of the actual code is unchanged, and it is backward compatible; however, there were several changes introduced:

All the toplevel code is removed and a main() method has been introduced, helping to make the flow easier to understand
All the variables moved to the top and declared in one visible place
Argument parsing moved into function process_arguments
New -i option added to support sending an init script to the k3d instance after the user-data executes and before k3d is installed. (This isn't strictly required for this issue, but I needed it for another issue I was working, and shipped it with this.)
New -T option to prevent terminating the instance after 8 hours. For the user experimenting with bigbang, this is a more friendly mode of operation. The default is still to terminate after 8 hours.
The script can now install k3d on any host the user provisions and provides to it, skipping the AWS creation logic. New -H, -P, -U, and -k options added to support this.
Refactored the AWS specific bits out into cloud_aws_* functions. Added a -c option to specify which cloud provider the k3d-dev script should use for provisioning cloud instances, with AWS being the default. We can later expand k3d-dev to support other cloud providers by adding cloud_CLOUDNAME_toolnames, cloud_CLOUDNAME_configure, cloud_CLOUDNAME_report_instances, and cloud_CLOUDNAME_create_instances functions for the specific cloud provider.
Refactored the k3d installation logic out into separate initialize_instance, install_docker, install_k3d, install_kubectl, install_metallb, and fix_etc_hosts methods
Moved the instruction printout to print_instructions

Quickstart script

The new quickstart script implements the functions outlined in the quickstart guide. It has 3 dependencies:

The k3d-dev script, which it uses to provision instances and/or install k3d on instances
The pipeline-templates repository's 03_wait_for_helmreleases.sh script, which it uses to determine when the bigbang release process has completed
An open source bash command line argument parsing library from github

All dependencies are fetched at runtime. The quickstart script checks to ensure all tools it needs are installed before attempting to fetch dependencies and run any further.

$ bash ./docs/assets/scripts/quickstart.sh --help                                                                                               
quickstart.sh (C) 2025 : PlatformOne Big Bang team                                                                                              
                                                                                                                                                
PlatformOne Big Bang quickstart : Quickly deploy a development bigbang cluster on a VM                                                          
                                                                                                                                                
Optional Arguments:                                                                                                                             
    -H,--host v : String. IP or Hostname of the VM to operate on                                                                                
    -P,--privateip v : String. If your VM has a separate private IP in addition to the public host, provide it here                             
    -U,--username v : String. Username to use when SSHing into the target VM                                                                    
    -K,--keyfile v : String. SSH Key file to use when SSHing into the target VM                                                                 
    -V,--version v : String. Big Bang version to deploy (Default "latest")
    -v,--pipeline-templates-version v : String. Version of the bigbang pipeline-templates to use (Default "master")
    -R,--repolocation v : String. Location on your host filesystem where bigbang should be checked out (Default "")
    -u,--registry1-username v : String. Username for your account on registry1.dso.mil (Default "")
    -t,--registry1-token v : String. Access token for your account on registry1.dso.mil (Default "")
    -c,--cloud-provider v : String. If using cloud provisioning, which cloud provider should be used (Default "aws")
    -m,--metallb : Boolean. Deploy a MetalLB on k3d 
    -p,--provision : Boolean. Provision the k3d cluster (implied) 
    -d,--deploy : Boolean. Deploy bigbang (implied) 
    -w,--wait : Boolean. Wait for bigbang (implied by --deploy)

The quickstart's primary job is to be as thin of a shim as possible between the various scripts utilized to get a functional k3d cluster with big bang running on it, and most of these options are covered in the quickstart as required. The ones not covered in the quickstart guide are

    -c,--cloud-provider v : String. If using cloud provisioning, which cloud provider should be used (Default "aws")
    -V,--version v : String. Big Bang version to deploy (Default "latest")
    -m,--metallb : Boolean. Deploy a MetalLB on k3d 
    -v,--pipeline-templates-version v : String. Version of the bigbang pipeline-templates to use (Default "master")

The version, cloud-provider and metallb options are self explanatory. The --pipeline-templates-version option was added out of necessity to support usage of a separate branch of pipeline-templates that I had to create to fix a bug in the pipeline package-mappings.yaml file. Until the dependent MR is merged, if you want to test this, you will need to pass:

    --pipeline-templates-version bigbang_2291_quickstart

The quickstart script performs 3 operations: --provision, --deploy, and --wait. The default behavior is to perform all 3 of these. If you specify any of the 3 options manually, that behavior changes to the actions you specify. This allows the user to use the quickstart script to provision, deploy, and later update their dev cluster as they desire, without having to learn any other tooling. Providing a single user interface hopefully will reduce the friction for adoption and increase their patience when they move into the customer template later.

Internally, the quickstart script uses only helm and kubectl commands to interact with the bigbang deployment on the cluster. Neither bbctl nor anyone's shell helpers are used. I had attempted to include bbctl but I had bad luck getting bbctl to work reliably, so we'll revisit that at bbctl 1.0.

For Issue

Closes #2291

Upgrade Notices

N/A

Edited Dec 20, 2024 by Andrew Kesterson

Admin message

Rewrite the quickstart document, write a new quickstart script, and refactor k3d-dev to support it