Spec-Zone.ru › Ansible

Модуль cisco.aci.aci_rest – Прямой доступ к REST API Cisco APIC

Примечание

Этот модуль входит в состав коллекции cisco.aci (версия 2.10.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не включена в ansible-core. Чтобы проверить установку, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install cisco.aci. Для использования этого модуля требуются дополнительные зависимости, см. Требования для подробной информации.

Для использования в playbook укажите: cisco.aci.aci_rest.

  • Описание
  • Требования
  • Параметры
  • Примечания
  • См. также
  • Примеры
  • Возвращаемые значения

Описание

  • Обеспечивает управление Cisco ACI fabric через прямой доступ к REST API Cisco APIC.
  • Благодаря идемпотентности APIC, этот модуль идемпотентен и сообщает об изменениях.

Требования

Ниже перечислены требования, необходимые на хосте, на котором выполняется этот модуль.

  • lxml (при использовании XML payload)
  • xmljson >= 0.1.8 (при использовании XML payload)
  • python 2.7+ (при использовании xmljson)

Параметры

Параметр

Комментарии

annotation

string

Пользовательская строка для аннотации объекта.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения ACI_ANNOTATION.

Если значение не указано в задаче и переменной окружения ACI_ANNOTATION, будет использовано значение по умолчанию.

По умолчанию: "orchestrator:ansible"

certificate_name

aliases: cert_name

string

Имя сертификата X.509, прикрепленного к пользователю APIC AAA, используемому для аутентификации на основе подписи.

Если указано имя файла private_key, значение по умолчанию будет базовым именем private_key, без расширения.

Если для private_key предоставлено содержимое в формате PEM, значение по умолчанию будет username.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения ACI_CERTIFICATE_NAME.

content

any

При использовании вместо src, напрямую устанавливает полезную нагрузку API-запроса.

Это может быть удобно для шаблонизации простых запросов.

Для чего-либо сложного используйте подключаемый модуль поиска template (см. примеры) или модуль template с параметром src.

host

aliases: hostname

string

IP-адрес или имя хоста APIC, распознаваемое узлом управления Ansible.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения ACI_HOST.

method

aliases: action

string

HTTP-метод запроса.

Использование delete обычно используется для удаления объектов.

Использование get обычно используется для запроса объектов.

Использование post обычно используется для изменения объектов.

Варианты:

  • "delete"
  • "get" ← (по умолчанию)
  • "post"

output_level

string

Влияет на вывод этого модуля ACI.

normal означает стандартный вывод, включая словарь current

info добавляет информационный вывод, включая словари previous, proposed и sent

debug добавляет отладочный вывод, включая информацию filter_string, method, response, status и url

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения ACI_OUTPUT_LEVEL.

Варианты:

  • "debug"
  • "info"
  • "normal" ← (по умолчанию)

output_path

string

Путь к файлу, который будет использоваться для выгрузки объектов конфигурации ACI JSON, сгенерированных модулем.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения ACI_OUTPUT_PATH.

password

string

Пароль, используемый для аутентификации.

Этот параметр является взаимоисключающим с private_key. Если также предоставлен private_key, он будет использован вместо него.

Если значение не указано в задаче, вместо него будут использованы значения переменных окружения ACI_PASSWORD или ANSIBLE_NET_PASSWORD.

path

aliases: uri

string / required

URI, используемый для выполнения API-вызовов.

Должен заканчиваться на .xml или .json.

port

integer

Номер порта, используемый для REST-соединения.

Значение по умолчанию зависит от параметра use_ssl.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения ACI_PORT.

private_key

aliases: cert_key

string

Либо файл закрытого ключа в формате PEM, либо содержимое закрытого ключа, используемое для аутентификации на основе подписи.

Это значение также влияет на используемое значение certificate_name по умолчанию.

Этот параметр является взаимоисключающим с password. Если также предоставлен password, он будет игнорироваться.

Если значение не указано в задаче, вместо него будут использованы значения переменных окружения ACI_PRIVATE_KEY или ANSIBLE_NET_SSH_KEYFILE.

rsp_subtree_preserve

boolean

Сохраняет ответ для указанного пути.

Варианты:

  • false ← (по умолчанию)
  • true

src

aliases: config_file

path

Имя абсолютного пути к файлу, содержащему тело HTTP-запроса, отправляемого в структуру ACI.

Если вам требуется шаблонная полезная нагрузка, используйте параметр content вместе с подключаемым модулем поиска template или используйте template.

suppress_previous

aliases: no_previous, ignore_previous

boolean

Если true, GET-запрос для проверки предыдущего состояния не будет отправлен перед обновлением APIC с помощью POST.

Если значение не указано в задаче, будет использовано значение переменной окружения ACI_SUPPRESS_PREVIOUS.

Значение по умолчанию — false.

ПРЕДУПРЕЖДЕНИЕ - Это приводит к тому, что предыдущее возвращаемое значение становится пустым.

Предыдущее состояние объекта не будет проверяться, и обновление POST будет содержать все свойства.

Варианты:

  • false
  • true

suppress_verification

aliases: no_verification, no_verify, suppress_verify, ignore_verify, ignore_verification

boolean

Если true, проверяющий GET-запрос не будет отправлен после обновления APIC с помощью POST.

Если значение не указано в задаче, будет использовано значение переменной окружения ACI_SUPPRESS_VERIFICATION.

Значение по умолчанию — false.

ПРЕДУПРЕЖДЕНИЕ - Это приводит к тому, что текущее возвращаемое значение устанавливается в предложенное значение.

Текущий объект, включая значения по умолчанию, не будет проверяться в одной задаче.

Варианты:

  • false
  • true

timeout

integer

Таймаут уровня сокета в секундах.

Если значение не указано в задаче, будет использовано значение переменной окружения ACI_TIMEOUT.

Значение по умолчанию — 30.

use_proxy

boolean

Если false, прокси не будет использоваться, даже если он определен в переменной окружения на целевых хостах.

Если значение не указано в задаче, будет использовано значение переменной окружения ACI_USE_PROXY.

Значение по умолчанию — true.

Варианты:

  • false
  • true

use_ssl

boolean

Если false, вместо стандартного HTTPS будет использовано HTTP-соединение.

Если значение не указано в задаче, будет использовано значение переменной окружения ACI_USE_SSL.

Значение по умолчанию — true для локального подключения.

Варианты:

  • false
  • true

username

aliases: user

string

Имя пользователя для аутентификации.

Если значение не указано в задаче, будет использовано значение переменных окружения ACI_USERNAME или ANSIBLE_NET_USERNAME.

Значение по умолчанию — admin.

validate_certs

boolean

Если false, сертификаты SSL не будут проверены.

Это следует устанавливать в false только при использовании на сайтах, контролируемых лично, с самозаверяющими сертификатами.

Если значение не указано в задаче, будет использовано значение переменной окружения ACI_VALIDATE_CERTS.

Значение по умолчанию — true.

Варианты:

  • false
  • true

Примечания

Примечание

  • Известно, что некоторые полезные нагрузки не являются идемпотентными, поэтому будьте осторожны при построении полезных нагрузок, например, использование status="created" вызовет проблемы с идемпотентностью, используйте status="modified" вместо этого. Дополнительная информация в :ref:`документации ACI <aci_guide_known_issues>`.
  • Известно, что некоторые полезные нагрузки (и используемые пути) сообщают об отсутствии изменений, когда изменения произошли. Это известная проблема APIC, о которой было сообщено поставщику. Существует обходное решение для этой проблемы. Дополнительная информация в :ref:`документации ACI <aci_guide_known_issues>`.
  • XML-полезные нагрузки требуют библиотек python lxml и xmljson. Для JSON-полезных нагрузок ничего специального не требуется.
  • Если у вас нет атрибутов, возможно, потребуется добавить ключ «attributes» со значением пустого словаря «{}», так как APIC ожидает, что запись будет предшествовать любым дочерним элементам.
  • Наборы аннотаций, заданные непосредственно в c(src) или content, имеют приоритет над параметром annotation.

См. также

См. также

cisco.aci.aci_tenant

Управление арендаторами (fv:Tenant).

Руководство по конфигурации API REST APIC Cisco

Дополнительная информация об API REST APIC.

Руководство Cisco ACI

Подробная информация о том, как управлять вашей инфраструктурой ACI с помощью Ansible.

Разработка модулей Cisco ACI

Подробное руководство по написанию собственных модулей Cisco ACI для участия в сообществе.

Примеры

- name: Add a tenant using certificate authentication
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    method: post
    path: /api/mo/uni.xml
    src: /home/cisco/ansible/aci/configs/aci_config.xml
  delegate_to: localhost

- name: Add a tenant from a templated payload file from templates/
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    method: post
    path: /api/mo/uni.xml
    content: "{{ lookup('template', 'aci/tenant.xml.j2') }}"
  delegate_to: localhost

- name: Add a tenant using inline YAML
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    path: /api/mo/uni.json
    method: post
    content:
      fvTenant:
        attributes:
          name: Sales
          descr: Sales department
  delegate_to: localhost

- name: Add a tenant using a JSON string
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    path: /api/mo/uni.json
    method: post
    content:
      {
        "fvTenant": {
          "attributes": {
            "name": "Sales",
            "descr": "Sales department"
          }
        }
      }
  delegate_to: localhost

- name: Add a tenant using an XML string
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/{{ aci_username }}.key
    validate_certs: false
    path: /api/mo/uni.xml
    method: post
    content: '<fvTenant name="Sales" descr="Sales departement"/>'
  delegate_to: localhost

- name: Get tenants using password authentication
  cisco.aci.aci_rest:
    host: apic
    username: admin
    password: SomeSecretPassword
    method: get
    path: /api/node/class/fvTenant.json
  delegate_to: localhost
  register: query_result

- name: Configure contracts
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    method: post
    path: /api/mo/uni.xml
    src: /home/cisco/ansible/aci/configs/contract_config.xml
  delegate_to: localhost

- name: Register leaves and spines
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    method: post
    path: /api/mo/uni/controller/nodeidentpol.xml
    content:
      <fabricNodeIdentPol>
        <fabricNodeIdentP name="{{ item.name }}" nodeId="{{ item.nodeid }}" status="{{ item.status }}" serial="{{ item.serial }}"/>
      </fabricNodeIdentPol>
  with_items:
    - '{{ apic_leavesspines }}'
  delegate_to: localhost

- name: Wait for all controllers to become ready
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller")
  register: apics
  until: "'totalCount' in apics and apics.totalCount|int >= groups['apic']|count"
  retries: 120
  delay: 30
  delegate_to: localhost
  run_once: true

Значения возврата

Общие значения возврата задокументированы здесь, следующие являются полями, уникальными для этого модуля:

Ключ

Описание

error_code

целое число

Код возврата REST ACI, полезный для устранения неполадок при ошибках

Возвращается: всегда

Пример: 122

error_text

строка

Дескриптивный текст REST ACI, полезный для устранения неполадок при ошибках

Возвращается: всегда

Пример: "unknown managed object class foo"

imdata

строка

Преобразованный вывод, возвращённый APIC REST (зарегистрируйте для последующей обработки)

Возвращается: всегда

Пример: "[{'error': {'attributes': {'code': '122', 'text': 'unknown managed object class foo'}}}]"

payload

строка

Отправляемый (шаблонный) payload в APIC REST API (xml или json)

Возвращается: всегда

Пример: "<foo bar=\"boo\"/>"

raw

строка

Необработанный вывод, возвращённый APIC REST API (xml или json)

Возвращается: при ошибке парсинга

Пример: "<?xml version=\"1.0\" encoding=\"UTF-8\"?><imdata totalCount=\"1\"><error code=\"122\" text=\"unknown managed object class foo\"/></imdata>"

response

строка

Строка HTTP ответа

Возвращается: всегда

Пример: "HTTP Error 400: Bad Request"

status

целое число

Код состояния HTTP

Возвращается: всегда

Пример: 400

totalCount

строка

Количество элементов в массиве imdata

Возвращается: всегда

Пример: "0"

url

строка

URL, используемый для вызова APIC REST

Возвращается: при успехе

Пример: "https://1.2.3.4/api/mo/uni/tn-[Dag].json?rsp-subtree=modified"

Авторы

  • Dag Wieers (@dagwieers)
  • Cindy Zhao (@cizhao)
  • Samita Bhattacharjee (@samitab)

Ссылки на коллекцию

  • Система отслеживания ошибок
  • Репозиторий (источники)

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/cisco/aci/aci_rest_module.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API