Running the Ansible Installation Playbook
Lightbits Cluster Installation Process
| # | Installation Steps |
|---|---|
| 1 | Connecting your installation workstation to Lightbits’ software repository |
| 2 | Verifying the network connectivity of the servers used in the cluster |
| 3 | Setting up an Ansible environment on your installation workstation |
| 4 | Installing a Lightbits cluster by running the Ansible installation playbook |
| 5 | Updating clients (if required) |
| 6 | Provisioning storage, connecting clients, and performing IO tests |
As discussed in Preparing the Installation Workstation (Ansible Controller), we support installing using Ansible or using a prebuilt Docker image that contains Ansible. Pick the method that applies to your installation environment and follow the commands to install the Lightbits cluster software on the storage servers. Afterwards, go to the bottom of the section to confirm a successful installation.
For both methods, we provide the simple default installation methods. However, we provide other more advanced installation configuration examples in the Ansible Docker section. Note, however, that these same examples can be adopted into the Ansible method; for that you will just skip the Docker commands and refer to the ansible-playbook commands as the template.
Ansible Installation Method
Running the Ansible Controller
The Ansible playbook operations below can take several minutes. The output will report the status of all the tasks that succeeded/failed on the nodes.
To install the cluster software and configure the cluster, change into light-app directory with cd ~/light-app, and enter the following command to run the playbook. Note that this should be executed as a non-root user.
ansible-playbook -i ansible/inventories/cluster_example/hosts playbooks/deploy-lightos.yml -vvv- This command must be run from the directory where light-app was extracted to. All of the paths will then work as displayed.
- The inventory file points to a "hosts" file, which instructs Ansible where to deploy Lightbits.
- The selected playbook, "deploy-lightos.yml", instructs Ansible on how to install and configure the Lightbits cluster on the servers mentioned in the "hosts" file.
- Ansible will log to its default path as specified by ansible.cfg. By default that is /var/log/ansible.log. The log path can be changed by prefixing
ANSIBLE_LOG_PATH=/var/log/ansible.log ansible-playbook ... - The following files will be created into the home directory:
lightos-system-jwt&lightos-default-admin-jwt. Note: The home directory is the home directory of the non-root user running the Ansible command. - Certificates used by the cluster will be saved into a new directory,
lightos-certificates. This directory will be created in the home directory. - It is recommended to make a secure backup of this content, or at a minimum, the jwt files and
lightos-certificatesdirectory. - Debug level verbosity is enabled with
-vvv. This helps diagnose any issues if they happen.
When the installation is done, the cluster will be bootstrapped with a system-scope project. You will need access to the JWT. By default the cluster-admin JWT is placed in ~/lightos-system-jwt of the Ansible host. This path can be changed by editing group_vars/all.yml before running the ansible-playbook, and appending this variable system_jwt_path: "{{ '~/lightos-system-jwt' | expanduser }}"
Prebuilt Ansible Docker Installation Method
If using the prebuilt Docker image with Ansible, ensure that Docker is logged in. Refer to the bottom of Preparing the Installation Workstation (Ansible Controller) for instructions on how to log in using Docker.
This first subsection shows instructions on launching a simple or default Lightbits installation. The subsections afterwards show other variations to the installation that might apply to more complex configurations.
Additionally, each Docker example requires the correct Docker URL docker.lightbitslabs.com/lightos-3-(Minor Ver)-(Rev)-rhl-8/lb-ansible:v9.1.0. Note that the path bit is incomplete and requires substitution. Refer to the Lightbits Installation Customer Addendum for the correct Docker image URL.
Running Using the lb-ansible Docker Image
cd ~/light-appmkdir lightos-certificatesdocker run -it --rm --net=host \ -e UID=`id -u` \ -e GID=`id -g` \ -e UNAME=$USER \ -v `pwd`:/ansible \ -w /ansible \ -e ANSIBLE_LOG_PATH=/ansible/ansible.log \ docker.lightbitslabs.com/lightos-3-(Minor Ver)-(Rev)-rhl-(8/9)/lb-ansible:v9.13.0 \ sh -c 'ansible-playbook \ -e system_jwt_path=/ansible/lightos_jwt \ -e lightos_default_admin_jwt=/ansible/lightos_default_admin_jwt \ -e certificates_directory=/ansible/lightos-certificates \ -i ansible/inventories/cluster_example/hosts \ playbooks/deploy-lightos.yml -vvv'We will pre-create the lightos-certificates directory inside ~/light-app, so that our certificates get saved outside of the container.
Docker command breakdown:
- Mount the current working directory or $PWD to /ansible inside the container, to have access to the playbook and roles. The current working directory at this point will be where light-app was extracted.
- Set the WORKDIR to /ansible inside the container. This sets the current working directory within Docker to /ansible.
- Configure Ansible to write logs to /ansible/ansible.log.
- Run the playbook with specified hosts from an inventory folder in the ansible/inventories/cluster_example.
- Sets
system_jwt_pathfor the system jwt to be saved in~/light-app/lightos_jwtafter the container is closed. - Set
light_default_admin_jwtpath for the admin-project jwt to be placed at~/light-app/lightos_default_admin_jwtafter the container is closed. - Set the path for the generated certificates to be placed in
~/light-app/lightos-certificatesafter the container is closed.
Custom Inventory Folder
If the inventory folder is placed in a different location, such as: /path/to/inventory, you can mount this path as well and use it:
cd ~/light-appmkdir lightos-certificatesdocker run -it --rm --net=host \ -e UID=`id -u` \ -e GID=`id -g` \ -e UNAME=$USER \ -v `pwd`:/ansible \ -v /path/to/inventory:/inventory \ -w /ansible \ -e ANSIBLE_LOG_PATH=/ansible/ansible.log \ docker.lightbitslabs.com/lightos-3-(Minor Ver)-(Rev)-rhl-(8/9)/lb-ansible:v9.13.0 \ sh -c 'ansible-playbook \ -e system_jwt_path=/ansible/lightos_jwt \ -e lightos_default_admin_jwt=/ansible/lightos_default_admin_jwt \ -e certificates_directory=/ansible/lightos-certificates \ -i /inventory/hosts \ playbooks/deploy-lightos.yml -vvv'Using SSH-Keys Present On Ansible-Controller Host
If you use SSH-Keys present on your ansible-controller machine and you copied these keys to the authorized_keys on target hosts, you will want to use this key inside the container.
The following example shows how to mount the ~/.ssh folder so that Ansible running inside the container will use it.
cd light-appmkdir lightos-certificatesdocker run -it --rm --net=host \ -e UID=`id -u` \ -e GID=`id -g` \ -e UNAME=$USER \ -v `pwd`:/ansible \ -v ${HOME}/.ssh:${HOME}/.ssh \ -w /ansible \ -e ANSIBLE_LOG_PATH=/ansible/ansible.log \ docker.lightbitslabs.com/lightos-3-(Minor Ver)-(Rev)-rhl-(8/9)/lb-ansible:v9.13.0 \ sh -c 'ansible-playbook \ -e system_jwt_path=/ansible/lightos_jwt \ -e lightos_default_admin_jwt=/ansible/lightos_default_admin_jwt \ -e certificates_directory=/ansible/lightos-certificates \ -i ansible/inventories/cluster_example/hosts \ playbooks/deploy-lightos.yml -vvv'Verify Successful Installation
When the installation completes with no errors, you will see an output similar to the following:
PLAY RECAP*************************************************************************server00 :ok=68 changed=19 unreachable=0 failed=0 skipped=34 rescued=0 ignored=0server01 :ok=67 changed=18 unreachable=0 failed=0 skipped=33 rescued=0 ignored=0server02 :ok=67 changed=18 unreachable=0 failed=0 skipped=33 rescued=0 ignored=0- The "failed=0" indicates that the installation finished without errors.
- If the installation process failed, see Recovering from Cluster Installation Failure.
The installation flow is now complete, and you can move on to the client configuration sections of the Installation Guide.
You should also make sure you back up your installation files properly. For more, see Planning for the Lightbits Cluster Software Installation.