Skip to content

Maintainers Guide

Jump to bottom
Alex Karasulu edited this page Apr 23, 2020 · 3 revisions

Getting Started: Maintainers and Sysadmins

Maintainers will make changes to boxes. Sysadmins will want to automate box generation: use other virtual machines to build the virtual machine templates this project's code outputs. Both need to understand what tools and environments are required.

Required Tools

You need a number of tools installed on the system building the boxes:

  • Packer - Automates building Vagrant boxes for different hypervisors and platforms
  • Vagrant - Runs Vagrant boxes for different hypervisors and platforms
  • Jsonnet - A domain specific configuration language to define JSON data. Helps break up and annotate large template files. NO PACKAGES: NEEDS TO BE COMPILED

Hypervisor Environments

Various hypervisors are obviously needed to build boxes for them. The two primary hypervisors we MUST absolutely support are:

  • KVM/Libvirt
  • VirtualBox

The others are gravy. The next tier of nice to have hypervisors we're considering are documented on the Provider Box Status section of the Box User Guide.

Not every hypervisor is available on every OS. Sometimes one hypervisor gets in the way of another on the same OS: i.e. KVM and VirtualBox. Some hypervisors are simple desktop hypervisors (VirtualBox, VMWare Desktop, Parallels) and some are associated with environments (KVM/Libvirt, Xen, AWS EC2).

Subutai Vagrant Provider vs. Subutai Vagrant Plugin

We are talking about build a Subutai Vagrant Plugin. This is NOT the same as building a Subutai Vagrant Provider.

The Subutai Vagrant Plugin will expose Subutai CLI operations (and other convenience functions) directly from the host to be executed on the Guest virtual machine. Some examples:

vagrant subutai import management
vagrant subutai start apache-con
vagrant subutai tunnel add localhost
vagrant subutai register peer http://bazaar.subutai.io mypeer mypass
vagrant subutai register rh http://mypeer mypass

Vagrant Providers run things on/in specific hypervisor or container environment combinations: i.e. Docker has a provider to launch containers. Subutai MUST supply a Vagrant Provider for running Subutai Containers and Blueprints. It will work in tandem with the Subutai Vagrant Plugin.

Avoid Mixing Concerns

Sysadmins and others building environments to automate box building and deployment to Vagrant Cloud should not mix concerns. Meaning DO NOT PUT MULTIPLE HYPERVISORS ON A BUILD MACHINE. YES packer can build multiple virtual machines for different hypervisors at a time. It's a cute feature but it will cause you headaches. Instead create different build machines for the different hypervisors for the 'providers' of Packer. Just build one type on one builder machine.

Advice: Making Changes to Boxes

When in doubt, use these rules to guide your decisions

KISS: Keep it simple stupid!

  • The most common cases for users should be UBER easy, project developers can deal with more complexity.
  • Users are not going to be using the dev and master environments.
  • Do NOT expect users to follow rules or conventions: they will install anywhere any way possible.
  • Most users will want a peer (to experience Subutai). No need to introduce resource hosts until after they are satisfied with their first experience.
  • Docs are good and need to be there. However no one has time to read them. So don't point to directions and documentation, show users the way! Modern applications need to guide users, NOT expect them to read documentation.
  • Go simple to complex, as we go from common features to more obscure features. The default path is the common path. This path should be simple. If anyone is interested in alternative ways for more advanced functionality then that's fine, and can include more complexity.

Direct Approaches from Rules

Once the simple common path is satisfied, we can provide more advanced options for developers, testers, and project contributors. With these in mind we do the following:

  • By default always provision a production peer, with the management console.
  • Once satisfied by that experience, interested users can be introduced to the concept of a resource host, how to create them, and add them to peers. The configuration mechanisms can be introduced at this point. The Subutai Vagrant Plugin can assist to ease that path.
  • We might want to launch a browser to the console URL after a machine comes online rather than giving them links to goto. The Subutai Console should then walk the user through getting setup by requiring them install the browser plugin to get into the console. See issue for this here. PROBLEM: DO NOT LAUNCH BROWSERS IF IN A HEADLESS ENVIRONMENT! PROVIDE A CONFIGURATION PARAMETER TO SUPPRESS THIS BEHAVIOR FOR HARD CORE USERS. THEY WILL NOT WANT IT.
  • Other non-production environments (sysnet, dev, master) are for developers, testers, and contributors who already know the product. They'll already know what to do so there's no reason to expose normal users to this. They can easily follow directions and use one of the offered configuration mechanisms.
Clone this wiki locally