Spec-Zone.ru › Ansible

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

Примечание

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

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

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

Чтобы использовать модуль в плейбуке, укажите: cisco.aci.aci_rest.

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

Краткое описание

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

Требования

Следующие требования необходимо выполнить на узле, на котором запускается этот модуль.

  • lxml (при использовании XML-полезной нагрузки)
  • xmljson >= 0.1.8 (при использовании XML-полезной нагрузки)
  • python 2.7+ (при использовании xmljson)

Параметры

Параметр

Комментарии

annotation

string

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

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

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

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

certificate_name

псевдонимы: cert_name

string

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

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

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

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

content

any

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

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

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

host

псевдонимы: hostname

string

IP-адрес или имя узла APIC, разрешаемое управляющим узлом Ansible.

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

method

псевдонимы: action

string

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

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

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

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

Варианты:

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

normalize_payload_values

boolean

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

Начиная с Ansible Core v2.19.0 и Jinja2 v3.1.6 этот параметр принудительно преобразует целочисленные значения и значения с плавающей точкой в строки.

Чтобы отключить это преобразование, задайте normalize_payload_values=false или удалите переменную окружения ACI_NORMALIZE_PAYLOAD_VALUES.

Варианты:

  • false
  • true

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.

page

integer

Номер возвращаемой страницы.

page_size

integer

Количество элементов, возвращаемых на одной странице.

password

string

Пароль для аутентификации.

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

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

path

псевдонимы: uri

string / обязательный

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

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

port

integer

Номер порта для REST-подключения.

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

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

private_key

псевдонимы: cert_key

string

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

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

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

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

rsp_subtree_preserve

boolean

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

Варианты:

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

src

псевдонимы: config_file

path

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

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

suppress_previous

псевдонимы: no_previous, ignore_previous

boolean

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

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

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

ПРЕДУПРЕЖДЕНИЕ — в результате возвращаемое значение previous будет пустым.

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

Варианты:

  • false
  • true

suppress_verification

псевдонимы: no_verification, no_verify, suppress_verify, ignore_verify, ignore_verification

boolean

Если true, после отправки обновления POST в APIC проверочный запрос GET отправляться не будет.

Если значение не указано в задаче, вместо него будет использовано значение переменной окружения 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

псевдонимы: 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).

Руководство по настройке REST API Cisco APIC

Дополнительные сведения о REST API 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: Get first 5 tenants using password authentication and pagination
  cisco.aci.aci_rest:
    host: apic
    username: admin
    password: SomeSecretPassword
    method: get
    page_size: 5
    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

integer

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

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

Пример: 122

error_text

string

Текстовое описание REST ACI, полезное для диагностики при сбое.

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

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

imdata

string

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

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

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

payload

string

Полезная нагрузка (с шаблоном), отправленная в REST API APIC (XML или JSON).

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

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

raw

string

Необработанный вывод, возвращаемый REST API APIC (XML или JSON).

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

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

response

string

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

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

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

status

integer

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

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

Пример: 400

totalCount

string

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

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

Пример: "0"

url

string

URL, использованный для вызова REST API APIC.

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

Пример: "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–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/cisco/aci/aci_rest_module.html

Spec-Zone.ru

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