Readme.md
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents
- [Sourdough](#sourdough)
- [Testing](#testing)
- [Pre-requisites](#pre-requisites)
- [How to run the tests](#how-to-run-the-tests)
- [FAQs](#faqs)
- [How are node names generated?](#how-are-node-names-generated)
- [EC2](#ec2)
- [Outside EC2](#outside-ec2)
- [How is the runlist determined?](#how-is-the-runlist-determined)
- [EC2](#ec2-1)
- [What Chef environment does Sourdough use](#what-chef-environment-does-sourdough-use)
- [How do I have sourdough pass environment variables to chef-client?](#how-do-i-have-sourdough-pass-environment-variables-to-chef-client)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Sourdough
[](https://opensource.org/licenses/Apache-2.0)
[](https://circleci.com/gh/unixorn/sourdough)
[](https://codeclimate.com/github/unixorn/sourdough)
[](https://codeclimate.com/github/unixorn/sourdough)
[](https://github.com/unixorn/git-extra-commands/stargazers)
[](https://github.com/unixorn/sourdough)
Sourdough is a tool to install `chef-client` during instance boot, or to run `chef-client` after boot.
Sourdough reads the **Environment** and **Runlist** EC2 / VMware tags and runs `chef-client` with those settings so you can update an instance's Chef settings just by tweaking its tags. This also lets you see what runlist and environment an instance has using just the AWS/VMware webui, so no more having to correlate Chef information for your instances in two places.
# Testing
## Pre-requisites
You must have `docker` and `docker-compose` installed on your machine to run the test suite.
## How to run the tests
`make test` will build a container, then run the tests inside the container with `docker-compose`.
**WARNING** only run the tests inside a disposable container - they _will_ **_destroy_** the chef installation on your machine.
# Uploads
1. Make sure you're on the right branch and that you've updated the version in `setup.py`
2. `make wheel`
3. `make upload`
# FAQs
## How are node names generated?
### EC2
If we're in EC2, we look for a Node tag/knob. If a Node tag or knob exists, our node name will be **AWS_REGION-NODE_TAG_KNOB-INSTANCE_ID**
If the node tag and knob don't exist, we look for a Hostname tag or knob and set the node name to **AWS_REGION-HOSTNAME_TAGKNOB**.
If the Hostname tag or knob are both missing we fail back to reading the output of `hostname` which is better than nothing.
### Outside EC2
If we aren't in EC2, we look for a `/etc/knobs/Hostname` file and use the
contents of that - if there's no knob file we use the output of
`hostname` so we have at least something sane-ish.
## How is the runlist determined?
### EC2 / VMware
First we attempt to read the instance's **Runlist** tag and set the runlist to that. If we can't reach AWS/vSphere to read a tag, we search for `/etc/knobs/Runlist` and use the contents of that. If we still haven't found a **Runlist** setting we look for a **default_runlist** entry in `/etc/sourdough/sourdough.toml`. Once we determine a Runlist, we write it to `/etc/knobs/Runlist` to use as a fallback on future runs.
## What Chef environment does Sourdough use
Similarly to how it determines the Runlist, `sourdough` looks for an **Environment** tag for the instance, and if that is missing, looks for `/etc/knobs/Environment`, and finally falls back to looking for a **default_environment** entry in `/etc/sourdough/sourdough.toml`
## How do I have sourdough pass environment variables to chef-client?
`sourdough` will look for `/etc/sourdough/environment-variables.json`, and if present and _valid JSON_, will pass the variables inside to `chef-client` when it runs it.
## VMware Vcenter configuration
`sourdough` will look for `/etc/sourdough/vmware.toml`, and if present and _valid toml_, it will search for the UUID of the VM in the vSphere host(s) listed there. Check the `example_vmware.toml` file for configuration details.