Working with Ansible Cake

Ansible Cake is a wrapper tool for executing ansible-playbook commands which abstracts each ansible command into a easy to memorize function name like cus_www_prod_php.

The Ansible Cake Docker container provides an environment with all tools required to operate the playbook-infrastructure-company.

./start-cake.sh

Start your wireguard VPN before starting Ansible Cake. When you connect after, the wireguard NIC will not be available inside the docker container.

To start Ansible Cake inside your playbook-infrastructure-company:

# Clone the playbook repository
mkdir -p ~/code/git/git.cus.int/
git clone git@git.cus.int:ansible/playbook-infrastructure-company.git ~/code/git/git.cus.int/
cd ~/code/git/git.cus.int/playbook-infrastructure-company

# Start the Docker container
./start-cake.sh

tmux

After ./start-cake.sh you are inside a Docker container which runs a BASH shell with tmux.

tmux commands in a nutshell:

Key combination	Description
CRTL + b - d	detach from Ansible Cake's tmux and the docker container shell
tmux ls	list running tmux sessions (run outside cake)
tmux attach -t ansile-cake	get back into the tmux (run outside cake)
CRTL b + %	Split screen vertically
CRTL b + \"	Split screen horizontally
Resize screen borders	Drag split screen borders with mouse to resize
CRTL + b - z	make a pane full sized. Use that again to get to its original size again
CRTL b + c	Create a new window (workspace)
CRTL b + ,	Rename current window
CRTL b + 0..9	Switch to window 0 (default) up to 9
CRTL b + w	Choose window from list
Copy Paste	Keep SHIFT pressed while selecting text or left / right clicking

cake Arguments

cake can be executed with the following arguments:

Argument	Long Argument	Description
-h	--help	Print link to documentation
-lf	--list-functions	List all cake functions
-s	--search string	Search all cake functions names for the given string
-f	--function function_name	Execute a given cake function
-i	--inventory inventory_name	Use the specified inventory (normally pub or vpn, default: vpn)
-l	--limit target,target	Limit ansible commands to a specific host, group or list hosts and groups
-t	--tags tag,tag	Limit ansible roles to only execute tasks matching the given tags
-nc	--no-check	Disable ansible check mode (always on by default)
-p	--print-unchanged	Display unchanged tasks / hosts
-v	--verbose	Verbose output
-vv	--very-verbose	Very verbose output
-d	--debug	Debug output

Examples:

# List all available functions
cake -lf

# Search for a specific function
cake -s nginx

# Run the function \"debug_ping\"
cake -f debug_ping

# Run the function \"provisioning_accept_ssh\" with the inventory \"inventory/pub.yml\"
cake -f provisioning_accept_ssh -i pub

# Run a function and use --limit, --tags and --verbose
cake -f cus_www_prod_web -l cus_www_prod_web --tags apt,config -v

# Run the function \"baseline_shorewall\" using --limit and show changes
cake -f www_prod_web_apache2 -l cus_www_prod_web -p

# Run a function with WITHOUT --check, where the console output is tee'd to a changelog file
cake -f 'util prod' -nc

cake Helpers

cake has several small helper tools designed to make life simpler:

Name	Description
setup	Run initial setup steps when using cake the first time
ssh [user] [vpn/pub]	SSH to a host matching in inventory/hosts (Default user: root, default connection: vpn)
shell [vpn/pub] "[command]"	Run a command on a single or group of hosts matching in inventory/hosts (quote the command!)
pwgen	Generate a random password and save it in pass as
log [grep-string]	Browse and view changelog files. Use [grep-string] to limit logfile names matching it
roles [-u	-r]
status [prom,borg,stat] [hosts]	Shows prometheus alerts, borg backups and ressource usage of all or, if specified, only given hosts (only complete inventory_hostname works)
grep [grep-string]	recursively greps a string below inventory/, plays/, terraform/ and cake.conf.sh

Examples:

# Before using cake the first time
cake setup

# SSH to a specific host
cake ssh git-1 git pub

# Restart shorewall on a group of hosts
cake shell cus_www_prod vpn "shorewall restart"

# Generate a secure password named www_prod_apache2_htpasswd
cake pwgen www_prod_apache2_htpasswd

# View changelog files
cake log

# Grep changelog files for a specific string
cake log letsencrypt

# ansible-galaxy update roles
cake roles

# Show monitoring alerts and backups but not ressource usage of only selected instances
cake status "back prom" "cus-util-prod-backup-1,cus-tool-prod-sentry-1"

# grep -r a string in the playbook files
cake grep "some string"

Additional tools

The following additional tools are available inside Ansible Cake:

# Start a firefox browser with all of the utility stack WebUIs (requires Ubuntu or Debian Linux workstation)
browser

# Start a ncurses GnuPG management tool
gpg-tui

cake.conf.sh

All commands required to manage the infrastructure are saved in the file cake.conf.sh. Each command is assigned its own BASH function, which can be executed via cake -f name_of_function.

Examples:

# Manage MariaDB on cus_www_stag
cus_www_stag_mariadb() {        ansible-playbook plays/customers/cus/www/stag/mariadb.yml $CAKE_ARGS; }

# Manage the floating IP on the cus_www_prod loadbalancer
cus_www_prod_lb_floating_ip() { ansible-playbook plays/customers/cus/www/prod/floating-ip/main.yml $CAKE_ARGS; }

# Manage the cloud instances in the group cus_tool_prod
terraform_cus_tool_prod() {
    cd terraform/hcloud/cus_tool_prod
    terraform init
    terraform apply
}

To create a group of functions that will be executed in sequence:

cus_project_prod() {
    run cus_project_prod_nginx
    run cus_project_prod_mariadb
    run cus_project_prod_php
}

You can run multiple functions in parallel, which will open one horizontal tmux pane for each run_tmux statement. You can use your mouse to resize the borders of each pane.

To wait for all tmux panes to finish before continuing, use the wait_tmux statement.

cus_tool_prod() {
     run_tmux cus_project_stag_nginx
     run_tmux cus_project_stag_php
     wait_tmux
     run_tmux cus_project_prod_nginx
     run_tmux cus_project_prod_php