Setup Script Instructions

This page will describe in detail each of the steps of the setup script used for installing, upgrading, or removing a node deployment instance. The 0_setup.sh script is designed to be a wrapper for specific helm commands (e.g. helm install and helm dependency build) and aids one in creating a separate namespace for this installation. If you are comfortable using the various helm commands for managing and deploying helm charts, then feel free to skip using this script.

Detailed Instructions

NOTE: At each step during this script, it will ask for input, but also provide a default option that can be selected by simply pressing "Enter" without providing any input. If a list of options are presented, one can type the number for that option and press "Enter".

Choosing a Context

Kubernetes is available as multiple distributions (e.g. minikube, microk8s, k3s) and one can even create "profiles" within a single distribution to essentially have multiple instances of the same distribution running on a single cluster. These are known as "contexts" and the setup script needs to know with which to communicate with so it will scan for available contexts and present them as a list of options to select from. If only one context is found, it will selected automatically and the script will proceed to the next step:

Only one context available, automatically selecting: microk8s
Switched to context "microk8s".

Otherwise, enter the number of the context you wish to choose and press "Enter".

The default provided option is the currently active context.

For more information on inspecting and configuring which kubernetes cluster the script is interacting with, see the Kubernetes documentation.

Creating a Namespace

A namespace within kubernetes is a way to isolate or group a collection resources. Users can enter a specific namespace that they would like to deploy the node software to, and if the namespace does not yet exist, it will be created before installing all of the components there. This step will appear like so:

Enter namespace (default is 'default'):

By default, the script will install everything in the "default" namespace.

For more information on namespaces in kubernetes, see Namespaces.

Choose an Action

When managing a helm deployment (i.e. a collection of resources generated when using a helm such as the FLAME node-deployment), helm offers several commands for interacting with it. This script limits the presented options and allows one to do the following at this next step:

• install - create the resources
• upgrade - update all of the resources to use the latest updated configuration files
• uninstall - remove all of the related resources

If no node-deployment installation is found, the script will only offer the install option at this step, otherwise users will see upgrade and uninstall here and can choose either accordingly.

For both install and upgrade, the sub-charts (i.e. the helm charts for the individual components) need to be compiled for the flame/ parent helm chart, which will be done automatically by the script in the final step.

For more information on the available helm commands, see the Helm command documentation.
For information on how helm chart dependencies are managed, see the helm dependency documentation.

Selecting a Values File

Whenever a helm deployment is installed or upgraded, a file of needed parameters must be provided. While most of the parameters are pre-defined for all of the node-deployment services, some user configuration is required (e.g. the robotUser and robotSecret) and these defined values are provided to helm during installation/upgrading using a values YAML file. At this point in the script, it will find any files in the current directory matching the values*.yaml pattern and present these as options for applying to helm:

Available values files:
1) values.yaml (default)
2) values_min.yaml
3) values_min_node1.yaml
Enter the number corresponding to the values file to use (default is 1):

You may see more or fewer files depending on whether you followed the Deploy the FLAME Node section of the README or created other custom values files.

By default, the values.yaml will be selected, but the installation will fail unless this file was modified to include the node robot credentials as described in the README.

For more information on values files, see the Helm documentation on the subject

Finish

The setup script will now execute whichever command you gave it: either install the node-deployment, upgrade it, or uninstall the components and resources. If installing, this can take several minutes since multiple images need to be pulled from the image repository and certain jobs will be executed to prepare the environments. Subsequent upgrades should run much quicker.

If you selected uninstall, the setup script will ask whether you wish to delete the Persistent Volume Claims (PVCs) created for the node-deployment. PVCs create persistent volumes, or allocated disk space, which data is stored for the deployed components. If the PVCs are deleted, they will have to be recreated if you choose to deploy a FLAME node again in the future, otherwise, they can be reused for future FLAME node deployments thus saving time by not having to recreate these partitions and populating them.