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

Что такое Cisco ACI?

Инфраструктура, ориентированная на приложения (ACI)

Инфраструктура Cisco Application Centric Infrastructure (ACI) позволяет определять сеть на основе требований приложений. Эта архитектура упрощает, оптимизирует и ускоряет весь жизненный цикл развертывания приложений.

Контроллер инфраструктуры политик приложений (APIC)

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

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

API Cisco Application Policy Infrastructure Controller (APIC) позволяет приложениям напрямую подключаться к защищенному, общему, высокопроизводительному пулу ресурсов, включающему возможности сети, вычислений и хранения.

Ткань ACI

Ткань Cisco Application Centric Infrastructure (ACI) включает коммутаторы Cisco Nexus 9000 серии с APIC для работы в режиме ткани ACI «лист/хребет». Эти коммутаторы образуют сеть «толстого дерева», подключая каждый узел листа к каждому узлу хребта; все остальные устройства подключаются к узлам листа. APIC управляет тканью ACI.

Ткань ACI обеспечивает согласованную передачу данных с низкой задержкой по высокоскоростным каналам (40 Гбит/с, с будущей возможностью 100 Гбит/с). Трафик с источником и получателем на одном коммутаторе листа обрабатывается локально, а весь другой трафик перемещается от входного листа к выходному через коммутатор хребта. Хотя с физической точки зрения эта архитектура выглядит как два перехода, на самом деле это один переход уровня 3, поскольку ткань функционирует как один коммутатор уровня 3.

Объектно-ориентированная операционная система (ОС) ткани ACI работает на каждом узле серии Cisco Nexus 9000. Она позволяет программировать объекты для каждого настраиваемого элемента системы. ОС ткани ACI преобразует политики из APIC в конкретную модель, которая выполняется в физической инфраструктуре. Конкретная модель аналогична скомпилированному программному обеспечению; это форма модели, которую может выполнить операционная система коммутатора.

Все узлы коммутаторов содержат полную копию конкретной модели. Когда администратор создаёт политику в APIC, которая представляет конфигурацию, APIC обновляет логическую модель. Затем APIC выполняет промежуточный шаг по созданию полностью разработанной политики, которую он распространяет на все узлы коммутаторов, где обновляется конкретная модель.

APIC отвечает за активацию ткани, управление прошивкой коммутаторов, конфигурацию сетевых политик и их создание. Хотя APIC действует как центральный движок управления политиками и сетью для ткани, он полностью удалён из траектории данных, включая топологию переадресации. Следовательно, ткань по-прежнему может пересылать трафик даже при потере связи с APIC.

Дополнительная информация

Существует множество ресурсов для начала изучения ACI, вот список интересных статей из сообщества.

• Adam Raffe: Обучение ACI
• Luca Relandini: ACI для начинающих
• Cisco DevNet Learning Labs о ACI

Использование модулей ACI

Модули Ansible ACI предоставляют удобный интерфейс для управления вашей средой ACI с помощью playbooks Ansible.

Например, для обеспечения существования определенного арендатора используется следующая задача Ansible с модулем aci_tenant:

- name: Ensure tenant customer-xyz exists
  aci_tenant:
    host: my-apic-1
    username: admin
    password: my-password

    tenant: customer-xyz
    description: Customer XYZ
    state: present

Полный список существующих модулей ACI доступен для последней стабильной версии на странице список сетевых модулей. Вы также можете просмотреть текущую версию разработки.

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

Запрос конфигурации ACI

Модуль также можно использовать для запроса определенного объекта.

- name: Query tenant customer-xyz
  aci_tenant:
    host: my-apic-1
    username: admin
    password: my-password

    tenant: customer-xyz
    state: query
  register: my_tenant

Или запросить все объекты.

- name: Query all tenants
  aci_tenant:
    host: my-apic-1
    username: admin
    password: my-password

    state: query
  register: all_tenants

После регистрации возвращаемых значений задачи aci_tenant, как показано выше, вы можете получить доступ ко всей информации об арендаторах из переменной all_tenants.

Выполнение на контроллере локально

Как изначально задумывалось, модули Ansible отправляются и выполняются на удалённом целевом объекте(ах), однако модули ACI (как и большинство модулей, связанных с сетью) не выполняются на сетевых устройствах или контроллере (в данном случае APIC), а взаимодействуют непосредственно с REST-интерфейсом APIC.

По этой причине модули должны выполняться на локальном контроллере Ansible (или делегируются другой системе, которая может подключиться к APIC).

Сбор фактов

Поскольку модули выполняются на контроллере Ansible, сбор фактов не будет работать. Именно поэтому при использовании этих модулей ACI обязательно нужно отключить сбор фактов. Вы можете сделать это глобально в вашем ansible.cfg или добавив gather_facts: no к каждой игре.

 - name: Another play in my playbook
   hosts: my-apic-1
   gather_facts: no
   tasks:
   - name: Create a tenant
     aci_tenant:
       ...

Делегирование на localhost

Предположим, что наш целевой объект настроен в инвентаре с использованием полного доменного имени в качестве значения ansible_host, как показано ниже.

 apics:
   my-apic-1:
     ansible_host: apic01.fqdn.intra
     ansible_user: admin
     ansible_pass: my-password

Один из способов настроить это — добавить к каждой задаче директиву: delegate_to: localhost.

 - name: Query all tenants
   aci_tenant:
     host: '{{ ansible_host }}'
     username: '{{ ansible_user }}'
     password: '{{ ansible_pass }}'

     state: query
   delegate_to: localhost
   register: all_tenants

Если эта директива будет забыта, Ansible попытается подключиться к APIC с помощью SSH и попытается скопировать модуль и запустить его удалённо. Это приведёт к ошибке, но может быть непонятно для некоторых.

Использование метода локального подключения

Другой часто используемый вариант — привязать метод подключения local к этому целевому объекту, чтобы каждая последующая задача для этого целевого объекта использовала метод локального подключения (то есть выполнялась локально, а не с использованием SSH).

В этом случае инвентарь может выглядеть так:

 apics:
   my-apic-1:
     ansible_host: apic01.fqdn.intra
     ansible_user: admin
     ansible_pass: my-password
     ansible_connection: local

Но используемым задачам ничего специального добавлять не нужно.

- name: Query all tenants
  aci_tenant:
    host: '{{ ansible_host }}'
    username: '{{ ansible_user }}'
    password: '{{ ansible_pass }}'

    state: query
  register: all_tenants

Общие параметры

Каждый модуль Ansible ACI принимает следующие параметры, которые влияют на общение модуля с REST-API APIC:

host

Имя хоста или IP-адрес APIC.

port

Порт для использования в общении. (По умолчанию 443 для HTTPS и 80 для HTTP)

username

Имя пользователя для входа в APIC. (По умолчанию admin)

password

Пароль для username входа в APIC с использованием аутентификации на основе пароля.

private_key

Приватный ключ для username входа в APIC с использованием аутентификации на основе подписи. Новое в версии 2.5

certificate_name

Имя сертификата в веб-интерфейсе ACI. (По умолчанию имя файла private_key) Новое в версии 2.5

timeout

Значение таймаута для связи на уровне сокета.

use_proxy

Использовать системные настройки прокси. (По умолчанию yes)

use_ssl

Использовать HTTPS или HTTP для связи с REST-API APIC. (По умолчанию yes)

validate_certs

Проверять сертификат при использовании HTTPS-связи. (По умолчанию yes)

output_level

Влияет на уровень детализации, который модули ACI возвращают пользователю. (Один из normal, info или debug) Новое в версии 2.5

Поддержка прокси

По умолчанию, если на целевом хосте установлена переменная окружения <protocol>_proxy, запросы будут отправляться через этот прокси. Это поведение можно переопределить, задав переменную для этой задачи (см. Установка окружения (и работа с прокси)) или используя параметр модуля use_proxy.

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

Если поддержка прокси не нужна, но система может быть настроена на её использование, используйте параметр use_proxy: no для предотвращения случайного использования системного прокси.

Возвращаемые значения

Следующие значения всегда возвращаются:

current

Результирующее состояние управляемого объекта или результаты запроса.

Следующие значения возвращаются, когда output_level: info:

previous

Исходное состояние управляемого объекта (до внесения изменений).

proposed

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

sent

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

Следующие значения возвращаются, когда output_level: debug или ANSIBLE_DEBUG=1:

filter_string

Фильтр, используемый для конкретных запросов APIC.

method

HTTP-метод, используемый для отправленной полезной нагрузки. (Либо GET для запросов, DELETE или POST для изменений).

response

HTTP-ответ от APIC.

status

HTTP-код состояния для запроса.

url

URL, используемый для запроса.

Дополнительная информация

Существует множество ресурсов, чтобы узнать больше об ACI программируемости, мы рекомендуем следующие ссылки:

• Разработка модулей Cisco ACI
• Jacob McGill: Автоматизация Cisco ACI с помощью Ansible
• Cisco DevNet Learning Labs об ACI и Ansible

Авторизация ACI

Авторизация по паролю

Если вы хотите войти с помощью имени пользователя и пароля, вы можете использовать следующие параметры с вашими модулями ACI:

username: admin
password: my-password

Авторизация по паролю очень проста в использовании, но она не является наиболее эффективным методом авторизации с точки зрения ACI, так как требует отдельного запроса на вход и открытой сессии. Чтобы избежать истечения срока действия вашей сессии и необходимости повторного входа, вы можете использовать более эффективную авторизацию на основе подписи.

Функция «Vault» Ansible позволяет хранить конфиденциальные данные, такие как пароли или ключи, в зашифрованных файлах вместо открытого текста в ваших playbook или ролях. Эти файлы Vault можно затем распространять или размещать в системе контроля версий. Более подробную информацию см. в разделе Использование Vault в playbook.

Авторизация на основе подписи с использованием сертификатов

Использование авторизации на основе подписи более эффективно и надежно, чем авторизация по паролю.

Генерация сертификата и закрытого ключа

Авторизация на основе подписи требует (самозаверяющего) сертификата X.509 с закрытым ключом и шага конфигурации для вашего пользователя AAA в ACI. Для генерации работающего сертификата X.509 и закрытого ключа выполните следующие действия:

$ openssl req -new -newkey rsa:1024 -days 36500 -nodes -x509 -keyout admin.key -out admin.crt -subj '/CN=Admin/O=Your Company/C=US'

Настройка локального пользователя

Выполните следующие шаги:

• Добавьте сертификат X.509 к локальному пользователю ACI AAA в ADMIN » AAA
• Нажмите Авторизация AAA
• Убедитесь, что в поле Авторизация поле Домен отображает Локальный
• Разверните Управление безопасностью » Локальные пользователи
• Щелкните имя пользователя, которому вы хотите добавить сертификат, в области Сертификаты пользователей
• Нажмите значок + и в поле Создать сертификат X509 введите имя сертификата в поле Имя
  • Если вы используете имя файла вашего закрытого ключа здесь, вам не нужно вводить certificate_name в Ansible
• Скопируйте и вставьте свой сертификат X.509 в поле Данные.

Вы можете автоматизировать это с помощью следующей задачи Ansible:

- name: Ensure we have a certificate installed
  aci_aaa_user_certificate:
    host: my-apic-1
    username: admin
    password: my-password

    aaa_user: admin
    certificate_name: admin
    certificate: "{{ lookup('file', 'pki/admin.crt') }}"  # This will read the certificate data from a local file

Использование авторизации на основе подписи с Ansible

Для работы с модулем(ами) ACI необходимы следующие параметры:

 username: admin
 private_key: pki/admin.key
 certificate_name: admin  # This could be left out !

Дополнительная информация

Подробная информация об авторизации на основе подписи доступна по адресу Cisco APIC Signature-Based Transactions.

Использование ACI REST с Ansible

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

Модуль aci_rest предоставляет прямой доступ к API REST APIC и позволяет выполнять любые задачи, не охваченные существующими модулями. Это может показаться сложной задачей, но вы можете легко сгенерировать необходимую нагрузку REST для любого действия, выполненного в веб-интерфейсе ACI.

Встроенная идемпотентность

Поскольку API REST APIC изначально идемпотентен и может сообщить, было ли произведено изменение, модуль aci_rest автоматически наследует обе возможности и является первоклассным решением для автоматизации вашей инфраструктуры ACI. В результате пользователи, которым требуется более мощный низкоуровневый доступ к своей инфраструктуре ACI, не должны отказываться от идемпотентности и не должны предполагать, было ли произведено изменение при использовании модуля aci_rest.

Использование модуля aci_rest

Модуль aci_rest принимает исходные XML и JSON payloads, но также принимает встроенные YAML payload (структурированные как JSON). XML payload требует использования пути, заканчивающегося .xml , в то время как JSON или YAML требуют, чтобы путь заканчивался .json.

При выполнении изменений вы можете использовать методы POST или DELETE, в то время как запросы требуют метода GET.

Например, если вы хотите убедиться, что определенный арендатор существует в ACI, следующие четыре примера функционально идентичны:

XML (Исходный REST ACI)

- aci_rest:
    host: my-apic-1
    private_key: pki/admin.key

    method: post
    path: /api/mo/uni.xml
    content: |
      <fvTenant name="customer-xyz" descr="Customer XYZ"/>

JSON (Исходный REST ACI)

- aci_rest:
    host: my-apic-1
    private_key: pki/admin.key

    method: post
    path: /api/mo/uni.json
    content:
      {
        "fvTenant": {
          "attributes": {
            "name": "customer-xyz",
            "descr": "Customer XYZ"
          }
        }
      }

YAML (REST Ansible-стиль)

- aci_rest:
    host: my-apic-1
    private_key: pki/admin.key

    method: post
    path: /api/mo/uni.json
    content:
      fvTenant:
        attributes:
          name: customer-xyz
          descr: Customer XYZ

Задача Ansible (Специализированный модуль)

- aci_tenant:
    host: my-apic-1
    private_key: pki/admin.key

    tenant: customer-xyz
    description: Customer XYZ
    state: present

Дополнительная информация

Существует много ресурсов для изучения REST интерфейса APIC ACI, мы рекомендуем следующие ссылки:

• Документация модуля aci_rest
• APIC REST API Configuration Guide – Подробное руководство по разработке и использованию API REST APIC, включая множество примеров
• APIC Management Information Model reference – Полная справка по модели объектов APIC
• Cisco DevNet Learning Labs об ACI и REST

Операционные примеры

Вот краткий обзор полезных операционных задач для повторного использования в ваших playbook.

Не стесняйтесь делиться дополнительными полезными фрагментами.

Ожидание готовности всех контроллеров

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

- name: Waiting for all controllers to be ready
  aci_rest:
    host: my-apic-1
    private_key: pki/admin.key
    method: get
    path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller")
  register: topsystem
  until: topsystem|success and topsystem.totalCount|int >= groups['apic']|count >= 3
  retries: 20
  delay: 30

Ожидание полного соответствия кластера

Нижеприведенный пример ожидает, пока кластер не будет полностью совместим. В этом примере вы знаете количество APIC в кластере и проверяете, что каждый APIC сообщает о статусе «полной совместимости».

- name: Waiting for cluster to be fully-fit
  aci_rest:
    host: my-apic-1
    private_key: pki/admin.key
    method: get
    path: /api/node/class/infraWiNode.json?query-target-filter=wcard(infraWiNode.dn,"topology/pod-1/node-1/av")
  register: infrawinode
  until: >
    infrawinode|success and
    infrawinode.totalCount|int >= groups['apic']|count >= 3 and
    infrawinode.imdata[0].infraWiNode.attributes.health == 'fully-fit' and
    infrawinode.imdata[1].infraWiNode.attributes.health == 'fully-fit' and
    infrawinode.imdata[2].infraWiNode.attributes.health == 'fully-fit'
  retries: 30
  delay: 30

Сообщения об ошибках APIC

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

Ошибка APIC 122: неизвестный управляемый класс объекта ‘polUni’

В случае получения этой ошибки, когда вы уверены, что ваш aci_rest payload и классы объектов кажутся правильными, проблема может заключаться в том, что ваш payload на самом деле не является корректным JSON (например, в отправленном payload используются одинарные кавычки вместо двойных), и в результате APIC некорректно парсит ваши классы объектов из payload. Один из способов избежать этого — использовать payload в формате YAML или XML, которые легче корректно создать и изменить позже.

Ошибка APIC 400: некорректные данные на строке ‘1’. Отсутствуют атрибуты, тег ‘attributes’ должен быть указан первым, прежде чем любой другой тег

Хотя спецификация JSON допускает неупорядоченные элементы, APIC REST API требует, чтобы элемент JSON attributes предшествовал массиву children или другим элементам. Поэтому необходимо убедиться, что ваш payload соответствует этому требованию. Сортировка ключей вашего словаря прекрасно справится с этой задачей. Если у вас нет атрибутов, возможно, необходимо добавить: attributes: {} , так как APIC ожидает, что запись будет предшествовать любому children.

Ошибка APIC 801: свойство descr объекта uni/tn-TENANT/ap-AP не прошло валидацию для значения ‘A “legacy” network’

Некоторые значения в APIC имеют строгие правила формата, и внутренняя проверка валидации APIC для предоставленного значения завершилась неудачно. В приведенном выше случае параметр description (внутренне известный как descr) принимает только значения, соответствующие Regex: [a-zA-Z0-9\!#$%()*,-./:;@ _{|}~?&+]+, в общем случае он не должен включать кавычки или квадратные скобки.

Известные проблемы

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

Все проблемы ниже либо были сообщены поставщику, и большинство из них можно просто избежать.

Слишком много последовательных вызовов API могут привести к ограничению соединения

Начиная с ACI v3.1, APIC активно ограничивает скорость подключений с аутентификацией по паролю, превышающую определенный порог. Это делается как часть меры анти-DDOS, но может проявляться при использовании Ansible с ACI с аутентификацией по паролю. В настоящее время одним из решений является увеличение этого порога в конфигурации nginx, но рекомендуется использовать аутентификацию на основе подписи.

ПРИМЕЧАНИЕ: Рекомендуется использовать аутентификацию на основе подписи с ACI, так как она не только предотвращает ограничение подключений, но и улучшает общую производительность при использовании модулей ACI.

Определенные запросы могут не отражать изменения корректно (#35401)

Известна проблема, когда определенные запросы к APIC не отражают изменения в результирующем выводе должным образом, даже когда мы явно запрашиваем эти изменения у APIC. В одном случае использование пути api/node/mo/uni/infra.xml терпит неудачу, тогда как api/node/mo/uni/infra/.xml работает корректно.

ПРИМЕЧАНИЕ: Обходной путь заключается в регистрации возвращаемых значений задачи (например, register: this) и влиянии на то, когда задача должна сообщить об изменении, добавив: changed_when: this.imdata != [].

Известно, что определенные запросы не являются идемпотентными (#35050)

Поведение APIC не согласуется с использованием status="created" и status="deleted". В результате, когда вы используете status="created" в своём payload, результирующие задачи не являются идемпотентными, и создание завершится ошибкой, если объект уже был создан. Однако это не так с status="deleted", где такой вызов несуществующего объекта не приводит к какой-либо ошибке.

ПРИМЕЧАНИЕ: Обходной путь заключается в избегании использования status="created" и использовании вместо этого status="modified", когда идемпотентность необходима для вашего рабочего процесса.

Установка пароля пользователя не является идемпотентной (#35544)

Из-за несоответствия в APIC REST API задача, устанавливающая пароль локально аутентифицированного пользователя, не является идемпотентной. APIC выдаст сообщение Password history check: user dag should not use previous 5 passwords.

ПРИМЕЧАНИЕ: Обходного пути для этой проблемы нет.

Сообщество ACI Ansible

Если у вас есть конкретные проблемы с модулями ACI, предложения по функциям или вы хотите внести вклад в проект ACI, предложив изменения или обновления документации, посетите страницу Wiki Ansible Community ACI по адресу: https://github.com/ansible/community/wiki/Network:-ACI

Вы найдёте там наш план, обзор открытых проблем и запросов на включение в ACI, и больше информации о нас. Если вы заинтересованы в использовании ACI с Ansible, присоединяйтесь! Мы время от времени собираемся онлайн, чтобы отслеживать прогресс и готовиться к новым выпускам Ansible.