{"id":3352,"date":"2018-05-12T15:40:36","date_gmt":"2018-05-12T20:40:36","guid":{"rendered":"https:\/\/dev.iachieved.it\/iachievedit\/?p=3352"},"modified":"2018-05-12T15:40:36","modified_gmt":"2018-05-12T20:40:36","slug":"ansible-and-aws-part-3","status":"publish","type":"post","link":"https:\/\/dev.iachieved.it\/iachievedit\/ansible-and-aws-part-3\/","title":{"rendered":"Ansible and AWS – Part 3"},"content":{"rendered":"

This is the third article in a series looking at utilizing Ansible<\/a> with AWS<\/a>. So far the focus has been Ansible itself, and we’ll continue that in this post and look at the Ansible Vault<\/a>. The final version of the Ansible playbook are on the part3<\/code> branch of this repository<\/a>.<\/p>\n

You will frequently come across occasions where you want to submit something that needs to be kept secret to a code repository. API keys, passwords, credentials, or other sensitive information that really is<\/i> a part of the configuration of a server or application, and should<\/i> be revisioned controlled, but shouldn’t<\/i> be exposed to “the world” are great candidates for things to lock up in an Ansible vault. I’ll illustrate several different applications of a vault, and then share a great technique for diffing vault files.<\/p>\n

Vault It!<\/h2>\n

Any file can be encrypted (vaulted) with the ansible-vault<\/code> command. now.txt<\/code> contains:<\/p>\n

[code lang=text]
\nNow is the time for all good men to come to the aid of their country.
\n[\/code]<\/p>\n

Let’s encrypt it with ansible-vault<\/code>:<\/p>\n

[code lang=text]
\n# ansible-vault encrypt now.txt
\nNew Vault password:
\n[\/code]<\/p>\n

Type in a good password and you’ll be prompted to confirm it. If the passwords match you’ll see Encryption successful<\/code>. Now, cat<\/code> the file:<\/p>\n

[code lang=text]
\n# cat now.txt
\n$ANSIBLE_VAULT;1.1;AES256
\n30323261363061623735613964633862613232393261323638396435373561396237313161336531
\n…
\n33363033636132353034306130383064306264613935353133386664613062613438383361663462
\n33393438396236383230
\n[\/code]<\/p>\n

You’ll notice that ansible-vault<\/code> did not change the name of your file or add an extension. Thus from looking at the filename you can’t tell this file is a “vault” file.<\/p>\n

To edit the file, use ansible-vault edit now.txt<\/code>. You’ll be prompted for the password (I hope you remember it!), and if provided successfully ansible-vault<\/code> will open the file with the default editor (on my Mac it’s vi<\/code> but you can set the EDITOR<\/code> shell variable explicitly). Make any changes you like and then save them in your editor. ansible-vault<\/code> will reencrypt the file for you automatically.<\/p>\n

ansible-vault view<\/code> is another handy command; if you just want to look at the contents of the file and not edit them use ansible-vault view FILENAME<\/code> and supply the password.<\/p>\n

Practical Use<\/h2>\n

The most practical use of the vault capability is to protect sensitive information such as API keys, etc. We’re going to use it for two applications: encrypt AWS IAM credentials for accessing an S3 bucket, and an SSL certificate key.<\/p>\n

First though, let’s talk about where to put the actual variables. We could put them in vars.yml<\/code> and then encrypt the entire file. This is overkill. Better is to create a file called vault<\/code> (so we know it’s a vault!) and put our values there. But<\/i>, we’re going to use a little indirection technique like this:<\/p>\n

vault<\/code>:<\/p>\n

\n---\nVAULT_AWS_ACCESS_KEY:  theAwsAccessKey\nVAULT_AWS_SECRET_KEY:  theAwsSecretKey\n<\/pre>\n
By the way, to be clear, the vault<\/code> file here is located in our host_vars<\/code> directory for the target host, alongside our vars.yml<\/code> for that host<\/i>.<\/p>\n
vars.yml<\/code>:<\/p>\n
\n---\nHOSTNAME:  helloworld\n\nAWS_ACCESS_KEY:  '{{ VAULT_AWS_ACCESS_KEY }}'\nAWS_SECRET_KEY:  '{{ VAULT_AWS_SECRET_KEY }}'\n<\/pre>\n
Again, this is the vars.yml<\/code> file we created previously for our host.<\/p>\n
Our playbooks and template files will reference AWS_ACCESS_KEY<\/code> and AWS_SECRET_KEY<\/code> which in turn will get their values from the vault.  In this manner you can quickly view your vars.yml<\/code> and know which values you get from the vault (hence the prefix VAULT_<\/code>).  NB<\/b>:  This is purely a convention I’ve come to find to be extremely useful!<\/p>\n
The Real Thing<\/h3>\n
To access S3 buckets we’re going to use the s3cmd<\/code> package, so let’s add it to our playbook apt<\/code> task:<\/p>\n
\n  - name:  Install base packages\n    apt:\n      name:  \"{{ item }}\"\n      state: present\n      update_cache: yes\n    with_items:\n      - htop\n      - zsh\n      - s3cmd\n<\/pre>\n
Then, in our AWS console we’ll create a new IAM user named S3Reader<\/code> and give it Programmatic access<\/code>.  For this user we can Attach existing policies directly<\/code> and use the existing policy AmazonS3ReadOnlyAccess<\/code>.  You should be given both an access key and a secret key.  We’ll plug these both in to our vault<\/code> file and then encrypt it with ansible-vault encrypt<\/code>.<\/p>\n
Even though s3cmd<\/code> is installed, it needs a configuration file .s3cfg<\/code>.  We’re going to create one with our credentials (the ones just obtained), again through the use of the template<\/code> task.  Create a file in the templates<\/code> directory called s3cfg.j2<\/code> (make note we aren’t putting a dot in front of the file) with the following content:<\/p>\n
[code lang=text]
\n[default]
\naccess_key={{ AWS_ACCESS_KEY }}
\nsecret_key={{ AWS_SECRET_KEY }}
\n[\/code]<\/p>\n
Now, add the template<\/code> task that will create the .s3cfg<\/code> file:<\/p>\n
\n  # Create .s3cfg\n  - name:  Create .s3cfg\n    template:\n      src:   s3cfg.j2\n      dest:  \/home\/ubuntu\/.s3cfg\n      user:  ubuntu\n      group: ubuntu\n<\/pre>\n
Note the use of the user<\/code> and group<\/code> parameters for this task.  The file is being created in the \/home\/ubuntu\/<\/code> directory and since our Ansible playbook is issuing commands as the root<\/code> user (the become_user<\/code> directive in the playbook we’ve glossed over thus far), it would have, by default, set the owner and group of the file to root<\/code>.  We don’t want that, so we explicitly call out that the user and group should be set to ubuntu<\/code>.<\/p>\n
Execute your playbook, this time including --ask-vault<\/code> to ensure you get prompted for your vault password (we’ll show you in a minute how to set this in a configuration file).<\/p>\n
[code lang=text]
\n# ansible-playbook playbook.yml –ask-vault
\n[\/code]<\/p>\n
If everything was done correctly you’ll have a new file .s3cfg<\/code> in your \/home\/ubuntu<\/code> directory that has your S3 credentials (the ones you placed in the vault<\/code> file).  Indeed, we can now run the s3cmd ls<\/code>:<\/p>\n
[code lang=text]
\nubuntu@helloworld:~$ s3cmd ls
\n2016-10-01 14:06  s3:\/\/elasticbeanstalk-us-east-1-124186967073
\n2017-10-04 00:20  s3:\/\/iachievedit-cbbucket
\n2015-12-21 23:47  s3:\/\/iachievedit-repos
\n…
\n[\/code]<\/p>\n
Nice.<\/p>\n
key.pem<\/h3>\n
If you run a website you’re undoubtedly familiar with SSL certificates<\/a> and the need to have one (or more).  You’re also familiar with the private key<\/a> for your certificate (unless you started your career with Let’s Encrypt<\/a> and it’s abstracted some of the “magic”).  That private key is, strictly speaking, a part of the server configuration, and we want everything on our server to be revisioned controlled, including that private key.  So let’s vault it.<\/p>\n
I have a private key named key.pem<\/code> and the contents look like what you’d expect:<\/p>\n
[code lang=text]
\n# cat key.pem
\n—–BEGIN PRIVATE KEY—–
\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDDXnM+DZ0tTn9M
\n38CRP2dwOuRJhH3xRc3WcTmL1S+EIxdFGIffy0+YVXU9Uzbn0XDl0TgtfZwBcMeU
\n…
\nwVumMxo0FpnH9Wb3QtVwlv1zxaW2VakRvdiZ31PkUWK7oCkFJPVj0yGe\/MDsCfQX
\nlCDhi\/ncV+DL\/FWXgPafUIA=
\n—–END PRIVATE KEY—–
\n[\/code]<\/p>\n
We don’t want to submit this as-is to revision control, so let’s encrypt it with ansible-vault<\/code> and put it in a directory called files<\/code>.<\/p>\n
[code lang=text]
\n# ansible-vault encrypt $HOME\/key.pem
\n# cd ansible-helloworld
\n# mkdir files
\n# cp $HOME\/key.pem files\/
\n[\/code]<\/p>\n
Note here that you will want to use the same vault password as you did for vault<\/code>.  Also, the directory files<\/code> (like templates<\/code>) is a special name to Ansible.  Don’t call it file<\/code> or my_files<\/code>, etc., just files<\/code>!<\/p>\n
Our key.pem<\/code> will be copied to \/etc\/ssl\/private<\/code>, so let’s create a task for that in the playbook:<\/p>\n
\n  # Copy key.pem\n  - name:  Copy key.pem\n    copy:\n      src:  key.pem\n      dest: \/etc\/ssl\/private\n      mode: 0400\n<\/pre>\n
If you run the playbook now and then check \/etc\/ssl\/private\/key.pem<\/code> on your server you’ll see that Ansible decrypted<\/i> the file and stored the decrypted contents; precisely what we wanted!<\/p>\n
Your Vault Password<\/h3>\n
If you grow tired of supplying the vault password to --ask-vault<\/code> each time you run a playbook, or even when using ansible-vault edit<\/code> you can save the password in plain text in your home directory or other secure location.  This is an example of a file you would not<\/i> submit to revision control!<\/p>\n
[code lang=text]
\n# export ANSIBLE_VAULT_PASSWORD_FILE=~\/.ansible_vault_pass.txt
\n# ansible-playbook playbook.yml
\n[\/code]<\/p>\n
The file ~\/.ansible_vault_pass.txt<\/code> contains the vault password in the clear.  Add the environment variable ANSIBLE_VAULT_PASSWORD_FILE<\/code> to your shellrc file (e.g., .zshrc<\/code>, .bashrc<\/code>, etc.) to make things even simpler.<\/p>\n
Vault Diffs<\/h2>\n
I found this one weird trick just the other day and it’s a lifesaver if you are responsible for reviewing changes to API keys, passwords, etc.  Courtesy of Mark Longair<\/a> on Stack Overflow<\/a>.<\/p>\n
We have two “vaulted” files in our repository, a file named vault<\/code> in our host_vars<\/code> directory and key.pem<\/code>.  We’d like to easily diff them for changes, so following along with the Stack Overflow post, create a .gitattributes<\/code> file with:<\/p>\n
[code lang=text]
\nhost_vars\/*\/vault diff=ansible-vault merge=binary
\nfiles\/key.pem diff=ansible-vault merge=binary
\n[\/code]<\/p>\n
Then, set the diff driver for files with that diff=ansible-vault<\/code> attribute:<\/p>\n
[code lang=text]
\n# git config –global diff.ansible-vault.textconv "ansible-vault view"
\n[\/code]<\/p>\n
With this, if you make changes to your vaulted files, a git diff<\/code> will automatically show you the actual diff vs. the encrypted diff (which is, obviously, unreadable).<\/p>\n
Final Thoughts<\/h2>\n
Credentials, API keys, passwords, private keys.  It’s been hammered in your head to not submit those to revision control systems, and rightfully so if they aren’t encrypted.  But these pieces of information are critical to the successful build of a server or environment, and part of the charm that Ansible brings is the ability to rebuild a server (or sets of servers) and not worry about whether or not you missed a step.  With the Ansible vault, however, you can encrypt this information and include it alongside the rest of your Ansible playbook; supply the vault password and watch the magic happen.<\/p>\n
This Series<\/h2>\n
Each post in this series is building upon the last.  If you missed something, here are the previous posts.  We’ve also put everything on this Github repository<\/a> with branches that contain all of the changes from one part to the next.<\/p>\n