aka. Mighty Server Management System 😉
MSMS is a server management system based on |tool_ansible| IT automation tool and other open-source utilities designed to create ready to use and easy to extend server management workflow with following key features:
- Local installation of |tool_ansible| and all other utilities within virtual environment.
- Full power of |tool_ansible| with customized preconfigured environment.
- Batteries included: ready-to-use base set of server management roles.
- Role management based on |tool_git| submodules (installation, upgrading).
- Built-in documentation based on |tool_sphinx|.
- Autogenerated server inventory documentation based on |tool_sphinx|.
- Control utility based on |tool_make|.
- Separated server inventory configuration versioned with |tool_git|.
- Support for multi administrator workflow based on |tool_git|.
For description of the MSMS architecture please refer to section :ref:`section-readme-overview` below, or to more thorough :ref:`section-overview` manual page.
Table of contents:
- :ref:`section-readme-prerequisites`
- :ref:`section-readme-overview`
- :ref:`section-readme-usage`
- :ref:`section-readme-next`
- :ref:`section-readme-author`
The only prerequisite for successfull installation is the presence of following packages on your system:
- make
- python3
- python3-venv
Make sure you have all of these installed with command similar to this:
apt install make python3 python3-venv
For installation instructions please refer to section :ref:`section-readme-usage` below.
Following ASCII chart provides the quick overview of the architecture of the MSMS system.
+-------------------------------------------------------------------+
| MSMS (.git) |
| |
| bin +---------------------------------------------+ |
| doc | INVENTORY (.git) | |
| lib | | |
| spool | docs +-----------------------------+ | |
| venv | group_vars | ROLES | | |
| Makefile | group_files | +-------------------------+ | | |
| ansible.cfg | host_vars | | role_1 (.git;submodule) | | | |
| conf.py | host_files | +-------------------------+ | | |
| documentation.rst | user_files | +-------------------------+ | | |
| README.rst | playbooks | | role_2 (.git;submodule) | | | |
| | hosts | +-------------------------+ | | |
| | | ... | | |
| | | +-------------------------+ | | |
| | | | role_N (.git;submodule) | | | |
| | | +-------------------------+ | | |
| | +-----------------------------+ | |
| +---------------------------------------------+ |
+-------------------------------------------------------------------+The outer box is the MSMS system itself. It is composed of some executable utilities, documentation pages, master Makefile etc. It is designed to be a standalone package independent of any particular local requirements. It resides in its own |tool_git| repository.
The key component is the inventory subdirectory, which contains all specific
configurations. |tool_ansible| users will immediately recognize the group_vars
and host_vars directories, which contain server environment configurations. There
are also some additional directories, most noteworthy being the roles directory
containing all installed roles required for that particular setup. Roles are
installed as |tool_git| submodules of the whole inventory repository. The
inventory repository itself is however NOT installed as a submodule of the
master MSMS |tool_git| repository, it is intentionally installed as a loose
plugin to separate tool/code from configuration.
This architecture enables separate development of the MSMS system features, separate development and management (installation, upgrading, uninstallation) of |tool_ansible| roles and keeping all server environment configurations (inventory) in version control system. The use of |tool_git| also enables collaboration of multiple administrators.
Following ASCCI chart depicts expected usage of MSMS system:
+--------------------+
| MSMS |
| -----------------+ | +----------+
WS1 | |inventory (.git)| +------+ | |
| +----------------+ | | +->+ SERVER_1 |
+--------------------+ | | | |
| | +----------+
^ | |
| | |
v v |
XXXXXX + +----------+
+----------------+ XXXX XXXXXX | |
SHARE |inventory (.git)| XX INTERNET X+-->+ SERVER_2 |
+----------------+ XX XXXX | |
XXXXXXXXX+ +----------+
^ ^ |
| | |
v | | +----------+
| | | |
+--------------------+ | +->+ SERVER_3 |
| MSMS | | | |
| -----------------+ | | +----------+
WS2 | |inventory (.git)| +------+
| +----------------+ |
+--------------------+Each admin is working from his own workstation (WS). They exchange server inventory configurations via remote shared Git repository and each is communicating directly with each managed server.
Installation process is pretty straightforward, the |tool_git| takes care of that.
If you are starting from scratch please follow these instructions to bootstrap fresh MSMS installation:
# Prepare workspace. $ mkdir ~/Ansible $ cd ~/Ansible # Get the MSMS codebase with Git. $ git clone https://github.com/honzamach/msms.git msms-local $ cd msms-local # Display built-in make help to review available commands. $ make # OR explicitly: $ make help # Setup fresh server management environment. $ make msms-setup # Activate server management environment before executing any playbooks. $ . ./venv/bin/activate $ make msms-on # In case you are interested install default set of roles. $ make roles-install-default # Generate and view documentation locally for your convenience. $ make docs
Another option is to start working on existing server management environment created perhaps by one of your coworkers. In that case please follow these installation instructions:
# Prepare workspace. $ mkdir ~/Ansible $ cd ~/Ansible # Get the MSMS codebase with Git. $ git clone https://github.com/honzamach/msms.git msms-local $ cd msms-local # Display built-in make help to review available commands. $ make # OR explicitly: $ make help # Load existing server environment configurations from shared remote Git repository. $ make msms-load META_URL=git_repository_url # Activate server management environment before executing any playbooks. $ . ./venv/bin/activate $ make msms-on # Generate and view documentation locally for your convenience. $ make docs
At this point you should have working MSMS installation.
Next you may wish to perform some of the following tasks:
Install additional existing role from any |tool_git| repository:
$ make role-install ROLE_URL=https://github.com/honzamach/ansible-role-cleanup.git ROLE_NAME=honzamach.cleanup
Create brand new role:
$ make role-create
Execute Ansible playbooks as necessary:
$ ansible-playbook --ask-vault-pass role_accounts.yml $ ansible-playbook --ask-vault-pass role_... $ ansible-playbook --ask-vault-pass playbook_full.yml $ make play-full
When you make any changes in your inventory do not forget to commit and
push your local server environment configuration changes to your upstream
shared repository, so your changes are available to your coworkers:
$ make msms-commit $ make msms-push
Always kep the MSMS system and server environment configurations up-to date:
$ make msms-upgrade
Disable the server management environment when you are done:
$ make msms-off $ deactivate
- For full description of the MSMS architecture please refer to :ref:`section-overview` manual page.
- For full description of the MSMS usage please refer to :ref:`section-usage` manual page.
- For list and documentation of all currently installed roles please refer to :ref:`section-roles` manual page.