Suitable API Documentation

class suitable.api.Api(servers, ignore_unreachable=False, ignore_errors=False, sudo=False, dry_run=False, verbosity='info', environment=None, strategy=None, **options)

Provides all available ansible modules as local functions:

api = Api('personal.server.dev')
api.sync(src='/Users/denis/.zshrc', dest='/home/denis/.zshrc')

Parameters:

• servers –

  A list of servers or a string with space-delimited servers. The api instances will operate on these servers only. Servers which cannot be reached or whose use triggers an error are taken out of the list for the lifetime of the object.

  Examples of valid uses:

  api = Api(['web.example.org', 'db.example.org'])
  api = Api('web.example.org')
  api = Api('web.example.org db.example.org')
  

  Each server may optionally contain the port in the form of host:port. If the host part is an ipv6 address you need to use the following form to specify the port: [host]:port.

  For example:

  api = Api('remote.example.org:2222')
  api = Api('[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:1234')
  

  Note that there’s currently no support for passing the same host more than once (like in the case of a bastion host). Ansible groups these kind of calls together and only calls the first server.

  So this won’t work as expected:

  api = Api(['example.org:2222', 'example.org:2223'])
  

  As a work around you should define aliases for these hosts in your ssh config or your hosts file.

• ignore_unreachable – If true, unreachable servers will not trigger an exception. They are however still taken out of the list for the lifetime of the object.
• ignore_errors – If true, errors on servers will not trigger an exception. Servers who trigger an error are still ignored for the lifteime of the object.
• sudo –

  If true, the commands run as root using sudo. This is a shortcut for the following:

  Api('example.org', become=True, become_user='root')
  

  If become or become_user are passed, this option is ignored!

• sudo_pass – If given, sudo is invoked with the given password. Alternatively you can use Ansible’s builtin password option (e.g. passwords={'become_pass': '***'}).
• remote_pass –

  Passwords are passed to ansible using the passwords dictionary by default (e.g. passwords={'conn_pass': '****'}). Since this is a bit cumbersome and because earlier Suitable releases supported remote_pass this convenience argument exists.

  If passwords is passed, the remote_pass argument is ignored.

• dry_run – Runs ansible in ‘check’ mode, where no changes are actually applied to the server(s).
• verbosity –

  The verbosity level of ansible. Possible values:

  • debug
  • info (default)
  • warn
  • error
  • critical
• environment –

  The environment variables which should be set during when a module is executed. For example:

  api = Api('example.org', environment={
      'PGPORT': '5432'
  })
  

• strategy –

  The Ansible strategy to use. Defaults to None which lets Ansible decide which strategy it wants to use.

  Note that you need to globally install strategy plugins using install_strategy_plugins() before using strategies provided by plugins.

• extra_vars –

  Extra variables available to Ansible. Note that those will be global and not bound to any particular host:

  api = Api('webserver', extra_vars={'home': '/home/denis'})
  api.file(dest="{{ home }}/.zshrc", state='touch')
  

  This can be used to specify an alternative Python interpreter:

  api = Api('example.org', extra_vars={
      'ansible_python_interpreter': '/path/to/interpreter'
  })
  

• **options –

  All remining keyword arguments are passed to the Ansible TaskQueueManager. The available options are listed here:

  http://docs.ansible.com/ansible/developing_api.html

on_module_error(module, host, result)

If you want to customize your error handling, this would be the point to write your own method in a subclass.

Note that this method is not called if ignore_errors is True.

If the return value of this method is ‘keep-trying’, the server will not be ignored for the lifetime of the object. This enables you to practically write your own flavor of ‘ignore_errors’.

If an any exception is raised the server WILL be ignored.

on_unreachable_host(module, host)

If you want to customize your error handling, this would be the point to write your own method in a subclass.

Note that this method is not called if ignore_unreachable is True.

If the return value of this method is ‘keep-trying’, the server will not be ignored for the lifetime of the object. This enables you to practically write your own flavor of ‘ignore_unreachable’.

If an any exception is raised the server WILL be ignored.

valid_return_codes(**kwds)

Sets codes which are considered valid when returned from command modules. The default is (0, ).

Should be used as a context:

with api.valid_return_codes(0, 1):
    api.shell('test -e /tmp/log && rm /tmp/log')

suitable.api.install_strategy_plugins(directories)

Loads the given strategy plugins, which is a list of directories, a string with a single directory or a string with multiple directories separated by colon.

As these plugins are globally loaded and cached by Ansible we do the same here. We could try to bind those plugins to the Api instance, but that’s probably not something we’d ever have much of a use for.

Call this function before using custom strategies on the Api class.