Main Page

Access rights

Anonymous users

You'll need to have an account created for you. If you currently have SVN access, then you have an account, but need to have it linked to Labs. We are still working out the account activation process, but hope to have it done soon.

Logged-in users

After creating an account, you can:

• Add and manage your public SSH keys

Once you add a key, you'll be able to log into any existing instance in the main project testlabs: ssh <nameofinstance>. It may take up to 30 minutes for your key to be propagated to all instances.

To create instances, you'll need to have an admin add you to a project, and to the sysadmin role in that project.

You can make queries for nova resources; currently Nova instances have semantic properties enabled.

After logging in, you can also access Gerrit; if you wish to do git checkouts of the puppet repositories, you'll need to log into Gerrit, and add your SSH key there as well. Note: it would be nice if Gerrit could use LDAP for its SSH keystore, instead of its database; I've opened a bug for this, if you'd like to help, please add that feature to Gerrit!

Admins

Wiki Admin

If you are a wiki admin, you can:

• Create/delete Nova projects and manage project and project role membership
• Manage global role membership.
• Manage sudo policies.

Net Admins

If you are a NetAdmin, you can:

• Allocate and associate public IP addresses, and add public DNS entries to instances
• Manage security groups and rules.

Sys Admins

If you are a sysadmin, you can:

• Create or manage instances.
• Create or manage volumes.

After creating an instance, you'll get an email notifying you that it is ready to be logged into. If you did not add an SSH key prior to creating the instance, you'll need to wait until your key is propagated to the instances (which can take an additional 30 minutes).

Cloud Admins

In addition to all actions that sysadmins and netadmins, you can:

• Create or manage DNS domains.

Access FAQ

• Q: I was added to a group that gives me access to something in git, but it isn't working, what's wrong?
  • A: Once you have been added to the group, you need to log out of gerrit, then back in. Gerrit pulls its groups from LDAP, but caches them. Logging out, then back in re-synchronizes your groups, and thus clears the cache.

Git/Gerrit and the puppet repositories

Note: Push access is currently limited to staff developers and operations engineers. This will change soon. To pull the repository anonymously for read access use the following command:

git clone https://gerrit.wikimedia.org/r/p/operations/puppet

Set up your ssh key in Gerrit

Log into the web interface for gerrit. Click on Settings then SSH Public Keys then add your key.

Checking out the puppet repositories

We have the following main repositories and branches:

• operations/puppet
  • production (HEAD)
    • used in production
  • test
    • used in the testlabs project
• labs/private
  • master (HEAD)
    • only used in testlabs project

To check out the production branch of the puppet repo, you can clone it like so (if they're different, shell-username is your unix shell name, not the wiki username.):

git clone ssh://<shell-username>@gerrit.wikimedia.org:29418/operations/puppet.git

To check out the labs/private branch, you can clone it like so:

git clone ssh://<shell-username>@gerrit.wikimedia.org:29418/labs/private.git

Git configuration required to commit

Use git-setup

After the initial clone of the git repository, you can use the git-setup script (in the root level of the repository). It will set your user name, email, and will pull hooks required for proper use of gerrit.

...or do initial git configuration manually

First, you should set your name and email address in your local git configuration. The email address and wiki username are the same as what you use to log into this wiki:

git config --global user.email "<email-address>"
git config --global user.name "<wiki-username>"

Next you'll need to add a commit-msg hook to your local repository. This hook is required for pushing changes to the Gerrit server.

curl "https://gerrit.wikimedia.org/r/tools/hooks/commit-msg" > .git/hooks/commit-msg && chmod u+x .git/hooks/commit-msg

Updating your local repository

After you do the initial repository clone, git will automatically set up a remote tracking branch for you. You simply need to fetch/merge or pull:

git fetch
git diff origin/<branch>
git merge origin/<branch>

or:

git pull

Making changes

After cloning the repo, you can make changes the normal git way:

<make changes>
git add <newfiles>
git commit -a

After doing so, you'll need to push the changes for review; for instance, here's how to push to the test branch of the puppet repository:

git push ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet HEAD:refs/for/test

You can shorten that by adding a remote:

git remote add puppet ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet

Now you can push for review like so:

git push puppet HEAD:refs/for/test

You can shorten this further by making an alias:

git config alias.push-for-review-test "push puppet HEAD:refs/for/test"

Now you can push for review like so:

git push-for-review-test

Here's the alias for production:

git config alias.push-for-review-production "push puppet HEAD:refs/for/production"

Also, staff operations members have the ability to (but shouldn't!) skip the review step; to do so, simply do a push:

git push puppet

Here's the remotes and aliases for the private repo:

git remote add private ssh://<username>@gerrit.wikimedia.org:29418/labs/private
git config alias.push-for-review-private "push private HEAD:refs/for/master"

Review

Review your change (or someone elses!) in Gerrit.

1. Go to https://gerrit.wikimedia.org
   • if it's your own change, you will see it listed on the first screen
   • if it's someone else's, click on 'All' then 'open' to see all unreviewed changes
2. click on the change you want to review
3. click on "Diff all side by side" to examine the diff
   • this will open each changed file in a new tab
4. when you're done reviewing, go back to the parent tab
5. click 'Review'
   1. check +1 Verified
   2. check +2 Reviewed
   3. click "Publish and Submit"

You're done! The change is now merged.

Amending a change

Occasionally your change may fail a lint test, or someone may review your change and ask you to fix something. In this case, you'll need to amend your change. To do this:

1. Checkout the change (you can find this line in Gerrit, on the change, in Download -> checkout, ssh):

   git fetch ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet <ref> && git checkout FETCH_HEAD

2. Make changes
3. Commit the change, ensuring you are amending the commit

   git commit --amend -a

4. Push the change

   git push-for-review production

The above assumes you are pushing to the production branch, change commands appropriately for other branches.

Making the changes live in puppet

Test

Changes merged in the test branch will go live in puppet within a minute. Live meaning the change will be available to others when they pull from the test branch, it is not deployed anywhere.

Production

Public repo

Changes for production need to be pulled manually; this is done for security purposes. Here's the procedure you should use:

cd ~/puppet
git fetch
git diff HEAD origin/production | less
git merge origin/production

Explanations:

The fetch command grabs pending changes in your local repository.

diff HEAD origin/production lets you review them before submitting.

merge origin/production makes you apply the changes to the production branch.

Private repo

cd ~/private
<make changes>
git add <newfiles>
git commit -a

On commit, the changes will go live.

Merging changes from test into production

git pull
git merge --squash origin/test
git commit -a
git push-for-review-production

The above assumes you are in the production branch.

Merging changes from production to test

git pull
git merge --squash origin/production
git commit -a
git push-for-review-test

The above assumes you are in the test branch.

dry runs

• git push has "--dry-run" ("will do everything except for the actually sending of the data.")
• git merge has "--no-commit --no-ff"
• git pull - "does not really need it ('git fetch origin', then a 'git log master..origin/master', before a git merge origin/master)"

[1],[2], [3]

Books, guides, tutorials, documentation, etc.

• Gerrit documentation
• Community git book
• Git for Subversion users
• Why to fetch/merge instead of pull
• Git workflow