Package: ploy-ansible
OverviewThe ploy_ansible plugin provides integration ofAnsiblewithploy.
It automatically builds aninventoryand provides a custom connection plugin.Installationploy_ansible is best installed with easy_install, pip or with zc.recipe.egg in a buildout.CommandsThe plugin adds the following commands to ploy.configureConfigures an instance.
There are three ways to specify how to configure an instance.
Applying the roles given by therolesoption of an instance, a playbook set by theplaybookoption or a playbook with the unique name of the instance found in theplaybooks-directory.
Usingrolesor a playbook is mutually exclusive.
If you specify a playbook and there is also a playbook in the default location, you will get a warning.inventoryLists all known groups and their associated hosts, including regular default groups, such asallbut also implicit,ploy_ansiblegroups such as instances of a particularmaster(i.e. allez-instancesof anez-master)ansibleRuns an Ansible command.
This basically reflects theansiblescript of Ansible.playbookApplies a playbook.
This basically reflects theansible-playbookscript of Ansible.vaultManages file encryption.
This basically reflects theansible-vaultscript of Ansible, but handles the encryption key source viaploy.conf.vault-keyManages the vault key.OptionsGlobalplaybooks-directoryTheplaybooks-directoryoption of theansiblesection allows you to specify the directory where playbooks, roles, host_vars etc are looked up.
If you specify a relative path, then it’s always relative to theploy.confdirectory.
If you have a structure like this:project
|-- deployment
| |-- roles
| |-- host_vars
|
|-- etc
  |-- ploy.confThen you would put the following into yourploy.conf:[ansible]
playbooks-directory = ../deploymentBy default it is set to the parent directory of the directory theploy.confis located at like this:project
|-- roles
|-- host_vars
|-- etc
  |-- ploy.confvault-password-sourceUsing thekeyringlibrary, you can store the encryption key for the Ansible vault in your keychain.Thevault-password-sourceoption is the id used in your keychain.
The id must be unique among all people who have to use the feature, as it is used as an identifier in their keychain.
If in doubt, use a speaking prefix and add a guid by runningpython-c"import uuid;print(uuid.uuid4().hex)".If you want to rekey your files, you have to put the old id into thevault-password-old-sourceoption and set a new id invault-password-source.
Just incrementing a number or appending a new guid is best.Example:[ansible]vault-password-old-source=my-domain-deployment-0da2c8296f744c90a236721486dbd258vault-password-source=my-domain-deployment-042a98b666ec4e4e8e06de7d42688f3bYou can manage your key with thevault-keycommand.
For easy exchange with other developers, you can also export and import the key via gpg using thevault-keyexportandvault-keyimportcommands.Per instancegroupsWhitespace separated list of Ansible group names this instance should be added to in addition to the default ones.rolesUsed by theconfigurecommand.
This allows you to configure an instance by applying the whitespace separated roles.
This is like creating a playbook which only specifies a host and a list of roles names.
If thesudooption is set, it’s also set for the generated playbook.playbookAllows you to explicitly specify a playbook to use for this instance.
If you needsudo, then you have to add it yourself in that playbook.Any option starting withansible_is passed through to Ansible as is. This can be used for settings likeansible_python_interpreter.Any option starting withansible-is stripped of theansible-prefix and then passed through to Ansible.
This is the main way to set Ansible variables for use in playbooks and roles.All other options are prefixed withploy_and made available to Ansible.Ansible inventoryAll instances inploy.confare available to Ansible via theirunique id.The variables for each instance are gathered fromgroup_vars,host_varsand theploy.conf.Ansible lookup pluginsTheploy_cryptedlookup plugin can be used in playbooks to read the content of encrypted files.
This is another way to access encrypted data where you don’t have to move that data into yml files.
An added benefit is, that the file is only decrypted when it is actually accessed.
If you run tasks filtered by tags and those tasks don’t access the encrypted data, then it’s not decrypted at all.WarningThis lookup plugin only works with files that are plain ascii or utf-8.
It’s a limitation caused by the way ansible handles variable substitution.API usageOn the Python side, each ploy instance gains the following methods:apply_playbook(self, playbook, *args, **kwargs)Applies theplaybookto the instance.has_playbookReturnTrueif the instance has either of therolesor a playbook option set.get_playbook(*args,**kwargs)Returns an instance of the Ansible internalPlayBookclass.
This is either from a file (fromplaybookoption or the playbook kwarg), or dynamically generated from therolesoption.configure(*args,**kwargs)Configures the instance with the same semantics as theconfigurecommand.get_ansible_variablesReturns the Ansible variables from the inventory.
This does not includefacts, as it doesn’t connect to the instance.
This is particularly useful in Fabric scripts.get_vault_libReturns a readily usable Ansible VaultLib class.
Use theencryptanddecryptmethods do encrypt/decrypt strings.Known issuesOn macOS when using a key stored in keyring, Ansible might hang with a message similar to the following:` objc[81450]: +[__NSCFBoolean initialize] may have been in progress in another thread when fork() was called. objc[81450]: +[__NSCFBoolean initialize] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc_initializeAfterForkError to debug. `This is caused by trying to access the secret from the keyring in a forked process.To work around this you may have to add an encrypted host_vars yml for the affected host (or just one for the “all” group_vars) to trigger the key load early in Ansible.Changelog2.0.0 - 2022-08-17Dropped support for Python 3.6.
[fschulze]Added support for Python 3.10 using ansible-core.
[fschulze]Restore ploy_crypted compatibility for older Ansible versions.
[fschulze]2.0.0b8 - 2021-09-08Never store python objects in inventory data to fix issues with
ansible >= 2.8.x.
[fschulze]2.0.0b7 - 2021-07-16Fix encoding issue with execnet connection on Python 3.x.
[fschulze]Fix hanging when using keyring in newer macOS with ansible 2.x.
[fschulze]2.0.0b6 - 2020-05-13Support switch from vaultcattoviewcommand for ansible 2.x.
[fschulze]2.0.0b5 - 2019-06-09This release works up to and including ansible 2.7.x.
[fschulze]Restored support for ansible 1.9.x.
[fschulze]Support Python >= 3.5 with ansible >= 2.4.x.
[fschulze]Make host lookup in InventoryManager lazy to prevent errors when unrelated
hosts are not accessible.
[fschulze]2.0.0b4 - 2018-02-11Fix become/sudo support forexecnet_connection.
[fschulze]Fix playbook discovery.
[fschulze]2.0.0b3 - 2018-02-10Fixploy_cryptedlookup plugin.
[fschulze]2.0.0b2 - 2018-02-07Readdedexecnet_connectionas plugin.
[fschulze]2.0.0b1 - 2018-02-07Support ansible >= 2.4.0 and drop support for previous versions.
[fschulze]Support for ploy 2.0.0.
[fschulze]1.4.1 - 2018-02-11Return with proper exit code on failure ofconfigurecommand.
[fschulze]Fix playbook discovery.
[fschulze]1.4.0 - 2017-12-17Look for[instance-name].ymlin addition to[master-name]-[instance-name].yml.
This allows using the same playbook for the same instance on multiple masters.
[fschulze]1.3.2 - 2016-06-02Don’t add empty search path when no additional role or library paths are
defined. This prevents the current working directory from being searched.
[fschulze]1.3.1 - 2015-09-03Update Ansible requirement to < 2.dev0. The upcoming 2.0.0 has way too many
internal changes to be supported.
[fschulze]Add hosts only once in Inventory.
[fschulze]1.3.0 - 2015-04-10Added handling ofgroupsoption of instances to allow definition of
additional Ansible groups.
[fschulze]Get host variables on demand instead of at startup. If you have many hosts
with encrypted yml files, this speeds things up considerably in most cases.
[fschulze]Fixes for changes in ansible 1.9.
[fschulze]Addedinventorycommand to list all known groups and their
associated hosts.
[fschulze]1.2.4 - 2015-02-28Pass on thesudosetting if therolesoption is used.
[fschulze]1.2.3 - 2015-02-28Fix sudo support for ansible > 1.6.
[fschulze]Print warning when using an untested version of ansible.
[fschulze]If ansible isn’t installed, then require >= 1.8 as that doesn’t violate
the sandbox of buildout anymore.
[fschulze]1.2.2 - 2015-02-18Test and fixes for changes in ansible 1.8.
[fschulze]1.2.1 - 2015-01-06Limit Ansible to pre 1.8, as > 1.8 breaks stuff.
[fschulze]1.2.0 - 2014-10-27Always setansible_ssh_userin inventory.
[fschulze]Clear host and pattern cache after calling original Inventory.__init__ method.
[fschulze]Add--extra-varsoption toconfigurecommand.
[witsch (Andreas Zeidler)]Provide ploy_crypted lookup plugin to load encrypted files into Ansible
variables. Only ascii and utf8 encoded files will work.
[fschulze]Expand Ansible variables in get_ansible_variables method.
[fschulze]Support Ansible vault with safe key storage via keyring library, so you don’t
have to type it in or have it in an unprotected file.
[fschulze]1.1.0 - 2014-08-13Test and fixes for changes in ansible 1.7.
[fschulze]Add verbosity argument toconfigurecommand.
[fschulze]1.0.0 - 2014-07-19Added documentation.
[fschulze]1.0b8 - 2014-07-15Add ansible as dependency if it can’t be imported already.
[fschulze]1.0b7 - 2014-07-08Packaging and test fixes.
[fschulze]1.0b6 - 2014-07-04Use unique instance id to avoid issues.
[fschulze]Renamed mr.awsome to ploy and mr.awsome.ansible to ploy_ansible.
[fschulze]1.0b5 - 2014-06-16Set user in playbook to the one from the config if it’s not set already.
[fschulze]Change default playbook directory from the aws.conf directory to it’s parent.
[fschulze]1.0b4 - 2014-06-11Addedplaybookandrolesconfig options for instances.
[fschulze]Addedhas_playbookandconfiguremethods to instances.
[fschulze]Added before/after_ansible_configure hooks.
[fschulze]1.0b3 - 2014-06-09Use execnet for connections. There is only one ssh connection per host and
it’s reused for all commands.
[fschulze]Make sure the playbook directory is always absolute.
[fschulze]Prevent use of persistent ssh connections, as that easily results in
connections to wrong jails because of the proxying. This makes ansible a lot
slower at the moment.
[fschulze]Add support for su and vault (ansible 1.5) as well as--force-handlers(ansible 1.6).
[fschulze]Removedansiblefrom install requirements. It won’t install in a buildout
so it needs to be installed in a virtualenv or via a system package.
[fschulze]1.0b2 - 2014-05-15Addconfigurecommand which is a stripped down variant of theplaybookcommand with assumptions about the location of the yml file.
[fschulze]Warn if a playbook is requested for a host that is not configured in the
playbook hosts list.
[fschulze]Allow mr.awsome plugins to add ansible variables.
[fschulze]Inject the ansible paths sooner as they may not apply in some cases otherwise.
[fschulze]Moved setuptools-git from setup.py to .travis.yml, it’s only needed for
releases and testing.
[fschulze]1.0b1 - 2014-03-24Initial release
[fschulze]