|
|
This page describes ways, how to customize virtual environments using Ansible provisioning including basic examples of a playbook. It requires at least a basic understanding of Ansible playbooks.
|
|
|
|
|
|
# Provisioning Files
|
|
|
|
|
|
Ansible allows to install/uninstall/configure software, change settings, or transport files to any virtual machine of the sandbox. Users can provide their configuration files using the `--provisioning-dir` option of the `create-sandbox` script. This option expects an absolute or relative path to a directory. The specified directory must contain a `playbook.yml` file.
|
|
|
|
|
|
After using `--provisioning-dir`, CSC copies the content of the entire directory to the `provisioning` directory of the _intermediate definition_. It can contain any additional files or subdirectories that will be needed during the provisioning.
|
|
|
|
|
|
The `playbook.yml` file is the main [playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks.html) of the Ansible provisioning, and it is passed to Ansible after an instance of a virtual machine is built. The provisioning can be done entirely from this file, or it can be divided into many files, or [ansible roles](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html) included in `playbook.yml`.
|
|
|
|
|
|
# Groups
|
|
|
|
|
|
In custom playbooks, you can target special [groups](https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html)
|
|
|
- `all`: a group of all virtual machines
|
|
|
- `hosts`: a group of all host machines defined in the topology definition
|
|
|
- `routers`: a group of all router machines defined in the topology definition
|
|
|
- `ssh`: a group of all machines using ssh connection (Linux machines)
|
|
|
- `winrm`: a group of all machines using winrm connection (Windows machines)
|
|
|
|
|
|
or you can specify your own groups in the `groups` section of the topology definition file:
|
|
|
```
|
|
|
groups:
|
|
|
- name: my-servers
|
|
|
nodes:
|
|
|
- server1
|
|
|
- server2
|
|
|
- name: second-group
|
|
|
nodes:
|
|
|
- server1
|
|
|
- home
|
|
|
```
|
|
|
|
|
|
# Windows VMs
|
|
|
|
|
|
Generally, a sandbox can contain Windows VMs only inside one network. Windows VMs in multiple networks work correctly only using Ansible on the host machine (command line argument `--ansible-installed`).
|
|
|
|
|
|
The example `provisioning` generated by CSC contains `group_vars` for the `winrm` group. Windows VMs needs the variables inside to do the provisioning through WinRM:
|
|
|
```
|
|
|
ansible_become_pass: vagrant
|
|
|
ansible_connection: winrm
|
|
|
ansible_password: vagrant
|
|
|
ansible_user: windows
|
|
|
ansible_port: 5985
|
|
|
ansible_winrm_scheme: http
|
|
|
ansible_winrm_server_cert_validation: ignore
|
|
|
ansible_winrm_transport: basic
|
|
|
```
|
|
|
The file or variables can be removed if the sandbox does not contain a Windows VM.
|
|
|
|
|
|
# Extra variables
|
|
|
|
|
|
Additional variables can be passed to Ansible using a yml file. The `--extra-vars` option of the `create_sandbox` script specifies the path to this file. Variables can be defined in the following way inside the file:
|
|
|
```
|
|
|
attribute_name: value
|
|
|
another_attribute: another_value
|
|
|
```
|
|
|
|
|
|
# External Roles
|
|
|
|
|
|
Ansible roles from external repositories can also be included using the `requirements.yml` file in the user provisioning directory. If this file exists, the specified roles will be downloaded during the provisioning. A definition of a requirement has the following structure:
|
|
|
```
|
|
|
- name: my-external-role
|
|
|
src: https://gitlab.com/my-repository/my-role.git
|
|
|
scm: git
|
|
|
version: 1.0.1
|
|
|
```
|
|
|
|
|
|
# Playbook examples
|
|
|
|
|
|
## Playbook and plays
|
|
|
|
|
|
[Ansible playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) are YAML text files containing configuration of virtual machines. Every playbook consists of one or more _plays_, which may look like this
|
|
|
```
|
|
|
- name: Configuration of all devices
|
|
|
hosts: all
|
|
|
become: yes
|
|
|
tasks:
|
|
|
```
|
|
|
- The `name` attribute is useful for debugging, since Ansible writes out plays (and tasks) it is working on at the moment.
|
|
|
- `hosts` defines on which VM the play should be executed. It can be `all`, a name of a VM or a group.
|
|
|
- `become: yes` activates privileged execution of commands (_sudo_). It is usually needed for tasks like package installation.
|
|
|
- Each play consists of _tasks_, that represent steps of the configuration. The `tasks` attribute is a list of tasks to be executed in the play.
|
|
|
|
|
|
## Tasks
|
|
|
|
|
|
A _task_ is a unit of work Ansible can execute. Here are some examples of simple tasks:
|
|
|
|
|
|
### Linux package installation (_apt_, _yum_)
|
|
|
|
|
|
Package installation is one of the most common operations. We can use the [package](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/package_module.html) module for this purpose, which can automatically decide which package manager (_apt_ or _yum_) to use. [apt](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_module.html#ansible-collections-ansible-builtin-apt-module) and [yum](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/yum_module.html#ansible-collections-ansible-builtin-yum-module) modules are also available with more manager-specific attributes.
|
|
|
```
|
|
|
- name: Install ntpdate
|
|
|
package:
|
|
|
name: ntpdate
|
|
|
```
|
|
|
|
|
|
### Python package installation
|
|
|
|
|
|
Python packages can also be installed using the [pip](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/pip_module.html) module. This requires _pip_ to be installed on the virtual machine.
|
|
|
```
|
|
|
- name: Install bottle python package
|
|
|
pip:
|
|
|
name: bottle
|
|
|
```
|
|
|
|
|
|
### Execute a shell command
|
|
|
|
|
|
Sometimes Ansible modules are not enough, and a shell command needs to be executed. The [shell](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/shell_module.html#ansible-collections-ansible-builtin-shell-module) module executes the given command on the remote shell. For Windows VMs, the [win_shell](https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_shell_module.html#ansible-collections-ansible-windows-win-shell-module) module can be used. Generally, it is better to use commands only when no Ansible module is available for the given task.
|
|
|
```
|
|
|
- name: Execute script and redirect output
|
|
|
shell: somescript.sh >> somelog.txt
|
|
|
``` |
|
|
\ No newline at end of file |