Usage
See the Install Home for mu master installation instructions
You can access the master via the root account or a privileged or unprivileged user account. The overall paradigm is:
- Develop your deployments in a user account
- Use a privileged user account or the root account for production deploys
Since each account has its own namespace in Mu and Chef this will allow you to have more than one person working on common components without stepping on each other. Manage your merges via Git.
For simplicity we'll describe usage from the point of view of the root account. The main difference in user accounts is that the path for platform deployment repositories is local to the user at ~/.mu/var instead of in /opt/mu/var for root. And, of course, the unprivileged user cannot access common components, which are reserved for the enterprise and production.
Working from the point of view of root, mu shared artifacts live in the /opt/mu directory unless you've selected different MU_INSTALLDIR. You'll see:
bin: holds the mu tooling binaries, rebuilt every time you update mu etc: holds environmental information -- most importantly the mu.rc file with ENV variables lib: holds the actual mu tooling that supports and updates the binaries var: is the MU_DATADIR (unless you changed it in setup) and holds the repositories for your platform deploys
Mu comes configured to use github for its repositories, but any git repository will suffice. Mu itself is cloned into $MU_INSTALLDIR/lib.
In addition, you'll create a "platform repository" in git for each deploy or group of deploys you want to manage. A single platform repository can hold multiple deployments, but be aware that the entire repository is uploaded to Chef memory as a whole. Partition your projects accordingly so you don't step on yourself.
You can have as many project repositories as you need. Add more repositories after the initial install by running mu-configure (below)
Use the mu tooling's commands to do your actual work. Each command has an -h option for help
| Command | Purpose |
|---|---|
| mu-cleanup | Clean up a deploy with its dozens of artifacts in aws and on server |
| mu-deploy | Deploys a stack, including dry run and keep alive on fail |
| mu-node-manage | Carry out individual and bulk management operations on nodes |
| mu-momma-cat | Fires up the management process |
| mu-self-update | Updates the binaries from latest code |
| mu-upload-chef-artifacts | Uploads current cookbooks |
| mu-user-manage | Add, delete, or modify users |
Lesser known commands, used mainly in setup:
| Command | Purpose |
|---|---|
| mu-firewall-allow-clients | Opens master firewall to nodes |
| mu-gen-docs | Generates the online documentation |
| mu-load-murc.rb | Loads up the rc file in /opt/mu/etc or elsewhere in user account. Used in setup |
| mu-aws-setup | Manage relationship between master and AWS account re EIPs, SG, log buckets, etc |
This is a typical development cycle for deploys using mu tooling:
- Create your repository in /opt/mu/var if not already there with a git clone
- Build or test your BOK with a mu-deploy –d
- Carry out your deploy with a mu-deploy
- List nodes with knife node list, or look at /opt/mu/var/deployments or local equivalent
- ssh as needed with node name, see what's up on the node.
- Destroy your deploy with a mu-cleanup
mu-upload-chef-artifacts handles the synchronization of your local and foreign Chef recipe repositories into your Cloudamatic master. We use Berkshelf for coordination with remote cookbooks.
# mu-upload-chef-artifacts -h
Syncs Chef code to running Chef master. Optionally refreshes from git.
Usage: /opt/mu/lib/bin/mu-upload-chef-artifacts [-a|-r repo_name[:branch] [-r repo_name[:branch] [...]]] [-f [-c <commit>] ] [-d] [-n] [-s]
-f: Forcibly re-sync Chef repos from Git before uploading
to Chef. Saves your working changes unless -d is specified.
-c <commit> (requires -f and at most one -r): Reset to a specific commit.
-d: Discard any uncommited changes to currently checked-out branches.
-n: No purging of Chef resources, just uploads new Chef data without
expunging old resources from the running server.
-s: Shortcut mode. Update cookbooks only. Implies -n.
-a: Upload currently checked-out branch from ALL Chef repos. Cannot be used
with -c or -r.
-b <branchname>: Upload the named branch from ALL Chef repos. Useful if
you want to use, for example, only master from every repo.
-r: A Chef artifact repository to upload. Can specify multiple. See list
below. Optionally, specify a branch by appending :branchname (this will
override -b).
Known Chef artifact repositories, as set by mu-configure. Ordered
from lowest priority to highest:
mu
myorg_platform
Example uses:
Upload Chef code from currently checked-out branches of all known repositories, but skip purging existing Chef artifacts from the running server:
mu-upload-chef-artifacts -n
Upload Chef code from whatever Mu branch is currently checked out, and from the newfeature branch of the myrepo repository:
mu-upload-chef-artifacts -r mu -r myrepo:newfeature
Upload Chef code from all known repositories, forcing them to use the master branch:
mu-upload-chef-artifacts -b master
Upload Chef code from all known repositories, forcing them to use the master branch, resetting to the last commit and discarding all unstaged changes:
mu-upload-chef-artifacts -f -d -b master
mu-self-update manages your local copy of the Mu deployment tools and baseline Chef recipes. Its main use is to switch between Git branches to work with experimental features.
# mu-self-update -h
Updates Mu scripts in /opt/mu/lib/bin. Optionally refreshes from git.
Usage: /opt/mu/lib/bin/mu-self-update [-b <branch>] [-f [-c <commit>] ] [-d]
-f: Forcibly re-sync /opt/mu/lib from Git. Saves your
working changes unless -d is specified.
-c <commit> (requires -f): Reset to a specific commit.
-b <branch>: Use a branch in /opt/mu/lib other than master.
-d: Discard local changes to current branch.
mu-configure can be used to reconfigure the parameters of your Cloudamatic master. It works identically to mu_setup. Your configuration is stored in ~/.murc by default.
mu-deploy creates a deployed application stack from a .json description file. See the applications/ directory of your Mu repository for examples.
mu-cleanup removes an application stack created by mu-deploy
Things rarely go as planned the first time. Here are some tips:
- For BOK’s use the –d for dryrun
- Can use either JSON or YAML
- For nodes that will not bootstrap, get the key from .ssh/deploy*, ssh to bastion, ssh to instance, run chef-client
- Grooming problems – ssh to node, and rerun userdata, trace mu-momma-cat.log on master. Userdata is in /var/lib/cloud/instance/user-data.txt
Often you want to iterate on the configuration phase until it's just right.
This technique makes use of the mu tooling to repeat the configuration portion of a deploy
- Find recipe in mu repository (/opt/mu/var/MYREPO…) and modify
- mu-upload-chef-artifacts –r MYREPO [-n –s] (note that the switches will speed things by only uploading changed cookbooks, but if you've changed a role or something noncookbook you will miss the change with the switches)
- ssh to node and rerun chef-client. You can narrow things down to the one cookbook with the -o switch
This technique bypasses mu's upload process for a faster but very unofficial turnaround
- Find recipe in local cache and modify it. For root the local cache is in /root/.chef
- Upload the modified cookbook with knife cookbook upload
- ssh to node and rerun chef-client, maybe with -o
This technique is a way to work directly on a node without going back and forth to the master. It can be very productive when you're doing iterative cookbook development, especially from scratch
Here's what we do:
- Get node attributes from the master with knife node edit or knife node show - something like
knife node show -f json "NODENAMEFROMDEPLOY" - Get node environment from master with knife environment with
knife environment show [your env name] -f json - ssh to node
- Copy the cookbook cache that master put on the node to ~/cookbooks. Depending on your node OS the commmand will look something like
cp -R /var/chef/cache/cookbooks/ /root - Create skeleton local nodes/attributes by running chef-client -z
- Edit the local node skeleton in ~/nodes by replacing its contents with node attributes from master
- Create ~/environments and put the environment from the master there
- Run locally with chef-client –local-mode –l info –o cookbookname
Here's an example of a command:
chef-client --local-mode -l info -E mytestenv -o somecookbook::somerecipe
The cookbook will be run from the local copy in ~/cookbooks. No need to upload or anything like that. Edit, rerun, etc.