Python API

• Python API 2.0
• Python API до версии 2.0
  • Подробный пример API

Обратите внимание, что, хотя мы предоставляем этот API, он не предназначен для прямого использования. Он предназначен для поддержки командной строки Ansible. Мы стараемся избегать критических изменений, но оставляем за собой право их вносить в любое время, если это необходимо для инструментария Ansible.

Данная документация предоставляется для тех, кто все еще хочет использовать API напрямую, но имейте в виду, что команда Ansible не поддерживает его.

Существует несколько интересных способов использования Ansible с точки зрения API. Вы можете использовать Python API Ansible для управления узлами, расширять Ansible для реагирования на различные события Python, писать различные плагины и подключать данные инвентаризации из внешних источников данных. Этот документ охватывает API выполнения и Playbook на базовом уровне.

Если вы хотите использовать Ansible программно из чего-то, кроме Python, запускать события асинхронно или иметь требования к управлению доступом и регистрации, ознакомьтесь с Ansible Tower, так как у него есть очень хороший REST API, который предоставляет все эти возможности на более высоком уровне.

Ansible написан на собственном API, что предоставляет значительную мощность. В данном разделе рассматривается Python API.

Python API очень мощный и используется для реализации всех инструментов командной строки ansible. В версии 2.0 ядро ansible было переписано, и API был в основном переписан.

Python API 2.0

В версии 2.0 начать работу немного сложнее, но в итоге вы получите более дискретные и удобочитаемые классы:

#!/usr/bin/env python

import json
from collections import namedtuple
from ansible.parsing.dataloader import DataLoader
from ansible.vars.manager import VariableManager
from ansible.inventory.manager import InventoryManager
from ansible.playbook.play import Play
from ansible.executor.task_queue_manager import TaskQueueManager
from ansible.plugins.callback import CallbackBase

class ResultCallback(CallbackBase):
    """A sample callback plugin used for performing an action as results come in

    If you want to collect all results into a single object for processing at
    the end of the execution, look into utilizing the ``json`` callback plugin
    or writing your own custom callback plugin
    """
    def v2_runner_on_ok(self, result, **kwargs):
        """Print a json representation of the result

        This method could store the result in an instance attribute for retrieval later
        """
        host = result._host
        print(json.dumps({host.name: result._result}, indent=4))

Options = namedtuple('Options', ['connection', 'module_path', 'forks', 'become', 'become_method', 'become_user', 'check', 'diff'])
# initialize needed objects
loader = DataLoader()
options = Options(connection='local', module_path='/path/to/mymodules', forks=100, become=None, become_method=None, become_user=None, check=False,
                  diff=False)
passwords = dict(vault_pass='secret')

# Instantiate our ResultCallback for handling results as they come in
results_callback = ResultCallback()

# create inventory and pass to var manager
inventory = InventoryManager(loader=loader, sources=['localhost'])
variable_manager = VariableManager(loader=loader, inventory=inventory)

# create play with tasks
play_source =  dict(
        name = "Ansible Play",
        hosts = 'localhost',
        gather_facts = 'no',
        tasks = [
            dict(action=dict(module='shell', args='ls'), register='shell_out'),
            dict(action=dict(module='debug', args=dict(msg='{{shell_out.stdout}}')))
         ]
    )
play = Play().load(play_source, variable_manager=variable_manager, loader=loader)

# actually run it
tqm = None
try:
    tqm = TaskQueueManager(
              inventory=inventory,
              variable_manager=variable_manager,
              loader=loader,
              options=options,
              passwords=passwords,
              stdout_callback=results_callback,  # Use our custom callback instead of the ``default`` callback plugin
          )
    result = tqm.run(play)
finally:
    if tqm is not None:
        tqm.cleanup()

Python API до версии 2.0

Всё довольно просто:

import ansible.runner

runner = ansible.runner.Runner(
   module_name='ping',
   module_args='',
   pattern='web*',
   forks=10
)
datastructure = runner.run()

Метод run возвращает результаты по каждому хосту, сгруппированные по возможности контакта с ними. Типы возвращаемых значений зависят от модуля, как указано в документации Описание модулей.:

{
    "dark" : {
       "web1.example.com" : "failure message"
    },
    "contacted" : {
       "web2.example.com" : 1
    }
}

Модуль может возвращать любые типы данных JSON, поэтому Ansible может использоваться как фреймворк для быстрого создания мощных приложений и скриптов.

Подробный пример API

Следующий скрипт выводит информацию об активности всех хостов:

#!/usr/bin/python

import ansible.runner
import sys

# construct the ansible runner and execute on all hosts
results = ansible.runner.Runner(
    pattern='*', forks=10,
    module_name='command', module_args='/usr/bin/uptime',
).run()

if results is None:
   print "No hosts found"
   sys.exit(1)

print "UP ***********"
for (hostname, result) in results['contacted'].items():
    if not 'failed' in result:
        print "%s >>> %s" % (hostname, result['stdout'])

print "FAILED *******"
for (hostname, result) in results['contacted'].items():
    if 'failed' in result:
        print "%s >>> %s" % (hostname, result['msg'])

print "DOWN *********"
for (hostname, result) in results['dark'].items():
    print "%s >>> %s" % (hostname, result)

Продвинутые программисты могут также прочитать исходный код самого ansible, поскольку он использует API (со всеми доступными параметрами) для реализации инструментов командной строки ansible (lib/ansible/cli/).