From Wikitech
Jump to navigation Jump to search

This page contains information how to set up an instance. Instances are not projects: see Help:Terminology and the full list of projects with their members.

An instance is a virtual machine, see Help:Terminology.

Creating an instance

You must have Project Admin rights (see Help:Terminology) in a project to create and manage its instances. You can ask an existing Project Admin in a project to grant you the role.

In a project you can create as many instances as you'd like up to its quota. A wikitech admin can increase a project's limits as needed.

If you are in the cloudadmin group on this wiki, and have two-factor authentication enabled, you can add members to any project.

Before you create an instance, make sure your project has an appropriate security group for the instance's networking needs. For example, a web server or wiki requires access on port 80, the default port for HTTP requests; the security group for this is often named "Web" or "web-servers".

Add Instance link

  1. Make sure you are properly logged in to
    Note: if you see a permissions error at any time, try logging out and then back in.
  2. In the left menu look for the sub-menu group “Labs Projectadmins” (this will only be visible after logging in to wikitech) and click on it to open it.
  3. Click on the menu item “Manage Instances”.
  4. You will be brought to a page that shows an “Instance list”, which is a summary of the projects and instances you are able to manage.
    nb: if you do not see any instances or projects, make sure the “project filter” is open and select the projects you wish to view.
  5. Under the projects listed, you will see the names of the server groups that you can create instances on for your project; most likely, region eqiad.
    nb: openstack regions are groups of servers, server farms, etc. usually located in the same geographical area.
  6. Click on the “Add instance” link.

Initial settings

Instance information

  1. Instance name
    The name of your instance will also be its hostname. Important: it’s a good idea to name your instance using the following format project-instance, e.g, project name is myproject, instance is coolbot, so the resulting instance name would be myproject-coolbot
  2. Instance type
    The drop-down contains a range of possible instance types indicating RAM, number of CPUs, and Hard Drive space. Further information on Instance Types also known as Flavors.
    The drop-down contains a list of system images available with your most likely choice at the top.
  3. Security groups
    A list of available security groups for your instance is listed; select any security groups you think you need for this instance; it is usually best to make sure that at least the default security group is selected.
    nb: if the projectadmin for the project has not created any additional security groups, besides the default group, you will only see the default security group listed; also, before creating your instance, make sure you read the information on Security groups - you cannot add or remove security groups assigned to an instance after it has been created. while security groups can never be added or removed from an instance, after the instance has been created, you can add and remove firewall rules from the already defined and assigned security groups, so, it is usually best to create your necessary security groups before creating your instance, assign those to the instance, and then add/remove rules from those groups as necessary after instance creation.

Build the Instance

When happy with the configuration, click on the [Submit] button.

The instance will be created, but it will be a short while until the instance is ready to be logged into. You can check the process of the build by viewing the instance's console log (see § Managing Instances). When the puppet run finishes, you can log into it with ssh (see Help:Access).

Managing Instances

Once your instance is created it appears as a row in its project's instance list). You can click the instance to get more information about it, and you can perform various actions on the instance:

  • configure: configure the instance using a Puppet configuration listed
  • delete: Delete the instance together with logical volume where OS is stored (your home is preserved)
  • get console output
  • reboot: reboot the instance

Puppet information

Wikimedia Labs uses Puppet to manage instance configurations. You select Puppet configurations after instance creation using the “Configure” link of the instance (next section).

You can also ssh to your instance and administer it from the command line. You can use apt-get (Ubuntu’s documentation, also see Debian's package management) or other package manager if you wish. But if you are developing something that will eventually get deployed to Wikimedia servers, you have to use puppet to configure it, see Help:Self-hosted puppetmaster.

Configuring Instances

When you click configure, you get a list of various puppet roles available for your instance. If you're setting up a test MediaWiki server, role::labs::mediawiki_vagrant is all you need, see MediaWiki Vagrant in Labs.

  • To add specific puppet classes to your project and make them available to your instances, use the Manage Puppet Groups special page.
  • To make changes to the puppet classes available to your instance, check out the puppet configs following the instructions in the help page on Git.

Once you submit the change, you can either run puppet by running

sudo puppet agent -tv

or just wait until puppet runs on your instance. If you encounter a problem running the sudo command above, then you might need be added as a sudo user for the project you're working on. Any user with the projectadmin role for the project can do that – see Help:Sudo policies for more information.


All instances are monitored with Icinga, viewable at; it's possible that once you create an instance it's not immediately configured there, we are now trying to find out some solution to automatize its configuration.

Searching for instances by Puppet role

If you'd like to know which labs instances are currently assigned a Puppet class, you can use the ldapsearch command-line tool. On any labs instance, run:

 ldapsearch -LLL -x -D 'cn=proxyagent,ou=profile,dc=wikimedia,dc=org' \
     -w $(grep -Po "(?<=bindpw).*" /etc/ldap.conf) -b 'ou=hosts,dc=wikimedia,dc=org' \
     'puppetClass=role::beta::logging::mediawiki' 'associatedDomain'

Replace 'role::beta::logging::mediawiki' with the name of the class you are searching for.