mcgrof.kdevops_vagrant

kdevops_vagrant

kdevops_vagrant is an Ansible role that helps you set up a shared Vagrant file for the kdevops community in your project. This role copies the Vagrantfile into your project's directory and can optionally start Vagrant for you.

The main purpose of this Ansible role is to make it easy to share the same flexible Vagrantfile between different projects, and to provide a base where contributors can improve and document it.

Project Namespace Directory

The project namespace directory is the main folder of your project. For example, if your development project is called kdevops and all files are kept in:

/home/user/devel/kdevops/

Then kdevops is your project namespace. By default, the Ansible role automatically identifies your project directory using the name of the folder where your playbook file is located. For instance, if your playbook is at:

/home/user/devel/kdevops/playbooks/kdevops_vagrant_nodes.yml

You can also use a different file to override settings:

/home/user/devel/kdevops/playbooks/kdevops_vagrant_nodes_override.yaml

The directory for your playbook is:

/home/user/devel/kdevops/playbooks/

The base name of that directory, which is:

/home/user/devel/kdevops/

This path is recognized as your project's namespace directory. You can change this using the force_project_dir variable explained below.

Project Namespace

The project namespace is included in the Vagrantfile used by this role, allowing you to change default settings with environment variables. The project namespace is derived from the directory name mentioned above. For example, if your project namespace directory is:

/home/user/devel/kdevops/

Then the project namespace is kdevops, and the upper case version is used as a prefix for environment variables, like KDEVOPS. Dashes in names are replaced with underscores because shell variables cannot have dashes. So if your project directory was:

/home/user/devel/some-cool-project/

The project namespace would be SOME_COOL_PROJECT.

Requirements

You need to have Vagrant installed.

Vagrant is used to easily create virtual machines (VMs) without using the cloud. The following Vagrant providers are supported:

Virtualbox
libvirt (KVM)

Supported Operating Systems:

OS X
Linux

Running libvirt as a Regular User

We use the libvirt-user Ansible role to allow a regular user to run libvirt. Check the documentation for details.

Overriding Node Configuration with a Different File

The best way to change variables in Vagrant is through the $(project)_node_override.yaml file. For example, you can override data for the kdevops project in an optional file located outside of git:

/home/user/devel/kdevops/playbooks/kdevops_vagrant_nodes_override.yaml

Environment Variables

If using an override file does not work, you can use environment variables. However, this should be done carefully, as we need to support each new variable individually. Using the override file allows you to change anything simply when a new feature is added.

Environment variables use the upper case version of the project namespace as a prefix. We'll refer to this as ${PN_U}. Here are some environment variables that affect how the Vagrantfile behaves:

${PN_U}_VAGRANT_NODE_CONFIG: overrides the default configuration file
${PN_U}_VAGRANT_PROVIDER: changes the provider for Vagrant
${PN_U}_VAGRANT_LIMIT_BOXES: enables limiting the number of boxes
${PN_U}_VAGRANT_LIMIT_NUM_BOXES: sets the number of boxes to create
${PN_U}_VAGRANT_QEMU_GROUP: overrides the QEMU user to use

Limiting Vagrant's Number of Boxes

By default, Vagrant attempts to create all specified nodes in your configuration file. Typically, this file is named ${PN_L}_nodes.yml, where ${PN_L} is the lower case version of your project namespace. For the kdevops project, this would be kdevops_nodes.yml.

To limit Vagrant to create only one box in the kdevops project, you would use:

export KDEVOPS_VAGRANT_LIMIT_BOXES="yes"
export KDEVOPS_VAGRANT_LIMIT_NUM_BOXES=1

Make sure to use the correct prefix for your project.

This ensures that only the first host is created and set up, which can be helpful if you're working on a laptop and want to save resources.

Scope of Use of Ansible

The kdevops project is designed to work independently of how you configure a system, whether on a virtual machine, a physical machine, or in a cloud environment.

There are three main stages to set everything up:

Bring up: Start virtual/cloud/bare metal systems
Configure and install dependencies: Set up user preferences, SSH configurations, and necessary development packages. This is managed using the update_ssh_config_vagrant and devconfig Ansible roles.
Let it rip: Start working, typically encouraged through Ansible.

We focus on using Vagrant with Ansible only for the first two stages, using these two roles:

We do not encourage adding more Ansible roles for Vagrant to keep it simple.

Ansible Python Interpreter

Ansible needs Python on the remote systems. The version of Python may vary, but Ansible usually tries to use an older version for compatibility. You should specify which version is used, ideally in the inventory file. The Vagrantfile has a default inventory file called ../hosts, but you can change this in your Ansible configuration:

ansible_playbooks:
  # You can override any Ansible variable here if this file exists.
  # This file is optional.
  extra_vars: "../extra_vars.yml"
  inventory: "../hosts"
  playbooks:
    - name: "../playbooks/update_ssh_config_vagrant.yml"
    - name: "../playbooks/devconfig.yml"

Your hosts file example might look like this:

[all]
newsystem1
oldsystem1

[all:vars]
ansible_python_interpreter = "/usr/bin/python3"

[new]
newsystem1
[new:vars]
ansible_python_interpreter = "/usr/bin/python3"

[old]
oldsystem1
[old:vars]
ansible_python_interpreter = "/usr/bin/python2"

Here, all systems are set to use Python 3, except for the last entry, which ensures that the old system uses Python 2 instead.

Ansible Extra Vars Use with Vagrant

Ansible has its own way of determining variable priority, whether from the command line, role files, etc., which is documented on the Ansible variable documentation page.

To allow users to specify custom settings in a file not under version control without needing to use the command line each time, kdevops allows the use of a file named extra_vars.yml in the project root directory:

/home/user/devel/kdevops/extra_vars.yml

When this file is present, the Vagrant Ansible plugin will ensure it is directly passed to Ansible with --extra-vars=@file. The @ character is required when specifying a file, but you don't need to worry about it.

All Ansible roles used with kdevops check for this extra_vars file.

Ansible Role Variables

run_vagrant: Defaults to False; if set to True, Vagrant will run automatically.
force_project_dir: If set, it designates where to look for the Vagrant directory, otherwise it defaults to the parent directory of the playbook.

Dependencies

None required.

Example Playbook

Here’s a simple example of a playbook for the kdevops project:

---
- hosts: localhost
  roles:
    - role: kdevops_vagrant

In this case, localhost is used because we are setting up the Vagrantfile in the local kdevops/vagrant/ directory. You can use other hosts as needed.