PageRenderTime 28ms CodeModel.GetById 22ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 1ms

/docsite/rst/playbooks_vault.rst

https://github.com/ajanthanm/ansible
ReStructuredText | 97 lines | 53 code | 44 blank | 0 comment | 0 complexity | 239a2d91e4f08742f5cbc79c380bd348 MD5 | raw file
 1Vault
 2=====
 3
 4.. contents:: Topics
 5
 6New in Ansible 1.5, "Vault" is a feature of ansible that allows keeping encrypted data in source control.
 7
 8To enable this feature, a command line tool, `ansible-vault` is used to edit files, and a command line flag `--ask-vault-pass` or `--vault-password-file` is used.
 9
10.. _what_can_be_encrypted_with_vault:
11
12What Can Be Encrypted With Vault
13````````````````````````````````
14
15The vault feature can encrypt any structured data file used by Ansible.  This can include "group_vars/" or "host_vars/" inventory variables, variables loaded by "include_vars" or "vars_files", or variable files passed on the ansible-playbook command line with "-e @file.yml" or "-e @file.json".  Role variables and defaults are also included!
16
17Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault.  If you'd like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted.  However, that might be a little much and could annoy your coworkers :)
18
19.. _creating_files:
20
21Creating Encrypted Files
22````````````````````````
23
24To create a new encrypted data file, run the following command::
25
26   ansible-vault create foo.yml
27
28First you will be prompted for a password.  The password used with vault currently must be the same for all files you wish to use together at the same time.
29
30After providing a password, the tool will launch whatever editor you have defined with $EDITOR, and defaults to vim.  Once you are done with the editor session, the file will be saved as encrypted data.
31
32The default cipher is AES (which is shared-secret based).
33
34.. _editing_encrypted_files:
35
36Editing Encrypted Files
37```````````````````````
38
39To edit an encrypted file in place, use the `ansible-vault edit` command.
40This command will decrypt the file to a temporary file and allow you to edit
41the file, saving it back when done and removing the temporary file::
42
43   ansible-vault edit foo.yml
44
45.. _rekeying_files:
46
47Rekeying Encrypted Files
48````````````````````````
49
50Should you wish to change your password on a vault-encrypted file or files, you can do so with the rekey command::
51
52    ansible-vault rekey foo.yml bar.yml baz.yml
53
54This command can rekey multiple data files at once and will ask for the original
55password and also the new password.
56
57.. _encrypting_files:
58
59Encrypting Unencrypted Files
60````````````````````````````
61
62If you have existing files that you wish to encrypt, use the `ansible-vault encrypt` command.  This command can operate on multiple files at once::
63 
64   ansible-vault encrypt foo.yml bar.yml baz.yml
65
66.. _decrypting_files:
67
68Decrypting Encrypted Files
69``````````````````````````
70
71If you have existing files that you no longer want to keep encrypted, you can permanently decrypt them by running the `ansible-vault decrypt` command.  This command will save them unencrypted to the disk, so be sure you do not want `ansible-vault edit` instead::
72
73    ansible-vault decrypt foo.yml bar.yml baz.yml
74
75.. _running_a_playbook_with_vault:
76
77Running a Playbook With Vault
78`````````````````````````````
79
80To run a playbook that contains vault-encrypted data files, you must pass one of two flags.  To specify the vault-password interactively::
81
82    ansible-playbook site.yml --ask-vault-pass
83
84This prompt will then be used to decrypt (in memory only) any vault encrypted files that are accessed.  Currently this requires that all passwords be encrypted with the same password.
85
86Alternatively, passwords can be specified with a file.  If this is done, be careful to ensure permissions on the file are such that no one else can access your key, and do not add your key to source control::
87
88    ansible-playbook site.yml --vault-password-file ~/.vault_pass.txt
89
90The password should be a string stored as a single line in the file.
91
92This is likely something you may wish to do if using Ansible from a continuous integration system like Jenkins.
93
94(The `--vault-password-file` option can also be used with the :ref:`ansible-pull` command if you wish, though this would require distributing the keys to your nodes, so understand the implications -- vault is more intended for push mode).
95
96
97