Skip to content

Latest commit

 

History

History
394 lines (280 loc) · 12.9 KB

README.adoc

File metadata and controls

394 lines (280 loc) · 12.9 KB
Raw

Ansible

Table of Contents

Conventions

When we refer to the controller, that means that we speak about the machine that executes the Ansible playbooks and roles and which owns the inventory. The hosts are the machines where the playbooks and roles are executed against.

The exception goes to the playbooks that are executed against localhost. This special host is referred to the controller.

ℹ️
 Check the Ansible requirement page for Python compatibility !

Ansible Inventory

The Ansible Inventory is managed by

Installation guide

In order to play with the playbooks/roles of this project, it is needed to:

ℹ️

Since passwordstore is integrated with git, all changes made locally to a pass repository are automatically committed to the local git repo.
⚠️

Don’t forget to git push and git pull often in order to have your local repository synchronized with other team members as well as publishing to the team your changes.

Python Virtual Environments

This project suggests using a python virtual environment to manage all the python dependencies.

This section describes the procedure to create a virtual environment for using with the project.

First create the .snowdrop-venv virtual environment.

ℹ️

This command only needs to be executed the first time. After being created the virtual environment status will be stored at the .snowdrop-venv folder at the root of the project. This folder has been excluded from git.
Create the .snowdrop-venv virtual environment
python3 -m venv .snowdrop-venv

Then activate the virtual environment to be able to use it. Activating is done by executing the following command.

Activate .snowdrop-venv virtual environment
source .snowdrop-venv/bin/activate

After this the virtual environment name will show up on the bash prompt (e.g. (.snowdrop-venv) [janedoe@mycomputer k8s-infra]$).

Once using the python virtual environment install the requirements.

ℹ️

This command only needs to be executed the first time.
Install the python requirements
python3 -m pip install -r requirements.txt
Install required Ansible Collections
ansible-galaxy collection install -r ./collections/requirements.yml --upgrade

Deactivate the Python Virtual Environment

To deactivate the python virtual environment execute the following command.

deactivate

As a result the .snowdrop-venv reference on the bash prompt will disappear.

Install the snowdrop.cloud_infra Ansible Collection

⚠️

Requires: Python Virtual Environment active.

Before building the collection make sure no previous versions have been built.

rm -f build/snowdrop-cloud_infra-*.tar.gz

To build the collection execute the following ansible-galaxy command.

Build the snowdrop/cloud_infra collection
ansible-galaxy collection build ansible/ansible_collections/snowdrop/cloud_infra --output build/ --force

This will generate a .tar.gz file with name snowdrop-cloud_infra-<version>.tar.gz on the ./build/ subfolder of the k8s-infra repository.

Finally install the collection.

ansible-galaxy collection install $(find . -name snowdrop-cloud_infra-*.tar.gz) --upgrade

User Guide

Provisioning and accessing a server requires several steps, each of which will be covered in this section.

  1. Manage Ansible Inventory groups […​](Group management in ansible)

  2. Manage Ansible Inventory host records […​](#host-management-in-ansible)

  3. Create Server in Cloud Provider […​]([Create server])

  4. Secure Host […​](Secure host)

  5. Install Software […​](Install software)

Group management in ansible

Groups are defined in the hosts.yml file that exists in the inventory folder inventory/hosts.yml. The 2 main goals of groups is to apply variable values and filter playbook execution.

The usage for groups is to:

  • define the provider of each host and the associated information

  • define information related to groups of applications

Click to see more information related to the providers hosts group

There can are different groups for the providers, ATTOW two providers exist, openstack and hezner. The goal is to provide variables that are required for each provider such as the provider variable which contains the provider name.

Excerpt of the actual inventory/hosts.yml file
link:inventory/hosts.yml[role=include]

Another existing group is k8s are associated with kubernetes and assign the kubernetes version or ports to be open.

Click to see more information related to the k8s (kubernetes) group

There can are different groups for the providers, ATTOW two providers exist, openstack and hezner. The goal is to provide variables that are required for each provider such as the provider variable which contains the provider name.

Excerpt of the actual inventory/hosts.yml file
all:
  children:
link:inventory/hosts.yml[role=include]

For each k8s version there is associated information defined by common variables.

⚠️

The usage of group variables to keep this information is subject to be reviewed on the short term. More information at GitHub Issue 335.
Excerpt of the kubernetes version variables
link:inventory/hosts.yml[role=include]

If it would be required to support a new kubernetes version than a new set of variables should be added to the inventory file. For instance, preparing the installation for version 1.17 would require adding a new group as child of the k8s group. It might also be required to adjust the dashboard and flannel values.

Sample of new k8s version variables
        k8s_1.30:
          vars:
            k8s_version: 1.30.1
            k8s_dashboard_version: v3.1.2
            coreos_flannel_sha_commit: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Considerations on the Ansible Inventory

The Ansible host inventory is generated from the hosts.yml file as well as the passwordstore database. The inventory is dynamically generated by this python script.

The location of the inventory is defined at the ansible.cfg configuration file at the root of the project.

Inventory definition for ansible.cfg
link:../ansible.cfg[role=include]

The first step is to add the host to the Ansible inventory but also to create the needed keys under the password store. This section describes how to maintain our hosts and their use.

Managing the Inventory

The passwordstore inventory should be updated whenever a VM is created and/or updated. For instances, the playbook that creates an OpenStack VM (openstack_vm_create_passwordstore.yml) also calls the passwordstore playbook for adding the host to the inventory. The same happens in the playbook that removes an OpenStack VM (openstack_vm_remove_passwordstore.yml).

Excerpt of the playbook that invokes the passwordstore playbook to manage the inventory
link:playbook/openstack/openstack_vm_create_passwordstore.yml[role=include]

Nevertheless whis can be done manually and the next sections will describe the process.

Updating and retrieving the inventory

As commented before, the host information (user, pwd, ssh port, …​) is obtained from the github passwordstore team [project](https://github.com/snowdrop/pass).

Because a host can already be defined under the store, prior to execute the playbook creating a host, check the content of the store using the following command

pass hetzner
hetzner
├── ...
├── host-1
│   ├── ...
├── host-2
│   ├── ...

According to what you will find under the Hetzner level, then 2 scenario will take place:

  1. The host exists. Jump to the Import a host section;

  2. The host doesn’t exist. Create a new host as documented under the section Create a host.

ℹ️

Check the [team password store documentation](https://github.com/snowdrop/pass) if it is not yet installed on your laptop.
⚠️

Whenever a command to create a host and password entries took place, then push the content using the command pass git push manually !!

Import a host

If a host has already been created, it can be imported within the inventory using the command:

ansible-playbook ansible/playbook/passstore_controller_inventory.yml -e vm_name=<VM_NAME> -e pass_provider=hetzner

where <VM_NAME> corresponds to the host key created under hetzner.

ℹ️

The playbook used is the same as the one described in the Create a host section but without the create tag.

Create a host

If the host doesn’t exist it must be generated and added to the Ansible inventory.

This is done using the passstore_controller_inventory playbook. More information on how to use this playbook in the [passstore_controller_inventory section](#passstore_controller_inventory).

Remove a host

This is done using the passstore_controller_inventory_remove playbook. More information on how to use this playbook in the [passstore_controller_inventory_remove section](#passstore_controller_inventory_remove).

ansible-playbook ansible/playbook/passstore_controller_inventory_remove.yml -e vm_name=<vm_name> -e pass_provider=<provider>

Create Server

Once the inventory is defined the server can be provisioned, if it isn’t.

There should be different playbooks for each of the providers so check the corresponding provider:

Once the server is created it must be securized. More information on the next section.

Secure host

Host securization is of utmost importance. For this reason a specific playbook and roles have been generated to perform this task.

For the execution of the securization check the [sec_host playbook section](#sec_host).

Install software

k8s

For information on k8s playbooks and roles check ../../kubernetes/README.md[here].

Folders

Ansible Collections: ansible_collections

Ansible Inventory: inventory

Ansible Playbooks: playbook

Ansible Roles: roles

Collections

Build a collection

ansible-galaxy collection build ansible/ansible_collections/snowdrop/godaddy --output build/ --force

Install a collection

ansible-galaxy collection install build/snowdrop-godaddy-$(yq -r .version ansible/ansible_collections/snowdrop/godaddy/galaxy.yml).tar.gz --upgrade

Development Guide

Testing

Testing

molecule test