This reference implementation describes how to use the guided-setup PowerShell Core module. The demo files show how the guided setup can assist with the configuration and deployment of Bitnami's MariaDB Helm chart.
This MariaDB guided setup and deployment script provide the following benefits:
- asserts prerequisites
- creates Kubernetes (K8s) Secret dependency for MariaDB passwords
- avoids using the same password for root and replicator database accounts
- creates K8s ConfigMap dependency for MariaDB options
- configures binary log expiration when using replication
- configures optional character set, collation, and table name case
- generates resource files or orchestrates helm deployment
Note: You do not need to cover every possible deployment configuration with a guided setup and related deployment script.
You can start the setup by installing PowerShell Core and running this command: pwsh ./guided-setup.ps1.
The reference implementation has two main parts. The first is the guided setup, a series of screens that gather the desired deployment configuration from a user. The second is a setup script that takes the setup responses and either orchestrates the deployment by running helm or stops short of running helm by producing required helm values and K8s resource files. The reference implementation lets the user decide the deployment method.
The guided-setup.ps1 file provides the starting point. It is a wrapper. The first step dot sources the .install-guided-setup-module.ps1 to install a specific guided-setup module version. The next step dot sources the .guided-setup.ps1 file, which is the main file that establishes the directed graph of configuration steps and invokes the guided setup.
The .guided-setup.ps1 file has multiple parts. The using module statement imports a specific version of the guided-setup module (it should reference the same version specified in .install-guided-setup-module.ps1). It allows you to reference PowerShell content from the guided-setup module. Files containing guided setup steps then get included via dot sourcing. The next phase adds each step to the directed graph. With the steps added, the next step is to establish step transitions. Step transitions define how the user can move between steps. Define transitions to optional steps first to allow those steps to run conditionally. The main setup starts by running the Invoke-GuidedSetup function.
Each configuration step should derive from a base Step that derives from the module's GuidedSetupStep. The base step should accept a ConfigInput parameter that will include your setup parameters.
The core/steps directory includes files with MariaDB-related guided setup steps. For example, the credential.ps1 contains the steps required to gather the root and replicator account passwords. Specifying the latter password is required when using MariaDB's replication feature, so the CanRun function determines whether the replication account password screen appears. It uses a helper method to determine whether replication is enabled, something the user indicates on the ReplicaCount screen.
An important step is testing whether prerequisites have been met. The Prerequisites step uses the Test-SetupPreqs function to check prerequisites. It uses the same function invoked by the guided-setup-check-prereqs.ps1 script that can be run standalone.
The guided-setup module includes multiple question types, derived from Question. The base question has parameters that affect how the response is gathered. For example, an answer can be masked by setting $isSecure to $true.
The ConfirmationQuestion requests an input that must be matched when entered a second time. You can use it to gather passwords when masking a response. The IntegerQuestion lets you request an integer response that falls between a minimum and maximum value. The PathQuestion lets you request a path to a file or directory, validating whether the filesystem item exists. The CertificateFileQuestion question derives from PathQuestion and validates the response as a certificate file. You can use the MultipleChoiceQuestion for responses selected from a list of valid choices. A yes/no response can be fetched using the YesNoQuestion.
The guided setup ends with a Finish step that prepares setup.ps1 script parameters according to the guided setup responses.
The setup.ps1 file can invoke helm or create the Helm and K8s resource files so you can run helm on your own. The $resourceFilesOnly parameter determines the deployment mode.
Specifying MariaDB options like binary log file expiration requires appending settings to the default MariaDB configuration. The options.ps1 file includes the MariaDBOptions step, asking whether default MariaDB options will be used, or if the user wants to specify a specific character set, collation, and table name option. The setup directory contains files upon which setup.ps1 depends, and the resources.ps1 file includes the New-MariaDBOptionConfigMap function that helps you specify optional MariaDB options.
A guided setup implementation does not need to cover every deployment configuration. For example, the Bitnami MariaDB Helm chart includes many parameters not covered by the reference implementation. The $extraValuesFiles parameter accepts additional helm values files outside the scope of the guided setup. Similarly, you can include any additional setup.ps1 parameters that are outside the scope of your guided setup (e.g., the primaryName and replicaName setup.ps1 parameters).
You can use Pester to test the guided setup by simulating a user at the keyboard. The guided-setup-tests.ps1 file includes example tests that depend on mock.ps1 and pass.ps1. You can run the test by invoking this command: pwsh ./test/guided-setup-tests.ps1. Note that you must have previously installed the guided-setup module either indirectly by running the guided setup or by directly running the .install-guided-setup-module.ps1 script (with pwsh ./.install-guided-setup-module.ps1).
You can visualize the guided setup graph by setting $DebugPreference='Continue' to generate the following at the start of the setup:
digraph G {
BinaryLogExpiration -> RootPwd;
WorkDir -> Namespace;
RootPwd -> ReplicationPwd;
RootPwd -> MariaDBOptions;
ReleaseName -> ReplicaCount;
PrequisitesNotMet -> Abort;
DeploymentMethod -> Prerequisites;
TableNameCase -> Finish;
Collation -> TableNameCase;
ChooseContext -> HandleNoContext;
ChooseContext -> SelectContext;
ReplicationPwd -> MariaDBOptions;
ReplicaCount -> BinaryLogExpiration;
ReplicaCount -> RootPwd;
SelectContext -> PrequisitesNotMet;
SelectContext -> WorkDir;
Welcome -> DeploymentMethod;
HandleNoContext -> Abort;
Namespace -> ReleaseName;
Prerequisites -> PrequisitesNotMet;
Prerequisites -> ChooseContext;
CharacterSet -> Collation;
MariaDBOptions -> CharacterSet;
MariaDBOptions -> Finish;
}
You can visualize the resulting graph at GraphvizOnline. You can paste the debug output into the display's left side to see the graph on the right.
You can also use GraphvizOnline to view the path a user took in the guided setup by visualizing the graph.path file produced by the Write-StepGraph function. A blue highlight will show the user's path through the setup.
